From 7a5aa35ed09dbdf306adbe5786cca7019a10bf98 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 9 May 2010 02:28:13 +0300 Subject: AS guide: documents some Date calculations (calendar reform details pending) --- .../source/active_support_core_extensions.textile | 51 +++++++++++++++++++++- 1 file changed, 49 insertions(+), 2 deletions(-) (limited to 'railties/guides/source/active_support_core_extensions.textile') diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 32738fe070..a3cb864796 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2648,11 +2648,58 @@ NOTE: Defined in +active_support/core_ext/proc.rb+. h3. Extensions to +Date+ -... +h4. Calculations + +All the following methods are defined in +active_support/core_ext/date/calculations.rb+. + +h5. +Date.current+ + +Active Support defines +Date.current+ to be today in the current time zone. That's like +Date.today+, except that it honors +Time.zone_default+. It also defines +Date.yesterday+ and +Date.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Date.current+. + +h5. Named dates + +h6. +last_year+, +next_year+ + +The methods +last_year+ and +next_year+ return a date with the same day/month in the last or next year: + + +d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 +d.last_year # => Fri, 08 May 2009 +d.next_year # => Sun, 08 May 2011 + + +If date is the 29th of February of a leap year, you obtain the 28th: + + +d = Date.new(2000, 2, 29) # => Tue, 29 Feb 2000 +d.last_year # => Sun, 28 Feb 1999 +d.next_year # => Wed, 28 Feb 2001 + + +h6. +last_month+, +next_month+ + +The methods +last_month+ and +next_month+ return the a date with the same day in the last or next month: + + +d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 +d.last_month # => Thu, 08 Apr 2010 +d.next_month # => Tue, 08 Jun 2010 + + +If such a day does not exist, the last day of the corresponding month is returned: + + +Date.new(2000, 5, 31).last_month # => Sun, 30 Apr 2000 +Date.new(2000, 3, 31).last_month # => Tue, 29 Feb 2000 +Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 +Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 + + +h4. Conversions h3. Extensions to +DateTime+ -... +NOTE TO SELF: Since +DateTime+ is a subclass of +Date+, you get inherited methods that return +DateTime+ objects. h3. Extensions to +Time+ -- cgit v1.2.3 From 345c38a5277400e96a0b6992192037f0eaa81718 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 9 May 2010 11:39:57 +0300 Subject: AS guide: adds a catchall note about date calculations around the calendar reform --- railties/guides/source/active_support_core_extensions.textile | 2 ++ 1 file changed, 2 insertions(+) (limited to 'railties/guides/source/active_support_core_extensions.textile') diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index a3cb864796..091a639270 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2652,6 +2652,8 @@ h4. Calculations All the following methods are defined in +active_support/core_ext/date/calculations.rb+. +WARNING: The following calculation methods have edge cases in November 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. + h5. +Date.current+ Active Support defines +Date.current+ to be today in the current time zone. That's like +Date.today+, except that it honors +Time.zone_default+. It also defines +Date.yesterday+ and +Date.tomorrow+, and the instance predicates +past?+, +today?+, and +future?+, all of them relative to +Date.current+. -- cgit v1.2.3 From 08d991ad409295a2d91b10bca4c7080fdbe7b5b9 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 9 May 2010 11:44:22 +0300 Subject: AS guide: you know, the 10th is not November --- railties/guides/source/active_support_core_extensions.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides/source/active_support_core_extensions.textile') diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 091a639270..d321e3db72 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2652,7 +2652,7 @@ h4. Calculations All the following methods are defined in +active_support/core_ext/date/calculations.rb+. -WARNING: The following calculation methods have edge cases in November 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. +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. h5. +Date.current+ -- cgit v1.2.3 From 1ff3d951e620ddeeb97e87e2024391470e886467 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Sun, 9 May 2010 12:45:21 +0300 Subject: AS guide: more date calculation utilities --- .../source/active_support_core_extensions.textile | 60 +++++++++++++++++++++- 1 file changed, 59 insertions(+), 1 deletion(-) (limited to 'railties/guides/source/active_support_core_extensions.textile') diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index d321e3db72..b7b5f47eef 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2680,7 +2680,7 @@ d.next_year # => Wed, 28 Feb 2001 h6. +last_month+, +next_month+ -The methods +last_month+ and +next_month+ return the a date with the same day in the last or next month: +The methods +last_month+ and +next_month+ return the date with the same day in the last or next month: d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 @@ -2697,6 +2697,64 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 +h6. +beginning_of_week+, +end_of_week+ + +The methods +beginning_of_week+ and +end_of_week+ return the dates for the beginning and end of week, assuming weeks start on Monday: + + +d = Date.new(2010, 5, 8) # => Sat, 08 May 2010 +d.beginning_of_week # => Mon, 03 May 2010 +d.end_of_week # => Sun, 09 May 2010 + + ++beginning_of_week+ is aliased to +monday+ and +at_beginning_of_week+. +end_of_week+ is aliased to +sunday+ and +at_end_of_week+. + +h6. +next_week+ + ++next_week+ receives a symbol with a day name in English (in lowercase, default is +:monday+) and it returns the date corresponding to that day in the next week: + + +d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 +d.next_week # => Mon, 10 May 2010 +d.next_week(:saturday) # => Sat, 15 May 2010 + + +h6. +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: + + +d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 +d.beginning_of_month # => Sat, 01 May 2010 +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+. + +h6. +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: + + +d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 +d.beginning_of_quarter # => Thu, 01 Apr 2010 +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+. + +h6. +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: + + +d = Date.new(2010, 5, 9) # => Sun, 09 May 2010 +d.beginning_of_year # => Fri, 01 Jan 2010 +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+. + h4. Conversions h3. Extensions to +DateTime+ -- cgit v1.2.3