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

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

14.2. Character set

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

is_char_in_set returns bool

argument

argument type

Character

int const

Charset

uint const[8] implicit

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

set_total(Charset: uint const[8] implicit)

set_total returns uint

argument

argument type

Charset

uint const[8] implicit

Total number of elements in the character set.

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

set_element returns int

argument

argument type

Character

int const

Charset

uint const[8] implicit

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

14.3. Character groups

is_alpha(Character: int const)

is_alpha returns bool

argument

argument type

Character

int const

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

is_new_line(Character: int const)

is_new_line returns bool

argument

argument type

Character

int const

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

is_white_space(Character: int const)

is_white_space returns bool

argument

argument type

Character

int const

Returns true if character is [ tnr].

is_number(Character: int const)

is_number returns bool

argument

argument type

Character

int const

Returns true if character is [0-9].

14.4. Character by index

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

character_at returns int

argument

argument type

str

string const implicit

idx

int const

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

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

character_uat returns int

Warning

This is unsafe operation.

argument

argument type

str

string const implicit

idx

int const

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

14.5. String properties

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

ends_with returns bool

argument

argument type

str

string const implicit

cmp

string const implicit

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

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

ends_with returns bool

argument

argument type

str

builtin::das_string const implicit

cmp

string const implicit

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

starts_with(str: string const implicit; cmp: string const implicit)

starts_with returns bool

argument

argument type

str

string const implicit

cmp

string const implicit

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

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

starts_with returns bool

argument

argument type

str

string const implicit

cmp

string const implicit

cmpLen

uint const

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

length(str: string const implicit)

length returns int

argument

argument type

str

string const implicit

Return length of string

length(str: das_string const implicit)

length returns int

argument

argument type

str

builtin::das_string const implicit

Return length of string

14.6. String builder

build_string(block: block<(var arg0:strings::StringBuilderWriter):void> const implicit)

build_string returns string

argument

argument type

block

block<( strings::StringBuilderWriter ):void> const implicit

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

write(writer: StringBuilderWriter; anything: any const)

argument

argument type

writer

strings::StringBuilderWriter

anything

any const

Returns textual representation of the value.

write_char(writer: StringBuilderWriter implicit; ch: int const)

argument

argument type

writer

strings::StringBuilderWriter implicit

ch

int const

Writes character into StringBuilderWriter.

write_chars(writer: StringBuilderWriter implicit; ch: int const; count: int const)

argument

argument type

writer

strings::StringBuilderWriter implicit

ch

int const

count

int const

Writes multiple characters into StringBuilderWriter.

write_escape_string(writer: StringBuilderWriter implicit; str: string const implicit)

argument

argument type

writer

strings::StringBuilderWriter implicit

str

string const implicit

Writes escaped string into StringBuilderWriter.

