refinements 7.10.0 → 7.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b7b36399c299675bc98b26334acc2466c5c506849e34b36534f21d2eed72e57
-  data.tar.gz: 0d00c8e399a0d43c21dafef5985e9d0eb51fe7d544fbe93f4d184eafa75018a8
+  metadata.gz: 756d9dcbbc60385370835ad8001dd4fb84f6848aba8ca51cbe949fcd2aaa72a4
+  data.tar.gz: f09562bfe5991533c166f5aa0aa215a3f2fe8df3604e85dd3404a7688df67980
 SHA512:
-  metadata.gz: 558191fc552ba160302b9189b8bd2e3ed17ceaee226426cf9453c0c65b8ca0e771b9e85be1e5453c8c1438bc52511a45afc218c72329c17570a6036b65e9f91f
-  data.tar.gz: 69436b5353f1541b644f9ca72346da713bd8bb1c0f9595983392881727f06ea46ecacdea1412a929981ee24e0243865c6ac9274e747f04d3584c85216e7e300b
+  metadata.gz: b37235bf15f3b959dd295a22c3e9c89dff28faa4124da955b0e27b2bef7db505d3093dc56369550d2863e6dc2ca3d10bbfe248da1e7a70f0eaee7fb351bd4e9f
+  data.tar.gz: 0c7aeed58557e626cc6494d761e79c4a0bcb60f42e79d83cef01676c9fd5fbf838dd97f4b89c3234a978455d3acfb6bdd3f715ed55dfed05a92e5f0e86d7426d

data/LICENSE.adoc

@@ -150,7 +150,7 @@ additional liability.
 
 END OF TERMS AND CONDITIONS
 
-Copyright link:https://www.alchemists.io[Alchemists].
+Copyright 2015 link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
 
 Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
 compliance with the License. You may obtain a link:https://www.apache.org/licenses/LICENSE-2.0[copy]

data/README.adoc

@@ -6,6 +6,8 @@
 
 [link=http://badge.fury.io/rb/refinements]
 image::https://badge.fury.io/rb/refinements.svg[Gem Version]
+[link=https://www.alchemists.io/projects/code_quality]
+image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
 [link=https://circleci.com/gh/bkuhlmann/refinements]
 image::https://circleci.com/gh/bkuhlmann/refinements.svg?style=svg[Circle CI Status]
 
@@ -22,9 +24,11 @@ Enhances the following objects:
 * DateTime
 * File
 * Hash
+* IO
 * Pathname
 * String
 * StringIO
+* Structs
 
 == Requirements
 
@@ -34,8 +38,6 @@ Enhances the following objects:
 
 == Setup
 
-=== Production
-
 To install, run:
 
 [source,bash]
@@ -50,24 +52,6 @@ Add the following to your Gemfile file:
 gem "refinements"
 ----
 
-=== Development
-
-To contribute, run:
-
-[source,bash]
-----
-git clone https://github.com/bkuhlmann/refinements.git
-cd refinements
-bin/setup
-----
-
-You can also use the IRB console for direct access to all objects:
-
-[source,bash]
-----
-bin/console
-----
-
 == Usage
 
 === Requires
@@ -79,7 +63,7 @@ If all refinements are not desired, add the following to your `+Gemfile+` instea
 gem "refinements", require: false
 ----
 
-…then require the specific refinement, as needed. Example:
+...then require the specific refinement, as needed. Example:
 
 [source,ruby]
 ----
@@ -88,9 +72,11 @@ require "refinements/big_decimals"
 require "refinements/date_times"
 require "refinements/files"
 require "refinements/hashes"
+require "refinements/ios"
 require "refinements/pathnames"
 require "refinements/strings"
 require "refinements/string_ios"
+require "refinements/structs"
 ----
 
 === Using
@@ -106,9 +92,11 @@ class Example
   using Refinements::DateTimes
   using Refinements::Files
   using Refinements::Hashes
+  using Refinements::IOs
   using Refinements::Pathnames
   using Refinements::Strings
   using Refinements::StringIOs
+  using Refinements::Structs
 end
 ----
 
@@ -140,24 +128,47 @@ example.compress!  # => ["An", "Example"]
 example            # => ["An", "Example"]
 ----
 
-===== #include
+===== #excluding
+
+Removes given array or elements without mutating itself.
+
+[source,ruby]
+----
+[1, 2, 3, 4, 5].excluding [4, 5]  # => [1, 2, 3]
+[1, 2, 3, 4, 5].excluding 4, 5    # => [1, 2, 3]
+----
+
+===== #including
 
 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]
+[1, 2, 3].including [4, 5]  # => [1, 2, 3, 4, 5]
+[1, 2, 3].including 4, 5    # => [1, 2, 3, 4, 5]
 ----
 
-===== #exclude
+===== #intersperse
 
-Removes given array or elements without mutating itself.
+Inserts additional elements or array between all members of given array.
+
+[source,ruby]
+----
+[1, 2, 3].intersperse :a         # => [1, :a, 2, :a, 3]
+[1, 2, 3].intersperse :a, :b     # => [1, :a, :b, 2, :a, :b, 3]
+[1, 2, 3].intersperse %i[a b c]  # => [1, :a, :b, :c, 2, :a, :b, :c, 3]
+----
+
+===== #mean
+
+Answers mean/average all elements within an array.
 
 [source,ruby]
 ----
-[1, 2, 3, 4, 5].exclude [4, 5]  # => [1, 2, 3]
-[1, 2, 3, 4, 5].exclude 4, 5    # => [1, 2, 3]
+[].mean                 # => 0
+[5].mean                # => 5
+[1, 2, 3].mean          # => 2
+[1.25, 1.5, 1.75].mean  # => 1.5
 ----
 
 ===== #ring
@@ -235,6 +246,72 @@ example = Hash.with_default []
 example[:b] # => []
 ----
 
+===== #deep_merge
+
+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 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 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 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}}
+----
+
 ===== #except
 
 Answers new hash with given keys removed without mutating itself.
