7. String manipulation library

The string library implements string formatting, conversion, searching, and modification routines.

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

require strings

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

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

7.3. Character set

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

Returns true if character bit is set in the set (of 256 bits in uint32[8]).

Arguments:

  • Character : int

  • Charset : uint[8] implicit

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

Total number of elements in the character set.

Arguments:

  • Charset : uint[8] implicit

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

Gen character set element by element index (not character index).

Arguments:

  • Character : int

  • Charset : uint[8] implicit

7.4. Character groups

is_alpha(Character: int): bool

Returns true if character is [A-Za-z].

Arguments:

  • Character : int

is_alnum(Character: int): bool

Returns true if character is alphanumeric [A-Za-z0-9].

Arguments:

  • Character : int

is_hex(Character: int): bool

Returns true if character is hexadecimal [0-9A-Fa-f].

Arguments:

  • Character : int

is_tab_or_space(Character: int): bool

Returns true if character is tab or space [ t].

Arguments:

  • Character : int

is_new_line(Character: int): bool

Returns true if character is ‘n’ or ‘r’.

Arguments:

  • Character : int

is_white_space(Character: int): bool

Returns true if character is [ tnr].

Arguments:

  • Character : int

is_number(Character: int): bool

Returns true if character is [0-9].

Arguments:

  • Character : int

7.5. Character by index

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

Returns character of the string ‘str’ at index ‘idx’.

Arguments:

  • str : string implicit

  • idx : int

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

Warning

This is unsafe operation.

Returns character of the string ‘str’ at index ‘idx’. This function does not check bounds of index.

Arguments:

  • str : string implicit

  • idx : int

7.6. String properties

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

returns true if the end of the string str matches a the string cmp otherwise returns false

Arguments:

  • str : string implicit

  • cmp : string implicit

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

returns true if the end of the string str matches a the string cmp otherwise returns false

Arguments:
starts_with(str: string implicit; cmp: string implicit): bool

returns true if the beginning of the string str matches the string cmp; otherwise returns false

Arguments:

  • str : string implicit

  • cmp : string implicit

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

returns true if the beginning of the string str matches the string cmp; otherwise returns false

Arguments:

  • str : string implicit

  • cmp : string implicit

  • cmpLen : uint

starts_with(str: string implicit; offset: int; cmp: string implicit): bool

returns true if the beginning of the string str matches the string cmp; otherwise returns false

Arguments:

  • str : string implicit

  • offset : int

  • cmp : string implicit

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

returns true if the beginning of the string str matches the string cmp; otherwise returns false

Arguments:

  • str : string implicit

  • offset : int

  • cmp : string implicit

  • cmpLen : uint

length(str: string implicit): int

Return length of string

Arguments:

  • str : string implicit

length(str: das_string implicit): int

Return length of string

Arguments:

7.7. String builder

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

Create StringBuilderWriter and pass it to the block. Upon completion of a block, return whatever was written as string.

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

Build hash of the string (as oppose to building entire string).

Arguments:
write(writer: StringBuilderWriter; anything: any): StringBuilderWriter&

Returns textual representation of the value.

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

Writes character into StringBuilderWriter.

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

Writes multiple characters into StringBuilderWriter.

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

Writes escaped string into StringBuilderWriter.

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: int): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: uint): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: int64): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: uint64): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: float): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(writer: StringBuilderWriter implicit; format: string implicit; value: double): StringBuilderWriter&

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:
format(format: string implicit; value: int): string

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : int

format(format: string implicit; value: uint): string

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : uint

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

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : int64

format(format: string implicit; value: uint64): string

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : uint64

format(format: string implicit; value: float): string

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : float

format(format: string implicit; value: double): string

Warning

This function is deprecated.

Converts value to string given specified format (that of C printf).

Arguments:

  • format : string implicit

  • value : double

7.8. das::string manipulation

append(str: das_string implicit; ch: int)

Appends single character ch to das::string str.

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

Resize string, i.e make it specified length.

Arguments:

7.9. String modifications

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

Repeat string specified number of times, and return the result.

Arguments:

  • str : string implicit

  • count : int

strip(str: string implicit): string

Strips white-space-only characters that might appear at the beginning or end of the given string and returns the new stripped string.

Arguments:

  • str : string implicit

strip_right(str: string implicit): string

Strips white-space-only characters that might appear at the end of the given string and returns the new stripped string.

Arguments:

  • str : string implicit

strip_left(str: string implicit): string

Strips white-space-only characters that might appear at the beginning of the given string and returns the new stripped string.

Arguments:

  • str : string implicit

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

Return all part of the strings starting at start and ending at start + length.

Arguments:

  • str : string implicit

  • start : int

  • length : int

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

Return all part of the strings starting at start and ending by end. Start can be negative (-1 means “1 from the end”).

Arguments:

  • str : string implicit

  • start : int

  • end : int

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

Return all part of the strings starting at start and ending by end. Start can be negative (-1 means “1 from the end”).

Arguments:

  • str : string implicit

  • start : int

reverse(str: string implicit): string

Return reversed string

Arguments:

  • str : string implicit

to_upper(str: string implicit): string

Return all upper case string

Arguments:

  • str : string implicit

to_lower(str: string implicit): string

Return all lower case string

Arguments:

  • str : string implicit

to_lower_in_place(str: string implicit): string

Warning

This is unsafe operation.

Modify string in place to be all lower case

Arguments:

  • str : string implicit

to_upper_in_place(str: string implicit): string

Warning

This is unsafe operation.

Modify string in place to be all upper case string

Arguments:

  • str : string implicit

escape(str: string implicit): string

Escape string so that escape sequences are printable, for example converting “n” into “\n”.

Arguments:

  • str : string implicit

unescape(str: string implicit): string

Unescape string i.e reverse effects of escape. For example “\n” is converted to “n”.

Arguments:

  • str : string implicit

safe_unescape(str: string implicit): string

Unescape string i.e reverse effects of escape. For example “\n” is converted to “n”.

Arguments:

  • str : string implicit

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

Replace all occurances of the stubstring in the string with another substring.

Arguments:

  • str : string implicit

  • toSearch : string implicit

  • replace : string implicit

rtrim(str: string implicit): string

Removes trailing white space.

Arguments:

  • str : string implicit

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

Removes trailing white space.

Arguments:

  • str : string implicit

  • chars : string implicit

ltrim(str: string implicit): string

Removes leading white space.

Arguments:

  • str : string implicit

trim(str: string implicit): string

Removes leading and trailing white space.

Arguments:

  • str : string implicit

7.10. Search substrings

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

Return index where substr can be found within str (starting from optional ‘start’ at), or -1 if not found

Arguments:

  • str : string implicit

  • substr : string implicit

  • start : int

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

Return index where substr can be found within str (starting from optional ‘start’ at), or -1 if not found

Arguments:

  • str : string implicit

  • substr : string implicit

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

Return index where substr can be found within str (starting from optional ‘start’ at), or -1 if not found

Arguments:

  • str : string implicit

  • substr : int

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

Return index where substr can be found within str (starting from optional ‘start’ at), or -1 if not found

Arguments:

  • str : string implicit

  • substr : int

  • start : int

7.11. String conversion routines

fmt(writer: StringBuilderWriter implicit; format: string implicit; value: int8): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: uint8): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: int16): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: uint16): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: int): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: uint): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

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

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: uint64): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: float): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
fmt(writer: StringBuilderWriter implicit; format: string implicit; value: double): StringBuilderWriter&

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:
string(bytes: array<uint8>): string

Return string from the byte array.

Arguments:

  • bytes : array<uint8> implicit

to_char(char: int): string

Convert character to string.

Arguments:

  • char : int

int8(str: string implicit): int8

Converts string to int8. In case of error panic.

Arguments:

  • str : string implicit

uint8(str: string implicit): uint8

Convert string to uint8. In case of error panic.

Arguments:

  • str : string implicit

int16(str: string implicit): int16

Converts string to int16. In case of error panic.

Arguments:

  • str : string implicit

uint16(str: string implicit): uint16

Convert string to uint16. In case of error panic.

Arguments:

  • str : string implicit

int(str: string implicit): int

Converts string to integer. In case of error panic.

Arguments:

  • str : string implicit

uint(str: string implicit): uint

Convert string to uint. In case of error panic.

Arguments:

  • str : string implicit

int64(str: string implicit): int64

Converts string to int64. In case of error panic.

Arguments:

  • str : string implicit

uint64(str: string implicit): uint64

Convert string to uint64. In case of error panic.

Arguments:

  • str : string implicit

float(str: string implicit): float

Converts string to float. In case of error panic.

Arguments:

  • str : string implicit

double(str: string implicit): double

Converts string to double. In case of error panic.

Arguments:

  • str : string implicit

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

Convert string to int8. In case of error returns 0

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to uint8. In case of error returns 0u

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to int16. In case of error returns 0

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to int. In case of error returns 0

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to uint. In case of error returns 0u

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to int64. In case of error returns 0l

Arguments:

  • value : string implicit

  • hex : bool

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

Convert string to uint64. In case of error returns 0ul

Arguments:

  • value : string implicit

  • hex : bool

to_cpp_float(value: float): string

Convert string to float using C++ fmt::format_to, while also recognizing FLT_MIN, FLT_MAX, etc.

Arguments:

  • value : float

to_float(value: string implicit): float

Convert string to float. In case of error returns 0.0

Arguments:

  • value : string implicit

to_double(value: string implicit): double

Convert string to double. In case of error returns 0.0lf

Arguments:

  • value : string implicit

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

Converts string to int8. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Convert string to uint8. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Converts string to int16. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Convert string to uint16. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Converts string to integer. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Convert string to uint. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Converts string to int64. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Convert string to uint64. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

  • hex : bool

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

Converts string to float. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

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

Converts string to double. In case of error panic.

Arguments:

  • str : string implicit

  • result : ConversionResult & implicit

  • offset : int& implicit

fmt(format: string implicit; value: int8): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : int8

fmt(format: string implicit; value: uint8): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : uint8

fmt(format: string implicit; value: int16): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : int16

fmt(format: string implicit; value: uint16): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : uint16

fmt(format: string implicit; value: int): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : int

fmt(format: string implicit; value: uint): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : uint

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

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : int64

fmt(format: string implicit; value: uint64): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : uint64

fmt(format: string implicit; value: float): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : float

fmt(format: string implicit; value: double): string

Converts value to string given specified format (that of libfmt or C++20 std::format, see Format String Syntax).

Arguments:

  • format : string implicit

  • value : double

7.12. String as array

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

Passes temporary array which is mapped to the string data to a block as read-only.

Arguments:

  • str : string implicit

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

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

Passes temporary array which is mapped to the string data to a block for both reading and writing.

Arguments:

  • str : string implicit

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

7.13. Low level memory allocation

delete_string(str: string& implicit): bool

Warning

This is unsafe operation.

Removes string from the string heap. This is unsafe because it will free the memory and all dangling strings will be broken.

Arguments:

  • str : string& implicit

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

Allocate copy of the string data on the heap.

Arguments:

  • str : string implicit

  • length : int