Class: Date

Inherits:
Object show all
Includes:
DateAndTime::Calculations, DateAndTime::Zones
Defined in:
lib/active_support/core_ext/date/blank.rb,
lib/active_support/core_ext/date/zones.rb,
lib/active_support/core_ext/object/json.rb,
lib/active_support/core_ext/date/acts_like.rb,
lib/active_support/core_ext/date/conversions.rb,
lib/active_support/core_ext/date/calculations.rb,
lib/active_support/core_ext/date/deprecated_conversions.rb

Overview

:nodoc:

Constant Summary collapse

DATE_FORMATS = 
{
  short: "%d %b",
  long: "%B %d, %Y",
  db: "%Y-%m-%d",
  inspect: "%Y-%m-%d",
  number: "%Y%m%d",
  long_ordinal: lambda { |date|
    day_format = ActiveSupport::Inflector.ordinalize(date.day)
    date.strftime("%B #{day_format}, %Y") # => "April 25th, 2007"
  },
  rfc822: "%d %b %Y",
  iso8601: lambda { |date| date.iso8601 }
}
NOT_SET =

:nodoc:

Object.new

Constants included from DateAndTime::Calculations

DateAndTime::Calculations::DAYS_INTO_WEEK, DateAndTime::Calculations::WEEKEND_DAYS

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from DateAndTime::Calculations

#after?, #all_day, #all_month, #all_quarter, #all_week, #all_year, #before?, #beginning_of_month, #beginning_of_quarter, #beginning_of_week, #beginning_of_year, #days_ago, #days_since, #days_to_week_start, #end_of_month, #end_of_quarter, #end_of_week, #end_of_year, #future?, #last_month, #last_year, #monday, #months_ago, #months_since, #next_occurring, #next_quarter, #next_week, #next_weekday, #on_weekday?, #on_weekend?, #past?, #prev_occurring, #prev_quarter, #prev_week, #prev_weekday, #sunday, #today?, #tomorrow, #tomorrow?, #weeks_ago, #weeks_since, #years_ago, #years_since, #yesterday, #yesterday?

Methods included from DateAndTime::Zones

#in_time_zone

Class Attribute Details

.beginning_of_week_default ⇒ Object

Returns the value of attribute beginning_of_week_default.



14
15
16
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 14

def beginning_of_week_default
  @beginning_of_week_default
end

Class Method Details

.beginning_of_week ⇒ Object

Returns the week start (e.g. :monday) for the current request, if this has been set (via Date.beginning_of_week=). If Date.beginning_of_week has not been set for the current request, returns the week start specified in config.beginning_of_week. If no config.beginning_of_week was specified, returns :monday.



19
20
21
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 19

def beginning_of_week
  ::ActiveSupport::IsolatedExecutionState[:beginning_of_week] || beginning_of_week_default || :monday
end

.beginning_of_week=(week_start) ⇒ Object

Sets Date.beginning_of_week to a week start (e.g. :monday) for current request/thread.

This method accepts any of the following day symbols: :monday, :tuesday, :wednesday, :thursday, :friday, :saturday, :sunday



27
28
29
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 27

def beginning_of_week=(week_start)
  ::ActiveSupport::IsolatedExecutionState[:beginning_of_week] = find_beginning_of_week!(week_start)
end

.current ⇒ Object

Returns Time.zone.today when Time.zone or config.time_zone are set, otherwise just returns Date.today.



48
49
50
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 48

def current
  ::Time.zone ? ::Time.zone.today : ::Date.today
end

.find_beginning_of_week!(week_start) ⇒ Object

Returns week start day symbol (e.g. :monday), or raises an ArgumentError for invalid day symbol.

Raises:

  • (ArgumentError) 


32
33
34
35
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 32

def find_beginning_of_week!(week_start)
  raise ArgumentError, "Invalid beginning of week: #{week_start}" unless ::Date::DAYS_INTO_WEEK.key?(week_start)
  week_start
end

.tomorrow ⇒ Object

Returns a new Date representing the date 1 day after today (i.e. tomorrow’s date).



43
44
45
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 43

def tomorrow
  ::Date.current.tomorrow
end

.yesterday ⇒ Object

Returns a new Date representing the date 1 day ago (i.e. yesterday’s date).



38
39
40
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 38

def yesterday
  ::Date.current.yesterday
end

Instance Method Details

#acts_like_date? ⇒ Boolean

Duck-types as a Date-like class. See Object#acts_like?.

Returns:

  • (Boolean) 


7
8
9
 
