strings+x86_64 +linux

The strings module provides support functions for working with Hare strings.

Submodules

Index

Types

type tokenizer = bytes::tokenizer;

// Undocumented types:
type end = void;
type iterator = struct {
	dec: utf8::decoder,
	reverse: bool,
};

Functions

fn byteindex(haystack: str, needle: (str | rune)) (size | void);
fn compare(a: str, b: str) int;
fn concat(strs: str...) str;
fn contains(haystack: str, needles: (str | rune)...) bool;
fn cut(in: str, delim: str) (str, str);
fn dup(s: const str) str;
fn dupall(s: []str) []str;
fn freeall(s: []str) void;
fn fromrunes(rs: []rune) str;
fn fromutf8(in: []u8) (str | utf8::invalid);
fn fromutf8_unsafe(in: []u8) str;
fn hasprefix(in: str, prefix: (str | rune)) bool;
fn hassuffix(in: str, suff: (str | rune)) bool;
fn index(haystack: str, needle: (str | rune)) (size | void);
fn iter(src: str) iterator;
fn iterstr(iter: *iterator) str;
fn join(delim: str, strs: str...) str;
fn lpad(s: str, p: rune, maxlen: size) str;
fn ltrim(input: str, trim: rune...) str;
fn multireplace(s: str, repls: (str, str)...) str;
fn next(iter: *iterator) (rune | void);
fn next_token(s: *tokenizer) (str | void);
fn peek_token(s: *tokenizer) (str | void);
fn prev(iter: *iterator) (rune | void);
fn rbyteindex(haystack: str, needle: (str | rune)) (size | void);
fn rcut(in: str, delim: str) (str, str);
fn remaining_tokens(s: *tokenizer) str;
fn replace(s: str, needle: str, target: str) str;
fn rindex(haystack: str, needle: (str | rune)) (size | void);
fn riter(src: str) iterator;
fn rpad(s: str, p: rune, maxlen: size) str;
fn rsplitn(in: str, delim: str, n: size) []str;
fn rtokenize(s: str, delim: str) tokenizer;
fn rtrim(input: str, trim: rune...) str;
fn slice(begin: *iterator, end: *iterator) str;
fn split(in: str, delim: str) []str;
fn splitn(in: str, delim: str, n: size) []str;
fn sub(s: str, start: size, end: (size | end)) str;
fn tokenize(s: str, delim: str) tokenizer;
fn torunes(s: str) []rune;
fn toutf8(in: str) []u8;
fn trim(input: str, exclude: rune...) str;
fn trimprefix(input: str, trim: str) str;
fn trimsuffix(input: str, trim: str) str;

Types

type tokenizer[link]

type tokenizer = bytes::tokenizer;

The state for a tokenizer.

type end[link]

Show undocumented member
type end = void;

type iterator[link]

Show undocumented member
type iterator = struct {
	dec: utf8::decoder,
	reverse: bool,
};

Functions

fn byteindex[link]

fn byteindex(haystack: str, needle: (str | rune)) (size | void);

Returns the byte-wise index of the first occurance of 'needle' in the 'haystack', or void if not present.

fn compare[link]

fn compare(a: str, b: str) int;

Compares two strings by their Unicode codepoint sort order. Zero is returned if the strings are equal, a negative value if a is less than b, or a positive value if a is greater than b.

fn concat[link]

fn concat(strs: str...) str;

Concatenates multiple strings. The caller must free the return value.

fn contains[link]

fn contains(haystack: str, needles: (str | rune)...) bool;

Returns true if a string contains a rune or a sub-string, multiple of which can be given.

fn cut[link]

fn cut(in: str, delim: str) (str, str);

Returns a string "cut" along the first instance of a delimiter, returning everything up to the delimiter, and everything after the delimiter, in a tuple.

strings::cut("hello=world=foobar", "=")	// ("hello", "world=foobar")
strings::cut("hello world", "=")	// ("hello world", "")

The return value is borrowed from the 'in' parameter. The caller must ensure that 'delim' is not an empty string.

fn dup[link]

fn dup(s: const str) str;

Duplicates a string. Aborts on allocation failure.

fn dupall[link]

fn dupall(s: []str) []str;

Creates a copy of a []str slice with all the strings duplicated. The result must be freed using freeall.

fn freeall[link]

fn freeall(s: []str) void;

Frees all the strings in a slice and the slice itself. Inverse of dupall.

fn fromrunes[link]

fn fromrunes(rs: []rune) str;

