facets 4.0.1 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. checksums.yaml +4 -4
  2. data/CONTRIBUTING.md +10 -0
  3. data/HISTORY.md +222 -0
  4. data/README.md +2 -2
  5. data/lib/core/facets/array/commonality.rb +1 -1
  6. data/lib/core/facets/array/delete_first.rb +6 -5
  7. data/lib/core/facets/array/divide.rb +1 -1
  8. data/lib/core/facets/array/from_base.rb +68 -0
  9. data/lib/core/facets/array/indexes.rb +1 -1
  10. data/lib/core/facets/array/occur.rb +1 -1
  11. data/lib/core/facets/array/split.rb +16 -9
  12. data/lib/core/facets/array/split_at.rb +3 -3
  13. data/lib/core/facets/array.rb +1 -0
  14. data/lib/core/facets/boolean.rb +2 -2
  15. data/lib/core/facets/class/descendants.rb +26 -12
  16. data/lib/core/facets/dir/ascend.rb +1 -2
  17. data/lib/core/facets/dir/multiglob.rb +4 -9
  18. data/lib/core/facets/enumerable/apply.rb +3 -3
  19. data/lib/core/facets/enumerable/cluster.rb +2 -2
  20. data/lib/core/facets/enumerable/defer.rb +4 -1
  21. data/lib/core/facets/enumerable/hashify.rb +5 -5
  22. data/lib/core/facets/enumerable/with_position.rb +2 -2
  23. data/lib/core/facets/enumerator/fx.rb +11 -11
  24. data/lib/core/facets/essentials.rb +2 -2
  25. data/lib/core/facets/file/atomic_open.rb +1 -1
  26. data/lib/core/facets/file/rewrite.rb +4 -4
  27. data/lib/core/facets/hash/count.rb +19 -8
  28. data/lib/core/facets/hash/deep_merge.rb +25 -20
  29. data/lib/core/facets/hash/deep_rekey.rb +1 -1
  30. data/lib/core/facets/hash/except.rb +1 -1
  31. data/lib/core/facets/hash/op_mul.rb +2 -0
  32. data/lib/core/facets/hash/op_push.rb +7 -7
  33. data/lib/core/facets/hash/rekey.rb +7 -7
  34. data/lib/core/facets/hash/weave.rb +1 -1
  35. data/lib/core/facets/integer/ordinal.rb +18 -13
  36. data/lib/core/facets/integer/to_base.rb +115 -0
  37. data/lib/core/facets/integer.rb +1 -0
  38. data/lib/core/facets/kernel/ask.rb +3 -3
  39. data/lib/core/facets/kernel/blank.rb +13 -8
  40. data/lib/core/facets/kernel/callstack.rb +2 -2
  41. data/lib/core/facets/kernel/d.rb +3 -3
  42. data/lib/core/facets/kernel/demo.rb +2 -2
  43. data/lib/core/facets/kernel/extend.rb +20 -4
  44. data/lib/core/facets/kernel/functor.rb +1 -1
  45. data/lib/core/facets/kernel/instance_assign.rb +2 -3
  46. data/lib/core/facets/kernel/instance_replace.rb +2 -2
  47. data/lib/core/facets/kernel/maybe.rb +1 -1
  48. data/lib/core/facets/kernel/meta_class.rb +2 -1
  49. data/lib/core/facets/kernel/meta_def.rb +3 -3
  50. data/lib/core/facets/kernel/object_hexid.rb +2 -7
  51. data/lib/core/facets/kernel/try.rb +3 -1
  52. data/lib/core/facets/module/attr_class_accessor.rb +2 -2
  53. data/lib/core/facets/module/class_accessor.rb +2 -2
  54. data/lib/core/facets/module/instance_method.rb +2 -2
  55. data/lib/core/facets/module/is.rb +1 -1
  56. data/lib/core/facets/numeric/delimit.rb +1 -1
  57. data/lib/core/facets/proc/wrap.rb +1 -1
  58. data/lib/core/facets/range/op_sub.rb +2 -2
  59. data/lib/core/facets/range/overlap.rb +32 -1
  60. data/lib/core/facets/range/within.rb +1 -1
  61. data/lib/core/facets/regexp/op_or.rb +1 -1
  62. data/lib/core/facets/string/align.rb +4 -4
  63. data/lib/core/facets/string/ascii_only.rb +2 -2
  64. data/lib/core/facets/string/dashcase.rb +1 -1
  65. data/lib/core/facets/string/file.rb +1 -1
  66. data/lib/core/facets/string/from_base.rb +85 -0
  67. data/lib/core/facets/string/indent.rb +35 -23
  68. data/lib/core/facets/string/margin.rb +18 -4
  69. data/lib/core/facets/string/mask.rb +264 -0
  70. data/lib/core/facets/string/natcmp.rb +1 -1
  71. data/lib/core/facets/string/random.rb +1 -1
  72. data/lib/core/facets/string/remove.rb +13 -8
  73. data/lib/core/facets/string/rotate.rb +1 -1
  74. data/lib/core/facets/string/similarity.rb +2 -2
  75. data/lib/core/facets/string/squish.rb +5 -3
  76. data/lib/core/facets/string/trim.rb +1 -1
  77. data/lib/core/facets/string/unfold.rb +1 -1
  78. data/lib/core/facets/string/word_wrap.rb +1 -1
  79. data/lib/core/facets/string/words.rb +2 -2
  80. data/lib/core/facets/string.rb +3 -0
  81. data/lib/core/facets/symbol/call.rb +0 -9
  82. data/lib/core/facets/time/change.rb +51 -29
  83. data/lib/core/facets/time/future.rb +6 -2
  84. data/lib/core/facets/time/stamp.rb +1 -1
  85. data/lib/core/facets/time/to_time.rb +3 -7
  86. data/lib/core/facets/version.rb +1 -1
  87. data/lib/rails/facets/file/atomic_write.rb +1 -1
  88. data/lib/standard/facets/crypt3.rb +4 -2
  89. data/lib/standard/facets/digest/salted_digest.rb +6 -2
  90. data/lib/standard/facets/fileutils/ln_r.rb +7 -56
  91. data/lib/standard/facets/mirror.rb +276 -0
  92. data/lib/standard/facets/ostruct/initialize.rb +7 -6
  93. data/lib/standard/facets/ostruct.rb +3 -3
  94. data/lib/standard/facets/paramix.rb +150 -0
  95. data/lib/standard/facets/pathname/glob.rb +11 -7
  96. data/lib/standard/facets/shellwords.rb +53 -5
  97. data/lib/standard/facets/zlib.rb +5 -9
  98. metadata +7 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: db8b790b2c8e0551d30a4020f9e9a206306ef7b57dc3bb73cf75ab8bfe192b52
