[ViewVC] Diff of: cvs/libecb/ecb.pod

Comparing libecb/ecb.pod (file contents):
Revision 1.75 by root, Sat Dec 28 08:01:05 2019 UTC vs.
Revision 1.77 by root, Mon Jan 20 13:41:18 2020 UTC

…		…
58		58
59	=head2 TYPES / TYPE SUPPORT	59	=head2 TYPES / TYPE SUPPORT
60		60
61	ecb.h makes sure that the following types are defined (in the expected way):	61	ecb.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
67	The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this	73	The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
68	platform (currently C<4> or C<8>) and can be used in preprocessor	74	platform (currently C<4> or C<8>) and can be used in preprocessor
69	expressions.	75	expressions.
70		76
…		…
589		595
590	=item int ecb_ctz32 (uint32_t x)	596	=item int ecb_ctz32 (uint32_t x)
591		597
592	=item int ecb_ctz64 (uint64_t x)	598	=item int ecb_ctz64 (uint64_t x)
593		599
		600	=item int ecb_ctz (T x) [C++]
		601
594	Returns the index of the least significant bit set in C<x> (or	602	Returns the index of the least significant bit set in C<x> (or
595	equivalently the number of bits set to 0 before the least significant bit	603	equivalently the number of bits set to 0 before the least significant bit
596	set), starting from 0. If C<x> is 0 the result is undefined.	604	set), starting from 0. If C<x> is 0 the result is undefined.
597		605
598	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.	606	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
599		607
		608	The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
		609	C<uint32_t> and C<uint64_t> types.
		610
600	For example:	611	For example:
601		612
602	ecb_ctz32 (3) = 0	613	ecb_ctz32 (3) = 0
603	ecb_ctz32 (6) = 1	614	ecb_ctz32 (6) = 1
604		615
605	=item bool ecb_is_pot32 (uint32_t x)	616	=item bool ecb_is_pot32 (uint32_t x)
606		617
607	=item bool ecb_is_pot64 (uint32_t x)	618	=item bool ecb_is_pot64 (uint32_t x)
608		619
		620	=item bool ecb_is_pot (T x) [C++]
		621
609	Returns true iff C<x> is a power of two or C<x == 0>.	622	Returns true iff C<x> is a power of two or C<x == 0>.
610		623
611	For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.	624	For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
612		625
		626	The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
		627	C<uint32_t> and C<uint64_t> types.
		628
613	=item int ecb_ld32 (uint32_t x)	629	=item int ecb_ld32 (uint32_t x)
614		630
615	=item int ecb_ld64 (uint64_t x)	631	=item int ecb_ld64 (uint64_t x)
		632
		633	=item int ecb_ld64 (T x) [C++]
616		634
617	Returns the index of the most significant bit set in C<x>, or the number	635	Returns the index of the most significant bit set in C<x>, or the number
618	of digits the number requires in binary (so that C<< 2**ld <= x <	636	of digits the number requires in binary (so that C<< 2**ld <= x <
619	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is	637	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
620	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for	638	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
…		…
625	the given data type), while C<ecb_ld> returns how many bits the number	643	the given data type), while C<ecb_ld> returns how many bits the number
626	itself requires.	644	itself requires.
627		645
628	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.	646	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
629		647
		648	The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
		649	C<uint32_t> and C<uint64_t> types.
		650
630	=item int ecb_popcount32 (uint32_t x)	651	=item int ecb_popcount32 (uint32_t x)
631		652
632	=item int ecb_popcount64 (uint64_t x)	653	=item int ecb_popcount64 (uint64_t x)
633		654
		655	=item int ecb_popcount (T x) [C++]
		656
634	Returns the number of bits set to 1 in C<x>.	657	Returns the number of bits set to 1 in C<x>.
635		658
636	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.	659	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		660
		661	The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
		662	C<uint32_t> and C<uint64_t> types.
637		663
638	For example:	664	For example:
639		665
640	ecb_popcount32 (7) = 3	666	ecb_popcount32 (7) = 3
641	ecb_popcount32 (255) = 8	667	ecb_popcount32 (255) = 8
…		…
644		670
645	=item uint16_t ecb_bitrev16 (uint16_t x)	671	=item uint16_t ecb_bitrev16 (uint16_t x)
646		672
647	=item uint32_t ecb_bitrev32 (uint32_t x)	673	=item uint32_t ecb_bitrev32 (uint32_t x)
648		674
		675	=item T ecb_bitrev (T x) [C++]
		676
649	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1	677	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
650	and so on.	678	and so on.
651		679
		680	The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
		681
652	Example:	682	Example:
653		683
654	ecb_bitrev8 (0xa7) = 0xea	684	ecb_bitrev8 (0xa7) = 0xea
655	ecb_bitrev32 (0xffcc4411) = 0x882233ff	685	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		686
		687	=item T ecb_bitrev (T x) [C++]
		688
		689	Overloaded C++ bitrev function.
		690
		691	C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
656		692
657	=item uint32_t ecb_bswap16 (uint32_t x)	693	=item uint32_t ecb_bswap16 (uint32_t x)
658		694
659	=item uint32_t ecb_bswap32 (uint32_t x)	695	=item uint32_t ecb_bswap32 (uint32_t x)
660		696
…		…
662		698
663	These functions return the value of the 16-bit (32-bit, 64-bit) value	699	These functions return the value of the 16-bit (32-bit, 64-bit) value
664	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in	700	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
665	C<ecb_bswap32>).	701	C<ecb_bswap32>).
666		702
		703	The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
		704	C<uint32_t> and C<uint64_t> types.
		705
