3.1. String manipulation library

The STRINGS module implements string formatting, conversion, searching, and modification routines. It provides functions for building strings (build_string), parsing (to_int, to_float), character classification (is_alpha, is_number), and low-level string manipulation.

All functions and symbols are in “strings” module, use require to get access to it.

require strings

3.1.1. Enumerations

ConversionResult

Result of conversion from string to number.

Values:

  • ok = 0 - Successful conversion

  • invalid_argument = 22 - Argument is not a valid number

  • out_of_range = 34 - Argument is out of range for the target type

3.1.2. Handled structures

StringBuilderWriter

Object representing a string builder. Its significantly faster to write data to the string builder and than convert it to a string, as oppose to using sequences of string concatenations.

3.1.3. Character set

is_char_in_set(Character: int; Charset: uint const[8]): bool

Returns true if the character given by its integer code is present in the 256-bit character set represented as a uint[8] array.

Arguments:

  • Character : int

  • Charset : uint[8] implicit

set_element(Character: int; Charset: uint const[8]): int

Returns the character code at the given element index within the 256-bit character set represented as a uint[8] array.

Arguments:

  • Character : int

  • Charset : uint[8] implicit

set_total(Charset: uint const[8]): uint

Returns the total number of characters present (bits set) in the 256-bit character set represented as a uint[8] array.

Arguments:

  • Charset : uint[8] implicit

3.1.4. Character groups

is_alnum(Character: int): bool

Returns true if the integer character code represents an alphanumeric ASCII character [A-Za-z0-9].

Arguments:

  • Character : int

is_alpha(Character: int): bool

Returns true if the integer character code represents an alphabetic ASCII character [A-Za-z].

Arguments:

  • Character : int

is_hex(Character: int): bool

Returns true if the integer character code represents a hexadecimal digit [0-9A-Fa-f].

Arguments:

  • Character : int

is_new_line(Character: int): bool

Returns true if the integer character code is a newline character (\n or \r).

Arguments:

  • Character : int

is_number(Character: int): bool

Returns true if the integer character code represents a decimal digit [0-9].

Arguments:

  • Character : int

is_tab_or_space(Character: int): bool

Returns true if the integer character code is a tab or space character.

Arguments:

  • Character : int

is_white_space(Character: int): bool

Returns true if the integer character code is a whitespace character (space, tab, newline, carriage return, etc.).

Arguments:

  • Character : int

3.1.5. Character by index

character_at(str: string; idx: int): int

Returns the integer character code of string str at the given index idx, with bounds checking.

Arguments:

  • str : string implicit

  • idx : int

character_uat(str: string; idx: int): int

Warning

This is unsafe operation.

Returns the integer character code of string str at the given index idx without performing bounds checking (unsafe).

Arguments:

  • str : string implicit

  • idx : int

3.1.6. String properties

3.1.6.1. ends_with

ends_with(str: das_string; cmp: string): bool

Returns true if the string str ends with the substring cmp, false otherwise.

Arguments:
ends_with(str: string; cmp: string): bool

3.1.6.2. length

length(str: string): int

Returns the length of the string or das_string in characters as an int.

Arguments:

  • str : string implicit

length(str: das_string): int

3.1.6.3. starts_with

starts_with(str: string; cmp: string; cmpLen: uint): bool

Returns true if the beginning of string str matches the string cmp, with optional offset and cmpLen parameters to control the comparison start position and length.

Arguments:

  • str : string implicit

  • cmp : string implicit

  • cmpLen : uint

starts_with(str: string; cmp: string): bool
starts_with(str: string; offset: int; cmp: string): bool
starts_with(str: string; offset: int; cmp: string; cmpLen: uint): bool

3.1.7. String builder

build_hash(block: block<(StringBuilderWriter):void>): uint64

Computes a uint64 hash by streaming writes through a StringBuilderWriter passed to block, without allocating the full concatenated string.

Arguments:
build_string(block: block<(StringBuilderWriter):void>): string

Creates a StringBuilderWriter, passes it to block for writing, and returns the accumulated output as a string.

Arguments:

3.1.7.1. format

format(format: string; value: int64): string

Warning

This function is deprecated.

Formats a numeric value of type T using a C printf-style format string, either appending to a StringBuilderWriter and returning a reference to it, or returning the formatted result as a new string.

Arguments:

  • format : string implicit

  • value : int64

format(format: string; value: double): string
format(writer: StringBuilderWriter; format: string; value: int): StringBuilderWriter&
format(writer: StringBuilderWriter; format: string; value: uint): StringBuilderWriter&
format(writer: StringBuilderWriter; format: string; value: int64): StringBuilderWriter&
format(format: string; value: uint64): string
format(writer: StringBuilderWriter; format: string; value: float): StringBuilderWriter&
format(writer: StringBuilderWriter; format: string; value: uint64): StringBuilderWriter&
format(writer: StringBuilderWriter; format: string; value: double): StringBuilderWriter&
format(format: string; value: int): string
format(format: string; value: uint): string
format(format: string; value: float): string
write(writer: StringBuilderWriter; anything: any): StringBuilderWriter&