4
- data.tar.gz: 38d282a641961639027ed77a9042de9f837d55f6d4c37935e502ed71c1b22431
3
+ metadata.gz: a5a0fe1f15e51a1eb910a6c2725ec6a40a03e34250401a1211bb7b5f2c0fb5e5
4
+ data.tar.gz: 45b61435e8159919b01bf88bc37a4ebe8330c1743b7a8d544763299f798957dc
5
5
  SHA512:
6
- metadata.gz: 7e85bd3715fbf1a7c333aefbf9b9db67afe2bd7dfbfe1119a6c2af640e6f5b189518b5c59b47d36effca090d523eaf31bed497028d000691f3c5b26f15012265
7
- data.tar.gz: d32670ff9724cdd492b10092970ef9cfb4716530c2aa3f6b4906846ca0e8dae45dc04336c30d78f66da41c99e00ce9cc9a23df833dd07cf66c515891e8527945
6
+ metadata.gz: 5bef39a334f530b1fea26901da7975267cb7e764c2763798130d09cb457187d2c6e935261a83527673e37d510bc66869a264dc4b459e81c9d0e6519d26715ac0
7
+ data.tar.gz: eb3591e5256eea3e91c82a8a074830cdc7c4b415fdd13ac40da475192a8e76a93d9157c0445e0abd1595b88f26abff9a8aee541e77cf6155cc88ca0123f966d5
data/CONTRIBUTING.md CHANGED
@@ -27,6 +27,16 @@
27
27
  require line, and comment out their line in the aggregator file with
28
28
  `# uncommon`.
29
29
 
30
+ * Facets must not change what Ruby's own methods do, in the core or the
31
+ standard library. A Facets method with the same name as one of Ruby's is
32
+ allowed only if it is compatible, giving Ruby's result for everything
33
+ Ruby's version accepts (or differing only where Ruby's gives no useful
34
+ answer, such as raising or returning nil), and it adds something useful.
35
+ Otherwise Facets gets out of Ruby's way, and the Facets version is either
36
+ dropped or kept under a new name. Never redefine a method just to copy
37
+ Ruby's. If Ruby later adds a method Facets already has, the same rule
38
+ applies.
39
+
30
40
  * Standard libraries that are not extensions of existing standard libraries
31
41
  do not have to be divvied up into individual method files. But note that
32
42
  full classes and/or modules are less likely to make it into Facets, as
data/HISTORY.md CHANGED
@@ -1,5 +1,227 @@
1
1
  # Facets Release History
2
2
 