Returns a string from a slice of runes. The caller must free the return value.

fn fromutf8[link]

fn fromutf8(in: []u8) (str | utf8::invalid);

Converts a byte slice into a string. The return value is borrowed from the input. If the slice contains invalid UTF-8 sequences, encoding::utf8::invalid is returned instead.

fn fromutf8_unsafe[link]

fn fromutf8_unsafe(in: []u8) str;

Converts a byte slice into a string, but does not test if it is valid UTF-8. This is faster than the safe equivalent, but if the string is not valid UTF-8 it may cause undefined behavior. The return value is borrowed from the input.

fn hasprefix[link]

fn hasprefix(in: str, prefix: (str | rune)) bool;

Returns true if 'in' has the given prefix.

fn hassuffix[link]

fn hassuffix(in: str, suff: (str | rune)) bool;

Returns true if 'in' has the given suffix.

fn index[link]

fn index(haystack: str, needle: (str | rune)) (size | void);

Returns the index of the first occurance of 'needle' in the 'haystack', or void if not present. The index returned is the rune-wise index, not the byte-wise index.

fn iter[link]

fn iter(src: str) iterator;

Initializes a string iterator, starting at the beginning of the string. You may copy the iterator to save its state.

let iter = strings::iter("hi!");
strings::next(&iter);	// 'h'
strings::next(&iter);	// 'i'

// Copying the iterator copies its state:
let dup = iter;
strings::next(&iter);	// '!'
strings::next(&iter);	// void
strings::next(&dup);	// '!'
strings::next(&dup);	// void

fn iterstr[link]

fn iterstr(iter: *iterator) str;

Return a substring from the next rune to the end of the string if initialized with iter, or the beginning of the string if initialized with riter.

fn join[link]

fn join(delim: str, strs: str...) str;

Joins several strings together by placing a delimiter between them. The caller must free the return value.

fn lpad[link]

fn lpad(s: str, p: rune, maxlen: size) str;

Pads the start of a string 's' with rune 'p' until the string reaches length 'maxlen'. The caller must free the return value.

fn ltrim[link]

fn ltrim(input: str, trim: rune...) str;

Returns a string (borrowed from given input string) after trimming off of the start of the input string the characters in the given list of runes. If no runes are given, returns the string with leading whitespace stripped off.

fn multireplace[link]

fn multireplace(s: str, repls: (str, str)...) str;

Performs a replacement in 's' of each tuple given by 'repls'. Replacement occurs in a single pass of 's', and works like in replace, except that replacement pairs found earlier in 'repls' will take precedence over later ones. For example:

assert(multireplace("hello there", ("e", "a"), ("a", "x"), ("ell", "eww")) == "hallo thara");
assert(multireplace("hello there", ("ell", "eww"), ("e", "a")) == "hewwo thara");

The caller must free the return value.

fn next[link]

fn next(iter: *iterator) (rune | void);

Get the next rune from an iterator, or void if there are none left.

Be aware that a rune is not the minimum lexographical unit of language in Unicode strings. If you use these runes to construct a new string, reordering, editing, or omitting any of the runes without careful discretion may cause linguistic errors to arise. To avoid this, you may need to use a third-party Unicode module instead.

fn next_token[link]

fn next_token(s: *tokenizer) (str | void);

Returns the next string from a tokenizer, and advances the cursor. Returns void if there are no tokens left.

fn peek_token[link]

fn peek_token(s: *tokenizer) (str | void);

Same as next_token(), but does not advance the cursor

fn prev[link]

fn prev(iter: *iterator) (rune | void);

Get the previous rune from an iterator, or void when at the start of the string.

fn rbyteindex[link]

fn rbyteindex(haystack: str, needle: (str | rune)) (size | void);

Returns the byte-wise index of the last occurance of 'needle' in the 'haystack', or void if not present.

fn rcut[link]

fn rcut(in: str, delim: str) (str, str);

Returns a string "cut" along the last instance of a delimiter, returning everything up to the delimiter, and everything after the delimiter, in a tuple.

strings::rcut("hello=world=foobar", "=")	// ("hello=world", "foobar")
strings::rcut("hello world", "=")	// ("hello world", "")

The return value is borrowed from the 'in' parameter. The caller must ensure that 'delim' is not an empty string.

fn remaining_tokens[link]

fn remaining_tokens(s: *tokenizer) str;

Returns the remainder of the string associated with a tokenizer, without doing any further tokenization.

fn replace[link]

