v0.4.0

Strings and memory v0.1.0

C's <string.h>: byte-string and raw memory operations.

`memchr`

pub extern func memchr(
    ptr: *opaque,
    ch: c_int,
    count: size_t
) -> *opaque

Finds the first byte equal to ch within the first count bytes. ptr is borrowed for the call and count bytes of it are read. ch is converted to an unsigned char before comparison, so only its low eight bits matter. Returns a pointer into ptr, valid for as long as ptr is, or null when no byte matches. Runs in time proportional to count and allocates nothing. ptr must be readable for count bytes. A count larger than the object reads past it.

See also: https://en.cppreference.com/c/string/byte/memchr

Parameters

Name	Type	Description
`ptr`	`*opaque`	the block to act on
`ch`	`c_int`	the character, as an `int` holding an `unsigned char` value or `EOF`
`count`	`size_t`	how many bytes to search

Returns: the address of the first matching byte, or null

`memcmp`

pub extern func memcmp(
    lhs: *opaque,
    rhs: *opaque,
    count: size_t
) -> c_int

Compares the first count bytes of two objects. Both are borrowed for the call. Returns a negative value when lhs orders first, zero when the two ranges are identical, and a positive value otherwise; the magnitude means nothing. Bytes are compared as unsigned char, so the result does not depend on whether plain char is signed. Runs in time proportional to count and allocates nothing. Not constant-time: it stops at the first difference, so it must not be used to compare secrets. Both pointers must be readable for count bytes.

See also: https://en.cppreference.com/c/string/byte/memcmp

Parameters

Name	Type	Description
`lhs`	`*opaque`	the left operand
`rhs`	`*opaque`	the right operand
`count`	`size_t`	how many bytes to compare

Returns: negative, zero or positive as the first differing byte orders

`memcpy`

pub extern func memcpy(
    dest: *var opaque,
    src: *opaque,
    count: size_t
) -> *var opaque

Copies count bytes from src to dest. src is borrowed and read; dest is borrowed and written. Returns dest. The two ranges must not overlap -- that is what memmove is for, and overlapping them here is undefined rather than merely unpredictable. Runs in time proportional to count and allocates nothing. dest must be writable for count bytes, src readable for count, and the two must not overlap.

See also: https://en.cppreference.com/c/string/byte/memcpy

Parameters

Name	Type	Description
`dest`	`*var opaque`	where the bytes go
`src`	`*opaque`	where the bytes come from
`count`	`size_t`	how many bytes to copy

Returns: dest

`memmove`

pub extern func memmove(
    dest: *var opaque,
    src: *opaque,
    count: size_t
) -> *var opaque

Copies count bytes from src to dest, correctly even when the two overlap. src is borrowed and read; dest is borrowed and written. Returns dest. Behaves as though the source were copied to a temporary first, so sliding a range within one buffer works in either direction. Runs in time proportional to count and allocates nothing. dest must be writable for count bytes and src readable for count.

See also: https://en.cppreference.com/c/string/byte/memmove

Parameters

Name	Type	Description
`dest`	`*var opaque`	where the bytes go
`src`	`*opaque`	where the bytes come from
`count`	`size_t`	how many bytes to move

Returns: dest

`memset`

pub extern func memset(
    dest: *var opaque,
    ch: c_int,
    count: size_t
) -> *var opaque

Writes ch to each of the first count bytes of dest. dest is borrowed and written. ch is converted to an unsigned char, so only its low eight bits are stored. Returns dest. Runs in time proportional to count and allocates nothing. dest must be writable for count bytes. This is not the call for clearing a secret: a compiler is entitled to delete a write nothing reads back, and Core::Zeroize is the one that is not.

See also: https://en.cppreference.com/c/string/byte/memset

Parameters

Name	Type	Description
`dest`	`*var opaque`	where the bytes go
`ch`	`c_int`	the character, as an `int` holding an `unsigned char` value or `EOF`
`count`	`size_t`	how many bytes to write

Returns: dest

`strlen`

pub extern func strlen(str: *char8) -> size_t