format(writer: StringBuilderWriter implicit; format: string const implicit; value: int const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

int const

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

format(writer: StringBuilderWriter implicit; format: string const implicit; value: uint const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

uint const

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

format(writer: StringBuilderWriter implicit; format: string const implicit; value: int64 const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

int64 const

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

format(writer: StringBuilderWriter implicit; format: string const implicit; value: uint64 const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

uint64 const

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

format(writer: StringBuilderWriter implicit; format: string const implicit; value: float const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

float const

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

format(writer: StringBuilderWriter implicit; format: string const implicit; value: double const)

argument

argument type

writer

strings::StringBuilderWriter implicit

format

string const implicit

value

double const

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

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

format returns string

argument

argument type

format

string const implicit

value

int const

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

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

format returns string

argument

argument type

format

string const implicit

value

uint const

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

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

format returns string

argument

argument type

format

string const implicit

value

int64 const

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

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

format returns string

argument

argument type

format

string const implicit

value

uint64 const

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

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

format returns string

argument

argument type

format

string const implicit

value

float const

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

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

format returns string

argument

argument type

format

string const implicit

value

double const

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

14.7. das::string manipulation

append(str: das_string implicit; ch: int const)

argument

argument type

str

builtin::das_string implicit

ch

int const

Appends single character ch to das::string str.

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

argument

argument type

str

builtin::das_string implicit

new_length

int const

Resize string, i.e make it specified length.

14.8. String modifications

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

repeat returns string

argument

argument type

str

string const implicit

count

int const

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

strip(str: string const implicit)

strip returns string

argument

argument type

str

string const implicit

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

strip_right(str: string const implicit)

strip_right returns string

argument

argument type

str

string const implicit

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

strip_left(str: string const implicit)

strip_left returns string

argument

argument type

str

string const implicit

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

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

chop returns string

argument

argument type

str

string const implicit

start

int const

length

int const

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

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

slice returns string

argument

argument type

str

string const implicit

start

int const

end

int const

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

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

slice returns string

argument

argument type

str

string const implicit

start

int const

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

reverse(str: string const implicit)

reverse returns string

argument

argument type

str

string const implicit

Return reversed string

to_upper(str: string const implicit)

to_upper returns string

argument

argument type

str

string const implicit

Return all upper case string

to_lower(str: string const implicit)

to_lower returns string

argument

argument type

str

string const implicit

Return all lower case string

to_lower_in_place(str: string const implicit)

to_lower_in_place returns string

Warning

This is unsafe operation.

argument

argument type

str

string const implicit

Modify string in place to be all lower case

to_upper_in_place(str: string const implicit)

to_upper_in_place returns string

Warning

This is unsafe operation.

argument

argument type

str

string const implicit

Modify string in place to be all upper case string

escape(str: string const implicit)

escape returns string

argument

argument type

str

string const implicit

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

unescape(str: string const implicit)

unescape returns string

argument

argument type

str

string const implicit

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

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

replace returns string

argument

argument type

str

string const implicit

toSearch

string const implicit

replace

string const implicit

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

rtrim(str: string const implicit)

rtrim returns string

argument

argument type

str

string const implicit

Removes trailing white space.

14.9. Search substrings

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

find returns int

argument

argument type

str

string const implicit

substr

string const implicit

start

int const

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

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

find returns int

argument

argument type

str

string const implicit

substr

string const implicit

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

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

find returns int

argument

argument type

str

string const implicit

substr

int const

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

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

find returns int

argument

argument type

str

string const implicit

substr

int const

start

int const

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

14.10. String conversion routines

string(bytes: array<uint8> const implicit)

string returns string

argument

argument type

bytes

array<uint8> const implicit

Return string from the byte array.

to_char(char: int const)

to_char returns string

argument

argument type

char

int const

Convert character to string.

int(str: string const implicit)

int returns int

argument

argument type

str

string const implicit

Converts string to integer. In case of error panic.

uint(str: string const implicit)

uint returns uint

argument

argument type

str

string const implicit

Convert string to uint. In case of error panic.

int64(str: string const implicit)

int64 returns int64

argument

argument type

str

string const implicit

Converts string to int64. In case of error panic.

uint64(str: string const implicit)

uint64 returns uint64

argument

argument type

str

string const implicit

Convert string to uint64. In case of error panic.

float(str: string const implicit)

float returns float

argument

argument type

str

string const implicit

Converts string to float. In case of error panic.

double(str: string const implicit)

double returns double

argument

argument type

str

string const implicit

Converts string to double. In case of error panic.

to_int(value: string const implicit; hex: bool const)

to_int returns int

argument

argument type

value

string const implicit

hex

bool const

Convert string to int. In case of error returns 0

to_uint(value: string const implicit; hex: bool const)

to_uint returns uint

argument

argument type

value

string const implicit

hex

bool const

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

to_int64(value: string const implicit; hex: bool const)

to_int64 returns int64

argument

argument type

value

string const implicit

hex

bool const

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

to_uint64(value: string const implicit; hex: bool const)

to_uint64 returns uint64

argument

argument type

value

string const implicit

hex

bool const

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

to_float(value: string const implicit)

to_float returns float

argument

argument type

value

string const implicit

Convert string to float. In case of error returns 0.0

to_double(value: string const implicit)

to_double returns double

argument

argument type

value

string const implicit

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

14.11. String as array

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

argument

argument type

str

string const implicit

block

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

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

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

modify_data returns string

argument

argument type

str

string const implicit

block

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

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

14.12. Low level memory allocation

delete_string(str: string& implicit)

Warning

This is unsafe operation.

argument

argument type

str

string& implicit

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

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

reserve_string_buffer returns string

argument

argument type

str

string const implicit

length

int const

Allocate copy of the string data on the heap.