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

Comparing libecb/ecb.pod (file contents):
Revision 1.49 by root, Thu Jun 28 14:50:01 2012 UTC vs.
Revision 1.50 by root, Thu Jun 28 20:20:27 2012 UTC

… …
112if the compiler used is GNU C and the version is the given version, or 112if the compiler used is GNU C and the version is the given version, or
113higher. 113higher.
114 114
115This macro tries to return false on compilers that claim to be GCC 115This macro tries to return false on compilers that claim to be GCC
116compatible but aren't. 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.
117 154
118=back 155=back
119 156
120=head2 GCC ATTRIBUTES 157=head2 GCC ATTRIBUTES
121 158
… …
574to "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
575x86). 612x86).
576 613
577=back 614=back
578 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.
668
669=back
670
579=head2 ARITHMETIC 671=head2 ARITHMETIC
580 672
581=over 4 673=over 4
582 674
583=item x = ecb_mod (m, n) 675=item x = ecb_mod (m, n)
… …
653multiple threads, but never concurrently (e.g. if the system the program 745multiple threads, but never concurrently (e.g. if the system the program
654runs on has only a single CPU with a single core, no hyperthreading and so 746runs on has only a single CPU with a single core, no hyperthreading and so
655on), then this symbol can be defined, leading to more efficient code and 747on), then this symbol can be defined, leading to more efficient code and
656fewer dependencies. 748fewer dependencies.
657 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
658=back 756=back
659 757
660 758

Diff Legend

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