3
+ ## 4.2.0 / 2026-11-17
4
+
5
+ This release brings back four libraries that began in Facets and were
6
+ later kept as gems of their own: number bases (Radix), object
7
+ introspection (Instance, now `Mirror`), parametric mixins (Paramix) and
8
+ string masks (Strmask). The number bases load with `require 'facets'`;
9
+ the other three are loaded on request.
10
+
11
+ Changes:
12
+
13
+ * Additions
14
+
15
+ * `Integer#to_base` and `String#from_base` convert to and from any base
16
+ from 2 to 62, or with your own digits: `255.to_base(62)` is `"47"`,
17
+ and `"47".from_base(62)` is 255. Ruby's `to_s` and `to_i` stop at
18
+ base 36; up to there, `to_base` gives the same result as `to_s`, and
19
+ `from_base` the same as `to_i` for valid input. Unlike `to_i`,
20
+ `from_base` raises `ArgumentError` for a character that isn't a digit.
21
+ In base 256 the digits are bytes: `256.to_base(256)` is `"\x01\x00"`,
22
+ a binary string, and `from_base(256)` reads a string's bytes.
23
+ * Given an array, `to_base` gives an array, with no limit on the base.
24
+ An array holding a number is the base, and the result is the digit
25
+ values: `1000.to_base([100])` is `[10, 0]`. Any other array is the
26
+ digits, which can be any objects: `5.to_base([:zero, :one])` is
27
+ `[:one, :zero, :one]`.
28
+ * `Array#from_base` turns such an array back into a number, given the
29
+ same base: `[10, 0].from_base([100])` is 1000, and
30
+ `[1, 0].from_base(256)` is 256. All three load with
31
+ `require 'facets'`, and are based on the Radix gem.
32
+ * `String#margin` takes a `:flush` option, which gives every line the
33
+ same margin and doesn't keep their relative indentation:
34
+ `"abc\n xyz".margin(2, flush: true)` is `" abc\n xyz"`. This is
35
+ what `String#tab`, removed in 3.1.0, used to do; `String#tabto` is
36
+ `margin(n, lead: true)`.
37
+ * `Mirror`, loaded with `require 'facets/mirror'`, looks at an object
38
+ from the outside: `obj.mirror.to_h` gives its instance variables as a
39
+ hash, and the mirror also gets and sets them, and gives the object's
40
+ class and methods. It calls Ruby's own reflection methods, so it gives
41
+ the true answers even for an object that redefines `class` or
42
+ `instance_variables`, or a `BasicObject` that has neither. The class
43
+ is `Kernel::Mirror`, so an application's own `Mirror` class takes
44
+ precedence instead of clashing. Based on the Instance gem.
45
+ * `Paramix`, loaded with `require 'facets/paramix'`, makes a module
46
+ take parameters where it is included or extended:
47
+ `include Greeter[:name => 'x']`. A module that includes `Paramix`
48
+ has a `parameterized` block, which is given the parameters and
49
+ defines the methods that depend on them. Paramix was part of Facets
50
+ until 2.7.0, then the Paramix gem, where the module to include was
51
+ `Paramix::Parametric`; that name still works.
52
+ * `String::Mask` and `String#mask`, loaded with
53
+ `require 'facets/string/mask'`, treat a string as a mask with empty
54
+ slots and combine masks character by character:
55
+ `("abc..123".mask('.') + "ab..789.").to_s` is `"abc.7893"`, and `-`,
56
+ `*`, `&` and `^` work likewise. This was Facets' `string/mask` until
57
+ 2.7.0, then the Strmask gem. Compared with the gem: masks of
58
+ different lengths can be combined, a mask can be made without an
59
+ empty-slot character, equal masks are the same hash key, `apply`
60
+ works, only methods a string has are passed on to it, and a mask is
61
+ equal only to another mask (compare `mask.to_s` with a string).
62
+
63
+ * Bug fixes
64
+
65
+ * `String#dashcase` now squeezes runs of dashes, as its docs say:
66
+ `"Dash - Case".dashcase` is `"dash-case"`, not `"dash-----case"`.
67
+ * `Dir.multiglob` ignored `:recurse => true`. It now gives the same
68
+ result as `Dir.multiglob_r`, and no longer changes the options hash
69
+ it is given.
70
+ * `Array#delete_first` now returns the block's result when the item
71
+ isn't found, as its docs say and as `Array#delete` does.
72
+ * `Crypt3.generate_salt`, and so the salt `Crypt3.crypt` makes when
73
+ given none, now comes from `SecureRandom`. It came from `rand`, which
74
+ isn't a cryptographic source.
75
+
76
+ * Documentation
77
+
78
+ * The examples in the doc comments run again, with `rake qed:code`,
79
+ and CI now runs them. Many had gone stale: wrong results, renamed
80
+ methods, and output that depended on the local time zone. Those that
81
+ can't run, such as interactive prompts and random output, are now
82
+ marked as sample text. Six `@uncommon` tags named files that don't
83
+ exist; a test now checks those paths.
84
+
85
+ ## 4.1.0 / 2026-11-08
86
+
87
+ Facets and ActiveSupport define many of the same methods, and whichever
88
+ loads last replaces the other's. This release makes a set of those methods
89
+ behave the same in both libraries, so it no longer matters which one wins.
90
+ Facets now matches ActiveSupport 8.1 in these cases, which fixes bugs in
91
+ Rails apps that load Facets, and adds the extra options ActiveSupport's
92
+ versions take.
93
+
94
+ It also stops Facets from changing what Ruby's own methods do. Under a new
95
+ rule, now in CONTRIBUTING.md, a Facets method may share a name with one of
96
+ Ruby's only if it gives Ruby's results and adds something useful. Otherwise
97
+ Facets gets out of Ruby's way.
98
+
99
+ Changes:
100
+
101
+ * Bug Fixes
102
+
103
+ * `Hash#count`, loaded by `require 'facets'`, gives Ruby's own answers
104
+ again. Facets' version counted values rather than key-value pairs, which
105
+ changed Ruby's answer for every library in the program:
106
+ `{a: 1}.count([:a, 1])` returned 0. To count values, use
107
+ `hash.values.count(value)`. Until 2027-09-30, `Hash#count` warns when
108
+ given an argument that can't be a key-value pair, which is how Facets'
109
+ version was called.
110
+ * `Array#shelljoin` from `facets/shellwords` is Ruby's own again. Facets'
111
+ version flattened nested arrays and turned hashes into options, so a
112
+ value meant as one argument could become several. A web request's
113
+ parameter can be an array (`?term[]=&term[]=/home`), and with it
114
+ `['grep', '-r', '--', term, 'public/'].shelljoin` gave
115
+ `grep -r -- '' /home public/`, which prints every file under `/home`.
116
+ Ruby's escapes each element as one argument. To turn hashes into
117
+ options, use `array.shellwords.shelljoin`. Until 2027-09-30,
118
+ `Array#shelljoin` warns when the array has a hash or an array in it.
119
+ * `Hash#shellwords`, and so `Hash#shelljoin` and `Array#shellwords`, no
120
+ longer put quote characters around values. Once the words were escaped
121
+ with `shelljoin`, the quotes became part of the value:
122
+ `{name: 'jim'}.shelljoin` passed `"jim"`, quotes included. Each flag and
123
+ its value is now one plain word, `--name=jim`.
124
+ * `require 'facets'` loads `String#trim`. When `String#margin` was renamed
125
+ to `#trim` in 3.0, the new file was never added to the core aggregator,
126
+ so `trim` worked only with its own require.
127
+ * `Enumerable#defer` with a block works again. Since 3.2 deprecated it,
128
+ `defer` ignored its block, so
129
+ `(1..10).defer { |out, i| out << i if i.even? }.first(5)` returned
130
+ `[1, 2, 3, 4, 5]` instead of `[2, 4, 6, 8, 10]`. It is still
131
+ deprecated; the block form is `Enumerator::Lazy.new(enum) { ... }`.
132
+ * `Range#overlap?` on Ruby 3.1 and 3.2, where Ruby has no version of its
133
+ own, gives the same answers as Ruby's. Facets' version said an empty
134
+ range like `3...3` overlapped any range containing 3, raised RangeError
135
+ for `(3..).overlap?(..5)`, and raised NoMethodError rather than
136
+ TypeError for a non-Range argument. It now follows Ruby's algorithm.
137
+ * `Time.current` uses ActiveSupport's `Time.zone` when it is set. Before,
138
+ when Facets loaded after ActiveSupport, `Time.current` ignored the Rails
139
+ app's time zone and returned the system's local time.
140
+ * `Time#change` keeps the time's UTC offset or time zone. Before, a time
141
+ such as `15:30 +09:00` changed to the system's local time zone. It also
142
+ keeps fractions of a microsecond.
143
+ * Facets' deprecated `Time#to_time`, used only when `date` isn't loaded,
144
+ returns `self`, as Ruby's own does. Before, it converted to local time.
145
+ * `String#blank?` and `String#squish` treat Unicode whitespace, such as a
146
+ non-breaking space, as whitespace. `String#blank?` also works for strings
147
+ in encodings such as UTF-16.
148
+ * `Class#descendants` no longer raises `ArgumentError` when ActiveSupport
149
+ is loaded. Calling it with a number of generations still does, because
150
+ ActiveSupport wraps the method in one that takes no argument.
151
+ * `Integer#ordinal` and `#ordinalize` give `"-1st"` for -1, not `"-1th"`.
152
+ * `String#unindent` with no argument removes only the least indented
153
+ line's indentation from each line. Before, it removed more from the more
154
+ indented lines, so its own example, `"ohaie\n wurld"`, came out as
155
+ `"ohaie\nwurld"`. It also raised `NoMethodError` for an empty string.
156
+ * `String#indent` with a negative number and an indent string of more than
157
+ one character removes only whole copies of that string.
158
+ * `require 'facets/fileutils/ln_r'` replaced Ruby's `FileUtils.link_entry`
159
+ and an internal method it uses with old copies, so Ruby's own
160
+ `FileUtils.cp_lr` raised `NameError`. `FileUtils.ln_r` now uses Ruby's
161
+ `link_entry`, and the file requires `fileutils` itself.
162
+ * `Pathname#glob` from `facets/pathname/glob` ignored a block; it now gives
163
+ the block each match, as Ruby's does. With symbol flags, such as
164
+ `:dotmatch`, it now uses Ruby's glob too, so it works in a directory
165
+ whose name has glob characters such as `[`, and returns paths in the
166
+ same form as it does without them. The file requires `pathname` itself.
167
+ * `Kernel#extend` with no arguments and no block raises `ArgumentError`,
168
+ as Ruby's does; before, it returned the object. `ruby -w` no longer warns
169
+ that `extend` was redefined.
170
+ * `require 'facets/digest'` raised `LoadError`, because it required a file
171
+ that had moved. `#salted_digest`'s automatic salt now comes from
172
+ `SecureRandom` instead of `rand`.
173
+ * `facets/zlib` no longer defines its own copies of Ruby's `Zlib.inflate`
174
+ and `Zlib.deflate`. It now requires `zlib` and `stringio` itself;
175
+ before, `Zlib.compress` raised `NameError` unless they were already
176
+ loaded.
177
+ * `OpenStruct#initialize` from `facets/ostruct` calls Ruby's own
178
+ `initialize` for the hash, instead of a copy of it, and `ruby -w` no
179
+ longer warns that it was redefined.
180
+
181
+ * Additions
182
+
183
+ * `Time#change` takes `nsec:` and `offset:`.
184
+ * `String#remove` and `#remove!` take several patterns.
185
+ * `Hash#deep_merge` and `#deep_merge!` take a block, as `Hash#merge` does,
186
+ to decide the value of a key both hashes have.
187
+ * `Array#split` takes a block instead of a pattern, and splits on `nil`
188
+ when given neither.
189
+ * `String#indent` and `#indent!` take a third argument; when true, empty
190
+ lines are indented too.
191
+
192
+ * Deprecations
193
+
194
+ * `Kernel#extend` with a block, which Facets has added since 2.8.0, now
195
+ warns, and will be removed after 2027-09-30. It's the only reason Facets
196
+ overrides Ruby's `extend`, which every `extend` call in a program then
197
+ goes through. Use `obj.extend(Module.new { ... })` instead. Without
198
+ Facets, Ruby raises if given only a block, and ignores a block given
199
+ with modules.
200
+
201
+ * Changes that can affect existing code
202
+
203
+ * `Hash#count(value)` and `Array#shelljoin` no longer do what Facets'
204
+ versions did; see Bug Fixes. Both warn until 2027-09-30 when called
205
+ the old way.
206
+ * `Hash#shellwords` gives `--name=jim` rather than `--name="jim"`. Code
207
+ that joined the words with spaces into a shell command should use
208
+ `shelljoin` instead.
209
+ * `Array#split` keeps an empty piece where a match is at either end:
210
+ `[2, 1, 2].split(2)` is `[[], [1], []]`, and `[].split(2)` is `[[]]`.
211
+ Before, empty pieces at the end were dropped.
212
+ * `String#indent` leaves empty lines unchanged unless asked. Without an
213
+ indent string, it indents with the string's own indentation character,
214
+ so a tab-indented string gets more tabs.
215
+ * `String#remove!` returns the string even when nothing was removed.
216
+ Before, it returned `nil` then.
217
+ * `Hash#deep_merge!` replaces a sub-hash with a merged copy instead of
218
+ changing it, so other references to the sub-hash no longer see the
219
+ change.
220
+ * `Class#descendants` lists all subclasses before their own descendants.
221
+ On Ruby 4.1, which adds its own `Module#descendants`, a call without a
222
+ number of generations is passed to Ruby's, so it gives Ruby's list, in
223
+ Ruby's order. Only `descendants(n)` is still Facets' own there.
224
+
3
225
  ## 4.0.1 / 2026-11-02
