= String Library =

The string library provides functionality for manipulating strings. Most of these functions are accessed as methods of
string objects. These are indicated as `s.methodName` in the following docs.

Remember that strings in Croc are immutable. Therefore these functions never operate on the object on which they were
called. They will always return new strings distinct from the original string.

[[PageOutline(2-9, Members, inline)]]

== `StringBuffer` ==

 '''`class StringBuffer`'''::
 A mutable string type. [wiki:StdLib/BaseLib/StringBuffer Go to this class's documentation]

== '''`string.fromRawUnicode(mb: memblock, lo: int = 0, hi: int = #mb)`''' ==
Converts data stored in a memblock into a string. The given memblock must be of type `u8`, `u16`, or `u32`.
If it's `u8`, it must contain UTF-8 data; if it's `u16`, it must contain UTF-16 data; and if it's `u32`, it
must contain UTF-32 data. You can specify only a slice of the memblock to convert into a string with the `lo`
and `hi` parameters; the default behavior is to convert the entire memblock. If the data is invalid Unicode,
an exception will be thrown. Returns the converted string.

== '''`string.fromRawAscii(mb: memblock, lo: int = 0, hi: int = #mb)`''' ==
Similar to `fromRawUnicode`, except converts a memblock containing ASCII data into a string. The memblock
must be of type `u8`. Any bytes above U+0007F are turned into the Unicode replacement character, U+0001A.
Returns the converted string.

== '''`s.toRawUnicode(bits: int = 8, mb: memblock = null)`''' ==
Converts a string into a memblock containing Unicode-encoded data. The `bits` parameter determines which
encoding to use. It defaults to 8, which means the resulting memblock will be filled with a UTF-8 encoding of
`s`, and its type will be `u8`. The other two valid values are 16, which will encode UTF-16 data in a memblock
of type `u16`, and 32, which will encode UTF-32 data in a memblock of type `u32`.

You may optionally pass a memblock as the second parameter to be used as the destination memblock. This way you
can reuse a memblock as a conversion buffer to avoid memory allocations. The memblock's type will be set
appropriately and its data will be replaced by the encoded string data.

Returns the memblock containing the encoded string data, either a new memblock if `mb` is `null`, or `mb`
otherwise.

== '''`s.toRawAscii(mb: memblock = null)`''' ==
Similar to `toRawUnicode`, except encodes `s` as ASCII. `s` must not contain any codepoints above U+0007F; that
is, `s.isAscii()` must return true for this method to work.

Just like `toRawUnicode` you can pass a memblock as a destination buffer. Its type will be set to `u8`.

Returns the memblock containing the encoded string data, either a new memblock if `mb` is `null`, or `mb`
otherwise.

== '''`s.opApply(reverse: string = null)`''' ==
This function allows you to iterate over the characters of a string with a `foreach` loop.

{{{
#!croc
foreach(i, v; "hello")
        writeln("string[", i, "] = ", v)

foreach(i, v; "hello", "reverse")
        writeln("string[", i, "] = ", v)
}}}

As this example shows, if you pass "reverse" to the '''`opApply`''' function, either directly or as the second
part of the `foreach` container, the iteration will go in reverse, starting at the end of the string.

== '''`s.join(arr: array)`''' ==
The inverse of the `split` method. This joins together the elements of `arr` using `s` as the separator. The
elements of `arr` must all be characters or strings. If `s` is the empty string, this just concatenates all the
elements of `arr` together. If `#arr` is 0, returns the empty string. If `#arr` is 1, returns `arr[0]` as a string
(so a single character will be converted to a string). Otherwise, returns the elements joined sequentially with the
separator (`s`) between each pair of arguments. So "`".".join(["apple", "banana", "orange"])`" will yield
the string `"apple.banana.orange"`.

== '''`s.vjoin(vararg)`''' ==
Similar to `join`, but joins its list of variadic parameters instead of an array. The functionality is otherwise
identical. So "`".".join("apple", "banana", "orange")`" will yield the string `"apple.banana.orange"`.

== '''`s.isAscii()`''' ==
Returns a bool indicating whether or not this string is pure ASCII, that is, whether or not all the codepoints in it
are less than or equal to U+0007F.

== '''`s.toInt(base: int = 10)`''' ==
Converts the string into an integer. If the string does not follow the format of an integer, an exception will be
thrown. The optional `base` parameter defaults to 10, but you can use any base between 2 and 36 inclusive.

== '''`s.toFloat()`''' ==
Converts the string into a float. If the string does not follow the format of a float, an exception will be thrown.

== '''`s.compare(other: string)`''' ==
Compares the string to the string `other`, and returns an integer. If `s` is less than (alphabetically) `other`, the
return is negative; if they are the same, the return is 0; and otherwise, the return is positive. This does not perform
language-sensitive collation; this is a pure codepoint comparison. Note that the exact same functionality can be
achieved by using the `<=>` operator on two strings.

== '''`s.icompare(other: string)`''' ==
The same as `compare`, but case-insensitive, so "foo", "Foo", and "FOO" will all compare equal, for instance.

== '''`s.find(sub: string|char, start: int = 0)`''' ==
Searches for an occurence of `sub` in `s`. `sub` can be either a string or a single character. The search starts from
`start` (which defaults to the first character) and goes right. If `sub` is found, this function returns the integer
index of the occurrence in the string, with 0 meaning the first character. Otherwise, if `sub` cannot be found, `#s`
is returned.

== '''`s.ifind(sub: string|char, start: int = 0)`''' ==
The same as `find`, but case-insensitive.

== '''`s.rfind(sub: string|char, start: int = #s)`''' ==
Reverse find. Works similarly to `find`, but the search starts with the character at `start - 1` (which defaults to
the last character) and goes ''left''. `start` is not included in the search so you can use the result of this function
as the `start` parameter to successive calls. If `sub` is found, this function returns the integer index of the occurrence
in the string, with 0 meaning the first character. Otherwise, if `sub` cannot be found, `#s` is returned.

== '''`s.irfind(sub: string|char, start: int = #s)`''' ==
The same as `rfind`, but case-insensitive.

== '''`s.toLower()`''' ==
Returns a new string with any uppercase letters converted to lowercase. Non-uppercase letters and non-letters are not
affected.

== '''`s.toUpper()`''' ==
Returns a new string with any lowercase letters converted to uppercase. Non-lowercase letters and non-letters are not
affected.

== '''`s.repeat(n: int)`''' ==
Returns a string which is the concatenation of `n` instances of `s`. So `"hello".repeat(3)` will return
`"hellohellohello"`. `n` must be greater than or equal to 0.

== '''`s.reverse()`''' ==
Returns a string which is the reversal of `s`.

== '''`s.split(delim: string = null)`''' ==
The inverse of the `join` method. Splits `s` into pieces and returns an array of the split pieces. If no parameters are
given, the splitting occurs at whitespace (spaces, tabs, newlines etc.) and all the whitespace is stripped from the split
pieces. Thus `"one\t\ttwo".split()` will return `["one", "two"]`. If the `delim` parameter is given, it specifies
a delimiting string where `s` will be split. Thus `"one--two--three".split("--")` will return `["one", "two", "three"]`.

== '''`s.vsplit(delim: string = null)`''' ==
Similar to `split`, but instead of returning an array, returns the split pieces as multiple return values. Thus
`"one\t\ttwo".split()` will return `"one", "two"`. If the string splits into more than 20 pieces, an error will be
thrown (as returning many values can be a memory problem). Otherwise the behavior is identical to `split`.

== '''`s.splitLines()`''' ==
This will split the string at any newline characters (`'
'`, `'
'`, or `'
'`). Other whitespace is preserved, and empty
lines are preserved. This returns an array of strings, each of which holds one line of text.

== '''`s.vsplitLines()`''' ==
Similar to `splitLines`, but instead of returning an array, returns the split lines as multiple return values. If the string
splits into more than 20 lines, an error will be thrown. Otherwise the behavior is identical to `splitLines`.

== '''`s.strip()`''' ==
Strips any whitespace from the beginning and end of the string.

== '''`s.lstrip()`''' ==
Strips any whitespace from just the beginning of the string.

== '''`s.rstrip()`''' ==
Strips any whitespace from just the end of the string.

== '''`s.replace(from: string, to: string)`''' ==
Replaces any occurrences in `s` of the string `from` with the string `to`.

== '''`s.startsWith(other: string)`''' ==
Returns a bool of whether or not `s` starts with the substring `other`. This is case-sensitive.

== '''`s.endsWith(other: string)`''' ==
Returns a bool of whether or not `s` ends with the substring `other`. This is case-sensitive.

== '''`s.istartsWith(other: string)`''' ==
Returns a bool of whether or not `s` starts with the substring `other`. This is case-insensitive.

== '''`s.iendsWith(other: string)`''' ==
Returns a bool of whether or not `s` ends with the substring `other`. This is case-insensitive.