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

Comparing libecb/ecb.pod (file contents):
Revision 1.66 by sf-exg, Fri Feb 20 11:28:08 2015 UTC vs.
Revision 1.75 by root, Sat Dec 28 08:01:05 2019 UTC

… …
66 66
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this 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 68platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions. 69expressions.
70 70
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>. 71For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
72 72
73=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS 73=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
74 74
75All the following symbols expand to an expression that can be tested in 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 76preprocessor instructions as well as treated as a boolean (use C<!!> to
… …
899899:1999) or any later version, while not claiming to be C++. 899899:1999) or any later version, while not claiming to be C++.
90 90
91Note that later versions (ECB_C11) remove core features again (for 91Note that later versions (ECB_C11) remove core features again (for
92example, variable length arrays). 92example, variable length arrays).
93 93
94=item ECB_C11 94=item ECB_C11, ECB_C17
95 95
96True if the implementation claims to be compliant to C11 (ISO/IEC 96True if the implementation claims to be compliant to C11/C17 (ISO/IEC
979899:2011) or any later version, while not claiming to be C++. 979899:2011, :20187) or any later version, while not claiming to be C++.
98 98
99=item ECB_CPP 99=item ECB_CPP
100 100
101True if the implementation defines the C<__cplusplus__> macro to a true 101True if the implementation defines the C<__cplusplus__> macro to a true
102value, which is typically true for C++ compilers. 102value, which is typically true for C++ compilers.
103 103
104=item ECB_CPP11 104=item ECB_CPP11, ECB_CPP14, ECB_CPP17
105 105
106True if the implementation claims to be compliant to ISO/IEC 14882:2011 106True if the implementation claims to be compliant to C++11/C++14/C++17
107(C++11) or any later version. 107(ISO/IEC 14882:2011, :2014, :2017) or any later version.
108 108
109=item ECB_GCC_VERSION (major, minor) 109=item ECB_GCC_VERSION (major, minor)
110 110
111Expands to a true value (suitable for testing in by the preprocessor) 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 112if the compiler used is GNU C and the version is the given version, or
… …
242Similar to C<ecb_unused>, but marks a function, variable or type as 242Similar to C<ecb_unused>, but marks a function, variable or type as
243deprecated. This makes some compilers warn when the type is used. 243deprecated. This makes some compilers warn when the type is used.
244 244
245=item ecb_deprecated_message (message) 245=item ecb_deprecated_message (message)
246 246
247Same as C<ecb_deprecated>, but if possible, supplies a diagnostic that is 247Same as C<ecb_deprecated>, but if possible, the specified diagnostic is
248used instead of a generic depreciation message when the object is being 248used instead of a generic depreciation message when the object is being
249used. 249used.
250 250
251=item ecb_inline 251=item ecb_inline
252 252
253Expands either to C<static inline> or to just C<static>, if inline 253Expands either to (a compiler-specific equivalent of) C<static inline> or
254isn't supported. It should be used to declare functions that should be 254to just C<static>, if inline isn't supported. It should be used to declare
255inlined, for code size or speed reasons. 255functions that should be inlined, for code size or speed reasons.
256 256
257Example: inline this function, it surely will reduce codesize. 257Example: inline this function, it surely will reduce codesize.
258 258
259 ecb_inline int 259 ecb_inline int
260 negmul (int a, int b) 260 negmul (int a, int b)
… …
401=back 401=back
402 402
403=head2 OPTIMISATION HINTS 403=head2 OPTIMISATION HINTS
404 404
405=over 4 405=over 4
406
407=item ECB_OPTIMIZE_SIZE
408
409Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
410can also be defined before including F<ecb.h>, in which case it will be
411unchanged.
406 412
407=item bool ecb_is_constant (expr) 413=item bool ecb_is_constant (expr)
408 414
409Returns true iff the expression can be deduced to be a compile-time 415Returns true iff the expression can be deduced to be a compile-time
410constant, and false otherwise. 416constant, and false otherwise.
… …
686 692
687=head2 FLOATING POINT FIDDLING 693=head2 FLOATING POINT FIDDLING
688 694
689=over 4 695=over 4
690 696
691=item ECB_INFINITY 697=item ECB_INFINITY [-UECB_NO_LIBM]
692 698
693Evaluates to positive infinity if supported by the platform, otherwise to 699Evaluates to positive infinity if supported by the platform, otherwise to
694a truly huge number. 700a truly huge number.
695 701
696=item ECB_NAN 702=item ECB_NAN [-UECB_NO_LIBM]
697 703
698Evaluates to a quiet NAN if supported by the platform, otherwise to 704Evaluates to a quiet NAN if supported by the platform, otherwise to
699C<ECB_INFINITY>. 705C<ECB_INFINITY>.
700 706
701=item float ecb_ldexpf (float x, int exp) 707=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
702 708
703Same as C<ldexpf>, but always available. 709Same as C<ldexpf>, but always available.
704 710
711=item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
712
705=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM] 713=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
706 714
707=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM] 715=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
708 716
709These functions each take an argument in the native C<float> or C<double> 717These functions each take an argument in the native C<float> or C<double>
710type and return the IEEE 754 bit representation of it. 718type and return the IEEE 754 bit representation of it (binary16/half,
719binary32/single or binary64/double precision).
711 720
712The bit representation is just as IEEE 754 defines it, i.e. the sign bit 721The bit representation is just as IEEE 754 defines it, i.e. the sign bit
713will be the most significant bit, followed by exponent and mantissa. 722will be the most significant bit, followed by exponent and mantissa.
714 723
715This function should work even when the native floating point format isn't 724This function should work even when the native floating point format isn't
… …
719 728
720On all modern platforms (where C<ECB_STDFP> is true), the compiler should 729On all modern platforms (where C<ECB_STDFP> is true), the compiler should
721be able to optimise away this function completely. 730be able to optimise away this function completely.
722 731
723These functions can be helpful when serialising floats to the network - you 732These functions can be helpful when serialising floats to the network - you
724can serialise the return value like a normal uint32_t/uint64_t. 733can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
725 734
726Another use for these functions is to manipulate floating point values 735Another use for these functions is to manipulate floating point values
727directly. 736directly.
728 737
729Silly example: toggle the sign bit of a float. 738Silly example: toggle the sign bit of a float.
… …
736 745
737=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM] 746=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
738 747
739=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM] 748=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
740 749
741=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM] 750=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
742 751
743The reverse operation of the previous function - takes the bit 752The reverse operation of the previous function - takes the bit
744representation of an IEEE binary16, binary32 or binary64 number and 753representation of an IEEE binary16, binary32 or binary64 number (half,
745converts it to the native C<float> or C<double> format. 754single or double precision) and converts it to the native C<float> or
755C<double> format.
746 756
747This function should work even when the native floating point format isn't 757This function should work even when the native floating point format isn't
748IEEE compliant, of course at a speed and code size penalty, and of course 758IEEE compliant, of course at a speed and code size penalty, and of course
749also within reasonable limits (it tries to convert normals and denormals, 759also within reasonable limits (it tries to convert normals and denormals,
750and might be lucky for infinities, and with extraordinary luck, also for 760and might be lucky for infinities, and with extraordinary luck, also for
751negative zero). 761negative zero).
752 762
753On all modern platforms (where C<ECB_STDFP> is true), the compiler should 763On all modern platforms (where C<ECB_STDFP> is true), the compiler should
754be able to optimise away this function completely. 764be able to optimise away this function completely.
765
766=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
767
768=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
769
770Convert a IEEE binary32/single precision to binary16/half format, and vice
771versa, handling all details (round-to-nearest-even, subnormals, infinity
772and NaNs) correctly.
773
774These are functions are available under C<-DECB_NO_LIBM>, since
775they do not rely on the platform floating point format. The
776C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
777usually what you want.
755 778
756=back 779=back
757 780
758=head2 ARITHMETIC 781=head2 ARITHMETIC
759 782
… …
840dependencies on the math library (usually called F<-lm>) - these are 863dependencies on the math library (usually called F<-lm>) - these are
841marked with [-UECB_NO_LIBM]. 864marked with [-UECB_NO_LIBM].
842 865
843=back 866=back
844 867
868=head1 UNDOCUMENTED FUNCTIONALITY
845 869
870F<ecb.h> is full of undocumented functionality as well, some of which is
871intended to be internal-use only, some of which we forgot to document, and
872some of which we hide because we are not sure we will keep the interface
873stable.
874
875While you are welcome to rummage around and use whatever you find useful
876(we can't stop you), keep in mind that we will change undocumented
877functionality in incompatible ways without thinking twice, while we are
878considerably more conservative with documented things.
879
880=head1 AUTHORS
881
882C<libecb> is designed and maintained by:
883
884 Emanuele Giaquinta <e.giaquinta@glauco.it>
885 Marc Alexander Lehmann <schmorp@schmorp.de>
886
887

Diff Legend

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