Writes the textual representation of any value into the StringBuilderWriter and returns a reference to the writer for chaining.

Arguments:
write_char(writer: StringBuilderWriter; ch: int): StringBuilderWriter&

Writes a single character specified by its integer code ch into the StringBuilderWriter and returns a reference to the writer.

Arguments:
write_chars(writer: StringBuilderWriter; ch: int; count: int): StringBuilderWriter&

Writes the character specified by integer code ch repeated count times into the StringBuilderWriter and returns a reference to the writer.

Arguments:
write_escape_string(writer: StringBuilderWriter; str: string): StringBuilderWriter&

Writes the escaped form of string str (with special characters converted to escape sequences) into the StringBuilderWriter and returns a reference to the writer.

Arguments:

3.1.8. das::string manipulation

append(str: das_string; ch: int)

Appends a single character specified by its integer code ch to the mutable das_string str.

Arguments:
resize(str: das_string; new_length: int)

Resizes the mutable das_string str in place to new_length characters.

Arguments:

3.1.9. String modifications

chop(str: string; start: int; length: int): string

Returns a substring of str beginning at index start with the specified length.

Arguments:

  • str : string implicit

  • start : int

  • length : int

escape(str: string): string

Returns a new string with special characters replaced by their printable escape sequences (e.g. newline becomes \n).

Arguments:

  • str : string implicit

ltrim(str: string): string

Returns a new string with leading whitespace characters removed from str.

Arguments:

  • str : string implicit

repeat(str: string; count: int): string

Returns a new string formed by concatenating str repeated count times.

Arguments:

  • str : string implicit

  • count : int

replace(str: string; toSearch: string; replace: string): string

Returns a new string with all occurrences of substring toSearch in str replaced by the substring replace.

Arguments:

  • str : string implicit

  • toSearch : string implicit

  • replace : string implicit

reverse(str: string): string

Returns a new string with the characters of str in reverse order.

Arguments:

  • str : string implicit

3.1.9.1. rtrim

rtrim(str: string; chars: string): string

Returns a new string with trailing whitespace removed from str, or with trailing characters from the specified chars set removed.

Arguments:

  • str : string implicit

  • chars : string implicit

rtrim(str: string): string
safe_unescape(str: string): string

Unescapes a string by converting printable escape sequences back to their original characters (e.g. \n becomes a newline), skipping invalid sequences instead of failing.

Arguments:

  • str : string implicit

3.1.9.2. slice

slice(str: string; start: int): string

Returns a substring of str from index start to optional end (exclusive), where negative indices count from the end of the string.

Arguments:

  • str : string implicit

  • start : int

slice(str: string; start: int; end: int): string
strip(str: string): string

Returns a new string with all leading and trailing whitespace characters removed from str.

Arguments:

  • str : string implicit

strip_left(str: string): string

Returns a new string with all leading whitespace characters removed from str.

Arguments:

  • str : string implicit

strip_right(str: string): string

Returns a new string with all trailing whitespace characters removed from str.

Arguments:

  • str : string implicit

to_lower(str: string): string

Returns a new string with all characters of str converted to lower case.

Arguments:

  • str : string implicit

to_lower_in_place(str: string): string

Warning

This is unsafe operation.

Converts all characters of str to lower case in place and returns the modified string.

Arguments:

  • str : string implicit

to_upper(str: string): string

Returns a new string with all characters of str converted to upper case.

Arguments:

  • str : string implicit

to_upper_in_place(str: string): string

Warning

This is unsafe operation.

Converts all characters of str to upper case in place and returns the modified string.

Arguments:

  • str : string implicit

trim(str: string): string

Returns a new string with both leading and trailing whitespace characters removed from str.

Arguments:

  • str : string implicit

unescape(str: string): string

Returns a new string with printable escape sequences converted back to their original characters (e.g. \n becomes a newline).

Arguments:

  • str : string implicit

3.1.10. Search substrings

3.1.10.1. find

find(str: string; substr: string): int

Returns the first index at which substr (string or character code) occurs in str, optionally searching from start, or -1 if not found.

Arguments:

  • str : string implicit

  • substr : string implicit

find(str: string; substr: string; start: int): int
find(str: string; substr: int; start: int): int
find(str: string; substr: int): int

3.1.11. String comparison

compare_ignore_case(a: string; b: string): int

Performs case-insensitive string comparison. Returns 0 if strings are equal, a negative value if a is less than b, or a positive value if a is greater than b.

Arguments:

  • a : string implicit

  • b : string implicit

3.1.12. String conversion routines

3.1.12.1. double

double(str: string; result: ConversionResult&; offset: int&): double

Converts a string to a double value, panicking on failure; an overload accepts result and offset output parameters to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

  • result : ConversionResult& implicit

  • offset : int& implicit

double(str: string): double

3.1.12.2. float

float(str: string): float

Converts a string to a float value, panicking on failure; an overload accepts result and offset output parameters to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

float(str: string; result: ConversionResult&; offset: int&): float

3.1.12.3. fmt

fmt(writer: StringBuilderWriter; format: string; value: int64): StringBuilderWriter&

Formats a numeric value of type T into the StringBuilderWriter using a libfmt/C++20 std::format format string and returns a reference to the writer.

Arguments:
fmt(writer: StringBuilderWriter; format: string; value: uint): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: uint64): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: uint16): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: uint8): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: int8): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: int16): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: int): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: double): StringBuilderWriter&
fmt(writer: StringBuilderWriter; format: string; value: float): StringBuilderWriter&

3.1.12.4. int

int(str: string): int

Converts a string to an int, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

int(str: string; result: ConversionResult&; offset: int&; hex: bool = false): int

3.1.12.5. int16

int16(str: string; result: ConversionResult&; offset: int&; hex: bool = false): int16

Converts a string to an int16, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

  • result : ConversionResult& implicit

  • offset : int& implicit

  • hex : bool

int16(str: string): int16

3.1.12.6. int64

int64(str: string): int64

Converts a string to an int64, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

int64(str: string; result: ConversionResult&; offset: int&; hex: bool = false): int64

3.1.12.7. int8

int8(str: string): int8

Converts a string to an int8, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

int8(str: string; result: ConversionResult&; offset: int&; hex: bool = false): int8
string(bytes: array<uint8>): string

Constructs and returns a new string from the contents of a uint8 byte array.

Arguments:

  • bytes : array<uint8> implicit

to_char(char: int): string

Converts an integer character code to a single-character string.

Arguments:

  • char : int

to_cpp_float(value: float): string

Converts a float value to its string representation using C++ fmt::format_to, correctly handling special constants like FLT_MIN and FLT_MAX.

Arguments:

  • value : float

to_double(value: string): double

Converts a string to a double value, returning 0.0lf if the conversion fails.

Arguments:

  • value : string implicit

to_float(value: string): float

Converts a string to a float value, returning 0.0 if the conversion fails.

Arguments:

  • value : string implicit

to_int(value: string; hex: bool = false): int

Converts a string to an int value with optional hexadecimal parsing when hex is true, returning 0 if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_int16(value: string; hex: bool = false): int16

Converts a string to an int16 value with optional hexadecimal parsing when hex is true, returning 0 if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_int64(value: string; hex: bool = false): int64

Converts a string to an int64 value with optional hexadecimal parsing when hex is true, returning 0l if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_int8(value: string; hex: bool = false): int8

Converts a string to an int8 value with optional hexadecimal parsing when hex is true, returning 0 if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_uint(value: string; hex: bool = false): uint

Converts a string to a uint value with optional hexadecimal parsing when hex is true, returning 0u if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_uint16(value: string; hex: bool = false): uint16

Converts a string to a uint16 value. Returns 0 if conversion fails. When hex is true, parses the string as hexadecimal.

Arguments:

  • value : string implicit

  • hex : bool

to_uint64(value: string; hex: bool = false): uint64

Converts a string to a uint64 value with optional hexadecimal parsing when hex is true, returning 0ul if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

to_uint8(value: string; hex: bool = false): uint8

Converts a string to a uint8 value with optional hexadecimal parsing when hex is true, returning 0u if the conversion fails.

Arguments:

  • value : string implicit

  • hex : bool

3.1.12.8. uint

uint(str: string): uint

Converts a string to a uint, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

uint(str: string; result: ConversionResult&; offset: int&; hex: bool = false): uint

3.1.12.9. uint16

uint16(str: string): uint16

Converts a string to a uint16, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

uint16(str: string; result: ConversionResult&; offset: int&; hex: bool = false): uint16

3.1.12.10. uint64

uint64(str: string): uint64

Converts a string to a uint64, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

uint64(str: string; result: ConversionResult&; offset: int&; hex: bool = false): uint64

3.1.12.11. uint8

uint8(str: string; result: ConversionResult&; offset: int&; hex: bool = false): uint8

Converts a string to a uint8, panicking on failure; an overload accepts result, offset, and optional hex flag to report the ConversionResult status and parsed position instead of panicking.

Arguments:

  • str : string implicit

  • result : ConversionResult& implicit

  • offset : int& implicit

  • hex : bool

uint8(str: string): uint8

3.1.13. String as array

modify_data(str: string; block: block<(array<uint8>#):void>): string

Maps the raw bytes of string str into a temporary uint8 array, passes it to block for in-place reading and writing, and returns the modified string.

Arguments:

  • str : string implicit

  • block : block<(array<uint8>#):void> implicit

peek_data(str: string; block: block<(array<uint8>#):void>)

Maps the raw bytes of string str into a temporary read-only uint8 array and passes it to block for inspection.

Arguments:

  • str : string implicit

  • block : block<(array<uint8>#):void> implicit

3.1.14. Low level memory allocation

delete_string(str: string&): bool

Warning

This is unsafe operation.

Frees the string str from the heap and clears the reference, returning true on success; unsafe because existing aliases become dangling pointers.

Arguments:

  • str : string& implicit

reserve_string_buffer(str: string; length: int): string

Allocates a copy of the string data on the heap with at least length bytes reserved and returns the new string.

Arguments:

  • str : string implicit

  • length : int