Merge remote branch 'docrails/master'

activerecord/lib/active_record/callbacks.rb

@@ -31,7 +31,7 @@ module ActiveRecord
   #   class CreditCard < ActiveRecord::Base
   #     # Strip everything but digits, so the user can specify "555 234 34" or
   #     # "5552-3434" or both will mean "55523434"
-  #     def before_validation_on_create
+  #     before_validation(:on => :create) do
   #       self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
   #     end
   #   end

railties/guides/source/3_0_release_notes.textile

@@ -36,7 +36,7 @@ h4. Rails 3 requires Ruby 1.8.7+
 
 Rails 3.0 requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.0 is also compatible with Ruby 1.9.2.
 
-TIP: Note that Ruby 1.8.7 p248 and p249 has marshaling bugs that crash Rails 3.0.0. Ruby 1.9.1 outright segfaults on Rails 3.0.0, so if you want to use Rails 3 with 1.9.x, jump on 1.9.2 trunk for smooth sailing.
+TIP: Note that Ruby 1.8.7 p248 and p249 has marshaling bugs that crash Rails 3.0.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
 
 h4. Rails Application object
 

railties/guides/source/active_support_core_extensions.textile

@@ -2869,7 +2869,7 @@ Date.new(2010, 2, 28).advance(:days => 1).advance(:months => 1)
 # => Thu, 01 Apr 2010
 </ruby>
 
-h5. Changing Date Components
+h5. 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:
 
@@ -2909,11 +2909,122 @@ date.end_of_day # => Sun Jun 06 23:59:59 +0200 2010
 
 +beginning_of_day+ is aliased to +at_beginning_of_day+, +midnight+, +at_midnight+
 
-h4. Conversions
+h4(#date-conversions). Conversions
 
 h3. Extensions to +DateTime+
 
-NOTE TO SELF: Since +DateTime+ is a subclass of +Date+, you get inherited methods that return +DateTime+ objects.
+NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+.
+
+WARNING: +DateTime+ is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example +seconds_since_midnight+ might not return the real amount in such a day.
+
+h4(#calculations-datetime). Calculations
+
+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:
+
+<ruby>
+yesterday
+tomorrow
+beginning_of_week
+end_on_week
+next_week
+months_ago
+months_since
+beginning_of_month
+end_of_month
+prev_month
+next_month
+beginning_of_quarter
+end_of_quarter
+beginning_of_year
+end_of_year
+years_ago
+years_since
+prev_year
+next_year
+</ruby>
+
+The following methods are reimplemented so you do *not* need to load +active_support/core_ext/date/calculations.rb+ for these ones:
+
+<ruby>
+beginning_of_day
+end_of_day
+ago
+since
+</ruby>
+
+On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below.
+
+h5. Named Datetimes
+
+h6. +DateTime.current+
+
+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 instance predicates +past?+, and +future?+ relative to +DateTime.current+.
+
+h5. Other Extensions
+
+h6. +seconds_since_midnight+
+
+The method +seconds_since_midnight+ returns the number of seconds since midnight:
+
+<ruby>
+now = DateTime.current     # => Mon, 07 Jun 2010 20:26:36 +0000
+now.seconds_since_midnight # => 73596
+</ruby>
+
+h6(#utc-datetime). +utc+
+
+The method +utc+ gives you the same datetime in the receiver expressed in UTC.
+
+<ruby>
+now = DateTime.current # => Mon, 07 Jun 2010 19:27:52 -0400
+now.utc                # => Mon, 07 Jun 2010 23:27:52 +0000
+</ruby>
+
+This method is also aliased as +getutc+.
+
+h6. +utc?+
+
+The predicate +utc?+ says whether the receiver has UTC as its time zone:
+
+<ruby>
+now = DateTime.now # => Mon, 07 Jun 2010 19:30:47 -0400
+now.utc?           # => false
+now.utc.utc?       # => true
+</ruby>
+
+h5(#datetime-changing-components). 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+:
+
+<ruby>
+now = DateTime.current
+# => Tue, 08 Jun 2010 01:56:22 +0000
+now.change(:year => 2011, :offset => Rational(-6, 24))
+# => Wed, 08 Jun 2011 01:56:22 -0600
+</ruby>
+
+If hours are zeroed, then minutes and seconds are too (unless they have given values):
+
+<ruby>
+now.change(:hour => 0)
+# => Tue, 08 Jun 2010 00:00:00 +0000
+</ruby>
+
+Similarly, if minutes are zeroed, then seconds are too (unless it has given a value):
+
+<ruby>
+now.change(:min => 0)
+# => Tue, 08 Jun 2010 01:00:00 +0000
+</ruby>
+
+This method is not tolerant to non-existing dates, if the change is invalid +ArgumentError+ is raised:
+
+<ruby>
+DateTime.current.change(:month => 2, :day => 30)
+# => ArgumentError: invalid date
+</ruby>
+
+h4(#datetime-conversions). Conversions
 
 h3. Extensions to +Time+
 

railties/guides/source/getting_started.textile

@@ -17,7 +17,7 @@ This guide is designed for beginners who want to get started with a Rails applic
 
 * The "Ruby":http://www.ruby-lang.org/en/downloads language version 1.8.7 or higher
 
-TIP: Note that Ruby 1.8.7 p248 and p249 has marshaling bugs that crash Rails 3.0.0. Ruby 1.9.1 outright segfaults on Rails 3.0.0, so if you want to use Rails 3 with 1.9.x, jump on 1.9.2 trunk for smooth sailing.
+TIP: Note that Ruby 1.8.7 p248 and p249 has marshaling bugs that crash Rails 3.0.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.
 
 * The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system
 * A working installation of the "SQLite3 Database":http://www.sqlite.org