docs: add demos for issue 80 utility methods

demo/core/enumerable/squeeze.md

@@ -0,0 +1,17 @@
+## Enumerable#squeeze
+
+    require 'facets/enumerable/squeeze'
+
+Returns a new array with consecutive duplicate entries collapsed. Unlike
+`Array#uniq`, duplicate values are only removed when they are adjacent.
+
+    [1, 2, 2, 3, 3, 2, 1].squeeze.assert == [1, 2, 3, 2, 1]
+
+When the enumerable is sorted first, adjacent duplicates become grouped, so
+the result matches `uniq`.
+
+    [1, 2, 2, 3, 3, 2, 1].sort.squeeze.assert == [1, 2, 3]
+
+Pass one or more values to squeeze only those values.
+
+    [1, 2, 2, 3, 3, 2, 1].squeeze(3).assert == [1, 2, 2, 3, 2, 1]

demo/core/enumerator/lazy/squeeze.md

@@ -0,0 +1,14 @@
+## Enumerator::Lazy#squeeze
+
+    require 'facets/enumerator/lazy/squeeze'
+
+Provides a lazy version of `Enumerable#squeeze`, collapsing consecutive
+duplicates while preserving lazy enumeration.
+
+    enum = [1, 2, 2, 3, 3, 2, 1].lazy.squeeze
+    enum.to_a.assert == [1, 2, 3, 2, 1]
+
+Pass values to squeeze only matching entries.
+
+    enum = [1, 2, 2, 3, 3, 2, 1].lazy.squeeze(3)
+    enum.to_a.assert == [1, 2, 2, 3, 2, 1]

demo/core/hash/fetch_nested.md

@@ -0,0 +1,17 @@
+## Hash#fetch_nested
+
+    require 'facets/hash/fetch_nested'
+
+Fetches a nested value by walking a series of keys. If any key is missing,
+`nil` is returned instead of raising `KeyError`.
+
+    data = {'hello' => {'world' => 42}}
+    data.fetch_nested('hello', 'world').assert == 42
+
+    data.fetch_nested('hello', 'missing').assert == nil
+
+When a block is given, it is called with the requested keys when the nested
+path cannot be fetched.
+
+    fallback = data.fetch_nested('hello', 'missing') { |*keys| keys.join('.') }
+    fallback.assert == 'hello.missing'

demo/core/string/rotate.md

@@ -0,0 +1,23 @@
+## String#rotate
+
+    require 'facets/string/rotate'
+
+Returns a copy of the string rotated left by the given count.
+
+    'abcdefgh'.rotate(2).assert == 'cdefghab'
+
+Negative counts rotate from the right.
+
+    'abcdefgh'.rotate(-2).assert == 'ghabcdef'
+
+## String#rotate!
+
+Performs the rotation in place.
+
+    string = 'abcdefgh'
+    string.rotate!(2)
+    string.assert == 'cdefghab'
+
+    string = 'abcdefgh'
+    string.rotate!(-2)
+    string.assert == 'ghabcdef'