@@ -287,217 +364,216 @@ example.flatten_keys!  # => {a_b: 1}
 example                # => {a_b: 1}
 ----
 
-===== #stringify_keys
+===== #recurse
 
-Converts keys to strings without mutating itself.
+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: 1, b: 2}
-example.stringify_keys  # => {"a" => 1, "b" => 2}
-example                 # => {a: 1, b: 2}
+example = {"a" => {"b" => 1}}
+example.recurse(&:symbolize_keys)  # => {a: {b: 1}}
+example.recurse(&:invert)          # => {{"b" => 1} => "a"}
 ----
 
-===== #stringify_keys!
+===== #rekey
 
-Converts keys to strings while mutating itself.
+Transforms keys per mapping (size of mapping can vary) without mutating itself.
 
 [source,ruby]
 ----
-example = {a: 1, b: 2}
-example.stringify_keys!  # => {"a" => 1, "b" => 2}
-example                  # => {"a" => 1, "b" => 2}
+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}
 ----
 
-===== #symbolize_keys
+===== #rekey!
 
-Converts keys to symbols without mutating itself.
+Transforms keys per mapping (size of mapping can vary) while mutating itself.
 
 [source,ruby]
 ----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys  # => {a: 1, b: 2}
-example                 # => {"a" => 1, "b" => 2}
+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}
 ----
 
-===== #symbolize_keys!
+===== #reverse_merge
 
-Converts keys to symbols while mutating itself.
+Merges calling hash into passed in hash without mutating itself.
 
 [source,ruby]
 ----
-example = {"a" => 1, "b" => 2}
-example.symbolize_keys!  # => {a: 1, b: 2}
-example                  # => {a: 1, b: 2}
+example = {a: 1, b: 2}
+example.reverse_merge a: 0, c: 3  # => {a: 1, b: 2, c: 3}
+example                           # => {a: 1, b: 2}
 ----
 
-===== #deep_merge
+===== #reverse_merge!
 
-Merges deeply nested hashes together without mutating itself.
+Merges calling hash into passed in hash 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: "One", two: "Two"}}
+example = {a: 1, b: 2}
+example.reverse_merge! a: 0, c: 3  # => {a: 1, b: 2, c: 3}
+example                            # => {a: 1, b: 2, c: 3}
 ----
 
-===== #deep_merge!
+===== #stringify_keys
 
-Merges deeply nested hashes together while mutating itself.
+Converts keys to strings 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: 1, two: "Two"}}
+example = {a: 1, b: 2}
+example.stringify_keys  # => {"a" => 1, "b" => 2}
+example                 # => {a: 1, b: 2}
 ----
 
-===== #deep_stringify_keys
+===== #stringify_keys!
 
-Stringifies keys of nested hash without mutating itself. Does not handle nested arrays, though.
+Converts keys to strings while mutating itself.
 
 [source,ruby]
 ----
-example = {a: {b: 2}}
-example.deep_stringify_keys  # => {"a" => {"b" => 1}}
-example                      # => {a: {b: 2}}
+example = {a: 1, b: 2}
+example.stringify_keys!  # => {"a" => 1, "b" => 2}
+example                  # => {"a" => 1, "b" => 2}
 ----
 
-===== #deep_stringify_keys!
+===== #symbolize_keys
 
