`std/string` — Strings¶

import std/string

Operations on NUL-terminated SRAM strings, plus the usual character classification predicates. Inputs typed str ram are NUL-terminated strings in SRAM; outputs and in-place targets are ptr ram u8 buffers you must size and own (there is no allocation).

Length and copying¶

@strlen($s: str ram) -> u16¶: Return the number of bytes in $s before its NUL terminator.

@strcpy($dest: ptr ram u8, $src: str ram)¶: Copy $src, including its NUL terminator, into $dest. $dest must be large enough.

@strncpy($dest: ptr ram u8, $src: str ram, $n: u16)¶: Copy up to $n characters from $src into $dest. If $src is shorter than $n, the remainder of $dest is padded with NUL bytes.

@strcat($dest: ptr ram u8, $src: str ram)¶: Append $src to the end of the existing string in $dest.

@strncat($dest: ptr ram u8, $src: str ram, $n: u16)¶: Append up to $n characters of $src to $dest and NUL-terminate the result.

Comparison¶

@strcmp($s1: str ram, $s2: str ram) -> i16¶: Compare two strings lexicographically. Return 0 if equal, otherwise the signed difference of the first pair of differing bytes.

@strncmp($s1: str ram, $s2: str ram, $n: u16) -> i16¶: As @strcmp, but compare at most $n characters.

Searching¶

@strchr($s: str ram, $c: u8) -> ptr ram u8¶: Return a pointer to the first occurrence of byte $c in $s, or 0 if it does not occur.

@strrchr($s: str ram, $c: u8) -> ptr ram u8¶: Return a pointer to the last occurrence of byte $c in $s, or 0.

@strstr($haystack: str ram, $needle: str ram) -> ptr ram u8¶: Return a pointer to the first occurrence of the substring $needle in $haystack, or 0 if it is not found.

@strpbrk($s: str ram, $accept: str ram) -> ptr ram u8¶: Return a pointer to the first character in $s that is any of the characters in $accept, or 0.

@strspn($s: str ram, $accept: str ram) -> u16¶: Return the length of the initial run of $s made up entirely of characters from $accept.

@strcspn($s: str ram, $reject: str ram) -> u16¶: Return the length of the initial run of $s made up entirely of characters not in $reject.

Case conversion¶

@tolower($c: u8) -> u8¶: Return the lowercase form of $c if it is an uppercase letter, otherwise $c unchanged.

@toupper($c: u8) -> u8¶: Return the uppercase form of $c if it is a lowercase letter, otherwise $c unchanged.

Character classification¶

Each predicate returns a bool.

@isspace($c: u8) -> bool¶: True for whitespace: space, \t, \r, \n, \v, \f.

@isdigit($c: u8) -> bool¶: True for a decimal digit '0'–'9'.

@isalpha($c: u8) -> bool¶: True for an alphabetic letter.

@isalnum($c: u8) -> bool¶: True for a letter or a digit.

@isxdigit($c: u8) -> bool¶: True for a hexadecimal digit (0–9, A–F, a–f).

@islower($c: u8) -> bool¶: True for a lowercase letter.

@isupper($c: u8) -> bool¶: True for an uppercase letter.

Example¶

import std/string

@main {
    ram str $name = "ik"             # a NUL-terminated string in SRAM
    ram mut $copy: u8[8] = 0         # destination buffer you own (8 bytes)

    @strcpy(&$copy[0], $name)        # copy $name (incl. NUL) into $copy
    ram imut $n: u16 = @strlen($name)         # length, not counting NUL -> 4
    ram imut $eq: i16 = @strcmp($name, "ik")  # 0 means the strings are equal
    loop * { }                       # embedded programs never return
}

std/string — Strings¶