4
226
 
5
227
  A patch release with a security fix: `require 'facets/shellwords'` replaced
data/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
 
6
6
  **More of Ruby, one method at a time.** Facets is a collection of extensions to Ruby's core classes and standard library, plus a few small, reusable classes and modules. Most methods live in their own files, so you can load one extension, a class's extensions, or the core collection.
7
7
 
8
- Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **4.0.1**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
8
+ Facets took its name in 2004, growing out of a small methods library started in 2002, and is still maintained. The current release is **4.2.0**, which requires **Ruby 3.1 or newer**. See the [release history](HISTORY.md) for changes and migration notes from earlier versions. The `main` branch also contains changes awaiting the next release.
9
9
 
10
10
  ## Install
11
11
 
@@ -62,7 +62,7 @@ require 'facets'
62
62
  require 'facets/ostruct'
63
63
  ```
64
64
 
65
- This loads `ostruct` and Facets' OpenStruct extensions. On Ruby 3.5+, declare the `ostruct` gem separately because it is no longer a default gem.
65
+ This loads `ostruct` and Facets' OpenStruct extensions. On Ruby 4.0+, list the `ostruct` gem in your Gemfile, because it is now a bundled gem rather than a default gem.
66
66
 
67
67
  ## Documentation
68
68
 
@@ -5,7 +5,7 @@ class Array
5
5
  # common if they return the same value for Object#hash and if obj1 == obj2.
6
6
  #
7
7
  # This can be useful, for instance, in determining all persons that share
8
- # their last name with another person.
8
+ # their last name with another person:
9
9
  #
10
10
  # persons.commonality { |person| person.last_name }
11
11
  #
@@ -7,15 +7,16 @@ class Array
7
7
  # the item is not found.
8
8
  #
9
9
  # a = [ "a", "b", "b", "b", "c" ]
10
- # a.delete_first("b") #=> "b"
11
- # a #=> ["a", "c"]
12
- # a.delete("z") #=> nil
13
- # a.delete("z") {"not found"} #=> "not found"
10
+ # a.delete_first("b") #=> "b"
11
+ # a #=> ["a", "b", "b", "c"]
12
+ # a.delete_first("z") #=> nil
13
+ # a.delete_first("z") { "not found" } #=> "not found"
14
14
  def delete_first(el)
15
15
  i = index(el)
16
16
  if i
17
17
  delete_at(i)
18
+ elsif block_given?
19
+ yield(el)
18
20
  end
19
21
  end
20
22
  end
21
-
@@ -6,7 +6,7 @@ class Array
6
6
  # #=> [['a1','b1'],['a2','b2']]
7
7
  #
8
8
  # ['a1','b1','a2','b2'].divide(/^b/)
9
- # #=> [['a1',['b1','a2'],[]'b2']]
9
+ # #=> [['a1'],['b1','a2'],['b2']]
10
10
  #
11
11
  # ['a1','b1','a2','b2'].divide(/^c/)
12
12
  # #=> [['a1','b1','a2','b2']]
@@ -0,0 +1,68 @@
1
+ class Array
2
+
3
+ # Reads the array as the digit values of a number in the given base,
4
+ # most significant first, and returns the number. Any base from 2 up
5
+ # works.
6
+ #
7
+ # [1, 0].from_base(256) #=> 256
8
+ # [100, 10].from_base(256) #=> 25610
9
+ # [2, 5, 5].from_base(10) #=> 255
10
+ #
11
+ # This reverses Ruby's `Integer#digits`, which gives the digit values
12
+ # least significant first:
13
+ #
14
+ # 255.digits(16) #=> [15, 15]
15
+ # 255.digits(16).reverse.from_base(16) #=> 255
16
+ #
17
+ # The base can also be given as Integer#to_base takes it for an
18
+ # array: as an array holding the base, or as an array of the digits,
19
+ # starting with the digit for zero. Whatever array `to_base` was
20
+ # given reads its result back.
21
+ #
22
+ # [10, 0].from_base([100]) #=> 1000
23
+ # %w[L O L].from_base(%w[O L T W F S]) #=> 37
24
+ # [:one, :zero, :one].from_base([:zero, :one]) #=> 5
25
+ #
26
+ # Raises ArgumentError for an empty array, and for an element that
27
+ # isn't a digit of the base: an Integer from 0 to one less than the
28
+ # base, or one of the digits given.
29
+ #
30
+ # String#from_base reads a number written as a string.
31
+ #
32
+ # Since: 4.2.0
33
+
34
+ def from_base(base)
35
+ values = nil
36
+ case base
37
+ when ::Integer
38
+ # digit values
39
+ when ::Array
40
+ if base.size == 1 && base.first.is_a?(::Integer)
41
+ base = base.first
42
+ else
43
+ if base.size < 2
44
+ raise ArgumentError, "a base needs at least two digits"
45
+ end
46
+ if base.uniq.size < base.size
47
+ raise ArgumentError, "digits must not repeat"
48
+ end
49
+ values = {}
50
+ base.each_with_index { |d, i| values[d] = i }
51
+ base = base.size
52
+ end
53
+ else
54
+ raise TypeError, "base must be an Integer or Array, not #{base.class}"
55
+ end
56
+ raise ArgumentError, "invalid radix #{base}" if base < 2
57
+ raise ArgumentError, "no digits" if empty?
58
+
59
+ inject(0) do |n, d|
60
+ v = values ? values[d] : d
61
+ unless v.is_a?(::Integer) && v >= 0 && v < base
62
+ raise ArgumentError, "invalid digit #{d.inspect} for base #{base}"
63
+ end
64
+ n * base + v
65
+ end
66
+ end
67
+
68
+ end
@@ -87,7 +87,7 @@ class Enumerator::Lazy
87
87
  # If neither a block nor argument is given, an Enumerator for _all_ indexes is returned.
