README.adoc in refinements-7.9.0 vs README.adoc in refinements-7.10.0
- old
+ new
@@ -7,11 +7,11 @@
[link=http://badge.fury.io/rb/refinements]
image::https://badge.fury.io/rb/refinements.svg[Gem Version]
[link=https://circleci.com/gh/bkuhlmann/refinements]
image::https://circleci.com/gh/bkuhlmann/refinements.svg?style=svg[Circle CI Status]
-A collection of refinements (enhancements) to core Ruby objects.
+A collection of refinements (enhancements) to primitive Ruby objects.
toc::[]
== Features
@@ -93,11 +93,12 @@
require "refinements/string_ios"
----
=== Using
-Much like including/extending a module, you’ll need modify your object(s) to use the refinement(s):
+Much like including/extending a module, you’ll need to modify your object(s) to use the
+refinement(s):
[source,ruby]
----
class Example
using Refinements::Arrays
@@ -117,43 +118,43 @@
==== Array
===== #compress
-Removes `nil` and empty values without modifying itself.
+Removes `nil` and empty values without mutating itself.
[source,ruby]
----
example = ["An", nil, "", "Example"]
example.compress # => ["An", "Example"]
example # => ["An", nil, "", "Example"]
----
===== #compress!
-Removes `nil` and empty values while modifying itself.
+Removes `nil` and empty values while mutating itself.
[source,ruby]
----
example = ["An", nil, "", "Example"]
example.compress! # => ["An", "Example"]
example # => ["An", "Example"]
----
===== #include
-Adds given array or elements without modifying itself.
+Adds given array or elements without mutating itself.
[source,ruby]
----
[1, 2, 3].include [4, 5] # => [1, 2, 3, 4, 5]
[1, 2, 3].include 4, 5 # => [1, 2, 3, 4, 5]
----
===== #exclude
-Removes given array or elements without modifying itself.
+Removes given array or elements without mutating itself.
[source,ruby]
----
[1, 2, 3, 4, 5].exclude [4, 5] # => [1, 2, 3]
[1, 2, 3, 4, 5].exclude 4, 5 # => [1, 2, 3]
@@ -234,33 +235,33 @@
example[:b] # => []
----
===== #except
-Answers new hash with given keys removed without modifying itself.
+Answers new hash with given keys removed without mutating itself.
[source,ruby]
----
example = {a: 1, b: 2, c: 3}
example.except :a, :b # => {c: 3}
example # => {a: 1, b: 2, c: 3}
----
===== #except!
-Answers new hash with given keys removed while modifying itself.
+Answers new hash with given keys removed while mutating itself.
[source,ruby]
----
example = {a: 1, b: 2, c: 3}
example.except! :a, :b # => {c: 3}
example # => {c: 3}
----
===== #flatten_keys
-Flattens nested keys as top-level keys without modifying itself. Does not handle nested arrays,
+Flattens nested keys as top-level keys without mutating itself. Does not handle nested arrays,
though.
[source,ruby]
----
{a: {b: 1}}.flatten_keys prefix: :test # => {test_a_b: 1}
@@ -274,133 +275,178 @@
example # => {a: {b: 1}}
----
===== #flatten_keys!
-Flattens nested keys as top-level keys while modifying itself. Does not handle nested arrays,
+Flattens nested keys as top-level keys while mutating itself. Does not handle nested arrays,
though.
[source,ruby]
----
example = {a: {b: 1}}
example.flatten_keys! # => {a_b: 1}
example # => {a_b: 1}
----
+===== #stringify_keys
+
+Converts keys to strings without mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys # => {"a" => 1, "b" => 2}
+example # => {a: 1, b: 2}
+----
+
+===== #stringify_keys!
+
+Converts keys to strings while mutating itself.
+
+[source,ruby]
+----
+example = {a: 1, b: 2}
+example.stringify_keys! # => {"a" => 1, "b" => 2}
+example # => {"a" => 1, "b" => 2}
+----
+
===== #symbolize_keys
-Converts keys to symbols without modifying itself.
+Converts keys to symbols without mutating itself.
[source,ruby]
----
example = {"a" => 1, "b" => 2}
example.symbolize_keys # => {a: 1, b: 2}
example # => {"a" => 1, "b" => 2}
----
===== #symbolize_keys!
-Converts keys to symbols while modifying itself.
+Converts keys to symbols while mutating itself.
[source,ruby]
----
example = {"a" => 1, "b" => 2}
example.symbolize_keys! # => {a: 1, b: 2}
example # => {a: 1, b: 2}
----
===== #deep_merge
-Merges deeply nested hashes together without modifying itself.
+Merges deeply nested hashes together without mutating itself.
[source,ruby]
----
example = {a: "A", b: {one: "One", two: "Two"}}
example.deep_merge b: {one: 1} # => {a: "A", b: {one: 1, two: "Two"}}
example # => {a: "A", b: {one: "One", two: "Two"}}
----
===== #deep_merge!
-Merges deeply nested hashes together while modifying itself.
+Merges deeply nested hashes together while mutating itself.
[source,ruby]
----
example = {a: "A", b: {one: "One", two: "Two"}}
example.deep_merge! b: {one: 1} # => {a: "A", b: {one: 1, two: "Two"}}
example # => {a: "A", b: {one: 1, two: "Two"}}
----
+===== #deep_stringify_keys
+
+Stringifies keys of nested hash without mutating itself. Does not handle nested arrays, though.
+
+[source,ruby]
+----
+example = {a: {b: 2}}
+example.deep_stringify_keys # => {"a" => {"b" => 1}}
+example # => {a: {b: 2}}
+----
+
+===== #deep_stringify_keys!
+
+Stringifies keys of nested hash while mutating itself. Does not handle nested arrays, though.
+
+[source,ruby]
+----
+example = {a: {b: 2}}
+example.deep_stringify_keys! # => {"a" => {"b" => 1}}
+example # => {"a" => {"b" => 1}}
+----
+
===== #deep_symbolize_keys
-Symbolizes keys of nested hash without modifying itself. Does not handle nested arrays, though.
+Symbolizes keys of nested hash without mutating itself. Does not handle nested arrays, though.
[source,ruby]
----
example = {"a" => {"b" => 2}}
example.deep_symbolize_keys # => {a: {b: 1}}
example # => {"a" => {"b" => 2}}
----
===== #deep_symbolize_keys!
-Symbolizes keys of nested hash while modifying itself. Does not handle nested arrays, though.
+Symbolizes keys of nested hash while mutating itself. Does not handle nested arrays, though.
[source,ruby]
----
example = {"a" => {"b" => 2}}
example.deep_symbolize_keys! # => {a: {b: 1}}
example # => {a: {b: 1}}
----
===== #recurse
-Applies block to nested hash. Does not handle nested arrays, though.
+Recursively iterates over the hash and any hash value by applying the given block to it. Does not
+handle nested arrays, though.
[source,ruby]
----
example = {"a" => {"b" => 1}}
example.recurse(&:symbolize_keys) # => {a: {b: 1}}
example.recurse(&:invert) # => {{"b" => 1} => "a"}
----
===== #rekey
-Transforms keys per mapping (size of mapping can vary) without modifying itself.
+Transforms keys per mapping (size of mapping can vary) without mutating itself.
[source,ruby]
----
example = {a: 1, b: 2, c: 3}
example.rekey a: :amber, b: :blue # => {amber: 1, blue: 2, c: 3}
example # => {a: 1, b: 2, c: 3}
----
===== #rekey!
-Transforms keys per mapping (size of mapping can vary) while modifying itself.
+Transforms keys per mapping (size of mapping can vary) while mutating itself.
[source,ruby]
----
example = {a: 1, b: 2, c: 3}
example.rekey! a: :amber, b: :blue # => {amber: 1, blue: 2, c: 3}
example # => {amber: 1, blue: 2, c: 3}
----
===== #reverse_merge
-Merges calling hash into passed in hash without modifying itself.
+Merges calling hash into passed in hash without mutating itself.
[source,ruby]
----
example = {a: 1, b: 2}
example.reverse_merge a: 0, c: 3 # => {a: 1, b: 2, c: 3}
example # => {a: 1, b: 2}
----
===== #reverse_merge!
-Merges calling hash into passed in hash while modifying itself.
+Merges calling hash into passed in hash while mutating itself.
[source,ruby]
----
example = {a: 1, b: 2}
example.reverse_merge! a: 0, c: 3 # => {a: 1, b: 2, c: 3}
@@ -419,11 +465,14 @@
==== Pathname
===== Pathname
-Conversion function (refined from `Kernel`) which can cast `nil` into a pathname.
+Enhances the conversion function -- refined from `Kernel` -- which casts `nil` into a pathname in
+order to avoid: `TypeError (no implicit conversion of nil into String)`. The pathname is still
+invalid but at least you have an instance of `Pathname`, which behaves like a _Null Object_, that
+can still be used to construct a valid path.
[source,ruby]
----
Pathname(nil) # => Pathname("")
----
@@ -575,9 +624,22 @@
Answers string with only first letter downcased.
[source,ruby]
----
"EXAMPLE".down # => "eXAMPLE"
+----
+
+===== #indent
+
+Answers string indented by two spaces by default.
+
+[source,ruby]
+----
+"example".indent # => " example"
+"example".indent 0 # => "example"
+"example".indent -1 # => "example"
+"example".indent 2 # => " example"
+"example".indent 3, padding: " " # => " example"
----
===== #camelcase
Answers a camelcased string.