Revision 1.67 by

Revision 1.72 by

… | … | ||
---|---|---|---|

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 | ||

693 | Evaluates to positive infinity if supported by the platform, otherwise to | 693 | Evaluates to positive infinity if supported by the platform, otherwise to |

694 | a truly huge number. | 694 | a truly huge number. |

695 | 695 | ||

696 | =item ECB_NAN | 696 | =item ECB_NAN [-UECB_NO_LIBM] |

697 | 697 | ||

698 | Evaluates to a quiet NAN if supported by the platform, otherwise to | 698 | Evaluates to a quiet NAN if supported by the platform, otherwise to |

699 | C<ECB_INFINITY>. | 699 | C<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 | ||

703 | Same as C<ldexpf>, but always available. | 703 | Same 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 | ||

709 | These functions each take an argument in the native C<float> or C<double> | 711 | These functions each take an argument in the native C<float> or C<double> |

710 | type and return the IEEE 754 bit representation of it. | 712 | type and return the IEEE 754 bit representation of it (binary16/half, |

713 | binary32/single or binary64/double precision). | ||

711 | 714 | ||

712 | The bit representation is just as IEEE 754 defines it, i.e. the sign bit | 715 | The bit representation is just as IEEE 754 defines it, i.e. the sign bit |

713 | will be the most significant bit, followed by exponent and mantissa. | 716 | will be the most significant bit, followed by exponent and mantissa. |

714 | 717 | ||

715 | This function should work even when the native floating point format isn't | 718 | This function should work even when the native floating point format isn't |

… | … | ||

719 | 722 | ||

720 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should | 723 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should |

721 | be able to optimise away this function completely. | 724 | be able to optimise away this function completely. |

722 | 725 | ||

723 | These functions can be helpful when serialising floats to the network - you | 726 | These functions can be helpful when serialising floats to the network - you |

724 | can serialise the return value like a normal uint32_t/uint64_t. | 727 | can serialise the return value like a normal uint16_t/uint32_t/uint64_t. |

725 | 728 | ||

726 | Another use for these functions is to manipulate floating point values | 729 | Another use for these functions is to manipulate floating point values |

727 | directly. | 730 | directly. |

728 | 731 | ||

729 | Silly example: toggle the sign bit of a float. | 732 | Silly 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 | ||

743 | The reverse operation of the previous function - takes the bit | 746 | The reverse operation of the previous function - takes the bit |

744 | representation of an IEEE binary16, binary32 or binary64 number and | 747 | representation of an IEEE binary16, binary32 or binary64 number (half, |

745 | converts it to the native C<float> or C<double> format. | 748 | single or double precision) and converts it to the native C<float> or |

749 | C<double> format. | ||

746 | 750 | ||

747 | This function should work even when the native floating point format isn't | 751 | This function should work even when the native floating point format isn't |

748 | IEEE compliant, of course at a speed and code size penalty, and of course | 752 | IEEE compliant, of course at a speed and code size penalty, and of course |

749 | also within reasonable limits (it tries to convert normals and denormals, | 753 | also within reasonable limits (it tries to convert normals and denormals, |

750 | and might be lucky for infinities, and with extraordinary luck, also for | 754 | and might be lucky for infinities, and with extraordinary luck, also for |

751 | negative zero). | 755 | negative zero). |

752 | 756 | ||

753 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should | 757 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should |

754 | be able to optimise away this function completely. | 758 | be 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 | |||

764 | Convert a IEEE binary32/single precision to binary16/half format, and vice | ||

765 | versa, handling all details (round-to-nearest-even, subnormals, infinity | ||

766 | and NaNs) correctly. | ||

767 | |||

768 | These are functions are available under C<-DECB_NO_LIBM>, since | ||

769 | they do not rely on the platform floating point format. The | ||

770 | C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are | ||

771 | usually what you want. | ||

755 | 772 | ||

756 | =back | 773 | =back |

757 | 774 | ||

758 | =head2 ARITHMETIC | 775 | =head2 ARITHMETIC |

759 | 776 | ||

… | … | ||

840 | dependencies on the math library (usually called F<-lm>) - these are | 857 | dependencies on the math library (usually called F<-lm>) - these are |

841 | marked with [-UECB_NO_LIBM]. | 858 | marked with [-UECB_NO_LIBM]. |

842 | 859 | ||

843 | =back | 860 | =back |

844 | 861 | ||

862 | =head1 UNDOCUMENTED FUNCTIONALITY | ||

845 | 863 | ||

864 | F<ecb.h> is full of undocumented functionality as well, some of which is | ||

865 | intended to be internal-use only, some of which we forgot to document, and | ||

866 | some of which we hide because we are not sure we will keep the interface | ||

867 | stable. | ||

868 | |||

869 | While 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 | ||

871 | functionality in incompatible ways without thinking twice, while we are | ||

872 | considerably more conservative with documented things. | ||

873 | |||

874 | =head1 AUTHORS | ||

875 | |||

876 | C<libecb> is designed and maintained by: | ||

877 | |||

878 | Emanuele Giaquinta <e.giaquinta@glauco.it> | ||

879 | Marc Alexander Lehmann <schmorp@schmorp.de> | ||

880 | |||

881 |

– |
Removed lines |

+ |
Added lines |

< |
Changed lines |

> |
Changed lines |