88
88
  #
89
89
  # enum = (42 .. Float::INFINITY).lazy.indexes
90
- # #=> #<Enumerator::Lazy: ...>
90
+ # enum.class #=> Enumerator::Lazy
91
91
  # enum.next #=> 0
92
92
  # enum.next #=> 1
93
93
  # enum.first(5) #=> [0, 1, 2, 3, 4]
@@ -7,7 +7,7 @@ class Array
7
7
  #
8
8
  # Examples
9
9
  #
10
- # [0,1,1,1,3,0,1,2,4].occur(3) #=> [1]
10
+ # [0,1,1,1,3,0,1,2,4].occur(4) #=> [1]
11
11
  #
12
12
  # [0,1,1,1,3,0,1,2,4].occur(2..4) #=> [0,1]
13
13
  #
@@ -1,20 +1,30 @@
1
1
  class Array
2
2
 
3
- # Split on matching pattern. Unlike #divide this does not include matching
4
- # elements.
5
- #
6
- # Examples
3
+ # Split on matching elements. Unlike #divide this does not include the
4
+ # matching elements. An element matches if `pattern === element`, so a
5
+ # pattern can be a value, a Regexp or a class.
7
6
  #
8
7
  # ['a1','a2','b1','a3','b2','a4'].split(/^b/)
