1 files changed, 46 insertions, 43 deletions

diff --git a/activerecord/lib/active_record/type/value.rb b/activerecord/lib/active_record/type/value.rb
index 9456a4a56c..fc3ef5e83b 100644
--- a/activerecord/lib/active_record/type/value.rb
+++ b/activerecord/lib/active_record/type/value.rb
@@ -1,44 +1,46 @@
 module ActiveRecord
   module Type
-    class Value # :nodoc:
+    class Value
       attr_reader :precision, :scale, :limit
 
-      # Valid options are +precision+, +scale+, and +limit+. They are only
-      # used when dumping schema.
-      def initialize(options = {})
-        options.assert_valid_keys(:precision, :scale, :limit)
-        @precision = options[:precision]
-        @scale = options[:scale]
-        @limit = options[:limit]
+      def initialize(precision: nil, limit: nil, scale: nil)
+        @precision = precision
+        @scale = scale
+        @limit = limit
       end
 
-      # The simplified type that this object represents. Returns a symbol such
-      # as +:string+ or +:integer+
-      def type; end
+      def type # :nodoc:
+      end
 
-      # Type casts a string from the database into the appropriate ruby type.
-      # Classes which do not need separate type casting behavior for database
-      # and user provided values should override +cast_value+ instead.
-      def type_cast_from_database(value)
-        type_cast(value)
+      # Convert a value from database input to the appropriate ruby type. The
+      # return value of this method will be returned from
+      # ActiveRecord::AttributeMethods::Read#read_attribute. The default
+      # implementation just calls Value#cast.
+      #
+      # +value+ The raw input, as provided from the database.
+      def deserialize(value)
+        cast(value)
       end
 
       # Type casts a value from user input (e.g. from a setter). This value may
-      # be a string from the form builder, or an already type cast value
-      # provided manually to a setter.
+      # be a string from the form builder, or a ruby object passed to a setter.
+      # There is currently no way to differentiate between which source it came
+      # from.
+      #
+      # The return value of this method will be returned from
+      # ActiveRecord::AttributeMethods::Read#read_attribute. See also:
+      # Value#cast_value.
       #
-      # Classes which do not need separate type casting behavior for database
-      # and user provided values should override +type_cast+ or +cast_value+
-      # instead.
-      def type_cast_from_user(value)
-        type_cast(value)
+      # +value+ The raw input, as provided to the attribute setter.
+      def cast(value)
+        cast_value(value) unless value.nil?
       end
 
       # Cast a value from the ruby type to a type that the database knows how
       # to understand. The returned value from this method should be a
       # +String+, +Numeric+, +Date+, +Time+, +Symbol+, +true+, +false+, or
-      # +nil+
-      def type_cast_for_database(value)
+      # +nil+.
+      def serialize(value)
         value
       end
 
@@ -50,17 +52,10 @@ module ActiveRecord
 
       # These predicates are not documented, as I need to look further into
       # their use, and see if they can be removed entirely.
-      def number? # :nodoc:
-        false
-      end
-
       def binary? # :nodoc:
         false
       end
 
-      def klass # :nodoc:
-      end
-
       # Determines whether a value has changed for dirty checking. +old_value+
       # and +new_value+ will always be type-cast. Types should not need to
       # override this method.
@@ -69,10 +64,23 @@ module ActiveRecord
       end
 
       # Determines whether the mutable value has been modified since it was
-      # read. Returns +false+ by default. This method should not be overridden
-      # directly. Types which return a mutable value should include
-      # +Type::Mutable+, which will define this method.
-      def changed_in_place?(*)
+      # read. Returns +false+ by default. If your type returns an object
+      # which could be mutated, you should override this method. You will need
+      # to either:
+      #
+      # - pass +new_value+ to Value#serialize and compare it to
+      #   +raw_old_value+
+      #
+      # or
+      #
+      # - pass +raw_old_value+ to Value#deserialize and compare it to
+      #   +new_value+
+      #
+      # +raw_old_value+ The original value, before being passed to
+      # +deserialize+.
+      #
+      # +new_value+ The current value, after type casting.
+      def changed_in_place?(raw_old_value, new_value)
         false
       end
 
@@ -85,14 +93,9 @@ module ActiveRecord
 
       private
 
-      def type_cast(value)
-        cast_value(value) unless value.nil?
-      end
-
       # Convenience method for types which do not need separate type casting
-      # behavior for user and database inputs. Called by
-      # `type_cast_from_database` and `type_cast_from_user` for all values
-      # except `nil`.
+      # behavior for user and database inputs. Called by Value#cast for
+      # values except +nil+.
       def cast_value(value) # :doc:
         value
       end