String
class String
Overview
A String
represents an immutable sequence of UTF-8 characters.
A String
is typically created with a string literal, enclosing UTF-8 characters in double quotes:
"hello world"
A backslash can be used to denote some characters inside the string:
"\"" # double quote "\\" # backslash "\e" # escape "\f" # form feed "\n" # newline "\r" # carriage return "\t" # tab "\v" # vertical tab
You can use a backslash followed by an u and four hexadecimal characters to denote a unicode codepoint written:
"\u0041" # == "A"
Or you can use curly braces and specify up to six hexadecimal numbers (0 to 10FFFF):
"\u{41}" # == "A"
A string can span multiple lines:
"hello world" # same as "hello\n world"
Note that in the above example trailing and leading spaces, as well as newlines, end up in the resulting string. To avoid this, you can split a string into multiple lines by joining multiple literals with a backslash:
"hello " \ "world, " \ "no newlines" # same as "hello world, no newlines"
Alternatively, a backslash followed by a newline can be inserted inside the string literal:
"hello \ world, \ no newlines" # same as "hello world, no newlines"
In this case, leading whitespace is not included in the resulting string.
If you need to write a string that has many double quotes, parentheses, or similar characters, you can use alternative literals:
# Supports double quotes and nested parentheses %(hello ("world")) # same as "hello (\"world\")" # Supports double quotes and nested brackets %[hello ["world"]] # same as "hello [\"world\"]" # Supports double quotes and nested curlies %{hello {"world"}} # same as "hello {\"world\"}" # Supports double quotes and nested angles %<hello <"world">> # same as "hello <\"world\">"
To create a String
with embedded expressions, you can use string interpolation:
a = 1 b = 2 "sum = #{a + b}" # "sum = 3"
This ends up invoking Object#to_s(IO)
on each expression enclosed by #{...}
.
If you need to dynamically build a string, use String#build
or IO::Memory
.
Non UTF-8 valid strings
String might end up being conformed of bytes which are an invalid byte sequence according to UTF-8. This can happen if the string is created via one of the constructors that accept bytes, or when getting a string from String.build
or IO::Memory
. No exception will be raised, but invalid byte sequences, when asked as chars, will use the unicode replacement char (value 0xFFFD). For example:
# here 255 is not a valid byte value in the UTF-8 encoding string = String.new(Bytes[255, 97]) string.valid_encoding? # => false # The first char here is the unicode replacement char string.chars # => ['�', 'a']
One can also create strings with specific byte value in them by using octal and hexadecimal escape sequences:
# Octal escape sequences "\101" # # => "A" "\12" # # => "\n" "\1" # string with one character with code point 1 "\377" # string with one byte with value 255 # Hexadecimal escape sequences "\x45" # # => "A" "\xFF" # string with one byte with value 255
The reason for allowing strings that don't have a valid UTF-8 sequence is that the world is full of content that isn't properly encoded, and having a program raise an exception or stop because of this is not good. It's better if programs are more resilient, but show a replacement character when there's an error in incoming data.
Included Modules
Defined in:
string.crbig/big_int.cr
big/big_float.cr
json/to_json.cr
yaml/to_yaml.cr
Class Method Summary
- .build(capacity = 64, &block) : self
Builds a
String
by creating aString::Builder
with the given initial capacity, yielding it to the block and finally getting aString
out of it. - .new(bytes : Bytes, encoding : String, invalid : Symbol? = nil) : String
Creates a new
String
from the given bytes, which are encoded in the given encoding. - .new(chars : Pointer(UInt8), bytesize, size = 0)
Creates a new
String
from a pointer, indicating its bytesize count and, optionally, the UTF-8 codepoints count (size). - .new(slice : Bytes)
Creates a
String
from the given slice. - .new(chars : Pointer(UInt8))
Creates a
String
from a pointer. - .new(capacity : Int, &block)
- .new(pull : JSON::PullParser)
- .new(pull : YAML::PullParser)
Instance Method Summary
- #%(other)
Interpolates other into the string using
Kernel#sprintf
. - #*(times : Int)
Makes a new
String
by adding str to itself times times. - #+(other : self)
Concatenates str and other.
- #+(char : Char)
Concatenates str and other.
- #<=>(other : self)
Compares this string with other, returning
-1
,0
or+1
depending on whether this string is less, equal or greater than other. - #==(other : self)
- #=~(other)
Tests whether str matches regex.
- #=~(regex : Regex)
Tests whether str matches regex.
- #[](start : Int, count : Int)
Returns a substring starting from the start character of size count.
- #[](regex : Regex, group)
- #[](index : Int)
Returns the
Char
at the given index, or raisesIndexError
if out of bounds- - #[](range : Range(Int, Int))
Returns a substring by using a Range's begin and end as character indices.
- #[](str : String | Char)
- #[](regex : Regex)
- #[]?(regex : Regex)
- #[]?(index : Int)
- #[]?(regex : Regex, group)
- #[]?(str : String | Char)
- #ascii_only?
Returns
true
if this String is comprised in its entirety by ASCII characters. - #at(index : Int)
- #at(index : Int, &block)
- #blank?
Returns
true
if this string consists exclusively of unicode whitespace. - #byte_at(index, &block)
- #byte_at(index)
- #byte_at?(index)
- #byte_index(string : String, offset = 0)
- #byte_index(byte : Int, offset = 0)
- #byte_index_to_char_index(index)
Returns the char index of a byte index, or
nil
if out of bounds. - #byte_slice(start : Int, count : Int)
- #byte_slice(start : Int)
- #bytes
- #bytesize : Int32
Returns the number of bytes in this string.
- #camelcase
Converts underscores to camelcase boundaries.
- #capitalize(options = Unicode::CaseOptions::None)
Returns a new
String
with the first letter converted to uppercase and every subsequent letter converted to lowercase. - #char_at(index)
- #char_index_to_byte_index(index)
Returns the byte index of a char index, or
nil
if out of bounds. - #chars
Returns an
Array
of all characters in the string- - #check_no_null_byte
Raises an
ArgumentError
ifself
has null bytes. - #chomp
Returns a new
String
with the last carriage return removed (that is, it will remove \n, \r, and \r\n). - #chomp(suffix : String)
Returns a new
String
with suffix removed from the end of the string. - #chomp(suffix : Char)
Returns a new
String
with suffix removed from the end of the string. - #clone
- #codepoint_at(index)
- #codepoints
Returns an
Array
of the codepoints that make the string- - #compare(other : String, case_insensitive = false)
Compares this string with other, returning
-1
,0
or+1
depending on whether this string is less, equal or greater than other, optionally in a case_insensitive manner. - #count(&block)
Yields each char in this string to the block, returns the number of times the block returned a truthy value.
- #count(other : Char)
Counts the occurrences of other char in this string.
- #count(*sets)
Sets should be a list of strings following the rules described at
Char#in_set?
. - #delete(&block)
Yields each char in this string to the block.
- #delete(char : Char)
Returns a new
String
with all occurrences of char removed. - #delete(*sets)
Sets should be a list of strings following the rules described at
Char#in_set?
. - #downcase(options = Unicode::CaseOptions::None)
Returns a new
String
with each uppercase letter replaced with its lowercase counterpart. - #dump(io)
- #dump
- #dump_unquoted(io)
- #dump_unquoted
- #dup
- #each_byte
Returns an
Iterator
over each byte in the string. - #each_byte(&block)
Yields each byte in the string to the block.
- #each_char
Returns an
Iterator
over each character in the string. - #each_char(&block) : Nil
Yields each character in the string to the block.
- #each_char_with_index(&block)
Yields each character and its index in the string to the block.
- #each_codepoint(&block)
Yields each codepoint to the block.
- #each_codepoint
Returns an
Iterator
for each codepoint. - #each_line(chomp = true)
Returns an
Iterator
which yields each line of this string (seeString#each_line
). - #each_line(chomp = true, &block) : Nil
Splits the string after each newline and yields each line to a block.
- #empty?
Returns
true
if this is the empty string,""
. - #encode(encoding : String, invalid : Symbol? = nil) : Bytes
Returns a slice of bytes containing this string encoded in the given encoding.
- #ends_with?(char : Char)
- #ends_with?(str : String)
- #gsub(string : String, &block)
Returns a
String
where all occurrences of the given string are replaced with the block's value. - #gsub(&block : Char -> _)
Returns a
String
where each character yielded to the given block is replaced by the block's return value. - #gsub(char : Char, replacement)
Returns a
String
where all occurrences of the given char are replaced with the given replacement. - #gsub(pattern : Regex, hash : Hash(String, _) | NamedTuple)
Returns a
String
where all occurrences of the given pattern are replaced with a hash of replacements. - #gsub(pattern : Regex, replacement, backreferences = true)
Returns a
String
where all occurrences of the given pattern are replaced with the given replacement. - #gsub(string : String, replacement)
Returns a
String
where all occurrences of the given string are replaced with the given replacement. - #gsub(hash : Hash(Char, _))
Returns a
String
where all chars in the given hash are replaced by the corresponding hash values. - #gsub(tuple : NamedTuple)
Returns a
String
where all chars in the given named tuple are replaced by the corresponding tuple values. - #gsub(pattern : Regex, &block)
Returns a
String
where all occurrences of the given pattern are replaced by the block value's value. - #has_back_references?
This returns
true
if this string has'\\'
in it. - #hash
Returns a hash based on this string’s size and content.
- #hexbytes : Bytes
Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes.
- #hexbytes? : Bytes?
Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes.
- #includes?(search : Char | String)
Returns
true
if the string contains search. - #index(search : Regex, offset = 0)
Returns the index of search in the string, or
nil
if the string is not present. - #index(search : String, offset = 0)
Returns the index of search in the string, or
nil
if the string is not present. - #index(search : Char, offset = 0)
Returns the index of search in the string, or
nil
if the string is not present. - #insert(index : Int, other : Char)
Returns a new
String
that results of inserting other inself
at index. - #insert(index : Int, other : String)
Returns a new
String
that results of inserting other inself
at index. - #inspect(io)
- #inspect_unquoted
- #inspect_unquoted(io)
- #lchop
Returns a new
String
with the first char removed from it. - #lchop(prefix : String)
Returns a new
String
with prefix removed from the beginning of the string. - #lchop(prefix : Char)
Returns a new
String
with prefix removed from the beginning of the string. - #lines(chomp = true)
- #ljust(len, char : Char = ' ')
Adds instances of char to right of the string until it is at least size of len.
- #lstrip(char : Char)
Returns a new string with leading occurrences of char removed.
- #lstrip
Returns a new
String
with leading whitespace removed. - #lstrip(&block : Char -> _)
Returns a new string where leading characters for which the block returns a truthy value are removed.
- #lstrip(chars : String)
Returns a new string where leading occurrences of any char in chars are removed.
- #match(regex : Regex, pos = 0) : Regex::MatchData?
Finds match of regex, starting at pos.
- #partition(search : Regex) : Tuple(String, String, String)
- #partition(search : Char | String) : Tuple(String, String, String)
- #pretty_print(pp)
- #rchop
Returns a new
String
with the last character removed. - #rchop(suffix : String)
Returns a new
String
with suffix removed from the end of the string. - #rchop(suffix : Char)
Returns a new
String
with suffix removed from the end of the string. - #reverse
Reverses the order of characters in the string.
- #rindex(search : Char, offset = size - 1)
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
- #rindex(search : String, offset = size - search.size)
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
- #rindex(search : Regex, offset = 0)
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
- #rjust(len, char : Char = ' ')
Adds instances of char to left of the string until it is at least size of len.
- #rpartition(search : Char | String) : Tuple(String, String, String)
- #rpartition(search : Regex) : Tuple(String, String, String)
- #rstrip
Returns a new
String
with trailing whitespace removed. - #rstrip(chars : String)
Returns a new string where trailing occurrences of any char in chars are removed.
- #rstrip(char : Char)
Returns a new string with trailing occurrences of char removed.
- #rstrip(&block : Char -> _)
Returns a new string where trailing characters for which the block returns a truthy value are removed.
- #scan(pattern : String)
Searches the string for instances of pattern, returning an array of the matched string for each match.
- #scan(pattern : Regex, &block)
Searches the string for instances of pattern, yielding a
Regex::MatchData
for each match. - #scan(pattern : Regex)
Searches the string for instances of pattern, returning an
Array
ofRegex::MatchData
for each match. - #scan(pattern : String, &block)
Searches the string for instances of pattern, yielding the matched string for each match.
- #scrub(replacement = Char::REPLACEMENT) : String
Returns a String where bytes that are invalid in the UTF-8 encoding are replaced with replacement.
- #size
Returns the number of unicode codepoints in this string.
- #split(separator : Regex, limit = nil, &block : String -> _)
Makes an
Array
by splitting the string on separator (and removing instances of separator)- - #split(separator : Regex, limit = nil)
Splits the string after each regex separator and yields each part to a block.
- #split(separator : String, limit = nil, &block : String -> _)
Splits the string after each string separator and yields each part to a block.
- #split(limit : Int32? = nil)
Makes an array by splitting the string on any ASCII whitespace characters (and removing that whitespace).
- #split(limit : Int32? = nil, &block : String -> _)
Splits the string after any ASCII whitespace character and yields each part to a block.
- #split(separator : Char, limit = nil)
Makes an
Array
by splitting the string on the given character separator (and removing that character)- - #split(separator : String, limit = nil)
Makes an
Array
by splitting the string on separator (and removing instances of separator)- - #split(separator : Char, limit = nil, &block : String -> _)
Splits the string after each character separator and yields each part to a block.
- #squeeze(&block)
Yields each char in this string to the block.
- #squeeze(char : Char)
Returns a new
String
, with all runs of char replaced by one instance. - #squeeze
Returns a new
String
, that has all characters removed, that were the same as the previous one. - #squeeze(*sets : String)
Sets should be a list of strings following the rules described at
Char#in_set?
. - #starts_with?(char : Char)
- #starts_with?(str : String)
- #strip(&block : Char -> _)
Returns a new string where leading and trailing characters for which the block returns a truthy value are removed.
- #strip
Returns a new
String
with leading and trailing whitespace removed. - #strip(chars : String)
Returns a new string where leading and trailing occurrences of any char in chars are removed.
- #strip(char : Char)
Returns a new string where leading and trailing occurrences of char are removed.
- #sub(pattern : Regex, &block)
Returns a
String
where the first occurrence of pattern is replaced by the block's return value. - #sub(index : Int, replacement : Char)
Returns a new
String
with the character at the given index replaced by replacement. - #sub(index : Int, replacement : String)
Returns a new
String
with the character at the given index replaced by replacement. - #sub(range : Range(Int, Int), replacement : Char)
Returns a new
String
with characters at the given range replaced by replacement. - #sub(range : Range(Int, Int), replacement : String)
Returns a new
String
with characters at the given range replaced by replacement. - #sub(hash : Hash(Char, _))
Returns a
String
where the first char in the string matching a key in the given hash is replaced by the corresponding hash value. - #sub(&block : Char -> _)
Returns a new
String
where the first character is yielded to the given block and replaced by its return value. - #sub(char : Char, replacement)
Returns a
String
where the first occurrence of char is replaced by replacement. - #sub(string : String, &block)
Returns a
String
where the first occurrences of the given string is replaced with the block's value. - #sub(pattern : Regex, replacement, backreferences = true)
Returns a
String
where the first occurrence of pattern is replaced by replacement - #sub(pattern : Regex, hash : Hash(String, _) | NamedTuple)
Returns a
String
where the first occurrences of the given pattern is replaced with the matching entry from the hash of replacements. - #sub(string : String, replacement)
Returns a
String
where the first occurrences of the given string is replaced with the given replacement. - #succ
Returns the successor of the string.
- #to_big_f
- #to_big_i(base = 10) : BigInt
Returns a
BigInt
from this string, in the given base. - #to_f(whitespace = true, strict = true)
Returns the result of interpreting characters in this string as a floating point number (
Float64
). - #to_f32(whitespace = true, strict = true)
Same as
#to_f
but returns a Float32. - #to_f32?(whitespace = true, strict = true)
Same as
#to_f?
but returns a Float32. - #to_f64(whitespace = true, strict = true)
Same as
#to_f
. - #to_f64?(whitespace = true, strict = true)
Same as
#to_f?
. - #to_f?(whitespace = true, strict = true)
Returns the result of interpreting characters in this string as a floating point number (
Float64
). - #to_i(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_i(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true)
Returns the result of interpreting leading characters in this string as an integer base base (between 2 and 36).
- #to_i16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_i16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int16
- #to_i16?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int16?
- #to_i32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int32
Same as
#to_i
. - #to_i32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
Same as
#to_i
. - #to_i32?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int32?
Same as
#to_i
. - #to_i64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_i64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int64
- #to_i64?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int64?
- #to_i8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int8
- #to_i8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_i8?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int8?
- #to_i?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true)
- #to_json(json : JSON::Builder)
- #to_s(io)
- #to_s
- #to_slice : Bytes
Returns the underlying bytes of this String in an unsafe way.
- #to_u16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt16
- #to_u16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_u16?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt16?
- #to_u32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_u32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt32
- #to_u32?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt32?
- #to_u64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_u64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt64
- #to_u64?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt64?
- #to_u8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt8
- #to_u8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)
- #to_u8?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt8?
- #to_unsafe : Pointer(UInt8)
Returns a pointer to the underlying bytes of this String.
- #to_yaml(yaml : YAML::Builder)
- #tr(from : String, to : String)
Returns a new string translating characters using from and to as a map.
- #underscore
Converts camelcase boundaries to underscores.
- #unsafe_byte_at(index)
- #unsafe_byte_slice(byte_offset, count)
- #unsafe_byte_slice(byte_offset)
- #upcase(options = Unicode::CaseOptions::None)
Returns a new
String
with each lowercase letter replaced with its uppercase counterpart. - #valid_encoding?
Returns
true
if this String is encoded correctly according to the UTF-8 encoding.
Instance methods inherited from module Comparable(self)
<, <=(other : T) <=, <=>(other : T) <=>, ==(other : T) ==, >(other : T) >, >=(other : T) >= Instance methods inherited from class Reference
==(other : self)==(other) ==, dup dup, hash hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Class methods inherited from class Reference
new new Instance methods inherited from class Object
!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash hash, inspect(io : IO)
inspect inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s
to_s(io : IO) to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try
Class methods inherited from class Object
from_json(string_or_io, root : String) : selffrom_json(string_or_io) : self from_json, from_yaml(string_or_io) : self from_yaml
Class Method Detail
def self.build(capacity = 64, &block) : selfSource
Builds a String
by creating a String::Builder
with the given initial capacity, yielding it to the block and finally getting a String
out of it. The String::Builder
automatically resizes as needed.
str = String.build do |str| str << "hello " str << 1 end str # => "hello 1"
def self.new(bytes : Bytes, encoding : String, invalid : Symbol? = nil) : StringSource
Creates a new String
from the given bytes, which are encoded in the given encoding.
The invalid argument can be:
-
nil
: an exception is raised on invalid byte sequences -
:skip
: invalid byte sequences are ignored
slice = Slice.new(2, 0_u8) slice[0] = 186_u8 slice[1] = 195_u8 String.new(slice, "GB2312") # => "好"
def self.new(chars : Pointer(UInt8), bytesize, size = 0)Source
Creates a new String
from a pointer, indicating its bytesize count and, optionally, the UTF-8 codepoints count (size). Bytes
will be copied from the pointer.
If the given size is zero, the amount of UTF-8 codepoints will be lazily computed when needed.
ptr = Pointer.malloc(4) { |i| ('a'.ord + i).to_u8 } String.new(ptr, 2) # => "ab"
def self.new(chars : Pointer(UInt8))Source
Creates a String
from a pointer. Bytes
will be copied from the pointer.
This method is unsafe: the pointer must point to data that eventually contains a zero byte that indicates the ends of the string. Otherwise, the result of this method is undefined and might cause a segmentation fault.
This method is typically used in C bindings, where you get a char*
from a library and the library guarantees that this pointer eventually has an ending zero byte.
ptr = Pointer.malloc(5) { |i| i == 4 ? 0_u8 : ('a'.ord + i).to_u8 } String.new(ptr) # => "abcd"
def self.new(capacity : Int, &block)Source
Creates a new String
by allocating a buffer (Pointer(UInt8)
) with the given capacity, then yielding that buffer. The block must return a tuple with the bytesize and size (UTF-8 codepoints count) of the String. If the returned size is zero, the UTF-8 codepoints count will be lazily computed.
The bytesize returned by the block must be less than or equal to the capacity given to this String, otherwise ArgumentError
is raised.
If you need to build a String
where the maximum capacity is unknown, use String#build
.
str = String.new(4) do |buffer| buffer[0] = 'a'.ord.to_u8 buffer[1] = 'b'.ord.to_u8 {2, 2} end str # => "ab"
def self.new(pull : JSON::PullParser)Source
def self.new(pull : YAML::PullParser)Source
Instance Method Detail
def %(other)Source
Interpolates other into the string using Kernel#sprintf
.
"Party like it's %d!!!" % 1999 # => "Party like it's 1999!!!"
def *(times : Int)Source
Makes a new String
by adding str to itself times times.
"Developers! " * 4 # => "Developers! Developers! Developers! Developers!"
def +(other : self)Source
Concatenates str and other.
"abc" + "def" # => "abcdef" "abc" + 'd' # => "abcd"
def +(char : Char)Source
Concatenates str and other.
"abc" + "def" # => "abcdef" "abc" + 'd' # => "abcd"
def <=>(other : self)Source
Compares this string with other, returning -1
, 0
or +1
depending on whether this string is less, equal or greater than other.
Comparison is done byte-per-byte: if a byte is less then the other corresponding byte, -1
is returned and so on.
If the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered greater than the shorter one.
"abcdef" <=> "abcde" # => 1 "abcdef" <=> "abcdef" # => 0 "abcdef" <=> "abcdefg" # => -1 "abcdef" <=> "ABCDEF" # => 1
def ==(other : self)Source
def =~(other)Source
Tests whether str matches regex. If successful, it returns the position of the first match. If unsuccessful, it returns nil
.
If the argument isn't a Regex
, it returns nil
-
"Haystack" =~ /ay/ # => 1 "Haystack" =~ /z/ # => nil "Haystack" =~ 45 # => nil
def =~(regex : Regex)Source
Tests whether str matches regex. If successful, it returns the position of the first match. If unsuccessful, it returns nil
.
If the argument isn't a Regex
, it returns nil
-
"Haystack" =~ /ay/ # => 1 "Haystack" =~ /z/ # => nil "Haystack" =~ 45 # => nil
def [](start : Int, count : Int)Source
Returns a substring starting from the start character of size count.
The start argument can be negative to start counting from the end of the string.
Raises IndexError
if start isn't in range-
Raises ArgumentError
if count is negative.
def [](index : Int)Source
Returns the Char
at the given index, or raises IndexError
if out of bounds-
Negative indices can be used to start counting from the end of the string-
"hello"[0] # 'h' "hello"[1] # 'e' "hello"[-1] # 'o' "hello"[-2] # 'l' "hello"[5] # raises IndexError
def [](range : Range(Int, Int))Source
Returns a substring by using a Range's begin and end as character indices. Indices can be negative to start counting from the end of the string.
Raises IndexError
if the range's start is not in range-
"hello"[0..2] # "hel" "hello"[0...2] # "he" "hello"[1..-1] # "ello" "hello"[1...-1] # "ell"
def ascii_only?Source
Returns true
if this String is comprised in its entirety by ASCII characters.
"hello".ascii_only? # => true "你好".ascii_only? # => false
def blank?Source
Returns true
if this string consists exclusively of unicode whitespace.
"".blank? # => true " ".blank? # => true " a ".blank? # => false
def byte_at(index, &block)Source
def byte_at(index)Source
def byte_at?(index)Source
def byte_index_to_char_index(index)Source
Returns the char index of a byte index, or nil
if out of bounds.
It is valid to pass #bytesize
to index, and in this case the answer will be the size of this string.
def bytesSource
def bytesize : Int32Source
Returns the number of bytes in this string.
"hello".bytesize # => 5 "你好".bytesize # => 6
def camelcaseSource
Converts underscores to camelcase boundaries.
"eiffel_tower".camelcase # => "EiffelTower"
def capitalize(options = Unicode::CaseOptions::None)Source
Returns a new String
with the first letter converted to uppercase and every subsequent letter converted to lowercase.
"hEllO".capitalize # => "Hello"
def char_at(index)Source
def char_index_to_byte_index(index)Source
Returns the byte index of a char index, or nil
if out of bounds.
It is valid to pass #size
to index, and in this case the answer will be the bytesize of this string.
"hello".char_index_to_byte_index(1) # => 1 "hello".char_index_to_byte_index(5) # => 5 "こんにちは".char_index_to_byte_index(1) # => 3 "こんにちは".char_index_to_byte_index(5) # => 15
def check_no_null_byteSource
Raises an ArgumentError
if self
has null bytes. Returns self
otherwise.
This method should sometimes be called before passing a String
to a C function.
def chompSource
Returns a new String
with the last carriage return removed (that is, it will remove \n, \r, and \r\n).
"string\r\n".chomp # => "string" "string\n\r".chomp # => "string\n" "string\n".chomp # => "string" "string".chomp # => "string" "x".chomp.chomp # => "x"
def chomp(suffix : String)Source
Returns a new String
with suffix removed from the end of the string. If suffix is "\n"
then "\r\n"
is also removed if the string ends with it,
"hello".chomp("llo") # => "he" "hello".chomp("ol") # => "hello"
def chomp(suffix : Char)Source
Returns a new String
with suffix removed from the end of the string. If suffix is '\n'
then "\r\n"
is also removed if the string ends with it,
"hello".chomp('o') # => "hell" "hello".chomp('a') # => "hello"
def cloneSource
def codepoint_at(index)Source
def codepointsSource
def compare(other : String, case_insensitive = false)Source
Compares this string with other, returning -1
, 0
or +1
depending on whether this string is less, equal or greater than other, optionally in a case_insensitive manner.
If case_insitive is false
, this method delegates to #<=>
. Otherwise, the strings are compared char-by-char, and ASCII characters are compared in a case-insensitive way.
"abcdef".compare("abcde") # => 1 "abcdef".compare("abcdef") # => 0 "abcdef".compare("abcdefg") # => -1 "abcdef".compare("ABCDEF") # => 1 "abcdef".compare("ABCDEF", case_insensitive: true) # => 0 "abcdef".compare("ABCDEG", case_insensitive: true) # => -1
def count(&block)Source
Yields each char in this string to the block, returns the number of times the block returned a truthy value.
"aabbcc".count { |c| ['a', 'b'].includes?(c) } # => 4
def count(other : Char)Source
Counts the occurrences of other char in this string.
"aabbcc".count('a') # => 2
def count(*sets)Source
Sets should be a list of strings following the rules described at Char#in_set?
. Returns the number of characters in this string that match the given set.
def delete(&block)Source
Yields each char in this string to the block. Returns a new String
with all characters for which the block returned a truthy value removed.
"aabbcc".delete { |c| ['a', 'b'].includes?(c) } # => "cc"
def delete(char : Char)Source
Returns a new String
with all occurrences of char removed.
"aabbcc".delete('b') # => "aacc"
def delete(*sets)Source
Sets should be a list of strings following the rules described at Char#in_set?
. Returns a new String
with all characters that match the given set removed.
"aabbccdd".delete("a-c") # => "dd"
def downcase(options = Unicode::CaseOptions::None)Source
Returns a new String
with each uppercase letter replaced with its lowercase counterpart.
"hEllO".downcase # => "hello"
def dump(io)Source
def dumpSource
def dump_unquoted(io)Source
def dump_unquotedSource
def dupSource
def each_byteSource
Returns an Iterator
over each byte in the string.
bytes = "ab☃".each_byte bytes.next # => 97 bytes.next # => 98 bytes.next # => 226 bytes.next # => 152 bytes.next # => 131
def each_byte(&block)Source
Yields each byte in the string to the block.
array = [] of UInt8 "ab☃".each_byte do |byte| array << byte end array # => [97, 98, 226, 152, 131]
def each_charSource
Returns an Iterator
over each character in the string.
chars = "ab☃".each_char chars.next # => 'a' chars.next # => 'b' chars.next # => '☃'
def each_char(&block) : NilSource
Yields each character in the string to the block.
array = [] of Char "ab☃".each_char do |char| array << char end array # => ['a', 'b', '☃']
def each_char_with_index(&block)Source
Yields each character and its index in the string to the block.
array = [] of Tuple(Char, Int32) "ab☃".each_char_with_index do |char, index| array << {char, index} end array # => [{'a', 0}, {'b', 1}, {'☃', 2}]
def each_codepoint(&block)Source
Yields each codepoint to the block.
array = [] of Int32 "ab☃".each_codepoint do |codepoint| array << codepoint end array # => [97, 98, 9731]
See also: Char#ord
.
def each_codepointSource
def each_line(chomp = true)Source
Returns an Iterator
which yields each line of this string (see String#each_line
).
def each_line(chomp = true, &block) : NilSource
Splits the string after each newline and yields each line to a block.
haiku = "the first cold shower even the monkey seems to want a little coat of straw" haiku.each_line do |stanza| puts stanza.upcase end # => THE FIRST COLD SHOWER # => EVEN THE MONKEY SEEMS TO WANT # => A LITTLE COAT OF STRAW
def empty?Source
Returns true
if this is the empty string, ""
.
def encode(encoding : String, invalid : Symbol? = nil) : BytesSource
Returns a slice of bytes containing this string encoded in the given encoding.
The invalid argument can be:
-
nil
: an exception is raised on invalid byte sequences -
:skip
: invalid byte sequences are ignored
"好".encode("GB2312") # => Bytes[186, 195] "好".bytes # => [229, 165, 189]
def gsub(string : String, &block)Source
Returns a String
where all occurrences of the given string are replaced with the block's value.
"hello yellow".gsub("ll") { "dd" } # => "heddo yeddow"
def gsub(&block : Char -> _)Source
Returns a String
where each character yielded to the given block is replaced by the block's return value.
"hello".gsub { |char| char + 1 } # => "ifmmp" "hello".gsub { "hi" } # => "hihihihihi"
def gsub(char : Char, replacement)Source
Returns a String
where all occurrences of the given char are replaced with the given replacement.
"hello".gsub('l', "lo") # => "heloloo" "hello world".gsub('o', 'a') # => "hella warld"
def gsub(pattern : Regex, hash : Hash(String, _) | NamedTuple)Source
Returns a String
where all occurrences of the given pattern are replaced with a hash of replacements. If the hash contains the matched pattern, the corresponding value is used as a replacement. Otherwise the match is not included in the returned string.
# "he" and "l" are matched and replaced, # but "o" is not and so is not included "hello".gsub(/(he|l|o)/, {"he": "ha", "l": "la"}) # => "halala"
def gsub(pattern : Regex, replacement, backreferences = true)Source
Returns a String
where all occurrences of the given pattern are replaced with the given replacement.
"hello".gsub(/[aeiou]/, '*') # => "h*ll*"
Within replacement, the special match variable $~
will not refer to the current match.
If backreferences is true
(the default value), replacement can include backreferences:
"hello".gsub(/[aeiou]/, "(\\0)") # => "h(e)ll(o)"
When substitution is performed, any backreferences found in replacement will be replaced with the contents of the corresponding capture group in pattern. Backreferences to capture groups that were not present in pattern or that did not match will be skipped. See Regex
for information about capture groups-
Backreferences are expressed in the form .html?lang=en"\\d"
, where d is a group number, or "\\k
where name is the name of a named capture group. A sequence of literal characters resembling a backreference can be expressed by placing "\\"
before the sequence.
"foo".gsub(/o/, "x\\0x") # => "fxoxxox" "foofoo".gsub(/(?<bar>oo)/, "|\\k<bar>|") # => "f|oo|f|oo|" "foo".gsub(/o/, "\\\\0") # => "f\\0\\0"
Raises ArgumentError
if an incomplete named back-reference is present in replacement.
Raises IndexError
if a named group referenced in replacement is not present in pattern-
def gsub(string : String, replacement)Source
Returns a String
where all occurrences of the given string are replaced with the given replacement.
"hello yellow".gsub("ll", "dd") # => "heddo yeddow"
def gsub(hash : Hash(Char, _))Source
Returns a String
where all chars in the given hash are replaced by the corresponding hash values.
"hello".gsub({'e' => 'a', 'l' => 'd'}) # => "haddo"
def gsub(tuple : NamedTuple)Source
Returns a String
where all chars in the given named tuple are replaced by the corresponding tuple values.
"hello".gsub({e: 'a', l: 'd'}) # => "haddo"
def gsub(pattern : Regex, &block)Source
Returns a String
where all occurrences of the given pattern are replaced by the block value's value.
"hello".gsub(/./) { |s| s[0].ord.to_s + ' ' } # => "104 101 108 108 111 "
def has_back_references?Source
This returns true
if this string has '\\'
in it. It might not be a back reference, but '\\'
is probably used for back references, so this check is faster than parsing the whole thing.
def hashSource
Returns a hash based on this string’s size and content.
See also: Object#hash
.
def hexbytes : BytesSource
Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes. Two consecutive bytes in the string represent a byte in the returned slice.
Raises ArgumentError
if this string does not denote an hexstring.
"0102031aff".hexbytes # => Bytes[1, 2, 3, 26, 255] "1".hexbytes # raises ArgumentError "hello world".hexbytes # raises ArgumentError
def hexbytes? : Bytes?Source
Interprets this string as containing a sequence of hexadecimal values and decodes it as a slice of bytes. Two consecutive bytes in the string represent a byte in the returned slice.
Returns nil
if this string does not denote an hexstring.
"0102031aff".hexbytes? # => Bytes[1, 2, 3, 26, 255] "1".hexbytes? # => nil "hello world".hexbytes? # => nil
def includes?(search : Char | String)Source
Returns true
if the string contains search.
"Team".includes?('i') # => false "Dysfunctional".includes?("fun") # => true
def index(search : Regex, offset = 0)Source
Returns the index of search in the string, or nil
if the string is not present. If offset is present, it defines the position to start the search.
"Hello, World".index('o') # => 4 "Hello, World".index('Z') # => nil "Hello, World".index("o", 5) # => 8 "Hello, World".index("H", 2) # => nil "Hello, World".index(/[ ]+/) # => 6 "Hello, World".index(/\d+/) # => nil
def index(search : String, offset = 0)Source
Returns the index of search in the string, or nil
if the string is not present. If offset is present, it defines the position to start the search.
"Hello, World".index('o') # => 4 "Hello, World".index('Z') # => nil "Hello, World".index("o", 5) # => 8 "Hello, World".index("H", 2) # => nil "Hello, World".index(/[ ]+/) # => 6 "Hello, World".index(/\d+/) # => nil
def index(search : Char, offset = 0)Source
Returns the index of search in the string, or nil
if the string is not present. If offset is present, it defines the position to start the search.
"Hello, World".index('o') # => 4 "Hello, World".index('Z') # => nil "Hello, World".index("o", 5) # => 8 "Hello, World".index("H", 2) # => nil "Hello, World".index(/[ ]+/) # => 6 "Hello, World".index(/\d+/) # => nil
def insert(index : Int, other : Char)Source
Returns a new String
that results of inserting other in self
at index. Negative indices count from the end of the string, and insert after the given index.
Raises IndexError
if the index is out of bounds-
"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" "abcd".insert(5, 'X') # raises IndexError "abcd".insert(-6, 'X') # raises IndexError
def insert(index : Int, other : String)Source
Returns a new String
that results of inserting other in self
at index. Negative indices count from the end of the string, and insert after the given index.
Raises IndexError
if the index is out of bounds-
"abcd".insert(0, "FOO") # => "FOOabcd" "abcd".insert(3, "FOO") # => "abcFOOd" "abcd".insert(4, "FOO") # => "abcdFOO" "abcd".insert(-3, "FOO") # => "abFOOcd" "abcd".insert(-1, "FOO") # => "abcdFOO" "abcd".insert(5, "FOO") # raises IndexError "abcd".insert(-6, "FOO") # raises IndexError
def inspect(io)Source
def inspect_unquotedSource
def inspect_unquoted(io)Source
def lchopSource
Returns a new String
with the first char removed from it. Applying lchop to an empty string returns an empty string.
"hello".lchop # => "ello" "".lchop # => ""
def lchop(prefix : String)Source
Returns a new String
with prefix removed from the beginning of the string.
"hello".lchop("hel") # => "lo" "hello".lchop("eh") # => "hello"
def lchop(prefix : Char)Source
Returns a new String
with prefix removed from the beginning of the string.
"hello".lchop('h') # => "ello" "hello".lchop('g') # => "hello"
def lines(chomp = true)Source
def ljust(len, char : Char = ' ')Source
Adds instances of char to right of the string until it is at least size of len.
"Purple".ljust(8) # => "Purple " "Purple".ljust(8, '-') # => "Purple--" "Aubergine".ljust(8) # => "Aubergine"
def lstrip(char : Char)Source
Returns a new string with leading occurrences of char removed.
"aaabcdaaa".lstrip('a') # => "bcdaaa"
def lstripSource
Returns a new String
with leading whitespace removed.
" hello ".lstrip # => "hello " "\tgoodbye\r\n".lstrip # => "goodbye\r\n"
def lstrip(&block : Char -> _)Source
Returns a new string where leading characters for which the block returns a truthy value are removed.
"bcadefcba".lstrip { |c| 'a' <= c <= 'c' } # => "defcba"
def lstrip(chars : String)Source
Returns a new string where leading occurrences of any char in chars are removed. The chars argument is not a suffix; rather; all combinations of its values are stripped.
"bcadefcba".lstrip("abc") # => "defcba"
def match(regex : Regex, pos = 0) : Regex::MatchData?Source
Finds match of regex, starting at pos.
def pretty_print(pp)Source
def rchopSource
Returns a new String
with the last character removed. Applying rchop to an empty string returns an empty string.
"string\r\n".rchop # => "string\r" "string\n\r".rchop # => "string\n" "string\n".rchop # => "string" "string".rchop # => "strin" "x".rchop.rchop # => ""
def rchop(suffix : String)Source
Returns a new String
with suffix removed from the end of the string.
"string".rchop("ing") # => "str" "string".rchop("inx") # => "string"
def rchop(suffix : Char)Source
Returns a new String
with suffix removed from the end of the string.
"string".rchop('g') # => "strin" "string".rchop('x') # => "string"
def reverseSource
Reverses the order of characters in the string.
"Argentina".reverse # => "anitnegrA" "racecar".reverse # => "racecar"
def rindex(search : Char, offset = size - 1)Source
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
"Hello, World".rindex('o') # => 8 "Hello, World".rindex('Z') # => nil "Hello, World".rindex("o", 5) # => 4 "Hello, World".rindex("W", 2) # => nil
def rindex(search : String, offset = size - search.size)Source
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
"Hello, World".rindex('o') # => 8 "Hello, World".rindex('Z') # => nil "Hello, World".rindex("o", 5) # => 4 "Hello, World".rindex("W", 2) # => nil
def rindex(search : Regex, offset = 0)Source
Returns the index of the last appearance of search in the string, If offset is present, it defines the position to end the search (characters beyond this point are ignored).
"Hello, World".rindex('o') # => 8 "Hello, World".rindex('Z') # => nil "Hello, World".rindex("o", 5) # => 4 "Hello, World".rindex("W", 2) # => nil
def rjust(len, char : Char = ' ')Source
Adds instances of char to left of the string until it is at least size of len.
"Purple".rjust(8) # => " Purple" "Purple".rjust(8, '-') # => "--Purple" "Aubergine".rjust(8) # => "Aubergine"
def rpartition(search : Char | String) : Tuple(String, String, String)Source
Searches separator or pattern (Regex
) in the string from the end of the string, and returns a Tuple
with the part before it, the match, and the part after it. If it is not found, returns two empty strings and str.
"hello".rpartition("l") # => {"hel", "l", "o"} "hello".rpartition("x") # => {"", "", "hello"} "hello".rpartition(/.l/) # => {"he", "ll", "o"}
def rpartition(search : Regex) : Tuple(String, String, String)Source
Searches separator or pattern (Regex
) in the string from the end of the string, and returns a Tuple
with the part before it, the match, and the part after it. If it is not found, returns two empty strings and str.
"hello".rpartition("l") # => {"hel", "l", "o"} "hello".rpartition("x") # => {"", "", "hello"} "hello".rpartition(/.l/) # => {"he", "ll", "o"}
def rstripSource
Returns a new String
with trailing whitespace removed.
" hello ".rstrip # => " hello" "\tgoodbye\r\n".rstrip # => "\tgoodbye"
def rstrip(chars : String)Source
Returns a new string where trailing occurrences of any char in chars are removed. The chars argument is not a suffix; rather; all combinations of its values are stripped.
"abcdefcba".rstrip("abc") # => "abcdef"
def rstrip(char : Char)Source
Returns a new string with trailing occurrences of char removed.
"aaabcdaaa".rstrip('a') # => "aaabcd"
def rstrip(&block : Char -> _)Source
Returns a new string where trailing characters for which the block returns a truthy value are removed.
"bcadefcba".rstrip { |c| 'a' <= c <= 'c' } # => "bcadef"
def scan(pattern : String)Source
Searches the string for instances of pattern, returning an array of the matched string for each match.
def scan(pattern : Regex, &block)Source
Searches the string for instances of pattern, yielding a Regex::MatchData
for each match.
def scan(pattern : Regex)Source
Searches the string for instances of pattern, returning an Array
of Regex::MatchData
for each match.
def scan(pattern : String, &block)Source
Searches the string for instances of pattern, yielding the matched string for each match.
def scrub(replacement = Char::REPLACEMENT) : StringSource
Returns a String where bytes that are invalid in the UTF-8 encoding are replaced with replacement.
def sizeSource
Returns the number of unicode codepoints in this string.
"hello".size # => 5 "你好".size # => 2
def split(separator : Regex, limit = nil, &block : String -> _)Source
Makes an Array
by splitting the string on separator (and removing instances of separator)-
If limit is present, the array will be limited to limit items and the final item will contain the remainder of the string-
If separator is an empty regex (--
), the string will be separated into one-character strings-
long_river_name = "Mississippi" long_river_name.split(/s+/) # => ["Mi", "i", "ippi"] long_river_name.split(//) # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
def split(separator : Regex, limit = nil)Source
Splits the string after each regex separator and yields each part to a block.
If limit is present, the array will be limited to limit items and the final item will contain the remainder of the string.
If separator is an empty regex (//
), the string will be separated into one-character strings.
ary = [] of String long_river_name = "Mississippi" long_river_name.split(/s+/) { |s| ary << s } ary # => ["Mi", "i", "ippi"] ary.clear long_river_name.split(//) { |s| ary << s } ary # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
def split(separator : String, limit = nil, &block : String -> _)Source
Splits the string after each string separator and yields each part to a block.
If limit is present, the array will be limited to limit items and the final item will contain the remainder of the string.
If separator is an empty string (""
), the string will be separated into one-character strings.
ary = [] of String long_river_name = "Mississippi" long_river_name.split("ss") { |s| ary << s } ary # => ["Mi", "i", "ippi"] ary.clear long_river_name.split("i") { |s| ary << s } ary # => ["M", "ss", "ss", "pp", ""] ary.clear long_river_name.split("") { |s| ary << s } ary # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
def split(limit : Int32? = nil)Source
Makes an array by splitting the string on any ASCII whitespace characters (and removing that whitespace).
If limit is present, up to limit new strings will be created, with the entire remainder added to the last string.
old_pond = " Old pond a frog leaps in water's sound " old_pond.split # => ["Old", "pond", "a", "frog", "leaps", "in", "water's", "sound"] old_pond.split(3) # => ["Old", "pond", "a frog leaps in\n water's sound\n"]
def split(limit : Int32? = nil, &block : String -> _)Source
Splits the string after any ASCII whitespace character and yields each part to a block.
If limit is present, up to limit new strings will be created, with the entire remainder added to the last string.
ary = [] of String old_pond = " Old pond a frog leaps in water's sound " old_pond.split { |s| ary << s } ary # => ["Old", "pond", "a", "frog", "leaps", "in", "water's", "sound"] ary.clear old_pond.split(3) { |s| ary << s } ary # => ["Old", "pond", "a frog leaps in\n water's sound\n"]
def split(separator : Char, limit = nil)Source
Makes an Array
by splitting the string on the given character separator (and removing that character)-
If limit is present, up to limit new strings will be created, with the entire remainder added to the last string-
"foo,bar,baz".split(',') # => ["foo", "bar", "baz"] "foo,bar,baz".split(',', 2) # => ["foo", "bar,baz"]
def split(separator : String, limit = nil)Source
Makes an Array
by splitting the string on separator (and removing instances of separator)-
If limit is present, the array will be limited to limit items and the final item will contain the remainder of the string-
If separator is an empty string (.html?lang=en""
), the string will be separated into one-character strings.
long_river_name = "Mississippi" long_river_name.split("ss") # => ["Mi", "i", "ippi"] long_river_name.split("i") # => ["M", "ss", "ss", "pp", ""] long_river_name.split("") # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
def split(separator : Char, limit = nil, &block : String -> _)Source
Splits the string after each character separator and yields each part to a block.
If limit is present, up to limit new strings will be created, with the entire remainder added to the last string.
ary = [] of String "foo,bar,baz".split(',') { |string| ary << string } ary # => ["foo", "bar", "baz"] ary.clear "foo,bar,baz".split(',', 2) { |string| ary << string } ary # => ["foo", "bar,baz"]
def squeeze(&block)Source
Yields each char in this string to the block. Returns a new String
, that has all characters removed, that were the same as the previous one and for which the given block returned a truthy value.
"aaabbbccc".squeeze { |c| ['a', 'b'].includes?(c) } # => "abccc" "aaabbbccc".squeeze { |c| ['a', 'c'].includes?(c) } # => "abbbc"
def squeeze(char : Char)Source
Returns a new String
, with all runs of char replaced by one instance.
"a bbb".squeeze(' ') # => "a bbb"
def squeezeSource
Returns a new String
, that has all characters removed, that were the same as the previous one.
"a bbb".squeeze # => "a b"
def squeeze(*sets : String)Source
Sets should be a list of strings following the rules described at Char#in_set?
. Returns a new String
with all runs of the same character replaced by one instance, if they match the given set.
If no set is given, all characters are matched.
"aaabbbcccddd".squeeze("b-d") # => "aaabcd" "a bbb".squeeze # => "a b"
def strip(&block : Char -> _)Source
Returns a new string where leading and trailing characters for which the block returns a truthy value are removed.
"bcadefcba".strip { |c| 'a' <= c <= 'c' } # => "def"
def stripSource
Returns a new String
with leading and trailing whitespace removed.
" hello ".strip # => "hello" "\tgoodbye\r\n".strip # => "goodbye"
def strip(chars : String)Source
Returns a new string where leading and trailing occurrences of any char in chars are removed. The chars argument is not a prefix or suffix; rather; all combinations of its values are stripped.
"abcdefcba".strip("abc") # => "def"
def strip(char : Char)Source
Returns a new string where leading and trailing occurrences of char are removed.
"aaabcdaaa".strip('a') # => "bcd"
def sub(pattern : Regex, &block)Source
Returns a String
where the first occurrence of pattern is replaced by the block's return value.
"hello".sub(/./) { |s| s[0].ord.to_s + ' ' } # => "104 ello"
def sub(index : Int, replacement : Char)Source
Returns a new String
with the character at the given index replaced by replacement.
"hello".sub(1, 'a') # => "hallo"
def sub(index : Int, replacement : String)Source
Returns a new String
with the character at the given index replaced by replacement.
"hello".sub(1, "eee") # => "heeello"
def sub(range : Range(Int, Int), replacement : Char)Source
Returns a new String
with characters at the given range replaced by replacement.
"hello".sub(1..2, 'a') # => "halo"
def sub(range : Range(Int, Int), replacement : String)Source
Returns a new String
with characters at the given range replaced by replacement.
"hello".sub(1..2, "eee") # => "heeelo"
def sub(hash : Hash(Char, _))Source
Returns a String
where the first char in the string matching a key in the given hash is replaced by the corresponding hash value.
"hello".sub({'a' => 'b', 'l' => 'd'}) # => "hedlo"
def sub(&block : Char -> _)Source
Returns a new String
where the first character is yielded to the given block and replaced by its return value.
"hello".sub { |char| char + 1 } # => "iello" "hello".sub { "hi" } # => "hiello"
def sub(char : Char, replacement)Source
Returns a String
where the first occurrence of char is replaced by replacement.
"hello".sub('l', "lo") # => "helolo" "hello world".sub('o', 'a') # => "hella world"
def sub(string : String, &block)Source
Returns a String
where the first occurrences of the given string is replaced with the block's value.
"hello yellow".sub("ll") { "dd" } # => "heddo yellow"
def sub(pattern : Regex, replacement, backreferences = true)Source
Returns a String
where the first occurrence of pattern is replaced by replacement
"hello".sub(/[aeiou]/, "*") # => "h*llo"
Within replacement, the special match variable $~
will not refer to the current match.
If backreferences is true
(the default value), replacement can include backreferences:
"hello".sub(/[aeiou]/, "(\\0)") # => "h(e)llo"
When substitution is performed, any backreferences found in replacement will be replaced with the contents of the corresponding capture group in pattern. Backreferences to capture groups that were not present in pattern or that did not match will be skipped. See Regex
for information about capture groups-
Backreferences are expressed in the form .html?lang=en"\\d"
, where d is a group number, or "\\k<name>"
where name is the name of a named capture group. A sequence of literal characters resembling a backreference can be expressed by placing "\\"
before the sequence.
"foo".sub(/o/, "x\\0x") # => "fxoxo" "foofoo".sub(/(?<bar>oo)/, "|\\k<bar>|") # => "f|oo|foo" "foo".sub(/o/, "\\\\0") # => "f\\0o"
Raises ArgumentError
if an incomplete named back-reference is present in replacement.
Raises IndexError
if a named group referenced in replacement is not present in pattern-
def sub(pattern : Regex, hash : Hash(String, _) | NamedTuple)Source
Returns a String
where the first occurrences of the given pattern is replaced with the matching entry from the hash of replacements. If the first match is not included in the hash, nothing is replaced.
"hello".sub(/(he|l|o)/, {"he": "ha", "l": "la"}) # => "hallo" "hello".sub(/(he|l|o)/, {"l": "la"}) # => "hello"
def sub(string : String, replacement)Source
Returns a String
where the first occurrences of the given string is replaced with the given replacement.
"hello yellow".sub("ll", "dd") # => "heddo yellow"
def succSource
Returns the successor of the string. The successor is calculated by incrementing characters starting from the rightmost alphanumeric (or the rightmost character if there are no alphanumerics) in the string. Incrementing a digit always results in another digit, and incrementing a letter results in another letter of the same case.
If the increment generates a "carry", the character to the left of it is incremented. This process repeats until there is no carry, adding an additional character if necessary.
"abcd".succ # => "abce" "THX1138".succ # => "THX1139" "((koala))".succ # => "((koalb))" "1999zzz".succ # => "2000aaa" "ZZZ9999".succ # => "AAAA0000" "***".succ # => "**+"
def to_big_fSource
def to_big_i(base = 10) : BigIntSource
Returns a BigInt
from this string, in the given base.
Raises ArgumentError
if this string doesn't denote a valid integer.
def to_f(whitespace = true, strict = true)Source
Returns the result of interpreting characters in this string as a floating point number (Float64
). This method raises an exception if the string is not a valid float representation.
Options:
-
whitespace: if
true
, leading and trailing whitespaces are allowed -
strict: if
true
, extraneous characters past the end of the number are disallowed
"123.45e1".to_f # => 1234.5 "45.67 degrees".to_f # raises ArgumentError "thx1138".to_f(strict: false) # raises ArgumentError " 1.2".to_f(whitespace: false) # raises ArgumentError "1.2foo".to_f(strict: false) # => 1.2
def to_f?(whitespace = true, strict = true)Source
Returns the result of interpreting characters in this string as a floating point number (Float64
). This method returns nil
if the string is not a valid float representation.
Options:
-
whitespace: if
true
, leading and trailing whitespaces are allowed -
strict: if
true
, extraneous characters past the end of the number are disallowed
"123.45e1".to_f? # => 1234.5 "45.67 degrees".to_f? # => nil "thx1138".to_f? # => nil " 1.2".to_f?(whitespace: false) # => nil "1.2foo".to_f?(strict: false) # => 1.2
def to_i(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_i(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true)Source
Returns the result of interpreting leading characters in this string as an integer base base (between 2 and 36).
If there is not a valid number at the start of this string, or if the resulting integer doesn't fit an Int32
, an ArgumentError
is raised.
Options:
-
whitespace: if
true
, leading and trailing whitespaces are allowed -
underscore: if
true
, underscores in numbers are allowed -
prefix: if
true
, the prefixes"0x"
,"0"
and"0b"
override the base -
strict: if
true
, extraneous characters past the end of the number are disallowed
"12345".to_i # => 12345 "0a".to_i # raises ArgumentError "hello".to_i # raises ArgumentError "0a".to_i(16) # => 10 "1100101".to_i(2) # => 101 "1100101".to_i(8) # => 294977 "1100101".to_i(10) # => 1100101 "1100101".to_i(base: 16) # => 17826049 "12_345".to_i # raises ArgumentError "12_345".to_i(underscore: true) # => 12345 " 12345 ".to_i # => 12345 " 12345 ".to_i(whitespace: false) # raises ArgumentError "0x123abc".to_i # raises ArgumentError "0x123abc".to_i(prefix: true) # => 1194684 "99 red balloons".to_i # raises ArgumentError "99 red balloons".to_i(strict: false) # => 99
def to_i16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_i16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int16Source
def to_i16?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int16?Source
def to_i32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int32Source
Same as #to_i
.
def to_i32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
Same as #to_i
.
def to_i32?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int32?Source
Same as #to_i
.
def to_i64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_i64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int64Source
def to_i64?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int64?Source
def to_i8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int8Source
def to_i8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_i8?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : Int8?Source
def to_i?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true)Source
def to_json(json : JSON::Builder)Source
def to_s(io)Source
def to_sSource
def to_slice : BytesSource
Returns the underlying bytes of this String in an unsafe way.
The returned slice is read-only.
def to_u16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt16Source
def to_u16(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_u16?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt16?Source
def to_u32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_u32(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt32Source
def to_u32?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt32?Source
def to_u64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_u64(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt64Source
def to_u64?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt64?Source
def to_u8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt8Source
def to_u8(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true, &block)Source
def to_u8?(base : Int = 10, whitespace = true, underscore = false, prefix = false, strict = true) : UInt8?Source
def to_yaml(yaml : YAML::Builder)Source
def tr(from : String, to : String)Source
Returns a new string translating characters using from and to as a map. If to is shorter than from, the last character in to is used for the rest. If to is empty, this acts like String#delete
.
"aabbcc".tr("abc", "xyz") # => "xxyyzz" "aabbcc".tr("abc", "x") # => "xxxxxx" "aabbcc".tr("a", "xyz") # => "xxbbcc"
def underscoreSource
Converts camelcase boundaries to underscores.
"DoesWhatItSaysOnTheTin".underscore # => "does_what_it_says_on_the_tin" "PartyInTheUSA".underscore # => "party_in_the_usa" "HTTP_CLIENT".underscore # => "http_client"
def unsafe_byte_at(index)Source
def unsafe_byte_slice(byte_offset, count)Source
def unsafe_byte_slice(byte_offset)Source
def upcase(options = Unicode::CaseOptions::None)Source
Returns a new String
with each lowercase letter replaced with its uppercase counterpart.
"hEllO".upcase # => "HELLO"
def valid_encoding?Source
Returns true
if this String is encoded correctly according to the UTF-8 encoding.
© 2012–2017 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.22.0/String.html