9
8
  # #=> [['a1','a2'],['a3'],['a4']]
10
9
  #
10
+ # Or give a block, and split where it returns true.
11
+ #
12
+ # [1, 2, 3, 4, 5].split { |x| x % 3 == 0 }
13
+ # #=> [[1, 2], [4, 5]]
14
+ #
15
+ # As with ActiveSupport's Array#split, every match ends a piece, so a match
16
+ # at either end gives an empty piece there.
17
+ #
18
+ # [2, 1, 2].split(2) #=> [[], [1], []]
19
+ # [].split(2) #=> [[]]
20
+ #
11
21
  # Returns list of split-up arrays. [Array<Array>]
12
22
 
13
- def split(pattern)
23
+ def split(pattern=nil, &block)
14
24
  memo = []
15
25
  sect = []
16
26
  each do |obj|
17
- if pattern === obj
27
+ if block ? block.call(obj) : pattern === obj
18
28
  memo << sect
19
29
  sect = []
20
30
  else
@@ -22,9 +32,6 @@ class Array
22
32
  end
23
33
  end
24
34
  memo << sect
25
- memo.pop while memo.last == []
26
- memo
27
35
  end
28
36
 
29
37
  end
30
-
@@ -5,10 +5,10 @@ class Array
5
5
  #
6
6
  # Examples
7
7
  #
8
- # ['a1','a2','b1','a3','b2','a4'].split('b1')
9
- # #=> [['a1','a2'],b1,['a3','b2','a4']]
8
+ # ['a1','a2','b1','a3','b2','a4'].split_at('b1')
9
+ # #=> [['a1','a2'],'b1',['a3','b2','a4']]
10
10
  #
11
- # ['a1','a2','b1','a3','b2','a4'].split('foo')
11
+ # ['a1','a2','b1','a3','b2','a4'].split_at('foo')
12
12
  # #=> [[],nil,[]]
13
13
  #
14
14
  # Returns list of split-up arrays. [Tuple<Array,Object,Array>]
@@ -16,6 +16,7 @@ require_relative 'array/each_pair.rb'
16
16
  require_relative 'array/each_value.rb'
17
17
  require_relative 'array/entropy.rb'
18
18
  require_relative 'array/from.rb'
19
+ require_relative 'array/from_base.rb'
19
20
  require_relative 'array/indexable.rb'
20
21
  #require_relative 'array/intersection.rb' # too new
21
22
  #require_relative 'array/median.rb' # uncommon
@@ -69,7 +69,7 @@ end
69
69
  class String
70
70
  # Interpret common affirmative string meanings as true,
71
71
  # otherwise nil or false. Blank space and case are ignored.
72
- # The following strings that will return true ...
72
+ # The following strings that will return true:
73
73
  #
74
74
  # true
75
75
  # yes
@@ -79,7 +79,7 @@ class String
79
79
  # y
80
80
  # ==
81
81
  #
82
- # The following strings will return nil ...
82
+ # The following strings will return nil:
83
83
  #
84
84
  # nil
85
85
  # null
@@ -1,11 +1,12 @@
1
1
  class Class
2
2
 
3
- # List all descedents of this class.
3
+ # List all descendants of this class. The order differs between
4
+ # Rubies, so these examples sort the list.
4
5
  #
5
6
  # class A ; end
6
7
  # class B < A; end
7
8
  # class C < A; end
8
- # A.descendants #=> [B,C]
9
+ # A.descendants.sort_by(&:name) #=> [B,C]
9
10
  #
10
11
  # You may also limit the generational distance the subclass may be from
11
12
  # the parent class.
@@ -13,22 +14,35 @@ class Class
13
14
  # class X ; end
14
15
  # class Y < X; end
15
16
  # class Z < Y; end
16
- # X.descendants #=> [Y,Z]
17
- # X.descendants(1) #=> [Y]
17
+ # X.descendants.sort_by(&:name) #=> [Y,Z]
18
+ # X.descendants(1) #=> [Y]
19
+ #
20
+ # Ruby 4.1 adds its own Module#descendants. Where Ruby has it, a call
21
+ # without a limit is passed to Ruby's, and Facets only handles the
22
+ # generations limit. Ruby doesn't define the order of its list.
23
+ #
24
+ # On older Rubies, the list is in the same order as ActiveSupport's
25
+ # Class#descendants: the subclasses first, then each one's own
26
+ # descendants.
27
+ #
28
+ # The generations walk goes through #subclasses only, never #descendants,
29
+ # because ActiveSupport wraps #descendants in a version that takes no
30
+ # argument.
31
+ #
32
+ # NOTE: With ActiveSupport loaded, calling descendants with an argument
33
+ # raises ArgumentError, because of that wrapper.
18
34
  #
19
35
  # NOTE: This is a intensive operation. Do not expect it to be very fast.
20
36
  #
21
37
  # @author Roger Pack
22
38
  def descendants(generations=-1)
23
- descendants = []
24
- subclasses.each do |k|
25
- descendants << k
26
- if generations != 1
27
- descendants.concat(k.descendants(generations - 1))
28
- end
39
+ return super() if generations < 1 && Module.method_defined?(:descendants)
40
+ walk = lambda do |klass, gen|
41
+ subs = klass.subclasses
42
+ next subs if gen == 1
43
+ subs + subs.flat_map { |k| walk.(k, gen - 1) }
29
44
  end
30
- descendants
45
+ walk.(self, generations)
31
46
  end
32
47
 
33
48
  end
34
-
@@ -14,8 +14,7 @@ class Dir
14
14
  #
15
15
  # CREDIT: Daniel Berger, Jeffrey Schwab
16
16
  #
17
- # TODO: Make it work with windows too
18
- # use FileTest.root?
17
+ # TODO: Make it work with windows too, use FileTest.root?
19
18
 
20
19
  def self.ascend(dir, inclusive=true, &blk)
21
20
  dir = dir.dup
@@ -5,7 +5,7 @@ class Dir
5
5
  # Dir.multiglob('tmp/*.rb', 'tmp/*.py')
6
6
  #
7
7
  # Rather then constants for options multiglob accepts a trailing options
8
- # hash of symbol keys...
8
+ # hash of symbol keys:
9
9
  #
10
10
  # :noescape File::FNM_NOESCAPE
11
11
  # :casefold File::FNM_CASEFOLD
@@ -13,7 +13,7 @@ class Dir
13
13
  # :dotmatch File::FNM_DOTMATCH
14
14
  # :strict File::FNM_PATHNAME && File::FNM_DOTMATCH
15
15
  #
16
- # It also has an option for recurse...
16
+ # It also has an option for recurse:
17
17
  #
18
18
  # :recurse Recurively include contents of directories.
19
19
  #
@@ -26,11 +26,10 @@ class Dir
26
26
  # Dir.multiglob('tmp/**/*')
27
27
  #
28
28
  def self.multiglob(*patterns)
29
- options = (Hash === patterns.last ? patterns.pop : {})
29
+ options = (Hash === patterns.last ? patterns.pop.dup : {})
30
30
 
31
31
  if options.delete(:recurse)
32
- ##patterns += patterns.collect{ |f| File.join(f, '**', '**') }
33
- multiglob_r(*patterns)
32
+ return multiglob_r(*patterns)
34
33
  end
35
34
 
36
35
  bitflags = 0
@@ -41,10 +40,6 @@ class Dir
41
40
 
42
41
  patterns = [patterns].flatten.compact
43
42
 
44
- if options[:recurse]
45
- patterns += patterns.collect{ |f| File.join(f, '**', '**') }
46
- end
47
-
48
43
  files = []
49
44
  files += patterns.collect{ |pattern| Dir.glob(pattern, bitflags) }.flatten.uniq
50
45
 
@@ -10,9 +10,9 @@ module Enumerable
10
10
  # r #=> 6
11
11
  #
12
12
  def apply
13
- #Functor.new do |sym, *args, &blk|
14
- # inject{ |r, e| r.__send__(sym, e, *args, &blk) }
15
- #end
13
+ ##Functor.new do |sym, *args, &blk|
14
+ ## inject{ |r, e| r.__send__(sym, e, *args, &blk) }
15
+ ##end
16
16
  per(:inject)
17
17
  end
18
18
 
@@ -3,10 +3,10 @@ module Enumerable
3
3
  # Clusters together adjacent elements into a list of sub-arrays.
4
4
  #
5
5
  # [2,2,2,3,3,4,2,2,1].cluster{ |x| x }
6
- # => [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
6
+ # #=> [[2, 2, 2], [3, 3], [4], [2, 2], [1]]
7
7
  #
8
8
  # ["dog", "duck", "cat", "dude"].cluster{ |x| x[0] }
9
- # => [["dog", "duck"], ["cat"], ["dude"]]
9
+ # #=> [["dog", "duck"], ["cat"], ["dude"]]
10
10
  #
11
11
  # @author Oleg K
12
12
 
@@ -26,9 +26,12 @@ module Enumerable
26
26
  # Array or Hash built with the results, or each{...} if you just want
27
27
  # to output each result and discard it.
28
28
  #
29
+ # @deprecated Use Enumerable#lazy, built into Ruby since 2.0. The block
30
+ # form is Enumerator::Lazy.new(enum) { |out, i| ... }. Scheduled for
31
+ # removal after 2027-09-30.
29
32
  def defer(&blk)
30
33
  warn "Enumerable#defer is deprecated. Use Enumerable#lazy instead. It will be removed after 2027-09-30.", uplevel: 1
31
- lazy
34
+ blk ? Enumerator::Lazy.new(self, &blk) : lazy
32
35
  end
33
36
 
34
37
  end