diff --git a/mrbgems/mruby-string-ext/README.md b/mrbgems/mruby-string-ext/README.md new file mode 100644 index 000000000..9b8b8e5ae --- /dev/null +++ b/mrbgems/mruby-string-ext/README.md @@ -0,0 +1,886 @@ +# mruby-string-ext + +This mrbgem adds extended string functionalities to mruby. + +## Methods + +### `String#clear` + +Makes string empty. + +```ruby +string.clear +``` + +Example: + +```ruby +a = "abcde" +a.clear #=> "" +``` + +### `String#lstrip` + +Returns a copy of the string with leading whitespace removed. + +```ruby +str.lstrip +``` + +Example: + +```ruby +" hello ".lstrip #=> "hello " +``` + +### `String#lstrip!` + +Removes leading whitespace from the string, returning `nil` if no change was made. Modifies the receiver in place. + +```ruby +str.lstrip! +``` + +Example: + +```ruby +a = " hello " +a.lstrip! #=> "hello " +b = "hello" +b.lstrip! #=> nil +``` + +### `String#rstrip` + +Returns a copy of the string with trailing whitespace removed. + +```ruby +str.rstrip +``` + +Example: + +```ruby +" hello ".rstrip #=> " hello" +``` + +### `String#rstrip!` + +Removes trailing whitespace from the string, returning `nil` if no change was made. Modifies the receiver in place. + +```ruby +str.rstrip! +``` + +Example: + +```ruby +a = " hello " +a.rstrip! #=> " hello" +b = "hello" +b.rstrip! #=> nil +``` + +### `String#strip` + +Returns a copy of the string with leading and trailing whitespace removed. + +```ruby +str.strip +``` + +Example: + +```ruby +" hello ".strip #=> "hello" +"\tgoodbye\r\n".strip #=> "goodbye" +``` + +### `String#strip!` + +Removes leading and trailing whitespace from the string. Returns `nil` if the string was not altered. Modifies the receiver in place. + +```ruby +str.strip! +``` + +Example: + +```ruby +a = " hello " +a.strip! #=> "hello" +b = "goodbye" +b.strip! #=> nil +``` + +### `String#partition` + +Searches for the first occurrence of the separator `sep` and returns a three-element array: the part before the separator, the separator itself, and the part after the separator. If the separator is not found, returns the original string and two empty strings. + +```ruby +string.partition(sep) +``` + +Example: + +```ruby +"hello".partition("l") #=> ["he", "l", "lo"] +"hello".partition("x") #=> ["hello", "", ""] +``` + +### `String#rpartition` + +Searches for the last occurrence of the separator `sep` and returns a three-element array: the part before the separator, the separator itself, and the part after the separator. If the separator is not found, returns two empty strings and the original string. + +```ruby +string.rpartition(sep) +``` + +Example: + +```ruby +"hello ello".rpartition("l") #=> ["hello el", "l", "o"] +"hello".rpartition("x") #=> ["", "", "hello"] +``` + +### `String#slice!` + +Deletes the specified portion from the string, and returns the portion deleted. Modifies the receiver in place. + +```ruby +str.slice!(fixnum) +str.slice!(fixnum, fixnum) +str.slice!(range) +str.slice!(other_str) +``` + +Example: + +```ruby +string = "hello world" +string.slice!(4) #=> "o" +# string is now "hell world" +string.slice!(2..3) #=> "ll" +# string is now "he world" +string.slice!("l") #=> "l" +# string is now "he word" +string.slice!("nomatch") #=> nil +``` + +### `String#insert` + +Inserts `other_str` before the character at the given `index`, modifying `str`. Negative indices count from the end of the string. + +```ruby +str.insert(index, other_str) +``` + +Example: + +```ruby +"abcd".insert(0, 'X') #=> "Xabcd" +"abcd".insert(3, 'X') #=> "abcXd" +"abcd".insert(4, 'X') #=> "abcdX" +"abcd".insert(-3, 'X') #=> "abXcd" +"abcd".insert(-1, 'X') #=> "abcdX" +``` + +### `String#ljust` + +If `integer` is greater than the length of `str`, returns a new string of length `integer` with `str` left justified and padded with `padstr`; otherwise, returns `str`. + +```ruby +str.ljust(integer, padstr=' ') +``` + +Example: + +```ruby +"hello".ljust(4) #=> "hello" +"hello".ljust(20) #=> "hello " +"hello".ljust(20, '1234') #=> "hello123412341234123" +``` + +### `String#rjust` + +If `integer` is greater than the length of `str`, returns a new string of length `integer` with `str` right justified and padded with `padstr`; otherwise, returns `str`. + +```ruby +str.rjust(integer, padstr=' ') +``` + +Example: + +```ruby +"hello".rjust(4) #=> "hello" +"hello".rjust(20) #=> " hello" +"hello".rjust(20, '1234') #=> "123412341234123hello" +``` + +### `String#center` + +Centers `str` in `width`. If `width` is greater than the length of `str`, returns a new String of length `width` with `str` centered and padded with `padstr`; otherwise, returns `str`. + +```ruby +str.center(width, padstr=' ') +``` + +Example: + +```ruby +"hello".center(4) #=> "hello" +"hello".center(20) #=> " hello " +"hello".center(20, '123') #=> "1231231hello12312312" +``` + +### `String#chars` + +If a block is given, calls the block for each character. Otherwise, returns an array of characters in the string. + +```ruby +str.chars #=> array +str.chars {|char| block } #=> str +``` + +Example: + +```ruby +"hello".chars #=> ["h", "e", "l", "l", "o"] +``` + +### `String#each_char` + +Calls the given block for each character of the string. If no block is given, returns an enumerator. + +```ruby +str.each_char {|char| block } #=> str +str.each_char #=> an_enumerator +``` + +Example: + +```ruby +s = "" +"hello".each_char {|c| s << c << '*' } # s is now "h*e*l*l*o*" +``` + +### `String#codepoints` (alias `each_codepoint`) + +If a block is given, calls the block with the Integer ordinal of each character in the string. If no block is given, returns an array of these ordinals. + +```ruby +str.codepoints #=> array +str.codepoints {|codepoint| block } #=> str +``` + +Example: + +```ruby +"h\u00E9llo".codepoints #=> [104, 233, 108, 108, 111] (if UTF-8 aware) +"hello".codepoints #=> [104, 101, 108, 108, 111] +``` + +### `String#prepend` + +Prepends the given string(s) to `str`. Modifies `str` in place. + +```ruby +str.prepend(other_str, ...) +``` + +Example: + +```ruby +a = "world" +a.prepend("hello ") #=> "hello world" +a #=> "hello world" +a.prepend("Greeting: ", "Bob! ") #=> "Greeting: Bob! hello world" +``` + +### `String#lines` + +Returns an array of strings, where each string is a line from the original string. Lines are separated by `\n`. If a block is given, it works the same as `each_line`. + +```ruby +string.lines #=> array +string.lines {|s| block} #=> string +``` + +Example: + +```ruby +a = "abc\ndef" +a.lines #=> ["abc\n", "def"] +"hello\nworld".lines {|line| puts line } # prints "hello\n" then "world" +``` + +### `String#upto` + +Iterates through successive values, starting at `str` and ending at `other_str` inclusive (unless `exclusive` is true). The `String#succ` method is used to generate each value. + +```ruby +str.upto(other_str, exclusive=false) {|s| block } #=> str +str.upto(other_str, exclusive=false) #=> an_enumerator +``` + +Example: + +```ruby +"a8".upto("b1") {|s| print s, ' ' } #=> prints: a8 a9 b0 b1 +"9".upto("11").to_a #=> ["9", "10", "11"] +"07".upto("11").to_a #=> ["07", "08", "09", "10", "11"] +"a".upto("c", true).to_a #=> ["a", "b"] +``` + +### `String#swapcase` + +Returns a copy of `str` with uppercase alphabetic characters converted to lowercase and lowercase characters converted to uppercase. Effective only in ASCII region. + +```ruby +str.swapcase #=> new_str +``` + +Example: + +```ruby +"Hello".swapcase #=> "hELLO" +"cYbEr_PuNk11".swapcase #=> "CyBeR_pUnK11" +``` + +### `String#swapcase!` + +Equivalent to `String#swapcase`, but modifies the receiver in place. Returns `str`, or `nil` if no changes were made. + +```ruby +str.swapcase! #=> str or nil +``` + +Example: + +```ruby +a = "Hello" +a.swapcase! #=> "hELLO" +a #=> "hELLO" +b = "123" +b.swapcase! #=> nil +``` + +### `String#concat` (alias `String#<<`) + +Appends the argument(s) to the string. If an argument is an Integer, it's considered a codepoint and converted to a character. Modifies the string in place. + +```ruby +str.concat(other_str, ...) #=> str +str << obj #=> str +``` + +Example: + +```ruby +s = 'foo' +s.concat('bar', 'baz') # => "foobarbaz" +s # => "foobarbaz" +s = 'foo' +s << 'bar' << 32 << 'baz' # => "foobar baz" (32 is space) +``` + +### `String#append_as_bytes` + +Works like `concat` but considers arguments as binary strings. Integer arguments are treated as byte values (0-255) and converted to characters. + +```ruby +str.append_as_bytes(*obj) #=> str +``` + +Example: + +```ruby +s = "test" +s.append_as_bytes(32, "bytes", 33) #=> "test bytes!" (32 is space, 33 is !) +s.append_as_bytes(256) #=> RangeError (byte 256 out of range) +``` + +### `String#start_with?` + +Returns true if `str` starts with one of the `prefixes` given. + +```ruby +str.start_with?([prefixes]+) #=> true or false +``` + +Example: + +```ruby +"hello".start_with?("hell") #=> true +"hello".start_with?("heaven", "hell") #=> true +"hello".start_with?("heaven", "paradise") #=> false +``` + +### `String#end_with?` + +Returns true if `str` ends with one of the `suffixes` given. + +```ruby +str.end_with?([suffixes]+) #=> true or false +``` + +Example: + +```ruby +"hello".end_with?("llo") #=> true +"hello".end_with?("heaven", "llo") #=> true +"hello".end_with?("heaven", "paradise") #=> false +``` + +### `String#tr` + +Returns a copy of `str` with the characters in `from_str` replaced by the corresponding characters in `to_str`. +Supports `c1-c2` range notation and `^` for negation in `from_str`. + +```ruby +str.tr(from_str, to_str) #=> new_str +``` + +Example: + +```ruby +"hello".tr('el', 'ip') #=> "hippo" +"hello".tr('aeiou', '*') #=> "h*ll*" +"hello".tr('a-y', 'b-z') #=> "ifmmp" +"hello".tr('^aeiou', '*') #=> "*e**o" +``` + +### `String#tr!` + +Translates `str` in place, using the same rules as `String#tr`. Returns `str`, or `nil` if no changes were made. + +```ruby +str.tr!(from_str, to_str) #=> str or nil +``` + +Example: + +```ruby +a = "hello" +a.tr!('el', 'ip') #=> "hippo" +a #=> "hippo" +b = "hello" +b.tr!('xyz', '123') #=> nil +``` + +### `String#tr_s` + +Processes a copy of `str` as described under `String#tr`, then removes duplicate characters in regions that were affected by the translation (squeeze). + +```ruby +str.tr_s(from_str, to_str) #=> new_str +``` + +Example: + +```ruby +"hello".tr_s('l', 'r') #=> "hero" +"hello".tr_s('el', '*') #=> "h*o" +"hello".tr_s('el', 'hx') #=> "hhxo" +``` + +### `String#tr_s!` + +Performs `String#tr_s` processing on `str` in place, returning `str`, or `nil` if no changes were made. + +```ruby +str.tr_s!(from_str, to_str) #=> str or nil +``` + +Example: + +```ruby +a = "hello" +a.tr_s!('l', 'r') #=> "hero" +a #=> "hero" +b = "hello" +b.tr_s!('x', 'y') #=> nil +``` + +### `String#squeeze` + +Builds a set of characters from the `other_str` parameter(s). Returns a new string where runs of the same character that occur in this set are replaced by a single character. If no arguments are given, all runs of identical characters are replaced. + +```ruby +str.squeeze([other_str]) #=> new_str +``` + +Example: + +```ruby +"yellow moon".squeeze #=> "yelow mon" +" now is the".squeeze(" ") #=> " now is the" +"putters shoot balls".squeeze("m-z") #=> "puters shot balls" +``` + +### `String#squeeze!` + +Squeezes `str` in place, returning either `str`, or `nil` if no changes were made. + +```ruby +str.squeeze!([other_str]) #=> str or nil +``` + +Example: + +```ruby +a = "yellow moon" +a.squeeze! #=> "yelow mon" +a #=> "yelow mon" +b = "abc" +b.squeeze! #=> nil +``` + +### `String#delete` + +Returns a copy of `str` with all characters in the intersection of its arguments removed. Arguments are selectors like for `String#count`. + +```ruby +str.delete([other_str]+) #=> new_str +``` + +Example: + +```ruby +"hello".delete "l" #=> "heo" +"hello".delete "aeiou" #=> "hll" +"hello".delete "aeiou", "^l" #=> "l" (deletes vowels, but not 'l') +``` + +### `String#delete!` + +Performs a `delete` operation in place, returning `str`, or `nil` if `str` was not modified. + +```ruby +str.delete!([other_str]+) #=> str or nil +``` + +Example: + +```ruby +a = "hello" +a.delete!("l") #=> "heo" +a #=> "heo" +b = "hello" +b.delete!("xyz") #=> nil +``` + +### `String#count` + +Each `other_str` parameter defines a set of characters to count. The intersection of these sets defines the characters to count in `str`. + +```ruby +str.count([other_str]+) #=> integer +``` + +Example: + +```ruby +"hello world".count("lo") #=> 5 +"hello world".count("lo", "o") #=> 2 (chars 'l' and 'o', but only 'o' is in both sets) +"hello world".count("h") #=> 1 +"hello world".count("a-e", "h-l") #=> 3 (chars 'h', 'e', 'l') +"hello world".count("^l") #=> 8 (all chars except 'l') +``` + +### `String#hex` + +Treats leading characters of `str` as a string of hexadecimal digits (with an optional sign and an optional `0x`) and returns the corresponding number. + +```ruby +str.hex #=> integer +``` + +Example: + +```ruby +"0x0a".hex #=> 10 +"10".hex #=> 16 +"-10".hex #=> -16 +"ff".hex #=> 255 +"hello".hex #=> 0 (if no valid hex digits at start) +"0xhello".hex #=> 0 +``` + +### `String#oct` + +Treats leading characters of `str` as a string of octal digits (with an optional sign) and returns the corresponding number. + +```ruby +str.oct #=> integer +``` + +Example: + +```ruby +"10".oct #=> 8 +"010".oct #=> 8 +"-10".oct #=> -8 +"077".oct #=> 63 +"hello".oct #=> 0 (if no valid octal digits at start) +"0o10".oct #=> 8 (common prefix, depends on MRuby version) +``` + +### `String#chr` (on String instances) + +Returns a one-character string at the beginning of the string. + +```ruby +string.chr #=> string +``` + +Example: + +```ruby +a = "abcde" +a.chr #=> "a" +"".chr #=> "" (or error, mruby specific behavior might differ from CRuby) +``` + +### `Integer#chr` + +Returns a string containing the character represented by the `int`'s value according to `encoding`. + +```ruby +int.chr([encoding]) #=> string +``` + +Example: + +```ruby +65.chr #=> "A" +230.chr #=> "\xE6" (in ASCII-8BIT) +230.chr("ASCII-8BIT") #=> "\xE6" +# 230.chr("UTF-8") #=> "\u00E6" (if MRB_UTF8_STRING enabled) +``` + +### `String#succ` (alias `String#next`) + +Returns the successor to `str`. Increments the rightmost alphanumeric characters. + +```ruby +str.succ #=> new_str +``` + +Example: + +```ruby +"a".succ #=> "b" +"z".succ #=> "aa" +"9".succ #=> "10" +"a9".succ #=> "b0" +"Az".succ #=> "Ba" +"zz".succ #=> "aaa" +``` + +### `String#succ!` (alias `String#next!`) + +Equivalent to `String#succ`, but modifies the receiver in place. + +```ruby +str.succ! #=> str +``` + +Example: + +```ruby +a = "a9" +a.succ! #=> "b0" +a #=> "b0" +``` + +### `String#ord` + +Returns the Integer ordinal (codepoint) of the first character in `str`. + +```ruby +str.ord #=> integer +``` + +Example: + +```ruby +"a".ord #=> 97 +"A".ord #=> 65 +"\u20AC".ord #=> 8364 (if UTF-8 and character is euro sign) +"".ord #=> ArgumentError (empty string) +``` + +### `String#delete_prefix` + +Returns a copy of `str` with leading `prefix` deleted. + +```ruby +str.delete_prefix(prefix) -> new_str +``` + +Example: + +```ruby +"hello".delete_prefix("hel") #=> "lo" +"hello".delete_prefix("llo") #=> "hello" +``` + +### `String#delete_prefix!` + +Deletes leading `prefix` from `str`, returning `nil` if no change was made. Modifies the receiver in place. + +```ruby +str.delete_prefix!(prefix) -> self or nil +``` + +Example: + +```ruby +a = "hello" +a.delete_prefix!("hel") #=> "lo" +a #=> "lo" +b = "hello" +b.delete_prefix!("llo") #=> nil +``` + +### `String#delete_suffix` + +Returns a copy of `str` with trailing `suffix` deleted. + +```ruby +str.delete_suffix(suffix) -> new_str +``` + +Example: + +```ruby +"hello".delete_suffix("llo") #=> "he" +"hello".delete_suffix("hel") #=> "hello" +``` + +### `String#delete_suffix!` + +Deletes trailing `suffix` from `str`, returning `nil` if no change was made. Modifies the receiver in place. + +```ruby +str.delete_suffix!(suffix) -> self or nil +``` + +Example: + +```ruby +a = "hello" +a.delete_suffix!("llo") #=> "he" +a #=> "he" +b = "hello" +b.delete_suffix!("hel") #=> nil +``` + +### `String#casecmp` + +Case-insensitive version of `String#<=>`. Returns -1, 0, or +1. Returns `nil` if `other_str` is not a String. + +```ruby +str.casecmp(other_str) #=> -1, 0, +1 or nil +``` + +Example: + +```ruby +"abcdef".casecmp("abcde") #=> 1 +"aBcDeF".casecmp("abcdef") #=> 0 +"abcdef".casecmp("abcdefg") #=> -1 +"abcdef".casecmp("ABCDEF") #=> 0 +``` + +### `String#casecmp?` + +Returns `true` if `str` and `other_str` are equal after case folding, `false` if they are not equal, and `nil` if `other_str` is not a String. + +```ruby +str.casecmp?(other_str) #=> true, false, or nil +``` + +Example: + +```ruby +"aBcDeF".casecmp?("abcdef") #=> true +"aBcDeF".casecmp?("abcdeg") #=> false +``` + +### `String#+@` (Unary Plus) + +Returns `self` if `self` is not frozen. Otherwise returns a mutable (not frozen) duplicate of `self`. + +```ruby ++string #=> new_string or self +``` + +Example: + +```ruby +a = "hello" +b = +a +a.equal?(b) #=> true (both point to the same object) + +c = "world".freeze +d = +c +c.equal?(d) #=> false (d is a mutable copy) +d.frozen? #=> false +``` + +### `String#-@` (Unary Minus) + +Returns a frozen, possibly pre-existing (interned) copy of the string. + +```ruby +-string #=> frozen_string +``` + +Example: + +```ruby +a = "hello" +b = -a +a.equal?(b) #=> false (b is a different, frozen object) +b.frozen? #=> true + +c = "world".freeze +d = -c +c.equal?(d) #=> true (if c was already suitably frozen/interned) +``` + +### `String#ascii_only?` + +Returns `true` if `str` contains only ASCII characters. + +```ruby +str.ascii_only? #=> true or false +``` + +Example: + +```ruby +"abc".ascii_only? #=> true +"abc\x80".ascii_only? #=> false (if \x80 is considered non-ASCII) +"日本語".ascii_only? #=> false +``` + +### `String#b` + +Returns a copy of `str` with its encoding set to ASCII-8BIT (binary). + +```ruby +str.b #=> new_str_in_binary_encoding +``` + +Example: + +```ruby +# Assuming str was UTF-8 +str_utf8 = "\u00E9" # "é" +str_bin = str_utf8.b +# str_bin might be "\xC3\xA9" if that's the UTF-8 byte representation +# str_bin.encoding will be ASCII-8BIT +```