November XXIII MMXXII
Copyright Gabriel Jensen
the Zap Algorithmics Interfaces
Edition XXI amd. I
Contents
Behaviour
Preamble
This section specifies what behaviour the implementation is and is not allowed to express. Some cases might allow the implementation to perform non-standard, implementation-defined behaviour, whilst others may require specific, reproducable outcomes.
Guaranteed Behaviour
The implementation must guarantee the following:
The behaviour of a program that doesn't contain any undefined or deprecated behaviour is well-defined and doesn't behave in a way not allowed by this standard;
Normal usage from all versions of standard C and of standard C++ is supported; 1
The behaviour of the program doesn't change with multiple inclusions of a header; 2
All object-like macros evaluate to immutable expressions (as by wrapping the values in parantheses where necessary) which may be used in preprocessor-if expressions; 3
All function-like macros evaluate every provided parameter (argument) excactly once, and their return values must be immutable (if applicable); 3
All symbols are made available after including the required header;
All symbols are wrapped in a C-langauge-linkage block in C++; 3
The implementation – by default – doesn't define, declare, or otherwise provide any symbol which isn't reserved by this standard or already provided by the system, but this may be overwritten if the program opts-in in an implementation-defined manner;
1 Implementation-provided extensions may require usage from a specific language;
2 This doesn't apply for implementation-provided headers directly-included by the program;
3 This isn't required for implementation-provided symbols;
Deprecated Behaviour
If any behaviour is deprecated, the implementation may warn about such behaviour at translation time.
Unspecified Behaviour
If unspecified behaviour occurs, the implementation is free to conform to any of the choices specified by this standard. The behaviour of a program that depends on such behaviour is deprecated.
Undefined Behaviour
If the program breaks a clause (which, per this standard, results in undefined behaviour), no result of the program may be predictable. The implementation may, however, guarantee well-defined behaviour on a case-by-case basis.
Extensions
The implementation may extend this standard by providing it's own symbols and headers. Implementations are advised, however, to follow the same naming convention as this standard.
All symbols with the zap_priv_ prefix and all global headers with the zap/priv/ prefix are reserved for the implementation, and no future version of this standard may use them. All other symbols with the zap_ prefix and all other headers with the zap/ prefix may be provided by the implementation, but these may in the future be replaced by this standard.
Headers
Preamble
The following headers are required to be present on all implementation. They all have the zap/ prefix and are included via an '#include <XXX>' expression.
These headers may only include implementation-provided headers or permitted standard headers.
If the program creates a new header of the style '<zap/XXX>', the behaviour is undefined.
bs.h
The bs.h (base) header provides a basic groundwork for the program and the other headers.
It may (optionally) directly include any of the following standard library headers: limits.h, stdbool.h, stddef.h, stdint.h, uchar.h.
This header provides the following symbols:
mem.h
The mem.h (memory) header provides functions for manipulating memory sequences and strings. It includes the bs.h header.
It provides the following symbols:
Symbols
Preamble
The following symbols are required to be available after the appropriate header has been included. They all have the zap_ prefix.
All symbols with the zap_ prefix are reserved for this standard and the implementation. If the program declares or defines a reserved symbol, undefines a reserved macro (through the '#undef'-preprocessor statement), the behaviour is undefined.
abs
unsigned char zap_abs_c(char val);
unsigned int zap_abs_i(int val);
unsigned long zap_abs_l(long val);
unsigned long long zap_abs_ll(long long val);
unsigned short zap_abs_s(short val);
unsigned char zap_abs_sc(signed char val);
Returns the absolute value of val, that is, the positive equivalent value of val.
alloc
zap_mem zap_alloc(zap_sz algn,zap_sz num);
Attempts to allocate a continuous memory sequence of num-bytes, with the first being aligned at an algn-byte boundary. The values of each byte is indeterminate.
If the memory allocation – for any reason – fails, nullptr is placed into .ptr, and .len has an unspecified value. Otherwise, a pointer to the first byte of the memory sequence is placed into .ptr, with the length of the sequence (num) being placed into .len.
If algn is zero, the first byte is fundamentally aligned instead (that is, it has the same alignement as that of the standard library type max_align_t).
The allocated object (pointed to by .ptr) has – by default – no effective type. This can, however, be overwritten through the following means:
If it's written to via memcp, the effective type becomes that of the source object (unless it also doesn't have one);
If it's written to via strcp or strfill, the effective type becomes the built-in type char;
If it's written to via utf8enc or win1252enc, the effective type becomes chr8;
If it's written to via utf8dec or win1252dec, the effective type becomes chr20;
If it's accessed through dereferencing or using the subscript operator after a pointer type cast, the effective type is the pointed-to type of the new pointer type;
All calls to alloc synchronise with calls to free such that the freed memory may immediatly be reused and so that no race condition occurs.
The behaviour is undefined if:
num is zero;
algn isn't a valid alignement (that is, it's never the result of the alignof operator);
the returned structure is never passed to free;
bool, false, true
typedef /* see below */ zap_bool;
#define zap_false /* see below */
#define zap_true /* see below */
The type bool is an unsigned integral type capable of holding (at least) the values zero and one. The object-like macros false and true expand to expressions of this type, with the evaluated values being zero and an unspecified, greater-than-zero value respectively.
Only values returned by standard functions returning bool are guaranteed to return the values false or true. It's unspecified if this type can represent more than two values, or if a value cast to this type is truncated to one of those two.
chr10, chr20, chr8
typedef /* see below */ zap_chr10;
typedef /* see below */ zap_chr20;
typedef /* see below */ zap_chr8;
The types chr8, chr10, chr20 are unsigned integral types suitable for holding character values (namely of UTF-8, UTF-16, and UTF-32 respectively).
The underlying type of chr8 is the built-in type unsigned char. The underlying types of chr10 and chr20 are the smallest unsigned integral types of at least 16 and 32 bits respectively.
cmp, eq, gt, lt
typedef /* see below */ zap_cmp;
#define zap_eq /* see below */
#define zap_gt /* see below */
#define zap_lt /* see below */
A signed integral type capable of storing (at least) negative one, zero, and positive one. The object-like macros eq, gt, and lt evaluate to zero, a greater-than-zero value, and a less-than-zero value (all of this type) respectively.
It's unspecified if this type can hold more values that the minimum required. It's unspecified if values cast to this type are truncated to one of the three required.
Only values returned by standard facilities (returning this type) are guaranteed to compare equal to either eq, gt, or lt.
div
zap_divmod_c zap_div_c(char num,char den);
zap_divmod_i zap_div_i(int num,int den);
zap_divmod_l zap_div_l(long num,long den);
zap_divmod_ll zap_div_ll(long long num,long long den);
zap_divmod_s zap_div_s(short num,short den);
zap_divmod_sc zap_div_sc(signed char num,signed char den);
zap_divmod_uc zap_div_uc(unsigned char num,unsigned char den);
zap_divmod_ui zap_div_ui(unsigned int num,unsigned int den);
zap_divmod_ul zap_div_ul(unsigned long num,unsigned long den);
zap_divmod_ull zap_div_ull(unsigned long long num,unsigned long long den);
zap_divmod_us zap_div_us(unsigned short num,unsigned short den);
Returns a structure containing the quotient (result of the operation (num / den)) and the remainder of the division (result of (num % den)) of the numerator num and denominator in the div and mod members respectively.
The behaviour is undefined if:
den is zero;
The operands are signed and the result cannot fit into the destination type;
divmod
typedef struct {char div;char mod;} zap_divmod_c;
typedef struct {int div;int mod;} zap_divmod_i;
typedef struct {long div;long mod;} zap_divmod_l;
typedef struct {long long div;long long mod;} zap_divmod_ll;
typedef struct {short div;short mod;} zap_divmod_s;
typedef struct {signed char div;signed char mod;} zap_divmod_sc;
typedef struct {unsigned char div;unsigned char mod;} zap_divmod_uc;
typedef struct {unsigned int div;unsigned int mod;} zap_divmod_ui;
typedef struct {unsigned long div;unsigned long mod;} zap_divmod_ul;
typedef struct {unsigned long long div;unsigned long long mod;} zap_divmod_ull;
typedef struct {unsigned short div;unsigned short mod;} zap_divmod_us;
Has the members div and mod for storing the quotient and the remainder of a division.
exp
char zap_exp_c(char bs,char exp);
int zap_exp_i(int bs,int exp);
long zap_exp_l(long bs,long exp);
long long zap_exp_ll(long long bs,long long exp);
short zap_exp_s(short bs,short exp);
signed char zap_exp_sc(signed char bs,signed char exp);
unsigned char zap_exp_uc(unsigned char bs,unsigned char exp);
unsigned int zap_exp_ui(unsigned int bs,unsigned int exp);
unsigned long zap_exp_ul(unsigned long bs,unsigned long exp);
unsigned long long zap_exp_ull(unsigned long long bs,unsigned long long exp);
unsigned short zap_exp_us(unsigned short bs,unsigned short exp);
Returns bs raised to the power of exp. If the first operand is unsigned and the result cannot be represented by the target type, the result is truncated according to the rules of unsigned overflow. If exp is zero, one is always returned.
The behaviour is undefined if:
The first operand is signed and the result cannot fit into the destination type;
frac
typedef struct {char num;char den;} zap_frac_c;
typedef struct {int num;int den;} zap_frac_i;
typedef struct {long num;long den;} zap_frac_l;
typedef struct {long long num;long long den;} zap_frac_ll;
typedef struct {short num;short den;} zap_frac_s;
typedef struct {signed char num;signed char den;} zap_frac_sc;
typedef struct {unsigned char num;unsigned char den;} zap_frac_uc;
typedef struct {unsigned int num;unsigned int den;} zap_frac_ui;
typedef struct {unsigned long num;unsigned long den;} zap_frac_ul;
typedef struct {unsigned long long num;unsigned long long den;} zap_frac_ull;
typedef struct {unsigned short num;unsigned short den;} zap_frac_us;
Has the members num and den for storing the numerator and denominator of a fraction.
free
void zap_free(zap_mem mem);
Frees the memory sequence specified by mem.
All calls to free synchronise with calls to alloc such that the freed memory may immediatly be reused and so that no race condition occurs.
The behaviour is undefined if:
mem isn't an unmodified structure previously returned by a successful call to alloc (and which isn't already free);
mem.len isn't the length of the memory sequence pointed to by mem.ptr (as passed to alloc);
mem is passed to this function more than once (without being returned by alloc in the meantime);
The object pointed to by mem.ptr is accessed after the call to free (and the same memory block hasn't been allocated by alloc in the meantime);
log
unsigned char zap_log_uc(unsigned char bs,unsigned char pow);
unsigned int zap_log_ui(unsigned int bs,unsigned int pow);
unsigned long zap_log_ul(unsigned long bs,unsigned long pow);
unsigned long long zap_log_ull(unsigned long long bs,unsigned long long pow);
unsigned short zap_log_us(unsigned short bs,unsigned short pow);
Returns the truncated (to the nearest representable value) logarithm base bs of the power pow, unless:
bs and num are zero, in which case one is returned;
bs and num are one, in which case zero is returned;
If multiple of these conditions are met, the first listed outcome is used.
The behaviour is undefined if:
bs is zero or one;
num is zero;
maxval
#define zap_maxval_sc /* see below */
#define zap_maxval_c /* see below */
#define zap_maxval_i /* see below */
#define zap_maxval_l /* see below */
#define zap_maxval_ll /* see below */
#define zap_maxval_s /* see below */
#define zap_maxval_sc /* see below */
#define zap_maxval_uc /* see below */
#define zap_maxval_ui /* see below */
#define zap_maxval_ul /* see below */
#define zap_maxval_ull /* see below */
#define zap_maxval_us /* see below */
Expands to an expression of the appropriate type evaluating to the type's largest supported value.
mem
typedef struct {void * ptr;zap_sz sz} zap_mem;
A structure type for holding information about memory blocks returned by alloc. It has the members ptr of the built-in type void * and len of the type sz (in that order).
The type is made a typedef so that usage of 'zap_mem' (without the 'struct' keyword) is correct usage.
memcnt
zap_sz zap_memcnt(void const * ptr,zap_sz sz,zap_sz num,zap_bool (* fn)(void const *));
Invokes the function fn num-times with a pointer value that is sz points larger than the previous, starting at ptr. The number of times the function invokation returned true is returned.
The behaviour is undefined if:
ptr isn't a valid pointer to an array;
num is larger than the number of elements in the array;
sz is not the object size of the elements that make up the array;
fn is not a valid pointer to a function with C-language-linkage;
memcp
void zap_memcp(void const * in,zap_sz num,void * out);
Copies num-bytes from the buffer pointed to by in into the same relative position in the buffer pointer to by out.
The behaviour is undefined if:
in or out aren't valid pointers to arrays;
num is larger than the number of bytes in the smallest array;
memeq
bool zap_memeq(void const * lptr,zap_sz num,void * rptr);
Checks num-bytes of the buffers pointed to by lptr and rptr for equality.
If any two bytes are found to be different in the two buffers, false is returned. Otherwise, true is returned.
The behaviour is undefined if:
lptr or rptr aren't valid pointers to arrays;
num is larger than the number of bytes in the smallest array;
memfill
void zap_memfill(void const * ptr,zap_sz num,unsigned char byte);
Fills num-bytes of the buffer pointed to by ptr with the representation of byte.
The behaviour is undefined if:
ptr isn't a valid pointer to an array;
num is larger than the number of bytes of in the array;
memfnd
zap_sz zap_fndbtyte(void const * ptr,zap_sz num,unsigned char byte);
Searches for the byte-value byte in the array pointed to by ptr within the bounds of num.
If the byte-value is found within the specified bounds, the position of it's first occurrence (starting at zero) is returned. Otherwise, nopos is returned.
The behaviour is undefined if:
ptr isn't a valid pointer to an array;
num is larger than the number of bytes in the array;
memfor
void zap_memfor(void * ptr,zap_sz sz,zap_sz num,void (* fn)(void *));
Iterates through the array pointed to by ptr, invoking the function fn with a pointer to the current element. Each pointer value after the first is equal to the previous plus sz.
The behaviour is undefined if:
sz is neither one nor the real object size of each element in the array;
num is larger than the number of elements in the array;
fn isn't a valid pointer to a function with C-language-linkage;
memgen
void zap_memgen(void * ptr,zap_sz sz,zap_sz num,void (* fn)(zap_sz,void *));
Calls fn for num-elements of size sz in the array pointed to by ptr. The index number of the element (starting at zero) and a pointer to the element are passed to the function.
The behaviour is undefined if:
ptr isn't a valid pointer to an array;
sz is neither one nor the real object size of each element in the array;
num is larger than the number of bytes of in the array;
fn isn't a valid pointer to a function with C-language-linkage;
minval
#define zap_minval_c /* see below */
#define zap_minval_i /* see below */
#define zap_minval_l /* see below */
#define zap_minval_ll /* see below */
#define zap_minval_s /* see below */
#define zap_minval_sc /* see below */
Expands to an expression of the appropriate type evaluating to the type's smallest supported value.
mul
char zap_mul_c(char lfac,char rfac);
int zap_mul_i(int lfac,int rfac);
long zap_mul_l(long lfac,long rfac);
long long zap_mul_ll(long long lfac,long long rfac);
short zap_mul_s(short lfac,short rfac);
signed char zap_mul_sc(signed char lfac,signed char rfac);
unsigned char zap_mul_uc(unsigned char lfac,unsigned char rfac);
unsigned int zap_mul_ui(unsigned int lfac,unsigned int rfac);
unsigned long zap_mul_ul(unsigned long lfac,unsigned long rfac);
unsigned long long zap_mul_ull(unsigned long long lfac,unsigned long long rfac);
unsigned short zap_mul_us(unsigned short lfac,unsigned short rfac);
Returns the result of the expression (lfac * rfac). If the operands are unsigned, the result is truncated according to unsigned overflow.
The behaviour is undefined if:
The operands are signed and the result cannot be represented by the target type;
nopos
#define zap_nopos /* see below */
Expands to a value of type sz indicating an invalid position. The value may not be a valid position of any valid array type.
nrt
char zap_nrt_c(char deg,char rad);
int zap_nrt_i(int deg,int rad);
long zap_nrt_l(long deg,long rad);
long long zap_nrt_ll(long long deg,long long rad);
short zap_nrt_s(short deg,short rad);
signed char zap_nrt_sc(signed char deg,signed char rad);
unsigned char zap_nrt_uc(unsigned char deg,unsigned char rad);
unsigned int zap_nrt_ui(unsigned int deg,unsigned int rad);
unsigned long zap_nrt_ul(unsigned long deg,unsigned long rad);
unsigned long long zap_nrt_ull(unsigned long long deg,unsigned long long rad);
unsigned short zap_nrt_us(unsigned short deg,unsigned short rad);
Returns the deg-th root of rad. If the operands are unsigned, the result is truncated according to unsigned overflow.
The behaviour is undefined if:
deg is zero;
deg is a positive, even number and rad is negative;
nullptr
#define zap_nullptr /* see below */
Expands to the system null pointer constant. This constant may be implicitly cast to any other pointer type, and the result of such cast is the null pointer value of that type.
If this constant is cast to any pointer type, the value of such conversion will compare equal to the standard library constant NULL cast to the same type.
The definition may either be a constant expression of the type int with the value zero, the same but cast to the type void * (except in C++), or the nullptr constant (if supported by the language).
strcp
zap_sz zap_strcp(char const * in,char * out);
Copies all characters (including the null-terminator) of the string pointed to by in into the buffer pointed to by out. The length (excluding the null-terminator) of the string is returned.
The behaviour is undefined if:
in isn't a valid pointer to a null-terminated string;
out isn't a valid pointer to an array, or if the pointed-to array cannot fit the string;
streq
bool zap_streq(char const * lstr,char const * rstr);
Checks the equality of the strings lstr and rstr.
If one of the strings has a length different from the other, or if any character in the two strings is different from the other (at the same offset), true is returned. Otherwise, false is returned.
The behaviour is undefined if:
lstr or rstr aren't valid pointers to null-terminated strings;
strfill
zap_sz zap_strfill(char * str,char chr);
Writes the character chr to every valid position in the string str, excluding that of the null-terminator. The length of the string (excluding the null-terminater) is returned.
The behaviour is undefined if:
str isn't a valid pointer to a null-terminated string;
strfnd
zap_sz zap_strfnd(char const * str,char chr);
Searches for the character chr in the string str. The null-terminator isn't included in the search.
If the character is found within the string, it's index number is returned. Otherwise, nopos is returned.
The behaviour is undefined if:
str isn't a valid pointer to a null-terminated string;
strlen
zap_sz zap_strlen(char const * str);
Counts the number of characters in the string str.
Returns the number of characters (excluding the null-terminator) in the string.
The behaviour is undefined if:
str isn't a valid pointer to a null-terminated string;
sz
typedef /* see below */ zap_sz;
An unsigned integral type capable of holding any valid object size (as returned by sizeof) or alignement (as returned by alignof). It's identical to the standard library type size_t.
It's unspecified if all representable values of this type are valid object sizes or alignements.
utf8dec
void zap_utf8dec(zap_chr8 const * in,zap_chr20 * out);
Decodes the UTF-8-encoded string pointed to by in into UTF-32. The resulting (null-terminated) string is placed into the buffer pointed to by out.
The behaviour is undefined if:
in isn't a valid pointer to a null-terminated, UTF-8-encoded string;
The input string contains an invalid octet;
out isn't a valid pointer to an array, or if the array cannot fit the encoded string;
utf8declen
zap_sz zap_utf8declen(zap_chr8 const * utf8);
Returns the length (excluding the null-terminator) of the UTF-8-encoded string pointed to by utf8, as if it was encoded in UTF-32.
The behaviour is undefined if:
utf8 isn't a valid pointer to a null-terminated, UTF-8-encoded string;
The string contains an invalid octet;
utf8enc
void zap_utf8enc(zap_chr20 const * in,zap_chr8 * out);
Encodes the UTF-32-encoded string pointed to by in into UTF-8. The resulting (null-terminated) string is placed into the buffer pointed to by out.
The behaviour is undefined if:
in isn't a valid pointer to a null-terminated, UTF-32-encoded string;
The input string contains an invalid codepoint;
out isn't a valid pointer to an array, or if the array cannot fit the encoded string;
utf8enclen
zap_sz zap_utf8enclen(zap_chr20 const * utf20);
Returns the length (excluding the null-terminator) of the UTF-32-encoded string pointed to by utf20, as if it was encoded in UTF-8.
The behaviour is undefined if:
utf8 isn't a valid pointer to a null-terminated, UTF-32-encoded string;
The string contains an invalid codepoint;
ver
#define zap_ver /* see below */
Expands to a value (of the built-in type unsigned long) indicating the edition of the supported interface – currently twenty-one (21).
win1252dec
void zap_win1252dec(zap_chr8 const * in,zap_chr20 * out);
Decodes the null-terminated, Windows-1252-encoded string (pointed to by in) into UTF-32, with the resulting (null-terminated) string being placed into the buffer pointed to by out.
If an invalid Windows-1252 character (that is, the byte values 0x81, 0x8D, 0x8F, 0x90, and 0x9D) is found, it's replaced with the codepoint U+FFFD (REPLACEMENT CHARACTER).
The behaviour is undefined if:
in isn't a valid pointer to a null-terminated, Windows-1252-encoded string;
out isn't a valid pointer to a buffer, or if the pointed-to buffer isn't at least as big (in number of elements) as the input string (including the null-terminator);
win1252enc
void zap_win1252enc(zap_chr20 const * in,zap_chr8 * out);
Encodes the null-terminated, UTF-32-encoded string (pointed to by in) into Windows-1252, with the resulting (null-terminated) string being placed into the buffer pointed to by out.
If a character in the input doesn't exist in win1252, it's replaced by an unspecified, valid win1252 character.
The behaviour is undefined if:
in isn't a valid pointer to a null-terminated, UTF-20-encoded string;
out isn't a valid pointer to a buffer, or if the pointed-to buffer isn't at least as big (in number of elements) as the input string (including the null-terminator);