README.adoc in refinements-10.1.1 vs README.adoc in refinements-11.0.0
- old
+ new
@@ -29,22 +29,38 @@
. https://www.ruby-lang.org[Ruby].
. A solid understanding of link:https://alchemists.io/articles/ruby_refinements[refinements].
== Setup
-To install, run:
+To install _with_ security, run:
[source,bash]
----
+# 💡 Skip this line if you already have the public certificate installed.
+gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
+gem install refinements --trust-policy HighSecurity
+----
+
+To install _without_ security, run:
+
+[source,bash]
+----
gem install refinements
----
-Add the following to your Gemfile file:
+You can also add the gem directly to your project:
+[source,bash]
+----
+bundle add refinements
+----
+
+Once the gem is installed, you only need to require it:
+
[source,ruby]
----
-gem "refinements"
+require "refinements"
----
== Usage
=== Requires
@@ -260,10 +276,50 @@
[1].pad 0 # [1]
[1].pad 0, max: 3 # [1, 0, 0]
[1, 2].pad 3, max: 3 # [1, 2, 3]
----
+===== #pick
+
+Answers value of first element that matches given key.
+
+[source,ruby]
+----
+array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C"}]
+
+array.pick :name # "a"
+array.pick :name, :label # ["a", "A"]
+array.pick # nil
+[].pick(:test) # nil
+----
+
+===== #pluck
+
+Answers values of all elements that match given keys.
+
+[source,ruby]
+----
+array = [{name: "a", label: "A"}, {name: "b", label: "B"}, {name: "c", label: "C"}]
+
+array.pluck :name # ["a", "b", "c"]
+array.pluck :name, :label # [["a", "A"], ["b", "B"], ["c", "C"]]
+array.pluck # []
+[].pluck :test # []
+----
+
+===== #replace_at
+
+Answers mutated array where an element -- at a specific index -- is replaced by single or multiple elements.
+
+[source,ruby]
+----
+%i[a b c].replace_at(0, :x) # [:x, :b, :c]
+%i[a b c].replace_at(1, :x) # [:a, :x, :c]
+%i[a b c].replace_at(1, :x, :y) # [:a, :x, :y, :c]
+%i[a b c].replace_at(-1, :x) # [:a, :b, :x]
+----
+
===== #ring
Answers a circular array which can enumerate before, current, after elements.
[source,ruby]
@@ -301,23 +357,37 @@
%i[a b a].supplant_if :a, %i[z y] # [[:z, :y], :b, [:z, :y]]
----
===== #to_sentence
-Answers a sentence using `", "` as the default delimiter and `"and"` as the default conjunction.
+Answers a sentence using `"and"` as the default conjunction and `", "` as the default delimiter.
Useful when building documentation, answering human readable error messages, etc.
[source,ruby]
----
-[].to_sentence # ""
-["test"].to_sentence # "test"
-["a", :b].to_sentence # "a and b"
-[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_sentence # 1, "a", :b, 2.0, and /\w+/
-%w[one two three].to_sentence # "one, two, and three"
-%w[eins zwei drei].to_sentence delimiter: " ", conjunction: "und" # "eins zwei und drei"
+[].to_sentence # ""
+["test"].to_sentence # "test"
+["a", :b].to_sentence # "a and b"
+[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_sentence # 1, "a", :b, 2.0, and /\w+/
+%w[one two three].to_sentence # "one, two, and three"
+%w[eins zwei drei].to_sentence "und", delimiter: " " # "eins zwei und drei"
----
+===== #to_usage
+
+Builds upon and enhances `#to_sentence` further by answering a sentence which all elements are inspected -- where each element of the array is called with `#inspect` -- before turned into a sentence using `"and"` as the default conjunction and `", "` as the default delimiter. This is useful when providing detailed error messages _and_ you need to show the element types used.
+
+[source,ruby]
+----
+[].to_usage # ""
+["test"].to_usage # "test"
+["a", :b].to_usage # "a and b"
+[1, "a", :b, 2.0, /\w+/].map(&:inspect).to_usage # 1, "a", :b, 2.0, and /\w+/
+%w[one two three].to_usage # "one, two, and three"
+%w[eins zwei drei].to_usage "und", delimiter: " " # "eins zwei und drei"
+----
+
==== Big Decimal
===== #inspect
Allows one to inspect a big decimal with numeric representation.
@@ -811,12 +881,11 @@
Pathname.make_temp_dir { |path| path.join "sub_dir" } # Pathname:/var/folders/T/temp-20200101-16940-r8/sub_dir
----
===== .require_tree
-Requires all files in given root path and corresponding nested tree structure. All files are sorted
-before being required to ensure consistent behavior. Example:
+Requires all Ruby files in given root path and corresponding nested tree structure. All files are sorted before being required to ensure consistent behavior. Example:
[source,ruby]
----
# Before
Dir[File.join(__dir__, "support/shared_contexts/**/*.rb")].sort.each { |path| require path }
@@ -1140,14 +1209,14 @@
Answers indentation (string) which is the result of the multiplier times padding. By default, the multiplier is `1` and the padding is `" "` which equates to two spaces.
[source,ruby]
----
-"example".indent # " example"
-"example".indent 0 # "example"
-"example".indent -1 # "example"
-"example".indent 2 # " example"
-"example".indent 3, padding: " " # " example"
+"example".indent # " example"
+"example".indent 0 # "example"
+"example".indent -1 # "example"
+"example".indent 2 # " example"
+"example".indent 3, pad: " " # " example"
----
===== #last
Answers last character of a string or last set of characters if given a number.