- Inheritance
- < Object
- Included Modules
- Comparable
Class representing a date.
See the documentation to the file date.rb for an overview.
Internally, the date is represented as an Astronomical Julian Day Number, ajd. The Day of Calendar Reform, sg, is also stored, for conversions to other date formats. (There is also an of field for a time zone offset, but this is only for the use of the DateTime subclass.)
A new Date object is created using one of the object creation class methods named after the corresponding date format, and the arguments appropriate to that date format; for instance, Date::civil() (aliased to Date::new()) with year, month, and day-of-month, or Date::ordinal() with year and day-of-year. All of these object creation class methods also take the Day of Calendar Reform as an optional argument.
Date objects are immutable once created.
Once a Date has been created, date values can be retrieved for the different date formats supported using instance methods. For instance, mon() gives the Civil month, cwday() gives the Commercial day of the week, and yday() gives the Ordinal day of the year. Date values can be retrieved in any format, regardless of what format was used to create the Date instance.
The Date class includes the Comparable module, allowing date objects to be compared and sorted, ranges of dates to be created, and so forth.
Constants
| Name | Description | |
|---|---|---|
| ABBR_DAYNAMES | = %w(Sun Mon Tue Wed Thu Fri Sat) | Abbreviated day names, in English. |
| ABBR_MONTHNAMES | = [nil] + %w(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec) | Abbreviated month names, in English. |
| DAYNAMES | = %w(Sunday Monday Tuesday Wednesday Thursday Friday Saturday) | Full names of days of the week, in English. Days of the week count from 0 to 6 (except in the commercial week); a day‘s numerical representation indexed into this array gives the name of that day. |
| ENGLAND | = 2361222 | The Julian Day Number of the Day of Calendar Reform for England and her Colonies. |
| GREGORIAN | = -Infinity.new | A constant used to indicate that a Date should always use the Gregorian calendar. |
| ITALY | = 2299161 | The Julian Day Number of the Day of Calendar Reform for Italy and the Catholic countries. |
| JULIAN | = Infinity.new | A constant used to indicate that a Date should always use the Julian calendar. |
| MONTHNAMES | = [nil] + %w(January February March April May June July August September October November December) | Full month names, in English. Months count from 1 to 12; a month‘s numerical representation indexed into this array gives the name of that month (hence the first element is nil). |
Aliases
| Method | Alias | Description |
|---|---|---|
| civil | → new | |
| gregorian_leap? | → leap? | |
| new | → new! | |
| valid_civil? | → valid_date? |
Methods
Class
| Visibility | Signature |
|---|---|
| public | _load (str) |
| public | _parse (str, comp=false) |
| public | _strptime (str, fmt='%F') |
| public | ajd_to_amjd (ajd) |
| public | ajd_to_jd (ajd, of=0) |
| public | amjd_to_ajd (amjd) |
| public | civil (y=-4712, m=1, d=1, sg=ITALY) |
| public | civil_to_jd (y, m, d, sg=GREGORIAN) |
| public | commercial (y=1582, w=41, d=5, sg=ITALY) |
| public | commercial_to_jd (y, w, d, ns=GREGORIAN) |
| public | day_fraction_to_time (fr) |
| public | gregorian? (jd, sg) |
| public | gregorian_leap? (y) |
| public | jd (jd=0, sg=ITALY) |
| public | jd_to_ajd (jd, fr, of=0) |
| public | jd_to_civil (jd, sg=GREGORIAN) |
| public | jd_to_commercial (jd, sg=GREGORIAN) |
| public | jd_to_ld (jd) |
| public | jd_to_mjd (jd) |
| public | jd_to_ordinal (jd, sg=GREGORIAN) |
| public | jd_to_wday (jd) |
| public | julian? (jd, sg) |
| public | julian_leap? (y) |
| public | ld_to_jd (ld) |
| public | mjd_to_jd (mjd) |
| public | new (ajd=0, of=0, sg=ITALY) |
| public | ordinal (y=-4712, d=1, sg=ITALY) |
| public | ordinal_to_jd (y, d, sg=GREGORIAN) |
| public | parse (str='-4712-01-01', comp=false, sg=ITALY) |
| public | strptime (str='-4712-01-01', fmt='%F', sg=ITALY) |
| public | time_to_day_fraction (h, min, s) |
| public | time_to_day_fraction (h, min, s) |
| public | today (sg=ITALY) |
| public | valid_civil? (y, m, d, sg=ITALY) |
| public | valid_commercial? (y, w, d, sg=ITALY) |
| public | valid_jd? (jd, sg=ITALY) |
| public | valid_ordinal? (y, d, sg=ITALY) |
| public | valid_time? (h, min, s) |
Instance
| Visibility | Signature |
|---|---|
| public | + (n) |
| public | - (x) |
| public | << (n) |
| public | <=> (other) |
| public | === (other) |
| public | >> (n) |
| public | _dump (limit) |
| public | ajd () |
| public | amjd () |
| public | asctime () |
| public | ctime () |
| public | cwday () |
| public | cweek () |
| public | cwyear () |
| public | day () |
| public | day_fraction () |
| public | downto (min) {|date| ...} |
| public | england () |
| public | eql? (other) |
| public | gregorian () |
| public | gregorian? () |
| public | hash () |
| public | inspect () |
| public | italy () |
| public | jd () |
| public | julian () |
| public | julian? () |
| public | ld () |
| public | leap? () |
| public | mday () |
| public | mjd () |
| public | mon () |
| public | month () |
| public | new_start (sg=self.class::ITALY) |
| public | next () |
| public | start () |
| public | step (limit, step=1) {|date| ...} |
| public | strftime (fmt='%F') |
| public | succ () |
| public | to_s () |
| public | to_yaml ( opts = {} ) |
| public | upto (max) {|date| ...} |
| public | wday () |
| public | yday () |
| public | year () |
Class Method Detail
_load(str)
Load from Marshal format.
_parse(str, comp=false)
_strptime(str, fmt='%F')
ajd_to_amjd(ajd)
Convert an Astronomical Julian Day Number to an Astronomical Modified Julian Day Number.
ajd_to_jd(ajd, of=0)
Convert an Astronomical Julian Day Number to a (civil) Julian Day Number.
ajd is the Astronomical Julian Day Number to convert. of is the offset from UTC as a fraction of a day (defaults to 0).
Returns the (civil) Julian Day Number as [day_number, fraction] where fraction is always 1/2.
amjd_to_ajd(amjd)
Convert an Astronomical Modified Julian Day Number to an Astronomical Julian Day Number.
civil(y=-4712, m=1, d=1, sg=ITALY)
Create a new Date object for the Civil Date specified by year y, month m, and day-of-month d.
m and d can be negative, in which case they count backwards from the end of the year and the end of the month respectively. No wraparound is performed, however, and invalid values cause an ArgumentError to be raised. can be negative
y defaults to -4712, m to 1, and d to 1; this is Julian Day Number day 0.
sg specifies the Day of Calendar Reform.
civil_to_jd(y, m, d, sg=GREGORIAN)
Convert a Civil Date to a Julian Day Number. y, m, and d are the year, month, and day of the month. sg specifies the Day of Calendar Reform.
Returns the corresponding Julian Day Number.
commercial(y=1582, w=41, d=5, sg=ITALY)
Create a new Date object for the Commercial Date specified by year y, week-of-year w, and day-of-week d.
Monday is day-of-week 1; Sunday is day-of-week 7.
w and d can be negative, in which case they count backwards from the end of the year and the end of the week respectively. No wraparound is performed, however, and invalid values cause an ArgumentError to be raised.
y defaults to 1582, w to 41, and d to 5, the Day of Calendar Reform for Italy and the Catholic countries.
sg specifies the Day of Calendar Reform.
commercial_to_jd(y, w, d, ns=GREGORIAN)
Convert a Commercial Date to a Julian Day Number.
y, w, and d are the (commercial) year, week of the year, and day of the week of the Commercial Date to convert. sg specifies the Day of Calendar Reform.
day_fraction_to_time(fr)
Convert a fractional day fr to [hours, minutes, seconds, fraction_of_a_second]
gregorian?(jd, sg)
Does a given Julian Day Number fall inside the new-style (Gregorian) calendar?
The reverse of self.os? See the documentation for that method for more details.
gregorian_leap?(y)
Is a year a leap year in the Gregorian calendar?
All years divisible by 4 are leap years in the Gregorian calendar, except for years divisible by 100 and not by 400.
jd(jd=0, sg=ITALY)
Create a new Date object from a Julian Day Number.
jd is the Julian Day Number; if not specified, it defaults to 0. sg specifies the Day of Calendar Reform.
jd_to_ajd(jd, fr, of=0)
Convert a (civil) Julian Day Number to an Astronomical Julian Day Number.
jd is the Julian Day Number to convert, and fr is a fractional day. of is the offset from UTC as a fraction of a day (defaults to 0).
Returns the Astronomical Julian Day Number as a single numeric value.
jd_to_civil(jd, sg=GREGORIAN)
Convert a Julian Day Number to a Civil Date. jd is the Julian Day Number. sg specifies the Day of Calendar Reform.
Returns the corresponding [year, month, day_of_month] as a three-element array.
jd_to_commercial(jd, sg=GREGORIAN)
Convert a Julian Day Number to a Commercial Date
jd is the Julian Day Number to convert. sg specifies the Day of Calendar Reform.
Returns the corresponding Commercial Date as [commercial_year, week_of_year, day_of_week]
jd_to_ld(jd)
Convert a Julian Day Number to the number of days since the adoption of the Gregorian Calendar (in Italy).
jd_to_mjd(jd)
Convert a Julian Day Number to a Modified Julian Day Number.
jd_to_ordinal(jd, sg=GREGORIAN)
Convert a Julian Day Number to an Ordinal Date.
jd is the Julian Day Number to convert. sg specifies the Day of Calendar Reform.
Returns the corresponding Ordinal Date as [year, day_of_year]
jd_to_wday(jd)
Convert a Julian Day Number to the day of the week.
julian?(jd, sg)
Does a given Julian Day Number fall inside the old-style (Julian) calendar?
jd is the Julian Day Number in question. sg may be Date::GREGORIAN, in which case the answer is false; it may be Date::JULIAN, in which case the answer is true; or it may a number representing the Day of Calendar Reform. Date::ENGLAND and Date::ITALY are two possible such days.
julian_leap?(y)
Is a year a leap year in the Julian calendar?
All years divisible by 4 are leap years in the Julian calendar.
ld_to_jd(ld)
Convert a count of the number of days since the adoption of the Gregorian Calendar (in Italy) to a Julian Day Number.
mjd_to_jd(mjd)
Convert a Modified Julian Day Number to a Julian Day Number.
new(ajd=0, of=0, sg=ITALY)
NOTE this is the documentation for the method new!(). If you are reading this as the documentation for new(), that is because rdoc doesn‘t fully support the aliasing of the initialize() method. new() is in fact an alias for civil(): read the documentation for that method instead.
ajd is the Astronomical Julian Day Number. of is the offset from UTC as a fraction of a day. Both default to 0.
sg specifies the Day of Calendar Reform to use for this Date object.
Using one of the factory methods such as Date::civil is generally easier and safer.
ordinal(y=-4712, d=1, sg=ITALY)
Create a new Date object from an Ordinal Date, specified by year y and day-of-year d. d can be negative, in which it counts backwards from the end of the year. No year wraparound is performed, however. An invalid value for d results in an ArgumentError being raised.
y defaults to -4712, and d to 1; this is Julian Day Number day 0.
sg specifies the Day of Calendar Reform.
ordinal_to_jd(y, d, sg=GREGORIAN)
Convert an Ordinal Date to a Julian Day Number.
y and d are the year and day-of-year to convert. sg specifies the Day of Calendar Reform.
Returns the corresponding Julian Day Number.
parse(str='-4712-01-01', comp=false, sg=ITALY)
Create a new Date object by parsing from a String, without specifying the format.
str is a String holding a date representation. comp specifies whether to interpret 2-digit years as 19XX (>= 69) or 20XX (< 69); the default is not to. The method will attempt to parse a date from the String using various heuristics; see _parse in date/format.rb for more details. If parsing fails, an ArgumentError will be raised.
The default str is ’-4712-01-01’; this is Julian Day Number day 0.
sg specifies the Day of Calendar Reform.
strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
Create a new Date object by parsing from a String according to a specified format.
str is a String holding a date representation. fmt is the format that the date is in. See date/format.rb for details on supported formats.
The default str is ’-4712-01-01’, and the default fmt is ’%F’, which means Year-Month-Day_of_Month. This gives Julian Day Number day 0.
sg specifies the Day of Calendar Reform.
An ArgumentError will be raised if str cannot be parsed.
time_to_day_fraction(h, min, s)
time_to_day_fraction(h, min, s)
today(sg=ITALY)
valid_civil?(y, m, d, sg=ITALY)
Do year y, month m, and day-of-month d make a valid Civil Date? Returns the corresponding Julian Day Number if they do, nil if they don‘t.
m and d can be negative, in which case they count backwards from the end of the year and the end of the month respectively. No wraparound is performed, however, and invalid values cause an ArgumentError to be raised. A date falling in the period skipped in the Day of Calendar Reform adjustment is not valid.
sg specifies the Day of Calendar Reform.
valid_commercial?(y, w, d, sg=ITALY)
Do year y, week-of-year w, and day-of-week d make a valid Commercial Date? Returns the corresponding Julian Day Number if they do, nil if they don‘t.
Monday is day-of-week 1; Sunday is day-of-week 7.
w and d can be negative, in which case they count backwards from the end of the year and the end of the week respectively. No wraparound is performed, however, and invalid values cause an ArgumentError to be raised. A date falling in the period skipped in the Day of Calendar Reform adjustment is not valid.
sg specifies the Day of Calendar Reform.
valid_jd?(jd, sg=ITALY)
Is jd a valid Julian Day Number?
If it is, returns it. In fact, any value is treated as a valid Julian Day Number.
valid_ordinal?(y, d, sg=ITALY)
Do the year y and day-of-year d make a valid Ordinal Date? Returns the corresponding Julian Day Number if they do, or nil if they don‘t.
d can be a negative number, in which case it counts backwards from the end of the year (-1 being the last day of the year). No year wraparound is performed, however, so valid values of d are -365 .. -1, 1 .. 365 on a non-leap-year, -366 .. -1, 1 .. 366 on a leap year. A date falling in the period skipped in the Day of Calendar Reform adjustment is not valid.
sg specifies the Day of Calendar Reform.
valid_time?(h, min, s)
Do hour h, minute min, and second s constitute a valid time?
If they do, returns their value as a fraction of a day. If not, returns nil.
The 24-hour clock is used. Negative values of h, min, and sec are treating as counting backwards from the end of the next larger unit (e.g. a min of -2 is treated as 58). No wraparound is performed.
Instance Method Detail
+(n)
Return a new Date object that is n days later than the current one.
n may be a negative value, in which case the new Date is earlier than the current one; however, #-() might be more intuitive.
If n is not a Numeric, a TypeError will be thrown. In particular, two Dates cannot be added to each other.
-(x)
If x is a Numeric value, create a new Date object that is x days earlier than the current one.
If x is a Date, return the number of days between the two dates; or, more precisely, how many days later the current date is than x.
<<(n)
Return a new Date object that is n months earlier than the current one.
If the day-of-the-month of the current Date is greater than the last day of the target month, the day-of-the-month of the returned Date will be the last day of the target month.
<=>(other)
Compare this date with another date.
other can also be a Numeric value, in which case it is interpreted as an Astronomical Julian Day Number.
Comparison is by Astronomical Julian Day Number, including fractional days. This means that both the time and the timezone offset are taken into account when comparing two DateTime instances. When comparing a DateTime instance with a Date instance, the time of the latter will be considered as falling on midnight UTC.
===(other)
The relationship operator for Date.
Compares dates by Julian Day Number. When comparing two DateTime instances, or a DateTime with a Date, the instances will be regarded as equivalent if they fall on the same date in local time.
>>(n)
Return a new Date object that is n months later than the current one.
If the day-of-the-month of the current Date is greater than the last day of the target month, the day-of-the-month of the returned Date will be the last day of the target month.
_dump(limit)
Dump to Marshal format.
ajd()
Get the date as an Astronomical Julian Day Number.
amjd()
Get the date as an Astronomical Modified Julian Day Number.
asctime()
alias_method :format, :strftime
ctime()
Alias for asctime
cwday()
Get the commercial day of the week of this date. Monday is commercial day-of-week 1; Sunday is commercial day-of-week 7.
cweek()
Get the commercial week of the year of this date.
cwyear()
Get the commercial year of this date. See Commercial Date in the introduction for how this differs from the normal year.
day()
Alias for mday
day_fraction()
Get any fractional day part of the date.
downto(min) {|date| ...}
Step backward one day at a time until we reach min (inclusive), yielding each date as we go.
england()
Create a copy of this Date object that uses the English/Colonial Day of Calendar Reform.
eql?(other)
gregorian()
Create a copy of this Date object that always uses the Gregorian Calendar.
gregorian?()
Is the current date new-style (Gregorian Calendar)?
hash()
Calculate a hash value for this date.
inspect()
Return internal object state as a programmer-readable string.
italy()
Create a copy of this Date object that uses the Italian/Catholic Day of Calendar Reform.
jd()
Get the date as a Julian Day Number.
julian()
Create a copy of this Date object that always uses the Julian Calendar.
julian?()
Is the current date old-style (Julian Calendar)?
ld()
Get the date as the number of days since the Day of Calendar Reform (in Italy and the Catholic countries).
leap?()
Is this a leap year?
mday()
mjd()
Get the date as a Modified Julian Day Number.
mon()
month()
Alias for mon
new_start(sg=self.class::ITALY)
next()
start()
When is the Day of Calendar Reform for this Date object?
step(limit, step=1) {|date| ...}
Step the current date forward step days at a time (or backward, if step is negative) until we reach limit (inclusive), yielding the resultant date at each step.
strftime(fmt='%F')
succ()
Alias for next
to_s()
Return the date as a human-readable string.
The format used is YYYY-MM-DD.
to_yaml( opts = {} )
upto(max) {|date| ...}
Step forward one day at a time until we reach max (inclusive), yielding each date as we go.
wday()
yday()
year()
Get the year of this date.