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

Comparing libecb/ecb.pod (file contents):
Revision 1.67 by root, Fri Feb 20 15:53:36 2015 UTC vs.
Revision 1.72 by root, Sat Nov 21 18:09:37 2015 UTC

… …
686 686
687=head2 FLOATING POINT FIDDLING 687=head2 FLOATING POINT FIDDLING
688 688
689=over 4 689=over 4
690 690
691=item ECB_INFINITY 691=item ECB_INFINITY [-UECB_NO_LIBM]
692 692
693Evaluates to positive infinity if supported by the platform, otherwise to 693Evaluates to positive infinity if supported by the platform, otherwise to
694a truly huge number. 694a truly huge number.
695 695
696=item ECB_NAN 696=item ECB_NAN [-UECB_NO_LIBM]
697 697
698Evaluates to a quiet NAN if supported by the platform, otherwise to 698Evaluates to a quiet NAN if supported by the platform, otherwise to
699C<ECB_INFINITY>. 699C<ECB_INFINITY>.
700 700
701=item float ecb_ldexpf (float x, int exp) 701=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
702 702
703Same as C<ldexpf>, but always available. 703Same as C<ldexpf>, but always available.
704 704
705=item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
706
705=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM] 707=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
706 708
707=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM] 709=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
708 710
709These functions each take an argument in the native C<float> or C<double> 711These functions each take an argument in the native C<float> or C<double>
710type and return the IEEE 754 bit representation of it. 712type and return the IEEE 754 bit representation of it (binary16/half,
713binary32/single or binary64/double precision).
711 714
712The bit representation is just as IEEE 754 defines it, i.e. the sign bit 715The 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. 716will be the most significant bit, followed by exponent and mantissa.
714 717
715This function should work even when the native floating point format isn't 718This function should work even when the native floating point format isn't
… …
719 722
720On all modern platforms (where C<ECB_STDFP> is true), the compiler should 723On all modern platforms (where C<ECB_STDFP> is true), the compiler should
721be able to optimise away this function completely. 724be able to optimise away this function completely.
722 725
723These functions can be helpful when serialising floats to the network - you 726These functions can be helpful when serialising floats to the network - you
724can serialise the return value like a normal uint32_t/uint64_t. 727can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
725 728
726Another use for these functions is to manipulate floating point values 729Another use for these functions is to manipulate floating point values
727directly. 730directly.
728 731
729Silly example: toggle the sign bit of a float. 732Silly example: toggle the sign bit of a float.
… …
736 739
737=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM] 740=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
738 741
739=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM] 742=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
740 743
741=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM] 744=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
742 745
743The reverse operation of the previous function - takes the bit 746The reverse operation of the previous function - takes the bit
744representation of an IEEE binary16, binary32 or binary64 number and 747representation of an IEEE binary16, binary32 or binary64 number (half,
745converts it to the native C<float> or C<double> format. 748single or double precision) and converts it to the native C<float> or
749C<double> format.
746 750
747This function should work even when the native floating point format isn't 751This 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 752IEEE compliant, of course at a speed and code size penalty, and of course
749also within reasonable limits (it tries to convert normals and denormals, 753also within reasonable limits (it tries to convert normals and denormals,
750and might be lucky for infinities, and with extraordinary luck, also for 754and might be lucky for infinities, and with extraordinary luck, also for
751negative zero). 755negative zero).
752 756
753On all modern platforms (where C<ECB_STDFP> is true), the compiler should 757On all modern platforms (where C<ECB_STDFP> is true), the compiler should
754be able to optimise away this function completely. 758be able to optimise away this function completely.
759
760=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
761
762=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
763
764Convert a IEEE binary32/single precision to binary16/half format, and vice
765versa, handling all details (round-to-nearest-even, subnormals, infinity
766and NaNs) correctly.
767
768These are functions are available under C<-DECB_NO_LIBM>, since
769they do not rely on the platform floating point format. The
770C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
771usually what you want.
755 772
756=back 773=back
757 774
758=head2 ARITHMETIC 775=head2 ARITHMETIC
759 776
… …
840dependencies on the math library (usually called F<-lm>) - these are 857dependencies on the math library (usually called F<-lm>) - these are
841marked with [-UECB_NO_LIBM]. 858marked with [-UECB_NO_LIBM].
842 859
843=back 860=back
844 861
862=head1 UNDOCUMENTED FUNCTIONALITY
845 863
864F<ecb.h> is full of undocumented functionality as well, some of which is
865intended to be internal-use only, some of which we forgot to document, and
866some of which we hide because we are not sure we will keep the interface
867stable.
868
869While you are welcome to rummage around and use whatever you find useful
870(we can't stop you), keep in mind that we will change undocumented
871functionality in incompatible ways without thinking twice, while we are
872considerably more conservative with documented things.
873
874=head1 AUTHORS
875
876C<libecb> is designed and maintained by:
877
878 Emanuele Giaquinta <e.giaquinta@glauco.it>
879 Marc Alexander Lehmann <schmorp@schmorp.de>
880
881

Diff Legend

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