kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

time.rb: Move documents and stop others

Browse source 
* lib/time.rb: Move method documents to each methods.  And stop
  documentation of the abstract and others, which were confusingly
  placed at the top of generated documents prior to the abstract
  in time.c.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@66082 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
nobu 2018-11-29 01:09:47 +00:00
parent 5a9066f22a
commit 8ea6c92eb3
1 changed files with 101 additions and 73 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

174
lib/time.rb
View file

@ -2,6 +2,8 @@
require 'date'
# :stopdoc:
# = time.rb
#
# When 'time' is required, Time is extended with additional methods for parsing
@ -18,73 +20,8 @@ require 'date'
# 8601}[http://www.iso.org/iso/date_and_time_format])
# * various formats handled by Date._parse
# * custom formats handled by Date._strptime
#
# == Examples
#
# All examples assume you have loaded Time with:
#
# require 'time'
#
# All of these examples were done using the EST timezone which is GMT-5.
#
# === Converting to a String
#
# t = Time.now
# t.iso8601 # => "2011-10-05T22:26:12-04:00"
# t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400"
# t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT"
#
# === Time.parse
#
# #parse takes a string representation of a Time and attempts to parse it
# using a heuristic.
#
# Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500
#
# Any missing pieces of the date are inferred based on the current date.
#
# # assuming the current date is "2011-10-31"
# Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500
#
# We can change the date used to infer our missing elements by passing a second
# object that responds to #mon, #day and #year, such as Date, Time or DateTime.
# We can also use our own object.
#
# class MyDate
# attr_reader :mon, :day, :year
#
# def initialize(mon, day, year)
# @mon, @day, @year = mon, day, year
# end
# end
#
# d = Date.parse("2010-10-28")
# t = Time.parse("2010-10-29")
# dt = DateTime.parse("2010-10-30")
# md = MyDate.new(10,31,2010)
#
# Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500
# Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500
# Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500
# Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500
#
# #parse also accepts an optional block. You can use this block to specify how
# to handle the year component of the date. This is specifically designed for
# handling two digit years. For example, if you wanted to treat all two digit
# years prior to 70 as the year 2000+ you could write this:
#
# Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
# #=> 2001-10-31 00:00:00 -0500
# Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
# #=> 1970-10-31 00:00:00 -0500
#
# === Time.strptime
#
# #strptime works similar to +parse+ except that instead of using a heuristic
# to detect the format of the input string, you provide a second argument that
# describes the format of the string. For example:
#
# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500
# :startdoc:
class Time
class << Time
@ -131,6 +68,13 @@ class Time
#
# If +zone_offset+ is unable to determine the offset, nil will be
# returned.
#
# require 'time'
#
# Time.zone_offset("EST") #=> -18000
#
# You must require 'time' to use this method.
#
def zone_offset(zone, year=self.now.year)
off = nil
zone = zone.upcase
@ -316,17 +260,62 @@ class Time
private :make_time
#
# Parses +date+ using Date._parse and converts it to a Time object.
# Takes a string representation of a Time and attempts to parse it
# using a heuristic.
#
# If a block is given, the year described in +date+ is converted by the
# block. For example:
# require 'time'
#
# Time.parse(...) {|y| 0 <= y && y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y}
# Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500
#
# Any missing pieces of the date are inferred based on the current date.
#
# require 'time'
#
# # assuming the current date is "2011-10-31"
# Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500
#
# We can change the date used to infer our missing elements by passing a second
# object that responds to #mon, #day and #year, such as Date, Time or DateTime.
# We can also use our own object.
#
# require 'time'
#
# class MyDate
# attr_reader :mon, :day, :year
#
# def initialize(mon, day, year)
# @mon, @day, @year = mon, day, year
# end
# end
#
# d = Date.parse("2010-10-28")
# t = Time.parse("2010-10-29")
# dt = DateTime.parse("2010-10-30")
# md = MyDate.new(10,31,2010)
#
# Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500
# Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500
# Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500
# Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500
#
# If a block is given, the year described in +date+ is converted
# by the block. This is specifically designed for handling two
# digit years. For example, if you wanted to treat all two digit
# years prior to 70 as the year 2000+ you could write this:
#
# require 'time'
#
# Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
# #=> 2001-10-31 00:00:00 -0500
# Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
# #=> 1970-10-31 00:00:00 -0500
#
# If the upper components of the given time are broken or missing, they are
# supplied with those of +now+. For the lower components, the minimum
# values (1 or 0) are assumed if broken or missing. For example:
#
# require 'time'
#
# # Suppose it is "Thu Nov 29 14:33:20 2001" now and
# # your time zone is EST which is GMT-5.
# now = Time.parse("Thu Nov 29 14:33:20 2001")
@ -378,7 +367,9 @@ class Time
end
#
# Parses +date+ using Date._strptime and converts it to a Time object.
# Works similar to +parse+ except that instead of using a
# heuristic to detect the format of the input string, you provide
# a second argument that describes the format of the string.
#
# If a block is given, the year described in +date+ is converted by the
# block. For example:
@ -436,7 +427,13 @@ class Time
# %Z :: Time zone name
# %% :: Literal "%" character
# %+ :: date(1) (%a %b %e %H:%M:%S %Z %Y)
#
# require 'time'
#
# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500
#
# You must require 'time' to use this method.
#
def strptime(date, format, now=self.now)
d = Date._strptime(date, format)
raise ArgumentError, "invalid strptime format - `#{format}'" unless d
@ -474,6 +471,11 @@ class Time
#
# See #rfc2822 for more information on this format.
#
# require 'time'
#
# Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400")
# #=> 2010-10-05 22:26:12 -0400
#
# You must require 'time' to use this method.
#
def rfc2822(date)
@ -527,6 +529,11 @@ class Time
#
# See #httpdate for more information on this format.
#
# require 'time'
#
# Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT")
# #=> 2011-10-06 02:26:12 UTC
#
# You must require 'time' to use this method.
#
def httpdate(date)
@ -576,6 +583,12 @@ class Time
#
# See #xmlschema for more information on this format.
#
# require 'time'
#
# t = Time.now
# Time.xmlschema("2011-10-05T22:26:12-04:00")
# #=> 2011-10-05 22:26:12-04:00
#
# You must require 'time' to use this method.
#
def xmlschema(date)
@ -623,6 +636,11 @@ class Time
#
# If +self+ is a UTC time, -0000 is used as zone.
#
# require 'time'
#
# t = Time.now
# t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400"
#
# You must require 'time' to use this method.
#
def rfc2822
@ -658,6 +676,11 @@ class Time
#
# Note that the result is always UTC (GMT).
#
# require 'time'
#
# t = Time.now
# t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT"
#
# You must require 'time' to use this method.
#
def httpdate
@ -682,6 +705,11 @@ class Time
# +fractional_digits+ specifies a number of digits to use for fractional
# seconds. Its default value is 0.
#
# require 'time'
#
# t = Time.now
# t.iso8601 # => "2011-10-05T22:26:12-04:00"
#
# You must require 'time' to use this method.
#
def xmlschema(fraction_digits=0)