Nanyx
PlaygroundPackages

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.