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

strings::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

strings::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

strings::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

strings::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

strings::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

strings::is_alnum(Character: int) : bool()

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

Arguments

  • Character : int

strings::is_alpha(Character: int) : bool()

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

Arguments

  • Character : int

strings::is_hex(Character: int) : bool()

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

Arguments

  • Character : int

strings::is_new_line(Character: int) : bool()

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

Arguments

  • Character : int

strings::is_number(Character: int) : bool()

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

Arguments

  • Character : int

strings::is_tab_or_space(Character: int) : bool()

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

Arguments

  • Character : int

strings::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

strings::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

strings::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

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

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

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

3.1.6.2. length

strings::length(str: string) : int()

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

Arguments

  • str : string implicit

strings::length(str: das_string) : int()

3.1.6.3. starts_with

strings::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

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

3.1.7. String builder

strings::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
strings::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

strings::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

strings::format(format: string; value: double) : string()
strings::format(writer: StringBuilderWriter; format: string; value: int) : StringBuilderWriter&()
strings::format(writer: StringBuilderWriter; format: string; value: uint) : StringBuilderWriter&()
strings::format(writer: StringBuilderWriter; format: string; value: int64) : StringBuilderWriter&()
strings::format(format: string; value: uint64) : string()
strings::format(writer: StringBuilderWriter; format: string; value: float) : StringBuilderWriter&()
strings::format(writer: StringBuilderWriter; format: string; value: uint64) : StringBuilderWriter&()
strings::format(writer: StringBuilderWriter; format: string; value: double) : StringBuilderWriter&()
strings::format(format: string; value: int) : string()
strings::format(format: string; value: uint) : string()
strings::format(format: string; value: float) : string()
strings::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
strings::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
strings::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
strings::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

strings::append(str: das_string; ch: int)

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

Arguments
strings::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

strings::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

strings::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

strings::ltrim(str: string) : string()

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

Arguments

  • str : string implicit

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

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

Arguments

  • str : string implicit

  • count : int

strings::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

strings::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

strings::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

strings::rtrim(str: string) : string()
strings::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

strings::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

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

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

Arguments

  • str : string implicit

strings::strip_left(str: string) : string()

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

Arguments

  • str : string implicit

strings::strip_right(str: string) : string()

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

Arguments

  • str : string implicit

strings::to_lower(str: string) : string()

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

Arguments

  • str : string implicit

strings::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

strings::to_upper(str: string) : string()

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

Arguments

  • str : string implicit

strings::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

strings::trim(str: string) : string()

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

Arguments

  • str : string implicit

strings::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

strings::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

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

3.1.11. String comparison

strings::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

strings::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

strings::double(str: string) : double()

3.1.12.2. float

strings::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

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

3.1.12.3. fmt

strings::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
strings::fmt(writer: StringBuilderWriter; format: string; value: uint) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: uint64) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: uint16) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: uint8) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: int8) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: int16) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: int) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: double) : StringBuilderWriter&()
strings::fmt(writer: StringBuilderWriter; format: string; value: float) : StringBuilderWriter&()

3.1.12.4. int

strings::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

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

3.1.12.5. int16

strings::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

strings::int16(str: string) : int16()

3.1.12.6. int64

strings::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

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

3.1.12.7. int8

strings::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

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

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

Arguments

  • bytes : array<uint8> implicit

strings::to_char(char: int) : string()

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

Arguments

  • char : int

strings::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

strings::to_double(value: string) : double()

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

Arguments

  • value : string implicit

strings::to_float(value: string) : float()

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

Arguments

  • value : string implicit

strings::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

strings::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

strings::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

strings::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

strings::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

strings::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

strings::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

strings::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

strings::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

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

3.1.12.9. uint16

strings::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

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

3.1.12.10. uint64

strings::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

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

3.1.12.11. uint8

strings::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

strings::uint8(str: string) : uint8()

3.1.13. String as array

strings::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

strings::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

strings::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

strings::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