The length of a byte string, not counting its terminator. str is borrowed and read up to and including its first zero byte. Returns the count of bytes before it. Runs in time proportional to the result and allocates nothing. str must be non-null and must contain a zero byte. Without one this reads until it faults or wraps.

See also: https://en.cppreference.com/c/string/byte/strlen

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string

Returns: how many bytes precede the terminator

`strcmp`

pub extern func strcmp(lhs: *char8, rhs: *char8) -> c_int

Compares two byte strings. Both are borrowed and read to their terminators. Returns a negative value when lhs orders first, zero when the two are equal, and a positive value otherwise. Bytes are compared as unsigned char. Runs in time proportional to the shorter string and allocates nothing. Not constant-time. Both must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strcmp

Parameters

Name	Type	Description
`lhs`	`*char8`	the left operand
`rhs`	`*char8`	the right operand

Returns: negative, zero or positive as the first differing byte orders

`strncmp`

pub extern func strncmp(
    lhs: *char8,
    rhs: *char8,
    count: size_t
) -> c_int

Compares at most count bytes of two byte strings. Both are borrowed. Stops at count bytes or at either terminator, whichever comes first. Returns the same three-way answer strcmp does. Runs in time proportional to count and allocates nothing. Not constant-time. Both must be readable until a terminator or count bytes, whichever comes first.

See also: https://en.cppreference.com/c/string/byte/strncmp

Parameters

Name	Type	Description
`lhs`	`*char8`	the left operand
`rhs`	`*char8`	the right operand
`count`	`size_t`	how many bytes to compare at most

Returns: negative, zero or positive as the first differing byte orders

`strcpy`

pub extern func strcpy(
    dest: *var char8,
    src: *char8
) -> *var char8

Copies a byte string, terminator included. src is borrowed and read to its terminator; dest is borrowed and written. Returns dest. Runs in time proportional to the source length and allocates nothing. dest must have room for the source's length plus one, which this call has no way to check and does not. Getting that wrong is the classic buffer overrun; prefer memcpy with a length the caller computed.

See also: https://en.cppreference.com/c/string/byte/strcpy

Parameters

Name	Type	Description
`dest`	`*var char8`	where the bytes go
`src`	`*char8`	where the bytes come from

Returns: dest

`strncpy`

pub extern func strncpy(
    dest: *var char8,
    src: *char8,
    count: size_t
) -> *var char8

Copies at most count bytes of a byte string, padding with zeros. src is borrowed; dest is borrowed and written. Returns dest. Writes exactly count bytes: shorter sources are zero-padded to fill them. Runs in time proportional to count and allocates nothing. dest must be writable for count bytes. This does not terminate the result when the source is count bytes or longer, which is the trap in its name: it is not a bounded strcpy.

See also: https://en.cppreference.com/c/string/byte/strncpy

Parameters

Name	Type	Description
`dest`	`*var char8`	where the bytes go
`src`	`*char8`	where the bytes come from
`count`	`size_t`	how many bytes to write, terminator included

Returns: dest, which is not terminated when src filled the count

`strcat`

pub extern func strcat(
    dest: *var char8,
    src: *char8
) -> *var char8

Appends a byte string to the end of another. src is borrowed; dest is borrowed, read to its terminator, and then written from there. Returns dest. Runs in time proportional to the sum of the two lengths, since it finds the destination's end first. dest must be terminated and must have room for both lengths plus one. Repeated appending is quadratic and is a common accident: each call walks the destination from its start.

See also: https://en.cppreference.com/c/string/byte/strcat

Parameters

Name	Type	Description
`dest`	`*var char8`	where the bytes go
`src`	`*char8`	where the bytes come from

Returns: dest

`strncat`

pub extern func strncat(
    dest: *var char8,
    src: *char8,
    count: size_t
) -> *var char8

Appends at most count bytes of a byte string to the end of another. src is borrowed; dest is borrowed and written. Returns dest. Always terminates the result, so it writes up to count + 1 bytes past the destination's existing end. Runs in time proportional to the destination's length plus count. dest must be terminated and must have room for its own length plus count plus one. count bounds what is taken from the source, not the size of the destination.