-Stringifies keys of nested hash while mutating itself. Does not handle nested arrays, though.
+Converts keys to symbols without mutating itself.
 
 [source,ruby]
 ----
-example = {a: {b: 2}}
-example.deep_stringify_keys!  # => {"a" => {"b" => 1}}
-example                       # => {"a" => {"b" => 1}}
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys  # => {a: 1, b: 2}
+example                 # => {"a" => 1, "b" => 2}
 ----
 
-===== #deep_symbolize_keys
+===== #symbolize_keys!
 
-Symbolizes keys of nested hash without mutating itself. Does not handle nested arrays, though.
+Converts keys to symbols while mutating itself.
 
 [source,ruby]
 ----
-example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys  # => {a: {b: 1}}
-example                      # => {"a" => {"b" => 2}}
+example = {"a" => 1, "b" => 2}
+example.symbolize_keys!  # => {a: 1, b: 2}
+example                  # => {a: 1, b: 2}
 ----
 
-===== #deep_symbolize_keys!
+===== #use
 
-Symbolizes keys of nested hash while mutating itself. Does not handle nested arrays, though.
+Passes each hash value as a block argument for further processing.
 
 [source,ruby]
 ----
-example = {"a" => {"b" => 2}}
-example.deep_symbolize_keys!  # => {a: {b: 1}}
-example                       # => {a: {b: 1}}
+example = {unit: "221B", street: "Baker Street", city: "London", country: "UK"}
+example.use { |unit, street| "#{unit} #{street}" } # => "221B Baker Street"
 ----
 
-===== #recurse
-
-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"}
-----
+==== IO
 
-===== #rekey
+===== .void
 
-Transforms keys per mapping (size of mapping can vary) without mutating itself.
+Answers an IO stream which points to `/dev/null` in order to ignore any reads or writes to the
+stream. When given a block, the stream will automatically close upon block exit. When not given a
+block, you'll need to close the stream manually.
 
 [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}
+io = IO.void                                    # => #<IO:fd 20>
+io = IO.void { |void| void.write "nevermore" }  # => #<IO:(closed)>
 ----
 
-===== #rekey!
+===== #redirect
 
-Transforms keys per mapping (size of mapping can vary) while mutating itself.
+Redirects current stream to other stream when given a block. Without a block, the original stream is
+answered instead.
 
 [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}
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+other = IO.new IO.sysopen(Pathname("other.txt").to_s, "w+")
+
+io.redirect other                                    # => #<IO:fd 20>
+io.redirect(other) { |stream| stream.write "test" }  # => #<IO:fd 21>
 ----
 
-===== #reverse_merge
+===== #reread
 
