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

Comparing libecb/ecb.pod (file contents):
Revision 1.39 by root, Sat Dec 10 11:58:38 2011 UTC vs.
Revision 1.50 by root, Thu Jun 28 20:20:27 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
… …
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
… …
502(C<ecb_rotl>). 608(C<ecb_rotl>).
503 609
504Current GCC versions understand these functions and usually compile them 610Current GCC versions understand these functions and usually compile them
505to "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
506x86). 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.
507 668
508=back 669=back
509 670
510=head2 ARITHMETIC 671=head2 ARITHMETIC
511 672
… …
562 for (i = 0; i < ecb_array_length (primes); i++) 723 for (i = 0; i < ecb_array_length (primes); i++)
563 sum += primes [i]; 724 sum += primes [i];
564 725
565=back 726=back
566 727
728=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
567 729
730These symbols need to be defined before including F<ecb.h> the first time.
731
732=over 4
733
734=item ECB_NO_THRADS
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