See also: https://en.cppreference.com/c/string/byte/strncat

Parameters

Name	Type	Description
`dest`	`*var char8`	where the bytes go
`src`	`*char8`	where the bytes come from
`count`	`size_t`	how many bytes to take from `src` at most

Returns: dest

`strchr`

pub extern func strchr(str: *char8, ch: c_int) -> *char8

Finds the first occurrence of a byte in a byte string. str is borrowed. ch is converted to a char before comparison, and a ch of zero finds the terminator rather than failing. Returns a pointer into str, or null when the byte does not occur. Runs in time proportional to the string's length and allocates nothing. str must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strchr

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string
`ch`	`c_int`	the character, as an `int` holding an `unsigned char` value or `EOF`

Returns: the address of the first matching byte, or null; the terminator counts as a byte

`strrchr`

pub extern func strrchr(str: *char8, ch: c_int) -> *char8

Finds the last occurrence of a byte in a byte string. str is borrowed. A ch of zero finds the terminator. Returns a pointer into str, or null when the byte does not occur. Runs in time proportional to the string's length and allocates nothing. str must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strrchr

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string
`ch`	`c_int`	the character, as an `int` holding an `unsigned char` value or `EOF`

Returns: the address of the last matching byte, or null

`strstr`

pub extern func strstr(
    haystack: *char8,
    needle: *char8
) -> *char8

Finds the first occurrence of one byte string within another. Both are borrowed. An empty needle matches at the start. Returns a pointer into haystack, or null when the needle does not occur. Complexity is unspecified by the standard and is quadratic in the worst case on common implementations. Both must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strstr

Parameters

Name	Type	Description
`haystack`	`*char8`	the string to search
`needle`	`*char8`	the substring to look for

Returns: the address where needle starts in haystack, or null

`strspn`

pub extern func strspn(
    str: *char8,
    accept: *char8
) -> size_t

The length of the leading run of bytes drawn only from accept. Both are borrowed. Returns the index of the first byte of str not present in accept, which is the string's length when every byte is. Runs in time proportional to the product of the two lengths on a naive implementation. Both must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strspn

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string
`accept`	`*char8`	the set of bytes to accept

Returns: how many leading bytes are all in accept

`strcspn`

pub extern func strcspn(
    str: *char8,
    reject: *char8
) -> size_t

The length of the leading run of bytes drawn from none of reject. Both are borrowed. Returns the index of the first byte of str present in reject, which is the string's length when none is. Both must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strcspn

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string
`reject`	`*char8`	the set of bytes to reject

Returns: how many leading bytes are none of reject

`strpbrk`

pub extern func strpbrk(
    str: *char8,
    accept: *char8
) -> *char8

Finds the first byte of str that occurs in accept. Both are borrowed. Returns a pointer into str, or null when no byte of it occurs in accept. Both must be non-null and terminated.

See also: https://en.cppreference.com/c/string/byte/strpbrk

Parameters

Name	Type	Description
`str`	`*char8`	a null-terminated byte string
`accept`	`*char8`	the set of bytes to accept

Returns: the address of the first byte that is in accept, or null

`strtok`

pub extern func strtok(
    str: *var char8,
    delimiters: *char8
) -> *char8

Splits a byte string into tokens separated by any byte of delimiters. str is borrowed and modified: a terminator is written over each delimiter found. Pass the string on the first call and null on each call after it to continue the same scan. Returns the next token, or null when none is left. The scan's position is kept in storage shared by the whole program, so two interleaved scans destroy each other and no two threads may use this at once. The string must be writable, which rules out a literal.

See also: https://en.cppreference.com/c/string/byte/strtok

Parameters

Name	Type	Description
`str`	`*var char8`	a null-terminated byte string
`delimiters`	`*char8`	the set of bytes that separate tokens

Returns: the next token, or null; the position is kept in storage shared by the whole program

General utilities

C's <stdlib.h>: allocation, number parsing, sorting, pseudo-random numbers and exit codes.

Time

C's <time.h>: calendar time, processor time and the conversions between them.

Edit this page on GitHub