backports 3.18.0 → 3.23.0

data/README.md

@@ -1,6 +1,7 @@
 # Backports Library [<img src="https://travis-ci.org/marcandre/backports.svg?branch=master">](https://travis-ci.org/marcandre/backports) [<img src="https://badge.fury.io/rb/backports.svg" alt="Gem Version" />](http://badge.fury.io/rb/backports) [![Tidelift](https://tidelift.com/badges/package/rubygems/backports)](https://tidelift.com/subscription/pkg/rubygems-backports?utm_source=rubygems-backports&utm_medium=referral&utm_campaign=readme)
 
-Yearning to use some of the new cool features in Ruby 2.7 while using 2.3.x?
+Yearning to write a gem using some new cool features in Ruby 3.1 while
+still supporting Ruby 2.5.x?
 Have some legacy code in Ruby 1.8 but can't live without `flat_map`?
 
 This gem is for you!
@@ -9,20 +10,20 @@ The goal of 'backports' is to make it easier to write ruby code that runs
 across different versions of Ruby.
 
 Note: [Next major version (X-mas
-2020)](https://github.com/marcandre/backports/issues/139) will drop support
+2021?)](https://github.com/marcandre/backports/issues/139) may drop support
 for Ruby < 2.2.
 
 ## Loading backports
 
 ### Explicitly (recommended)
 
-For example, if you want to use transform_values and transform_keys, even in
+For example, if you want to use `transform_values` and `transform_keys`, even in
 Ruby implementations that don't include it:
 
     require 'backports/2.4.0/hash/transform_values'
     require 'backports/2.5.0/hash/transform_keys'
 
-This will enable Hash#transform_values and Hash#transform_keys, using the
+This will enable `Hash#transform_values` and `Hash#transform_keys`, using the
 native versions if available or otherwise provide a pure Ruby version.
 
 ### By Module
@@ -32,32 +33,31 @@ Class:
 
     require 'backports/2.3.0/hash'
 
-This will make sure that Hash responds to dig, fetch_values, <, <=, >, >= and
-to_proc
+This will make sure that Hash responds to `dig`, `fetch_values`, `to_proc` and comparisons.
 
 ### Up to a specific Ruby version (for quick coding)
 
 You can load all backports up to a specific version.
-For example, to bring any
-version of Ruby mostly up to Ruby 2.7.0's standards:
+For example, to bring any version of Ruby mostly up to Ruby 3.1.0's standards:
 
-    require 'backports/2.7.0'
+    require 'backports/3.1.0'
 
 This will bring in all the features of 1.8.7 and many features of Ruby 1.9.x
-all the way up to Ruby 2.7.0 (for all versions of Ruby)!
+all the way up to Ruby 3.1.0 (for all versions of Ruby)!
 
 You may `require 'backports/latest'` as a
 shortcut to the latest Ruby version supported.
 
-*Note*: For production / public gems, it is highly recommended you only require
+_Note_: For production / public gems, it is highly recommended you only require
 the backports you need explicitly.
 
-*Note*: Although I am a Ruby committer, this gem is a personal project and is
+_Note_: Although I am a Ruby committer, this gem is a personal project and is
 not endorsed by ruby-core.
 
 ## What's inside
 
 Goals for backported features:
+
 1.  Won't break older code
 2.  Pure Ruby (no C extensions)
 3.  Pass [ruby/spec](https://github.com/ruby/spec)
@@ -109,328 +109,467 @@ itself, JRuby and Rubinius.
 
 # Complete List of backports
 
+## Ruby 3.1 backports
+
+#### Array
+
+- `intersect?`
+
+#### Class
+
+- `descendants`
+- `subclasses`
+
+#### Enumerable
+
+- `compact`
+- `tally` (with hash argument)
+
+### File
+
+- `dirname` (with depth argument)
+
+#### Integer
+
+- `try_convert`
+
+#### MatchData
+
+- `match`
+- `match_length`
+
+#### Struct
+
+- `keyword_init?`
+
+## Ruby 3.0 backports
+
+#### Env
+
+- `except`
+
+#### Hash
+
+- `except`
+- `transform_keys`, `transform_keys!` (with hash argument)
+
+#### Ractor
+
+- All methods, with the caveats:
+  - uses Ruby's `Thread` internally
+  - will not raise some errors when `Ractor` would (in particular `Ractor::IsolationError`)
+  - supported in Ruby 2.0+ only
+
+#### Symbol
+
+- `name`
+
 ## Ruby 2.7 backports
 
 #### Array
-  - `intersection`
+
+- `intersection`
 
 #### Comparable
-  - `clamp` (with range)
+
+- `clamp` (with range)
 
 #### Complex
-  - +<=>+
+
+- `<=>`
 
 #### Enumerable
-  - `filter_map`
-  - `tally`
+
+- `filter_map`
+- `tally`
 
 #### Enumerator
-  - `produce` (class method)
+
+- `produce` (class method)
+
+#### Symbol
+  - `end_with?`
 
 #### Time
-  - `floor`, `ceil`
+
+- `floor`, `ceil`
 
 ## Ruby 2.6 backports
 
 #### Array
-  - `difference`, `union`
-  - `to_h` (with block)
+
+- `difference`, `union`
+- `to_h` (with block)
 
 #### Enumerable
-  - `chain`
-  - `to_h` (with block)
+
+- `chain`
+- `to_h` (with block)
 
 #### Enumerator::Chain (use Enumerable#chain)
 
 #### Hash
-  - `merge`, `merge!`/`update` (with multiple arguments)
-  - `to_h` (with block)
+
+- `merge`, `merge!`/`update` (with multiple arguments)
+- `to_h` (with block)
 
 #### Kernel
-  - `then`
+
+- `then`
 
 #### Method
-  - +<<+, +>>+
+
+- `<<`, `>>`
 
 #### Proc
-  - +<<+, +>>+
+
+- `<<`, `>>`
 
 #### Range
-  - `cover?` (with `Range` argument)
+
+- `cover?` (with `Range` argument)
 
 ## Ruby 2.5 backports
 
 #### Array
-  - `append`, `prepend`
+
+- `append`, `prepend`
 
 #### Dir
-  - `children`, `each_child`
+
+- `children`, `each_child`
 
 #### Enumerable
-  - `any?`, `all?`, `none?`, `one?` (with pattern argument)
+
+- `any?`, `all?`, `none?`, `one?` (with pattern argument)
 
 #### Hash
-  - `slice`
-  - `transform_keys`
+
+- `slice`
+- `transform_keys`
 
 #### Integer
-  - `sqrt`
-  - `allbits?`, `anybits?` and `nobits?`
+
+- `sqrt`
+- `allbits?`, `anybits?` and `nobits?`
 
 #### Kernel
-  - `yield_self`
+
+- `yield_self`
 
 #### Module
-  - `attr`, `attr_accessor`, `attr_reader`, `attr_writer` (now public)
-  - `define_method`, `alias_method`, `undef_method`, `remove_method` (now
-        public)
+
+- `attr`, `attr_accessor`, `attr_reader`, `attr_writer` (now public)
+- `define_method`, `alias_method`, `undef_method`, `remove_method` (now
+  public)
 
 #### String
-  - `delete_prefix`, `delete_prefix!`
-  - `delete_suffix`, `delete_suffix!`
-  - `undump`
+
+- `delete_prefix`, `delete_prefix!`
+- `delete_suffix`, `delete_suffix!`
+- `undump`
 
 #### Struct
-  - `new` (with `keyword_init: true`)
+
+- `new` (with `keyword_init: true`)
 
 ## Ruby 2.4 backports
 
 #### Comparable
-  - `clamp`
+
+- `clamp`
 
 #### Enumerable
-  - `sum`
-  - `uniq`
+
+- `sum`
+- `uniq`
 
 #### Hash
-  - `compact`, `compact!`
-  - `transform_values`, `transform_values!`
+
+- `compact`, `compact!`
+- `transform_values`, `transform_values!`
+
+#### Queue
+
+- `close`, `closed?`
 
 #### Regexp
-  - `match?`
+
+- `match?`
 
 #### String
-  - `match?`
 
-#### FalseClass, Fixnum, Float, NilClass, TrueClass
-  - `dup`
+- `match?`
+- `unpack1`
+
+#### FalseClass, Fixnum, Bignum, Float, NilClass, TrueClass
+
+- `dup`
 
 ## Ruby 2.3 backports
 
 #### Array
-  - `bsearch_index`
-  - `dig`
+
+- `bsearch_index`
+- `dig`
 
 #### Enumerable
-  - `chunk_while`
-  - `grep_v`
+
+- `chunk_while`
+- `grep_v`
 
 #### Hash
-  - `dig`
-  - `fetch_values`
-  - `to_proc`
-  - <=, <, >=, >
+
+- `dig`
+- `fetch_values`
+- `to_proc`
+- <=, <, >=, >
 
 #### Numeric
-  - `negative?`
-  - `positive?`
+
+- `negative?`
+- `positive?`
 
 #### String
-  - unary + and -
+
+- unary + and -
 
 #### Struct
-  - `dig`
+
+- `dig`
 
 ## Ruby 2.2 backports
 
 #### Enumerable
-  - `slice_after`
-  - `slice_when`
+
+- `slice_after`
+- `slice_when`
 
 #### Float
-  - `prev_float`
-  - `next_float`
+
+- `prev_float`
+- `next_float`
 
 #### Kernel
-  - `itself`
+
+- `itself`
 
 #### Method
-  - `curry`
-  - `super_method`
+
+- `curry`
+- `super_method`
 
 #### String
-  - `unicode_normalize`
-  - `unicode_normalize!`
-  - `unicode_normalize?`
+
+- `unicode_normalize`
+- `unicode_normalize!`
+- `unicode_normalize?`
 
 ## Ruby 2.1 backports
 
 #### Array
-  - `to_h`
+
+- `to_h`
 
 #### Bignum
-  - `bit_length`
+
+- `bit_length`
 
 #### Enumerable
-  - `to_h`
+
+- `to_h`
 
 #### Fixnum
-  - `bit_length`
+
+- `bit_length`
 
 #### Module
-  - `include` (now public)
+
+- `include` (now public)
+- `singleton_class?`
 
 ## Ruby 2.0 backports
 
 #### Array
-  - `bsearch`
+
+- `bsearch`
 
 #### Enumerable
-  - `lazy`
+
+- `lazy`
 
 #### Enumerator::Lazy
-  - all methods
+
+- all methods
 
 #### Hash
-  - `default_proc=` (with nil argument)
-  - `to_h`
+
+- `default_proc=` (with nil argument)
+- `to_h`
 
 #### `nil.to_h`
 
 #### Range
-  - `bsearch`
+
+- `bsearch`
 
 #### Struct
-  - `to_h`
+
+- `to_h`
 
 ## Ruby 1.9.3 backports
 
 #### File
-  - `NULL`
+
+- `NULL`
 
 #### IO
-  - `advise` (acts as a noop)
-  - `write`, `binwrite`
+
+- `advise` (acts as a noop)
+- `write`, `binwrite`
 
 #### String
-  - `byteslice`
-  - `prepend`
+
+- `byteslice`
+- `prepend`
 
 ## Ruby 1.9.2 backports
 
 #### Array
-  - `rotate, rotate!`
-  - `keep_if, select!`
-  - `product` (with block)
-  - `repeated_combination`, `repeated_permutation`
-  - `sort_by!`
-  - `uniq, uniq!` (with block)
+
+- `rotate, rotate!`
+- `keep_if, select!`
+- `product` (with block)
+- `repeated_combination`, `repeated_permutation`
+- `sort_by!`
+- `uniq, uniq!` (with block)
 
 #### Complex
-  - `to_r`
+
+- `to_r`
 
 #### Dir
-  - `home`
+
+- `home`
 
 #### Enumerable
-  - `chunk`
-  - `flat_map`, `collect_concat`
-  - `join`
-  - `slice_before`
+
+- `chunk`
+- `flat_map`, `collect_concat`
+- `join`
+- `slice_before`
 
 #### Float::INFINITY, NAN
 
 #### Hash
-  - `keep_if`, `select!`
+
+- `keep_if`, `select!`
 
 #### Object
-  - `singleton_class`
+
+- `singleton_class`
 
 #### Random (new class)
 
-*Note*: The methods of `Random` can't be required individually; the class
+_Note_: The methods of `Random` can't be required individually; the class
 can only be required whole with `require 'backports/1.9.2/random'`.
 
 ## Ruby 1.9.1 backports
 
 Additionally, the following Ruby 1.9 features have been backported:
+
 #### Array
-  - `try_convert`
-  - `sample`
+
+- `try_convert`
+- `sample`
 
 #### Enumerable
-  - `each_with_object`
-  - `each_with_index` (with arguments)
+
+- `each_with_object`
+- `each_with_index` (with arguments)
 
 #### Enumerator
-  - `new` (with block)
+
+- `new` (with block)
 
 #### File
-  - `binread`
-  - `to_path`
-  - All class methods accepting filenames will accept files or anything
-        with a `#to_path` method.
-  - `File.open` accepts an options hash.
+
+- `binread`
+- `to_path`
+- All class methods accepting filenames will accept files or anything
+  with a `#to_path` method.
+- `File.open` accepts an options hash.
 
 #### Float
-  - `round`
+
+- `round`
 
 #### Hash
-  - `assoc`, `rassoc`
-  - `key`
-  - `try_convert`
-  - `default_proc=`
+
+- `assoc`, `rassoc`
+- `key`
+- `try_convert`
+- `default_proc=`
 
 #### Integer
-  - `magnitude`
-  - `round`
+
+- `magnitude`
+- `round`
 
 #### IO
-  - `bin_read`
-  - `try_convert`
-  - `ungetbyte`
-  - `IO.open` accepts an options hash.
+
+- `bin_read`
+- `try_convert`
+- `ungetbyte`
+- `IO.open` accepts an options hash.
 
 #### Kernel
-  - `require_relative`
+
+- `require_relative`
 
 #### Math
-  - `log` (with base)
-  - `log2`
+
+- `log` (with base)
+- `log2`
 
 #### Numeric
-  - `round`
+
+- `round`
 
 #### Object
-  - `define_singleton_method`
-  - `public_method`
-  - `public_send`
+
+- `define_singleton_method`
+- `public_method`
+- `public_send`
 
 #### Proc
-  - `yield`
-  - `lambda?`
-  - `curry`
-  - `===`
+
+- `yield`
+- `lambda?`
+- `curry`
+- `===`
 
 #### Range
-  - `cover?`
+
+- `cover?`
 
 #### Regexp
-  - `try_convert`
+
+- `try_convert`
 
 #### String
-  - `ascii_only?`
-  - `chr`
-  - `clear`
-  - `codepoints`, `each_codepoint`
-  - `get_byte`, `set_byte`
-  - `ord`
-  - `try_convert`
+
+- `ascii_only?`
+- `chr`
+- `clear`
+- `codepoints`, `each_codepoint`
+- `get_byte`, `set_byte`
+- `ord`
+- `try_convert`
 
 `Enumerator` can be accessed directly (instead of `Enumerable::Enumerator`)
 
-To include *only* these backports and those of the 1.8 line, `require
-"backports/1.9.1"`.
+To include _only_ these backports and those of the 1.8 line, `require "backports/1.9.1"`.
 
 Moreover, a pretty good imitation of `BasicObject` is available, but since it
 is only an imitation, it must be required explicitly:
@@ -444,8 +583,11 @@ Complete Ruby 1.8.7 backporting (core language). Refer to the official list of
 backports!
 
 Only exceptions:
+
 #### String#gsub (the form returning an enumerator)
-#### GC.stress=  (not implemented)
+
+#### GC.stress= (not implemented)
+
 #### Array#choice (removed in 1.9, use 1.9.1's Array#sample instead)
 
 ## Libraries
@@ -457,7 +599,9 @@ The backports would be automatically used after requiring 'backports/std_lib' bu
 The following libraries are up to date with Ruby 1.9.3:
 
 #### Matrix
+
 #### Prime
+
 #### Set
 
 The following library is to date with Ruby 2.0.0:
@@ -468,6 +612,7 @@ I am aware of the following backport gem, which probably won't make it into
 this gem:
 
 #### Net::SMTP for Ruby 1.8.6:
+
     [smtp_tls](http://seattlerb.rubyforge.org/smtp_tls/)
 
 Requiring backports for a given version of Ruby will also load
@@ -480,13 +625,16 @@ but could be useful in some projects. It is possible to request such
 incompatible changes. Backports currently supports the following:
 
 #### Hash
-  - `select` (returns a Hash instead of an Array)
+
+- `select` (returns a Hash instead of an Array)
 
 #### Enumerable / Array
-  - `map` (returns an enumerator when called without a block)
+
+- `map` (returns an enumerator when called without a block)
 
 #### String
-  - `length`, `size` (for UTF-8 support)
+
+- `length`, `size` (for UTF-8 support)
 
 These must be imported in addition to the backports gem, for example:
 
@@ -498,8 +646,11 @@ These must be imported in addition to the backports gem, for example:
 Thanks for the bug reports and patches, in particular the repeat offenders:
 
 #### Arto Bendiken ( [bendiken](http://github.com/bendiken) )
+
 #### Konstantin Haase ( [rkh](https://github.com/rkh) )
+
 #### Roger Pack ( [rdp](http://github.com/rdp) )
+
 #### Victor Shepelev ( [zverok](http://github.com/zverok) )
 
 ## Contributing
@@ -525,5 +676,4 @@ Failures that are acceptable are added the to `tags` file.
 LICENSE file.
 
 Author
-:   Marc-André Lafortune
-
+: Marc-André Lafortune