1ECB(1) User Contributed Perl Documentation ECB(1)
2
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 It's part of the e-suite of libraries, other members of which include
11 libev and libeio.
12 Its homepage can be found here:
14 http://software.schmorp.de/pkg/libecb
16 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 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 More might come.
27 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 #include <ecb.h>
33 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 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 It also currently includes everything from inttypes.h.
42 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 When the manual mentions a "function" then this could be defined either
50 as as inline function, a macro, or an external symbol.
51 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 TYPES / TYPE SUPPORT
60 ecb.h makes sure that the following types are defined (in the expected
61 way):
62 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 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 For "ptrdiff_t" and "size_t" use "stddef.h"/"cstddef".
78 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 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 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 Note that later versions (ECB_C11) remove core features again (for
93 example, variable length arrays).
94 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 ECB_CPP
101 True if the implementation defines the "__cplusplus__" macro to a
102 true value, which is typically true for C++ compilers.
103 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 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 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 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 This macro tries to return false on compilers that claim to be GCC
123 compatible but aren't.
124 ECB_EXTERN_C
126 Expands to "extern "C"" in C++, and a simple "extern" in C.
127 This can be used to declare a single external C function:
129 ECB_EXTERN_C int printf (const char *format, ...);
131 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 They are most useful in header files:
137 ECB_EXTERN_C_BEG
139 int mycfun1 (int x);
141 int mycfun2 (int x);
142 ECB_EXTERN_C_END
144 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 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 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 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 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 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 #define S1 str
177 #define S2 cpy
178 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
180 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 #define SQL_LIMIT 100
187 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
188 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 #include <errno.h>
195 ECB_STRINGIFY (EDOM); // "33" (on my system at least)
197 ECB_STRINGIFY_EXPR (EDOM); // "33"
198 // now imagine we had a typo:
200 ECB_STRINGIFY (EDAM); // "EDAM"
202 ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
203 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 ecb_const int mysqrt (int a);
212 ecb_unused int i;
213 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 {
220 ecb_unused int var;
221 #ifdef SOMECONDITION
223 var = ...;
224 return var;
225 #else
226 return 0;
227 #endif
228 }
229 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 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 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 Example: inline this function, it surely will reduce codesize.
246 ecb_inline int
248 negmul (int a, int b)
249 {
250 return - (a * b);
251 }
252 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 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 ecb_noreturn void
265 my_abort (const char *errline)
266 {
267 puts (errline);
268 abort ();
269 }
270 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 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 Example: multiply a vector, and allow the compiler to parallelise
281 the loop, because it knows it doesn't overwrite input values.
282 void
284 multiply (ecb_restrict float *src,
285 ecb_restrict float *dst,
286 int len, float factor)
287 {
288 int i;
289 for (i = 0; i < len; ++i)
291 dst [i] = src [i] * factor;
292 }
293 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 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 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 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 See "ecb_pure" for a slightly less restrictive class of functions.
315 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 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 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 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 The compiler reacts by trying to place hot functions near to each
338 other in memory.
339 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 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 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 Good examples for such functions would be error reporting
358 functions, or functions only called in exceptional or rare cases.
359 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 Marking them as artificial will instruct the debugger about just
369 this, leading to happier debugging and thus happier lives.
370 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 template<typename T>
376 struct my_smart_ptr
377 {
378 T *value;
379 ecb_artificial
381 operator T *()
382 {
383 return value;
384 }
385 };
386 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 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 ecb_inline uint32_t
398 rndm (uint32_t n)
399 {
400 return (n * (uint32_t)rndm16 ()) >> 16;
401 }
402 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 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 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 Usually, you want to use the more intuitive "ecb_expect_true" and
422 "ecb_expect_false" functions instead.
423 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 /* these two do the same thing */
432 if (some_condition) ...;
433 if (ecb_expect_true (some_condition)) ...;
434 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 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 void my_free (void *ptr)
443 {
444 if (ecb_expect_false (ptr == 0))
445 return;
446 }
447 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 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 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 /* 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 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 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 For example, the example reservation function from the
483 "ecb_expect_false" description could be written thus (only
484 "ecb_assume" was added):
485 ecb_inline void
487 reserve (int size)
488 {
489 if (ecb_expect_false (current + size > end))
490 real_reserve_method (size); /* presumably noinline */
491 ecb_assume (current + size <= end);
493 }
494 If you then call this function twice, like this:
496 reserve (10);
498 reserve (1);
499 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 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 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 This is a statement, not a function: you cannot use it as part of
520 an expression.
521 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 int sum = 0;
528 for (i = 0; i < N; ++i)
530 {
531 sum += arr [i]
532 ecb_prefetch (arr + i + 128, 0, 0);
533 }
534 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 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 After processing the node, (part of) the next node might already be
547 in cache.
548 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 On systems that are neither, their return values are unspecified.
557 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 For smaller types than "uint32_t" you can safely use "ecb_ctz32".
567 The overloaded C++ "ecb_ctz" function supports "uint8_t",
569 "uint16_t", "uint32_t" and "uint64_t" types.
570 For example:
572 ecb_ctz32 (3) = 0
574 ecb_ctz32 (6) = 1
575 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 For smaller types than "uint32_t" you can safely use
582 "ecb_is_pot32".
583 The overloaded C++ "ecb_is_pot" function supports "uint8_t",
585 "uint16_t", "uint32_t" and "uint64_t" types.
586 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 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 For smaller types than "uint32_t" you can safely use "ecb_ld32".
603 The overloaded C++ "ecb_ld" function supports "uint8_t",
605 "uint16_t", "uint32_t" and "uint64_t" types.
606 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 For smaller types than "uint32_t" you can safely use
613 "ecb_popcount32".
614 The overloaded C++ "ecb_popcount" function supports "uint8_t",
616 "uint16_t", "uint32_t" and "uint64_t" types.
617 For example:
619 ecb_popcount32 (7) = 3
621 ecb_popcount32 (255) = 8
622 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 The overloaded C++ "ecb_bitrev" function supports "uint8_t",
631 "uint16_t" and "uint32_t" types.
632 Example:
634 ecb_bitrev8 (0xa7) = 0xea
636 ecb_bitrev32 (0xffcc4411) = 0x882233ff
637 T ecb_bitrev (T x) [C++]
639 Overloaded C++ bitrev function.
640 "T" must be one of "uint8_t", "uint16_t" or "uint32_t".
642 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 The overloaded C++ "ecb_bswap" function supports "uint8_t",
652 "uint16_t", "uint32_t" and "uint64_t" types.
653 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 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 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 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
675 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 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 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 In C++ the following additional template functions are supported:
700 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 These functions work like their C counterparts, above, but use
707 templates, which make them useful in generic code.
708 "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 UNALIGNED LOAD/STORE
714 These function load or store unaligned multi-byte values.
715 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 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 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 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 In C++ the following additional template functions are supported:
747 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 Since the type cannot be deduced, it has to be specified
759 explicitly, e.g.
760 uint_fast16_t v = ecb_peek<uint16_t> (ptr);
762 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
764 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 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 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
781 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 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 ECB_NAN [-UECB_NO_LIBM]
793 Evaluates to a quiet NAN if supported by the platform, otherwise to
794 "ECB_INFINITY".
795 float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
797 Same as "ldexpf", but always available.
798 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 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 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 On all modern platforms (where "ECB_STDFP" is true), the compiler
817 should be able to optimise away this function completely.
818 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 Another use for these functions is to manipulate floating point
824 values directly.
825 Silly example: toggle the sign bit of a float.
827 /* 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 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
833 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 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 On all modern platforms (where "ECB_STDFP" is true), the compiler
849 should be able to optimise away this function completely.
850 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 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 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 "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 Current GCC/clang versions compile this into an efficient
878 branchless sequence on almost all CPUs.
879 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 for (m = -100; m <= 100; ++m)
886 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
887 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 UTILITY
896 element_count = ecb_array_length (name)
897 Returns the number of elements in the array "name". For example:
898 int primes[] = { 2, 3, 5, 7, 11 };
900 int sum = 0;
901 for (i = 0; i < ecb_array_length (primes); i++)
903 sum += primes [i];
904 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
906 These symbols need to be defined before including ecb.h the first time.
907 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 Setting this symbol to a true value implies "ECB_NO_SMP".
915 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 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
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 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
940 "libecb" is designed and maintained by:
941 Emanuele Giaquinta <e.giaquinta@glauco.it>
943 Marc Alexander Lehmann <schmorp@schmorp.de>
944perl v5.32.1 2021-01-26 ECB(1)