text
Functions on strings
Its functions are attached to string, so they need no import (see Extending a type); import nanyx/text as t reaches them as t.string.trim. string.length is also a built-in property of strings and lists, so s.length is the string’s length, as string.length(s) is. string.toString, which gives back the string itself, is in the prelude rather than in this module, with the toString of the other built-in types: see Converting to text.
import nanyx/text
println("a,b,c" \split(on = ","))
println("7" \padStart(width = 3, fill = "0"))
println(["Hello", "World"] \string.join(", "))
println("héllo" \chars)
-- [a, b, c]
-- 007
-- Hello, World
-- [h, é, l, l, o]
Reference
Functions on strings.
Each is attached to string, so it is in scope wherever strings are, without an import, and is called as string.trim(s), or as
s \trim when s is known to be a string. A dot on a value never reaches an attached definition:
s.trim is an error.
Strings are UTF-8. Most of these functions work byte by byte: length counts bytes (not
characters or grapheme clusters), indices and widths are byte offsets, uppercase and lowercase
only change ASCII letters, and the trimming and words functions only treat ASCII whitespace as
whitespace. Multi-byte characters pass through unchanged, except that padStart and padEnd cut
their fill at a byte count, so a multi-byte fill can be cut mid-character. chars, reverse and
codePoints work by character, where a character is one Unicode code point: they read each UTF-8
sequence’s lead byte, so they never cut a character in half. fromCodePoint turns a code point
back into a character.
Every function here is stack-safe: each one that walks a string calls itself only in tail position, so it works on a string of any length.
string.length
def string.length: string -> int
The number of bytes in s.
string.substring
def string.substring: (string, start: int, length: int) -> string
The length bytes of s starting at byte start. Out-of-range values are clamped, so the result
is never longer than what s actually holds.
string.take
def string.take: string, int -> string
The first n bytes of s, or all of s when it is shorter. A negative n takes none. Bytes are
counted as substring and indexOf count them, so s \take(i) cuts at an index indexOf gave.
string.skip
def string.skip: string, int -> string
All but the first n bytes of s, or "" when it is shorter. A negative n skips none.
string.startsWith
def string.startsWith: string, string -> bool
Whether s begins with prefix.
string.endsWith
def string.endsWith: string, string -> bool
Whether s ends with suffix.
string.indexOf
def string.indexOf: string, string -> #some(int) | #notFound
The byte index of the first occurrence of needle in s. An empty needle is found at 0.
string.lastIndexOf
def string.lastIndexOf: string, string -> #some(int) | #notFound
The byte index of the last occurrence of needle in s. An empty needle is found at the end.
string.contains
def string.contains: string, string -> bool
Whether needle occurs anywhere in s.
string.count
def string.count: string, string -> int
The number of non-overlapping occurrences of needle in s. An empty needle is counted 0 times.
string.removePrefix
def string.removePrefix: string, string -> string
s without prefix, or s unchanged when it doesn’t start with prefix.
string.removeSuffix
def string.removeSuffix: string, string -> string
s without suffix, or s unchanged when it doesn’t end with suffix.
string.uppercase
def string.uppercase: string -> string
s with every ASCII letter upper-cased, made in one allocation.
string.lowercase
def string.lowercase: string -> string
s with every ASCII letter lower-cased, made in one allocation.
string.trim
def string.trim: string -> string
s without leading and trailing whitespace.
string.trimStart
def string.trimStart: string -> string
s without leading whitespace.
string.trimEnd
def string.trimEnd: string -> string
s without trailing whitespace.
string.isEmpty
def string.isEmpty: string -> bool
Whether s has no bytes at all.
string.isBlank
def string.isBlank: string -> bool
Whether s is empty or only whitespace.
string.repeat
def string.repeat: string, int -> string
s repeated times times (the empty string when times is zero or negative). Stack-safe: it works
for any times.
string.padStart
def string.padStart: (string, width: int, fill: string) -> string
s with fill repeated in front of it until it is width bytes long. Longer strings are unchanged.
string.padEnd
def string.padEnd: (string, width: int, fill: string) -> string
s with fill repeated after it until it is width bytes long. Longer strings are unchanged.
string.split
def string.split: (string, on: string) -> list(string)
The pieces of s between occurrences of on. An empty on yields [s]. Stack-safe:
it works however many pieces there are.
string.splitOnce
def string.splitOnce: (string, on: string) -> #some(string, string) | #notFound
The part of s before the first on, and the part after it, or #notFound when s does not
contain on. An empty on is found at the start, so it gives ("", s).
string.join
def string.join: list(string), string -> string
The pieces concatenated with separator between each pair. Each piece is copied once, so it
takes time in proportion to the length of the result.
string.concat
def string.concat: list(string) -> string
The pieces concatenated end to end.
string.replace
def string.replace: (string, pattern: string, replacement: string) -> string
s with every occurrence of pattern replaced by replacement. An empty pattern leaves s unchanged.
string.lines
def string.lines: string -> list(string)
The lines of s, split on line feeds, with any carriage return before a line feed dropped. A final
line break doesn’t start another line, so “a\nb\n” has two lines and "" has none. Stack-safe: it
works however many lines there are.
string.words
def string.words: string -> list(string)
The runs of non-whitespace in s, in order. Stack-safe: it works however many words there are.
string.chars
def string.chars: string -> list(string)
Each character of s as a string of its own, in order. A character is one Unicode code point, so
“héllo” has five characters though it is six bytes long. Stack-safe: it works on a string of any
length.
string.reverse
def string.reverse: string -> string
s with its characters (code points, not bytes) in reverse order, so it never cuts a character in
half. Stack-safe: it works on a string of any length.
string.codePoints
def string.codePoints: string -> list(int)
The Unicode code point of each character of s, in order: "aé€" \codePoints is
[97, 233, 8364]. It has one number for each of string.chars. Stack-safe: it works on a string
of any length.
string.fromCodePoint
def string.fromCodePoint: int -> #some(string) | #invalidCodePoint
The character whose Unicode code point is codePoint, as a string: string.fromCodePoint(233) is
#some("é"). A negative number, a surrogate (55296 to 57343, 0xD800 to 0xDFFF) or a number past
the last code point (1114111, 0x10FFFF) gives #invalidCodePoint.
StringSlice
type StringSlice = private (text: string, start: int, length: int)
A view of a run of a string’s bytes, which shares the string instead of copying it: the string,
the byte the run starts at and how many bytes it is. string.slice makes one, and a slice of a
slice is one too, each without copying, so a parser or a lexer can walk a text and look at its
tokens without making a substring of each. StringSlice.toString copies the run into a string
of its own, which lets go of the larger one. Bytes are counted as string.substring counts them.
string.slice
def string.slice: string, int, int -> StringSlice
The bytes of s from from up to but not including to, as a slice that shares s: each bound
is moved into 0 to the length of s, and the slice is empty when to is before from.
StringSlice.length
def StringSlice.length: StringSlice -> int
The number of bytes s views.
StringSlice.isEmpty
def StringSlice.isEmpty: StringSlice -> bool
Whether s views no bytes.
StringSlice.byteAt
def StringSlice.byteAt: StringSlice, int -> #some(int) | #none
The byte of s at index, counting from 0 at the start of s, or #none when index is
negative or past its end.
StringSlice.slice
def StringSlice.slice: StringSlice, int, int -> StringSlice
The bytes of s from from up to but not including to, counting from the start of s,
sharing the same string. The bounds clamp into s, as string.slice’s do.
StringSlice.startsWith
def StringSlice.startsWith: StringSlice, string -> bool
Whether the bytes s views begin with prefix, compared without copying them.
StringSlice.indexOf
def StringSlice.indexOf: StringSlice, string -> #some(int) | #notFound
The byte index, counting from 0 at the start of s, of the first occurrence of needle in the
bytes s views, found without copying them. An empty needle is found at 0.
StringSlice.toString
def StringSlice.toString: StringSlice -> string
A copy of the bytes s views, as a string of its own, which doesn’t keep the string s views
alive.