# File 'lib/active_support/core_ext/date/acts_like.rb', line 7

def acts_like_date?
  true
end

#advance(options) ⇒ Object

Provides precise Date calculations for years, months, and days. The options parameter takes a hash with any of these keys: :years, :months, :weeks, :days.

The increments are applied in order of time units from largest to smallest. In other words, the date is incremented first by :years, then by :months, then by :weeks, then by :days. This order can affect the result around the end of a month. For example, incrementing first by months then by days:

Date.new(2004, 9, 30).advance(months: 1, days: 1)
# => Sun, 31 Oct 2004

Whereas incrementing first by days then by months yields a different result:

Date.new(2004, 9, 30).advance(days: 1).advance(months: 1)
# => Mon, 01 Nov 2004



127
128
129
130
131
132
133
134
135
136
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 127

def advance(options)
  d = self

  d = d >> options[:years] * 12 if options[:years]
  d = d >> options[:months] if options[:months]
  d = d + options[:weeks] * 7 if options[:weeks]
  d = d + options[:days] if options[:days]

  d
end

#ago(seconds) ⇒ Object

Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00) and then subtracts the specified number of seconds.



55
56
57
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 55

def ago(seconds)
  in_time_zone.since(-seconds)
end

#as_json(options = nil) ⇒ Object

:nodoc:



197
198
199
200
201
202
203
 
# File 'lib/active_support/core_ext/object/json.rb', line 197

def as_json(options = nil) # :nodoc:
  if ActiveSupport::JSON::Encoding.use_standard_json_time_format
    strftime("%Y-%m-%d")
  else
    strftime("%Y/%m/%d")
  end
end

#beginning_of_day ⇒ Object Also known as: midnight, at_midnight, at_beginning_of_day

Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)



67
68
69
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 67

def beginning_of_day
  in_time_zone
end

#blank? ⇒ false

No Date is blank:

Date.today.blank? # => false

Returns:

  • (false) 


11
12
13
 
# File 'lib/active_support/core_ext/date/blank.rb', line 11

def blank?
  false
end

#change(options) ⇒ Object

Returns a new Date where one or more of the elements have been changed according to the options parameter. The options parameter is a hash with a combination of these keys: :year, :month, :day.

Date.new(2007, 5, 12).change(day: 1)               # => Date.new(2007, 5, 1)
Date.new(2007, 5, 12).change(year: 2005, month: 1) # => Date.new(2005, 1, 12)



143
144
145
146
147
148
149
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 143

def change(options)
  ::Date.new(
    options.fetch(:year, year),
    options.fetch(:month, month),
    options.fetch(:day, day)
  )
end

#compare_with_coercion(other) ⇒ Object Also known as: <=>

Allow Date to be compared with Time by converting to DateTime and relying on the <=> from there.



152
153
154
155
156
157
158
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 152

def compare_with_coercion(other)
  if other.is_a?(Time)
    to_datetime <=> other
  else
    compare_without_coercion(other)
  end
end

#end_of_day ⇒ Object Also known as: at_end_of_day

Converts Date to a Time (or DateTime if necessary) with the time portion set to the end of the day (23:59:59)



85
86
87
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 85

def end_of_day
  in_time_zone.end_of_day
end

#middle_of_day ⇒ Object Also known as: midday, noon, at_midday, at_noon, at_middle_of_day

Converts Date to a Time (or DateTime if necessary) with the time portion set to the middle of the day (12:00)



75
76
77
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 75

def middle_of_day
  in_time_zone.middle_of_day
end

#minus_with_duration(other) ⇒ Object Also known as: -

:nodoc:



100
101
102
103
104
105
106
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 100

def minus_with_duration(other) # :nodoc:
  if ActiveSupport::Duration === other
    plus_with_duration(-other)
  else
    minus_without_duration(other)
  end
end

#plus_with_duration(other) ⇒ Object Also known as: +

:nodoc:



90
91
92
93
94
95
96
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 90

def plus_with_duration(other) # :nodoc:
  if ActiveSupport::Duration === other
    other.since(self)
  else
    plus_without_duration(other)
  end
end

#readable_inspect ⇒ Object Also known as: inspect

Overrides the default inspect method with a human readable one, e.g., “Mon, 21 Feb 2005”



62
63
64
 
# File 'lib/active_support/core_ext/date/conversions.rb', line 62

def readable_inspect
  strftime("%a, %d %b %Y")
end

#since(seconds) ⇒ Object Also known as: in

Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00) and then adds the specified number of seconds



61
62
63
 