-Merges calling hash into passed in hash without mutating itself.
+Answers full stream by rewinding to beginning of stream and reading all content.
 
 [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!
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.write "This is a test."
 
-Merges calling hash into passed in hash while mutating itself.
+io.reread    # => "This is a test."
+io.reread 4  # => "This"
 
-[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, c: 3}
+buffer = "".dup
+io.reread(buffer: buffer)  # => "This is a test."
+buffer                     # => "This is a test."
 ----
 
-===== #use
+===== #squelch
 
-Passes each hash value as a block argument for further processing.
+Temporarily ignores any reads/writes for code executed within a block. Answers itself without any
+arguments or when given a block.
 
 [source,ruby]
 ----
-example = {unit: "221B", street: "Baker Street", city: "London", country: "UK"}
-example.use { |unit, street| "#{unit} #{street}" } # => "221B Baker Street"
+io = IO.new IO.sysopen(Pathname("test.txt").to_s, "w+")
+io.squelch                      # => #<IO:fd 20>
+io.squelch { io.write "Test" }  # => #<IO:fd 20>
+io.reread                       # => ""
 ----
 
 ==== Pathname
 
 ===== 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.
+Enhances the `Kernel` conversion function which casts `nil` into a pathname in order to avoid:
+`TypeError (no implicit conversion of nil into String)`. The pathname remains invalid but at least
+you have an instance of `Pathname`, which behaves like a _Null Object_, that can be used to
+construct a valid path.
 
 [source,ruby]
 ----
 Pathname(nil) # => Pathname("")
 ----
 
-===== #name
+===== #change_dir
 
-Answers file name without extension.
+Inherits and wraps `Dir.chdir` behavior by changing to directory of current path. See
+link:https://rubyapi.org/2.7/o/s?q=Dir.chdir[Dir.chdir] for details.
 
 [source,ruby]
 ----
-Pathname("example.txt").name # => Pathname("example")
+Pathname.pwd                           # => "/"
+Pathname("/test").make_dir.change_dir  # => Pathname "/test"
+Pathname.pwd                           # => "/test"
+
+Pathname.pwd                                         # => "/"
+Pathname("/test").make_dir.change_dir { "example" }  # => "example"
+Pathname.pwd                                         # => "/"
 ----
 
 ===== #copy
 
-Copies file from current location to new location.
+Copies file from current location to new location while answering itself so it can be chained.
 
 [source,ruby]
 ----
-Pathname("input.txt").copy Pathname("output.txt")
+Pathname("input.txt").copy Pathname("output.txt")  # => Pathname("input.txt")
 ----
 
 ===== #directories
 
-Answers all or filtered directories for current path.
+Answers all directories or filtered directories for current path.
 
 [source,ruby]
 ----
@@ -517,7 +593,7 @@ Pathname("example.txt.erb").extensions # => [".txt", ".erb"]
 
 ===== #files
 
-Answers all or filtered files for current path.
+Answers all files or filtered files for current path.
 
 [source,ruby]
 ----
@@ -539,6 +615,48 @@ Pathname("/%placeholder%/some/%placeholder%").gsub("%placeholder%", "test")
 # => Pathname("/test/some/test")
 ----
 
+===== #make_ancestors
+
+Ensures all ancestor directories are created for a path.
+
+[source,ruby]
+----
+Pathname("/one/two").make_ancestors  # => Pathname("/one/two")
+Pathname("/one").exist?              # => true
+Pathname("/one/two").exist?          # => false
+----
+
+===== #make_dir
+
+Provides alternative `#mkdir` behavior by always answering itself (even when directory exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
+
+[source,ruby]
+----
+Pathname("/one").make_dir           # => Pathname("/one")
+Pathname("/one").make_dir.make_dir  # => Pathname("/one")
+----
+
+===== #make_path
+
+Provides alternative `#mkpath` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
+
+[source,ruby]
+----
+Pathname("/one/two/three").make_path            # => Pathname("/one/two/three")
+Pathname("/one/two/three").make_path.make_path  # => Pathname("/one/two/three")
+----
+
+===== #name
+
+Answers file name without extension.
+
+[source,ruby]
+----
+Pathname("example.txt").name # => Pathname("example")
+----
+
 ===== #relative_parent
 
 Answers relative path from parent directory. This is a complement to `#relative_path_from`.
@@ -548,59 +666,74 @@ Answers relative path from parent directory. This is a complement to `#relative_
 Pathname("/one/two/three").relative_parent("/one") # => Pathname "two"
 ----
 
-===== #make_ancestors
+===== #remove_dir
 
-Ensures all ancestor directories are created for a path.
+Provides alternative `#rmdir` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
 
 [source,ruby]
 ----
-Pathname("/one/two").make_ancestors
-Pathname("/one").exist?      # => true
-Pathname("/one/two").exist?  # => false
+Pathname("/test").make_dir.remove_dir.exist?  # => false
+Pathname("/test").remove_dir                  # => Pathname("/test")
+Pathname("/test").remove_dir.remove_dir       # => Pathname("/test")
 ----
 
-===== #rewrite
+===== #remove_tree
 
-When given a block, it provides the contents of the recently read file for manipulation and
-immediate writing back to the same file.
+Provides alternative `#rmtree` behavior by always answering itself (even when full path exists) and
+not throwing errors when directory does exist in order to ensure the pathname can be chained.
 
 [source,ruby]
 ----
-Pathname("/test.txt").rewrite { |content| content.sub "[placeholder]", "example" }
+parent_path = Pathname "/one"
+child_path = parent_path.join "two"
+
+child_path.make_path
+child_path.remove_tree  # => Pathname "/one/two"
+child_path.exist?       # => false
+paremt_path.exist?      # => true
+
+child_path.make_path
+parent_path.remove_tree  # => Pathname "/one"
+child_path.exist?        # => false
+parent_path.exist?       # => false
 ----
 
-===== #touch
+===== #rewrite
 
-Updates access and modification times for path. Defaults to current time.
+When given a block, it provides the contents of the recently read file for manipulation and
+immediate writing back to the same file.
 
 [source,ruby]
 ----
-Pathname("example.txt").touch
-Pathname("example.txt").touch at: Time.now - 1
+Pathname("/test.txt").rewrite                                           # => Pathname("/test.txt")
+Pathname("/test.txt").rewrite { |body| body.sub "[token]", "example" }  # => Pathname("/test.txt")
 ----
 
-==== String
-
-===== #first
+===== #touch
 
-Answers first character of a string or first set of characters if given a number.
+Updates access and modification times for path. Defaults to current time.
 
 [source,ruby]
 ----
-"example".first    # => "e"
-"example".first 4  # => "exam"
+Pathname("example.txt").touch                   # => Pathname("example.txt")
+Pathname("example.txt").touch at: Time.now - 1  # => Pathname("example.txt")
 ----
 
-===== #last
+===== #write
 
-Answers last character of a string or last set of characters if given a number.
+Writes to file and answers itself so it can be chained. See `IO.write` for details on additional
+options.
 
 [source,ruby]
 ----
-"instant".last    # => "t"
-"instant".last 3  # => "ant"
+Pathname("example.txt").write "test"             # => Pathname("example.txt")
+Pathname("example.txt").write "test", offset: 1  # => Pathname("example.txt")
+Pathname("example.txt").write "test", mode: "a"  # => Pathname("example.txt")
 ----
 
+==== String
+
 ===== #blank?
 
 Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`, and/or `\r`.
@@ -610,13 +743,13 @@ Answers `true`/`false` based on whether string is blank, `<space>`, `\n`, `\t`,
 " \n\t\r".blank? # => true
 ----
 
-===== #up
+===== #camelcase
 
-Answers string with only first letter upcased.
+Answers a camelcased string.
 
 [source,ruby]
 ----
-"example".up # => "Example"
+"this_is_an_example".camelcase # => "ThisIsAnExample"
 ----
 
 ===== #down
@@ -628,6 +761,16 @@ Answers string with only first letter downcased.
 "EXAMPLE".down # => "eXAMPLE"
 ----
 
+===== #first
+
+Answers first character of a string or first set of characters if given a number.
+
+[source,ruby]
+----
+"example".first    # => "e"
+"example".first 4  # => "exam"
+----
+
 ===== #indent
 
 Answers string indented by two spaces by default.
@@ -641,13 +784,14 @@ Answers string indented by two spaces by default.
 "example".indent 3, padding: " "  # => "   example"
 ----
 
-===== #camelcase
+===== #last
 
-Answers a camelcased string.
+Answers last character of a string or last set of characters if given a number.
 
 [source,ruby]
 ----
-"this_is_an_example".camelcase # => "ThisIsAnExample"
+"instant".last    # => "t"
+"instant".last 3  # => "ant"
 ----
 
 ===== #snakecase
@@ -681,6 +825,15 @@ Answers string as a boolean.
 "example".to_bool  # => false
 ----
 
+===== #up
+
+Answers string with only first letter upcased.
+
+[source,ruby]
+----
+"example".up # => "Example"
+----
+
 ==== String IO
 
 ===== #reread
@@ -696,8 +849,70 @@ io.reread    # => "This is a test."
 io.reread 4  # => "This"
 
 buffer = "".dup
-io.reread(buffer: buffer)
-buffer # => "This is a test."
+io.reread(buffer: buffer)  # => "This is a test."
+buffer                     # => "This is a test."
+----
+
+==== Struct
+
+===== #merge
+
+Merges multiple attributes without mutating itself.
+
+[source,ruby]
+----
+Example = Struct.new :a, :b, :c
+example = Example[1, 2, 3]
+example.merge a: 10                # => #<struct a=10, b=2, c=3>
+example.merge a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                            # => #<struct a=1, b=2, c=3>
+
+Example = Struct.new :a, :b, :c, keyword_init: true
+example = Example[a: 1, b: 2, c: 3]
+example.merge a: 10                # => #<struct a=10, b=2, c=3>
+example.merge a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                            # => #<struct a=1, b=2, c=3>
+----
+
+===== #merge!
+
+Merges multiple attributes while mutating itself.
+
+[source,ruby]
+----
+Example = Struct.new :a, :b, :c
+example = Example[1, 2, 3]
+example.merge! a: 10                # => #<struct a=10, b=2, c=3>
+example.merge! a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge! a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                             # => #<struct a=10, b=20, c=30>
+
+Example = Struct.new :a, :b, :c, keyword_init: true
+example = Example[a: 1, b: 2, c: 3]
+example.merge! a: 10                # => #<struct a=10, b=2, c=3>
+example.merge! a: 10, c: 30         # => #<struct a=10, b=2, c=30>
+example.merge! a: 10, b: 20, c: 30  # => #<struct a=10, b=20, c=30>
+example                             # => #<struct a=10, b=20, c=30>
+----
+
+== Development
+
+To contribute, run:
+
+[source,bash]
+----
+git clone https://github.com/bkuhlmann/refinements.git
+cd refinements
+bin/setup
+----
+
+You can also use the IRB console for direct access to all objects:
+
+[source,bash]
+----
+bin/console
 ----
 
 == Tests