README.md in postgres_ext-0.0.9 vs README.md in postgres_ext-0.0.10

@@ -32,17 +32,50 @@
  * [Migration/Schema.rb support](#migrationschemarb-support)
  * [Type Casting support](#type-casting-support)
  * [Querying PostgreSQL datatypes](#querying-postgresql-datatypes)
 
 ### Usage Notes
-Take care when dealing with arrays and other types that allow you to
-update their value in place. In place changes are not currently tracked
-in Rails (see [this issue](https://github.com/rails/rails/issues/6954)).
-To track changes that happen via `#<<` or other instance methods, be
-sure to call `<attribute>_will_change!` so that Active Record knows to
-persist the change.
+Avoid the use of in place operators (ie `Array#<<`). These changes are
+*not* tracked by Rails ([this issue](https://github.com/rails/rails/issues/6954))
+explains why). In place modifications also modify the default object.
 
+Assuming we have the following model:
+
+```ruby
+create_table :items do |t|
+  t.string :names, :array => true, :default => []
+end
+
+class Item < ActiveRecord::Base
+end
+```
+
+The following will modify the default value of the names attribute.
+
+```ruby
+a = Item.new
+a.names << 'foo'
+
+b = Item.new
+puts b.names
+# => ['foo']
+```
+
+The supported way of modifying `a.names`:
+
+```ruby
+a = Item.new
+a.names += 'foo'
+
+b = Item.new
+puts b.names
+# => []
+```
+
+As a result, in place operators are discouraged and will not be
+supported in postgres\_ext at this time. 
+
 ## Migration/Schema.rb support
 
 ### INET
 
 ```ruby
@@ -186,11 +219,12 @@
 predicate for the `&&` operator.
 
 ```ruby
 user_arel = User.arel_table
 
-User.where(user_arel[:tags].array_overlap(['one','two'])).to_sql
+# Execute the query
+User.where(user_arel[:tags].array_overlap(['one','two']))
 # => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"tags\" && '{one,two}'
 ```
 
 #### ANY or ALL functions
 
@@ -218,13 +252,13 @@
 user_arel = User.arel_table
 
 any_tags_function = Arel::Nodes::NamedFunction.new('ANY', [user_arel[:tags]])
 predicate = Arel::Nodes::Equality.new('test', any_tags_function)
 
-User.where(predicate).to_sql
+# Execute the query
+User.where(predicate)
 #=> SELECT \"users\".* FROM \"users\" WHERE 'test' = ANY(\"users\".\"tags\")
-
 ```
 
 The ALL version of this same predicate can be generated by swap `'ANY'`
 for `'ALL'` in the named function.
 
@@ -248,21 +282,24 @@
 predicate for the `<<` operator.
 
 ```ruby
 user_arel = User.arel_table
 
-User.where(user_arel[:ip_address].contained_witin('127.0.0.1/24')).to_sql
+# Execute the query
+User.where(user_arel[:ip_address].contained_witin('127.0.0.1/24'))
 # => SELECT \"users\".* FROM \"users\" WHERE \"users\".\"ip_address\" << '127.0.0.1/24'
 ```
 
 ## Indexes
 
 ### Index types
 
-Postgres\_ext allows you to specify an index type at index creation.
+Postgres\_ext allows you to specify index type and index operator
+class at index creation.
 
 ```ruby
 add_index :table_name, :column, :index_type => :gin
+add_index :table_name, :column, :index_type => :gin, :index_opclass => :gin_trgm_ops
 ```
 
 ### Where clauses
 
 Postgres\_ext allows you to specify a where clause at index creation.