doc updates

CHANGELOG.md

@@ -3,6 +3,7 @@
 * [#183](https://github.com/intridea/hashie/pull/183): Added Mash#load with YAML file support - [@gregory](https://github.com/gregory).
 * [#197](https://github.com/intridea/hashie/pull/197): Dont convert keys to string on initalization of mash - [@gregory](https://github.com/gregory).
 * Your contribution here.
+* [#200](https://github.com/intridea/hashie/pull/200): Improved coercion: primitives and error handling - [@maxlinc](https://github.com/maxlinc).
 
 ## 3.2.0 (7/10/2014)
 

README.md

@@ -96,6 +96,47 @@ tweet.relations.class # => Hash
 #    and Relation.new on each value since Relation doesn't define the `coerce` class method
 ```
 
+### Coercing Core Types
+
+Hashie handles coercion to the following by using standard conversion methods:
+
+| type     | method   |
+|----------|----------|
+| Integer  | `#to_i`  |
+| Float    | `#to_f`  |
+| Complex  | `#to_c`  |
+| Rational | `#to_r`  |
+| String   | `#to_s`  |
+| Symbol   | `#to_sym`|
+
+**Note**: The standard Ruby conversion methods are less strict than you may assume. For example, `:foo.to_i` raises an error but `"foo".to_i` returns 0.
+
+You can also use coerce from the following supertypes with `coerce_value`:
+- Integer
+- Numeric
+
+Hashie does not have built-in support for coercion boolean values, since Ruby does not have a built-in boolean type or standard method for to a boolean. You can coerce to booleans using a custom proc.
+
+### Coercion Proc
+
+You can use a custom coercion proc on either `#coerce_key` or `#coerce_value`. This is useful for coercing to booleans or other simple types without creating a new class and `coerce` method. For example:
+
+```ruby
+class Tweet < Hash
+  include Hashie::Extensions::Coercion
+  coerce_key :retweeted, ->(v) do
+    case v
+    when String
+      return !!(v =~ /^(true|t|yes|y|1)$/i)
+    when Numeric
+      return !v.to_i.zero?
+    else
+      return v == true
+    end
+  end
+end
+```
+
 ### KeyConversion
 
 The KeyConversion extension gives you the convenience methods of `symbolize_keys` and `stringify_keys` along with their bang counterparts. You can also include just stringify or just symbolize with `Hashie::Extensions::StringifyKeys` or `Hashie::Extensions::SymbolizeKeys`.

UPGRADING.md

@@ -1,6 +1,22 @@
 Upgrading Hashie
 ================
 
+### Upgrading to 3.2.1
+
+#### Possible coercion changes
+
+The improvements made to coercions in version 3.2.1 [issue #200](https://github.com/intridea/hashie/pull/200) do not break the documented API, but are significant enough that changes may effect undocumented side-effects. Applications that depended on those side-effects will need to be updated.
+
+**Change**: Type coercion no longer creates new objects if the input matches the target type. Previously coerced properties always resulted in the creation of a new object, even when it wasn't necessary. This had the effect of a `dup` or `clone` on coerced properties but not uncoerced ones.
+
+If necessary, `dup` or `clone` your own objects. Do not assume Hashie will do it for you.
+
+**Change**: Failed coercion attempts now raise Hashie::CoercionError.
+
+Hashie now raises a Hashie::CoercionError that details on the property that could not be coerced, the source and target type of the coercion, and the internal error. Previously only the internal error was raised.
+
+Applications that were attempting to rescuing the internal errors should be updated to rescue Hashie::CoercionError instead.
+
 ### Upgrading to 3.0
 
 #### Compatibility with Rails 4 Strong Parameters