# File 'lib/active_support/core_ext/date/calculations.rb', line 61

def since(seconds)
  in_time_zone.since(seconds)
end

#to_default_s ⇒ Object 



59
 
# File 'lib/active_support/core_ext/date/conversions.rb', line 59

alias_method :to_default_s, :to_s

#to_fs(format = :default) ⇒ Object Also known as: to_formatted_s

Convert to a formatted string. See DATE_FORMATS for predefined formats.

This method is aliased to to_formatted_s.

date = Date.new(2007, 11, 10)       # => Sat, 10 Nov 2007

date.to_fs(:db)                     # => "2007-11-10"
date.to_formatted_s(:db)            # => "2007-11-10"

date.to_fs(:short)         # => "10 Nov"
date.to_fs(:number)        # => "20071110"
date.to_fs(:long)          # => "November 10, 2007"
date.to_fs(:long_ordinal)  # => "November 10th, 2007"
date.to_fs(:rfc822)        # => "10 Nov 2007"
date.to_fs(:iso8601)       # => "2007-11-10"

Adding your own date formats to to_fs

You can add your own formats to the Date::DATE_FORMATS hash. Use the format name as the hash key and either a strftime string or Proc instance that takes a date argument as the value.

# config/initializers/date_formats.rb
Date::DATE_FORMATS[:month_and_year] = '%B %Y'
Date::DATE_FORMATS[:short_ordinal] = ->(date) { date.strftime("%B #{date.day.ordinalize}") }



47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/active_support/core_ext/date/conversions.rb', line 47

def to_fs(format = :default)
  if formatter = DATE_FORMATS[format]
    if formatter.respond_to?(:call)
      formatter.call(self).to_s
    else
      strftime(formatter)
    end
  else
    to_default_s
  end
end

#to_s(format = NOT_SET) ⇒ Object

:nodoc:



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/active_support/core_ext/date/deprecated_conversions.rb', line 7

def to_s(format = NOT_SET) # :nodoc:
  if formatter = DATE_FORMATS[format]
    ActiveSupport::Deprecation.warn(
      "Date#to_s(#{format.inspect}) is deprecated. Please use Date#to_fs(#{format.inspect}) instead."
    )
    if formatter.respond_to?(:call)
      formatter.call(self).to_s
    else
      strftime(formatter)
    end
  elsif format == NOT_SET
    if formatter = DATE_FORMATS[:default]
      ActiveSupport::Deprecation.warn(<<-MSG.squish)
        Using a :default format for Date#to_s is deprecated. Please use Date#to_fs instead. If you fixed all places
        inside your application that you see this deprecation, you can set
        `ENV['RAILS_DISABLE_DEPRECATED_TO_S_CONVERSION']` to `"true"` in the `config/application.rb` file before
        the `Bundler.require` call to fix all the callers outside of your application.
      MSG
      if formatter.respond_to?(:call)
        formatter.call(self).to_s
      else
        strftime(formatter)
      end
    else
      to_default_s
    end
  else
    ActiveSupport::Deprecation.warn(
      "Date#to_s(#{format.inspect}) is deprecated. Please use Date#to_fs(#{format.inspect}) instead."
    )
    to_default_s
  end
end

#to_time(form = :local) ⇒ Object

Converts a Date instance to a Time, where the time is set to the beginning of the day. The timezone can be either :local or :utc (default :local).

date = Date.new(2007, 11, 10)  # => Sat, 10 Nov 2007

date.to_time                   # => 2007-11-10 00:00:00 0800
date.to_time(:local)           # => 2007-11-10 00:00:00 0800

date.to_time(:utc)             # => 2007-11-10 00:00:00 UTC

NOTE: The :local timezone is Ruby’s process timezone, i.e. ENV['TZ']. If the application’s timezone is needed, then use in_time_zone instead.

Raises:

  • (ArgumentError) 


82
83
84
85
 
# File 'lib/active_support/core_ext/date/conversions.rb', line 82

def to_time(form = :local)
  raise ArgumentError, "Expected :local or :utc, got #{form.inspect}." unless [:local, :utc].include?(form)
  ::Time.public_send(form, year, month, day)
end

#xmlschema ⇒ Object

Returns a string which represents the time in used time zone as DateTime defined by XML Schema:

date = Date.new(2015, 05, 23)  # => Sat, 23 May 2015
date.xmlschema                 # => "2015-05-23T00:00:00+04:00"



94
95
96
 
# File 'lib/active_support/core_ext/date/conversions.rb', line 94

def xmlschema
  in_time_zone.xmlschema
end