MONGOID-5222 always return nil on mongoize (#5336)

* MONGOID-5222 add feature flag

* MONGOID-5222 first batch of type fixes

* MONGOID-5222 rebase

* MONGOID-5222 add sets

* MONGOID-5222 fix failures

* MONGOID-5222 fix most tests

* MONGOID-5222 fix to always raise in mongoize

* MONGOID-5222 use new architecture

* MONGOID-5222 fix many tests

* MONGOID-5222 fix rest of tests

* MONGOID-5222 remove dead code

* MONGOID-5222 fix binary tests

* MONGOID-5222 fix mongoizable tests

* MONGOID-5222 fix the rest of tests

* MONGOID-5222 unpend all mongoizable tests

* MONGOID-5222 add evolve to mongoizable spec

* comment out most evolve methods

* Revert "comment out most evolve methods"

This reverts commit f60e4b4c55a4cd0505a8a91564ef4feb57809946.

* MONGOID-5222 remove evolve tests

* MONGOID-5222 get rid of unnecessary test flags. Change integer to check for to_i

* MONGOID-5222 change float as well

* MONGOID-5222 fix range tests

* MONGOID-5222 rename wrap_mognoize

* MONGOID-5222 remove mongoize_safe

* MONGOID-5222 fix BigDecimal mongoization

* MONGOID-5222 add documentation

* MONGOID-5222 update error message and docs

* MONGOID-5222 fix tests

* MONGOID-5222 add note to custom types section

* MONGOID-5222 fix grammatical error

* MONGOID-5222 remove _mongoid_wrap_mongoize

* Update docs/release-notes/mongoid-8.0.txt

Co-authored-by: Oleg Pudeyev <[email protected]>

* Update docs/reference/fields.txt

Co-authored-by: Oleg Pudeyev <[email protected]>

* Update docs/reference/fields.txt

Co-authored-by: Oleg Pudeyev <[email protected]>

* MONGOID-5222 answer comments

* MONGOID-5222 fix tests

* MONGOID-5222 update error message

* MONGOID-5222 fix regexp mongoization

* MONGOID-5222 get rid of 42bogus

* MONGOID-5222 update mongoize update strings

* MONGOID-5222 fix range docs

* MONGOID-5222 always return nil on mongoize

* MONGOID-5222 remove InvalidValue from tests

* MONGOID-5222 fix array, set, regexp mongoize

* MONGOID-5222 fix more comments and update compatibility release note

* MONGOID-5222 remove invalid_value error

* MONGOID-5222 add another case to release notes

* MONGOID-5222 fix docs

* MONGOID-5222 remove byebug

* MONGOID-5222 fix boolean mongoize

* Update docs/reference/fields.txt

* MONGOID-5222 test nps

* MONGOID-5222 add reference to attributes_before_type_cast

* MONGOID-5222 answer some comments

* MONGOID-5222 move ArgumentError

* MONGOID-5222 update release notes

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: neilshweky

source/reference/fields.txt

@@ -827,6 +827,42 @@ Mongoid also defines the ``id`` field aliased to ``_id``. The ``id``
 alias can :ref:`be removed <unalias-id>` if desired (such as to integrate
 with systems that use the ``id`` field to store value different from ``_id``.
 
+.. _uncastable-values:
+
+Assigning Uncastable Values
+---------------------------
+
+In Mongoid 8, Mongoid has standardized the treatment of the assignment of
+"uncastable" values. A value is considered "uncastable" when it cannot be
+coerced to the type of the field. For example:
+
+.. code::
+
+  class User
+    include Mongoid::Document
+
+    field :name, type: Integer
+  end
+
+  User.new(name: [ "hello" ])
+
+Assigning an array to a field of type Integer doesn't work since an array can't
+be coerced to an Integer. The assignment of uncastable values to a field will
+cause a ``nil`` to be written:
+
+.. code::
+
+  user = User.new(name: [ "hello" ])
+  # => #<User _id: 62b222d43282a47bf73e3264, name: nil>
+
+Note that the original uncastable values will be stored in the
+``attributes_before_type_cast`` hash with their field names:
+
+.. code::
+
+  user.attributes_before_type_cast["name"]
+  # => ["hello"]
+
 
 .. _customizing-field-behavior:
 
@@ -978,6 +1014,12 @@ setter methods for fields of your custom type.
    venue = Venue.new(location: point) # This uses the Point#mongoize instance method.
    venue = Venue.new(location: [ 12, 24 ]) # This uses the Point.mongoize class method.
 
+.. note::
+
+  The ``mongoize`` method should return ``nil`` on values that are uncastable to
+  your custom type. See the section on :ref:`Uncastable Values <uncastable-values>`
+  for more details.
+
 The class method ``demongoize`` does the inverse of ``mongoize``. It takes the raw object
 from the MongoDB Ruby driver and converts it to an instance of your custom type.
 In this case, the database driver returns an ``Array`` and we instantiate a ``Point`` from it.

source/release-notes/mongoid-8.0.txt

@@ -57,6 +57,34 @@ changed in Mongoid 8.0:
 Please refer to :ref:`configuration option <configuration-options>` for
 the description and effects of each of these options.
 
+Storing Uncastable Value
+------------------------
+
+In Mongoid 8, Mongoid standardizes the storing of "uncastable values." On
+attempting to write an uncastable value, a ``nil`` is written instead. See the
+secion on :ref:`Uncastable Values <uncastable-values>` for more details.
+
+Some ``mongoize`` methods were also changed to perform consistently with rails
+and the other mongoize methods. The following is a table of the changes in
+functionality:
+
++--------------+------------------------+------------------------+-------------------+
+| Field Type   | Situation              | Previous Functionality | New Functionality |
++==============+========================+========================+===================+
+| Boolean      | When a non-boolean     | return ``false``       | return ``nil``    |
+|              | string is assigned:    |                        |                   |
+|              | "bogus value"          |                        |                   |
++--------------+------------------------+------------------------+-------------------+
+| Array/Set    | When a value that is   | raise ``InvalidValue`` | return ``nil``    |
+|              | not an array or set is | error                  |                   |
+|              | assigned, and does NOT |                        |                   |
+|              | respond to ``to_a``: 1 |                        |                   |
++--------------+------------------------+------------------------+-------------------+
+| All Other    | When an uncastable     | undefined behavior,    | return ``nil``    |
+| Types        | value is assigned      | occasionally raises    |                   |
+|              |                        | ``NoMethodError``      |                   |
++--------------+------------------------+------------------------+-------------------+
+
 
 Order of Callback Invocation
 ----------------------------