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

Comparing libecb/ecb.pod (file contents):
Revision 1.69 by sf-exg, Sun Feb 22 20:17:20 2015 UTC vs.
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC

58 58
59=head2 TYPES / TYPE SUPPORT 59=head2 TYPES / TYPE SUPPORT
60 60
61ecb.h makes sure that the following types are defined (in the expected way): 61ecb.h makes sure that the following types are defined (in the expected way):
62 62
63 int8_t uint8_t int16_t uint16_t 63 int8_t uint8_
64 int32_t uint32_t int64_t uint64_t 64 int16_t uint16_t
65 int32_t uint32_
66 int64_t uint64_t
67 int_fast8_t uint_fast8_t
68 int_fast16_t uint_fast16_t
69 int_fast32_t uint_fast32_t
70 int_fast64_t uint_fast64_t
65 intptr_t uintptr_t 71 intptr_t uintptr_t
66 72
67The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this 73The 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 74platform (currently C<4> or C<8>) and can be used in preprocessor
69expressions. 75expressions.
70 76
71For C<ptrdiff_t> and C<size_t> use C<stddef.h>. 77For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
72 78
73=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS 79=head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
74 80
75All the following symbols expand to an expression that can be tested in 81All the following symbols expand to an expression that can be tested in
76preprocessor instructions as well as treated as a boolean (use C<!!> to 82preprocessor instructions as well as treated as a boolean (use C<!!> to
899899:1999) or any later version, while not claiming to be C++. 959899:1999) or any later version, while not claiming to be C++.
90 96
91Note that later versions (ECB_C11) remove core features again (for 97Note that later versions (ECB_C11) remove core features again (for
92example, variable length arrays). 98example, variable length arrays).
93 99
94=item ECB_C11 100=item ECB_C11, ECB_C17
95 101
96True if the implementation claims to be compliant to C11 (ISO/IEC 102True if the implementation claims to be compliant to C11/C17 (ISO/IEC
979899:2011) or any later version, while not claiming to be C++. 1039899:2011, :20187) or any later version, while not claiming to be C++.
98 104
99=item ECB_CPP 105=item ECB_CPP
100 106
101True if the implementation defines the C<__cplusplus__> macro to a true 107True if the implementation defines the C<__cplusplus__> macro to a true
102value, which is typically true for C++ compilers. 108value, which is typically true for C++ compilers.
103 109
104=item ECB_CPP11 110=item ECB_CPP11, ECB_CPP14, ECB_CPP17
105 111
106True if the implementation claims to be compliant to ISO/IEC 14882:2011 112True if the implementation claims to be compliant to C++11/C++14/C++17
107(C++11) or any later version. 113(ISO/IEC 14882:2011, :2014, :2017) or any later version.
114
115=item ECB_OPTIMIZE_SIZE
116
117Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
118can also be defined before including F<ecb.h>, in which case it will be
119unchanged.
108 120
109=item ECB_GCC_VERSION (major, minor) 121=item ECB_GCC_VERSION (major, minor)
110 122
111Expands to a true value (suitable for testing in by the preprocessor) 123Expands 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 124if the compiler used is GNU C and the version is the given version, or
248used instead of a generic depreciation message when the object is being 260used instead of a generic depreciation message when the object is being
249used. 261used.
250 262
251=item ecb_inline 263=item ecb_inline
252 264
253Expands either to C<static inline> or to just C<static>, if inline 265Expands either to (a compiler-specific equivalent of) C<static inline> or
254isn't supported. It should be used to declare functions that should be 266to just C<static>, if inline isn't supported. It should be used to declare
255inlined, for code size or speed reasons. 267functions that should be inlined, for code size or speed reasons.
256 268
257Example: inline this function, it surely will reduce codesize. 269Example: inline this function, it surely will reduce codesize.
258 270
259 ecb_inline int 271 ecb_inline int
260 negmul (int a, int b) 272 negmul (int a, int b)
583 595
584=item int ecb_ctz32 (uint32_t x) 596=item int ecb_ctz32 (uint32_t x)
585 597
586=item int ecb_ctz64 (uint64_t x) 598=item int ecb_ctz64 (uint64_t x)
587 599
600=item int ecb_ctz (T x) [C++]
601
588Returns the index of the least significant bit set in C<x> (or 602Returns the index of the least significant bit set in C<x> (or
589equivalently the number of bits set to 0 before the least significant bit 603equivalently the number of bits set to 0 before the least significant bit
590set), starting from 0. If C<x> is 0 the result is undefined. 604set), starting from 0. If C<x> is 0 the result is undefined.
591 605
592For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>. 606For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
593 607
608The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
609C<uint32_t> and C<uint64_t> types.
610
594For example: 611For example:
595 612
596 ecb_ctz32 (3) = 0 613 ecb_ctz32 (3) = 0
597 ecb_ctz32 (6) = 1 614 ecb_ctz32 (6) = 1
598 615
599=item bool ecb_is_pot32 (uint32_t x) 616=item bool ecb_is_pot32 (uint32_t x)
600 617
601=item bool ecb_is_pot64 (uint32_t x) 618=item bool ecb_is_pot64 (uint32_t x)
602 619
620=item bool ecb_is_pot (T x) [C++]
621
603Returns true iff C<x> is a power of two or C<x == 0>. 622Returns true iff C<x> is a power of two or C<x == 0>.
604 623
605For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>. 624For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
606 625
626The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
627C<uint32_t> and C<uint64_t> types.
628
607=item int ecb_ld32 (uint32_t x) 629=item int ecb_ld32 (uint32_t x)
608 630
609=item int ecb_ld64 (uint64_t x) 631=item int ecb_ld64 (uint64_t x)
632
633=item int ecb_ld64 (T x) [C++]
610 634
611Returns the index of the most significant bit set in C<x>, or the number 635Returns the index of the most significant bit set in C<x>, or the number
612of digits the number requires in binary (so that C<< 2**ld <= x < 636of digits the number requires in binary (so that C<< 2**ld <= x <
6132**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is 6372**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
614to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for 638to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
619the given data type), while C<ecb_ld> returns how many bits the number 643the given data type), while C<ecb_ld> returns how many bits the number
620itself requires. 644itself requires.
621 645
622For smaller types than C<uint32_t> you can safely use C<ecb_ld32>. 646For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
623 647
648The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
649C<uint32_t> and C<uint64_t> types.
650
624=item int ecb_popcount32 (uint32_t x) 651=item int ecb_popcount32 (uint32_t x)
625 652
626=item int ecb_popcount64 (uint64_t x) 653=item int ecb_popcount64 (uint64_t x)
627 654
655=item int ecb_popcount (T x) [C++]
656
628Returns the number of bits set to 1 in C<x>. 657Returns the number of bits set to 1 in C<x>.
629 658
630For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>. 659For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
660
661The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
662C<uint32_t> and C<uint64_t> types.
631 663
632For example: 664For example:
633 665
634 ecb_popcount32 (7) = 3 666 ecb_popcount32 (7) = 3
635 ecb_popcount32 (255) = 8 667 ecb_popcount32 (255) = 8
638 670
639=item uint16_t ecb_bitrev16 (uint16_t x) 671=item uint16_t ecb_bitrev16 (uint16_t x)
640 672
641=item uint32_t ecb_bitrev32 (uint32_t x) 673=item uint32_t ecb_bitrev32 (uint32_t x)
642 674
675=item T ecb_bitrev (T x) [C++]
676
643Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1 677Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
644and so on. 678and so on.
645 679
680The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
681
646Example: 682Example:
647 683
648 ecb_bitrev8 (0xa7) = 0xea 684 ecb_bitrev8 (0xa7) = 0xea
649 ecb_bitrev32 (0xffcc4411) = 0x882233ff 685 ecb_bitrev32 (0xffcc4411) = 0x882233ff
650 686
687=item T ecb_bitrev (T x) [C++]
688
689Overloaded C++ bitrev function.
690
691C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
692
651=item uint32_t ecb_bswap16 (uint32_t x) 693=item uint32_t ecb_bswap16 (uint32_t x)
652 694
653=item uint32_t ecb_bswap32 (uint32_t x) 695=item uint32_t ecb_bswap32 (uint32_t x)
654 696
655=item uint64_t ecb_bswap64 (uint64_t x) 697=item uint64_t ecb_bswap64 (uint64_t x)
698
699=item T ecb_bswap (T x)
656 700
657These functions return the value of the 16-bit (32-bit, 64-bit) value 701These functions return the value of the 16-bit (32-bit, 64-bit) value
658C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in 702C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
659C<ecb_bswap32>). 703C<ecb_bswap32>).
660 704
705The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
706C<uint32_t> and C<uint64_t> types.
707
661=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count) 708=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
662 709
663=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count) 710=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
664 711
665=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count) 712=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
680 727
681Current GCC versions understand these functions and usually compile them 728Current GCC versions understand these functions and usually compile them
682to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 729to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
683x86). 730x86).
684 731
732=item T ecb_rotl (T x, unsigned int count) [C++]
733
734=item T ecb_rotr (T x, unsigned int count) [C++]
735
736Overloaded C++ rotl/rotr functions.
737
738C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
739
685=back 740=back
686 741
742=head2 HOST ENDIANNESS CONVERSION
743
744=over 4
745
746=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
747
748=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
749
750=item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
751
752=item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
753
754=item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
755
756=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
757
758Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
759
760The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>,
761where C<be> and C<le> stand for big endian and little endian, respectively.
762
763=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
764
765=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
766
767=item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
768
769=item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
770
771=item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
772
773=item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
774
775Like above, but converts I<from> host byte order to the specified
776endianness.
777
778=back
779
780In C++ the following additional template functions are supported:
781
782=over 4
783
784=item T ecb_be_to_host (T v)
785
786=item T ecb_le_to_host (T v)
787
788=item T ecb_host_to_be (T v)
789
790=item T ecb_host_to_le (T v)
791
792These functions work like their C counterparts, above, but use templates,
793which make them useful in generic code.
794
795C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
796(so unlike their C counterparts, there is a version for C<uint8_t>, which
797again can be useful in generic code).
798
799=head2 UNALIGNED LOAD/STORE
800
801These function load or store unaligned multi-byte values.
802
803=over 4
804
805=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
806
807=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
808
809=item uint_fast64_t ecb_peek_u64_u (const void *ptr)
810
811These functions load an unaligned, unsigned 16, 32 or 64 bit value from
812memory.
813
814=item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
815
816=item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
817
818=item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
819
820=item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
821
822=item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
823
824=item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
825
826Like above, but additionally convert from big endian (C<be>) or little
827endian (C<le>) byte order to host byte order while doing so.
828
829=item ecb_poke_u16_u (void *ptr, uint16_t v)
830
831=item ecb_poke_u32_u (void *ptr, uint32_t v)
832
833=item ecb_poke_u64_u (void *ptr, uint64_t v)
834
835These functions store an unaligned, unsigned 16, 32 or 64 bit value to
836memory.
837
838=item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
839
840=item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
841
842=item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
843
844=item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
845
846=item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
847
848=item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
849
850Like above, but additionally convert from host byte order to big endian
851(C<be>) or little endian (C<le>) byte order while doing so.
852
853=back
854
855In C++ the following additional template functions are supported:
856
857=over 4
858
859=item T ecb_peek<T> (const void *ptr)
860
861=item T ecb_peek_be<T> (const void *ptr)
862
863=item T ecb_peek_le<T> (const void *ptr)
864
865=item T ecb_peek_u<T> (const void *ptr)
866
867=item T ecb_peek_be_u<T> (const void *ptr)
868
869=item T ecb_peek_le_u<T> (const void *ptr)
870
871Similarly to their C counterparts, these functions load an unsigned 8, 16,
87232 or 64 bit value from memory, with optional conversion from big/little
873endian.
874
875Since the type cannot be deduced, it has to be specified explicitly, e.g.
876
877 uint_fast16_t v = ecb_peek<uint16_t> (ptr);
878
879C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
880
881Unlike their C counterparts, these functions support 8 bit quantities
882(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
883all of which hopefully makes them more useful in generic code.
884
885=item ecb_poke (void *ptr, T v)
886
887=item ecb_poke_be (void *ptr, T v)
888
889=item ecb_poke_le (void *ptr, T v)
890
891=item ecb_poke_u (void *ptr, T v)
892
893=item ecb_poke_be_u (void *ptr, T v)
894
895=item ecb_poke_le_u (void *ptr, T v)
896
897Again, similarly to their C counterparts, these functions store an
898unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
899big/little endian.
900
901C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
902
903Unlike their C counterparts, these functions support 8 bit quantities
904(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
905all of which hopefully makes them more useful in generic code.
906
907=back
908
687=head2 FLOATING POINT FIDDLING 909=head2 FLOATING POINT FIDDLING
688 910
689=over 4 911=over 4
690 912
691=item ECB_INFINITY 913=item ECB_INFINITY [-UECB_NO_LIBM]
692 914
693Evaluates to positive infinity if supported by the platform, otherwise to 915Evaluates to positive infinity if supported by the platform, otherwise to
694a truly huge number. 916a truly huge number.
695 917
696=item ECB_NAN 918=item ECB_NAN [-UECB_NO_LIBM]
697 919
698Evaluates to a quiet NAN if supported by the platform, otherwise to 920Evaluates to a quiet NAN if supported by the platform, otherwise to
699C<ECB_INFINITY>. 921C<ECB_INFINITY>.
700 922
701=item float ecb_ldexpf (float x, int exp) 923=item float ecb_ldexpf (float x, int exp) [-UECB_NO_LIBM]
702 924
703Same as C<ldexpf>, but always available. 925Same as C<ldexpf>, but always available.
704 926
927=item uint32_t ecb_float_to_binary16 (float x) [-UECB_NO_LIBM]
928
705=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM] 929=item uint32_t ecb_float_to_binary32 (float x) [-UECB_NO_LIBM]
706 930
707=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM] 931=item uint64_t ecb_double_to_binary64 (double x) [-UECB_NO_LIBM]
708 932
709These functions each take an argument in the native C<float> or C<double> 933These functions each take an argument in the native C<float> or C<double>
710type and return the IEEE 754 bit representation of it. 934type and return the IEEE 754 bit representation of it (binary16/half,
935binary32/single or binary64/double precision).
711 936
712The bit representation is just as IEEE 754 defines it, i.e. the sign bit 937The 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. 938will be the most significant bit, followed by exponent and mantissa.
714 939
715This function should work even when the native floating point format isn't 940This function should work even when the native floating point format isn't
719 944
720On all modern platforms (where C<ECB_STDFP> is true), the compiler should 945On all modern platforms (where C<ECB_STDFP> is true), the compiler should
721be able to optimise away this function completely. 946be able to optimise away this function completely.
722 947
723These functions can be helpful when serialising floats to the network - you 948These functions can be helpful when serialising floats to the network - you
724can serialise the return value like a normal uint32_t/uint64_t. 949can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
725 950
726Another use for these functions is to manipulate floating point values 951Another use for these functions is to manipulate floating point values
727directly. 952directly.
728 953
729Silly example: toggle the sign bit of a float. 954Silly example: toggle the sign bit of a float.
736 961
737=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM] 962=item float ecb_binary16_to_float (uint16_t x) [-UECB_NO_LIBM]
738 963
739=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM] 964=item float ecb_binary32_to_float (uint32_t x) [-UECB_NO_LIBM]
740 965
741=item double ecb_binary32_to_double (uint64_t x) [-UECB_NO_LIBM] 966=item double ecb_binary64_to_double (uint64_t x) [-UECB_NO_LIBM]
742 967
743The reverse operation of the previous function - takes the bit 968The reverse operation of the previous function - takes the bit
744representation of an IEEE binary16, binary32 or binary64 number and 969representation of an IEEE binary16, binary32 or binary64 number (half,
745converts it to the native C<float> or C<double> format. 970single or double precision) and converts it to the native C<float> or
971C<double> format.
746 972
747This function should work even when the native floating point format isn't 973This 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 974IEEE compliant, of course at a speed and code size penalty, and of course
749also within reasonable limits (it tries to convert normals and denormals, 975also within reasonable limits (it tries to convert normals and denormals,
750and might be lucky for infinities, and with extraordinary luck, also for 976and might be lucky for infinities, and with extraordinary luck, also for
751negative zero). 977negative zero).
752 978
753On all modern platforms (where C<ECB_STDFP> is true), the compiler should 979On all modern platforms (where C<ECB_STDFP> is true), the compiler should
754be able to optimise away this function completely. 980be able to optimise away this function completely.
981
982=item uint16_t ecb_binary32_to_binary16 (uint32_t x)
983
984=item uint32_t ecb_binary16_to_binary32 (uint16_t x)
985
986Convert a IEEE binary32/single precision to binary16/half format, and vice
987versa, handling all details (round-to-nearest-even, subnormals, infinity
988and NaNs) correctly.
989
990These are functions are available under C<-DECB_NO_LIBM>, since
991they do not rely on the platform floating point format. The
992C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
993usually what you want.
755 994
756=back 995=back
757 996
758=head2 ARITHMETIC 997=head2 ARITHMETIC
759 998

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines