summaryrefslogtreecommitdiff
path: root/string.rb
blob: be10b407b040e6d04879bca1b9eaba7420da82b7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
#  A \String object has an arbitrary sequence of bytes,
#  typically representing text or binary data.
#  A \String object may be created using String::new or as literals.
#
#  String objects differ from Symbol objects in that Symbol objects are
#  designed to be used as identifiers, instead of text or data.
#
#  You can create a \String object explicitly with:
#
#  - A {string literal}[rdoc-ref:syntax/literals.rdoc@String+Literals].
#  - A {heredoc literal}[rdoc-ref:syntax/literals.rdoc@Here+Document+Literals].
#
#  You can convert certain objects to Strings with:
#
#  - \Method #String.
#
#  Some \String methods modify +self+.
#  Typically, a method whose name ends with <tt>!</tt> modifies +self+
#  and returns +self+;
#  often a similarly named method (without the <tt>!</tt>)
#  returns a new string.
#
#  In general, if there exist both bang and non-bang version of method,
#  the bang! mutates and the non-bang! does not.
#  However, a method without a bang can also mutate, such as String#replace.
#
#  == Substitution Methods
#
#  These methods perform substitutions:
#
#  - String#sub: One substitution (or none); returns a new string.
#  - String#sub!: One substitution (or none); returns +self+.
#  - String#gsub: Zero or more substitutions; returns a new string.
#  - String#gsub!: Zero or more substitutions; returns +self+.
#
#  Each of these methods takes:
#
#  - A first argument, +pattern+ (string or regexp),
#    that specifies the substring(s) to be replaced.
#
#  - Either of these:
#
#    - A second argument, +replacement+ (string or hash),
#      that determines the replacing string.
#    - A block that will determine the replacing string.
#
#  The examples in this section mostly use methods String#sub and String#gsub;
#  the principles illustrated apply to all four substitution methods.
#
#  <b>Argument +pattern+</b>
#
#  Argument +pattern+ is commonly a regular expression:
#
#    s = 'hello'
#    s.sub(/[aeiou]/, '*')# => "h*llo"
#    s.gsub(/[aeiou]/, '*') # => "h*ll*"
#    s.gsub(/[aeiou]/, '')# => "hll"
#    s.sub(/ell/, 'al')   # => "halo"
#    s.gsub(/xyzzy/, '*') # => "hello"
#    'THX1138'.gsub(/\d+/, '00') # => "THX00"
#
#  When +pattern+ is a string, all its characters are treated
#  as ordinary characters (not as regexp special characters):
#
#    'THX1138'.gsub('\d+', '00') # => "THX1138"
#
#  <b>\String +replacement+</b>
#
#  If +replacement+ is a string, that string will determine
#  the replacing string that is to be substituted for the matched text.
#
#  Each of the examples above uses a simple string as the replacing string.
#
#  \String +replacement+ may contain back-references to the pattern's captures:
#
#  - <tt>\n</tt> (_n_ a non-negative integer) refers to <tt>$n</tt>.
#  - <tt>\k<name></tt> refers to the named capture +name+.
#
#  See rdoc-ref:regexp.rdoc for details.
#
#  Note that within the string +replacement+, a character combination
#  such as <tt>$&</tt> is treated as ordinary text, and not as
#  a special match variable.
#  However, you may refer to some special match variables using these
#  combinations:
#
#  - <tt>\&</tt> and <tt>\0</tt> correspond to <tt>$&</tt>,
#    which contains the complete matched text.
#  - <tt>\'</tt> corresponds to <tt>$'</tt>,
#    which contains string after match.
#  - <tt>\`</tt> corresponds to <tt>$`</tt>,
#    which contains string before match.
#  - <tt>\\+</tt> corresponds to <tt>$+</tt>,
#    which contains last capture group.
#
#  See rdoc-ref:regexp.rdoc for details.
#
#  Note that <tt>\\\\</tt> is interpreted as an escape, i.e., a single backslash.
#
#  Note also that a string literal consumes backslashes.
#  See {String Literals}[rdoc-ref:syntax/literals.rdoc@String+Literals] for details about string literals.
#
#  A back-reference is typically preceded by an additional backslash.
#  For example, if you want to write a back-reference <tt>\&</tt> in
#  +replacement+ with a double-quoted string literal, you need to write
#  <tt>"..\\\\&.."</tt>.
#
#  If you want to write a non-back-reference string <tt>\&</tt> in
#  +replacement+, you need first to escape the backslash to prevent
#  this method from interpreting it as a back-reference, and then you
#  need to escape the backslashes again to prevent a string literal from
#  consuming them: <tt>"..\\\\\\\\&.."</tt>.
#
#  You may want to use the block form to avoid a lot of backslashes.
#
#  <b>\Hash +replacement+</b>
#
#  If argument +replacement+ is a hash, and +pattern+ matches one of its keys,
#  the replacing string is the value for that key:
#
#    h = {'foo' => 'bar', 'baz' => 'bat'}
#    'food'.sub('foo', h) # => "bard"
#
#  Note that a symbol key does not match:
#
#    h = {foo: 'bar', baz: 'bat'}
#    'food'.sub('foo', h) # => "d"
#
#  <b>Block</b>
#
#  In the block form, the current match string is passed to the block;
#  the block's return value becomes the replacing string:
#
#    s = '@'
#   '1234'.gsub(/\d/) {|match| s.succ! } # => "ABCD"
#
#  Special match variables such as <tt>$1</tt>, <tt>$2</tt>, <tt>$`</tt>,
#  <tt>$&</tt>, and <tt>$'</tt> are set appropriately.
#
#  == Whitespace in Strings
#
#  In class \String, _whitespace_ is defined as a contiguous sequence of characters
#  consisting of any mixture of the following:
#
#  - NL (null): <tt>"\x00"</tt>, <tt>"\u0000"</tt>.
#  - HT (horizontal tab): <tt>"\x09"</tt>, <tt>"\t"</tt>.
#  - LF (line feed): <tt>"\x0a"</tt>, <tt>"\n"</tt>.
#  - VT (vertical tab): <tt>"\x0b"</tt>, <tt>"\v"</tt>.
#  - FF (form feed): <tt>"\x0c"</tt>, <tt>"\f"</tt>.
#  - CR (carriage return): <tt>"\x0d"</tt>, <tt>"\r"</tt>.
#  - SP (space): <tt>"\x20"</tt>, <tt>" "</tt>.
#
#
#  Whitespace is relevant for these methods:
#
#  - #lstrip, #lstrip!: strip leading whitespace.
#  - #rstrip, #rstrip!: strip trailing whitespace.
#  - #strip, #strip!: strip leading and trailing whitespace.
#
#  == \String Slices
#
#  A _slice_ of a string is a substring that is selected by certain criteria.
#
#  These instance methods make use of slicing:
#
#  - String#[] (also aliased as String#slice) returns a slice copied from +self+.
#  - String#[]= returns a copy of +self+ with a slice replaced.
#  - String#slice! returns +self+ with a slice removed.
#
#  Each of the above methods takes arguments that determine the slice
#  to be copied or replaced.
#
#  The arguments have several forms.
#  For string +string+,  the forms are:
#
#  - <tt>string[index]</tt>.
#  - <tt>string[start, length]</tt>.
#  - <tt>string[range]</tt>.
#  - <tt>string[regexp, capture = 0]</tt>.
#  - <tt>string[substring]</tt>.
#
#  <b><tt>string[index]</tt></b>
#
#  When non-negative integer argument +index+ is given,
#  the slice is the 1-character substring found in +self+ at character offset +index+:
#
#    'bar'[0]       # => "b"
#    'bar'[2]       # => "r"
#    'bar'[20]      # => nil
#    'тест'[2]      # => "с"
#    'こんにちは'[4]  # => "は"
#
#  When negative integer +index+ is given,
#  the slice begins at the offset given by counting backward from the end of +self+:
#
#    'bar'[-3]         # => "b"
#    'bar'[-1]         # => "r"
#    'bar'[-20]        # => nil
#
#  <b><tt>string[start, length]</tt></b>
#
#  When non-negative integer arguments +start+ and +length+ are given,
#  the slice begins at character offset +start+, if it exists,
#  and continues for +length+ characters, if available:
#
#    'foo'[0, 2]       # => "fo"
#    'тест'[1, 2]      # => "ес"
#    'こんにちは'[2, 2]  # => "にち"
#    # Zero length.
#    'foo'[2, 0]       # => ""
#    # Length not entirely available.
#    'foo'[1, 200]     # => "oo"
#    # Start out of range.
#    'foo'[4, 2]      # => nil
#
#  Special case: if +start+ is equal to the length of +self+,
#  the slice is a new empty string:
#
#    'foo'[3, 2]   # => ""
#    'foo'[3, 200] # => ""
#
#  When negative +start+ and non-negative +length+ are given,
#  the slice beginning is determined by counting backward from the end of +self+,
#  and the slice continues for +length+ characters, if available:
#
#    'foo'[-2, 2]    # => "oo"
#    'foo'[-2, 200]  # => "oo"
#    # Start out of range.
#    'foo'[-4, 2]     # => nil
#
#  When negative +length+ is given, there is no slice:
#
#    'foo'[1, -1]  # => nil
#    'foo'[-2, -1] # => nil
#
#  <b><tt>string[range]</tt></b>
#
#  When Range argument +range+ is given,
#  creates a substring of +string+ using the indices in +range+.
#  The slice is then determined as above:
#
#    'foo'[0..1]    # => "fo"
#    'foo'[0, 2]    # => "fo"
#
#    'foo'[2...2]   # => ""
#    'foo'[2, 0]    # => ""
#
#    'foo'[1..200]  # => "oo"
#    'foo'[1, 200]  # => "oo"
#
#    'foo'[4..5]    # => nil
#    'foo'[4, 2]    # => nil
#
#    'foo'[-4..-3]  # => nil
#    'foo'[-4, 2]   # => nil
#
#    'foo'[3..4]    # => ""
#    'foo'[3, 2]    # => ""
#
#    'foo'[-2..-1]  # => "oo"
#    'foo'[-2, 2]   # => "oo"
#
#    'foo'[-2..197] # => "oo"
#    'foo'[-2, 200] # => "oo"
#
#  <b><tt>string[regexp, capture = 0]</tt></b>
#
#  When the \Regexp argument +regexp+ is given,
#  and the +capture+ argument is <tt>0</tt>,
#  the slice is the first matching substring found in +self+:
#
#    'foo'[/o/] # => "o"
#    'foo'[/x/] # => nil
#    s = 'hello there'
#    s[/[aeiou](.)\1/] # => "ell"
#    s[/[aeiou](.)\1/, 0] # => "ell"
#
#  If argument +capture+ is given and not <tt>0</tt>,
#  it should be either an capture group index (integer)
#  or a capture group name (string or symbol);
#  the slice is the specified capture (see Regexp@Capturing):
#
#    s = 'hello there'
#    s[/[aeiou](.)\1/, 1] # => "l"
#    s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, "non_vowel"] # => "l"
#    s[/(?<vowel>[aeiou])(?<non_vowel>[^aeiou])/, :vowel] # => "e"
#
#  If an invalid capture group index is given, there is no slice.
#  If an invalid capture group name is given, +IndexError+ is raised.
#
#  <b><tt>string[substring]</tt></b>
#
#  When the single \String argument +substring+ is given,
#  returns the substring from +self+ if found, otherwise +nil+:
#
#    'foo'['oo'] # => "oo"
#    'foo'['xx'] # => nil
#
#  == What's Here
#
#  First, what's elsewhere. \Class \String:
#
#  - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
#  - Includes {module Comparable}[rdoc-ref:Comparable@What-27s+Here].
#
#  Here, class \String provides methods that are useful for:
#
#  - {Creating a String}[rdoc-ref:String@Methods+for+Creating+a+String]
#  - {Frozen/Unfrozen Strings}[rdoc-ref:String@Methods+for+a+Frozen-2FUnfrozen+String]
#  - {Querying}[rdoc-ref:String@Methods+for+Querying]
#  - {Comparing}[rdoc-ref:String@Methods+for+Comparing]
#  - {Modifying a String}[rdoc-ref:String@Methods+for+Modifying+a+String]
#  - {Converting to New String}[rdoc-ref:String@Methods+for+Converting+to+New+String]
#  - {Converting to Non-String}[rdoc-ref:String@Methods+for+Converting+to+Non--5CString]
#  - {Iterating}[rdoc-ref:String@Methods+for+Iterating]
#
#  === Methods for Creating a \String
#
#  - ::new: Returns a new string.
#  - ::try_convert: Returns a new string created from a given object.
#
#  === Methods for a Frozen/Unfrozen String
#
#  - #+@: Returns a string that is not frozen: +self+, if not frozen;
#    +self.dup+ otherwise.
#  - #-@: Returns a string that is frozen: +self+, if already frozen;
#    +self.freeze+ otherwise.
#  - #freeze: Freezes +self+, if not already frozen; returns +self+.
#
#  === Methods for Querying
#
#  _Counts_
#
#  - #length, #size: Returns the count of characters (not bytes).
#  - #empty?: Returns +true+ if +self.length+ is zero; +false+ otherwise.
#  - #bytesize: Returns the count of bytes.
#  - #count: Returns the count of substrings matching given strings.
#
#  _Substrings_
#
#  - #=~: Returns the index of the first substring that matches a given
#    Regexp or other object; returns +nil+ if no match is found.
#  - #index: Returns the index of the _first_ occurrence of a given substring;
#    returns +nil+ if none found.
#  - #rindex: Returns the index of the _last_ occurrence of a given substring;
#    returns +nil+ if none found.
#  - #include?: Returns +true+ if the string contains a given substring; +false+ otherwise.
#  - #match: Returns a MatchData object if the string matches a given Regexp; +nil+ otherwise.
#  - #match?: Returns +true+ if the string matches a given Regexp; +false+ otherwise.
#  - #start_with?: Returns +true+ if the string begins with any of the given substrings.
#  - #end_with?: Returns +true+ if the string ends with any of the given substrings.
#
#  _Encodings_
#
#  - #encoding\: Returns the Encoding object that represents the encoding of the string.
#  - #unicode_normalized?: Returns +true+ if the string is in Unicode normalized form; +false+ otherwise.
#  - #valid_encoding?: Returns +true+ if the string contains only characters that are valid
#    for its encoding.
#  - #ascii_only?: Returns +true+ if the string has only ASCII characters; +false+ otherwise.
#
#  _Other_
#
#  - #sum: Returns a basic checksum for the string: the sum of each byte.
#  - #hash: Returns the integer hash code.
#
#  === Methods for Comparing
#
#  - #==, #===: Returns +true+ if a given other string has the same content as +self+.
#  - #eql?: Returns +true+ if the content is the same as the given other string.
#  - #<=>: Returns -1, 0, or 1 as a given other string is smaller than,
#    equal to, or larger than +self+.
#  - #casecmp: Ignoring case, returns -1, 0, or 1 as a given
#    other string is smaller than, equal to, or larger than +self+.
#  - #casecmp?: Returns +true+ if the string is equal to a given string after Unicode case folding;
#    +false+ otherwise.
#
#  === Methods for Modifying a \String
#
#  Each of these methods modifies +self+.
#
#  _Insertion_
#
#  - #insert: Returns +self+ with a given string inserted at a given offset.
#  - #<<: Returns +self+ concatenated with a given string or integer.
#
#  _Substitution_
#
#  - #sub!: Replaces the first substring that matches a given pattern with a given replacement string;
#    returns +self+ if any changes, +nil+ otherwise.
#  - #gsub!: Replaces each substring that matches a given pattern with a given replacement string;
#    returns +self+ if any changes, +nil+ otherwise.
#  - #succ!, #next!: Returns +self+ modified to become its own successor.
#  - #replace: Returns +self+ with its entire content replaced by a given string.
#  - #reverse!: Returns +self+ with its characters in reverse order.
#  - #setbyte: Sets the byte at a given integer offset to a given value; returns the argument.
#  - #tr!: Replaces specified characters in +self+ with specified replacement characters;
#    returns +self+ if any changes, +nil+ otherwise.
#  - #tr_s!: Replaces specified characters in +self+ with specified replacement characters,
#    removing duplicates from the substrings that were modified;
#    returns +self+ if any changes, +nil+ otherwise.
#
#  _Casing_
#
#  - #capitalize!: Upcases the initial character and downcases all others;
#    returns +self+ if any changes, +nil+ otherwise.
#  - #downcase!: Downcases all characters; returns +self+ if any changes, +nil+ otherwise.
#  - #upcase!: Upcases all characters; returns +self+ if any changes, +nil+ otherwise.
#  - #swapcase!: Upcases each downcase character and downcases each upcase character;
#    returns +self+ if any changes, +nil+ otherwise.
#
#  _Encoding_
#
#  - #encode!: Returns +self+ with all characters transcoded from one given encoding into another.
#  - #unicode_normalize!: Unicode-normalizes +self+; returns +self+.
#  - #scrub!: Replaces each invalid byte with a given character; returns +self+.
#  - #force_encoding: Changes the encoding to a given encoding; returns +self+.
#
#  _Deletion_
#
#  - #clear: Removes all content, so that +self+ is empty; returns +self+.
#  - #slice!, #[]=: Removes a substring determined by a given index, start/length, range, regexp, or substring.
#  - #squeeze!: Removes contiguous duplicate characters; returns +self+.
#  - #delete!: Removes characters as determined by the intersection of substring arguments.
#  - #lstrip!: Removes leading whitespace; returns +self+ if any changes, +nil+ otherwise.
#  - #rstrip!: Removes trailing whitespace; returns +self+ if any changes, +nil+ otherwise.
#  - #strip!: Removes leading and trailing whitespace; returns +self+ if any changes, +nil+ otherwise.
#  - #chomp!: Removes trailing record separator, if found; returns +self+ if any changes, +nil+ otherwise.
#  - #chop!: Removes trailing newline characters if found; otherwise removes the last character;
#    returns +self+ if any changes, +nil+ otherwise.
#
#  === Methods for Converting to New \String
#
#  Each of these methods returns a new \String based on +self+,
#  often just a modified copy of +self+.
#
#  _Extension_
#
#  - #*: Returns the concatenation of multiple copies of +self+,
#  - #+: Returns the concatenation of +self+ and a given other string.
#  - #center: Returns a copy of +self+ centered between pad substring.
#  - #concat: Returns the concatenation of +self+ with given other strings.
#  - #prepend: Returns the concatenation of a given other string with +self+.
#  - #ljust: Returns a copy of +self+ of a given length, right-padded with a given other string.
#  - #rjust: Returns a copy of +self+ of a given length, left-padded with a given other string.
#
#  _Encoding_
#
#  - #b: Returns a copy of +self+ with ASCII-8BIT encoding.
#  - #scrub: Returns a copy of +self+ with each invalid byte replaced with a given character.
#  - #unicode_normalize: Returns a copy of +self+ with each character Unicode-normalized.
#  - #encode: Returns a copy of +self+ with all characters transcoded from one given encoding into another.
#
#  _Substitution_
#
#  - #dump: Returns a copy of +self+ with all non-printing characters replaced by \xHH notation
#    and all special characters escaped.
#  - #undump: Returns a copy of +self+ with all <tt>\xNN</tt> notation replace by <tt>\uNNNN</tt> notation
#    and all escaped characters unescaped.
#  - #sub: Returns a copy of +self+ with the first substring matching a given pattern
#    replaced with a given replacement string;.
#  - #gsub: Returns a copy of +self+ with each substring that matches a given pattern
#    replaced with a given replacement string.
#  - #succ, #next: Returns the string that is the successor to +self+.
#  - #reverse: Returns a copy of +self+ with its characters in reverse order.
#  - #tr: Returns a copy of +self+ with specified characters replaced with specified      replacement characters.
#  - #tr_s: Returns a copy of +self+ with specified characters replaced with
#    specified replacement characters,
#    removing duplicates from the substrings that were modified.
#  - #%: Returns the string resulting from formatting a given object into +self+
#
#  _Casing_
#
#  - #capitalize: Returns a copy of +self+ with the first character upcased
#    and all other characters downcased.
#  - #downcase: Returns a copy of +self+ with all characters downcased.
#  - #upcase: Returns a copy of +self+ with all characters upcased.
#  - #swapcase: Returns a copy of +self+ with all upcase characters downcased
#    and all downcase characters upcased.
#
#  _Deletion_
#
#  - #delete: Returns a copy of +self+ with characters removed
#  - #delete_prefix: Returns a copy of +self+ with a given prefix removed.
#  - #delete_suffix: Returns a copy of +self+ with a given suffix removed.
#  - #lstrip: Returns a copy of +self+ with leading whitespace removed.
#  - #rstrip: Returns a copy of +self+ with trailing whitespace removed.
#  - #strip: Returns a copy of +self+ with leading and trailing whitespace removed.
#  - #chomp: Returns a copy of +self+ with a trailing record separator removed, if found.
#  - #chop: Returns a copy of +self+ with trailing newline characters or the last character removed.
#  - #squeeze: Returns a copy of +self+ with contiguous duplicate characters removed.
#  - #[], #slice: Returns a substring determined by a given index, start/length, or range, or string.
#  - #byteslice: Returns a substring determined by a given index, start/length, or range.
#  - #chr: Returns the first character.
#
#  _Duplication_
#
#  - #to_s, $to_str: If +self+ is a subclass of \String, returns +self+ copied into a \String;
#    otherwise, returns +self+.
#
#  === Methods for Converting to Non-\String
#
#  Each of these methods converts the contents of +self+ to a non-\String.
#
#  <em>Characters, Bytes, and Clusters</em>
#
#  - #bytes: Returns an array of the bytes in +self+.
#  - #chars: Returns an array of the characters in +self+.
#  - #codepoints: Returns an array of the integer ordinals in +self+.
#  - #getbyte: Returns an integer byte as determined by a given index.
#  - #grapheme_clusters: Returns an array of the grapheme clusters in +self+.
#
#  _Splitting_
#
#  - #lines: Returns an array of the lines in +self+, as determined by a given record separator.
#  - #partition: Returns a 3-element array determined by the first substring that matches
#    a given substring or regexp,
#  - #rpartition: Returns a 3-element array determined by the last substring that matches
#    a given substring or regexp,
#  - #split: Returns an array of substrings determined by a given delimiter -- regexp or string --
#    or, if a block given, passes those substrings to the block.
#
#  _Matching_
#
#  - #scan: Returns an array of substrings matching a given regexp or string, or,
#    if a block given, passes each matching substring to the  block.
#  - #unpack: Returns an array of substrings extracted from +self+ according to a given format.
#  - #unpack1: Returns the first substring extracted from +self+ according to a given format.
#
#  _Numerics_
#
#  - #hex: Returns the integer value of the leading characters, interpreted as hexadecimal digits.
#  - #oct: Returns the integer value of the leading characters, interpreted as octal digits.
#  - #ord: Returns the integer ordinal of the first character in +self+.
#  - #to_i: Returns the integer value of leading characters, interpreted as an integer.
#  - #to_f: Returns the floating-point value of leading characters, interpreted as a floating-point number.
#
#  <em>Strings and Symbols</em>
#
#  - #inspect: Returns copy of +self+, enclosed in double-quotes, with special characters escaped.
#  - #to_sym, #intern: Returns the symbol corresponding to +self+.
#
#  === Methods for Iterating
#
#  - #each_byte: Calls the given block with each successive byte in +self+.
#  - #each_char: Calls the given block with each successive character in +self+.
#  - #each_codepoint: Calls the given block with each successive integer codepoint in +self+.
#  - #each_grapheme_cluster: Calls the given block with each successive grapheme cluster in +self+.
#  - #each_line: Calls the given block with each successive line in +self+,
#    as determined by a given record separator.
#  - #upto: Calls the given block with each string value returned by successive calls to #succ.

class String; end