strings +linux +x86_64

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

Submodules

Index

Types

type tokenizer;

// Undocumented types:
type end;
type iterator;

Functions

fn byteindex(str, (str | rune)) (size | void);
fn cap(str) size;
fn compare(str, str) int;
fn concat(str...) str;
fn contains(str, (str | rune)...) bool;
fn cstrlen(*const char) size;
fn cut(str, str) (str, str);
fn dup(const str) str;
fn dupall([]str) []str;
fn freeall([]str) void;
fn fromc(*const char) const str;
fn fromc_unsafe(*const char) const str;
fn fromrunes([]rune) str;
fn fromutf8([]u8) (str | utf8::invalid);
fn fromutf8_unsafe([]u8) str;
fn hasprefix(str, (str | rune)) bool;
fn hassuffix(str, (str | rune)) bool;
fn index(str, (str | rune)) (size | void);
fn iter(str) iterator;
fn iterstr(*iterator) str;
fn join(str, str...) str;
fn ltrim(str, rune...) str;
fn multireplace(str, (str, str)...) str;
fn next(*iterator) (rune | void);
fn next_token(*tokenizer) (str | void);
fn padend(str, rune, size) str;
fn padstart(str, rune, size) str;
fn peek_token(*tokenizer) (str | void);
fn prev(*iterator) (rune | void);
fn remaining_tokens(*tokenizer) str;
fn replace(str, str, str) str;
fn riter(str) iterator;
fn rtrim(str, rune...) str;
fn runes(str) []rune;
fn split(str, str) []str;
fn splitn(str, str, size) []str;
fn sub(str, size, (size | end)) str;
fn to_c(const str) *char;
fn to_cbuf(const str, []u8) *char;
fn tokenize(str, str) tokenizer;
fn toutf8(str) []u8;
fn trim(str, rune...) str;
fn trimprefix(str, str) str;
fn trimsuffix(str, 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 cap[link]

fn cap(s: str) size;

Returns the capacity of a string.

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 two or more 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 cstrlen[link]

fn cstrlen(cstr: *const char) size;

Computes the length of a NUL-terminated C string, in octets, in O(n). The computed length does not include the NUL terminator.

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 'delimiter' 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 fromc[link]

fn fromc(cstr: *const char) const str;

Converts a C string to a Hare string in O(n). If the string is not valid UTF-8, abort.

fn fromc_unsafe[link]

fn fromc_unsafe(cstr: *const char) const str;

Converts a C string to a Hare string in O(n), and does not check if it's valid UTF-8.

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.

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 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;

For each tuple given by 'repls', a replacement of 's' is done like in replace, in the order that they are passed as arguments. This function is nearly equivalent to calling replace multiple times, except only one new string is allocated. 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 padend[link]

fn padend(s: str, prefix: rune, target_len: size) str;

Pads a string's end with 'prefix' until it reaches length 'target_len'. The caller must free the return value.

fn padstart[link]

fn padstart(s: str, prefix: rune, target_len: size) str;

Pads a string's start with 'prefix' until it reaches length 'target_len'. The caller must free the return value.

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 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 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 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 runes[link]

fn runes(s: str) []rune;

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

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', and needn't be freed - but must be dupall'd if they should outlive 'in'.

The caller must ensure that 'delimiter' 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', returning a slice of up to N tokens. The caller must free this slice. The strings within the slice are borrowed from 'in', and needn't be freed - but should be dupall'd if they should outlive 'in'.

The caller must ensure that 'delimiter' 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 strings::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 to_c[link]

fn to_c(s: const str) *char;

Converts a Hare string to a C string. The result is allocated; the caller must free it when they're done.

fn to_cbuf[link]

fn to_cbuf(s: const str, sl: []u8) *char;

Converts a Hare string to a C string. The result is stored into a user-supplied buffer.

fn tokenize[link]

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

Returns a tokenizer which yields sub-strings tokenized by a delimiter.

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 'delimiter' is not an empty string.

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.