667	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)	706	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
668		707
669	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)	708	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
670		709
671	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	710	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
…		…
685	(C<ecb_rotl>).	724	(C<ecb_rotl>).
686		725
687	Current GCC versions understand these functions and usually compile them	726	Current GCC versions understand these functions and usually compile them
688	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on	727	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
689	x86).	728	x86).
		729
		730	=item T ecb_rotl (T x, unsigned int count) [C++]
		731
		732	=item T ecb_rotr (T x, unsigned int count) [C++]
		733
		734	Overloaded C++ rotl/rotr functions.
		735
		736	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		737
		738	=back
		739
		740	=head2 HOST ENDIANNESS CONVERSION
		741
		742	=over 4
		743
		744	=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
		745
		746	=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
		747
		748	=item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
		749
		750	=item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
		751
		752	=item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
		753
		754	=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
		755
		756	Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
		757
		758	The naming convention is C<ecb_>(C<be>\|C<le>)C<_u>C<16\|32\|64>C<_to_host>,
		759	where be and le stand for big endian and little endian, respectively.
		760
		761	=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
		762
		763	=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
		764
		765	=item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
		766
		767	=item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
		768
		769	=item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
		770
		771	=item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
		772
		773	Like above, but converts I<from> host byte order to the specified
		774	endianness.
		775
		776	=back
		777
		778	In C++ the following additional template functions are supported:
		779
		780	=over 4
		781
		782	=item T ecb_be_to_host (T v)
		783
		784	=item T ecb_le_to_host (T v)
		785
		786	=item T ecb_host_to_be (T v)
		787
		788	=item T ecb_host_to_le (T v)
		789
		790	These functions work like their C counterparts, above, but use templates,
		791	which make them useful in generic code.
		792
		793	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
		794	(so unlike their C counterparts, there is a version for C<uint8_t>, which
		795	again can be useful in generic code).
		796
		797	=head2 UNALIGNED LOAD/STORE
		798
		799	These function load or store unaligned multi-byte values.
		800
		801	=over 4
		802
		803	=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
		804
		805	=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
		806
		807	=item uint_fast64_t ecb_peek_u64_u (const void *ptr)
		808
		809	These functions load an unaligned, unsigned 16, 32 or 64 bit value from
		810	memory.
		811
		812	=item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
		813
		814	=item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
		815
		816	=item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
		817
		818	=item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
		819
		820	=item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
		821
		822	=item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
		823
		824	Like above, but additionally convert from big endian (C<be>) or little
		825	endian (C<le>) byte order to host byte order while doing so.
		826
		827	=item ecb_poke_u16_u (void *ptr, uint16_t v)
		828
		829	=item ecb_poke_u32_u (void *ptr, uint32_t v)
		830
		831	=item ecb_poke_u64_u (void *ptr, uint64_t v)
		832
		833	These functions store an unaligned, unsigned 16, 32 or 64 bit value to
		834	memory.
		835
		836	=item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
		837
		838	=item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
		839
		840	=item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
		841
		842	=item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
		843
		844	=item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
		845
		846	=item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
		847
		848	Like above, but additionally convert from host byte order to big endian
		849	(C<be>) or little endian (C<le>) byte order while doing so.
		850
		851	=back
		852
		853	In C++ the following additional template functions are supported:
		854
		855	=over 4
		856
		857	=item T ecb_peek (const void *ptr)
		858
		859	=item T ecb_peek_be (const void *ptr)
		860
		861	=item T ecb_peek_le (const void *ptr)
		862
		863	=item T ecb_peek_u (const void *ptr)
		864
		865	=item T ecb_peek_be_u (const void *ptr)
		866
		867	=item T ecb_peek_le_u (const void *ptr)
		868
		869	Similarly to their C counterparts, these functions load an unsigned 8, 16,
		870	32 or 64 bit value from memory, with optional conversion from big/little
		871	endian.
		872
		873	Since the type cannot be deduced, it has top be specified explicitly, e.g.
		874
		875	uint_fast16_t v = ecb_peek<uint16_t> (ptr);
		876
		877	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		878
		879	Unlike their C counterparts, these functions support 8 bit quantities
		880	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
		881	all of which hopefully makes them more useful in generic code.
		882
		883	=item ecb_poke (void *ptr, T v)
		884
		885	=item ecb_poke_be (void *ptr, T v)
		886
		887	=item ecb_poke_le (void *ptr, T v)
		888
		889	=item ecb_poke_u (void *ptr, T v)
		890
		891	=item ecb_poke_be_u (void *ptr, T v)
		892
		893	=item ecb_poke_le_u (void *ptr, T v)
		894
		895	Again, similarly to their C counterparts, these functions store an
		896	unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
		897	big/little endian.
		898
		899	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
		900
		901	Unlike their C counterparts, these functions support 8 bit quantities
		902	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
		903	all of which hopefully makes them more useful in generic code.
690		904
691	=back	905	=back
692		906
693	=head2 FLOATING POINT FIDDLING	907	=head2 FLOATING POINT FIDDLING
694		908

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.75 by root, Sat Dec 28 08:01:05 2019 UTC vs. Revision 1.77 by root, Mon Jan 20 13:41:18 2020 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.75 by root, Sat Dec 28 08:01:05 2019 UTC vs.
Revision 1.77 by root, Mon Jan 20 13:41:18 2020 UTC