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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.37 by sf-exg, Wed Aug 24 23:28:47 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,
… …
425For example: 523For example:
426 524
427 ecb_ctz32 (3) = 0 525 ecb_ctz32 (3) = 0
428 ecb_ctz32 (6) = 1 526 ecb_ctz32 (6) = 1
429 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
430=item int ecb_ld32 (uint32_t x) 536=item int ecb_ld32 (uint32_t x)
431 537
432=item int ecb_ld64 (uint64_t x) 538=item int ecb_ld64 (uint64_t x)
433 539
434Returns the index of the most significant bit set in C<x>, or the number 540Returns the index of the most significant bit set in C<x>, or the number
… …
455For example: 561For example:
456 562
457 ecb_popcount32 (7) = 3 563 ecb_popcount32 (7) = 3
458 ecb_popcount32 (255) = 8 564 ecb_popcount32 (255) = 8
459 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
460=item uint32_t ecb_bswap16 (uint32_t x) 580=item uint32_t ecb_bswap16 (uint32_t x)
461 581
462=item uint32_t ecb_bswap32 (uint32_t x) 582=item uint32_t ecb_bswap32 (uint32_t x)
463 583
464=item uint64_t ecb_bswap64 (uint64_t x) 584=item uint64_t ecb_bswap64 (uint64_t x)
… …
488(C<ecb_rotl>). 608(C<ecb_rotl>).
489 609
490Current GCC versions understand these functions and usually compile them 610Current GCC versions understand these functions and usually compile them
491to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 611to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
492x86). 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.
493 668
494=back 669=back
495 670
496=head2 ARITHMETIC 671=head2 ARITHMETIC
497 672
… …
527 702
528=item x = ecb_div_ru (val, div) 703=item x = ecb_div_ru (val, div)
529 704
530Returns C<val> divided by C<div> rounded down or up, respectively. 705Returns C<val> divided by C<div> rounded down or up, respectively.
531C<val> and C<div> must have integer types and C<div> must be strictly 706C<val> and C<div> must have integer types and C<div> must be strictly
532positive. 707positive. Note that these functions are implemented with macros in C
708and with function templates in C++.
533 709
534=back 710=back
535 711
536=head2 UTILITY 712=head2 UTILITY
537 713
… …
547 for (i = 0; i < ecb_array_length (primes); i++) 723 for (i = 0; i < ecb_array_length (primes); i++)
548 sum += primes [i]; 724 sum += primes [i];
549 725
550=back 726=back
551 727
728=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
552 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