AS guide: documents slice and slice!

1 files changed, 29 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 9682a6ee4b..352feb96fb 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -1321,6 +1321,35 @@ def create_has_many_reflection(association_id, options, &extension)
 end
 </ruby>
 
+h4. Slicing
+
+Ruby has builtin support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
+
+<ruby>
+{:a => 1, :b => 2, :c => 3}.slice(:a, :c)
+# => {:c => 3, :a => 1}
+
+{:a => 1, :b => 2, :c => 3}.slice(:b, :X)
+# => {:b => 2} # non-existing keys are ignored
+</ruby>
+
+If the receiver responds to +convert_key+ keys are normalized:
+
+<ruby>
+{:a => 1, :b => 2}.with_indifferent_access.slice("a")
+# => {:a => 1}
+</ruby>
+
+NOTE. Slicing may come in handy for sanitizing option hashes with a white list of keys.
+
+There's also +slice!+ which in addition to perform a slice in place returns what's removed:
+
+<ruby>
+hash = {:a => 1, :b => 2}
+rest = hash.slice!(:a) # => {:b => 2}
+hash                   # => {:a => 1}
+</ruby>
+
 h4. Indifferent Access
 
 The method +with_indifferent_access+ returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver: