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 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 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 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_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t
66 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 For "ptrdiff_t" and "size_t" use "stddef.h"/"cstddef".
72 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 ECB_C
79 True if the implementation defines the "__STDC__" macro to a true
80 value, while not claiming to be C++.
81 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 Note that later versions (ECB_C11) remove core features again (for
87 example, variable length arrays).
88 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 ECB_CPP
95 True if the implementation defines the "__cplusplus__" macro to a
96 true value, which is typically true for C++ compilers.
97 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 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 This macro tries to return false on compilers that claim to be GCC
109 compatible but aren't.
110 ECB_EXTERN_C
112 Expands to "extern "C"" in C++, and a simple "extern" in C.
113 This can be used to declare a single external C function:
115 ECB_EXTERN_C int printf (const char *format, ...);
117 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 They are most useful in header files:
123 ECB_EXTERN_C_BEG
125 int mycfun1 (int x);
127 int mycfun2 (int x);
128 ECB_EXTERN_C_END
130 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 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 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 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 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 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 #define S1 str
163 #define S2 cpy
164 ECB_CONCAT (S1, S2)(dst, src); // == strcpy (dst, src);
166 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 #define SQL_LIMIT 100
173 sql_exec ("select * from table limit " ECB_STRINGIFY (SQL_LIMIT));
174 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 #include <errno.h>
181 ECB_STRINGIFY (EDOM); // "33" (on my system at least)
183 ECB_STRINGIFY_EXPR (EDOM); // "33"
184 // now imagine we had a typo:
186 ECB_STRINGIFY (EDAM); // "EDAM"
188 ECB_STRINGIFY_EXPR (EDAM); // error: EDAM undefined
189 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 ecb_const int mysqrt (int a);
198 ecb_unused int i;
199 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 {
206 ecb_unused int var;
207 #ifdef SOMECONDITION
209 var = ...;
210 return var;
211 #else
212 return 0;
213 #endif
214 }
215 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 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 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 Example: inline this function, it surely will reduce codesize.
232 ecb_inline int
234 negmul (int a, int b)
235 {
236 return - (a * b);
237 }
238 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 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 ecb_noreturn void
251 my_abort (const char *errline)
252 {
253 puts (errline);
254 abort ();
255 }
256 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 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 Example: multiply a vector, and allow the compiler to parallelise
267 the loop, because it knows it doesn't overwrite input values.
268 void
270 multiply (ecb_restrict float *src,
271 ecb_restrict float *dst,
272 int len, float factor)
273 {
274 int i;
275 for (i = 0; i < len; ++i)
277 dst [i] = src [i] * factor;
278 }
279 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 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 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 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 See "ecb_pure" for a slightly less restrictive class of functions.
301 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 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 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 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 The compiler reacts by trying to place hot functions near to each
324 other in memory.
325 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 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 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 Good examples for such functions would be error reporting
344 functions, or functions only called in exceptional or rare cases.
345 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 Marking them as artificial will instruct the debugger about just
355 this, leading to happier debugging and thus happier lives.
356 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 template<typename T>
362 struct my_smart_ptr
363 {
364 T *value;
365 ecb_artificial
367 operator T *()
368 {
369 return value;
370 }
371 };
372 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 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 ecb_inline uint32_t
384 rndm (uint32_t n)
385 {
386 return (n * (uint32_t)rndm16 ()) >> 16;
387 }
388 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 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 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 Usually, you want to use the more intuitive "ecb_expect_true" and
408 "ecb_expect_false" functions instead.
409 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 /* these two do the same thing */
418 if (some_condition) ...;
419 if (ecb_expect_true (some_condition)) ...;
420 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 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 void my_free (void *ptr)
429 {
430 if (ecb_expect_false (ptr == 0))
431 return;
432 }
433 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 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 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 /* 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 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 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 For example, the example reservation function from the
469 "ecb_expect_false" description could be written thus (only
470 "ecb_assume" was added):
471 ecb_inline void
473 reserve (int size)
474 {
475 if (ecb_expect_false (current + size > end))
476 real_reserve_method (size); /* presumably noinline */
477 ecb_assume (current + size <= end);
479 }
480 If you then call this function twice, like this:
482 reserve (10);
484 reserve (1);
485 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 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 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 This is a statement, not a function: you cannot use it as part of
506 an expression.
507 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 int sum = 0;
514 for (i = 0; i < N; ++i)
516 {
517 sum += arr [i]
518 ecb_prefetch (arr + i + 128, 0, 0);
519 }
520 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 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 After processing the node, (part of) the next node might already be
533 in cache.
534 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 On systems that are neither, their return values are unspecified.
543 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 For smaller types than "uint32_t" you can safely use "ecb_ctz32".
552 For example:
554 ecb_ctz32 (3) = 0
556 ecb_ctz32 (6) = 1
557 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 For smaller types than "uint32_t" you can safely use
563 "ecb_is_pot32".
564 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 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 For smaller types than "uint32_t" you can safely use "ecb_ld32".
580 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 For smaller types than "uint32_t" you can safely use
586 "ecb_popcount32".
587 For example:
589 ecb_popcount32 (7) = 3
591 ecb_popcount32 (255) = 8
592 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 Example:
600 ecb_bitrev8 (0xa7) = 0xea
602 ecb_bitrev32 (0xffcc4411) = 0x882233ff
603 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 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 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 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 ECB_NAN [-UECB_NO_LIBM]
633 Evaluates to a quiet NAN if supported by the platform, otherwise to
634 "ECB_INFINITY".
635 float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
637 Same as "ldexpf", but always available.
638 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 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 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 On all modern platforms (where "ECB_STDFP" is true), the compiler
657 should be able to optimise away this function completely.
658 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 Another use for these functions is to manipulate floating point
664 values directly.
665 Silly example: toggle the sign bit of a float.
667 /* 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 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
673 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 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 On all modern platforms (where "ECB_STDFP" is true), the compiler
689 should be able to optimise away this function completely.
690 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 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 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 "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 Current GCC versions compile this into an efficient branchless
718 sequence on almost all CPUs.
719 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 for (m = -100; m <= 100; ++m)
726 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
727 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 UTILITY
736 element_count = ecb_array_length (name)
737 Returns the number of elements in the array "name". For example:
738 int primes[] = { 2, 3, 5, 7, 11 };
740 int sum = 0;
741 for (i = 0; i < ecb_array_length (primes); i++)
743 sum += primes [i];
744 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
746 These symbols need to be defined before including ecb.h the first time.
747 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 Setting this symbol to a true value implies "ECB_NO_SMP".
755 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 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
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 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
780 "libecb" is designed and maintained by:
781 Emanuele Giaquinta <e.giaquinta@glauco.it>
783 Marc Alexander Lehmann <schmorp@schmorp.de>
784perl v5.30.1 2020-01-29 ECB(1)