Instances of the Str class are immutable strings. A string is a potentially empty sequence of characters. A character is logically represented by an integer code between 0 and 65535, inclusive. Alore has no special data type for characters — characters are represented as strings of length 1. Character codes can be queried using the @ref{Ord} function, and strings with specific character codes can be created using the @ref{Chr} function.
String objects may contain data in various encodings. String methods that interpret string contents (e.g. upper) assume that strings are encoded in the 16-bit Unicode encoding or any subset of Unicode, such as ASCII or Latin 1. Some other modules can work with arbitrary narrow strings, i.e. string objects with only 8-bit characters (character codes between 0 and 255, inclusive).
Characters in a string can be accessed using integer indices starting from 0 (the first character). Alternatively, negative indices can used to refer to characters from the end of the string: -1 refers to the last character, -2 to the second to last character, etc. @see The @ref{string} and @ref{re} modules contain useful functions for dealing with strings. The @ref{encodings} module provides conversions between different character encodings. @end @class Str(x) @desc Construct an object of the Str type. Call the _str() method of the argument and return a value equal to the result, provided that it is a string. Objects of all primitive types (except Str) and the standard collection types provide a _str method. @see The function @ref{string::IntToStr} and the method @ref{Str.format} are alternative ways of converting objects to strings. @end @end
Return an array
containing the fields. If the separator is given, the result contains
always at least a single
field, which may be empty. The optional max parameter specifies
the maximum number of
splits. The rest of the string will be returned as the last element in
the array. Examples:
@example
" a black cat ".split() -- Result: ["a", "black", "cat"]
"a,black, cat".split(",") -- Result: ["a", "black", " cat"]
"a,b,c".split(",", 1) -- Result: ["a", "b,c"]
@end
@end
@fun join(sequence as Sequence Example:
@example
"\u00c3\u00a4".decode(encodings::Utf8) -- Decode "ä" in UTF-8 to 16-bit Unicode
@end
@see Module @ref{encodings}
@end
@end
@fun encode(encoding as Encoding[, mode as Constant]) as Str
@desc Encode the string (interpreted as 16-bit Unicode) using the given
character encoding.
The mode argument may be @ref{encodings::Strict} (the
default) or @ref{encodings::Unstrict}.
Calling this method is
equivalent to encoding.encoder([mode]).encode(str).
Example:
@example
"\u20ac".encode(encodings::Utf8) -- Encode the Euro sign using UTF-8
@end
@see Module @ref{encodings}
@end
@end
Str objects support the following operations:
@op str[n] @optype{Str[Int] -> Str; Str[Pair If the index is a pair x : y, return a
slice containing the indices x, x + 1, ...,
y - 1.
If the left value of the pair is omitted or nil, it is assumed to
be 0. If the right value is omitted or nil, the result is a
substring extending to the end of the string.
Invalid indices in range bounds are clipped to lie within the string.
@example
"hello"[2] -- "e"
"hello"[1:3] -- "el"
"hello"[3:] -- "lo"
"hello"[:-1] -- "hell"
@end
@end
@op substr in str @optype{Str in Str -> Boolean}
@desc Test whether a string contains a substring. Return a boolean
value.
@end
@op for ch in str @optype{for Str in Str}
@desc The characters in a string can be iterated with a for loop, starting
from the first character.
@end
@op x + y @optype{Str + Str -> Str}
@desc Return the concatenation of two strings.
@end
@op str * n @optype{Str * Int -> Str}
@op n * str @optype{Int * Str -> Str}
@desc A string can be repeated any number of times by multiplying it with an
integer. The integer must not be negative. Multiplying a string with zero
results in an empty string.
@example
"foo" * 3 -- "foofoofoo"
"x" * 0 -- ""
@end
@end
@op x == y @optype{Str == Object -> Boolean}
@desc Strings can be compared for equality.
@end
@op x < y @optype{Str < Str -> Boolean}
@op x > y @optype{Str > Str -> Boolean}
@desc Strings can be compared lexicographic order. Order comparisons are based
on the numeric values of characters.
@end
@op Repr(str)
@desc Return a string representing the string using Alore string literal
syntax, and only using printable ASCII characters. Characters other than
printable ASCII character are represented using the \uNNNN escape
sequences.
@example
WriteLn(Repr("""foo" + Tab + "\uffff")) -- Print """foo\u0009\uffff"
@end
@end
@op Int(str)
@desc Convert a string to an integer.
@end
@op Float(str)
@desc Convert a string to a float.
@end
@op Hash(str)
@desc Return the hash value of a string.
@end
Operations