ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
(Generate patch)

Comparing libecb/ecb.pod (file contents):
Revision 1.32 by sf-exg, Fri Jun 17 15:55:41 2011 UTC vs.
Revision 1.52 by root, Sun Sep 23 22:32:33 2012 UTC

… …
53C<uint32_t>, then the corresponding function works only with that type. If 53C<uint32_t>, then the corresponding function works only with that type. If
54only a generic name is used (C<expr>, C<cond>, C<value> and so on), then 54only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55the corresponding function relies on C to implement the correct types, and 55the corresponding function relies on C to implement the correct types, and
56is usually implemented as a macro. Specifically, a "bool" in this manual 56is usually implemented as a macro. Specifically, a "bool" in this manual
57refers to any kind of boolean value, not a specific type. 57refers to any kind of boolean value, not a specific type.
58
59=head2 TYPES / TYPE SUPPORT
60
61ecb.h makes sure that the following types are defined (in the expected way):
62
63 int8_t uint8_t int16_t uint16_t
64 int32_t uint32_t int64_t uint64_t
65 intptr_t uintptr_t
66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions.
70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
72
73=head2 LANGUAGE/COMPILER VERSIONS
74
75All the following symbols expand to an expression that can be tested in
76preprocessor instructions as well as treated as a boolean (use C<!!> to
77ensure it's either C<0> or C<1> if you need that).
78
79=over 4
80
81=item ECB_C
82
83True if the implementation defines the C<__STDC__> macro to a true value,
84which is typically true for both C and C++ compilers.
85
86=item ECB_C99
87
88True if the implementation claims to be compliant to C99 (ISO/IEC
899899:1999) or any later version.
90
91Note that later versions (ECB_C11) remove core features again (for
92example, variable length arrays).
93
94=item ECB_C11
95
96True if the implementation claims to be compliant to C11 (ISO/IEC
979899:2011) or any later version.
98
99=item ECB_CPP
100
101True if the implementation defines the C<__cplusplus__> macro to a true
102value, which is typically true for C++ compilers.
103
104=item ECB_CPP11
105
106True if the implementation claims to be compliant to ISO/IEC 14882:2011
107(C++11) or any later version.
108
109=item ECB_GCC_VERSION(major,minor)
110
111Expands to a true value (suitable for testing in by the preprocessor)
112if the compiler used is GNU C and the version is the given version, or
113higher.
114
115This macro tries to return false on compilers that claim to be GCC
116compatible but aren't.
117
118=item ECB_EXTERN_C
119
120Expands to C<extern "C"> in C++, and a simple C<extern> in C.
121
122This can be used to declare a single external C function:
123
124 ECB_EXTERN_C int printf (const char *format, ...);
125
126=item ECB_EXTERN_C_BEG / ECB_EXTERN_C_END
127
128These two macros can be used to wrap multiple C<extern "C"> definitions -
129they expand to nothing in C.
130
131They are most useful in header files:
132
133 ECB_EXTERN_C_BEG
134
135 int mycfun1 (int x);
136 int mycfun2 (int x);
137
138 ECB_EXTERN_C_END
139
140=item ECB_STDFP
141
142If this evaluates to a true value (suitable for testing in by the
143preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
144and double/binary64 representations internally I<and> the endianness of
145both types match the endianness of C<uint32_t> and C<uint64_t>.
146
147This means you can just copy the bits of a C<float> (or C<double>) to an
148C<uint32_t> (or C<uint64_t>) and get the raw IEEE 754 bit representation
149without having to think about format or endianness.
150
151This is true for basically all modern platforms, although F<ecb.h> might
152not be able to deduce this correctly everywhere and might err on the safe
153side.
154
155=back
58 156
59=head2 GCC ATTRIBUTES 157=head2 GCC ATTRIBUTES
60 158
61A major part of libecb deals with GCC attributes. These are additional 159A major part of libecb deals with GCC attributes. These are additional
62attributes that you can assign to functions, variables and sometimes even 160attributes that you can assign to functions, variables and sometimes even
… …
207functions only called in exceptional or rare cases. 305functions only called in exceptional or rare cases.
208 306
209=item ecb_artificial 307=item ecb_artificial
210 308
211Declares the function as "artificial", in this case meaning that this 309Declares the function as "artificial", in this case meaning that this
212function is not really mean to be a function, but more like an accessor 310function is not really meant to be a function, but more like an accessor
213- many methods in C++ classes are mere accessor functions, and having a 311- many methods in C++ classes are mere accessor functions, and having a
214crash reported in such a method, or single-stepping through them, is not 312crash reported in such a method, or single-stepping through them, is not
215usually so helpful, especially when it's inlined to just a few instructions. 313usually so helpful, especially when it's inlined to just a few instructions.
216 314
217Marking them as artificial will instruct the debugger about just this, 315Marking them as artificial will instruct the debugger about just this,
… …
396After processing the node, (part of) the next node might already be in 494After processing the node, (part of) the next node might already be in
397cache. 495cache.
398 496
399=back 497=back
400 498
401=head2 BIT FIDDLING / BITSTUFFS 499=head2 BIT FIDDLING / BIT WIZARDRY
402 500
403=over 4 501=over 4
404 502
405=item bool ecb_big_endian () 503=item bool ecb_big_endian ()
406 504
… …
412 510
413On systems that are neither, their return values are unspecified. 511On systems that are neither, their return values are unspecified.
414 512
415=item int ecb_ctz32 (uint32_t x) 513=item int ecb_ctz32 (uint32_t x)
416 514
515=item int ecb_ctz64 (uint64_t x)
516
417Returns the index of the least significant bit set in C<x> (or 517Returns the index of the least significant bit set in C<x> (or
418equivalently the number of bits set to 0 before the least significant bit 518equivalently the number of bits set to 0 before the least significant bit
419set), starting from 0. If C<x> is 0 the result is undefined. For example: 519set), starting from 0. If C<x> is 0 the result is undefined.
520
521For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
522
523For example:
420 524
421 ecb_ctz32 (3) = 0 525 ecb_ctz32 (3) = 0
422 ecb_ctz32 (6) = 1 526 ecb_ctz32 (6) = 1
423 527
528=item bool ecb_is_pot32 (uint32_t x)
529
530=item bool ecb_is_pot64 (uint32_t x)
531
532Return true iff C<x> is a power of two or C<x == 0>.
533
534For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
535
536=item int ecb_ld32 (uint32_t x)
537
538=item int ecb_ld64 (uint64_t x)
539
540Returns the index of the most significant bit set in C<x>, or the number
541of digits the number requires in binary (so that C<< 2**ld <= x <
5422**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
543to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
544example to see how many bits a certain number requires to be encoded.
545
546This function is similar to the "count leading zero bits" function, except
547that that one returns how many zero bits are "in front" of the number (in
548the given data type), while C<ecb_ld> returns how many bits the number
549itself requires.
550
551For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
552
424=item int ecb_popcount32 (uint32_t x) 553=item int ecb_popcount32 (uint32_t x)
425 554
555=item int ecb_popcount64 (uint64_t x)
556
426Returns the number of bits set to 1 in C<x>. For example: 557Returns the number of bits set to 1 in C<x>.
558
559For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
560
561For example:
427 562
428 ecb_popcount32 (7) = 3 563 ecb_popcount32 (7) = 3
429 ecb_popcount32 (255) = 8 564 ecb_popcount32 (255) = 8
430 565
566=item uint8_t ecb_bitrev8 (uint8_t x)
567
568=item uint16_t ecb_bitrev16 (uint16_t x)
569
570=item uint32_t ecb_bitrev32 (uint32_t x)
571
572Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
573and so on.
574
575Example:
576
577 ecb_bitrev8 (0xa7) = 0xea
578 ecb_bitrev32 (0xffcc4411) = 0x882233ff
579
431=item uint32_t ecb_bswap16 (uint32_t x) 580=item uint32_t ecb_bswap16 (uint32_t x)
432 581
433=item uint32_t ecb_bswap32 (uint32_t x) 582=item uint32_t ecb_bswap32 (uint32_t x)
434 583
584=item uint64_t ecb_bswap64 (uint64_t x)
585
435These two functions return the value of the 16-bit (32-bit) value C<x> 586These functions return the value of the 16-bit (32-bit, 64-bit) value
436after reversing the order of bytes (0x11223344 becomes 0x44332211). 587C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
588C<ecb_bswap32>).
589
590=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
591
592=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
593
594=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
595
596=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
597
598=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
599
600=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
437 601
438=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count) 602=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
439 603
440=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 604=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
441 605
442These two functions return the value of C<x> after rotating all the bits 606These two families of functions return the value of C<x> after rotating
443by C<count> positions to the right or left respectively. 607all the bits by C<count> positions to the right (C<ecb_rotr>) or left
608(C<ecb_rotl>).
444 609
445Current GCC versions understand these functions and usually compile them 610Current GCC versions understand these functions and usually compile them
446to "optimal" code (e.g. a single C<roll> on x86). 611to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
612x86).
613
614=back
615
616=head2 FLOATING POINT FIDDLING
617
618=over 4
619
620=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
621
622=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
623
624These functions each take an argument in the native C<float> or C<double>
625type and return the IEEE 754 bit representation of it.
626
627The bit representation is just as IEEE 754 defines it, i.e. the sign bit
628will be the most significant bit, followed by exponent and mantissa.
629
630This function should work even when the native floating point format isn't
631IEEE compliant, of course at a speed and code size penalty, and of course
632also within reasonable limits (it tries to convert NaNs, infinities and
633denormals, but will likely convert negative zero to positive zero).
634
635On all modern platforms (where C<ECB_STDFP> is true), the compiler should
636be able to optimise away this function completely.
637
638These functions can be helpful when serialising floats to the network - you
639can serialise the return value like a normal uint32_t/uint64_t.
640
641Another use for these functions is to manipulate floating point values
642directly.
643
644Silly example: toggle the sign bit of a float.
645
646 /* On gcc-4.7 on amd64, */
647 /* this results in a single add instruction to toggle the bit, and 4 extra */
648 /* instructions to move the float value to an integer register and back. */
649
650 x = ecb_binary32_to_float (ecb_float_to_binary32 (x) ^ 0x80000000U)
651
652=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
653
654=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM]
655
656The reverse operation of the previos function - takes the bit representation
657of an IEEE binary32 or binary64 number and converts it to the native C<float>
658or C<double> format.
659
660This function should work even when the native floating point format isn't
661IEEE compliant, of course at a speed and code size penalty, and of course
662also within reasonable limits (it tries to convert normals and denormals,
663and might be lucky for infinities, and with extraordinary luck, also for
664negative zero).
665
666On all modern platforms (where C<ECB_STDFP> is true), the compiler should
667be able to optimise away this function completely.
447 668
448=back 669=back
449 670
450=head2 ARITHMETIC 671=head2 ARITHMETIC
451 672
… …
475change direction for negative values: 696change direction for negative values:
476 697
477 for (m = -100; m <= 100; ++m) 698 for (m = -100; m <= 100; ++m)
478 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))]; 699 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
479 700
701=item x = ecb_div_rd (val, div)
702
703=item x = ecb_div_ru (val, div)
704
705Returns C<val> divided by C<div> rounded down or up, respectively.
706C<val> and C<div> must have integer types and C<div> must be strictly
707positive. Note that these functions are implemented with macros in C
708and with function templates in C++.
709
480=back 710=back
481 711
482=head2 UTILITY 712=head2 UTILITY
483 713
484=over 4 714=over 4
… …
493 for (i = 0; i < ecb_array_length (primes); i++) 723 for (i = 0; i < ecb_array_length (primes); i++)
494 sum += primes [i]; 724 sum += primes [i];
495 725
496=back 726=back
497 727
728=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
498 729
730These symbols need to be defined before including F<ecb.h> the first time.
731
732=over 4
733
734=item ECB_NO_THREADS
735
736If F<ecb.h> is never used from multiple threads, then this symbol can
737be defined, in which case memory fences (and similar constructs) are
738completely removed, leading to more efficient code and fewer dependencies.
739
740Setting this symbol to a true value implies C<ECB_NO_SMP>.
741
742=item ECB_NO_SMP
743
744The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
745multiple threads, but never concurrently (e.g. if the system the program
746runs on has only a single CPU with a single core, no hyperthreading and so
747on), then this symbol can be defined, leading to more efficient code and
748fewer dependencies.
749
750=item ECB_NO_LIBM
751
752When defined to C<1>, do not export any functions that might introduce
753dependencies on the math library (usually called F<-lm>) - these are
754marked with [-UECB_NO_LIBM].
755
756=back
757
758

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines