ContextQMD
Back to Mruby

mruby-string-ext

mrbgems/mruby-string-ext/README.md

4.0.017.7 KB
Original Source

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