mirror of
https://github.com/rails/rails.git
synced 2022-11-09 12:12:34 -05:00
Update "Active Support Core Extensions" Guide
Remove general sentence that explains that all methods that Active Support brings to `Date` `Time`, `DateTime` are defined in `active_support/core_ext/date/calculations.rb` since it isn't true. Add a references to an appropriate file where methods are defined like it is done with the other methods in this guide. Context https://github.com/rails/rails/pull/32552#discussion_r181216246 Related to #32543, #32552 [ci skip]
This commit is contained in:
bogdanvlviv
parent
3fe81d31c3
commit
b205f47d55
1 changed files with 56 additions and 76 deletions
|
|
@ -2935,34 +2935,6 @@ Extensions to `Date`
|
|||
|
||||
### Calculations
|
||||
|
||||
NOTE: All the following methods are defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
```ruby
|
||||
yesterday
|
||||
tomorrow
|
||||
beginning_of_week (at_beginning_of_week)
|
||||
end_of_week (at_end_of_week)
|
||||
monday
|
||||
sunday
|
||||
weeks_ago
|
||||
prev_week (last_week)
|
||||
next_week
|
||||
months_ago
|
||||
months_since
|
||||
beginning_of_month (at_beginning_of_month)
|
||||
end_of_month (at_end_of_month)
|
||||
last_month
|
||||
beginning_of_quarter (at_beginning_of_quarter)
|
||||
end_of_quarter (at_end_of_quarter)
|
||||
beginning_of_year (at_beginning_of_year)
|
||||
end_of_year (at_end_of_year)
|
||||
years_ago
|
||||
years_since
|
||||
last_year
|
||||
on_weekday?
|
||||
on_weekend?
|
||||
```
|
||||
|
||||
INFO: The following calculation methods have edge cases in October 1582, since days 5..14 just do not exist. This guide does not document their behavior around those days for brevity, but it is enough to say that they do what you would expect. That is, `Date.new(1582, 10, 4).tomorrow` returns `Date.new(1582, 10, 15)` and so on. Please check `test/core_ext/date_ext_test.rb` in the Active Support test suite for expected behavior.
|
||||
|
||||
#### `Date.current`
|
||||
|
|
@ -2971,6 +2943,8 @@ Active Support defines `Date.current` to be today in the current time zone. That
|
|||
|
||||
When making Date comparisons using methods which honor the user time zone, make sure to use `Date.current` and not `Date.today`. There are cases where the user time zone might be in the future compared to the system time zone, which `Date.today` uses by default. This means `Date.today` may equal `Date.yesterday`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
#### Named dates
|
||||
|
||||
##### `beginning_of_week`, `end_of_week`
|
||||
|
|
@ -2990,6 +2964,8 @@ d.end_of_week(:sunday) # => Sat, 08 May 2010
|
|||
|
||||
`beginning_of_week` is aliased to `at_beginning_of_week` and `end_of_week` is aliased to `at_end_of_week`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `monday`, `sunday`
|
||||
|
||||
The methods `monday` and `sunday` return the dates for the previous Monday and
|
||||
|
|
@ -3007,6 +2983,8 @@ d = Date.new(2012, 9, 16) # => Sun, 16 Sep 2012
|
|||
d.sunday # => Sun, 16 Sep 2012
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `prev_week`, `next_week`
|
||||
|
||||
The method `next_week` receives a symbol with a day name in English (default is the thread local `Date.beginning_of_week`, or `config.beginning_of_week`, or `:monday`) and it returns the date corresponding to that day.
|
||||
|
|
@ -3029,6 +3007,8 @@ d.prev_week(:friday) # => Fri, 30 Apr 2010
|
|||
|
||||
Both `next_week` and `prev_week` work as expected when `Date.beginning_of_week` or `config.beginning_of_week` are set.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `beginning_of_month`, `end_of_month`
|
||||
|
||||
The methods `beginning_of_month` and `end_of_month` return the dates for the beginning and end of the month:
|
||||
|
|
@ -3041,6 +3021,8 @@ d.end_of_month # => Mon, 31 May 2010
|
|||
|
||||
`beginning_of_month` is aliased to `at_beginning_of_month`, and `end_of_month` is aliased to `at_end_of_month`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `beginning_of_quarter`, `end_of_quarter`
|
||||
|
||||
The methods `beginning_of_quarter` and `end_of_quarter` return the dates for the beginning and end of the quarter of the receiver's calendar year:
|
||||
|
|
@ -3053,6 +3035,8 @@ d.end_of_quarter # => Wed, 30 Jun 2010
|
|||
|
||||
`beginning_of_quarter` is aliased to `at_beginning_of_quarter`, and `end_of_quarter` is aliased to `at_end_of_quarter`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `beginning_of_year`, `end_of_year`
|
||||
|
||||
The methods `beginning_of_year` and `end_of_year` return the dates for the beginning and end of the year:
|
||||
|
|
@ -3065,6 +3049,8 @@ d.end_of_year # => Fri, 31 Dec 2010
|
|||
|
||||
`beginning_of_year` is aliased to `at_beginning_of_year`, and `end_of_year` is aliased to `at_end_of_year`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
#### Other Date Computations
|
||||
|
||||
##### `years_ago`, `years_since`
|
||||
|
|
@ -3092,6 +3078,8 @@ Date.new(2012, 2, 29).years_since(3) # => Sat, 28 Feb 2015
|
|||
|
||||
`last_year` is short-hand for `#years_ago(1)`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `months_ago`, `months_since`
|
||||
|
||||
The methods `months_ago` and `months_since` work analogously for months:
|
||||
|
|
@ -3110,6 +3098,8 @@ Date.new(2009, 12, 31).months_since(2) # => Sun, 28 Feb 2010
|
|||
|
||||
`last_month` is short-hand for `#months_ago(1)`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `weeks_ago`
|
||||
|
||||
The method `weeks_ago` works analogously for weeks:
|
||||
|
|
@ -3119,6 +3109,8 @@ Date.new(2010, 5, 24).weeks_ago(1) # => Mon, 17 May 2010
|
|||
Date.new(2010, 5, 24).weeks_ago(2) # => Mon, 10 May 2010
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
##### `advance`
|
||||
|
||||
The most generic way to jump to other days is `advance`. This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, and returns a date advanced as much as the present keys indicate:
|
||||
|
|
@ -3147,6 +3139,8 @@ Date.new(2010, 2, 28).advance(days: 1).advance(months: 1)
|
|||
# => Thu, 01 Apr 2010
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
#### Changing Components
|
||||
|
||||
The method `change` allows you to get a new date which is the same as the receiver except for the given year, month, or day:
|
||||
|
|
@ -3163,6 +3157,8 @@ Date.new(2010, 1, 31).change(month: 2)
|
|||
# => ArgumentError: invalid date
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
#### Durations
|
||||
|
||||
Durations can be added to and subtracted from dates:
|
||||
|
|
@ -3205,6 +3201,8 @@ date.end_of_day # => Mon Jun 07 23:59:59 +0200 2010
|
|||
|
||||
`beginning_of_day` is aliased to `at_beginning_of_day`, `midnight`, `at_midnight`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
##### `beginning_of_hour`, `end_of_hour`
|
||||
|
||||
The method `beginning_of_hour` returns a timestamp at the beginning of the hour (hh:00:00):
|
||||
|
|
@ -3223,6 +3221,8 @@ date.end_of_hour # => Mon Jun 07 19:59:59 +0200 2010
|
|||
|
||||
`beginning_of_hour` is aliased to `at_beginning_of_hour`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
##### `beginning_of_minute`, `end_of_minute`
|
||||
|
||||
The method `beginning_of_minute` returns a timestamp at the beginning of the minute (hh:mm:00):
|
||||
|
|
@ -3243,6 +3243,8 @@ date.end_of_minute # => Mon Jun 07 19:55:59 +0200 2010
|
|||
|
||||
INFO: `beginning_of_hour`, `end_of_hour`, `beginning_of_minute` and `end_of_minute` are implemented for `Time` and `DateTime` but **not** `Date` as it does not make sense to request the beginning or end of an hour or minute on a `Date` instance.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
##### `ago`, `since`
|
||||
|
||||
The method `ago` receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight:
|
||||
|
|
@ -3259,6 +3261,8 @@ date = Date.current # => Fri, 11 Jun 2010
|
|||
date.since(1) # => Fri, 11 Jun 2010 00:00:01 EDT -04:00
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date/calculations.rb`.
|
||||
|
||||
#### Other Time Computations
|
||||
|
||||
### Conversions
|
||||
|
|
@ -3270,8 +3274,6 @@ WARNING: `DateTime` is not aware of DST rules and so some of these methods have
|
|||
|
||||
### Calculations
|
||||
|
||||
NOTE: All the following methods are defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
The class `DateTime` is a subclass of `Date` so by loading `active_support/core_ext/date/calculations.rb` you inherit these methods and their aliases, except that they will always return datetimes.
|
||||
|
||||
The following methods are reimplemented so you do **not** need to load `active_support/core_ext/date/calculations.rb` for these ones:
|
||||
|
|
@ -3298,6 +3300,8 @@ end_of_hour
|
|||
|
||||
Active Support defines `DateTime.current` to be like `Time.now.to_datetime`, except that it honors the user time zone, if defined. It also defines `DateTime.yesterday` and `DateTime.tomorrow`, and the instance predicates `past?`, and `future?` relative to `DateTime.current`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
#### Other Extensions
|
||||
|
||||
##### `seconds_since_midnight`
|
||||
|
|
@ -3309,6 +3313,8 @@ now = DateTime.current # => Mon, 07 Jun 2010 20:26:36 +0000
|
|||
now.seconds_since_midnight # => 73596
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
##### `utc`
|
||||
|
||||
The method `utc` gives you the same datetime in the receiver expressed in UTC.
|
||||
|
|
@ -3320,6 +3326,8 @@ now.utc # => Mon, 07 Jun 2010 23:27:52 +0000
|
|||
|
||||
This method is also aliased as `getutc`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
##### `utc?`
|
||||
|
||||
The predicate `utc?` says whether the receiver has UTC as its time zone:
|
||||
|
|
@ -3330,6 +3338,8 @@ now.utc? # => false
|
|||
now.utc.utc? # => true
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
##### `advance`
|
||||
|
||||
The most generic way to jump to another datetime is `advance`. This method receives a hash with keys `:years`, `:months`, `:weeks`, `:days`, `:hours`, `:minutes`, and `:seconds`, and returns a datetime advanced as much as the present keys indicate.
|
||||
|
|
@ -3361,6 +3371,8 @@ d.advance(seconds: 1).advance(months: 1)
|
|||
|
||||
WARNING: Since `DateTime` is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
#### Changing Components
|
||||
|
||||
The method `change` allows you to get a new datetime which is the same as the receiver except for the given options, which may include `:year`, `:month`, `:day`, `:hour`, `:min`, `:sec`, `:offset`, `:start`:
|
||||
|
|
@ -3393,6 +3405,8 @@ DateTime.current.change(month: 2, day: 30)
|
|||
# => ArgumentError: invalid date
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_time/calculations.rb`.
|
||||
|
||||
#### Durations
|
||||
|
||||
Durations can be added to and subtracted from datetimes:
|
||||
|
|
@ -3418,52 +3432,6 @@ Extensions to `Time`
|
|||
|
||||
### Calculations
|
||||
|
||||
NOTE: All the following methods are defined in `active_support/core_ext/time/calculations.rb`.
|
||||
|
||||
```ruby
|
||||
past?
|
||||
today?
|
||||
future?
|
||||
yesterday
|
||||
tomorrow
|
||||
seconds_since_midnight
|
||||
change
|
||||
advance
|
||||
ago
|
||||
since (in)
|
||||
prev_day
|
||||
next_day
|
||||
beginning_of_day (midnight, at_midnight, at_beginning_of_day)
|
||||
end_of_day
|
||||
beginning_of_hour (at_beginning_of_hour)
|
||||
end_of_hour
|
||||
beginning_of_week (at_beginning_of_week)
|
||||
end_of_week (at_end_of_week)
|
||||
monday
|
||||
sunday
|
||||
weeks_ago
|
||||
prev_week (last_week)
|
||||
next_week
|
||||
months_ago
|
||||
months_since
|
||||
beginning_of_month (at_beginning_of_month)
|
||||
end_of_month (at_end_of_month)
|
||||
prev_month
|
||||
next_month
|
||||
last_month
|
||||
beginning_of_quarter (at_beginning_of_quarter)
|
||||
end_of_quarter (at_end_of_quarter)
|
||||
beginning_of_year (at_beginning_of_year)
|
||||
end_of_year (at_end_of_year)
|
||||
years_ago
|
||||
years_since
|
||||
prev_year
|
||||
last_year
|
||||
next_year
|
||||
on_weekday?
|
||||
on_weekend?
|
||||
```
|
||||
|
||||
They are analogous. Please refer to their documentation above and take into account the following differences:
|
||||
|
||||
* `change` accepts an additional `:usec` option.
|
||||
|
|
@ -3488,6 +3456,8 @@ Active Support defines `Time.current` to be today in the current time zone. That
|
|||
|
||||
When making Time comparisons using methods which honor the user time zone, make sure to use `Time.current` instead of `Time.now`. There are cases where the user time zone might be in the future compared to the system time zone, which `Time.now` uses by default. This means `Time.now.to_date` may equal `Date.yesterday`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/time/calculations.rb`.
|
||||
|
||||
#### `all_day`, `all_week`, `all_month`, `all_quarter` and `all_year`
|
||||
|
||||
The method `all_day` returns a range representing the whole day of the current time.
|
||||
|
|
@ -3516,6 +3486,8 @@ now.all_year
|
|||
# => Fri, 01 Jan 2010 00:00:00 UTC +00:00..Fri, 31 Dec 2010 23:59:59 UTC +00:00
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
#### `prev_day`, `next_day`
|
||||
|
||||
In Ruby 1.9 `prev_day` and `next_day` return the date in the last or next day:
|
||||
|
|
@ -3526,6 +3498,8 @@ d.prev_day # => Fri, 07 May 2010
|
|||
d.next_day # => Sun, 09 May 2010
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
#### `prev_month`, `next_month`
|
||||
|
||||
In Ruby 1.9 `prev_month` and `next_month` return the date with the same day in the last or next month:
|
||||
|
|
@ -3545,6 +3519,8 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000
|
|||
Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
#### `prev_year`, `next_year`
|
||||
|
||||
In Ruby 1.9 `prev_year` and `next_year` return a date with the same day/month in the last or next year:
|
||||
|
|
@ -3563,6 +3539,8 @@ d.prev_year # => Sun, 28 Feb 1999
|
|||
d.next_year # => Wed, 28 Feb 2001
|
||||
```
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
#### `prev_quarter`, `next_quarter`
|
||||
|
||||
`prev_quarter` and `next_quarter` return the date with the same day in the previous or next quarter:
|
||||
|
|
@ -3584,6 +3562,8 @@ Time.local(2000, 11, 31).next_quarter # => 2001-03-01 00:00:00 +0200
|
|||
|
||||
`prev_quarter` is aliased to `last_quarter`.
|
||||
|
||||
NOTE: Defined in `active_support/core_ext/date_and_time/calculations.rb`.
|
||||
|
||||
### Time Constructors
|
||||
|
||||
Active Support defines `Time.current` to be `Time.zone.now` if there's a user time zone defined, with fallback to `Time.now`:
|
||||
|
|
|
|||
Loading…
Reference in a new issue