<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>the Zap Algorithmics Interface</title>
<style>
:root {
--black:hsl(0deg 0% calc(100% / 12));
--white:hsl(0deg 0% calc(100% * 35 / 36));
}
* {
color: var(--black);
margin: 0;
padding:0;
}
body {
background-color:var(--black);
font-family: "Liberation Serif","serif";
}
div.page {
background-color:var(--white);
border-radius: 1rem;
box-sizing: border-box;
counter-reset: chapter -1;
height: 100%;
margin: 2rem auto;
padding: 1rem 3rem;
width: 72rem;
}
div.page div.header {
margin-bottom:4rem;
}
div.page div.header p.date,div.page div.header p.copyright {
font-weight:bold;
text-align: center;
}
div.page div.header p.title {
font-size:4rem;
}
div.page div.header p.edition {
font-weight:bold;
}
div.page div.chapter {
counter-reset:section -1;
}
div.page div.chapter p.chapterTitle {
font-size: 2rem;
font-weight: bold;
margin-bottom:1rem;
}
div.page div.chapter p.chapterTitle:before {
content: counter(chapter) ". ";
counter-increment:chapter;
font-weight: normal;
}
div.page div.chapter div.code {
background-color:var(--black);
border-radius: calc(1rem / 3);
font-family: "Source Code Pro","monospace";
font-size: calc(5rem / 6);
letter-spacing: calc(1rem / 36);
line-height: 2em;
padding: calc(1rem / 3) 1rem;
width: fit-content;
}
div.page div.chapter div.code p {
color:var(--white);
}
div.page div.chapter p.note {
font-size:calc(5rem / 6);
}
div.page div.chapter ol li,div.chapter ul li {
margin-left:2rem;
}
div.page div.chapter ol.chapterList {
counter-reset: chapterListIndex -1;
list-style-type:none;
}
div.page div.chapter ol.chapterList li p:before {
content: counter(chapterListIndex) ". ";
counter-increment:chapterListIndex;
}
div.page div.chapter ol.chapterList li ol.sectionList {
counter-reset: sectionListIndex -1;
list-style-type:none;
}
div.page div.chapter ol.chapterList li ol.sectionList li p:before {
content: counter(sectionListIndex) ". ";
counter-increment:sectionListIndex;
}
div.page div.chapter + div.chapter {
margin-top:2rem;
}
div.page div.chapter div.section p.sectionTitle {
font-weight: bold;
margin-bottom:calc(1rem / 2);
}
div.page div.chapter div.section p.sectionTitle:before {
content: counter(section) ". ";
counter-increment:section;
}
div.page div.chapter div.section + div.section {
margin-top:1rem;
}
</style>
</head>
<body>
<div class="page">
<div class="header">
<p class="date">November XXIII MMXXII</p>
<p class="copyright">Copyright Gabriel Jensen</p>
<p class="title">the Zap Algorithmics Interfaces</p>
<p class="edition">Edition XXI<sub> amd. I</sub></p>
<div class="line"></div>
</div>
<div class="chapter">
<p class="chapterTitle" id="contents">Contents</p>
<ol class="chapterList">
<li>
<p><a href="#contents">Contents</a></p>
</li>
<li>
<p><a href="#behaviour">Behaviour</a></p>
<ol class="sectionList">
<li>
<p><a href="#behaviour_preamble">Preamble</a></p>
</li>
<li>
<p><a href="#behaviour_guaranteed-behaviour">Guaranteed Behaviour</a></p>
</li>
<li>
<p><a href="#behaviour_deprecated-behaviour">Deprecated Behaviour</a></p>
</li>
<li>
<p><a href="#behaviour_unspecified-behaviour">Unspecified Behaviour</a></p>
</li>
<li>
<p><a href="#behaviour_undefined-behaviour">Undefined Behaviour</a></p>
</li>
<li>
<p><a href="#behaviour_extensions">Extensions</a></p>
</li>
</ol>
</li>
<li>
<p><a href="#headers">Headers</a></p>
<ol class="sectionList">
<li>
<p><a href="#headers_preamble">Preamble</a></p>
</li>
<li>
<p><a href="#headers_bs">bs.h</a></p>
</li>
<li>
<p><a href="#headers_mem">mem.h</a></p>
</li>
<li>
<p><a href="#headers_mth">mth.h</a></p>
</li>
</ol>
</li>
<li>
<p><a href="#symbols">Symbols</a></p>
<ol class="sectionList">
<li>
<p><a href="#symbols_preamble">Preamble</a></p>
</li>
<li>
<p><a href="#symbols_abs">abs</a></p>
</li>
<li>
<p><a href="#symbols_alloc">alloc</a></p>
</li>
<li>
<p><a href="#symbols_bool-false-true">bool, false, true</a></p>
</li>
<li>
<p><a href="#symbols_chr10-chr20-chr8">chr10, chr20, chr8</a></p>
</li>
<li>
<p><a href="#symbols_cmp-eq-gt-lt">cmp, eq, gt, lt</a></p>
</li>
<li>
<p><a href="#symbols_div">div</a></p>
</li>
<li>
<p><a href="#symbols_divmod">divmod</a></p>
</li>
<li>
<p><a href="#symbols_exp">exp</a></p>
</li>
<li>
<p><a href="#symbols_frac">frac</a></p>
</li>
<li>
<p><a href="#symbols_free">free</a></p>
</li>
<li>
<p><a href="#symbols_log">log</a></p>
</li>
<li>
<p><a href="#symbols_maxval">maxval</a></p>
</li>
<li>
<p><a href="#symbols_mem">mem</a></p>
</li>
<li>
<p><a href="#symbols_memcnt">memcnt</a></p>
</li>
<li>
<p><a href="#symbols_memcp">memcp</a></p>
</li>
<li>
<p><a href="#symbols_memeq">memeq</a></p>
</li>
<li>
<p><a href="#symbols_memfill">memfill</a></p>
</li>
<li>
<p><a href="#symbols_memfnd">memfnd</a></p>
</li>
<li>
<p><a href="#symbols_memfor">memfor</a></p>
</li>
<li>
<p><a href="#symbols_memgen">memgen</a></p>
</li>
<li>
<p><a href="#symbols_minval">minval</a></p>
</li>
<li>
<p><a href="#symbols_mul">mul</a></p>
</li>
<li>
<p><a href="#symbols_nopos">nopos</a></p>
</li>
<li>
<p><a href="#symbols_nrt">nrt</a></p>
</li>
<li>
<p><a href="#symbols_nullptr">nullptr</a></p>
</li>
<li>
<p><a href="#symbols_strcp">strcp</a></p>
</li>
<li>
<p><a href="#symbols_strfill">strfill</a></p>
</li>
<li>
<p><a href="#symbols_strfnd">strfnd</a></p>
</li>
<li>
<p><a href="#symbols_strlen">strlen</a></p>
</li>
<li>
<p><a href="#symbols_sz">sz</a></p>
</li>
<li>
<p><a href="#symbols_utf8dec">utf8dec</a></p>
</li>
<li>
<p><a href="#symbols_utf8declen">utf8declen</a></p>
</li>
<li>
<p><a href="#symbols_utf8enc">utf8enc</a></p>
</li>
<li>
<p><a href="#symbols_utf8enclen">utf8enclen</a></p>
</li>
<li>
<p><a href="#symbols_ver">ver</a></p>
</li>
<li>
<p><a href="#symbols_win1252dec">win1252dec</a></p>
</li>
<li>
<p><a href="#symbols_win1252enc">win1252enc</a></p>
</li>
</ol>
</li>
</ol>
</div>
<div class="chapter">
<p class="chapterTitle" id="behaviour">Behaviour</p>
<div class="line"></div>
<div class="section">
<p class="sectionTitle" id="behaviour_preamble">Preamble</p>
<p>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.</p>
</div>
<div class="section">
<p class="sectionTitle" id="behaviour_guaranteed-behaviour">Guaranteed Behaviour</p>
<p>The implementation must guarantee the following:</p>
<ol>
<li><p>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;</p></li>
<li><p>Normal usage from all versions of standard C and of standard C++ is supported; <sup>1</sup></p></li>
<li><p>The behaviour of the program doesn't change with multiple inclusions of a header; <sup>2</sup></p></li>
<li><p>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; <sup>3</sup></p></li>
<li><p>All function-like macros evaluate every provided parameter (argument) excactly once, and their return values must be immutable (if applicable); <sup>3</sup></p></li>
<li><p>All symbols are made available after including the required header;</p></li>
<li><p>All symbols are wrapped in a C-langauge-linkage block in C++; <sup>3</sup></p></li>
<li><p>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;</p></li>
</ol>
<p class="note"><sup>1</sup> Implementation-provided extensions may require usage from a specific language;</p>
<p class="note"><sup>2</sup> This doesn't apply for implementation-provided headers directly-included by the program;</p>
<p class="note"><sup>3</sup> This isn't required for implementation-provided symbols;</p>
</div>
<div class="section">
<p class="sectionTitle" id="behaviour_deprecated-behaviour">Deprecated Behaviour</p>
<p>If any behaviour is <i>deprecated</i>, the implementation may warn about such behaviour at translation time.</p>
</div>
<div class="section">
<p class="sectionTitle" id="behaviour_unspecified-behaviour">Unspecified Behaviour</p>
<p>If <i>unspecified behaviour</i> 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.</p>
</div>
<div class="section">
<p class="sectionTitle" id="behaviour_undefined-behaviour">Undefined Behaviour</p>
<p>If the program breaks a clause (which, per this standard, results in <i>undefined behaviour</i>), no result of the program may be predictable. The implementation may, however, guarantee well-defined behaviour on a case-by-case basis.</p>
</div>
<div class="section">
<p class="sectionTitle" id="behaviour_extensions">Extensions</p>
<p>The implementation may <i>extend</i> this standard by providing it's own symbols and headers. Implementations are advised, however, to follow the same naming convention as this standard.</p>
<p>All symbols with the <i>zap_priv_</i> prefix and all global headers with the <i>zap/priv/</i> prefix are reserved for the implementation, and no future version of this standard may use them. All other symbols with the <i>zap_</i> prefix and all other headers with the <i>zap/</i> prefix may be provided by the implementation, but these may in the future be replaced by this standard.</p>
</div>
</div>
<div class="chapter">
<p class="chapterTitle" id="headers">Headers</p>
<div class="line"></div>
<div class="section">
<p class="sectionTitle" id="headers_preamble">Preamble</p>
<p>The following headers are required to be present on all implementation. They all have the <i>zap/</i> prefix and are included via an '#include <<i>XXX</i>>' expression.</p>
<p>These headers may only include implementation-provided headers or permitted standard headers.</p>
<p>If the program creates a new header of the style '<zap/<i>XXX</i>>', the behaviour is undefined.</p>
</div>
<div class="section">
<p class="sectionTitle" id="headers_bs">bs.h</p>
<p>The <i>bs.h</i> (base) header provides a basic groundwork for the program and the other headers.</p>
<p>It may (optionally) directly include any of the following standard library headers: <i>limits.h</i>, <i>stdbool.h</i>, <i>stddef.h</i>, <i>stdint.h</i>, <i>uchar.h</i>.</p>
<p>This header provides the following symbols:</p>
<ul>
<li>
<p><a href="#symbols_bool-false-true">bool, false, true</a></p>
</li>
<li>
<p><a href="#symbols_chr10-chr20-chr8">chr10, chr20, chr8</a></p>
</li>
<li>
<p><a href="#symbols_cmp-eq-gt-lt">cmp, eq, gt, lt</a></p>
</li>
<li>
<p><a href="#symbols_nopos">nopos</a></p>
</li>
<li>
<p><a href="#symbols_nullptr">nullptr</a></p>
</li>
<li>
<p><a href="#symbols_sz">sz</a></p>
</li>
<li>
<p><a href="#symbols_ver">ver</a></p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="headers_mem">mem.h</p>
<p>The <i>mem.h</i> (memory) header provides functions for manipulating memory sequences and strings. It includes the <i>bs.h</i> header.</p>
<p>It provides the following symbols:</p>
<ul>
<li>
<p><a href="#symbols_alloc">alloc</a></p>
</li>
<li>
<p><a href="#symbols_free">free</a></p>
</li>
<li>
<p><a href="#symbols_mem">mem</a></p>
</li>
<li>
<p><a href="#symbols_memcnt">memcnt</a></p>
</li>
<li>
<p><a href="#symbols_memcp">memcp</a></p>
</li>
<li>
<p><a href="#symbols_memfnd">memfnd</a></p>
</li>
<li>
<p><a href="#symbols_memfor">memfor</a></p>
</li>
<li>
<p><a href="#symbols_memeq">memeq</a></p>
</li>
<li>
<p><a href="#symbols_memfill">memfill</a></p>
</li>
<li>
<p><a href="#symbols_memgen">memgen</a></p>
</li>
<li>
<p><a href="#symbols_strcp">strcp</a></p>
</li>
<li>
<p><a href="#symbols_strfill">strfill</a></p>
</li>
<li>
<p><a href="#symbols_strfnd">strfnd</a></p>
</li>
<li>
<p><a href="#symbols_strlen">strlen</a></p>
</li>
<li>
<p><a href="#symbols_utf8dec">utf8dec</a></p>
</li>
<li>
<p><a href="#symbols_utf8declen">utf8declen</a></p>
</li>
<li>
<p><a href="#symbols_utf8enc">utf8enc</a></p>
</li>
<li>
<p><a href="#symbols_utf8enclen">utf8enclen</a></p>
</li>
<li>
<p><a href="#symbols_win1252dec">win1252dec</a></p>
</li>
<li>
<p><a href="#symbols_win1252enc">win1252enc</a></p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="headers_mth">mth.h</p>
<p>The <i>mth.h</i> (mathematics) header provides functions and types for mathematical operations. It includes the <i>bs.h</i> header.</p>
<p>The following symbols are provided:</p>
<ul>
<li>
<p><a href="#symbols_abs">abs</a></p>
</li>
<li>
<p><a href="#symbols_div">div</a></p>
</li>
<li>
<p><a href="#symbols_divmod">divmod</a></p>
</li>
<li>
<p><a href="#symbols_exp">exp</a></p>
</li>
<li>
<p><a href="#symbols_frac">frac</a></p>
</li>
<li>
<p><a href="#symbols_log">log</a></p>
</li>
<li>
<p><a href="#symbols_maxval">maxval</a></p>
</li>
<li>
<p><a href="#symbols_minval">minval</a></p>
</li>
<li>
<p><a href="#symbols_mul">mul</a></p>
</li>
<li>
<p><a href="#symbols_nrt">nrt</a></p>
</li>
</ul>
</div>
</div>
<div class="chapter">
<p class="chapterTitle" id="symbols">Symbols</p>
<div class="line"></div>
<div class="section">
<p class="sectionTitle" id="symbols_preamble">Preamble</p>
<p>The following symbols are required to be available after the appropriate header has been included. They all have the <i>zap_</i> prefix.</p>
<p>All symbols with the <i>zap_</i> 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.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_abs">abs</p>
<div class="code">
<p>unsigned char zap_abs_c(char val);</p>
<p>unsigned int zap_abs_i(int val);</p>
<p>unsigned long zap_abs_l(long val);</p>
<p>unsigned long long zap_abs_ll(long long val);</p>
<p>unsigned short zap_abs_s(short val);</p>
<p>unsigned char zap_abs_sc(signed char val);</p>
</div>
<br />
<p>Returns the <i>absolute value</i> of <i>val</i>, that is, the positive equivalent value of <i>val</i>.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_alloc">alloc</p>
<div class="code">
<p>zap_mem zap_alloc(zap_sz algn,zap_sz num);</p>
</div>
<br />
<p>Attempts to allocate a continuous memory sequence of <i>num</i>-bytes, with the first being aligned at an <i>algn</i>-byte boundary. The values of each byte is indeterminate.</p>
<p>If the memory allocation – for any reason – fails, <i>nullptr</i> is placed into <i>.ptr</i>, and <i>.len</i> has an unspecified value. Otherwise, a pointer to the first byte of the memory sequence is placed into <i>.ptr</i>, with the length of the sequence (<i>num</i>) being placed into <i>.len</i>.</p>
<br />
<p>If <i>algn</i> is zero, the first byte is fundamentally aligned instead (that is, it has the same alignement as that of the standard library type <i>max_align_t</i>).</p>
<br />
<p>The allocated object (pointed to by <i>.ptr</i>) has – by default – no effective type. This can, however, be overwritten through the following means:</p>
<ol>
<li>
<p>If it's written to via <i>memcp</i>, the effective type becomes that of the source object (unless it also doesn't have one);</p>
</li>
<li>
<p>If it's written to via <i>strcp</i> or <i>strfill</i>, the effective type becomes the built-in type <i>char</i>;</p>
</li>
<li>
<p>If it's written to via <i>utf8enc</i> or <i>win1252enc</i>, the effective type becomes <i>chr8</i>;</p>
</li>
<li>
<p>If it's written to via <i>utf8dec</i> or <i>win1252dec</i>, the effective type becomes <i>chr20</i>;</p>
</li>
<li>
<p>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;</p>
</li>
</ol>
<br />
<p>All calls to <i>alloc</i> synchronise with calls to <i>free</i> such that the freed memory may immediatly be reused and so that no race condition occurs.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>num</i> is zero;</p>
</li>
<li>
<p><i>algn</i> isn't a valid alignement (that is, it's never the result of the <i>alignof</i> operator);</p>
</li>
<li>
<p>the returned structure is never passed to <i>free</i>;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_bool-false-true">bool, false, true</p>
<div class="code">
<p>typedef /* see below */ zap_bool;</p>
<p>#define zap_false /* see below */</p>
<p>#define zap_true /* see below */</p>
</div>
<br />
<p>The type <i>bool</i> is an unsigned integral type capable of holding (at least) the values zero and one. The object-like macros <i>false</i> and <i>true</i> expand to expressions of this type, with the evaluated values being zero and an unspecified, greater-than-zero value respectively.</p>
<p>Only values returned by standard functions returning <i>bool</i> are guaranteed to return the values <i>false</i> or <i>true</i>. 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.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_chr10-chr20-chr8">chr10, chr20, chr8</p>
<div class="code">
<p>typedef /* see below */ zap_chr10;</p>
<p>typedef /* see below */ zap_chr20;</p>
<p>typedef /* see below */ zap_chr8;</p>
</div>
<br />
<p>The types <i>chr8</i>, <i>chr10</i>, <i>chr20</i> are unsigned integral types suitable for holding character values (namely of UTF-8, UTF-16, and UTF-32 respectively).</p>
<p>The underlying type of <i>chr8</i> is the built-in type <i>unsigned char</i>. The underlying types of <i>chr10</i> and <i>chr20</i> are the smallest unsigned integral types of at least 16 and 32 bits respectively.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_cmp-eq-gt-lt">cmp, eq, gt, lt</p>
<div class="code">
<p>typedef /* see below */ zap_cmp;</p>
<p>#define zap_eq /* see below */</p>
<p>#define zap_gt /* see below */</p>
<p>#define zap_lt /* see below */</p>
</div>
<br />
<p>A signed integral type capable of storing (at least) negative one, zero, and positive one. The object-like macros <i>eq</i>, <i>gt</i>, and <i>lt</i> evaluate to zero, a greater-than-zero value, and a less-than-zero value (all of this type) respectively.</p>
<p>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.</p>
<p>Only values returned by standard facilities (returning this type) are guaranteed to compare equal to either <i>eq</i>, <i>gt</i>, or <i>lt</i>.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_div">div</p>
<div class="code">
<p>zap_divmod_c zap_div_c(char num,char den);</p>
<p>zap_divmod_i zap_div_i(int num,int den);</p>
<p>zap_divmod_l zap_div_l(long num,long den);</p>
<p>zap_divmod_ll zap_div_ll(long long num,long long den);</p>
<p>zap_divmod_s zap_div_s(short num,short den);</p>
<p>zap_divmod_sc zap_div_sc(signed char num,signed char den);</p>
<p>zap_divmod_uc zap_div_uc(unsigned char num,unsigned char den);</p>
<p>zap_divmod_ui zap_div_ui(unsigned int num,unsigned int den);</p>
<p>zap_divmod_ul zap_div_ul(unsigned long num,unsigned long den);</p>
<p>zap_divmod_ull zap_div_ull(unsigned long long num,unsigned long long den);</p>
<p>zap_divmod_us zap_div_us(unsigned short num,unsigned short den);</p>
</div>
<br />
<p>Returns a structure containing the quotient (result of the operation <code>(num / den)</code>) and the remainder of the division (result of <code>(num % den)</code>) of the numerator <i>num</i> and <i>denominator</i> in the <i>div</i> and <i>mod</i> members respectively.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>den</i> is zero;</p>
</li>
<li>
<p>The operands are signed and the result cannot fit into the destination type;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_divmod">divmod</p>
<div class="code">
<p>typedef struct {char div;char mod;} zap_divmod_c;</p>
<p>typedef struct {int div;int mod;} zap_divmod_i;</p>
<p>typedef struct {long div;long mod;} zap_divmod_l;</p>
<p>typedef struct {long long div;long long mod;} zap_divmod_ll;</p>
<p>typedef struct {short div;short mod;} zap_divmod_s;</p>
<p>typedef struct {signed char div;signed char mod;} zap_divmod_sc;</p>
<p>typedef struct {unsigned char div;unsigned char mod;} zap_divmod_uc;</p>
<p>typedef struct {unsigned int div;unsigned int mod;} zap_divmod_ui;</p>
<p>typedef struct {unsigned long div;unsigned long mod;} zap_divmod_ul;</p>
<p>typedef struct {unsigned long long div;unsigned long long mod;} zap_divmod_ull;</p>
<p>typedef struct {unsigned short div;unsigned short mod;} zap_divmod_us;</p>
</div>
<br />
<p>Has the members <i>div</i> and <i>mod</i> for storing the quotient and the remainder of a division.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_exp">exp</p>
<div class="code">
<p>char zap_exp_c(char bs,char exp);</p>
<p>int zap_exp_i(int bs,int exp);</p>
<p>long zap_exp_l(long bs,long exp);</p>
<p>long long zap_exp_ll(long long bs,long long exp);</p>
<p>short zap_exp_s(short bs,short exp);</p>
<p>signed char zap_exp_sc(signed char bs,signed char exp);</p>
<p>unsigned char zap_exp_uc(unsigned char bs,unsigned char exp);</p>
<p>unsigned int zap_exp_ui(unsigned int bs,unsigned int exp);</p>
<p>unsigned long zap_exp_ul(unsigned long bs,unsigned long exp);</p>
<p>unsigned long long zap_exp_ull(unsigned long long bs,unsigned long long exp);</p>
<p>unsigned short zap_exp_us(unsigned short bs,unsigned short exp);</p>
</div>
<br />
<p>Returns <i>bs</i> raised to the power of <i>exp</i>. 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 <i>exp</i> is zero, one is always returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p>The first operand is signed and the result cannot fit into the destination type;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_frac">frac</p>
<div class="code">
<p>typedef struct {char num;char den;} zap_frac_c;</p>
<p>typedef struct {int num;int den;} zap_frac_i;</p>
<p>typedef struct {long num;long den;} zap_frac_l;</p>
<p>typedef struct {long long num;long long den;} zap_frac_ll;</p>
<p>typedef struct {short num;short den;} zap_frac_s;</p>
<p>typedef struct {signed char num;signed char den;} zap_frac_sc;</p>
<p>typedef struct {unsigned char num;unsigned char den;} zap_frac_uc;</p>
<p>typedef struct {unsigned int num;unsigned int den;} zap_frac_ui;</p>
<p>typedef struct {unsigned long num;unsigned long den;} zap_frac_ul;</p>
<p>typedef struct {unsigned long long num;unsigned long long den;} zap_frac_ull;</p>
<p>typedef struct {unsigned short num;unsigned short den;} zap_frac_us;</p>
</div>
<br />
<p>Has the members <i>num</i> and <i>den</i> for storing the numerator and denominator of a fraction.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_free">free</p>
<div class="code">
<p>void zap_free(zap_mem mem);</p>
</div>
<br />
<p>Frees the memory sequence specified by <i>mem</i>.</p>
<br />
<p>All calls to <i>free</i> synchronise with calls to <i>alloc</i> such that the freed memory may immediatly be reused and so that no race condition occurs.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>mem</i> isn't an unmodified structure previously returned by a successful call to <i>alloc</i> (and which isn't already free);</p>
</li>
<li>
<p><i>mem.len</i> isn't the length of the memory sequence pointed to by <i>mem.ptr</i> (as passed to <i>alloc</i>);</p>
</li>
<li>
<p><i>mem</i> is passed to this function more than once (without being returned by <i>alloc</i> in the meantime);</p>
</li>
<li>
<p>The object pointed to by <i>mem.ptr</i> is accessed after the call to <i>free</i> (and the same memory block hasn't been allocated by <i>alloc</i> in the meantime);</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_log">log</p>
<div class="code">
<p>unsigned char zap_log_uc(unsigned char bs,unsigned char pow);</p>
<p>unsigned int zap_log_ui(unsigned int bs,unsigned int pow);</p>
<p>unsigned long zap_log_ul(unsigned long bs,unsigned long pow);</p>
<p>unsigned long long zap_log_ull(unsigned long long bs,unsigned long long pow);</p>
<p>unsigned short zap_log_us(unsigned short bs,unsigned short pow);</p>
</div>
<br />
<p>Returns the truncated (to the nearest representable value) logarithm base <i>bs</i> of the power <i>pow</i>, unless:</p>
<ul>
<li>
<p><i>bs</i> and <i>num</i> are zero, in which case one is returned;</p>
</li>
<li>
<p><i>bs</i> and <i>num</i> are one, in which case zero is returned;</p>
</li>
</ul>
<p>If multiple of these conditions are met, the first listed outcome is used.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>bs</i> is zero or one;</p>
</li>
<li>
<p><i>num</i> is zero;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_maxval">maxval</p>
<div class="code">
<p>#define zap_maxval_sc /* see below */</p>
<p>#define zap_maxval_c /* see below */</p>
<p>#define zap_maxval_i /* see below */</p>
<p>#define zap_maxval_l /* see below */</p>
<p>#define zap_maxval_ll /* see below */</p>
<p>#define zap_maxval_s /* see below */</p>
<p>#define zap_maxval_sc /* see below */</p>
<p>#define zap_maxval_uc /* see below */</p>
<p>#define zap_maxval_ui /* see below */</p>
<p>#define zap_maxval_ul /* see below */</p>
<p>#define zap_maxval_ull /* see below */</p>
<p>#define zap_maxval_us /* see below */</p>
</div>
<br />
<p>Expands to an expression of the appropriate type evaluating to the type's largest supported value.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_mem">mem</p>
<div class="code">
<p>typedef struct {void * ptr;zap_sz sz} zap_mem;</p>
</div>
<br />
<p>A structure type for holding information about memory blocks returned by <i>alloc</i>. It has the members <i>ptr</i> of the built-in type <i>void *</i> and <i>len</i> of the type <i>sz</i> (in that order).</p>
<p>The type is made a typedef so that usage of 'zap_mem' (without the 'struct' keyword) is correct usage.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memcnt">memcnt</p>
<div class="code">
<p>zap_sz zap_memcnt(void const * ptr,zap_sz sz,zap_sz num,zap_bool (* fn)(void const *));</p>
</div>
<br />
<p>Invokes the function <i>fn</i> <i>num</i>-times with a pointer value that is <i>sz</i> points larger than the previous, starting at <i>ptr</i>. The number of times the function invokation returned <i>true</i> is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>ptr</i> isn't a valid pointer to an array;</p>
</li>
<li>
<p><i>num</i> is larger than the number of elements in the array;</p>
</li>
<li>
<p><i>sz</i> is not the object size of the elements that make up the array;</p>
</li>
<li>
<p><i>fn</i> is not a valid pointer to a function with C-language-linkage;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memcp">memcp</p>
<div class="code">
<p>void zap_memcp(void const * in,zap_sz num,void * out);</p>
</div>
<br />
<p>Copies <i>num</i>-bytes from the buffer pointed to by <i>in</i> into the same relative position in the buffer pointer to by <i>out</i>.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> or <i>out</i> aren't valid pointers to arrays;</p>
</li>
<li>
<p><i>num</i> is larger than the number of bytes in the smallest array;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memeq">memeq</p>
<div class="code">
<p>bool zap_memeq(void const * lptr,zap_sz num,void * rptr);</p>
</div>
<br />
<p>Checks <i>num</i>-bytes of the buffers pointed to by <i>lptr</i> and <i>rptr</i> for equality.</p>
<p>If any two bytes are found to be different in the two buffers, <i>false</i> is returned. Otherwise, <i>true</i> is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>lptr</i> or <i>rptr</i> aren't valid pointers to arrays;</p>
</li>
<li>
<p><i>num</i> is larger than the number of bytes in the smallest array;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memfill">memfill</p>
<div class="code">
<p>void zap_memfill(void const * ptr,zap_sz num,unsigned char byte);</p>
</div>
<br />
<p>Fills <i>num</i>-bytes of the buffer pointed to by <i>ptr</i> with the representation of <i>byte</i>.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>ptr</i> isn't a valid pointer to an array;</p>
</li>
<li>
<p><i>num</i> is larger than the number of bytes of in the array;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memfnd">memfnd</p>
<div class="code">
<p>zap_sz zap_fndbtyte(void const * ptr,zap_sz num,unsigned char byte);</p>
</div>
<br />
<p>Searches for the byte-value <i>byte</i> in the array pointed to by <i>ptr</i> within the bounds of <i>num</i>.</p>
<p>If the byte-value is found within the specified bounds, the position of it's first occurrence (starting at zero) is returned. Otherwise, <i>nopos</i> is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>ptr</i> isn't a valid pointer to an array;</p>
</li>
<li>
<p><i>num</i> is larger than the number of bytes in the array;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memfor">memfor</p>
<div class="code">
<p>void zap_memfor(void * ptr,zap_sz sz,zap_sz num,void (* fn)(void *));</p>
</div>
<br />
<p>Iterates through the array pointed to by <i>ptr</i>, invoking the function <i>fn</i> with a pointer to the current element. Each pointer value after the first is equal to the previous plus <i>sz</i>.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>sz</i> is neither one nor the real object size of each element in the array;</p>
</li>
<li>
<p><i>num</i> is larger than the number of elements in the array;</p>
</li>
<li>
<p><i>fn</i> isn't a valid pointer to a function with C-language-linkage;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_memgen">memgen</p>
<div class="code">
<p>void zap_memgen(void * ptr,zap_sz sz,zap_sz num,void (* fn)(zap_sz,void *));</p>
</div>
<br />
<p>Calls <i>fn</i> for <i>num</i>-elements of size <i>sz</i> in the array pointed to by <i>ptr</i>. The index number of the element (starting at zero) and a pointer to the element are passed to the function.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>ptr</i> isn't a valid pointer to an array;</p>
</li>
<li>
<p><i>sz</i> is neither one nor the real object size of each element in the array;</p>
</li>
<li>
<p><i>num</i> is larger than the number of bytes of in the array;</p>
</li>
<li>
<p><i>fn</i> isn't a valid pointer to a function with C-language-linkage;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_minval">minval</p>
<div class="code">
<p>#define zap_minval_c /* see below */</p>
<p>#define zap_minval_i /* see below */</p>
<p>#define zap_minval_l /* see below */</p>
<p>#define zap_minval_ll /* see below */</p>
<p>#define zap_minval_s /* see below */</p>
<p>#define zap_minval_sc /* see below */</p>
</div>
<br />
<p>Expands to an expression of the appropriate type evaluating to the type's smallest supported value.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_mul">mul</p>
<div class="code">
<p>char zap_mul_c(char lfac,char rfac);</p>
<p>int zap_mul_i(int lfac,int rfac);</p>
<p>long zap_mul_l(long lfac,long rfac);</p>
<p>long long zap_mul_ll(long long lfac,long long rfac);</p>
<p>short zap_mul_s(short lfac,short rfac);</p>
<p>signed char zap_mul_sc(signed char lfac,signed char rfac);</p>
<p>unsigned char zap_mul_uc(unsigned char lfac,unsigned char rfac);</p>
<p>unsigned int zap_mul_ui(unsigned int lfac,unsigned int rfac);</p>
<p>unsigned long zap_mul_ul(unsigned long lfac,unsigned long rfac);</p>
<p>unsigned long long zap_mul_ull(unsigned long long lfac,unsigned long long rfac);</p>
<p>unsigned short zap_mul_us(unsigned short lfac,unsigned short rfac);</p>
</div>
<br />
<p>Returns the result of the expression <code>(lfac * rfac)</code>. If the operands are unsigned, the result is truncated according to unsigned overflow.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p>The operands are signed and the result cannot be represented by the target type;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_nopos">nopos</p>
<div class="code">
<p>#define zap_nopos /* see below */</p>
</div>
<br />
<p>Expands to a value of type <i>sz</i> indicating an invalid position. The value may not be a valid position of any valid array type.</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_nrt">nrt</p>
<div class="code">
<p>char zap_nrt_c(char deg,char rad);</p>
<p>int zap_nrt_i(int deg,int rad);</p>
<p>long zap_nrt_l(long deg,long rad);</p>
<p>long long zap_nrt_ll(long long deg,long long rad);</p>
<p>short zap_nrt_s(short deg,short rad);</p>
<p>signed char zap_nrt_sc(signed char deg,signed char rad);</p>
<p>unsigned char zap_nrt_uc(unsigned char deg,unsigned char rad);</p>
<p>unsigned int zap_nrt_ui(unsigned int deg,unsigned int rad);</p>
<p>unsigned long zap_nrt_ul(unsigned long deg,unsigned long rad);</p>
<p>unsigned long long zap_nrt_ull(unsigned long long deg,unsigned long long rad);</p>
<p>unsigned short zap_nrt_us(unsigned short deg,unsigned short rad);</p>
</div>
<br />
<p>Returns the <i>deg</i>-th root of <i>rad</i>. If the operands are unsigned, the result is truncated according to unsigned overflow.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>deg</i> is zero;</p>
</li>
<li>
<p><i>deg</i> is a positive, even number and <i>rad</i> is negative;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_nullptr">nullptr</p>
<div class="code">
<p>#define zap_nullptr /* see below */</p>
</div>
<br />
<p>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.</p>
<p>If this constant is cast to any pointer type, the value of such conversion will compare equal to the standard library constant <i>NULL</i> cast to the same type.</p>
<br />
<p>The definition may either be a constant expression of the type <i>int</i> with the value zero, the same but cast to the type <i>void *</i> (except in C++), or the <i>nullptr</i> constant (if supported by the language).</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_strcp">strcp</p>
<div class="code">
<p>zap_sz zap_strcp(char const * in,char * out);</p>
</div>
<br />
<p>Copies all characters (including the null-terminator) of the string pointed to by <i>in</i> into the buffer pointed to by <i>out</i>. The length (excluding the null-terminator) of the string is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> isn't a valid pointer to a null-terminated string;</p>
</li>
<li>
<p><i>out</i> isn't a valid pointer to an array, or if the pointed-to array cannot fit the string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_streq">streq</p>
<div class="code">
<p>bool zap_streq(char const * lstr,char const * rstr);</p>
</div>
<br />
<p>Checks the equality of the strings <i>lstr</i> and <i>rstr</i>.</p>
<p>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), <i>true</i> is returned. Otherwise, <i>false</i> is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>lstr</i> or <i>rstr</i> aren't valid pointers to null-terminated strings;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_strfill">strfill</p>
<div class="code">
<p>zap_sz zap_strfill(char * str,char chr);</p>
</div>
<br />
<p>Writes the character <i>chr</i> to every valid position in the string <i>str</i>, excluding that of the null-terminator. The length of the string (excluding the null-terminater) is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>str</i> isn't a valid pointer to a null-terminated string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_strfnd">strfnd</p>
<div class="code">
<p>zap_sz zap_strfnd(char const * str,char chr);</p>
</div>
<br />
<p>Searches for the character <i>chr</i> in the string <i>str</i>. The null-terminator isn't included in the search.</p>
<p>If the character is found within the string, it's index number is returned. Otherwise, <i>nopos</i> is returned.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>str</i> isn't a valid pointer to a null-terminated string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_strlen">strlen</p>
<div class="code">
<p>zap_sz zap_strlen(char const * str);</p>
</div>
<br />
<p>Counts the number of characters in the string <i>str</i>.</p>
<p>Returns the number of characters (excluding the null-terminator) in the string.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>str</i> isn't a valid pointer to a null-terminated string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_sz">sz</p>
<div class="code">
<p>typedef /* see below */ zap_sz;</p>
</div>
<br />
<p>An unsigned integral type capable of holding any valid object size (as returned by <i>sizeof</i>) or alignement (as returned by <i>alignof</i>). It's identical to the standard library type <i>size_t</i>.</p>
<p>It's unspecified if all representable values of this type are valid object sizes or alignements. </p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_utf8dec">utf8dec</p>
<div class="code">
<p>void zap_utf8dec(zap_chr8 const * in,zap_chr20 * out);</p>
</div>
<br />
<p>Decodes the UTF-8-encoded string pointed to by <i>in</i> into UTF-32. The resulting (null-terminated) string is placed into the buffer pointed to by <i>out</i>.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> isn't a valid pointer to a null-terminated, UTF-8-encoded string;</p>
</li>
<li>
<p>The input string contains an invalid octet;</p>
</li>
<li>
<p><i>out</i> isn't a valid pointer to an array, or if the array cannot fit the encoded string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_utf8declen">utf8declen</p>
<div class="code">
<p>zap_sz zap_utf8declen(zap_chr8 const * utf8);</p>
</div>
<br />
<p>Returns the length (excluding the null-terminator) of the UTF-8-encoded string pointed to by <i>utf8</i>, as if it was encoded in UTF-32.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>utf8</i> isn't a valid pointer to a null-terminated, UTF-8-encoded string;</p>
</li>
<li>
<p>The string contains an invalid octet;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_utf8enc">utf8enc</p>
<div class="code">
<p>void zap_utf8enc(zap_chr20 const * in,zap_chr8 * out);</p>
</div>
<br />
<p>Encodes the UTF-32-encoded string pointed to by <i>in</i> into UTF-8. The resulting (null-terminated) string is placed into the buffer pointed to by <i>out</i>.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> isn't a valid pointer to a null-terminated, UTF-32-encoded string;</p>
</li>
<li>
<p>The input string contains an invalid codepoint;</p>
</li>
<li>
<p><i>out</i> isn't a valid pointer to an array, or if the array cannot fit the encoded string;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_utf8enclen">utf8enclen</p>
<div class="code">
<p>zap_sz zap_utf8enclen(zap_chr20 const * utf20);</p>
</div>
<br />
<p>Returns the length (excluding the null-terminator) of the UTF-32-encoded string pointed to by <i>utf20</i>, as if it was encoded in UTF-8.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>utf8</i> isn't a valid pointer to a null-terminated, UTF-32-encoded string;</p>
</li>
<li>
<p>The string contains an invalid codepoint;</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_ver">ver</p>
<div class="code">
<p>#define zap_ver /* see below */</p>
</div>
<br />
<p>Expands to a value (of the built-in type <i>unsigned long</i>) indicating the edition of the supported interface – currently twenty-one (21).</p>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_win1252dec">win1252dec</p>
<div class="code">
<p>void zap_win1252dec(zap_chr8 const * in,zap_chr20 * out);</p>
</div>
<br />
<p>Decodes the null-terminated, Windows-1252-encoded string (pointed to by <i>in</i>) into UTF-32, with the resulting (null-terminated) string being placed into the buffer pointed to by <i>out</i>.</p>
<p>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).</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> isn't a valid pointer to a null-terminated, Windows-1252-encoded string;</p>
</li>
<li>
<p><i>out</i> 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);</p>
</li>
</ul>
</div>
<div class="section">
<p class="sectionTitle" id="symbols_win1252enc">win1252enc</p>
<div class="code">
<p>void zap_win1252enc(zap_chr20 const * in,zap_chr8 * out);</p>
</div>
<br />
<p>Encodes the null-terminated, UTF-32-encoded string (pointed to by <i>in</i>) into Windows-1252, with the resulting (null-terminated) string being placed into the buffer pointed to by <i>out</i>.</p>
<p>If a character in the input doesn't exist in win1252, it's replaced by an unspecified, valid win1252 character.</p>
<br />
<p>The behaviour is undefined if:</p>
<ul>
<li>
<p><i>in</i> isn't a valid pointer to a null-terminated, UTF-20-encoded string;</p>
</li>
<li>
<p><i>out</i> 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);</p>
</li>
</ul>
</div>
</div>
</div>
</body>
</html>
