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 low-level 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_64BIT_NATIVE
161 Evaluates to a true value (suitable for both preprocessor and C
162 code testing) if 64 bit integer types on this architecture are
163 evaluated "natively", that is, with similar speeds as 32 bit
164 integers. While 64 bit integer support is very common (and in fact
165 required by libecb), 32 bit CPUs have to emulate operations on
166 them, so you might want to avoid them.
167 ECB_AMD64, ECB_AMD64_X32
169 These two macros are defined to 1 on the x86_64/amd64 ABI and the
170 X32 ABI, respectively, and undefined elsewhere.
171 The designers of the new X32 ABI for some inexplicable reason
173 decided to make it look exactly like amd64, even though it's
174 completely incompatible to that ABI, breaking about every piece of
175 software that assumed that "__x86_64" stands for, well, the x86-64
176 ABI, making these macros necessary.
177 MACRO TRICKERY
179 ECB_CONCAT (a, b)
180 Expands any macros in "a" and "b", then concatenates the result to
181 form a single token. This is mainly useful to form identifiers from
182 components, e.g.:
183 #define S1 str
185 #define S2 cpy
186 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
188 ECB_STRINGIFY (arg)
190 Expands any macros in "arg" and returns the stringified version of
191 it. This is mainly useful to get the contents of a macro in string
192 form, e.g.:
193 #define SQL_LIMIT 100
195 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
196 ECB_STRINGIFY_EXPR (expr)
198 Like "ECB_STRINGIFY", but additionally evaluates "expr" to make
199 sure it is a valid expression. This is useful to catch typos or
200 cases where the macro isn't available:
201 #include <errno.h>
203 ECB_STRINGIFY (EDOM); // "33" (on my system at least)
205 ECB_STRINGIFY_EXPR (EDOM); // "33"
206 // now imagine we had a typo:
208 ECB_STRINGIFY (EDAM); // "EDAM"
210 ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
211 ATTRIBUTES
213 A major part of libecb deals with additional attributes that can be
214 assigned to functions, variables and sometimes even types - much like
215 "const" or "volatile" in C. They are implemented using either GCC
216 attributes or other compiler/language specific features. Attributes
217 declarations must be put before the whole declaration:
218 ecb_const int mysqrt (int a);
220 ecb_unused int i;
221 ecb_unused
223 Marks a function or a variable as "unused", which simply suppresses
224 a warning by the compiler when it detects it as unused. This is
225 useful when you e.g. declare a variable but do not always use it:
226 {
228 ecb_unused int var;
229 #ifdef SOMECONDITION
231 var = ...;
232 return var;
233 #else
234 return 0;
235 #endif
236 }
237 ecb_deprecated
239 Similar to "ecb_unused", but marks a function, variable or type as
240 deprecated. This makes some compilers warn when the type is used.
241 ecb_deprecated_message (message)
243 Same as "ecb_deprecated", but if possible, the specified diagnostic
244 is used instead of a generic depreciation message when the object
245 is being used.
246 ecb_inline
248 Expands either to (a compiler-specific equivalent of) "static
249 inline" or to just "static", if inline isn't supported. It should
250 be used to declare functions that should be inlined, for code size
251 or speed reasons.
252 Example: inline this function, it surely will reduce code size.
254 ecb_inline int
256 negmul (int a, int b)
257 {
258 return - (a * b);
259 }
260 ecb_noinline
262 Prevents a function from being inlined - it might be optimised
263 away, but not inlined into other functions. This is useful if you
264 know your function is rarely called and large enough for inlining
265 not to be helpful.
266 ecb_noreturn
268 Marks a function as "not returning, ever". Some typical functions
269 that don't return are "exit" or "abort" (which really works hard to
270 not return), and now you can make your own:
271 ecb_noreturn void
273 my_abort (const char *errline)
274 {
275 puts (errline);
276 abort ();
277 }
278 In this case, the compiler would probably be smart enough to deduce
280 it on its own, so this is mainly useful for declarations.
281 ecb_restrict
283 Expands to the "restrict" keyword or equivalent on compilers that
284 support them, and to nothing on others. Must be specified on a
285 pointer type or an array index to indicate that the memory doesn't
286 alias with any other restricted pointer in the same scope.
287 Example: multiply a vector, and allow the compiler to parallelise
289 the loop, because it knows it doesn't overwrite input values.
290 void
292 multiply (ecb_restrict float *src,
293 ecb_restrict float *dst,
294 int len, float factor)
295 {
296 int i;
297 for (i = 0; i < len; ++i)
299 dst [i] = src [i] * factor;
300 }
301 ecb_const
303 Declares that the function only depends on the values of its
304 arguments, much like a mathematical function. It specifically does
305 not read or write any memory any arguments might point to, global
306 variables, or call any non-const functions. It also must not have
307 any side effects.
308 Such a function can be optimised much more aggressively by the
310 compiler - for example, multiple calls with the same arguments can
311 be optimised into a single call, which wouldn't be possible if the
312 compiler would have to expect any side effects.
313 It is best suited for functions in the sense of mathematical
315 functions, such as a function returning the square root of its
316 input argument.
317 Not suited would be a function that calculates the hash of some
319 memory area you pass in, prints some messages or looks at a global
320 variable to decide on rounding.
321 See "ecb_pure" for a slightly less restrictive class of functions.
323 ecb_pure
325 Similar to "ecb_const", declares a function that has no side
326 effects. Unlike "ecb_const", the function is allowed to examine
327 global variables and any other memory areas (such as the ones
328 passed to it via pointers).
329 While these functions cannot be optimised as aggressively as
331 "ecb_const" functions, they can still be optimised away in many
332 occasions, and the compiler has more freedom in moving calls to
333 them around.
334 Typical examples for such functions would be "strlen" or "memcmp".
336 A function that calculates the MD5 sum of some input and updates
337 some MD5 state passed as argument would NOT be pure, however, as it
338 would modify some memory area that is not the return value.
339 ecb_hot
341 This declares a function as "hot" with regards to the cache - the
342 function is used so often, that it is very beneficial to keep it in
343 the cache if possible.
344 The compiler reacts by trying to place hot functions near to each
346 other in memory.
347 Whether a function is hot or not often depends on the whole
349 program, and less on the function itself. "ecb_cold" is likely more
350 useful in practise.
351 ecb_cold
353 The opposite of "ecb_hot" - declares a function as "cold" with
354 regards to the cache, or in other words, this function is not
355 called often, or not at speed-critical times, and keeping it in the
356 cache might be a waste of said cache.
357 In addition to placing cold functions together (or at least away
359 from hot functions), this knowledge can be used in other ways, for
360 example, the function will be optimised for size, as opposed to
361 speed, and code paths leading to calls to those functions can
362 automatically be marked as if "ecb_expect_false" had been used to
363 reach them.
364 Good examples for such functions would be error reporting
366 functions, or functions only called in exceptional or rare cases.
367 ecb_artificial
369 Declares the function as "artificial", in this case meaning that
370 this function is not really meant to be a function, but more like
371 an accessor - many methods in C++ classes are mere accessor
372 functions, and having a crash reported in such a method, or single-
373 stepping through them, is not usually so helpful, especially when
374 it's inlined to just a few instructions.
375 Marking them as artificial will instruct the debugger about just
377 this, leading to happier debugging and thus happier lives.
378 Example: in some kind of smart-pointer class, mark the pointer
380 accessor as artificial, so that the whole class acts more like a
381 pointer and less like some C++ abstraction monster.
382 template<typename T>
384 struct my_smart_ptr
385 {
386 T *value;
387 ecb_artificial
389 operator T *()
390 {
391 return value;
392 }
393 };
394 OPTIMISATION HINTS
396 bool ecb_is_constant (expr)
397 Returns true iff the expression can be deduced to be a compile-time
398 constant, and false otherwise.
399 For example, when you have a "rndm16" function that returns a 16
401 bit random number, and you have a function that maps this to a
402 range from 0..n-1, then you could use this inline function in a
403 header file:
404 ecb_inline uint32_t
406 rndm (uint32_t n)
407 {
408 return (n * (uint32_t)rndm16 ()) >> 16;
409 }
410 However, for powers of two, you could use a normal mask, but that
412 is only worth it if, at compile time, you can detect this case.
413 This is the case when the passed number is a constant and also a
414 power of two ("n & (n - 1) == 0"):
415 ecb_inline uint32_t
417 rndm (uint32_t n)
418 {
419 return is_constant (n) && !(n & (n - 1))
420 ? rndm16 () & (num - 1)
421 : (n * (uint32_t)rndm16 ()) >> 16;
422 }
423 ecb_expect (expr, value)
425 Evaluates "expr" and returns it. In addition, it tells the compiler
426 that the "expr" evaluates to "value" a lot, which can be used for
427 static branch optimisations.
428 Usually, you want to use the more intuitive "ecb_expect_true" and
430 "ecb_expect_false" functions instead.
431 bool ecb_expect_true (cond)
433 bool ecb_expect_false (cond)
434 These two functions expect a expression that is true or false and
435 return 1 or 0, respectively, so when used in the condition of an
436 "if" or other conditional statement, it will not change the
437 program:
438 /* these two do the same thing */
440 if (some_condition) ...;
441 if (ecb_expect_true (some_condition)) ...;
442 However, by using "ecb_expect_true", you tell the compiler that the
444 condition is likely to be true (and for "ecb_expect_false", that it
445 is unlikely to be true).
446 For example, when you check for a null pointer and expect this to
448 be a rare, exceptional, case, then use "ecb_expect_false":
449 void my_free (void *ptr)
451 {
452 if (ecb_expect_false (ptr == 0))
453 return;
454 }
455 Consequent use of these functions to mark away exceptional cases or
457 to tell the compiler what the hot path through a function is can
458 increase performance considerably.
459 You might know these functions under the name "likely" and
461 "unlikely" - while these are common aliases, we find that the
462 expect name is easier to understand when quickly skimming code. If
463 you wish, you can use "ecb_likely" instead of "ecb_expect_true" and
464 "ecb_unlikely" instead of "ecb_expect_false" - these are simply
465 aliases.
466 A very good example is in a function that reserves more space for
468 some memory block (for example, inside an implementation of a
469 string stream) - each time something is added, you have to check
470 for a buffer overrun, but you expect that most checks will turn out
471 to be false:
472 /* make sure we have "size" extra room in our buffer */
474 ecb_inline void
475 reserve (int size)
476 {
477 if (ecb_expect_false (current + size > end))
478 real_reserve_method (size); /* presumably noinline */
479 }
480 ecb_assume (cond)
482 Tries to tell the compiler that some condition is true, even if
483 it's not obvious. This is not a function, but a statement: it
484 cannot be used in another expression.
485 This can be used to teach the compiler about invariants or other
487 conditions that might improve code generation, but which are
488 impossible to deduce form the code itself.
489 For example, the example reservation function from the
491 "ecb_expect_false" description could be written thus (only
492 "ecb_assume" was added):
493 ecb_inline void
495 reserve (int size)
496 {
497 if (ecb_expect_false (current + size > end))
498 real_reserve_method (size); /* presumably noinline */
499 ecb_assume (current + size <= end);
501 }
502 If you then call this function twice, like this:
504 reserve (10);
506 reserve (1);
507 Then the compiler might be able to optimise out the second call
509 completely, as it knows that "current + 1 > end" is false and the
510 call will never be executed.
511 ecb_unreachable ()
513 This function does nothing itself, except tell the compiler that it
514 will never be executed. Apart from suppressing a warning in some
515 cases, this function can be used to implement "ecb_assume" or
516 similar functionality.
517 ecb_prefetch (addr, rw, locality)
519 Tells the compiler to try to prefetch memory at the given address
520 for either reading (rw = 0) or writing (rw = 1). A locality of 0
521 means that there will only be one access later, 3 means that the
522 data will likely be accessed very often, and values in between mean
523 something... in between. The memory pointed to by the address does
524 not need to be accessible (it could be a null pointer for example),
525 but "rw" and "locality" must be compile-time constants.
526 This is a statement, not a function: you cannot use it as part of
528 an expression.
529 An obvious way to use this is to prefetch some data far away, in a
531 big array you loop over. This prefetches memory some 128 array
532 elements later, in the hope that it will be ready when the CPU
533 arrives at that location.
534 int sum = 0;
536 for (i = 0; i < N; ++i)
538 {
539 sum += arr [i]
540 ecb_prefetch (arr + i + 128, 0, 0);
541 }
542 It's hard to predict how far to prefetch, and most CPUs that can
544 prefetch are often good enough to predict this kind of behaviour
545 themselves. It gets more interesting with linked lists, especially
546 when you do some fair processing on each list element:
547 for (node *n = start; n; n = n->next)
549 {
550 ecb_prefetch (n->next, 0, 0);
551 ... do medium amount of work with *n
552 }
553 After processing the node, (part of) the next node might already be
555 in cache.
556 BIT FIDDLING / BIT WIZARDRY
558 bool ecb_big_endian ()
559 bool ecb_little_endian ()
560 These two functions return true if the byte order is big endian
561 (most-significant byte first) or little endian (least-significant
562 byte first) respectively.
563 On systems that are neither, their return values are unspecified.
565 int ecb_ctz32 (uint32_t x)
567 int ecb_ctz64 (uint64_t x)
568 int ecb_ctz (T x) [C++]
569 Returns the index of the least significant bit set in "x" (or
570 equivalently the number of bits set to 0 before the least
571 significant bit set), starting from 0. If "x" is 0 the result is
572 undefined.
573 For smaller types than "uint32_t" you can safely use "ecb_ctz32".
575 The overloaded C++ "ecb_ctz" function supports "uint8_t",
577 "uint16_t", "uint32_t" and "uint64_t" types.
578 For example:
580 ecb_ctz32 (3) = 0
582 ecb_ctz32 (6) = 1
583 int ecb_clz32 (uint32_t x)
585 int ecb_clz64 (uint64_t x)
586 Counts the number of leading zero bits in "x". If "x" is 0 the
587 result is undefined.
588 It is often simpler to use one of the "ecb_ld*" functions instead,
590 whose result only depends on the value and not the size of the
591 type. This is also the reason why there is no C++ overload.
592 For example:
594 ecb_clz32 (3) = 30
596 ecb_clz32 (6) = 29
597 bool ecb_is_pot32 (uint32_t x)
599 bool ecb_is_pot64 (uint32_t x)
600 bool ecb_is_pot (T x) [C++]
601 Returns true iff "x" is a power of two or "x == 0".
602 For smaller types than "uint32_t" you can safely use
604 "ecb_is_pot32".
605 The overloaded C++ "ecb_is_pot" function supports "uint8_t",
607 "uint16_t", "uint32_t" and "uint64_t" types.
608 int ecb_ld32 (uint32_t x)
610 int ecb_ld64 (uint64_t x)
611 int ecb_ld64 (T x) [C++]
612 Returns the index of the most significant bit set in "x", or the
613 number of digits the number requires in binary (so that "2**ld <= x
614 < 2**(ld+1)"). If "x" is 0 the result is undefined. A common use
615 case is to compute the integer binary logarithm, i.e. "floor (log2
616 (n))", for example to see how many bits a certain number requires
617 to be encoded.
618 This function is similar to the "count leading zero bits" function,
620 except that that one returns how many zero bits are "in front" of
621 the number (in the given data type), while "ecb_ld" returns how
622 many bits the number itself requires.
623 For smaller types than "uint32_t" you can safely use "ecb_ld32".
625 The overloaded C++ "ecb_ld" function supports "uint8_t",
627 "uint16_t", "uint32_t" and "uint64_t" types.
628 int ecb_popcount32 (uint32_t x)
630 int ecb_popcount64 (uint64_t x)
631 int ecb_popcount (T x) [C++]
632 Returns the number of bits set to 1 in "x".
633 For smaller types than "uint32_t" you can safely use
635 "ecb_popcount32".
636 The overloaded C++ "ecb_popcount" function supports "uint8_t",
638 "uint16_t", "uint32_t" and "uint64_t" types.
639 For example:
641 ecb_popcount32 (7) = 3
643 ecb_popcount32 (255) = 8
644 uint8_t ecb_bitrev8 (uint8_t x)
646 uint16_t ecb_bitrev16 (uint16_t x)
647 uint32_t ecb_bitrev32 (uint32_t x)
648 T ecb_bitrev (T x) [C++]
649 Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes
650 LSB+1 and so on.
651 The overloaded C++ "ecb_bitrev" function supports "uint8_t",
653 "uint16_t" and "uint32_t" types.
654 Example:
656 ecb_bitrev8 (0xa7) = 0xea
658 ecb_bitrev32 (0xffcc4411) = 0x882233ff
659 T ecb_bitrev (T x) [C++]
661 Overloaded C++ bitrev function.
662 "T" must be one of "uint8_t", "uint16_t" or "uint32_t".
664 uint32_t ecb_bswap16 (uint32_t x)
666 uint32_t ecb_bswap32 (uint32_t x)
667 uint64_t ecb_bswap64 (uint64_t x)
668 T ecb_bswap (T x)
669 These functions return the value of the 16-bit (32-bit, 64-bit)
670 value "x" after reversing the order of bytes (0x11223344 becomes
671 0x44332211 in "ecb_bswap32").
672 The overloaded C++ "ecb_bswap" function supports "uint8_t",
674 "uint16_t", "uint32_t" and "uint64_t" types.
675 uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
677 uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
678 uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
679 uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
680 uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
681 uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
682 uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
683 uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
684 These two families of functions return the value of "x" after
685 rotating all the bits by "count" positions to the right
686 ("ecb_rotr") or left ("ecb_rotl"). There are no restrictions on the
687 value "count", i.e. both zero and values equal or larger than the
688 word width work correctly. Also, notwithstanding "count" being
689 unsigned, negative numbers work and shift to the opposite
690 direction.
691 Current GCC/clang versions understand these functions and usually
693 compile them to "optimal" code (e.g. a single "rol" or a
694 combination of "shld" on x86).
695 T ecb_rotl (T x, unsigned int count) [C++]
697 T ecb_rotr (T x, unsigned int count) [C++]
698 Overloaded C++ rotl/rotr functions.
699 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
701 uint_fast8_t ecb_gray_encode8 (uint_fast8_t b)
703 uint_fast16_t ecb_gray_encode16 (uint_fast16_t b)
704 uint_fast32_t ecb_gray_encode32 (uint_fast32_t b)
705 uint_fast64_t ecb_gray_encode64 (uint_fast64_t b)
706 Encode an unsigned into its corresponding (reflective) gray code -
707 the kind of gray code meant when just talking about "gray code".
708 These functions are very fast and all have identical
709 implementation, so there is no need to use a smaller type, as long
710 as your CPU can handle it natively.
711 T ecb_gray_encode (T b) [C++]
713 Overloaded C++ version of the above, for "uint{8,16,32,64}_t".
714 uint_fast8_t ecb_gray_decode8 (uint_fast8_t b)
716 uint_fast16_t ecb_gray_decode16 (uint_fast16_t b)
717 uint_fast32_t ecb_gray_decode32 (uint_fast32_t b)
718 uint_fast64_t ecb_gray_decode64 (uint_fast64_t b)
719 Decode a gray code back into linear index form (the reverse of
720 "ecb_gray*_encode". Unlike the encode functions, the decode
721 functions have higher time complexity for larger types, so it can
722 pay off to use a smaller type here.
723 T ecb_gray_decode (T b) [C++]
725 Overloaded C++ version of the above, for "uint{8,16,32,64}_t".
726 HILBERT CURVES
728 These functions deal with (square, pseudo) Hilbert curves. The
729 parameter order indicates the size of the square and is specified in
730 bits, that means for order 8, the coordinates range from 0..255, and
731 the curve index ranges from 0..65535.
732 The 32 bit variants of these functions map a 32 bit index to two 16 bit
734 coordinates, stored in a 32 bit variable, where the high order bits are
735 the x-coordinate, and the low order bits are the y-coordinate, thus,
736 these functions map 32 bit linear index on the curve to a 32 bit packed
737 coordinate pair, and vice versa.
738 The 64 bit variants work similarly.
740 The order can go from 1 to 16 for the 32 bit curve, and 1 to 32 for the
742 64 bit curve.
743 When going from one order to the next higher order, these functions
745 replace the curve segments by smaller versions of the generating shape,
746 while doubling the size (since they use integer coordinates), which is
747 what you would expect mathematically. This means that the curve will be
748 mirrored at the diagonal. If your goal is to simply cover more area
749 while retaining existing point coordinates you should increase or
750 decrease the order by 2 or, in the case of
751 "ecb_hilbert2d_index_to_coord", simply specify the maximum order of 16
752 or 32, respectively, as these are constant-time.
753 uint32_t ecb_hilbert2d_index_to_coord32 (int order, uint32_t index)
755 uint64_t ecb_hilbert2d_index_to_coord64 (int order, uint64_t index)
756 Map a point on a pseudo Hilbert curve from its linear distance from
757 the origin on the curve to a x|y coordinate pair. The result is a
758 packed coordinate pair, to get the actual x and < coordinates, you
759 could do something like this:
760 uint32_t xy = ecb_hilbert2d_index_to_coord32 (16, 255);
762 uint16_t x = xy >> 16;
763 uint16_t y = xy & 0xffffU;
764 uint64_t xy = ecb_hilbert2d_index_to_coord64 (32, 255);
766 uint32_t x = xy >> 32;
767 uint32_t y = xy & 0xffffffffU;
768 These functions work in constant time, so for many applications it
770 is preferable to simply hard-code the order to the maximum (16 or
771 32).
772 This (production-ready, i.e. never run) example generates an SVG
774 image of an order 8 pseudo Hilbert curve:
775 printf ("<svg xmlns='http://www.w3.org/2000/svg' width='%d' height='%d'>\n", 64 * 8, 64 * 8);
777 printf ("<g transform='translate(4) scale(8)' stroke-width='0.25' stroke='black'>\n");
778 for (uint32_t i = 0; i < 64*64 - 1; ++i)
779 {
780 uint32_t p1 = ecb_hilbert2d_index_to_coord32 (6, i );
781 uint32_t p2 = ecb_hilbert2d_index_to_coord32 (6, i + 1);
782 printf ("<line x1='%d' y1='%d' x2='%d' y2='%d'/>\n",
783 p1 >> 16, p1 & 0xffff,
784 p2 >> 16, p2 & 0xffff);
785 }
786 printf ("</g>\n");
787 printf ("</svg>\n");
788 uint32_t ecb_hilbert2d_coord_to_index32 (int order, uint32_t xy)
790 uint64_t ecb_hilbert2d_coord_to_index64 (int order, uint64_t xy)
791 The reverse of "ecb_hilbert2d_index_to_coord" - map a packed pair
792 of coordinates to their linear index on the pseudo Hilbert curve of
793 order order.
794 They are an exact inverse of the "ecb_hilbert2d_coord_to_index"
796 functions for the same order:
797 assert (
799 u == ecb_hilbert2d_coord_to_index (32,
800 ecb_hilbert2d_index_to_coord32 (32,
801 u)));
802 Packing coordinates is done the same way, as well, from x and y:
804 uint32_t xy = ((uint32_t)x << 16) | y; // for ecb_hilbert2d_coord_to_index32
806 uint64_t xy = ((uint64_t)x << 32) | y; // for ecb_hilbert2d_coord_to_index64
807 Unlike "ecb_hilbert2d_coord_to_index", these functions are
809 O(order), so it is preferable to use the lowest possible order.
810 BIT MIXING, HASHING
812 Sometimes you have an integer and want to distribute its bits well, for
813 example, to use it as a hash in a hash table. A common example is
814 pointer values, which often only have a limited range (e.g. low and
815 high bits are often zero).
816 The following functions try to mix the bits to get a good bias-free
818 distribution. They were mainly made for pointers, but the underlying
819 integer functions are exposed as well.
820 As an added benefit, the functions are reversible, so if you find it
822 convenient to store only the hash value, you can recover the original
823 pointer from the hash ("unmix"), as long as your pointers are 32 or 64
824 bit (if this isn't the case on your platform, drop us a note and we
825 will add functions for other bit widths).
826 The unmix functions are very slightly slower than the mix functions, so
828 it is equally very slightly preferable to store the original values
829 wehen convenient.
830 The underlying algorithm if subject to change, so currently these
832 functions are not suitable for persistent hash tables, as their result
833 value can change between different versions of libecb.
834 uintptr_t ecb_ptrmix (void *ptr)
836 Mixes the bits of a pointer so the result is suitable for hash
837 table lookups. In other words, this hashes the pointer value.
838 uintptr_t ecb_ptrmix (T *ptr) [C++]
840 Overload the "ecb_ptrmix" function to work for any pointer in C++.
841 void *ecb_ptrunmix (uintptr_t v)
843 Unmix the hash value into the original pointer. This only works as
844 long as the hash value is not truncated, i.e. you used "uintptr_t"
845 (or equivalent) throughout to store it.
846 T *ecb_ptrunmix<T> (uintptr_t v) [C++]
848 The somewhat less useful template version of "ecb_ptrunmix" for
849 C++. Example:
850 sometype *myptr;
852 uintptr_t hash = ecb_ptrmix (myptr);
853 sometype *orig = ecb_ptrunmix<sometype> (hash);
854 uint32_t ecb_mix32 (uint32_t v)
856 uint64_t ecb_mix64 (uint64_t v)
857 Sometimes you don't have a pointer but an integer whose values are
858 very badly distributed. In this case you can use these integer
859 versions of the mixing function. No C++ template is provided
860 currently.
861 uint32_t ecb_unmix32 (uint32_t v)
863 uint64_t ecb_unmix64 (uint64_t v)
864 The reverse of the "ecb_mix" functions - they take a mixed/hashed
865 value and recover the original value.
866 HOST ENDIANNESS CONVERSION
868 uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
869 uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
870 uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
871 uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
872 uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
873 uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
874 Convert an unsigned 16, 32 or 64 bit value from big or little
875 endian to host byte order.
876 The naming convention is "ecb_"("be"|"le")"_u""16|32|64""_to_host",
878 where "be" and "le" stand for big endian and little endian,
879 respectively.
880 uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
882 uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
883 uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
884 uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
885 uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
886 uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
887 Like above, but converts from host byte order to the specified
888 endianness.
889 In C++ the following additional template functions are supported:
891 T ecb_be_to_host (T v)
893 T ecb_le_to_host (T v)
894 T ecb_host_to_be (T v)
895 T ecb_host_to_le (T v)
896 These functions work like their C counterparts, above, but use
898 templates, which make them useful in generic code.
899 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t" (so
901 unlike their C counterparts, there is a version for "uint8_t", which
902 again can be useful in generic code).
903 UNALIGNED LOAD/STORE
905 These function load or store unaligned multi-byte values.
906 uint_fast16_t ecb_peek_u16_u (const void *ptr)
908 uint_fast32_t ecb_peek_u32_u (const void *ptr)
909 uint_fast64_t ecb_peek_u64_u (const void *ptr)
910 These functions load an unaligned, unsigned 16, 32 or 64 bit value
911 from memory.
912 uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
914 uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
915 uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
916 uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
917 uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
918 uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
919 Like above, but additionally convert from big endian ("be") or
920 little endian ("le") byte order to host byte order while doing so.
921 ecb_poke_u16_u (void *ptr, uint16_t v)
923 ecb_poke_u32_u (void *ptr, uint32_t v)
924 ecb_poke_u64_u (void *ptr, uint64_t v)
925 These functions store an unaligned, unsigned 16, 32 or 64 bit value
926 to memory.
927 ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
929 ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
930 ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
931 ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
932 ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
933 ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
934 Like above, but additionally convert from host byte order to big
935 endian ("be") or little endian ("le") byte order while doing so.
936 In C++ the following additional template functions are supported:
938 T ecb_peek<T> (const void *ptr)
940 T ecb_peek_be<T> (const void *ptr)
941 T ecb_peek_le<T> (const void *ptr)
942 T ecb_peek_u<T> (const void *ptr)
943 T ecb_peek_be_u<T> (const void *ptr)
944 T ecb_peek_le_u<T> (const void *ptr)
945 Similarly to their C counterparts, these functions load an unsigned
946 8, 16, 32 or 64 bit value from memory, with optional conversion
947 from big/little endian.
948 Since the type cannot be deduced, it has to be specified
950 explicitly, e.g.
951 uint_fast16_t v = ecb_peek<uint16_t> (ptr);
953 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
955 Unlike their C counterparts, these functions support 8 bit
957 quantities ("uint8_t") and also have an aligned version (without
958 the "_u" prefix), all of which hopefully makes them more useful in
959 generic code.
960 ecb_poke (void *ptr, T v)
962 ecb_poke_be (void *ptr, T v)
963 ecb_poke_le (void *ptr, T v)
964 ecb_poke_u (void *ptr, T v)
965 ecb_poke_be_u (void *ptr, T v)
966 ecb_poke_le_u (void *ptr, T v)
967 Again, similarly to their C counterparts, these functions store an
968 unsigned 8, 16, 32 or 64 bit value to memory, with optional
969 conversion to big/little endian.
970 "T" must be one of "uint8_t", "uint16_t", "uint32_t" or "uint64_t".
972 Unlike their C counterparts, these functions support 8 bit
974 quantities ("uint8_t") and also have an aligned version (without
975 the "_u" prefix), all of which hopefully makes them more useful in
976 generic code.
977 FAST INTEGER TO STRING
979 Libecb defines a set of very fast integer to decimal string (or integer
980 to ASCII, short "i2a") functions. These work by converting the integer
981 to a fixed point representation and then successively multiplying out
982 the topmost digits. Unlike some other, also very fast, libraries, ecb's
983 algorithm should be completely branchless per digit, and does not rely
984 on the presence of special CPU functions (such as "clz").
985 There is a high level API that takes an "int32_t", "uint32_t",
987 "int64_t" or "uint64_t" as argument, and a low-level API, which is
988 harder to use but supports slightly more formatting options.
989 HIGH LEVEL API
991 The high level API consists of four functions, one each for "int32_t",
993 "uint32_t", "int64_t" and "uint64_t":
994 Example:
996 char buf[ECB_I2A_MAX_DIGITS + 1];
998 char *end = ecb_i2a_i32 (buf, 17262);
999 *end = 0;
1000 // buf now contains "17262"
1001 ECB_I2A_I32_DIGITS (=11)
1003 char *ecb_i2a_u32 (char *ptr, uint32_t value)
1004 Takes an "uint32_t" value and formats it as a decimal number
1005 starting at ptr, using at most "ECB_I2A_I32_DIGITS" characters.
1006 Returns a pointer to just after the generated string, where you
1007 would normally put the terminating 0 character. This function
1008 outputs the minimum number of digits.
1009 ECB_I2A_U32_DIGITS (=10)
1011 char *ecb_i2a_i32 (char *ptr, int32_t value)
1012 Same as "ecb_i2a_u32", but formats a "int32_t" value, including a
1013 minus sign if needed.
1014 ECB_I2A_I64_DIGITS (=20)
1016 char *ecb_i2a_u64 (char *ptr, uint64_t value)
1017 ECB_I2A_U64_DIGITS (=21)
1018 char *ecb_i2a_i64 (char *ptr, int64_t value)
1019 Similar to their 32 bit counterparts, these take a 64 bit argument.
1020 ECB_I2A_MAX_DIGITS (=21)
1022 Instead of using a type specific length macro, you can just use
1023 "ECB_I2A_MAX_DIGITS", which is good enough for any "ecb_i2a"
1024 function.
1025 LOW-LEVEL API
1027 The functions above use a number of low-level APIs which have some
1029 strict limitations, but can be used as building blocks (studying
1030 "ecb_i2a_i32" and related functions is recommended).
1031 There are three families of functions: functions that convert a number
1033 to a fixed number of digits with leading zeroes ("ecb_i2a_0N", 0 for
1034 "leading zeroes"), functions that generate up to N digits, skipping
1035 leading zeroes ("_N"), and functions that can generate more digits, but
1036 the leading digit has limited range ("_xN").
1037 None of the functions deal with negative numbers.
1039 Example: convert an IP address in an "uint32_t" into dotted-quad:
1041 uint32_t ip = 0x0a000164; // 10.0.1.100
1043 char ips[3 * 4 + 3 + 1];
1044 char *ptr = ips;
1045 ptr = ecb_i2a_3 (ptr, ip >> 24 ); *ptr++ = '.';
1046 ptr = ecb_i2a_3 (ptr, (ip >> 16) & 0xff); *ptr++ = '.';
1047 ptr = ecb_i2a_3 (ptr, (ip >> 8) & 0xff); *ptr++ = '.';
1048 ptr = ecb_i2a_3 (ptr, ip & 0xff); *ptr++ = 0;
1049 printf ("ip: %s\n", ips); // prints "ip: 10.0.1.100"
1050 char *ecb_i2a_02 (char *ptr, uint32_t value) // 32 bit
1052 char *ecb_i2a_03 (char *ptr, uint32_t value) // 32 bit
1053 char *ecb_i2a_04 (char *ptr, uint32_t value) // 32 bit
1054 char *ecb_i2a_05 (char *ptr, uint32_t value) // 64 bit
1055 char *ecb_i2a_06 (char *ptr, uint32_t value) // 64 bit
1056 char *ecb_i2a_07 (char *ptr, uint32_t value) // 64 bit
1057 char *ecb_i2a_08 (char *ptr, uint32_t value) // 64 bit
1058 char *ecb_i2a_09 (char *ptr, uint32_t value) // 64 bit
1059 The "ecb_i2a_0N" functions take an unsigned value and convert them
1060 to exactly N digits, returning a pointer to the first character
1061 after the digits. The value must be in range. The functions marked
1062 with 32 bit do their calculations internally in 32 bit, the ones
1063 marked with 64 bit internally use 64 bit integers, which might be
1064 slow on 32 bit architectures (the high level API decides on 32 vs.
1065 64 bit versions using "ECB_64BIT_NATIVE").
1066 char *ecb_i2a_2 (char *ptr, uint32_t value) // 32 bit
1068 char *ecb_i2a_3 (char *ptr, uint32_t value) // 32 bit
1069 char *ecb_i2a_4 (char *ptr, uint32_t value) // 32 bit
1070 char *ecb_i2a_5 (char *ptr, uint32_t value) // 64 bit
1071 char *ecb_i2a_6 (char *ptr, uint32_t value) // 64 bit
1072 char *ecb_i2a_7 (char *ptr, uint32_t value) // 64 bit
1073 char *ecb_i2a_8 (char *ptr, uint32_t value) // 64 bit
1074 char *ecb_i2a_9 (char *ptr, uint32_t value) // 64 bit
1075 Similarly, the "ecb_i2a_N" functions take an unsigned value and
1076 convert them to at most N digits, suppressing leading zeroes, and
1077 returning a pointer to the first character after the digits.
1078 ECB_I2A_MAX_X5 (=59074)
1080 char *ecb_i2a_x5 (char *ptr, uint32_t value) // 32 bit
1081 ECB_I2A_MAX_X10 (=2932500665)
1082 char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
1083 The "ecb_i2a_xN" functions are similar to the "ecb_i2a_N"
1084 functions, but they can generate one digit more, as long as the
1085 number is within range, which is given by the symbols
1086 "ECB_I2A_MAX_X5" (almost 16 bit range) and "ECB_I2A_MAX_X10" (a bit
1087 more than 31 bit range), respectively.
1088 For example, the digit part of a 32 bit signed integer just fits
1090 into the "ECB_I2A_MAX_X10" range, so while "ecb_i2a_x10" cannot
1091 convert a 10 digit number, it can convert all 32 bit signed
1092 numbers. Sadly, it's not good enough for 32 bit unsigned numbers.
1093 FLOATING POINT FIDDLING
1095 ECB_INFINITY [-UECB_NO_LIBM]
1096 Evaluates to positive infinity if supported by the platform,
1097 otherwise to a truly huge number.
1098 ECB_NAN [-UECB_NO_LIBM]
1100 Evaluates to a quiet NAN if supported by the platform, otherwise to
1101 "ECB_INFINITY".
1102 float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
1104 Same as "ldexpf", but always available.
1105 uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
1107 uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
1108 uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
1109 These functions each take an argument in the native "float" or
1110 "double" type and return the IEEE 754 bit representation of it
1111 (binary16/half, binary32/single or binary64/double precision).
1112 The bit representation is just as IEEE 754 defines it, i.e. the
1114 sign bit will be the most significant bit, followed by exponent and
1115 mantissa.
1116 This function should work even when the native floating point
1118 format isn't IEEE compliant, of course at a speed and code size
1119 penalty, and of course also within reasonable limits (it tries to
1120 convert NaNs, infinities and denormals, but will likely convert
1121 negative zero to positive zero).
1122 On all modern platforms (where "ECB_STDFP" is true), the compiler
1124 should be able to completely optimise away the 32 and 64 bit
1125 functions.
1126 These functions can be helpful when serialising floats to the
1128 network - you can serialise the return value like a normal
1129 uint16_t/uint32_t/uint64_t.
1130 Another use for these functions is to manipulate floating point
1132 values directly.
1133 Silly example: toggle the sign bit of a float.
1135 /* On gcc-4.7 on amd64, */
1137 /* this results in a single add instruction to toggle the bit, and 4 extra */
1138 /* instructions to move the float value to an integer register and back. */
1139 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
1141 float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
1143 float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
1144 double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
1145 The reverse operation of the previous function - takes the bit
1146 representation of an IEEE binary16, binary32 or binary64 number
1147 (half, single or double precision) and converts it to the native
1148 "float" or "double" format.
1149 This function should work even when the native floating point
1151 format isn't IEEE compliant, of course at a speed and code size
1152 penalty, and of course also within reasonable limits (it tries to
1153 convert normals and denormals, and might be lucky for infinities,
1154 and with extraordinary luck, also for negative zero).
1155 On all modern platforms (where "ECB_STDFP" is true), the compiler
1157 should be able to optimise away this function completely.
1158 uint16_t ecb_binary32_to_binary16 (uint32_t x)
1160 uint32_t ecb_binary16_to_binary32 (uint16_t x)
1161 Convert a IEEE binary32/single precision to binary16/half format,
1162 and vice versa, handling all details (round-to-nearest-even,
1163 subnormals, infinity and NaNs) correctly.
1164 These are functions are available under "-DECB_NO_LIBM", since they
1166 do not rely on the platform floating point format. The
1167 "ecb_float_to_binary16" and "ecb_binary16_to_float" functions are
1168 usually what you want.
1169 ARITHMETIC
1171 x = ecb_mod (m, n)
1172 Returns "m" modulo "n", which is the same as the positive remainder
1173 of the division operation between "m" and "n", using floored
1174 division. Unlike the C remainder operator "%", this function
1175 ensures that the return value is always positive and that the two
1176 numbers m and m' = m + i * n result in the same value modulo n - in
1177 other words, "ecb_mod" implements the mathematical modulo
1178 operation, which is missing in the language.
1179 "n" must be strictly positive (i.e. ">= 1"), while "m" must be
1181 negatable, that is, both "m" and "-m" must be representable in its
1182 type (this typically excludes the minimum signed integer value, the
1183 same limitation as for "/" and "%" in C).
1184 Current GCC/clang versions compile this into an efficient
1186 branchless sequence on almost all CPUs.
1187 For example, when you want to rotate forward through the members of
1189 an array for increasing "m" (which might be negative), then you
1190 should use "ecb_mod", as the "%" operator might give either
1191 negative results, or change direction for negative values:
1192 for (m = -100; m <= 100; ++m)
1194 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
1195 x = ecb_div_rd (val, div)
1197 x = ecb_div_ru (val, div)
1198 Returns "val" divided by "div" rounded down or up, respectively.
1199 "val" and "div" must have integer types and "div" must be strictly
1200 positive. Note that these functions are implemented with macros in
1201 C and with function templates in C++.
1202 UTILITY
1204 element_count = ecb_array_length (name)
1205 Returns the number of elements in the array "name". For example:
1206 int primes[] = { 2, 3, 5, 7, 11 };
1208 int sum = 0;
1209 for (i = 0; i < ecb_array_length (primes); i++)
1211 sum += primes [i];
1212 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
1214 These symbols need to be defined before including ecb.h the first time.
1215 ECB_NO_THREADS
1217 If ecb.h is never used from multiple threads, then this symbol can
1218 be defined, in which case memory fences (and similar constructs)
1219 are completely removed, leading to more efficient code and fewer
1220 dependencies.
1221 Setting this symbol to a true value implies "ECB_NO_SMP".
1223 ECB_NO_SMP
1225 The weaker version of "ECB_NO_THREADS" - if ecb.h is used from
1226 multiple threads, but never concurrently (e.g. if the system the
1227 program runs on has only a single CPU with a single core, no hyper-
1228 threading and so on), then this symbol can be defined, leading to
1229 more efficient code and fewer dependencies.
1230 ECB_NO_LIBM
1232 When defined to 1, do not export any functions that might introduce
1233 dependencies on the math library (usually called -lm) - these are
1234 marked with [-UECB_NO_LIBM].
1235
1237 ecb.h is full of undocumented functionality as well, some of which is
1238 intended to be internal-use only, some of which we forgot to document,
1239 and some of which we hide because we are not sure we will keep the
1240 interface stable.
1241 While you are welcome to rummage around and use whatever you find
1243 useful (we don't want to stop you), keep in mind that we will change
1244 undocumented functionality in incompatible ways without thinking twice,
1245 while we are considerably more conservative with documented things.
1246
1248 "libecb" is designed and maintained by:
1249 Emanuele Giaquinta <e.giaquinta@glauco.it>
1251 Marc Alexander Lehmann <schmorp@schmorp.de>
1252perl v5.38.0 2023-09-11 ECB(1)