1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
|
<!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</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 /* see below */ 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>
|
