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

UNDOCUMENTED FUNCTIONALITY

769       ecb.h is full of undocumented functionality as well, some of which is
770       intended to be internal-use only, some of which we forgot to document,
771       and some of which we hide because we are not sure we will keep the
772       interface stable.
773
774       While you are welcome to rummage around and use whatever you find
775       useful (we can't stop you), keep in mind that we will change
776       undocumented functionality in incompatible ways without thinking twice,
777       while we are considerably more conservative with documented things.
778

AUTHORS

780       "libecb" is designed and maintained by:
781
782          Emanuele Giaquinta <e.giaquinta@glauco.it>
783          Marc Alexander Lehmann <schmorp@schmorp.de>
784
785
786
787perl v5.30.1                      2020-01-29                            ECB(1)
Impressum