Class: Date

Inherits:
Object
  • Object
show all
Extended by:
FatCore::Date::ClassMethods
Includes:
FatCore::Date
Defined in:
lib/fat_core/date.rb

Utilities collapse

Parsing collapse

Relative ::Dates collapse

Federal Holidays and Workdays collapse

NYSE Holidays and Workdays collapse

Formatting collapse

Queries collapse

Class Method Details

.days_in_month(y, m) ⇒ Object Originally defined in module FatCore::Date::ClassMethods

Raises:

  • (ArgumentError)

.easter(year) ⇒ ::Date Originally defined in module FatCore::Date::ClassMethods

Return the date of Easter for the Western Church in the given year.

Parameters:

  • year (Integer) —

    the year of interest

Returns:

  • (::Date) —

    the date of Easter for year

.nth_wday_in_year_month(n, wday, year, month) ⇒ Object Originally defined in module FatCore::Date::ClassMethods

Return the nth weekday in the given month. If n is negative, count from last day of month.

Parameters:

  • n (Integer) —

    the ordinal number for the weekday

  • wday (Integer) —

    the weekday of interest with Monday 0 to Sunday 6

  • year (Integer) —

    the year of interest

  • month (Integer) —

    the month of interest with January 1 to December 12

Raises:

  • (ArgumentError)

.parse_american(str) ⇒ ::Date Originally defined in module FatCore::Date::ClassMethods

Convert a string +str+ with an American style date into a ::Date object

An American style date is of the form MM/DD/YYYY, that is it places the month first, then the day of the month, and finally the year. The European convention is typically to place the day of the month first, DD/MM/YYYY. A date found in the wild can be ambiguous, e.g. 3/5/2014, but a date string known to be using the American convention can be parsed using this method. Both the month and the day can be a single digit. The year can be either 2 or 4 digits, and if given as 2 digits, it adds 2000 to it to give the year.

Examples:

::Date.parse_american('9/11/2001') #=> ::Date(2011, 9, 11)
::Date.parse_american('9/11/01')   #=> ::Date(2011, 9, 11)
::Date.parse_american('9/11/1')    #=> ArgumentError

