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.70 by root, Tue Sep 1 16:14:42 2015 UTC vs.
Revision 1.71 by root, Sat Nov 21 16:53:50 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.
… …
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_binary64_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-even, subnormals, infinity and NaNs)
766correctly.
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

Diff Legend

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