fn replace(s: str, needle: str, target: str) str;

Returns a new string duplicated from 's', but with all instances of 'needle' replaced with 'target'. The caller must free the return value.

fn rindex[link]

fn rindex(haystack: str, needle: (str | rune)) (size | void);

Returns the index of the last occurance of 'needle' in the 'haystack', or void if not present. The index returned is the rune-wise index, not the byte-wise index.

fn riter[link]

fn riter(src: str) iterator;

Initializes a string iterator, starting at the end of the string and moving backwards with each call to next.

fn rpad[link]

fn rpad(s: str, p: rune, maxlen: size) str;

Pads the end of a string 's' with rune 'p' until the string reaches length 'maxlen'. The caller must free the return value.

fn rsplitn[link]

fn rsplitn(in: str, delim: str, n: size) []str;

Splits a string into tokens delimited by 'delim', starting at the end of the string, and returning a slice of up to N tokens. The caller must free this slice. The strings within the slice are borrowed from 'in'.

The caller must ensure that 'delim' is not an empty string.

fn rtokenize[link]

fn rtokenize(s: str, delim: str) tokenizer;

Returns a tokenizer which yields sub-strings tokenized by a delimiter, starting at the end of the string and moving backwards with each call to next_token.

let tok = strings::rtokenize("hello, my name is drew", " ");
assert(strings::next_token(&tok) as str == "drew");
assert(strings::next_token(&tok) as str == "is");
assert(strings::next_token(&tok) as str == "name");
assert(strings::remaining_tokens(&tok) == "hello, my");

The caller must ensure that 'delim' is not an empty string.

fn rtrim[link]

fn rtrim(input: str, trim: rune...) str;

Returns a string (borrowed from given input string) after trimming off of the end of the input string the characters in the given list of runes. If no runes are given, returns the string with trailing whitespace stripped off.

fn slice[link]

fn slice(begin: *iterator, end: *iterator) str;

Return a substring from the position of the first iterator to the position of the second iterator. The iterators must originate from the same string and the position of the second iterator must not be before the position of the first one.

fn split[link]

fn split(in: str, delim: str) []str;

Splits a string into tokens delimited by 'delim'. The caller must free the returned slice. The strings within the slice are borrowed from 'in'.

The caller must ensure that 'delim' is not an empty string.

fn splitn[link]

fn splitn(in: str, delim: str, n: size) []str;

Splits a string into tokens delimited by 'delim', starting at the beginning of the string, and returning a slice of up to N tokens. The caller must free this slice. The strings within the slice are borrowed from 'in'.

The caller must ensure that 'delim' is not an empty string.

fn sub[link]

fn sub(s: str, start: size, end: (size | end)) str;

Returns a substring in the range [start, end - 1], where each argument is the index of the Nth rune. If the end argument is given as end, the end of the substring is the end of the original string. The lifetime of the substring is the same as that of the original string.

Note that substringing runewise is not always the correct thing to do, and it may cause unexpected linguistic errors to arise. You may want to use a third-party Unicode module instead.

fn tokenize[link]

fn tokenize(s: str, delim: str) tokenizer;

Returns a tokenizer which yields sub-strings tokenized by a delimiter, starting at the beginning of the string.

let tok = strings::tokenize("hello, my name is drew", " ");
assert(strings::next_token(&tok) as str == "hello,");
assert(strings::next_token(&tok) as str == "my");
assert(strings::next_token(&tok) as str == "name");
assert(strings::remaining_tokens(&tok) == "is drew");

The caller must ensure that 'delim' is not an empty string.

fn torunes[link]

fn torunes(s: str) []rune;

Returns a slice of runes for a string in O(n). The caller must free the return value.

fn toutf8[link]

fn toutf8(in: str) []u8;

Converts a string to a UTF-8 byte slice. The return value is borrowed from the input.

fn trim[link]

fn trim(input: str, exclude: rune...) str;

Returns a string (borrowed from given input string) after trimming off of the both ends of the input string the characters in the given list of runes. If no runes are given, returns the string with both leading and trailing whitespace stripped off.

fn trimprefix[link]

fn trimprefix(input: str, trim: str) str;

Returns a string (borrowed from given input string) after trimming off the given prefix. If the input string doesn't have the given prefix, it is returned unmodified.

fn trimsuffix[link]

fn trimsuffix(input: str, trim: str) str;

Returns a string (borrowed from given input string) after trimming off the given suffix. If the input string doesn't have the given suffix, it is returned unmodified.