Parameters:

  • str (String, #to_s) —

    a stringling of the form MM/DD/YYYY

Returns:

  • (::Date) —

    the date represented by the str paramenter.

.parse_spec(spec, spec_type = :from) ⇒ ::Date Originally defined in module FatCore::Date::ClassMethods

Convert a 'period spec' spec to a ::Date. A date spec is a short-hand way of specifying a calendar period either absolutely or relative to the computer clock. This method returns the first date of that period, when spec_type is set to :from, the default, and returns the last date of the period when spec_type is :to.

There are a number of forms the spec can take. In each case, ::Date.parse_spec returns the first date in the period if spec_type is :from and the last date in the period if spec_type is :to:

  • YYYY is the whole year YYYY,
  • YYYY-1H or YYYY-H1 is the first calendar half in year YYYY,
  • H2 or 2H is the second calendar half of the current year,
  • YYYY-3Q or YYYY-Q3 is the third calendar quarter of year YYYY,
  • Q3 or 3Q is the third calendar quarter in the current year,
  • YYYY-04 or YYYY-4 is April, the fourth month of year YYYY,
  • 4-12 or 04-12 is the 12th of April in the current year,
  • 4 or 04 is April in the current year,
  • YYYY-W32 or YYYY-32W is the 32nd week in year YYYY,
  • W32 or 32W is the 32nd week in the current year,
  • YYYY-MM-DD a particular date, so :from and :to return the same date,
  • this_<chunk> where <chunk> is one of year, half, quarter, bimonth, month, semimonth, biweek, week, or day, the corresponding calendar period in which the current date falls,
  • last_<chunk> where <chunk> is one of year, half, quarter, bimonth, month, semimonth, biweek, week, or day, the corresponding calendar period immediately before the one in which the current date falls,
  • today is the same as this_day,
  • yesterday is the same as last_day,
  • forever is the period from ::Date::BOT to ::Date::EOT, essentially all dates of commercial interest, and
  • never causes the method to return nil.

In all of the above example specs, letter used for calendar chunks, W, Q, and H can be written in lower case as well. Also, you can use / to separate date components instead of -.

Examples:

::Date.parse_spec('2012-W32').iso      # => "2012-08-06"
::Date.parse_spec('2012-W32', :to).iso # => "2012-08-12"
::Date.parse_spec('W32').iso           # => "2012-08-06" if executed in 2012
::Date.parse_spec('W32').iso           # => "2012-08-04" if executed in 2014

Parameters:

  • spec (String, #to_s) —

    the spec to be interpreted as a calendar period

  • spec_type (:from, :to) (defaults to: :from) —

    return the first (:from) or last (:to) date in the spec's period respectively

Returns:

  • (::Date) —

    date that is the first (:from) or last (:to) in the period designated by spec

Instance Method Details

#add_chunk(chunk, n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is n chunks later than self.

Parameters:

  • chunk (Symbol) —

    one of +:year+, +:half+, +:quarter+, +:bimonth+, +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.

  • n (Integer) (defaults to: 1) —

    the number of chunks to add, can be negative

Returns:

  • (::Date) —

    the date n chunks from this date

#add_fed_workdays(n) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is n federal workdays after or before (if n < 0) this date.

Parameters:

  • n (Integer) —

    number of federal workdays to add to this date

Returns:

#add_nyse_workdays(n) ⇒ ::Date Also known as: add_trading_days Originally defined in module FatCore::Date

Return the date that is n NYSE trading days after or before (if n < 0) this date.

Parameters:

  • n (Integer) —

    number of NYSE trading days to add to this date

Returns:

#american ⇒ String Originally defined in module FatCore::Date

Format date in MM/DD/YYYY form, as typical for the short American form.

Returns:

#beginning_of_bimonth ⇒ ::Date Originally defined in module FatCore::Date

The date that is the first day of the bimonth in which self falls. A 'bimonth' is a two-month calendar period beginning on the first day of the odd-numbered months. E.g., 2014-01-01 to 2014-02-28 is the first bimonth of 2014.

Returns:

#beginning_of_bimonth? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a calendar bi-monthly period, i.e., the beginning of an odd-numbered month.

Returns:

  • (Boolean)

#beginning_of_biweek ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is the first day of the commercial biweek in which self falls. A biweek is a period of two commercial weeks starting with an odd-numbered week and with each week starting in Monday and ending on Sunday.

Returns:

#beginning_of_biweek? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a commercial bi-week, i.e., on /Monday/ in a commercial week that is an odd-numbered week. From ::Date: "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."

Returns:

  • (Boolean)

#beginning_of_chunk(chunk) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is the beginning of the +chunk+ in which this date falls.

Parameters:

  • chunk (Symbol) —

    one of +:year+, +:half+, +:quarter+, +:bimonth+, +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.

Returns:

  • (::Date) —

    the first date in the chunk-sized period in which this date falls

#beginning_of_half ⇒ ::Date Originally defined in module FatCore::Date

The date that is the first day of the half-year in which self falls.

Returns:

#beginning_of_half? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a half-year.

Returns:

  • (Boolean)

#beginning_of_month? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a calendar month.

Returns:

  • (Boolean)

#beginning_of_quarter? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a calendar quarter.

Returns:

  • (Boolean)

#beginning_of_semimonth ⇒ ::Date Originally defined in module FatCore::Date

The date that is the first day of the semimonth in which self falls. A semimonth is a calendar period beginning on the 1st or 16th of each month and ending on the 15th or last day of the month respectively. So each year has exactly 24 semimonths.

Returns:

#beginning_of_semimonth? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a calendar semi-monthly period, i.e., on the 1st or 15th of a month.

Returns:

  • (Boolean)

#beginning_of_week? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a commercial week, i.e., on /Monday/ in a commercial week. From ::Date: "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."

Returns:

  • (Boolean)

#beginning_of_year? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a year.

Returns:

  • (Boolean)

#easter? ⇒ Boolean Originally defined in module FatCore::Date

Return whether this date is Easter Sunday for the year in which it falls according to the Western Church. A few holidays key off this date as "moveable feasts."

Returns:

  • (Boolean)

#easter_this_year ⇒ ::Date Originally defined in module FatCore::Date

Return the date for Easter in the Western Church for the year in which this date falls.

Returns:

#end_of_bimonth ⇒ ::Date Originally defined in module FatCore::Date

The date that is the last day of the bimonth in which self falls. A 'bimonth' is a two-month calendar period beginning on the first day of the odd-numbered months. E.g., 2014-01-01 to 2014-02-28 is the first bimonth of 2014.

Returns:

#end_of_bimonth? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a calendar bi-monthly period, i.e., the end of an even-numbered month.

Returns:

  • (Boolean)

#end_of_biweek ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is the last day of the commercial biweek in which self falls. A biweek is a period of two commercial weeks starting with an odd-numbered week and with each week starting in Monday and ending on Sunday. So this will always return a Sunday in an even-numbered week.

Returns:

#end_of_biweek? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a commercial bi-week, i.e., on /Sunday/ in a commercial week that is an even-numbered week. From ::Date: "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."

Returns:

  • (Boolean)

#end_of_chunk(chunk) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is the end of the +chunk+ in which this date falls.

Parameters:

  • chunk (Symbol) —

    one of +:year+, +:half+, +:quarter+, +:bimonth+, +:month+, +:semimonth+, +:biweek+, +:week+, or +:day+.

Returns:

  • (::Date) —

    the first date in the chunk-sized period in which this date falls

#end_of_half ⇒ ::Date Originally defined in module FatCore::Date

The date that is the last day of the half-year in which self falls.

Returns:

#end_of_half? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a half-year.

Returns:

  • (Boolean)

#end_of_month? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a calendar month.

Returns:

  • (Boolean)

#end_of_quarter? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a calendar quarter.

Returns:

  • (Boolean)

#end_of_semimonth ⇒ ::Date Originally defined in module FatCore::Date

The date that is the last day of the semimonth in which self falls. A semimonth is a calendar period beginning on the 1st or 16th of each month and ending on the 15th or last day of the month respectively. So each year has exactly 24 semimonths.

Returns:

#end_of_semimonth? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a calendar semi-monthly period, i.e., on the 14th or the last day of a month.

Returns:

  • (Boolean)

#end_of_week? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the first day of a commercial week, i.e., on /Sunday/ in a commercial week. From ::Date: "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."

Returns:

  • (Boolean)

#end_of_year? ⇒ Boolean Originally defined in module FatCore::Date

Return whether the date falls on the last day of a year.

Returns:

  • (Boolean)

#eng ⇒ String Originally defined in module FatCore::Date

Format as an English string, like 'January 12, 2016'

Returns:

#fed_holiday? ⇒ Boolean Originally defined in module FatCore::Date

Return whether this date is a United States federal holiday.

Calculations for Federal holidays are based on 5 USC 6103, include all weekends, Presidential funerals, and holidays decreed executive orders.

Returns:

  • (Boolean)

#fed_workday? ⇒ Boolean Originally defined in module FatCore::Date

Return whether this date is a date on which the US federal government is open for business. It is the opposite of #fed_holiday?

Returns:

  • (Boolean)

#half ⇒ 1, 2 Originally defined in module FatCore::Date

Self's calendar "half" by analogy to calendar quarters: 1 or 2, depending on whether the date falls in the first or second half of the calendar year.

Returns:

  • (1, 2)

#iso ⇒ String Originally defined in module FatCore::Date

Format as an ISO string of the form YYYY-MM-DD.

Returns:

#next_bimonth(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar bimonths after this date, where a calendar bimonth is a period of 2 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of bimonths to advance, can be negative

Returns:

  • (::Date) —

    new date n bimonths after this date

#next_biweek(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ biweeks after this date where each biweek is 14 days.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of biweeks to advance, can be negative

Returns:

  • (::Date) —

    new date n biweeks after this date

#next_fed_workday ⇒ ::Date Originally defined in module FatCore::Date

Return the next federal workday after this date. The date returned is always a date at least one day after this date, never this date.

Returns:

#next_half(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar halves after this date, where a calendar half is a period of 6 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of halves to advance, can be negative

Returns:

  • (::Date) —

    new date n halves after this date

#next_nyse_workday ⇒ ::Date Also known as: next_trading_day Originally defined in module FatCore::Date

Return the next NYSE trading day after this date. The date returned is always a date at least one day after this date, never this date.

Returns:

#next_quarter(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar quarters after this date, where a calendar quarter is a period of 3 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of quarters to advance, can be negative

Returns:

  • (::Date) —

    new date n quarters after this date

#next_semimonth(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ semimonths after this date. Each semimonth begins on the 1st or 16th of the month, and advancing one semimonth from the first half of a month means to go as far past the 16th as the current date is past the 1st; advancing one semimonth from the second half of a month means to go as far into the next month past the 1st as the current date is past the 16th, but never past the 15th of the next month.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of semimonths to advance, can be negative

Returns:

  • (::Date) —

    new date n semimonths after this date

#next_until_fed_workday ⇒ ::Date Originally defined in module FatCore::Date

Return this date if its a federal workday, otherwise skip forward to the first later federal workday.

Returns:

#next_until_trading_day ⇒ ::Date Originally defined in module FatCore::Date

Return this date if its a trading day, otherwise skip forward to the first later trading day.

Returns:

#next_week(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ weeks after this date where each week is 7 days. This is different from the #next_week method in active_support, which goes to the first day of the week in the next week and does not take an argument +n+ to go multiple weeks.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of weeks to advance

Returns:

  • (::Date) —

    new date n weeks after this date

#nth_wday_in_month?(n, wday, month) ⇒ Boolean Originally defined in module FatCore::Date

Return whether this date is the nth weekday wday of the given month in this date's year.

Parameters:

  • n (Integer) —

    number of wday in month, if negative count from end of the month

  • wday (Integer) —

    day of week, 0 is Sunday, 1 Monday, etc.

  • month (Integer) —

    the month number, 1 is January, 2 is February, etc.

Returns:

  • (Boolean)

#num ⇒ String Originally defined in module FatCore::Date

Format as an all-numeric string of the form YYYYMMDD

Returns:

#nyse_holiday? ⇒ Boolean Originally defined in module FatCore::Date

Returns whether this date is one on which the NYSE was or is expected to be closed for business.

Calculations for NYSE holidays are from Rule 51 and supplementary materials for the Rules of the New York Stock Exchange, Inc.

  • General Rule 1: if a regular holiday falls on Saturday, observe it on the preceding Friday.
  • General Rule 2: if a regular holiday falls on Sunday, observe it on the following Monday.

These are the regular holidays:

  • New Year's Day, January 1.
  • Birthday of Martin Luther King, Jr., the third Monday in January.
  • Washington's Birthday, the third Monday in February.
  • Good Friday Friday before Easter Sunday. NOTE: this is not a fed holiday
  • Memorial Day, the last Monday in May.
  • Independence Day, July 4.
  • Labor Day, the first Monday in September.
  • Thanksgiving Day, the fourth Thursday in November.
  • Christmas Day, December 25.

Columbus and Veterans days not observed.

In addition, there have been several days on which the exchange has been closed for special events such as Presidential funerals, the 9-11 attacks, the paper-work crisis in the 1960's, hurricanes, etc. All of these are considered holidays for purposes of this method.

In addition, every weekend is considered a holiday.

Returns:

  • (Boolean)

#nyse_workday? ⇒ Boolean Also known as: trading_day? Originally defined in module FatCore::Date

Return whether the NYSE is open for trading on this date.

Returns:

  • (Boolean)

#org ⇒ String Originally defined in module FatCore::Date

Format as an inactive Org date timestamp of the form [YYYY-MM-DD <dow>] (see Emacs org-mode)

Returns:

#pred ⇒ ::Date Originally defined in module FatCore::Date

Predecessor of self, opposite of #succ.

Returns:

#prior_bimonth(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar bimonths before this date, where a calendar bimonth is a period of 2 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of bimonths to retreat, can be negative

Returns:

  • (::Date) —

    new date n bimonths before this date

#prior_biweek(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ biweeks before this date where each biweek is 14 days.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of biweeks to retreat, can be negative

Returns:

  • (::Date) —

    new date n biweeks before this date

#prior_day(n) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ weeks before this date where each week is 7 days.

Parameters:

  • n (Integer) —

    number of days to retreat

Returns:

  • (::Date) —

    new date n days before this date

#prior_fed_workday ⇒ ::Date Originally defined in module FatCore::Date

Return the last federal workday before this date. The date returned is always a date at least one day before this date, never this date.

Returns:

#prior_half(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar halves before this date, where a calendar half is a period of 6 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of halves to retreat, can be negative

Returns:

  • (::Date) —

    new date n halves before this date

#prior_nyse_workday ⇒ ::Date Also known as: prior_trading_day Originally defined in module FatCore::Date

Return the last NYSE trading day before this date. The date returned is always a date at least one day before this date, never this date.

Returns:

#prior_quarter(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ calendar quarters before this date, where a calendar quarter is a period of 3 months.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of quarters to retreat, can be negative

Returns:

  • (::Date) —

    new date n quarters after this date

#prior_semimonth(n = 1) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ semimonths before this date. Each semimonth begins on the 1st or 15th of the month, and retreating one semimonth from the first half of a month means to go as far past the 15th of the prior month as the current date is past the 1st; retreating one semimonth from the second half of a month means to go as far past the 1st of the current month as the current date is past the 15th, but never past the 14th of the the current month.

Parameters:

  • n (Integer) (defaults to: 1) —

    number of semimonths to retreat, can be negative

Returns:

  • (::Date) —

    new date n semimonths before this date

#prior_until_fed_workday ⇒ Object Originally defined in module FatCore::Date

Return this if its a federal workday, otherwise skip back to the first prior federal workday.

#prior_until_trading_day ⇒ ::Date Originally defined in module FatCore::Date

Return this date if its a trading day, otherwise skip back to the first prior trading day.

Returns:

#prior_week(n) ⇒ ::Date Originally defined in module FatCore::Date

Return the date that is +n+ weeks before this date where each week is 7 days.

Parameters:

  • n (Integer) —

    number of weeks to retreat

Returns:

  • (::Date) —

    new date n weeks from this date

#quarter ⇒ 1, ... Originally defined in module FatCore::Date

Self's calendar quarter: 1, 2, 3, or 4, depending on which calendar quarter the date falls in.

Returns:

  • (1, 2, 3, 4)

#tex_quote ⇒ String Originally defined in module FatCore::Date

Format date to TeX documents as ISO strings

Returns:

#weekday? ⇒ Boolean Originally defined in module FatCore::Date

Does self fall on a weekday?

Returns:

  • (Boolean)

#weekend? ⇒ Boolean Originally defined in module FatCore::Date

Does self fall on a weekend?

Returns:

  • (Boolean)

#within_6mos_of?(d) ⇒ Boolean Originally defined in module FatCore::Date

Return whether this date falls within a period of less than six months from the date d using the Stella v. Graham Page Motors convention that "less" than six months is true only if this date falls within the range of dates 2 days after date six months before and 2 days before the date six months after the date d.

Parameters:

  • d (::Date) —

    the middle of the six-month range

Returns:

  • (Boolean)