1ECB(1)                User Contributed Perl Documentation               ECB(1)
2
3
4

LIBECB - e-C-Builtins

6   ABOUT LIBECB
7       Libecb is currently a simple header file that doesn't require any
8       configuration to use or include in your project.
9
10       It's part of the e-suite of libraries, other members of which include
11       libev and libeio.
12
13       Its homepage can be found here:
14
15           http://software.schmorp.de/pkg/libecb
16
17       It mainly provides a number of wrappers around many compiler built-ins,
18       together with replacement functions for other compilers. In addition to
19       this, it provides a number of other lowlevel C utilities, such as
20       endianness detection, byte swapping or bit rotations.
21
22       Or in other words, things that should be built into any standard C
23       system, but aren't, implemented as efficient as possible with GCC
24       (clang, msvc...), and still correct with other compilers.
25
26       More might come.
27
28   ABOUT THE HEADER
29       At the moment, all you have to do is copy ecb.h somewhere where your
30       compiler can find it and include it:
31
32          #include <ecb.h>
33
34       The header should work fine for both C and C++ compilation, and gives
35       you all of inttypes.h in addition to the ECB symbols.
36
37       There are currently no object files to link to - future versions might
38       come with an (optional) object code library to link against, to reduce
39       code size or gain access to additional features.
40
41       It also currently includes everything from inttypes.h.
42
43   ABOUT THIS MANUAL / CONVENTIONS
44       This manual mainly describes each (public) function available after
45       including the ecb.h header. The header might define other symbols than
46       these, but these are not part of the public API, and not supported in
47       any way.
48
49       When the manual mentions a "function" then this could be defined either
50       as as inline function, a macro, or an external symbol.
51
52       When functions use a concrete standard type, such as "int" or
53       "uint32_t", then the corresponding function works only with that type.
54       If only a generic name is used ("expr", "cond", "value" and so on),
55       then the corresponding function relies on C to implement the correct
56       types, and is usually implemented as a macro. Specifically, a "bool" in
57       this manual refers to any kind of boolean value, not a specific type.
58
59   TYPES / TYPE SUPPORT
60       ecb.h makes sure that the following types are defined (in the expected
61       way):
62
63          int8_t       uint8_
64          int16_t      uint16_t
65          int32_t      uint32_
66          int64_t      uint64_t
67          int_fast8_t  uint_fast8_t
68          int_fast16_t uint_fast16_t
69          int_fast32_t uint_fast32_t
70          int_fast64_t uint_fast64_t
71          intptr_t     uintptr_t
72
73       The macro "ECB_PTRSIZE" is defined to the size of a pointer on this
74       platform (currently 4 or 8) and can be used in preprocessor
75       expressions.
76
77       For "ptrdiff_t" and "size_t" use "stddef.h"/"cstddef".
78
79   LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
80       All the following symbols expand to an expression that can be tested in
81       preprocessor instructions as well as treated as a boolean (use "!!" to
82       ensure it's either 0 or 1 if you need that).
83
84       ECB_C
85           True if the implementation defines the "__STDC__" macro to a true
86           value, while not claiming to be C++, i..e C, but not C++.
87
88       ECB_C99
89           True if the implementation claims to be compliant to C99 (ISO/IEC
90           9899:1999) or any later version, while not claiming to be C++.
91
92           Note that later versions (ECB_C11) remove core features again (for
93           example, variable length arrays).
94
95       ECB_C11, ECB_C17
96           True if the implementation claims to be compliant to C11/C17
97           (ISO/IEC 9899:2011, :20187) or any later version, while not
98           claiming to be C++.
99
100       ECB_CPP
101           True if the implementation defines the "__cplusplus__" macro to a
102           true value, which is typically true for C++ compilers.
103
104       ECB_CPP11, ECB_CPP14, ECB_CPP17
105           True if the implementation claims to be compliant to
106           C++11/C++14/C++17 (ISO/IEC 14882:2011, :2014, :2017) or any later
107           version.
108
109           Note that many C++20 features will likely have their own feature
110           test macros (see e.g. <http://eel.is/c++draft/cpp.predefined#1.8>).
111
112       ECB_OPTIMIZE_SIZE
113           Is 1 when the compiler optimizes for size, 0 otherwise. This symbol
114           can also be defined before including ecb.h, in which case it will
115           be unchanged.
116
117       ECB_GCC_VERSION (major, minor)
118           Expands to a true value (suitable for testing by the preprocessor)
119           if the compiler used is GNU C and the version is the given version,
120           or higher.
121
122           This macro tries to return false on compilers that claim to be GCC
123           compatible but aren't.
124
125       ECB_EXTERN_C
126           Expands to "extern "C"" in C++, and a simple "extern" in C.
127
128           This can be used to declare a single external C function:
129
130              ECB_EXTERN_C int printf (const char *format, ...);
131
132       ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
133           These two macros can be used to wrap multiple "extern "C""
134           definitions - they expand to nothing in C.
135
136           They are most useful in header files:
137
138              ECB_EXTERN_C_BEG
139
140              int mycfun1 (int x);
141              int mycfun2 (int x);
142
143              ECB_EXTERN_C_END
144
145       ECB_STDFP
146           If this evaluates to a true value (suitable for testing by the
147           preprocessor), then "float" and "double" use IEEE 754
148           single/binary32 and double/binary64 representations internally and
149           the endianness of both types match the endianness of "uint32_t" and
150           "uint64_t".
151
152           This means you can just copy the bits of a "float" (or "double") to
153           an "uint32_t" (or "uint64_t") and get the raw IEEE 754 bit
154           representation without having to think about format or endianness.
155
156           This is true for basically all modern platforms, although ecb.h
157           might not be able to deduce this correctly everywhere and might err
158           on the safe side.
159
160       ECB_AMD64, ECB_AMD64_X32
161           These two macros are defined to 1 on the x86_64/amd64 ABI and the
162           X32 ABI, respectively, and undefined elsewhere.
163
164           The designers of the new X32 ABI for some inexplicable reason
165           decided to make it look exactly like amd64, even though it's
166           completely incompatible to that ABI, breaking about every piece of
167           software that assumed that "__x86_64" stands for, well, the x86-64
168           ABI, making these macros necessary.
169
170   MACRO TRICKERY
171       ECB_CONCAT (a, b)
172           Expands any macros in "a" and "b", then concatenates the result to
173           form a single token. This is mainly useful to form identifiers from
174           components, e.g.:
175
176              #define S1 str
177              #define S2 cpy
178
179              ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
180
181       ECB_STRINGIFY (arg)
182           Expands any macros in "arg" and returns the stringified version of
183           it. This is mainly useful to get the contents of a macro in string
184           form, e.g.:
185
186              #define SQL_LIMIT 100
187              sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
188
189       ECB_STRINGIFY_EXPR (expr)
190           Like "ECB_STRINGIFY", but additionally evaluates "expr" to make
191           sure it is a valid expression. This is useful to catch typos or
192           cases where the macro isn't available:
193
194              #include <errno.h>
195
196              ECB_STRINGIFY      (EDOM); // "33" (on my system at least)
197              ECB_STRINGIFY_EXPR (EDOM); // "33"
198
199              // now imagine we had a typo:
200
201              ECB_STRINGIFY      (EDAM); // "EDAM"
202              ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
203
204   ATTRIBUTES
205       A major part of libecb deals with additional attributes that can be
206       assigned to functions, variables and sometimes even types - much like
207       "const" or "volatile" in C. They are implemented using either GCC
208       attributes or other compiler/language specific features. Attributes
209       declarations must be put before the whole declaration:
210
211          ecb_const int mysqrt (int a);
212          ecb_unused int i;
213
214       ecb_unused
215           Marks a function or a variable as "unused", which simply suppresses
216           a warning by the compiler when it detects it as unused. This is
217           useful when you e.g. declare a variable but do not always use it:
218
219             {
220               ecb_unused int var;
221
222               #ifdef SOMECONDITION
223                  var = ...;
224                  return var;
225               #else
226                  return 0;
227               #endif
228             }
229
230       ecb_deprecated
231           Similar to "ecb_unused", but marks a function, variable or type as
232           deprecated. This makes some compilers warn when the type is used.
233
234       ecb_deprecated_message (message)
235           Same as "ecb_deprecated", but if possible, the specified diagnostic
236           is used instead of a generic depreciation message when the object
237           is being used.
238
239       ecb_inline
240           Expands either to (a compiler-specific equivalent of) "static
241           inline" or to just "static", if inline isn't supported. It should
242           be used to declare functions that should be inlined, for code size
243           or speed reasons.
244
245           Example: inline this function, it surely will reduce codesize.
246
247              ecb_inline int
248              negmul (int a, int b)
249              {
250                return - (a * b);
251              }
252
253       ecb_noinline
254           Prevents a function from being inlined - it might be optimised
255           away, but not inlined into other functions. This is useful if you
256           know your function is rarely called and large enough for inlining
257           not to be helpful.
258
259       ecb_noreturn
260           Marks a function as "not returning, ever". Some typical functions
261           that don't return are "exit" or "abort" (which really works hard to
262           not return), and now you can make your own:
263
264              ecb_noreturn void
265              my_abort (const char *errline)
266              {
267                puts (errline);
268                abort ();
269              }
270
271           In this case, the compiler would probably be smart enough to deduce
272           it on its own, so this is mainly useful for declarations.
273
274       ecb_restrict
275           Expands to the "restrict" keyword or equivalent on compilers that
276           support them, and to nothing on others. Must be specified on a
277           pointer type or an array index to indicate that the memory doesn't
278           alias with any other restricted pointer in the same scope.
279
280           Example: multiply a vector, and allow the compiler to parallelise
281           the loop, because it knows it doesn't overwrite input values.
282
283              void
284              multiply (ecb_restrict float *src,
285                        ecb_restrict float *dst,
286                        int len, float factor)
287              {
288                int i;
289
290                for (i = 0; i < len; ++i)
291                  dst [i] = src [i] * factor;
292              }
293
294       ecb_const
295           Declares that the function only depends on the values of its
296           arguments, much like a mathematical function. It specifically does
297           not read or write any memory any arguments might point to, global
298           variables, or call any non-const functions. It also must not have
299           any side effects.
300
301           Such a function can be optimised much more aggressively by the
302           compiler - for example, multiple calls with the same arguments can
303           be optimised into a single call, which wouldn't be possible if the
304           compiler would have to expect any side effects.
305
306           It is best suited for functions in the sense of mathematical
307           functions, such as a function returning the square root of its
308           input argument.
309
310           Not suited would be a function that calculates the hash of some
311           memory area you pass in, prints some messages or looks at a global
312           variable to decide on rounding.
313
314           See "ecb_pure" for a slightly less restrictive class of functions.
315
316       ecb_pure
317           Similar to "ecb_const", declares a function that has no side
318           effects. Unlike "ecb_const", the function is allowed to examine
319           global variables and any other memory areas (such as the ones
320           passed to it via pointers).
321
322           While these functions cannot be optimised as aggressively as
323           "ecb_const" functions, they can still be optimised away in many
324           occasions, and the compiler has more freedom in moving calls to
325           them around.
326
327           Typical examples for such functions would be "strlen" or "memcmp".
328           A function that calculates the MD5 sum of some input and updates
329           some MD5 state passed as argument would NOT be pure, however, as it
330           would modify some memory area that is not the return value.
331
332       ecb_hot
333           This declares a function as "hot" with regards to the cache - the
334           function is used so often, that it is very beneficial to keep it in
335           the cache if possible.
336
337           The compiler reacts by trying to place hot functions near to each
338           other in memory.
339
340           Whether a function is hot or not often depends on the whole
341           program, and less on the function itself. "ecb_cold" is likely more
342           useful in practise.
343
344       ecb_cold
345           The opposite of "ecb_hot" - declares a function as "cold" with
346           regards to the cache, or in other words, this function is not
347           called often, or not at speed-critical times, and keeping it in the
348           cache might be a waste of said cache.
349
350           In addition to placing cold functions together (or at least away
351           from hot functions), this knowledge can be used in other ways, for
352           example, the function will be optimised for size, as opposed to
353           speed, and codepaths leading to calls to those functions can
354           automatically be marked as if "ecb_expect_false" had been used to
355           reach them.
356
357           Good examples for such functions would be error reporting
358           functions, or functions only called in exceptional or rare cases.
359
360       ecb_artificial
361           Declares the function as "artificial", in this case meaning that
362           this function is not really meant to be a function, but more like
363           an accessor - many methods in C++ classes are mere accessor
364           functions, and having a crash reported in such a method, or single-
365           stepping through them, is not usually so helpful, especially when
366           it's inlined to just a few instructions.
367
368           Marking them as artificial will instruct the debugger about just
369           this, leading to happier debugging and thus happier lives.
370
371           Example: in some kind of smart-pointer class, mark the pointer
372           accessor as artificial, so that the whole class acts more like a
373           pointer and less like some C++ abstraction monster.
374
375             template<typename T>
376             struct my_smart_ptr
377             {
378               T *value;
379
380               ecb_artificial
381               operator T *()
382               {
383                 return value;
384               }
385             };
386
387   OPTIMISATION HINTS
388       bool ecb_is_constant (expr)
389           Returns true iff the expression can be deduced to be a compile-time
390           constant, and false otherwise.
391
392           For example, when you have a "rndm16" function that returns a 16
393           bit random number, and you have a function that maps this to a
394           range from 0..n-1, then you could use this inline function in a
395           header file:
396
397             ecb_inline uint32_t
398             rndm (uint32_t n)
399             {
400               return (n * (uint32_t)rndm16 ()) >> 16;
401             }
402
403           However, for powers of two, you could use a normal mask, but that
404           is only worth it if, at compile time, you can detect this case.
405           This is the case when the passed number is a constant and also a
406           power of two ("n & (n - 1) == 0"):
407
408             ecb_inline uint32_t
409             rndm (uint32_t n)
410             {
411               return is_constant (n) && !(n & (n - 1))
412                 ? rndm16 () & (num - 1)
413                 : (n * (uint32_t)rndm16 ()) >> 16;
414             }
415
416       ecb_expect (expr, value)
417           Evaluates "expr" and returns it. In addition, it tells the compiler
418           that the "expr" evaluates to "value" a lot, which can be used for
419           static branch optimisations.
420
421           Usually, you want to use the more intuitive "ecb_expect_true" and
422           "ecb_expect_false" functions instead.
423
424       bool ecb_expect_true (cond)
425       bool ecb_expect_false (cond)
426           These two functions expect a expression that is true or false and
427           return 1 or 0, respectively, so when used in the condition of an
428           "if" or other conditional statement, it will not change the
429           program:
430
431             /* these two do the same thing */
432             if (some_condition) ...;
433             if (ecb_expect_true (some_condition)) ...;
434
435           However, by using "ecb_expect_true", you tell the compiler that the
436           condition is likely to be true (and for "ecb_expect_false", that it
437           is unlikely to be true).
438
439           For example, when you check for a null pointer and expect this to
440           be a rare, exceptional, case, then use "ecb_expect_false":
441
442             void my_free (void *ptr)
443             {
444               if (ecb_expect_false (ptr == 0))
445                 return;
446             }
447
448           Consequent use of these functions to mark away exceptional cases or
449           to tell the compiler what the hot path through a function is can
450           increase performance considerably.
451
452           You might know these functions under the name "likely" and
453           "unlikely" - while these are common aliases, we find that the
454           expect name is easier to understand when quickly skimming code. If
455           you wish, you can use "ecb_likely" instead of "ecb_expect_true" and
456           "ecb_unlikely" instead of "ecb_expect_false" - these are simply
457           aliases.
458
459           A very good example is in a function that reserves more space for
460           some memory block (for example, inside an implementation of a
461           string stream) - each time something is added, you have to check
462           for a buffer overrun, but you expect that most checks will turn out
463           to be false:
464
465             /* make sure we have "size" extra room in our buffer */
466             ecb_inline void
467             reserve (int size)
468             {
469               if (ecb_expect_false (current + size > end))
470                 real_reserve_method (size); /* presumably noinline */
471             }
472
473       ecb_assume (cond)
474           Tries to tell the compiler that some condition is true, even if
475           it's not obvious. This is not a function, but a statement: it
476           cannot be used in another expression.
477
478           This can be used to teach the compiler about invariants or other
479           conditions that might improve code generation, but which are
480           impossible to deduce form the code itself.
481
482           For example, the example reservation function from the
483           "ecb_expect_false" description could be written thus (only
484           "ecb_assume" was added):
485
486             ecb_inline void
487             reserve (int size)
488             {
489               if (ecb_expect_false (current + size > end))
490                 real_reserve_method (size); /* presumably noinline */
491
492               ecb_assume (current + size <= end);
493             }
494
495           If you then call this function twice, like this:
496
497             reserve (10);
498             reserve (1);
499
500           Then the compiler might be able to optimise out the second call
501           completely, as it knows that "current + 1 > end" is false and the
502           call will never be executed.
503
504       ecb_unreachable ()
505           This function does nothing itself, except tell the compiler that it
506           will never be executed. Apart from suppressing a warning in some
507           cases, this function can be used to implement "ecb_assume" or
508           similar functionality.
509
510       ecb_prefetch (addr, rw, locality)
511           Tells the compiler to try to prefetch memory at the given "addr"ess
512           for either reading ("rw" = 0) or writing ("rw" = 1). A "locality"
513           of 0 means that there will only be one access later, 3 means that
514           the data will likely be accessed very often, and values in between
515           mean something... in between. The memory pointed to by the address
516           does not need to be accessible (it could be a null pointer for
517           example), but "rw" and "locality" must be compile-time constants.
518
519           This is a statement, not a function: you cannot use it as part of
520           an expression.
521
522           An obvious way to use this is to prefetch some data far away, in a
523           big array you loop over. This prefetches memory some 128 array
524           elements later, in the hope that it will be ready when the CPU
525           arrives at that location.
526
527             int sum = 0;
528
529             for (i = 0; i < N; ++i)
530               {
531                 sum += arr [i]
532                 ecb_prefetch (arr + i + 128, 0, 0);
533               }
534
535           It's hard to predict how far to prefetch, and most CPUs that can
536           prefetch are often good enough to predict this kind of behaviour
537           themselves. It gets more interesting with linked lists, especially
538           when you do some fair processing on each list element:
539
540             for (node *n = start; n; n = n->next)
541               {
542                 ecb_prefetch (n->next, 0, 0);
543                 ... do medium amount of work with *n
544               }
545
546           After processing the node, (part of) the next node might already be
547           in cache.
548
549   BIT FIDDLING / BIT WIZARDRY
550       bool ecb_big_endian ()
551       bool ecb_little_endian ()
552           These two functions return true if the byte order is big endian
553           (most-significant byte first) or little endian (least-significant
554           byte first) respectively.
555
556           On systems that are neither, their return values are unspecified.
557
558       int ecb_ctz32 (uint32_t x)
559       int ecb_ctz64 (uint64_t x)
560       int ecb_ctz (T x) [C++]
561           Returns the index of the least significant bit set in "x" (or
562           equivalently the number of bits set to 0 before the least
563           significant bit set), starting from 0. If "x" is 0 the result is
564           undefined.
565
566           For smaller types than "uint32_t" you can safely use "ecb_ctz32".
567
568           The overloaded C++ "ecb_ctz" function supports "uint8_t",
569           "uint16_t", "uint32_t" and "uint64_t" types.
570
571           For example:
572
573             ecb_ctz32 (3) = 0
574             ecb_ctz32 (6) = 1
575
576       bool ecb_is_pot32 (uint32_t x)
577       bool ecb_is_pot64 (uint32_t x)
578       bool ecb_is_pot (T x) [C++]
579           Returns true iff "x" is a power of two or "x == 0".
580
581           For smaller types than "uint32_t" you can safely use
582           "ecb_is_pot32".
583
584           The overloaded C++ "ecb_is_pot" function supports "uint8_t",
585           "uint16_t", "uint32_t" and "uint64_t" types.
586
587       int ecb_ld32 (uint32_t x)
588       int ecb_ld64 (uint64_t x)
589       int ecb_ld64 (T x) [C++]
590           Returns the index of the most significant bit set in "x", or the
591           number of digits the number requires in binary (so that "2**ld <= x
592           < 2**(ld+1)"). If "x" is 0 the result is undefined. A common use
593           case is to compute the integer binary logarithm, i.e. "floor (log2
594           (n))", for example to see how many bits a certain number requires
595           to be encoded.
596
597           This function is similar to the "count leading zero bits" function,
598           except that that one returns how many zero bits are "in front" of
599           the number (in the given data type), while "ecb_ld" returns how
600           many bits the number itself requires.
601
602           For smaller types than "uint32_t" you can safely use "ecb_ld32".
603
604           The overloaded C++ "ecb_ld" function supports "uint8_t",
605           "uint16_t", "uint32_t" and "uint64_t" types.
606
607       int ecb_popcount32 (uint32_t x)
608       int ecb_popcount64 (uint64_t x)
609       int ecb_popcount (T x) [C++]
610           Returns the number of bits set to 1 in "x".
611
612           For smaller types than "uint32_t" you can safely use
613           "ecb_popcount32".
614
615           The overloaded C++ "ecb_popcount" function supports "uint8_t",
616           "uint16_t", "uint32_t" and "uint64_t" types.
617
618           For example:
619
620             ecb_popcount32 (7) = 3
621             ecb_popcount32 (255) = 8
622
623       uint8_t  ecb_bitrev8  (uint8_t  x)
624       uint16_t ecb_bitrev16 (uint16_t x)
625       uint32_t ecb_bitrev32 (uint32_t x)
626       T ecb_bitrev (T x) [C++]
627           Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes
628           LSB+1 and so on.
629
630           The overloaded C++ "ecb_bitrev" function supports "uint8_t",
631           "uint16_t" and "uint32_t" types.
632
633           Example:
634
635              ecb_bitrev8 (0xa7) = 0xea
636              ecb_bitrev32 (0xffcc4411) = 0x882233ff
637
638       T ecb_bitrev (T x) [C++]
639           Overloaded C++ bitrev function.
640
641           "T" must be one of "uint8_t", "uint16_t" or "uint32_t".
642
643       uint32_t ecb_bswap16 (uint32_t x)
644       uint32_t ecb_bswap32 (uint32_t x)
645       uint64_t ecb_bswap64 (uint64_t x)
646       T ecb_bswap (T x)
647           These functions return the value of the 16-bit (32-bit, 64-bit)
648           value "x" after reversing the order of bytes (0x11223344 becomes
649           0x44332211 in "ecb_bswap32").
650
651           The overloaded C++ "ecb_bswap" function supports "uint8_t",
652           "uint16_t", "uint32_t" and "uint64_t" types.
653
654       uint8_t  ecb_rotl8  (uint8_t  x, unsigned int count)
655       uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
656       uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
657       uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
658       uint8_t  ecb_rotr8  (uint8_t  x, unsigned int count)
659       uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
660       uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
661       uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
662           These two families of functions return the value of "x" after
663           rotating all the bits by "count" positions to the right
664           ("ecb_rotr") or left ("ecb_rotl").
665
666           Current GCC/clang versions understand these functions and usually
667           compile them to "optimal" code (e.g. a single "rol" or a
668           combination of "shld" on x86).
669
670       T ecb_rotl (T x, unsigned int count) [C++]
671       T ecb_rotr (T x, unsigned int count) [C++]
672           Overloaded C++ rotl/rotr functions.
673
674           "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
675
676   HOST ENDIANNESS CONVERSION
677       uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
678       uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
679       uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
680       uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
681       uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
682       uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
683           Convert an unsigned 16, 32 or 64 bit value from big or little
684           endian to host byte order.
685
686           The naming convention is "ecb_"("be"|"le")"_u""16|32|64""_to_host",
687           where "be" and "le" stand for big endian and little endian,
688           respectively.
689
690       uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
691       uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
692       uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
693       uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
694       uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
695       uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
696           Like above, but converts from host byte order to the specified
697           endianness.
698
699       In C++ the following additional template functions are supported:
700
701       T ecb_be_to_host (T v)
702       T ecb_le_to_host (T v)
703       T ecb_host_to_be (T v)
704       T ecb_host_to_le (T v)
705
706       These functions work like their C counterparts, above, but use
707       templates, which make them useful in generic code.
708
709       "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t" (so
710       unlike their C counterparts, there is a version for "uint8_t", which
711       again can be useful in generic code).
712
713   UNALIGNED LOAD/STORE
714       These function load or store unaligned multi-byte values.
715
716       uint_fast16_t ecb_peek_u16_u (const void *ptr)
717       uint_fast32_t ecb_peek_u32_u (const void *ptr)
718       uint_fast64_t ecb_peek_u64_u (const void *ptr)
719           These functions load an unaligned, unsigned 16, 32 or 64 bit value
720           from memory.
721
722       uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
723       uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
724       uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
725       uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
726       uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
727       uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
728           Like above, but additionally convert from big endian ("be") or
729           little endian ("le") byte order to host byte order while doing so.
730
731       ecb_poke_u16_u (void *ptr, uint16_t v)
732       ecb_poke_u32_u (void *ptr, uint32_t v)
733       ecb_poke_u64_u (void *ptr, uint64_t v)
734           These functions store an unaligned, unsigned 16, 32 or 64 bit value
735           to memory.
736
737       ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
738       ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
739       ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
740       ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
741       ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
742       ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
743           Like above, but additionally convert from host byte order to big
744           endian ("be") or little endian ("le") byte order while doing so.
745
746       In C++ the following additional template functions are supported:
747
748       T ecb_peek<T>      (const void *ptr)
749       T ecb_peek_be<T>   (const void *ptr)
750       T ecb_peek_le<T>   (const void *ptr)
751       T ecb_peek_u<T>    (const void *ptr)
752       T ecb_peek_be_u<T> (const void *ptr)
753       T ecb_peek_le_u<T> (const void *ptr)
754           Similarly to their C counterparts, these functions load an unsigned
755           8, 16, 32 or 64 bit value from memory, with optional conversion
756           from big/little endian.
757
758           Since the type cannot be deduced, it has to be specified
759           explicitly, e.g.
760
761              uint_fast16_t v = ecb_peek<uint16_t> (ptr);
762
763           "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
764
765           Unlike their C counterparts, these functions support 8 bit
766           quantities ("uint8_t") and also have an aligned version (without
767           the "_u" prefix), all of which hopefully makes them more useful in
768           generic code.
769
770       ecb_poke      (void *ptr, T v)
771       ecb_poke_be   (void *ptr, T v)
772       ecb_poke_le   (void *ptr, T v)
773       ecb_poke_u    (void *ptr, T v)
774       ecb_poke_be_u (void *ptr, T v)
775       ecb_poke_le_u (void *ptr, T v)
776           Again, similarly to their C counterparts, these functions store an
777           unsigned 8, 16, 32 or z64 bit value to memory, with optional
778           conversion to big/little endian.
779
780           "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
781
782           Unlike their C counterparts, these functions support 8 bit
783           quantities ("uint8_t") and also have an aligned version (without
784           the "_u" prefix), all of which hopefully makes them more useful in
785           generic code.
786
787   FLOATING POINT FIDDLING
788       ECB_INFINITY [-UECB_NO_LIBM]
789           Evaluates to positive infinity if supported by the platform,
790           otherwise to a truly huge number.
791
792       ECB_NAN [-UECB_NO_LIBM]
793           Evaluates to a quiet NAN if supported by the platform, otherwise to
794           "ECB_INFINITY".
795
796       float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
797           Same as "ldexpf", but always available.
798
799       uint32_t ecb_float_to_binary16  (float  x) [-UECB_NO_LIBM]
800       uint32_t ecb_float_to_binary32  (float  x) [-UECB_NO_LIBM]
801       uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
802           These functions each take an argument in the native "float" or
803           "double" type and return the IEEE 754 bit representation of it
804           (binary16/half, binary32/single or binary64/double precision).
805
806           The bit representation is just as IEEE 754 defines it, i.e. the
807           sign bit will be the most significant bit, followed by exponent and
808           mantissa.
809
810           This function should work even when the native floating point
811           format isn't IEEE compliant, of course at a speed and code size
812           penalty, and of course also within reasonable limits (it tries to
813           convert NaNs, infinities and denormals, but will likely convert
814           negative zero to positive zero).
815
816           On all modern platforms (where "ECB_STDFP" is true), the compiler
817           should be able to optimise away this function completely.
818
819           These functions can be helpful when serialising floats to the
820           network - you can serialise the return value like a normal
821           uint16_t/uint32_t/uint64_t.
822
823           Another use for these functions is to manipulate floating point
824           values directly.
825
826           Silly example: toggle the sign bit of a float.
827
828              /* On gcc-4.7 on amd64, */
829              /* this results in a single add instruction to toggle the bit, and 4 extra */
830              /* instructions to move the float value to an integer register and back. */
831
832              x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
833
834       float  ecb_binary16_to_float  (uint16_t x) [-UECB_NO_LIBM]
835       float  ecb_binary32_to_float  (uint32_t x) [-UECB_NO_LIBM]
836       double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
837           The reverse operation of the previous function - takes the bit
838           representation of an IEEE binary16, binary32 or binary64 number
839           (half, single or double precision) and converts it to the native
840           "float" or "double" format.
841
842           This function should work even when the native floating point
843           format isn't IEEE compliant, of course at a speed and code size
844           penalty, and of course also within reasonable limits (it tries to
845           convert normals and denormals, and might be lucky for infinities,
846           and with extraordinary luck, also for negative zero).
847
848           On all modern platforms (where "ECB_STDFP" is true), the compiler
849           should be able to optimise away this function completely.
850
851       uint16_t ecb_binary32_to_binary16 (uint32_t x)
852       uint32_t ecb_binary16_to_binary32 (uint16_t x)
853           Convert a IEEE binary32/single precision to binary16/half format,
854           and vice versa, handling all details (round-to-nearest-even,
855           subnormals, infinity and NaNs) correctly.
856
857           These are functions are available under "-DECB_NO_LIBM", since they
858           do not rely on the platform floating point format. The
859           "ecb_float_to_binary16" and "ecb_binary16_to_float" functions are
860           usually what you want.
861
862   ARITHMETIC
863       x = ecb_mod (m, n)
864           Returns "m" modulo "n", which is the same as the positive remainder
865           of the division operation between "m" and "n", using floored
866           division. Unlike the C remainder operator "%", this function
867           ensures that the return value is always positive and that the two
868           numbers m and m' = m + i * n result in the same value modulo n - in
869           other words, "ecb_mod" implements the mathematical modulo
870           operation, which is missing in the language.
871
872           "n" must be strictly positive (i.e. ">= 1"), while "m" must be
873           negatable, that is, both "m" and "-m" must be representable in its
874           type (this typically excludes the minimum signed integer value, the
875           same limitation as for "/" and "%" in C).
876
877           Current GCC/clang versions compile this into an efficient
878           branchless sequence on almost all CPUs.
879
880           For example, when you want to rotate forward through the members of
881           an array for increasing "m" (which might be negative), then you
882           should use "ecb_mod", as the "%" operator might give either
883           negative results, or change direction for negative values:
884
885              for (m = -100; m <= 100; ++m)
886                int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
887
888       x = ecb_div_rd (val, div)
889       x = ecb_div_ru (val, div)
890           Returns "val" divided by "div" rounded down or up, respectively.
891           "val" and "div" must have integer types and "div" must be strictly
892           positive. Note that these functions are implemented with macros in
893           C and with function templates in C++.
894
895   UTILITY
896       element_count = ecb_array_length (name)
897           Returns the number of elements in the array "name". For example:
898
899             int primes[] = { 2, 3, 5, 7, 11 };
900             int sum = 0;
901
902             for (i = 0; i < ecb_array_length (primes); i++)
903               sum += primes [i];
904
905   SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
906       These symbols need to be defined before including ecb.h the first time.
907
908       ECB_NO_THREADS
909           If ecb.h is never used from multiple threads, then this symbol can
910           be defined, in which case memory fences (and similar constructs)
911           are completely removed, leading to more efficient code and fewer
912           dependencies.
913
914           Setting this symbol to a true value implies "ECB_NO_SMP".
915
916       ECB_NO_SMP
917           The weaker version of "ECB_NO_THREADS" - if ecb.h is used from
918           multiple threads, but never concurrently (e.g. if the system the
919           program runs on has only a single CPU with a single core, no
920           hyperthreading and so on), then this symbol can be defined, leading
921           to more efficient code and fewer dependencies.
922
923       ECB_NO_LIBM
924           When defined to 1, do not export any functions that might introduce
925           dependencies on the math library (usually called -lm) - these are
926           marked with [-UECB_NO_LIBM].
927

UNDOCUMENTED FUNCTIONALITY

929       ecb.h is full of undocumented functionality as well, some of which is
930       intended to be internal-use only, some of which we forgot to document,
931       and some of which we hide because we are not sure we will keep the
932       interface stable.
933
934       While you are welcome to rummage around and use whatever you find
935       useful (we can't stop you), keep in mind that we will change
936       undocumented functionality in incompatible ways without thinking twice,
937       while we are considerably more conservative with documented things.
938

AUTHORS

940       "libecb" is designed and maintained by:
941
942          Emanuele Giaquinta <e.giaquinta@glauco.it>
943          Marc Alexander Lehmann <schmorp@schmorp.de>
944
945
946
947perl v5.32.0                      2020-07-28                            ECB(1)
Impressum