stdlib/date/0/date.rbs in rbs-3.0.0.dev.2 vs stdlib/date/0/date.rbs in rbs-3.0.0.dev.3

- old
+ new

@@ -1,628 +1,756 @@ # <!-- rdoc-file=ext/date/date_core.c --> -# date and datetime class - Tadayoshi Funaba 1998-2011 +# Class Date provides methods for storing and manipulating calendar dates. # -# 'date' provides two classes: Date and DateTime. +# Consider using [class Time](rdoc-ref:Time) instead of class Date if: # -# ## Terms and Definitions +# * You need both dates and times; Date handles only dates. +# * You need only Gregorian dates (and not Julian dates); see [Julian and +# Gregorian Calendars](rdoc-ref:calendars.rdoc). # -# Some terms and definitions are based on ISO 8601 and JIS X 0301. # -# ### Calendar Date +# A Date object, once created, is immutable, and cannot be modified. # -# The calendar date is a particular day of a calendar year, identified by its -# ordinal number within a calendar month within that year. +# ## Creating a Date # -# In those classes, this is so-called "civil". +# You can create a date for the current date, using Date.today: # -# ### Ordinal Date +# Date.today # => #<Date: 1999-12-31> # -# The ordinal date is a particular day of a calendar year identified by its -# ordinal number within the year. +# You can create a specific date from various combinations of arguments: # -# In those classes, this is so-called "ordinal". +# * Date.new takes integer year, month, and day-of-month: # -# ### Week Date +# Date.new(1999, 12, 31) # => #<Date: 1999-12-31> # -# The week date is a date identified by calendar week and day numbers. +# * Date.ordinal takes integer year and day-of-year: # -# The calendar week is a seven day period within a calendar year, starting on a -# Monday and identified by its ordinal number within the year; the first -# calendar week of the year is the one that includes the first Thursday of that -# year. In the Gregorian calendar, this is equivalent to the week which includes -# January 4. +# Date.ordinal(1999, 365) # => #<Date: 1999-12-31> # -# In those classes, this is so-called "commercial". +# * Date.jd takes integer Julian day: # -# ### Julian Day Number +# Date.jd(2451544) # => #<Date: 1999-12-31> # -# The Julian day number is in elapsed days since noon (Greenwich Mean Time) on -# January 1, 4713 BCE (in the Julian calendar). +# * Date.commercial takes integer commercial data (year, week, day-of-week): # -# In this document, the astronomical Julian day number is the same as the -# original Julian day number. And the chronological Julian day number is a -# variation of the Julian day number. Its days begin at midnight on local time. +# Date.commercial(1999, 52, 5) # => #<Date: 1999-12-31> # -# In this document, when the term "Julian day number" simply appears, it just -# refers to "chronological Julian day number", not the original. +# * Date.parse takes a string, which it parses heuristically: # -# In those classes, those are so-called "ajd" and "jd". +# Date.parse('1999-12-31') # => #<Date: 1999-12-31> +# Date.parse('31-12-1999') # => #<Date: 1999-12-31> +# Date.parse('1999-365') # => #<Date: 1999-12-31> +# Date.parse('1999-W52-5') # => #<Date: 1999-12-31> # -# ### Modified Julian Day Number +# * Date.strptime takes a date string and a format string, then parses the +# date string according to the format string: # -# The modified Julian day number is in elapsed days since midnight (Coordinated -# Universal Time) on November 17, 1858 CE (in the Gregorian calendar). +# Date.strptime('1999-12-31', '%Y-%m-%d') # => #<Date: 1999-12-31> +# Date.strptime('31-12-1999', '%d-%m-%Y') # => #<Date: 1999-12-31> +# Date.strptime('1999-365', '%Y-%j') # => #<Date: 1999-12-31> +# Date.strptime('1999-W52-5', '%G-W%V-%u') # => #<Date: 1999-12-31> +# Date.strptime('1999 52 5', '%Y %U %w') # => #<Date: 1999-12-31> +# Date.strptime('1999 52 5', '%Y %W %u') # => #<Date: 1999-12-31> +# Date.strptime('fri31dec99', '%a%d%b%y') # => #<Date: 1999-12-31> # -# In this document, the astronomical modified Julian day number is the same as -# the original modified Julian day number. And the chronological modified Julian -# day number is a variation of the modified Julian day number. Its days begin at -# midnight on local time. # -# In this document, when the term "modified Julian day number" simply appears, -# it just refers to "chronological modified Julian day number", not the -# original. +# See also the specialized methods in ["Specialized Format Strings" in Formats +# for Dates and +# Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) # -# In those classes, those are so-called "amjd" and "mjd". +# ## Argument `limit` # -# ## Date +# Certain singleton methods in Date that parse string arguments also take +# optional keyword argument `limit`, which can limit the length of the string +# argument. # -# A subclass of Object that includes the Comparable module and easily handles -# date. +# When `limit` is: # -# A Date object is created with Date::new, Date::jd, Date::ordinal, -# Date::commercial, Date::parse, Date::strptime, Date::today, Time#to_date, etc. +# * Non-negative: raises ArgumentError if the string length is greater than +# *limit*. +# * Other numeric or `nil`: ignores `limit`. +# * Other non-numeric: raises TypeError. # -# require 'date' -# -# Date.new(2001,2,3) -# #=> #<Date: 2001-02-03 ...> -# Date.jd(2451944) -# #=> #<Date: 2001-02-03 ...> -# Date.ordinal(2001,34) -# #=> #<Date: 2001-02-03 ...> -# Date.commercial(2001,5,6) -# #=> #<Date: 2001-02-03 ...> -# Date.parse('2001-02-03') -# #=> #<Date: 2001-02-03 ...> -# Date.strptime('03-02-2001', '%d-%m-%Y') -# #=> #<Date: 2001-02-03 ...> -# Time.new(2001,2,3).to_date -# #=> #<Date: 2001-02-03 ...> -# -# All date objects are immutable; hence cannot modify themselves. -# -# The concept of a date object can be represented as a tuple of the day count, -# the offset and the day of calendar reform. -# -# The day count denotes the absolute position of a temporal dimension. The -# offset is relative adjustment, which determines decoded local time with the -# day count. The day of calendar reform denotes the start day of the new style. -# The old style of the West is the Julian calendar which was adopted by Caesar. -# The new style is the Gregorian calendar, which is the current civil calendar -# of many countries. -# -# The day count is virtually the astronomical Julian day number. The offset in -# this class is usually zero, and cannot be specified directly. -# -# A Date object can be created with an optional argument, the day of calendar -# reform as a Julian day number, which should be 2298874 to 2426355 or -# negative/positive infinity. The default value is `Date::ITALY` -# (2299161=1582-10-15). See also sample/cal.rb. -# -# $ ruby sample/cal.rb -c it 10 1582 -# October 1582 -# S M Tu W Th F S -# 1 2 3 4 15 16 -# 17 18 19 20 21 22 23 -# 24 25 26 27 28 29 30 -# 31 -# -# $ ruby sample/cal.rb -c gb 9 1752 -# September 1752 -# S M Tu W Th F S -# 1 2 14 15 16 -# 17 18 19 20 21 22 23 -# 24 25 26 27 28 29 30 -# -# A Date object has various methods. See each reference. -# -# d = Date.parse('3rd Feb 2001') -# #=> #<Date: 2001-02-03 ...> -# d.year #=> 2001 -# d.mon #=> 2 -# d.mday #=> 3 -# d.wday #=> 6 -# d += 1 #=> #<Date: 2001-02-04 ...> -# d.strftime('%a %d %b %Y') #=> "Sun 04 Feb 2001" -# class Date # <!-- # rdoc-file=ext/date/date_core.c - # - new(p1 = v1, p2 = v2, p3 = v3, p4 = v4) + # - Date.new(year = -4712, month = 1, mday = 1, start = Date::ITALY) -> date # --> + # Returns a new Date object constructed from the given arguments: # + # Date.new(2022).to_s # => "2022-01-01" + # Date.new(2022, 2).to_s # => "2022-02-01" + # Date.new(2022, 2, 4).to_s # => "2022-02-04" + # + # Argument `month` should be in range (1..12) or range (-12..-1); when the + # argument is negative, counts backward from the end of the year: + # + # Date.new(2022, -11, 4).to_s # => "2022-02-04" + # + # Argument `mday` should be in range (1..n) or range (-n..-1) where `n` is the + # number of days in the month; when the argument is negative, counts backward + # from the end of the month. + # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # Date.civil is an alias for Date.new. + # + # Related: Date.jd. + # def initialize: (?Integer year, ?Integer month, ?Integer mday, ?Integer start) -> void include Comparable # <!-- # rdoc-file=ext/date/date_core.c - # - Date._httpdate(string, limit: 128) -> hash + # - Date._httpdate(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid [HTTP + # date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + # Date._httpdate(s) + # # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0} # + # Related: Date.httpdate (returns a Date object). + # def self._httpdate: (String str) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._iso8601(string, limit: 128) -> hash + # - Date._iso8601(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should contain an [ISO + # 8601 formatted + # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.iso8601 # => "2001-02-03" + # Date._iso8601(s) # => {:mday=>3, :year=>2001, :mon=>2} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Related: Date.iso8601 (returns a Date object). + # def self._iso8601: (String str) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._jisx0301(string, limit: 128) -> hash + # - Date._jisx0301(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid [JIS X + # 0301 date format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.jisx0301 # => "H13.02.03" + # Date._jisx0301(s) # => {:year=>2001, :mon=>2, :mday=>3} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Related: Date.jisx0301 (returns a Date object). + # def self._jisx0301: (String str) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._parse(string[, comp=true], limit: 128) -> hash + # - Date._parse(string, comp = true, limit: 128) -> hash # --> - # Parses the given representation of date and time, and returns a hash of parsed - # elements. + # **Note**: This method recognizes many forms in `string`, but it is not a + # validator. For formats, see ["Specialized Format Strings" in Formats for Dates + # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) # - # This method *does not* function as a validator. If the input string does not - # match valid formats strictly, you may get a cryptic result. Should consider - # to use `Date._strptime` or `DateTime._strptime` instead of this method as - # possible. + # If `string` does not specify a valid date, the result is unpredictable; + # consider using Date._strptime instead. # - # If the optional second argument is true and the detected year is in the range - # "00" to "99", considers the year a 2-digit form and makes it full. + # Returns a hash of values parsed from `string`: # - # Date._parse('2001-02-03') #=> {:year=>2001, :mon=>2, :mday=>3} + # Date._parse('2001-02-03') # => {:year=>2001, :mon=>2, :mday=>3} # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # If `comp` is `true` and the given year is in the range `(0..99)`, the current + # century is supplied; otherwise, the year is taken as given: # + # Date._parse('01-02-03', true) # => {:year=>2001, :mon=>2, :mday=>3} + # Date._parse('01-02-03', false) # => {:year=>1, :mon=>2, :mday=>3} + # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Related: Date.parse(returns a Date object). + # def self._parse: (String str, ?boolish complete) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._rfc2822(string, limit: 128) -> hash - # - Date._rfc822(string, limit: 128) -> hash + # - Date._rfc2822(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid [RFC + # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Date._rfc2822(s) + # # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Date._rfc822 is an alias for Date._rfc2822. + # + # Related: Date.rfc2822 (returns a Date object). + # def self._rfc2822: (String str) -> Hash[Symbol, Integer | String] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._rfc3339(string, limit: 128) -> hash + # - Date._rfc3339(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid [RFC + # 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + # Date._rfc3339(s) + # # => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Related: Date.rfc3339 (returns a Date object). + # def self._rfc3339: (String str) -> Hash[Symbol, Integer | String] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._rfc2822(string, limit: 128) -> hash - # - Date._rfc822(string, limit: 128) -> hash + # - Date._rfc2822(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid [RFC + # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Date._rfc2822(s) + # # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Date._rfc822 is an alias for Date._rfc2822. + # + # Related: Date.rfc2822 (returns a Date object). + # def self._rfc822: (String str) -> Hash[Symbol, Integer | String] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._strptime(string[, format='%F']) -> hash + # - Date._strptime(string, format = '%F') -> hash # --> - # Parses the given representation of date and time with the given template, and - # returns a hash of parsed elements. _strptime does not support specification - # of flags and width unlike strftime. + # Returns a hash of values parsed from `string` according to the given `format`: # - # Date._strptime('2001-02-03', '%Y-%m-%d') - # #=> {:year=>2001, :mon=>2, :mday=>3} + # Date._strptime('2001-02-03', '%Y-%m-%d') # => {:year=>2001, :mon=>2, :mday=>3} # - # See also strptime(3) and #strftime. + # For other formats, see [Formats for Dates and + # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not + # support flags and width.) # + # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html). + # + # Related: Date.strptime (returns a Date object). + # def self._strptime: (String str, ?String format) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date._xmlschema(string, limit: 128) -> hash + # - Date._xmlschema(string, limit: 128) -> hash # --> - # Returns a hash of parsed elements. + # Returns a hash of values parsed from `string`, which should be a valid XML + # date format: # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # d = Date.new(2001, 2, 3) + # s = d.xmlschema # => "2001-02-03" + # Date._xmlschema(s) # => {:year=>2001, :mon=>2, :mday=>3} # + # See argument [limit](rdoc-ref:Date@Argument+limit). + # + # Related: Date.xmlschema (returns a Date object). + # def self._xmlschema: (String str) -> Hash[Symbol, Integer] # <!-- # rdoc-file=ext/date/date_core.c - # - Date.civil([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]]) -> date - # - Date.new([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]]) -> date + # - civil(*args) # --> - # Creates a date object denoting the given calendar date. + # Same as Date.new. # - # In this class, BCE years are counted astronomically. Thus, the year before - # the year 1 is the year zero, and the year preceding the year zero is the year - # -1. The month and the day of month should be a negative or a positive number - # (as a relative month/day from the end of year/month when negative). They - # should not be zero. - # - # The last argument should be a Julian day number which denotes the day of - # calendar reform. Date::ITALY (2299161=1582-10-15), Date::ENGLAND - # (2361222=1752-09-14), Date::GREGORIAN (the proleptic Gregorian calendar) and - # Date::JULIAN (the proleptic Julian calendar) can be specified as a day of - # calendar reform. - # - # Date.new(2001) #=> #<Date: 2001-01-01 ...> - # Date.new(2001,2,3) #=> #<Date: 2001-02-03 ...> - # Date.new(2001,2,-1) #=> #<Date: 2001-02-28 ...> - # - # See also ::jd. - # def self.civil: (?Integer year, ?Integer month, ?Integer mday, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.commercial([cwyear=-4712[, cweek=1[, cwday=1[, start=Date::ITALY]]]]) -> date + # - Date.commercial(cwyear = -4712, cweek = 1, cwday = 1, start = Date::ITALY) -> date # --> - # Creates a date object denoting the given week date. + # Returns a new Date object constructed from the arguments. # - # The week and the day of week should be a negative or a positive number (as a - # relative week/day from the end of year/week when negative). They should not - # be zero. + # Argument `cwyear` gives the year, and should be an integer. # - # Date.commercial(2001) #=> #<Date: 2001-01-01 ...> - # Date.commercial(2002) #=> #<Date: 2001-12-31 ...> - # Date.commercial(2001,5,6) #=> #<Date: 2001-02-03 ...> + # Argument `cweek` gives the index of the week within the year, and should be in + # range (1..53) or (-53..-1); in some years, 53 or -53 will be out-of-range; if + # negative, counts backward from the end of the year: # - # See also ::jd and ::new. + # Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + # Date.commercial(2022, 52, 1).to_s # => "2022-12-26" # + # Argument `cwday` gives the indes of the weekday within the week, and should be + # in range (1..7) or (-7..-1); 1 or -7 is Monday; if negative, counts backward + # from the end of the week: + # + # Date.commercial(2022, 1, 1).to_s # => "2022-01-03" + # Date.commercial(2022, 1, -7).to_s # => "2022-01-03" + # + # When `cweek` is 1: + # + # * If January 1 is a Friday, Saturday, or Sunday, the first week begins in + # the week after: + # + # Date::ABBR_DAYNAMES[Date.new(2023, 1, 1).wday] # => "Sun" + # Date.commercial(2023, 1, 1).to_s # => "2023-01-02" + # Date.commercial(2023, 1, 7).to_s # => "2023-01-08" + # + # * Otherwise, the first week is the week of January 1, which may mean some of + # the days fall on the year before: + # + # Date::ABBR_DAYNAMES[Date.new(2020, 1, 1).wday] # => "Wed" + # Date.commercial(2020, 1, 1).to_s # => "2019-12-30" + # Date.commercial(2020, 1, 7).to_s # => "2020-01-05" + # + # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # Related: Date.jd, Date.new, Date.ordinal. + # def self.commercial: (?Integer cwyear, ?Integer cweek, ?Integer cwday, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.gregorian_leap?(year) -> bool - # - Date.leap?(year) -> bool + # - Date.gregorian_leap?(year) -> true or false # --> - # Returns true if the given year is a leap year of the proleptic Gregorian - # calendar. + # Returns `true` if the given year is a leap year in the [proleptic Gregorian + # calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), `false` + # otherwise: # - # Date.gregorian_leap?(1900) #=> false - # Date.gregorian_leap?(2000) #=> true + # Date.gregorian_leap?(2000) # => true + # Date.gregorian_leap?(2001) # => false # + # Date.leap? is an alias for Date.gregorian_leap?. + # + # Related: Date.julian_leap?. + # def self.gregorian_leap?: (Integer year) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY], limit: 128) -> date + # - Date.httpdate(string = 'Mon, 01 Jan -4712 00:00:00 GMT', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some RFC 2616 - # format. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [HTTP date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format): # - # Date.httpdate('Sat, 03 Feb 2001 00:00:00 GMT') - # #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + # Date.httpdate(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._httpdate (returns a hash). + # def self.httpdate: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.iso8601(string='-4712-01-01'[, start=Date::ITALY], limit: 128) -> date + # - Date.iso8601(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # ISO 8601 formats. + # Returns a new Date object with values parsed from `string`, which should + # contain an [ISO 8601 formatted + # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications): # - # Date.iso8601('2001-02-03') #=> #<Date: 2001-02-03 ...> - # Date.iso8601('20010203') #=> #<Date: 2001-02-03 ...> - # Date.iso8601('2001-W05-6') #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.iso8601 # => "2001-02-03" + # Date.iso8601(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._iso8601 (returns a hash). + # def self.iso8601: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.jd([jd=0[, start=Date::ITALY]]) -> date + # - Date.jd(jd = 0, start = Date::ITALY) -> date # --> - # Creates a date object denoting the given chronological Julian day number. + # Returns a new Date object formed from the arguments: # - # Date.jd(2451944) #=> #<Date: 2001-02-03 ...> - # Date.jd(2451945) #=> #<Date: 2001-02-04 ...> - # Date.jd(0) #=> #<Date: -4712-01-01 ...> + # Date.jd(2451944).to_s # => "2001-02-03" + # Date.jd(2451945).to_s # => "2001-02-04" + # Date.jd(0).to_s # => "-4712-01-01" # - # See also ::new. + # The returned date is: # + # * Gregorian, if the argument is greater than or equal to `start`: + # + # Date::ITALY # => 2299161 + # Date.jd(Date::ITALY).gregorian? # => true + # Date.jd(Date::ITALY + 1).gregorian? # => true + # + # * Julian, otherwise + # + # Date.jd(Date::ITALY - 1).julian? # => true + # + # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # Related: Date.new. + # def self.jd: (Integer jd, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.jisx0301(string='-4712-01-01'[, start=Date::ITALY], limit: 128) -> date + # - Date.jisx0301(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # JIS X 0301 formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [JIS X 0301 + # format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format): # - # Date.jisx0301('H13.02.03') #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.jisx0301 # => "H13.02.03" + # Date.jisx0301(s) # => #<Date: 2001-02-03> # # For no-era year, legacy format, Heisei is assumed. # - # Date.jisx0301('13.02.03') #=> #<Date: 2001-02-03 ...> + # Date.jisx0301('13.02.03') # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._jisx0301 (returns a hash). + # def self.jisx0301: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.julian_leap?(year) -> bool + # - Date.julian_leap?(year) -> true or false # --> - # Returns true if the given year is a leap year of the proleptic Julian - # calendar. + # Returns `true` if the given year is a leap year in the [proleptic Julian + # calendar](https://en.wikipedia.org/wiki/Proleptic_Julian_calendar), `false` + # otherwise: # - # Date.julian_leap?(1900) #=> true - # Date.julian_leap?(1901) #=> false + # Date.julian_leap?(1900) # => true + # Date.julian_leap?(1901) # => false # + # Related: Date.gregorian_leap?. + # def self.julian_leap?: (Integer year) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.gregorian_leap?(year) -> bool - # - Date.leap?(year) -> bool + # - Date.gregorian_leap?(year) -> true or false # --> - # Returns true if the given year is a leap year of the proleptic Gregorian - # calendar. + # Returns `true` if the given year is a leap year in the [proleptic Gregorian + # calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), `false` + # otherwise: # - # Date.gregorian_leap?(1900) #=> false - # Date.gregorian_leap?(2000) #=> true + # Date.gregorian_leap?(2000) # => true + # Date.gregorian_leap?(2001) # => false # + # Date.leap? is an alias for Date.gregorian_leap?. + # + # Related: Date.julian_leap?. + # def self.leap?: (Integer year) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.ordinal([year=-4712[, yday=1[, start=Date::ITALY]]]) -> date + # - Date.ordinal(year = -4712, yday = 1, start = Date::ITALY) -> date # --> - # Creates a date object denoting the given ordinal date. + # Returns a new Date object formed fom the arguments. # - # The day of year should be a negative or a positive number (as a relative day - # from the end of year when negative). It should not be zero. + # With no arguments, returns the date for January 1, -4712: # - # Date.ordinal(2001) #=> #<Date: 2001-01-01 ...> - # Date.ordinal(2001,34) #=> #<Date: 2001-02-03 ...> - # Date.ordinal(2001,-1) #=> #<Date: 2001-12-31 ...> + # Date.ordinal.to_s # => "-4712-01-01" # - # See also ::jd and ::new. + # With argument `year`, returns the date for January 1 of that year: # + # Date.ordinal(2001).to_s # => "2001-01-01" + # Date.ordinal(-2001).to_s # => "-2001-01-01" + # + # With positive argument `yday` == `n`, returns the date for the `nth` day of + # the given year: + # + # Date.ordinal(2001, 14).to_s # => "2001-01-14" + # + # With negative argument `yday`, counts backward from the end of the year: + # + # Date.ordinal(2001, -14).to_s # => "2001-12-18" + # + # Raises an exception if `yday` is zero or out of range. + # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # Related: Date.jd, Date.new. + # def self.ordinal: (?Integer year, ?Integer yday, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.parse(string='-4712-01-01'[, comp=true[, start=Date::ITALY]], limit: 128) -> date + # - Date.parse(string = '-4712-01-01', comp = true, start = Date::ITALY, limit: 128) -> date # --> - # Parses the given representation of date and time, and creates a date object. + # **Note**: This method recognizes many forms in `string`, but it is not a + # validator. For formats, see ["Specialized Format Strings" in Formats for Dates + # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) If + # `string` does not specify a valid date, the result is unpredictable; consider + # using Date._strptime instead. # - # This method *does not* function as a validator. If the input string does not - # match valid formats strictly, you may get a cryptic result. Should consider - # to use `Date.strptime` instead of this method as possible. + # Returns a new Date object with values parsed from `string`: # - # If the optional second argument is true and the detected year is in the range - # "00" to "99", considers the year a 2-digit form and makes it full. + # Date.parse('2001-02-03') # => #<Date: 2001-02-03> + # Date.parse('20010203') # => #<Date: 2001-02-03> + # Date.parse('3rd Feb 2001') # => #<Date: 2001-02-03> # - # Date.parse('2001-02-03') #=> #<Date: 2001-02-03 ...> - # Date.parse('20010203') #=> #<Date: 2001-02-03 ...> - # Date.parse('3rd Feb 2001') #=> #<Date: 2001-02-03 ...> + # If `comp` is `true` and the given year is in the range `(0..99)`, the current + # century is supplied; otherwise, the year is taken as given: # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # Date.parse('01-02-03', true) # => #<Date: 2001-02-03> + # Date.parse('01-02-03', false) # => #<Date: 0001-02-03> # + # See: + # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._parse (returns a hash). + # def self.parse: (String str, ?boolish complete, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) -> date - # - Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) -> date + # - Date.rfc2822(string = 'Mon, 1 Jan -4712 00:00:00 +0000', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # RFC 2822 formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [RFC 2822 date + # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): # - # Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000') - # #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Date.rfc2822(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Date.rfc822 is an alias for Date.rfc2822. + # + # Related: Date._rfc2822 (returns a hash). + # def self.rfc2822: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) -> date + # - Date.rfc3339(string = '-4712-01-01T00:00:00+00:00', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # RFC 3339 formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [RFC 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format): # - # Date.rfc3339('2001-02-03T04:05:06+07:00') #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.rfc3339 # => "2001-02-03T00:00:00+00:00" + # Date.rfc3339(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._rfc3339 (returns a hash). + # def self.rfc3339: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) -> date - # - Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) -> date + # - Date.rfc2822(string = 'Mon, 1 Jan -4712 00:00:00 +0000', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # RFC 2822 formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [RFC 2822 date + # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): # - # Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000') - # #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Date.rfc2822(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Date.rfc822 is an alias for Date.rfc2822. + # + # Related: Date._rfc2822 (returns a hash). + # def self.rfc822: (String str, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.strptime([string='-4712-01-01'[, format='%F'[, start=Date::ITALY]]]) -> date + # - Date.strptime(string = '-4712-01-01', format = '%F', start = Date::ITALY) -> date # --> - # Parses the given representation of date and time with the given template, and - # creates a date object. strptime does not support specification of flags and - # width unlike strftime. + # Returns a new Date object with values parsed from `string`, according to the + # given `format`: # - # Date.strptime('2001-02-03', '%Y-%m-%d') #=> #<Date: 2001-02-03 ...> - # Date.strptime('03-02-2001', '%d-%m-%Y') #=> #<Date: 2001-02-03 ...> - # Date.strptime('2001-034', '%Y-%j') #=> #<Date: 2001-02-03 ...> - # Date.strptime('2001-W05-6', '%G-W%V-%u') #=> #<Date: 2001-02-03 ...> - # Date.strptime('2001 04 6', '%Y %U %w') #=> #<Date: 2001-02-03 ...> - # Date.strptime('2001 05 6', '%Y %W %u') #=> #<Date: 2001-02-03 ...> - # Date.strptime('sat3feb01', '%a%d%b%y') #=> #<Date: 2001-02-03 ...> + # Date.strptime('2001-02-03', '%Y-%m-%d') # => #<Date: 2001-02-03> + # Date.strptime('03-02-2001', '%d-%m-%Y') # => #<Date: 2001-02-03> + # Date.strptime('2001-034', '%Y-%j') # => #<Date: 2001-02-03> + # Date.strptime('2001-W05-6', '%G-W%V-%u') # => #<Date: 2001-02-03> + # Date.strptime('2001 04 6', '%Y %U %w') # => #<Date: 2001-02-03> + # Date.strptime('2001 05 6', '%Y %W %u') # => #<Date: 2001-02-03> + # Date.strptime('sat3feb01', '%a%d%b%y') # => #<Date: 2001-02-03> # - # See also strptime(3) and #strftime. + # For other formats, see [Formats for Dates and + # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not + # support flags and width.) # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html). + # + # Related: Date._strptime (returns a hash). + # def self.strptime: (String str, ?String format, ?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.today([start=Date::ITALY]) -> date + # - Date.today(start = Date::ITALY) -> date # --> - # Creates a date object denoting the present day. + # Returns a new Date object constructed from the present date: # - # Date.today #=> #<Date: 2011-06-11 ...> + # Date.today.to_s # => "2022-07-06" # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # def self.today: (?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - Date.valid_civil?(year, month, mday[, start=Date::ITALY]) -> bool - # - Date.valid_date?(year, month, mday[, start=Date::ITALY]) -> bool + # - Date.valid_civil?(year, month, mday, start = Date::ITALY) -> true or false # --> - # Returns true if the given calendar date is valid, and false if not. Valid in - # this context is whether the arguments passed to this method would be accepted - # by ::new. + # Returns `true` if the arguments define a valid ordinal date, `false` + # otherwise: # - # Date.valid_date?(2001,2,3) #=> true - # Date.valid_date?(2001,2,29) #=> false - # Date.valid_date?(2001,2,-1) #=> true + # Date.valid_date?(2001, 2, 3) # => true + # Date.valid_date?(2001, 2, 29) # => false + # Date.valid_date?(2001, 2, -1) # => true # - # See also ::jd and ::civil. + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). # + # Date.valid_date? is an alias for Date.valid_civil?. + # + # Related: Date.jd, Date.new. + # def self.valid_civil?: (Integer year, Integer month, Integer mday, ?Integer start) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.valid_commercial?(cwyear, cweek, cwday[, start=Date::ITALY]) -> bool + # - Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false # --> - # Returns true if the given week date is valid, and false if not. + # Returns `true` if the arguments define a valid commercial date, `false` + # otherwise: # - # Date.valid_commercial?(2001,5,6) #=> true - # Date.valid_commercial?(2001,5,8) #=> false + # Date.valid_commercial?(2001, 5, 6) # => true + # Date.valid_commercial?(2001, 5, 8) # => false # - # See also ::jd and ::commercial. + # See Date.commercial. # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + # Related: Date.jd, Date.commercial. + # def self.valid_commercial?: (Integer cwyear, Integer cweek, Integer cwday, ?Integer start) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.valid_civil?(year, month, mday[, start=Date::ITALY]) -> bool - # - Date.valid_date?(year, month, mday[, start=Date::ITALY]) -> bool + # - Date.valid_civil?(year, month, mday, start = Date::ITALY) -> true or false # --> - # Returns true if the given calendar date is valid, and false if not. Valid in - # this context is whether the arguments passed to this method would be accepted - # by ::new. + # Returns `true` if the arguments define a valid ordinal date, `false` + # otherwise: # - # Date.valid_date?(2001,2,3) #=> true - # Date.valid_date?(2001,2,29) #=> false - # Date.valid_date?(2001,2,-1) #=> true + # Date.valid_date?(2001, 2, 3) # => true + # Date.valid_date?(2001, 2, 29) # => false + # Date.valid_date?(2001, 2, -1) # => true # - # See also ::jd and ::civil. + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). # + # Date.valid_date? is an alias for Date.valid_civil?. + # + # Related: Date.jd, Date.new. + # def self.valid_date?: (Integer year, Integer month, Integer mday, ?Integer start) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.valid_jd?(jd[, start=Date::ITALY]) -> bool + # - Date.valid_jd?(jd, start = Date::ITALY) -> true # --> - # Just returns true. It's nonsense, but is for symmetry. + # Implemented for compatibility; returns `true` unless `jd` is invalid (i.e., + # not a Numeric). # - # Date.valid_jd?(2451944) #=> true + # Date.valid_jd?(2451944) # => true # - # See also ::jd. + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). # + # Related: Date.jd. + # def self.valid_jd?: (Integer jd, ?Integer start) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.valid_ordinal?(year, yday[, start=Date::ITALY]) -> bool + # - Date.valid_ordinal?(year, yday, start = Date::ITALY) -> true or false # --> - # Returns true if the given ordinal date is valid, and false if not. + # Returns `true` if the arguments define a valid ordinal date, `false` + # otherwise: # - # Date.valid_ordinal?(2001,34) #=> true - # Date.valid_ordinal?(2001,366) #=> false + # Date.valid_ordinal?(2001, 34) # => true + # Date.valid_ordinal?(2001, 366) # => false # - # See also ::jd and ::ordinal. + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). # + # Related: Date.jd, Date.ordinal. + # def self.valid_ordinal?: (Integer year, Integer yday, ?Integer start) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - Date.xmlschema(string='-4712-01-01'[, start=Date::ITALY], limit: 128) -> date + # - Date.xmlschema(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date # --> - # Creates a new Date object by parsing from a string according to some typical - # XML Schema formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid XML date format: # - # Date.xmlschema('2001-02-03') #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.xmlschema # => "2001-02-03" + # Date.xmlschema(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Related: Date._xmlschema (returns a hash). + # def self.xmlschema: (String str, ?Integer start) -> Date public # <!-- @@ -665,89 +793,138 @@ # <!-- # rdoc-file=ext/date/date_core.c # - d << n -> date # --> - # Returns a date object pointing `n` months before self. The argument `n` should - # be a numeric value. + # Returns a new Date object representing the date `n` months earlier; `n` should + # be a numeric: # - # Date.new(2001,2,3) << 1 #=> #<Date: 2001-01-03 ...> - # Date.new(2001,2,3) << -2 #=> #<Date: 2001-04-03 ...> + # (Date.new(2001, 2, 3) << 1).to_s # => "2001-01-03" + # (Date.new(2001, 2, 3) << -2).to_s # => "2001-04-03" # - # When the same day does not exist for the corresponding month, the last day of - # the month is used instead: + # When the same day does not exist for the new month, the last day of that month + # is used instead: # - # Date.new(2001,3,28) << 1 #=> #<Date: 2001-02-28 ...> - # Date.new(2001,3,31) << 1 #=> #<Date: 2001-02-28 ...> + # (Date.new(2001, 3, 31) << 1).to_s # => "2001-02-28" + # (Date.new(2001, 3, 31) << -6).to_s # => "2001-09-30" # - # This also results in the following, possibly unexpected, behavior: + # This results in the following, possibly unexpected, behaviors: # - # Date.new(2001,3,31) << 2 #=> #<Date: 2001-01-31 ...> - # Date.new(2001,3,31) << 1 << 1 #=> #<Date: 2001-01-28 ...> + # d0 = Date.new(2001, 3, 31) + # d0 << 2 # => #<Date: 2001-01-31> + # d0 << 1 << 1 # => #<Date: 2001-01-28> # - # Date.new(2001,3,31) << 1 << -1 #=> #<Date: 2001-03-28 ...> + # d0 = Date.new(2001, 3, 31) + # d1 = d0 << 1 # => #<Date: 2001-02-28> + # d2 = d1 << -1 # => #<Date: 2001-03-28> # def <<: (Integer month) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d <=> other -> -1, 0, +1 or nil + # - self <=> other -> -1, 0, 1 or nil # --> - # Compares the two dates and returns -1, zero, 1 or nil. The other should be a - # date object or a numeric value as an astronomical Julian day number. + # Compares `self` and `other`, returning: # - # Date.new(2001,2,3) <=> Date.new(2001,2,4) #=> -1 - # Date.new(2001,2,3) <=> Date.new(2001,2,3) #=> 0 - # Date.new(2001,2,3) <=> Date.new(2001,2,2) #=> 1 - # Date.new(2001,2,3) <=> Object.new #=> nil - # Date.new(2001,2,3) <=> Rational(4903887,2) #=> 0 + # * `-1` if `other` is larger. + # * `0` if the two are equal. + # * `1` if `other` is smaller. + # * `nil` if the two are incomparable. # - # See also Comparable. # + # Argument `other` may be: + # + # * Another Date object: + # + # d = Date.new(2022, 7, 27) # => #<Date: 2022-07-27 ((2459788j,0s,0n),+0s,2299161j)> + # prev_date = d.prev_day # => #<Date: 2022-07-26 ((2459787j,0s,0n),+0s,2299161j)> + # next_date = d.next_day # => #<Date: 2022-07-28 ((2459789j,0s,0n),+0s,2299161j)> + # d <=> next_date # => -1 + # d <=> d # => 0 + # d <=> prev_date # => 1 + # + # * A DateTime object: + # + # d <=> DateTime.new(2022, 7, 26) # => 1 + # d <=> DateTime.new(2022, 7, 27) # => 0 + # d <=> DateTime.new(2022, 7, 28) # => -1 + # + # * A numeric (compares `self.ajd` to `other`): + # + # d <=> 2459788 # => -1 + # d <=> 2459787 # => 1 + # d <=> 2459786 # => 1 + # d <=> d.ajd # => 0 + # + # * Any other object: + # + # d <=> Object.new # => nil + # def <=>: (untyped other) -> Integer? # <!-- # rdoc-file=ext/date/date_core.c - # - d === other -> bool + # - self === other -> true, false, or nil. # --> - # Returns true if they are the same day. + # Returns `true` if `self` and `other` represent the same date, `false` if not, + # `nil` if the two are not comparable. # - # Date.new(2001,2,3) === Date.new(2001,2,3) - # #=> true - # Date.new(2001,2,3) === Date.new(2001,2,4) - # #=> false - # DateTime.new(2001,2,3) === DateTime.new(2001,2,3,12) - # #=> true - # DateTime.new(2001,2,3) === DateTime.new(2001,2,3,0,0,0,'+24:00') - # #=> true - # DateTime.new(2001,2,3) === DateTime.new(2001,2,4,0,0,0,'+24:00') - # #=> false + # Argument `other` may be: # + # * Another Date object: + # + # d = Date.new(2022, 7, 27) # => #<Date: 2022-07-27 ((2459788j,0s,0n),+0s,2299161j)> + # prev_date = d.prev_day # => #<Date: 2022-07-26 ((2459787j,0s,0n),+0s,2299161j)> + # next_date = d.next_day # => #<Date: 2022-07-28 ((2459789j,0s,0n),+0s,2299161j)> + # d === prev_date # => false + # d === d # => true + # d === next_date # => false + # + # * A DateTime object: + # + # d === DateTime.new(2022, 7, 26) # => false + # d === DateTime.new(2022, 7, 27) # => true + # d === DateTime.new(2022, 7, 28) # => false + # + # * A numeric (compares `self.jd` to `other`): + # + # d === 2459788 # => true + # d === 2459787 # => false + # d === 2459786 # => false + # d === d.jd # => true + # + # * An object not comparable: + # + # d === Object.new # => nil + # def ===: (Date other) -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d >> n -> date + # - d >> n -> new_date # --> - # Returns a date object pointing `n` months after self. The argument `n` should - # be a numeric value. + # Returns a new Date object representing the date `n` months later; `n` should + # be a numeric: # - # Date.new(2001,2,3) >> 1 #=> #<Date: 2001-03-03 ...> - # Date.new(2001,2,3) >> -2 #=> #<Date: 2000-12-03 ...> + # (Date.new(2001, 2, 3) >> 1).to_s # => "2001-03-03" + # (Date.new(2001, 2, 3) >> -2).to_s # => "2000-12-03" # - # When the same day does not exist for the corresponding month, the last day of - # the month is used instead: + # When the same day does not exist for the new month, the last day of that month + # is used instead: # - # Date.new(2001,1,28) >> 1 #=> #<Date: 2001-02-28 ...> - # Date.new(2001,1,31) >> 1 #=> #<Date: 2001-02-28 ...> + # (Date.new(2001, 1, 31) >> 1).to_s # => "2001-02-28" + # (Date.new(2001, 1, 31) >> -4).to_s # => "2000-09-30" # - # This also results in the following, possibly unexpected, behavior: + # This results in the following, possibly unexpected, behaviors: # - # Date.new(2001,1,31) >> 2 #=> #<Date: 2001-03-31 ...> - # Date.new(2001,1,31) >> 1 >> 1 #=> #<Date: 2001-03-28 ...> + # d0 = Date.new(2001, 1, 31) + # d1 = d0 >> 1 # => #<Date: 2001-02-28> + # d2 = d1 >> 1 # => #<Date: 2001-03-28> # - # Date.new(2001,1,31) >> 1 >> -1 #=> #<Date: 2001-01-28 ...> + # d0 = Date.new(2001, 1, 31) + # d1 = d0 >> 1 # => #<Date: 2001-02-28> + # d2 = d1 >> -1 # => #<Date: 2001-01-28> # def >>: (Integer month) -> Date # <!-- # rdoc-file=ext/date/date_core.c @@ -773,147 +950,198 @@ # def amjd: () -> Rational # <!-- # rdoc-file=ext/date/date_core.c - # - d.asctime -> string - # - d.ctime -> string + # - asctime -> string # --> - # Returns a string in asctime(3) format (but without "n\0" at the end). This - # method is equivalent to strftime('%c'). + # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand + # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) + # `'%c'`): # - # See also asctime(3) or ctime(3). + # Date.new(2001, 2, 3).asctime # => "Sat Feb 3 00:00:00 2001" # + # See [asctime](https://linux.die.net/man/3/asctime). + # + # Date#ctime is an alias for Date#asctime. + # def asctime: () -> String # <!-- rdoc-file=ext/date/date_core.c --> - # Returns a string in asctime(3) format (but without "n\0" at the end). This - # method is equivalent to strftime('%c'). + # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand + # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) + # `'%c'`): # - # See also asctime(3) or ctime(3). + # Date.new(2001, 2, 3).asctime # => "Sat Feb 3 00:00:00 2001" # + # See [asctime](https://linux.die.net/man/3/asctime). + # + # Date#ctime is an alias for Date#asctime. + # def ctime: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.cwday -> fixnum + # - cwday -> integer # --> - # Returns the day of calendar week (1-7, Monday is 1). + # Returns the commercial-date weekday index for `self` (see Date.commercial); 1 + # is Monday: # - # Date.new(2001,2,3).cwday #=> 6 + # Date.new(2001, 2, 3).cwday # => 6 # def cwday: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.cweek -> fixnum + # - cweek -> integer # --> - # Returns the calendar week number (1-53). + # Returns commercial-date week index for `self` (see Date.commercial): # - # Date.new(2001,2,3).cweek #=> 5 + # Date.new(2001, 2, 3).cweek # => 5 # def cweek: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.cwyear -> integer + # - cwyear -> integer # --> - # Returns the calendar week based year. + # Returns commercial-date year for `self` (see Date.commercial): # - # Date.new(2001,2,3).cwyear #=> 2001 - # Date.new(2000,1,1).cwyear #=> 1999 + # Date.new(2001, 2, 3).cwyear # => 2001 + # Date.new(2000, 1, 1).cwyear # => 1999 # def cwyear: () -> Integer # <!-- rdoc-file=ext/date/date_core.c --> - # Returns the day of the month (1-31). + # Returns the day of the month in range (1..31): # - # Date.new(2001,2,3).mday #=> 3 + # Date.new(2001, 2, 3).mday # => 3 # + # Date#day is an alias for Date#mday. + # def day: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.downto(min) -> enumerator - # - d.downto(min){|date| ...} -> self + # - deconstruct_keys(array_of_names_or_nil) -> hash # --> - # This method is equivalent to step(min, -1){|date| ...}. + # Returns a hash of the name/value pairs, to use in pattern matching. Possible + # keys are: `:year`, `:month`, `:day`, `:wday`, `:yday`. # + # Possible usages: + # + # d = Date.new(2022, 10, 5) + # + # if d in wday: 3, day: ..7 # uses deconstruct_keys underneath + # puts "first Wednesday of the month" + # end + # #=> prints "first Wednesday of the month" + # + # case d + # in year: ...2022 + # puts "too old" + # in month: ..9 + # puts "quarter 1-3" + # in wday: 1..5, month: + # puts "working day in month #{month}" + # end + # #=> prints "working day in month 10" + # + # Note that deconstruction by pattern can also be combined with class check: + # + # if d in Date(wday: 3, day: ..7) + # puts "first Wednesday of the month" + # end + # + def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, Integer] + + # <!-- + # rdoc-file=ext/date/date_core.c + # - downto(min){|date| ... } -> self + # --> + # Equivalent to #step with arguments `min` and `-1`. + # def downto: (Date min) { (Date) -> untyped } -> Date | (Date min) -> Enumerator[Date, Date] # <!-- # rdoc-file=ext/date/date_core.c - # - d.england -> date + # - england -> new_date # --> - # This method is equivalent to new_start(Date::ENGLAND). + # Equivalent to Date#new_start with argument Date::ENGLAND. # def england: () -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.friday? -> bool + # - friday? -> true or false # --> - # Returns true if the date is Friday. + # Returns `true` if `self` is a Friday, `false` otherwise. # def friday?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.gregorian -> date + # - gregorian -> new_date # --> - # This method is equivalent to new_start(Date::GREGORIAN). + # Equivalent to Date#new_start with argument Date::GREGORIAN. # def gregorian: () -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.gregorian? -> bool + # - gregorian? -> true or false # --> - # Returns true if the date is on or after the day of calendar reform. + # Returns `true` if the date is on or after the date of calendar reform, `false` + # otherwise: # - # Date.new(1582,10,15).gregorian? #=> true - # (Date.new(1582,10,15) - 1).gregorian? #=> false + # Date.new(1582, 10, 15).gregorian? # => true + # (Date.new(1582, 10, 15) - 1).gregorian? # => false # def gregorian?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.httpdate -> string + # - httpdate -> string # --> - # This method is equivalent to strftime('%a, %d %b %Y %T GMT'). See also RFC - # 2616. + # Equivalent to #strftime with argument `'%a, %d %b %Y %T GMT'`; see [Formats + # for Dates and Times](rdoc-ref:strftime_formatting.rdoc): # + # Date.new(2001, 2, 3).httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" + # def httpdate: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.inspect -> string + # - inspect -> string # --> - # Returns the value as a string for inspection. + # Returns a string representation of `self`: # - # Date.new(2001,2,3).inspect - # #=> "#<Date: 2001-02-03>" - # DateTime.new(2001,2,3,4,5,6,'-7').inspect - # #=> "#<DateTime: 2001-02-03T04:05:06-07:00>" + # Date.new(2001, 2, 3).inspect + # # => "#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>" # def inspect: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.iso8601 -> string - # - d.xmlschema -> string + # - iso8601 -> string # --> - # This method is equivalent to strftime('%F'). + # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand + # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) + # `'%F'`); # + # Date.new(2001, 2, 3).iso8601 # => "2001-02-03" + # + # Date#xmlschema is an alias for Date#iso8601. + # def iso8601: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.italy -> date + # - italy -> new_date # --> - # This method is equivalent to new_start(Date::ITALY). + # Equivalent to Date#new_start with argument Date::ITALY. # def italy: () -> Date # <!-- # rdoc-file=ext/date/date_core.c @@ -927,68 +1155,71 @@ # def jd: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.jisx0301 -> string + # - jisx0301 -> string # --> - # Returns a string in a JIS X 0301 format. + # Returns a string representation of the date in `self` in JIS X 0301 format. # - # Date.new(2001,2,3).jisx0301 #=> "H13.02.03" + # Date.new(2001, 2, 3).jisx0301 # => "H13.02.03" # def jisx0301: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.julian -> date + # - julian -> new_date # --> - # This method is equivalent to new_start(Date::JULIAN). + # Equivalent to Date#new_start with argument Date::JULIAN. # def julian: () -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.julian? -> bool + # - d.julian? -> true or false # --> - # Returns true if the date is before the day of calendar reform. + # Returns `true` if the date is before the date of calendar reform, `false` + # otherwise: # - # Date.new(1582,10,15).julian? #=> false - # (Date.new(1582,10,15) - 1).julian? #=> true + # (Date.new(1582, 10, 15) - 1).julian? # => true + # Date.new(1582, 10, 15).julian? # => false # def julian?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.ld -> integer + # - ld -> integer # --> - # Returns the Lilian day number. This is a whole number, which is adjusted by - # the offset as the local time. + # Returns the [Lilian day number](https://en.wikipedia.org/wiki/Lilian_date), + # which is the number of days since the beginning of the Gregorian calendar, + # October 15, 1582. # - # Date.new(2001,2,3).ld #=> 152784 + # Date.new(2001, 2, 3).ld # => 152784 # def ld: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.leap? -> bool + # - leap? -> true or false # --> - # Returns true if the year is a leap year. + # Returns `true` if the year is a leap year, `false` otherwise: # - # Date.new(2000).leap? #=> true - # Date.new(2001).leap? #=> false + # Date.new(2000).leap? # => true + # Date.new(2001).leap? # => false # def leap?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.mday -> fixnum - # - d.day -> fixnum + # - mday -> integer # --> - # Returns the day of the month (1-31). + # Returns the day of the month in range (1..31): # - # Date.new(2001,2,3).mday #=> 3 + # Date.new(2001, 2, 3).mday # => 3 # + # Date#day is an alias for Date#mday. + # def mday: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c # - d.mjd -> integer @@ -1001,469 +1232,368 @@ # def mjd: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.mon -> fixnum - # - d.month -> fixnum + # - mon -> integer # --> - # Returns the month (1-12). + # Returns the month in range (1..12): # - # Date.new(2001,2,3).mon #=> 2 + # Date.new(2001, 2, 3).mon # => 2 # + # Date#month is an alias for Date#mon. + # def mon: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.monday? -> bool + # - monday? -> true or false # --> - # Returns true if the date is Monday. + # Returns `true` if `self` is a Monday, `false` otherwise. # def monday?: () -> bool # <!-- rdoc-file=ext/date/date_core.c --> - # Returns the month (1-12). + # Returns the month in range (1..12): # - # Date.new(2001,2,3).mon #=> 2 + # Date.new(2001, 2, 3).mon # => 2 # + # Date#month is an alias for Date#mon. + # def month: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.new_start([start=Date::ITALY]) -> date + # - new_start(start = Date::ITALY]) -> new_date # --> - # Duplicates self and resets its day of calendar reform. + # Returns a copy of `self` with the given `start` value: # - # d = Date.new(1582,10,15) - # d.new_start(Date::JULIAN) #=> #<Date: 1582-10-05 ...> + # d0 = Date.new(2000, 2, 3) + # d0.julian? # => false + # d1 = d0.new_start(Date::JULIAN) + # d1.julian? # => true # + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # def new_start: (?Integer start) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.succ -> date - # - d.next -> date + # - d.next -> new_date # --> - # Returns a date object denoting the following day. + # Returns a new Date object representing the following day: # + # d = Date.new(2001, 2, 3) + # d.to_s # => "2001-02-03" + # d.next.to_s # => "2001-02-04" + # + # Date#succ is an alias for Date#next. + # def next: () -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.next_day([n=1]) -> date + # - next_day(n = 1) -> new_date # --> - # This method is equivalent to d + n. + # Equivalent to Date#+ with argument `n`. # def next_day: (?Integer day) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.next_month([n=1]) -> date + # - next_month(n = 1) -> new_date # --> - # This method is equivalent to d >> n. + # Equivalent to #>> with argument `n`. # - # See Date#>> for examples. - # def next_month: (?Integer month) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.next_year([n=1]) -> date + # - next_year(n = 1) -> new_date # --> - # This method is equivalent to d >> (n * 12). + # Equivalent to #>> with argument `n * 12`. # - # Date.new(2001,2,3).next_year #=> #<Date: 2002-02-03 ...> - # Date.new(2008,2,29).next_year #=> #<Date: 2009-02-28 ...> - # Date.new(2008,2,29).next_year(4) #=> #<Date: 2012-02-29 ...> - # - # See also Date#>>. - # def next_year: (?Integer year) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.prev_day([n=1]) -> date + # - prev_day(n = 1) -> new_date # --> - # This method is equivalent to d - n. + # Equivalent to Date#- with argument `n`. # def prev_day: (?Integer day) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.prev_month([n=1]) -> date + # - prev_month(n = 1) -> new_date # --> - # This method is equivalent to d << n. + # Equivalent to #<< with argument `n`. # - # See Date#<< for examples. - # def prev_month: (?Integer month) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.prev_year([n=1]) -> date + # - prev_year(n = 1) -> new_date # --> - # This method is equivalent to d << (n * 12). + # Equivalent to #<< with argument `n * 12`. # - # Date.new(2001,2,3).prev_year #=> #<Date: 2000-02-03 ...> - # Date.new(2008,2,29).prev_year #=> #<Date: 2007-02-28 ...> - # Date.new(2008,2,29).prev_year(4) #=> #<Date: 2004-02-29 ...> - # - # See also Date#<<. - # def prev_year: (?Integer year) -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.rfc2822 -> string - # - d.rfc822 -> string + # - rfc2822 -> string # --> - # This method is equivalent to strftime('%a, %-d %b %Y %T %z'). + # Equivalent to #strftime with argument `'%a, %-d %b %Y %T %z'`; see [Formats + # for Dates and Times](rdoc-ref:strftime_formatting.rdoc): # + # Date.new(2001, 2, 3).rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # + # Date#rfc822 is an alias for Date#rfc2822. + # def rfc2822: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.rfc3339 -> string + # - rfc3339 -> string # --> - # This method is equivalent to strftime('%FT%T%:z'). + # Equivalent to #strftime with argument `'%FT%T%:z'`; see [Formats for Dates and + # Times](rdoc-ref:strftime_formatting.rdoc): # + # Date.new(2001, 2, 3).rfc3339 # => "2001-02-03T00:00:00+00:00" + # def rfc3339: () -> String # <!-- rdoc-file=ext/date/date_core.c --> - # Creates a new Date object by parsing from a string according to some typical - # RFC 2822 formats. + # Returns a new Date object with values parsed from `string`, which should be a + # valid [RFC 2822 date + # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format): # - # Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000') - # #=> #<Date: 2001-02-03 ...> + # d = Date.new(2001, 2, 3) + # s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" + # Date.rfc2822(s) # => #<Date: 2001-02-03> # - # Raise an ArgumentError when the string length is longer than *limit*. You can - # stop this check by passing `limit: nil`, but note that it may take a long time - # to parse. + # See: # + # * Argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # * Argument [limit](rdoc-ref:Date@Argument+limit). + # + # + # Date.rfc822 is an alias for Date.rfc2822. + # + # Related: Date._rfc2822 (returns a hash). + # def rfc822: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.saturday? -> bool + # - saturday? -> true or false # --> - # Returns true if the date is Saturday. + # Returns `true` if `self` is a Saturday, `false` otherwise. # def saturday?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.start -> float + # - start -> float # --> - # Returns the Julian day number denoting the day of calendar reform. + # Returns the Julian start date for calendar reform; if not an infinity, the + # returned value is suitable for passing to Date#jd: # - # Date.new(2001,2,3).start #=> 2299161.0 - # Date.new(2001,2,3,Date::GREGORIAN).start #=> -Infinity + # d = Date.new(2001, 2, 3, Date::ITALY) + # s = d.start # => 2299161.0 + # Date.jd(s).to_s # => "1582-10-15" # - def start: () -> Float - - # <!-- - # rdoc-file=ext/date/date_core.c - # - d.step(limit[, step=1]) -> enumerator - # - d.step(limit[, step=1]){|date| ...} -> self - # --> - # Iterates evaluation of the given block, which takes a date object. The limit - # should be a date object. + # d = Date.new(2001, 2, 3, Date::ENGLAND) + # s = d.start # => 2361222.0 + # Date.jd(s).to_s # => "1752-09-14" # - # Date.new(2001).step(Date.new(2001,-1,-1)).select{|d| d.sunday?}.size - # #=> 52 + # Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity + # Date.new(2001, 2, 3, Date::JULIAN).start # => Infinity # - def step: (Date limit, ?Integer step) { (Date) -> untyped } -> Date - | (Date limit, ?Integer step) -> ::Enumerator[Date, Date] + # See argument [start](rdoc-ref:calendars.rdoc@Argument+start). + # + def start: () -> Float # <!-- # rdoc-file=ext/date/date_core.c - # - d.strftime([format='%F']) -> string + # - step(limit, step = 1){|date| ... } -> self # --> - # Formats date according to the directives in the given format string. The - # directives begin with a percent (%) character. Any text not listed as a - # directive will be passed through to the output string. + # Calls the block with specified dates; returns `self`. # - # A directive consists of a percent (%) character, zero or more flags, an - # optional minimum field width, an optional modifier, and a conversion specifier - # as follows. + # * The first `date` is `self`. + # * Each successive `date` is `date + step`, where `step` is the numeric step + # size in days. + # * The last date is the last one that is before or equal to `limit`, which + # should be a Date object. # - # %<flags><width><modifier><conversion> # - # Flags: - # - don't pad a numerical output. - # _ use spaces for padding. - # 0 use zeros for padding. - # ^ upcase the result string. - # # change case. + # Example: # - # The minimum field width specifies the minimum width. + # limit = Date.new(2001, 12, 31) + # Date.new(2001).step(limit){|date| p date.to_s if date.mday == 31 } # - # The modifiers are "E", "O", ":", "::" and ":::". "E" and "O" are ignored. No - # effect to result currently. + # Output: # - # Format directives: + # "2001-01-31" + # "2001-03-31" + # "2001-05-31" + # "2001-07-31" + # "2001-08-31" + # "2001-10-31" + # "2001-12-31" # - # Date (Year, Month, Day): - # %Y - Year with century (can be negative, 4 digits at least) - # -0001, 0000, 1995, 2009, 14292, etc. - # %C - year / 100 (round down. 20 in 2009) - # %y - year % 100 (00..99) + # Returns an Enumerator if no block is given. # - # %m - Month of the year, zero-padded (01..12) - # %_m blank-padded ( 1..12) - # %-m no-padded (1..12) - # %B - The full month name (``January'') - # %^B uppercased (``JANUARY'') - # %b - The abbreviated month name (``Jan'') - # %^b uppercased (``JAN'') - # %h - Equivalent to %b + def step: (Date limit, ?Integer step) { (Date) -> untyped } -> Date + | (Date limit, ?Integer step) -> ::Enumerator[Date, Date] + + # <!-- + # rdoc-file=ext/date/date_core.c + # - strftime(format = '%F') -> string + # --> + # Returns a string representation of the date in `self`, formatted according the + # given `format`: # - # %d - Day of the month, zero-padded (01..31) - # %-d no-padded (1..31) - # %e - Day of the month, blank-padded ( 1..31) + # Date.new(2001, 2, 3).strftime # => "2001-02-03" # - # %j - Day of the year (001..366) + # For other formats, see [Formats for Dates and + # Times](rdoc-ref:strftime_formatting.rdoc). # - # Time (Hour, Minute, Second, Subsecond): - # %H - Hour of the day, 24-hour clock, zero-padded (00..23) - # %k - Hour of the day, 24-hour clock, blank-padded ( 0..23) - # %I - Hour of the day, 12-hour clock, zero-padded (01..12) - # %l - Hour of the day, 12-hour clock, blank-padded ( 1..12) - # %P - Meridian indicator, lowercase (``am'' or ``pm'') - # %p - Meridian indicator, uppercase (``AM'' or ``PM'') - # - # %M - Minute of the hour (00..59) - # - # %S - Second of the minute (00..60) - # - # %L - Millisecond of the second (000..999) - # %N - Fractional seconds digits, default is 9 digits (nanosecond) - # %3N millisecond (3 digits) %15N femtosecond (15 digits) - # %6N microsecond (6 digits) %18N attosecond (18 digits) - # %9N nanosecond (9 digits) %21N zeptosecond (21 digits) - # %12N picosecond (12 digits) %24N yoctosecond (24 digits) - # - # Time zone: - # %z - Time zone as hour and minute offset from UTC (e.g. +0900) - # %:z - hour and minute offset from UTC with a colon (e.g. +09:00) - # %::z - hour, minute and second offset from UTC (e.g. +09:00:00) - # %:::z - hour, minute and second offset from UTC - # (e.g. +09, +09:30, +09:30:30) - # %Z - Equivalent to %:z (e.g. +09:00) - # - # Weekday: - # %A - The full weekday name (``Sunday'') - # %^A uppercased (``SUNDAY'') - # %a - The abbreviated name (``Sun'') - # %^a uppercased (``SUN'') - # %u - Day of the week (Monday is 1, 1..7) - # %w - Day of the week (Sunday is 0, 0..6) - # - # ISO 8601 week-based year and week number: - # The week 1 of YYYY starts with a Monday and includes YYYY-01-04. - # The days in the year before the first week are in the last week of - # the previous year. - # %G - The week-based year - # %g - The last 2 digits of the week-based year (00..99) - # %V - Week number of the week-based year (01..53) - # - # Week number: - # The week 1 of YYYY starts with a Sunday or Monday (according to %U - # or %W). The days in the year before the first week are in week 0. - # %U - Week number of the year. The week starts with Sunday. (00..53) - # %W - Week number of the year. The week starts with Monday. (00..53) - # - # Seconds since the Unix Epoch: - # %s - Number of seconds since 1970-01-01 00:00:00 UTC. - # %Q - Number of milliseconds since 1970-01-01 00:00:00 UTC. - # - # Literal string: - # %n - Newline character (\n) - # %t - Tab character (\t) - # %% - Literal ``%'' character - # - # Combination: - # %c - date and time (%a %b %e %T %Y) - # %D - Date (%m/%d/%y) - # %F - The ISO 8601 date format (%Y-%m-%d) - # %v - VMS date (%e-%^b-%Y) - # %x - Same as %D - # %X - Same as %T - # %r - 12-hour time (%I:%M:%S %p) - # %R - 24-hour time (%H:%M) - # %T - 24-hour time (%H:%M:%S) - # %+ - date(1) (%a %b %e %H:%M:%S %Z %Y) - # - # This method is similar to the strftime() function defined in ISO C and POSIX. - # Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z) are - # locale dependent in the function. However, this method is locale independent. - # So, the result may differ even if the same format string is used in other - # systems such as C. It is good practice to avoid %x and %X because there are - # corresponding locale independent representations, %D and %T. - # - # Examples: - # - # d = DateTime.new(2007,11,19,8,37,48,"-06:00") - # #=> #<DateTime: 2007-11-19T08:37:48-0600 ...> - # d.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007" - # d.strftime("at %I:%M%p") #=> "at 08:37AM" - # - # Various ISO 8601 formats: - # %Y%m%d => 20071119 Calendar date (basic) - # %F => 2007-11-19 Calendar date (extended) - # %Y-%m => 2007-11 Calendar date, reduced accuracy, specific month - # %Y => 2007 Calendar date, reduced accuracy, specific year - # %C => 20 Calendar date, reduced accuracy, specific century - # %Y%j => 2007323 Ordinal date (basic) - # %Y-%j => 2007-323 Ordinal date (extended) - # %GW%V%u => 2007W471 Week date (basic) - # %G-W%V-%u => 2007-W47-1 Week date (extended) - # %GW%V => 2007W47 Week date, reduced accuracy, specific week (basic) - # %G-W%V => 2007-W47 Week date, reduced accuracy, specific week (extended) - # %H%M%S => 083748 Local time (basic) - # %T => 08:37:48 Local time (extended) - # %H%M => 0837 Local time, reduced accuracy, specific minute (basic) - # %H:%M => 08:37 Local time, reduced accuracy, specific minute (extended) - # %H => 08 Local time, reduced accuracy, specific hour - # %H%M%S,%L => 083748,000 Local time with decimal fraction, comma as decimal sign (basic) - # %T,%L => 08:37:48,000 Local time with decimal fraction, comma as decimal sign (extended) - # %H%M%S.%L => 083748.000 Local time with decimal fraction, full stop as decimal sign (basic) - # %T.%L => 08:37:48.000 Local time with decimal fraction, full stop as decimal sign (extended) - # %H%M%S%z => 083748-0600 Local time and the difference from UTC (basic) - # %T%:z => 08:37:48-06:00 Local time and the difference from UTC (extended) - # %Y%m%dT%H%M%S%z => 20071119T083748-0600 Date and time of day for calendar date (basic) - # %FT%T%:z => 2007-11-19T08:37:48-06:00 Date and time of day for calendar date (extended) - # %Y%jT%H%M%S%z => 2007323T083748-0600 Date and time of day for ordinal date (basic) - # %Y-%jT%T%:z => 2007-323T08:37:48-06:00 Date and time of day for ordinal date (extended) - # %GW%V%uT%H%M%S%z => 2007W471T083748-0600 Date and time of day for week date (basic) - # %G-W%V-%uT%T%:z => 2007-W47-1T08:37:48-06:00 Date and time of day for week date (extended) - # %Y%m%dT%H%M => 20071119T0837 Calendar date and local time (basic) - # %FT%R => 2007-11-19T08:37 Calendar date and local time (extended) - # %Y%jT%H%MZ => 2007323T0837Z Ordinal date and UTC of day (basic) - # %Y-%jT%RZ => 2007-323T08:37Z Ordinal date and UTC of day (extended) - # %GW%V%uT%H%M%z => 2007W471T0837-0600 Week date and local time and difference from UTC (basic) - # %G-W%V-%uT%R%:z => 2007-W47-1T08:37-06:00 Week date and local time and difference from UTC (extended) - # - # See also strftime(3) and ::strptime. - # def strftime: (?String format) -> String # <!-- rdoc-file=ext/date/date_core.c --> - # Returns a date object denoting the following day. + # Returns a new Date object representing the following day: # + # d = Date.new(2001, 2, 3) + # d.to_s # => "2001-02-03" + # d.next.to_s # => "2001-02-04" + # + # Date#succ is an alias for Date#next. + # def succ: () -> Date # <!-- # rdoc-file=ext/date/date_core.c - # - d.sunday? -> bool + # - sunday? -> true or false # --> - # Returns true if the date is Sunday. + # Returns `true` if `self` is a Sunday, `false` otherwise. # def sunday?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.thursday? -> bool + # - thursday? -> true or false # --> - # Returns true if the date is Thursday. + # Returns `true` if `self` is a Thursday, `false` otherwise. # def thursday?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.to_date -> self + # - to_date -> self # --> - # Returns self. + # Returns `self`. # def to_date: () -> Date # <!-- # rdoc-file=ext/date/date_core.c # - d.to_datetime -> datetime # --> - # Returns a DateTime object which denotes self. + # Returns a DateTime whose value is the same as `self`: # + # Date.new(2001, 2, 3).to_datetime # => #<DateTime: 2001-02-03T00:00:00+00:00> + # def to_datetime: () -> DateTime # <!-- # rdoc-file=ext/date/date_core.c - # - d.to_s -> string + # - to_s -> string # --> - # Returns a string in an ISO 8601 format. (This method doesn't use the expanded - # representations.) + # Returns a string representation of the date in `self` in [ISO 8601 extended + # date format](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications) + # (`'%Y-%m-%d'`): # - # Date.new(2001,2,3).to_s #=> "2001-02-03" + # Date.new(2001, 2, 3).to_s # => "2001-02-03" # def to_s: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.to_time -> time + # - to_time -> time # --> - # Returns a Time object which denotes self. If self is a julian date, convert it - # to a gregorian date before converting it to Time. + # Returns a new Time object with the same value as `self`; if `self` is a Julian + # date, derives its Gregorian date for conversion to the Time object: # + # Date.new(2001, 2, 3).to_time # => 2001-02-03 00:00:00 -0600 + # Date.new(2001, 2, 3, Date::JULIAN).to_time # => 2001-02-16 00:00:00 -0600 + # def to_time: () -> Time # <!-- # rdoc-file=ext/date/date_core.c - # - d.tuesday? -> bool + # - tuesday? -> true or false # --> - # Returns true if the date is Tuesday. + # Returns `true` if `self` is a Tuesday, `false` otherwise. # def tuesday?: () -> bool # <!-- # rdoc-file=ext/date/date_core.c - # - d.upto(max) -> enumerator - # - d.upto(max){|date| ...} -> self + # - upto(max){|date| ... } -> self # --> - # This method is equivalent to step(max, 1){|date| ...}. + # Equivalent to #step with arguments `max` and `1`. # def upto: (Date max) { (Date) -> untyped } -> Date | (Date max) -> ::Enumerator[Date, Date] # <!-- # rdoc-file=ext/date/date_core.c - # - d.wday -> fixnum + # - wday -> integer # --> - # Returns the day of week (0-6, Sunday is zero). + # Returns the day of week in range (0..6); Sunday is 0: # - # Date.new(2001,2,3).wday #=> 6 + # Date.new(2001, 2, 3).wday # => 6 # def wday: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.wednesday? -> bool + # - wednesday? -> true or false # --> - # Returns true if the date is Wednesday. + # Returns `true` if `self` is a Wednesday, `false` otherwise. # def wednesday?: () -> bool # <!-- rdoc-file=ext/date/date_core.c --> - # This method is equivalent to strftime('%F'). + # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand + # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers) + # `'%F'`); # + # Date.new(2001, 2, 3).iso8601 # => "2001-02-03" + # + # Date#xmlschema is an alias for Date#iso8601. + # def xmlschema: () -> String # <!-- # rdoc-file=ext/date/date_core.c - # - d.yday -> fixnum + # - yday -> integer # --> - # Returns the day of the year (1-366). + # Returns the day of the year, in range (1..366): # - # Date.new(2001,2,3).yday #=> 34 + # Date.new(2001, 2, 3).yday # => 34 # def yday: () -> Integer # <!-- # rdoc-file=ext/date/date_core.c - # - d.year -> integer + # - year -> integer # --> - # Returns the year. + # Returns the year: # - # Date.new(2001,2,3).year #=> 2001 - # (Date.new(1,1,1) - 1).year #=> 0 + # Date.new(2001, 2, 3).year # => 2001 + # (Date.new(1, 1, 1) - 1).year # => 0 # def year: () -> Integer end # <!-- rdoc-file=ext/date/date_core.c -->