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

Comparing libecb/ecb.pod (file contents):
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs.
Revision 1.107 by root, Fri Mar 25 15:28:08 2022 UTC

…		…
10		10
11	Its homepage can be found here:	11	Its homepage can be found here:
12		12
13	http://software.schmorp.de/pkg/libecb	13	http://software.schmorp.de/pkg/libecb
14		14
15	It mainly provides a number of wrappers around GCC built-ins, together	15	It mainly provides a number of wrappers around many compiler built-ins,
16	with replacement functions for other compilers. In addition to this,	16	together with replacement functions for other compilers. In addition
17	it provides a number of other lowlevel C utilities, such as endianness	17	to this, it provides a number of other low-level C utilities, such as
18	detection, byte swapping or bit rotations.	18	endianness detection, byte swapping or bit rotations.
19		19
20	Or in other words, things that should be built into any standard C system,	20	Or in other words, things that should be built into any standard C
21	but aren't, implemented as efficient as possible with GCC, and still	21	system, but aren't, implemented as efficient as possible with GCC (clang,
22	correct with other compilers.	22	MSVC...), and still correct with other compilers.
23		23
24	More might come.	24	More might come.
25		25
26	=head2 ABOUT THE HEADER	26	=head2 ABOUT THE HEADER
27		27
…		…
56	is usually implemented as a macro. Specifically, a "bool" in this manual	56	is usually implemented as a macro. Specifically, a "bool" in this manual
57	refers to any kind of boolean value, not a specific type.	57	refers to any kind of boolean value, not a specific type.
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	F<ecb.h> makes sure that the following types are defined (in the expected way):
62		62
63	int8_t uint8_	63	int8_t uint8_
64	int16_t uint16_t	64	int16_t uint16_t
65	int32_t uint32_	65	int32_t uint32_
66	int64_t uint64_t	66	int64_t uint64_t
…		…
80		80
81	All the following symbols expand to an expression that can be tested in	81	All the following symbols expand to an expression that can be tested in
82	preprocessor instructions as well as treated as a boolean (use C<!!> to	82	preprocessor instructions as well as treated as a boolean (use C<!!> to
83	ensure it's either C<0> or C<1> if you need that).	83	ensure it's either C<0> or C<1> if you need that).
84		84
85	=over 4	85	=over
86		86
87	=item ECB_C	87	=item ECB_C
88		88
89	True if the implementation defines the C<__STDC__> macro to a true value,	89	True if the implementation defines the C<__STDC__> macro to a true value,
90	while not claiming to be C++.	90	while not claiming to be C++, i..e C, but not C++.
91		91
92	=item ECB_C99	92	=item ECB_C99
93		93
94	True if the implementation claims to be compliant to C99 (ISO/IEC	94	True if the implementation claims to be compliant to C99 (ISO/IEC
95	9899:1999) or any later version, while not claiming to be C++.	95	9899:1999) or any later version, while not claiming to be C++.
…		…
109		109
110	=item ECB_CPP11, ECB_CPP14, ECB_CPP17	110	=item ECB_CPP11, ECB_CPP14, ECB_CPP17
111		111
112	True if the implementation claims to be compliant to C++11/C++14/C++17	112	True if the implementation claims to be compliant to C++11/C++14/C++17
113	(ISO/IEC 14882:2011, :2014, :2017) or any later version.	113	(ISO/IEC 14882:2011, :2014, :2017) or any later version.
		114
		115	Note that many C++20 features will likely have their own feature test
		116	macros (see e.g. L<http://eel.is/c++draft/cpp.predefined#1.8>).
114		117
115	=item ECB_OPTIMIZE_SIZE	118	=item ECB_OPTIMIZE_SIZE
116		119
117	Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol	120	Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
118	can also be defined before including F<ecb.h>, in which case it will be	121	can also be defined before including F<ecb.h>, in which case it will be
119	unchanged.	122	unchanged.
120		123
121	=item ECB_GCC_VERSION (major, minor)	124	=item ECB_GCC_VERSION (major, minor)
122		125
123	Expands to a true value (suitable for testing in by the preprocessor)	126	Expands to a true value (suitable for testing by the preprocessor) if the
124	if the compiler used is GNU C and the version is the given version, or	127	compiler used is GNU C and the version is the given version, or higher.
125	higher.
126		128
127	This macro tries to return false on compilers that claim to be GCC	129	This macro tries to return false on compilers that claim to be GCC
128	compatible but aren't.	130	compatible but aren't.
129		131
130	=item ECB_EXTERN_C	132	=item ECB_EXTERN_C
…		…
149		151
150	ECB_EXTERN_C_END	152	ECB_EXTERN_C_END
151		153
152	=item ECB_STDFP	154	=item ECB_STDFP
153		155
154	If this evaluates to a true value (suitable for testing in by the	156	If this evaluates to a true value (suitable for testing by the
155	preprocessor), then C<float> and C<double> use IEEE 754 single/binary32	157	preprocessor), then C<float> and C<double> use IEEE 754 single/binary32
156	and double/binary64 representations internally I<and> the endianness of	158	and double/binary64 representations internally I<and> the endianness of
157	both types match the endianness of C<uint32_t> and C<uint64_t>.	159	both types match the endianness of C<uint32_t> and C<uint64_t>.
158		160
159	This means you can just copy the bits of a C<float> (or C<double>) to an	161	This means you can just copy the bits of a C<float> (or C<double>) to an
…		…
161	without having to think about format or endianness.	163	without having to think about format or endianness.
162		164
163	This is true for basically all modern platforms, although F<ecb.h> might	165	This is true for basically all modern platforms, although F<ecb.h> might
164	not be able to deduce this correctly everywhere and might err on the safe	166	not be able to deduce this correctly everywhere and might err on the safe
165	side.	167	side.
		168
		169	=item ECB_64BIT_NATIVE
		170
		171	Evaluates to a true value (suitable for both preprocessor and C code
		172	testing) if 64 bit integer types on this architecture are evaluated
		173	"natively", that is, with similar speeds as 32 bit integers. While 64 bit
		174	integer support is very common (and in fact required by libecb), 32 bit
		175	CPUs have to emulate operations on them, so you might want to avoid them.
166		176
167	=item ECB_AMD64, ECB_AMD64_X32	177	=item ECB_AMD64, ECB_AMD64_X32
168		178
169	These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32	179	These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
170	ABI, respectively, and undefined elsewhere.	180	ABI, respectively, and undefined elsewhere.
…		…
177		187
178	=back	188	=back
179		189
180	=head2 MACRO TRICKERY	190	=head2 MACRO TRICKERY
181		191
182	=over 4	192	=over
183		193
184	=item ECB_CONCAT (a, b)	194	=item ECB_CONCAT (a, b)
185		195
186	Expands any macros in C<a> and C<b>, then concatenates the result to form	196	Expands any macros in C<a> and C<b>, then concatenates the result to form
187	a single token. This is mainly useful to form identifiers from components,	197	a single token. This is mainly useful to form identifiers from components,
…		…
228	declarations must be put before the whole declaration:	238	declarations must be put before the whole declaration:
229		239
230	ecb_const int mysqrt (int a);	240	ecb_const int mysqrt (int a);
231	ecb_unused int i;	241	ecb_unused int i;
232		242
233	=over 4	243	=over
234		244
235	=item ecb_unused	245	=item ecb_unused
236		246
237	Marks a function or a variable as "unused", which simply suppresses a	247	Marks a function or a variable as "unused", which simply suppresses a
238	warning by GCC when it detects it as unused. This is useful when you e.g.	248	warning by the compiler when it detects it as unused. This is useful when
239	declare a variable but do not always use it:	249	you e.g. declare a variable but do not always use it:
240		250
241	{	251	{
242	ecb_unused int var;	252	ecb_unused int var;
243		253
244	#ifdef SOMECONDITION	254	#ifdef SOMECONDITION
…		…
264		274
265	Expands either to (a compiler-specific equivalent of) C<static inline> or	275	Expands either to (a compiler-specific equivalent of) C<static inline> or
266	to just C<static>, if inline isn't supported. It should be used to declare	276	to just C<static>, if inline isn't supported. It should be used to declare
267	functions that should be inlined, for code size or speed reasons.	277	functions that should be inlined, for code size or speed reasons.
268		278
269	Example: inline this function, it surely will reduce codesize.	279	Example: inline this function, it surely will reduce code size.
270		280
271	ecb_inline int	281	ecb_inline int
272	negmul (int a, int b)	282	negmul (int a, int b)
273	{	283	{
274	return - (a * b);	284	return - (a * b);
…		…
374	speed-critical times, and keeping it in the cache might be a waste of said	384	speed-critical times, and keeping it in the cache might be a waste of said
375	cache.	385	cache.
376		386
377	In addition to placing cold functions together (or at least away from hot	387	In addition to placing cold functions together (or at least away from hot
378	functions), this knowledge can be used in other ways, for example, the	388	functions), this knowledge can be used in other ways, for example, the
379	function will be optimised for size, as opposed to speed, and codepaths	389	function will be optimised for size, as opposed to speed, and code paths
380	leading to calls to those functions can automatically be marked as if	390	leading to calls to those functions can automatically be marked as if
381	C<ecb_expect_false> had been used to reach them.	391	C<ecb_expect_false> had been used to reach them.
382		392
383	Good examples for such functions would be error reporting functions, or	393	Good examples for such functions would be error reporting functions, or
384	functions only called in exceptional or rare cases.	394	functions only called in exceptional or rare cases.
…		…
412		422
413	=back	423	=back
414		424
415	=head2 OPTIMISATION HINTS	425	=head2 OPTIMISATION HINTS
416		426
417	=over 4	427	=over
418		428
419	=item bool ecb_is_constant (expr)	429	=item bool ecb_is_constant (expr)
420		430
421	Returns true iff the expression can be deduced to be a compile-time	431	Returns true iff the expression can be deduced to be a compile-time
422	constant, and false otherwise.	432	constant, and false otherwise.
…		…
538	never be executed. Apart from suppressing a warning in some cases, this	548	never be executed. Apart from suppressing a warning in some cases, this
539	function can be used to implement C<ecb_assume> or similar functionality.	549	function can be used to implement C<ecb_assume> or similar functionality.
540		550
541	=item ecb_prefetch (addr, rw, locality)	551	=item ecb_prefetch (addr, rw, locality)
542		552
543	Tells the compiler to try to prefetch memory at the given C<addr>ess	553	Tells the compiler to try to prefetch memory at the given I<addr>ess
544	for either reading (C<rw> = 0) or writing (C<rw> = 1). A C<locality> of	554	for either reading (I<rw> = 0) or writing (I<rw> = 1). A I<locality> of
545	C<0> means that there will only be one access later, C<3> means that	555	C<0> means that there will only be one access later, C<3> means that
546	the data will likely be accessed very often, and values in between mean	556	the data will likely be accessed very often, and values in between mean
547	something... in between. The memory pointed to by the address does not	557	something... in between. The memory pointed to by the address does not
548	need to be accessible (it could be a null pointer for example), but C<rw>	558	need to be accessible (it could be a null pointer for example), but C<rw>
549	and C<locality> must be compile-time constants.	559	and C<locality> must be compile-time constants.
…		…
579		589
580	=back	590	=back
581		591
582	=head2 BIT FIDDLING / BIT WIZARDRY	592	=head2 BIT FIDDLING / BIT WIZARDRY
583		593
584	=over 4	594	=over
585		595
586	=item bool ecb_big_endian ()	596	=item bool ecb_big_endian ()
587		597
588	=item bool ecb_little_endian ()	598	=item bool ecb_little_endian ()
589		599
…		…
610		620
611	For example:	621	For example:
612		622
613	ecb_ctz32 (3) = 0	623	ecb_ctz32 (3) = 0
614	ecb_ctz32 (6) = 1	624	ecb_ctz32 (6) = 1
		625
		626	=item int ecb_clz32 (uint32_t x)
		627
		628	=item int ecb_clz64 (uint64_t x)
		629
		630	Counts the number of leading zero bits in C<x>. If C<x> is 0 the result is
		631	undefined.
		632
		633	It is often simpler to use one of the C<ecb_ld*> functions instead, whose
		634	result only depends on the value and not the size of the type. This is
		635	also the reason why there is no C++ overload.
		636
		637	For example:
		638
		639	ecb_clz32 (3) = 30
		640	ecb_clz32 (6) = 29
615		641
616	=item bool ecb_is_pot32 (uint32_t x)	642	=item bool ecb_is_pot32 (uint32_t x)
617		643
618	=item bool ecb_is_pot64 (uint32_t x)	644	=item bool ecb_is_pot64 (uint32_t x)
619		645
…		…
721		747
722	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)	748	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
723		749
724	These two families of functions return the value of C<x> after rotating	750	These two families of functions return the value of C<x> after rotating
725	all the bits by C<count> positions to the right (C<ecb_rotr>) or left	751	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
726	(C<ecb_rotl>).	752	(C<ecb_rotl>). There are no restrictions on the value C<count>, i.e. both
		753	zero and values equal or larger than the word width work correctly. Also,
		754	notwithstanding C<count> being unsigned, negative numbers work and shift
		755	to the opposite direction.
727		756
728	Current GCC versions understand these functions and usually compile them	757	Current GCC/clang versions understand these functions and usually compile
729	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on	758	them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
730	x86).	759	on x86).
731		760
732	=item T ecb_rotl (T x, unsigned int count) [C++]	761	=item T ecb_rotl (T x, unsigned int count) [C++]
733		762
734	=item T ecb_rotr (T x, unsigned int count) [C++]	763	=item T ecb_rotr (T x, unsigned int count) [C++]
735		764
736	Overloaded C++ rotl/rotr functions.	765	Overloaded C++ rotl/rotr functions.
737		766
738	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.	767	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
739		768
		769	=item uint_fast8_t ecb_gray_encode8 (uint_fast8_t b)
		770
		771	=item uint_fast16_t ecb_gray_encode16 (uint_fast16_t b)
		772
		773	=item uint_fast32_t ecb_gray_encode32 (uint_fast32_t b)
		774
		775	=item uint_fast64_t ecb_gray_encode64 (uint_fast64_t b)
		776
		777	Encode an unsigned into its corresponding (reflective) gray code - the
		778	kind of gray code meant when just talking about "gray code". These
		779	functions are very fast and all have identical implementation, so there is
		780	no need to use a smaller type, as long as your CPU can handle it natively.
		781
		782	=item T ecb_gray_encode (T b) [C++]
		783
		784	Overloaded C++ version of the above, for C<uint{8,16,32,64}_t>.
		785
		786	=item uint_fast8_t ecb_gray_decode8 (uint_fast8_t b)
		787
		788	=item uint_fast16_t ecb_gray_decode16 (uint_fast16_t b)
		789
		790	=item uint_fast32_t ecb_gray_decode32 (uint_fast32_t b)
		791
		792	=item uint_fast64_t ecb_gray_decode64 (uint_fast64_t b)
		793
		794	Decode a gray code back into linear index form (the reverse of
		795	C<ecb_gray*_encode>. Unlike the encode functions, the decode functions
		796	have higher time complexity for larger types, so it can pay off to use a
		797	smaller type here.
		798
		799	=item T ecb_gray_decode (T b) [C++]
		800
		801	Overloaded C++ version of the above, for C<uint{8,16,32,64}_t>.
		802
		803	=back
		804
		805	=head2 HILBERT CURVES
		806
		807	These functions deal with (square, pseudo) Hilbert curves. The parameter
		808	I<order> indicates the size of the square and is specified in bits, that
		809	means for order C<8>, the coordinates range from C<0>..C<255>, and the
		810	curve index ranges from C<0>..C<65535>.
		811
		812	The 32 bit variants of these functions map a 32 bit index to two 16 bit
		813	coordinates, stored in a 32 bit variable, where the high order bits are
		814	the x-coordinate, and the low order bits are the y-coordinate, thus,
		815	these functions map 32 bit linear index on the curve to a 32 bit packed
		816	coordinate pair, and vice versa.
		817
		818	The 64 bit variants work similarly.
		819
		820	The I<order> can go from C<1> to C<16> for the 32 bit curve, and C<1> to
		821	C<32> for the 64 bit curve.
		822
		823	When going from one order to the next higher order, these functions
		824	replace the curve segments by smaller versions of the generating shape,
		825	while doubling the size (since they use integer coordinates), which is
		826	what you would expect mathematically. This means that the curve will be
		827	mirrored at the diagonal. If your goal is to simply cover more area while
		828	retaining existing point coordinates you should increase or decrease the
		829	I<order> by C<2> or, in the case of C<ecb_hilbert2d_index_to_coord>,
		830	simply specify the maximum I<order> of C<16> or C<32>, respectively, as
		831	these are constant-time.
		832
		833	=over
		834
		835	=item uint32_t ecb_hilbert2d_index_to_coord32 (int order, uint32_t index)
		836
		837	=item uint64_t ecb_hilbert2d_index_to_coord64 (int order, uint64_t index)
		838
		839	Map a point on a pseudo Hilbert curve from its linear distance from the
		840	origin on the curve to a x\|y coordinate pair. The result is a packed
		841	coordinate pair, to get the actual x and < coordinates, you could do
		842	something like this:
		843
		844	uint32_t xy = ecb_hilbert2d_index_to_coord32 (16, 255);
		845	uint16_t x = xy >> 16;
		846	uint16_t y = xy & 0xffffU;
		847
		848	uint64_t xy = ecb_hilbert2d_index_to_coord64 (32, 255);
		849	uint32_t x = xy >> 32;
		850	uint32_t y = xy & 0xffffffffU;
		851
		852	These functions work in constant time, so for many applications it is
		853	preferable to simply hard-code the order to the maximum (C<16> or C<32>).
		854
		855	This (production-ready, i.e. never run) example generates an SVG image of
		856	an order 8 pseudo Hilbert curve:
		857
		858	printf ("<svg xmlns='http://www.w3.org/2000/svg' width='%d' height='%d'>\n", 64 * 8, 64 * 8);
		859	printf ("<g transform='translate(4) scale(8)' stroke-width='0.25' stroke='black'>\n");
		860	for (uint32_t i = 0; i < 64*64 - 1; ++i)
		861	{
		862	uint32_t p1 = ecb_hilbert2d_index_to_coord32 (6, i );
		863	uint32_t p2 = ecb_hilbert2d_index_to_coord32 (6, i + 1);
		864	printf ("<line x1='%d' y1='%d' x2='%d' y2='%d'/>\n",
		865	p1 >> 16, p1 & 0xffff,
		866	p2 >> 16, p2 & 0xffff);
		867	}
		868	printf ("</g>\n");
		869	printf ("</svg>\n");
		870
		871	=item uint32_t ecb_hilbert2d_coord_to_index32 (int order, uint32_t xy)
		872
		873	=item uint64_t ecb_hilbert2d_coord_to_index64 (int order, uint64_t xy)
		874
		875	The reverse of C<ecb_hilbert2d_index_to_coord> - map a packed pair of
		876	coordinates to their linear index on the pseudo Hilbert curve of order
		877	I<order>.
		878
		879	They are an exact inverse of the C<ecb_hilbert2d_coord_to_index> functions
		880	for the same I<order>:
		881
		882	assert (
		883	u == ecb_hilbert2d_coord_to_index (32,
		884	ecb_hilbert2d_index_to_coord32 (32,
		885	u)));
		886
		887	Packing coordinates is done the same way, as well, from I<x> and I<y>:
		888
		889	uint32_t xy = ((uint32_t)x << 16) \| y; // for ecb_hilbert2d_coord_to_index32
		890	uint64_t xy = ((uint64_t)x << 32) \| y; // for ecb_hilbert2d_coord_to_index64
		891
		892	Unlike C<ecb_hilbert2d_coord_to_index>, these functions are O(I<order>),
		893	so it is preferable to use the lowest possible order.
		894
		895	=back
		896
		897	=head2 BIT MIXING, HASHING
		898
		899	Sometimes you have an integer and want to distribute its bits well, for
		900	example, to use it as a hash in a hash table. A common example is pointer
		901	values, which often only have a limited range (e.g. low and high bits are
		902	often zero).
		903
		904	The following functions try to mix the bits to get a good bias-free
		905	distribution. They were mainly made for pointers, but the underlying
		906	integer functions are exposed as well.
		907
		908	As an added benefit, the functions are reversible, so if you find it
		909	convenient to store only the hash value, you can recover the original
		910	pointer from the hash ("unmix"), as long as your pointers are 32 or 64 bit
		911	(if this isn't the case on your platform, drop us a note and we will add
		912	functions for other bit widths).
		913
		914	The unmix functions are very slightly slower than the mix functions, so
		915	it is equally very slightly preferable to store the original values wehen
		916	convenient.
		917
		918	The underlying algorithm if subject to change, so currently these
		919	functions are not suitable for persistent hash tables, as their result
		920	value can change between different versions of libecb.
		921
		922	=over
		923
		924	=item uintptr_t ecb_ptrmix (void *ptr)
		925
		926	Mixes the bits of a pointer so the result is suitable for hash table
		927	lookups. In other words, this hashes the pointer value.
		928
		929	=item uintptr_t ecb_ptrmix (T *ptr) [C++]
		930
		931	Overload the C<ecb_ptrmix> function to work for any pointer in C++.
		932
		933	=item void *ecb_ptrunmix (uintptr_t v)
		934
		935	Unmix the hash value into the original pointer. This only works as long
		936	as the hash value is not truncated, i.e. you used C<uintptr_t> (or
		937	equivalent) throughout to store it.
		938
		939	=item T *ecb_ptrunmix<T> (uintptr_t v) [C++]
		940
		941	The somewhat less useful template version of C<ecb_ptrunmix> for
		942	C++. Example:
		943
		944	sometype *myptr;
		945	uintptr_t hash = ecb_ptrmix (myptr);
		946	sometype *orig = ecb_ptrunmix<sometype> (hash);
		947
		948	=item uint32_t ecb_mix32 (uint32_t v)
		949
		950	=item uint64_t ecb_mix64 (uint64_t v)
		951
		952	Sometimes you don't have a pointer but an integer whose values are very
		953	badly distributed. In this case you can use these integer versions of the
		954	mixing function. No C++ template is provided currently.
		955
		956	=item uint32_t ecb_unmix32 (uint32_t v)
		957
		958	=item uint64_t ecb_unmix64 (uint64_t v)
		959
		960	The reverse of the C<ecb_mix> functions - they take a mixed/hashed value
		961	and recover the original value.
		962
740	=back	963	=back
741		964
742	=head2 HOST ENDIANNESS CONVERSION	965	=head2 HOST ENDIANNESS CONVERSION
743		966
744	=over 4	967	=over
745		968
746	=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)	969	=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
747		970
748	=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)	971	=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
749		972
…		…
777		1000
778	=back	1001	=back
779		1002
780	In C++ the following additional template functions are supported:	1003	In C++ the following additional template functions are supported:
781		1004
782	=over 4	1005	=over
783		1006
784	=item T ecb_be_to_host (T v)	1007	=item T ecb_be_to_host (T v)
785		1008
786	=item T ecb_le_to_host (T v)	1009	=item T ecb_le_to_host (T v)
787		1010
788	=item T ecb_host_to_be (T v)	1011	=item T ecb_host_to_be (T v)
789		1012
790	=item T ecb_host_to_le (T v)	1013	=item T ecb_host_to_le (T v)
		1014
		1015	=back
791		1016
792	These functions work like their C counterparts, above, but use templates,	1017	These functions work like their C counterparts, above, but use templates,
793	which make them useful in generic code.	1018	which make them useful in generic code.
794		1019
795	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>	1020	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
…		…
798		1023
799	=head2 UNALIGNED LOAD/STORE	1024	=head2 UNALIGNED LOAD/STORE
800		1025
801	These function load or store unaligned multi-byte values.	1026	These function load or store unaligned multi-byte values.
802		1027
803	=over 4	1028	=over
804		1029
805	=item uint_fast16_t ecb_peek_u16_u (const void *ptr)	1030	=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
806		1031
807	=item uint_fast32_t ecb_peek_u32_u (const void *ptr)	1032	=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
808		1033
…		…
852		1077
853	=back	1078	=back
854		1079
855	In C++ the following additional template functions are supported:	1080	In C++ the following additional template functions are supported:
856		1081
857	=over 4	1082	=over
858		1083
859	=item T ecb_peek<T> (const void *ptr)	1084	=item T ecb_peek<T> (const void *ptr)
860		1085
861	=item T ecb_peek_be<T> (const void *ptr)	1086	=item T ecb_peek_be<T> (const void *ptr)
862		1087
…		…
893	=item ecb_poke_be_u (void *ptr, T v)	1118	=item ecb_poke_be_u (void *ptr, T v)
894		1119
895	=item ecb_poke_le_u (void *ptr, T v)	1120	=item ecb_poke_le_u (void *ptr, T v)
896		1121
897	Again, similarly to their C counterparts, these functions store an	1122	Again, similarly to their C counterparts, these functions store an
898	unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to	1123	unsigned 8, 16, 32 or 64 bit value to memory, with optional conversion to
899	big/little endian.	1124	big/little endian.
900		1125
901	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.	1126	C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
902		1127
903	Unlike their C counterparts, these functions support 8 bit quantities	1128	Unlike their C counterparts, these functions support 8 bit quantities
904	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),	1129	(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
905	all of which hopefully makes them more useful in generic code.	1130	all of which hopefully makes them more useful in generic code.
906		1131
907	=back	1132	=back
908		1133
		1134	=head2 FAST INTEGER TO STRING
		1135
		1136	Libecb defines a set of very fast integer to decimal string (or integer
		1137	to ASCII, short C<i2a>) functions. These work by converting the integer
		1138	to a fixed point representation and then successively multiplying out
		1139	the topmost digits. Unlike some other, also very fast, libraries, ecb's
		1140	algorithm should be completely branchless per digit, and does not rely on
		1141	the presence of special CPU functions (such as C<clz>).
		1142
		1143	There is a high level API that takes an C<int32_t>, C<uint32_t>,
		1144	C<int64_t> or C<uint64_t> as argument, and a low-level API, which is
		1145	harder to use but supports slightly more formatting options.
		1146
		1147	=head3 HIGH LEVEL API
		1148
		1149	The high level API consists of four functions, one each for C<int32_t>,
		1150	C<uint32_t>, C<int64_t> and C<uint64_t>:
		1151
		1152	Example:
		1153
		1154	char buf[ECB_I2A_MAX_DIGITS + 1];
		1155	char *end = ecb_i2a_i32 (buf, 17262);
		1156	*end = 0;
		1157	// buf now contains "17262"
		1158
		1159	=over
		1160
		1161	=item ECB_I2A_I32_DIGITS (=11)
		1162
		1163	=item char ecb_i2a_u32 (char ptr, uint32_t value)
		1164
		1165	Takes an C<uint32_t> I<value> and formats it as a decimal number starting
		1166	at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a
		1167	pointer to just after the generated string, where you would normally put
		1168	the terminating C<0> character. This function outputs the minimum number
		1169	of digits.
		1170
		1171	=item ECB_I2A_U32_DIGITS (=10)
		1172
		1173	=item char ecb_i2a_i32 (char ptr, int32_t value)
		1174
		1175	Same as C<ecb_i2a_u32>, but formats a C<int32_t> value, including a minus
		1176	sign if needed.
		1177
		1178	=item ECB_I2A_I64_DIGITS (=20)
		1179
		1180	=item char ecb_i2a_u64 (char ptr, uint64_t value)
		1181
		1182	=item ECB_I2A_U64_DIGITS (=21)
		1183
		1184	=item char ecb_i2a_i64 (char ptr, int64_t value)
		1185
		1186	Similar to their 32 bit counterparts, these take a 64 bit argument.
		1187
		1188	=item ECB_I2A_MAX_DIGITS (=21)
		1189
		1190	Instead of using a type specific length macro, you can just use
		1191	C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function.
		1192
		1193	=back
		1194
		1195	=head3 LOW-LEVEL API
		1196
		1197	The functions above use a number of low-level APIs which have some strict
		1198	limitations, but can be used as building blocks (studying C<ecb_i2a_i32>
		1199	and related functions is recommended).
		1200
		1201	There are three families of functions: functions that convert a number
		1202	to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
		1203	for "leading zeroes"), functions that generate up to N digits, skipping
		1204	leading zeroes (C<_N>), and functions that can generate more digits, but
		1205	the leading digit has limited range (C<_xN>).
		1206
		1207	None of the functions deal with negative numbers.
		1208
		1209	Example: convert an IP address in an C<uint32_t> into dotted-quad:
		1210
		1211	uint32_t ip = 0x0a000164; // 10.0.1.100
		1212	char ips[3 * 4 + 3 + 1];
		1213	char *ptr = ips;
		1214	ptr = ecb_i2a_3 (ptr, ip >> 24 ); *ptr++ = '.';
		1215	ptr = ecb_i2a_3 (ptr, (ip >> 16) & 0xff); *ptr++ = '.';
		1216	ptr = ecb_i2a_3 (ptr, (ip >> 8) & 0xff); *ptr++ = '.';
		1217	ptr = ecb_i2a_3 (ptr, ip & 0xff); *ptr++ = 0;
		1218	printf ("ip: %s\n", ips); // prints "ip: 10.0.1.100"
		1219
		1220	=over
		1221
		1222	=item char ecb_i2a_02 (char ptr, uint32_t value) // 32 bit
		1223
		1224	=item char ecb_i2a_03 (char ptr, uint32_t value) // 32 bit
		1225
		1226	=item char ecb_i2a_04 (char ptr, uint32_t value) // 32 bit
		1227
		1228	=item char ecb_i2a_05 (char ptr, uint32_t value) // 64 bit
		1229
		1230	=item char ecb_i2a_06 (char ptr, uint32_t value) // 64 bit
		1231
		1232	=item char ecb_i2a_07 (char ptr, uint32_t value) // 64 bit
		1233
		1234	=item char ecb_i2a_08 (char ptr, uint32_t value) // 64 bit
		1235
		1236	=item char ecb_i2a_09 (char ptr, uint32_t value) // 64 bit
		1237
		1238	The C<< ecb_i2a_0I<N> >> functions take an unsigned I<value> and convert
		1239	them to exactly I<N> digits, returning a pointer to the first character
		1240	after the digits. The I<value> must be in range. The functions marked with
		1241	I<32 bit> do their calculations internally in 32 bit, the ones marked with
		1242	I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
		1243	architectures (the high level API decides on 32 vs. 64 bit versions using
		1244	C<ECB_64BIT_NATIVE>).
		1245
		1246	=item char ecb_i2a_2 (char ptr, uint32_t value) // 32 bit
		1247
		1248	=item char ecb_i2a_3 (char ptr, uint32_t value) // 32 bit
		1249
		1250	=item char ecb_i2a_4 (char ptr, uint32_t value) // 32 bit
		1251
		1252	=item char ecb_i2a_5 (char ptr, uint32_t value) // 64 bit
		1253
		1254	=item char ecb_i2a_6 (char ptr, uint32_t value) // 64 bit
		1255
		1256	=item char ecb_i2a_7 (char ptr, uint32_t value) // 64 bit
		1257
		1258	=item char ecb_i2a_8 (char ptr, uint32_t value) // 64 bit
		1259
		1260	=item char ecb_i2a_9 (char ptr, uint32_t value) // 64 bit
		1261
		1262	Similarly, the C<< ecb_i2a_I<N> >> functions take an unsigned I<value>
		1263	and convert them to at most I<N> digits, suppressing leading zeroes, and
		1264	returning a pointer to the first character after the digits.
		1265
		1266	=item ECB_I2A_MAX_X5 (=59074)
		1267
		1268	=item char ecb_i2a_x5 (char ptr, uint32_t value) // 32 bit
		1269
		1270	=item ECB_I2A_MAX_X10 (=2932500665)
		1271
		1272	=item char ecb_i2a_x10 (char ptr, uint32_t value) // 64 bit
		1273
		1274	The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >>
		1275	functions, but they can generate one digit more, as long as the number
		1276	is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
		1277	16 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
		1278	respectively.
		1279
		1280	For example, the digit part of a 32 bit signed integer just fits into the
		1281	C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10
		1282	digit number, it can convert all 32 bit signed numbers. Sadly, it's not
		1283	good enough for 32 bit unsigned numbers.
		1284
		1285	=back
		1286
909	=head2 FLOATING POINT FIDDLING	1287	=head2 FLOATING POINT FIDDLING
910		1288
911	=over 4	1289	=over
912		1290
913	=item ECB_INFINITY [-UECB_NO_LIBM]	1291	=item ECB_INFINITY [-UECB_NO_LIBM]
914		1292
915	Evaluates to positive infinity if supported by the platform, otherwise to	1293	Evaluates to positive infinity if supported by the platform, otherwise to
916	a truly huge number.	1294	a truly huge number.
…		…
941	IEEE compliant, of course at a speed and code size penalty, and of course	1319	IEEE compliant, of course at a speed and code size penalty, and of course
942	also within reasonable limits (it tries to convert NaNs, infinities and	1320	also within reasonable limits (it tries to convert NaNs, infinities and
943	denormals, but will likely convert negative zero to positive zero).	1321	denormals, but will likely convert negative zero to positive zero).
944		1322
945	On all modern platforms (where C<ECB_STDFP> is true), the compiler should	1323	On all modern platforms (where C<ECB_STDFP> is true), the compiler should
946	be able to optimise away this function completely.	1324	be able to completely optimise away the 32 and 64 bit functions.
947		1325
948	These functions can be helpful when serialising floats to the network - you	1326	These functions can be helpful when serialising floats to the network - you
949	can serialise the return value like a normal uint16_t/uint32_t/uint64_t.	1327	can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
950		1328
951	Another use for these functions is to manipulate floating point values	1329	Another use for these functions is to manipulate floating point values
…		…
994		1372
995	=back	1373	=back
996		1374
997	=head2 ARITHMETIC	1375	=head2 ARITHMETIC
998		1376
999	=over 4	1377	=over
1000		1378
1001	=item x = ecb_mod (m, n)	1379	=item x = ecb_mod (m, n)
1002		1380
1003	Returns C<m> modulo C<n>, which is the same as the positive remainder	1381	Returns C<m> modulo C<n>, which is the same as the positive remainder
1004	of the division operation between C<m> and C<n>, using floored	1382	of the division operation between C<m> and C<n>, using floored
…		…
1011	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be	1389	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
1012	negatable, that is, both C<m> and C<-m> must be representable in its	1390	negatable, that is, both C<m> and C<-m> must be representable in its
1013	type (this typically excludes the minimum signed integer value, the same	1391	type (this typically excludes the minimum signed integer value, the same
1014	limitation as for C</> and C<%> in C).	1392	limitation as for C</> and C<%> in C).
1015		1393
1016	Current GCC versions compile this into an efficient branchless sequence on	1394	Current GCC/clang versions compile this into an efficient branchless
1017	almost all CPUs.	1395	sequence on almost all CPUs.
1018		1396
1019	For example, when you want to rotate forward through the members of an	1397	For example, when you want to rotate forward through the members of an
1020	array for increasing C<m> (which might be negative), then you should use	1398	array for increasing C<m> (which might be negative), then you should use
1021	C<ecb_mod>, as the C<%> operator might give either negative results, or	1399	C<ecb_mod>, as the C<%> operator might give either negative results, or
1022	change direction for negative values:	1400	change direction for negative values:
…		…
1035		1413
1036	=back	1414	=back
1037		1415
1038	=head2 UTILITY	1416	=head2 UTILITY
1039		1417
1040	=over 4	1418	=over
1041		1419
1042	=item element_count = ecb_array_length (name)	1420	=item element_count = ecb_array_length (name)
1043		1421
1044	Returns the number of elements in the array C<name>. For example:	1422	Returns the number of elements in the array C<name>. For example:
1045		1423
…		…
1053		1431
1054	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF	1432	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
1055		1433
1056	These symbols need to be defined before including F<ecb.h> the first time.	1434	These symbols need to be defined before including F<ecb.h> the first time.
1057		1435
1058	=over 4	1436	=over
1059		1437
1060	=item ECB_NO_THREADS	1438	=item ECB_NO_THREADS
1061		1439
1062	If F<ecb.h> is never used from multiple threads, then this symbol can	1440	If F<ecb.h> is never used from multiple threads, then this symbol can
1063	be defined, in which case memory fences (and similar constructs) are	1441	be defined, in which case memory fences (and similar constructs) are
…		…
1067		1445
1068	=item ECB_NO_SMP	1446	=item ECB_NO_SMP
1069		1447
1070	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from	1448	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
1071	multiple threads, but never concurrently (e.g. if the system the program	1449	multiple threads, but never concurrently (e.g. if the system the program
1072	runs on has only a single CPU with a single core, no hyperthreading and so	1450	runs on has only a single CPU with a single core, no hyper-threading and so
1073	on), then this symbol can be defined, leading to more efficient code and	1451	on), then this symbol can be defined, leading to more efficient code and
1074	fewer dependencies.	1452	fewer dependencies.
1075		1453
1076	=item ECB_NO_LIBM	1454	=item ECB_NO_LIBM
1077		1455
…		…
1087	intended to be internal-use only, some of which we forgot to document, and	1465	intended to be internal-use only, some of which we forgot to document, and
1088	some of which we hide because we are not sure we will keep the interface	1466	some of which we hide because we are not sure we will keep the interface
1089	stable.	1467	stable.
1090		1468
1091	While you are welcome to rummage around and use whatever you find useful	1469	While you are welcome to rummage around and use whatever you find useful
1092	(we can't stop you), keep in mind that we will change undocumented	1470	(we don't want to stop you), keep in mind that we will change undocumented
1093	functionality in incompatible ways without thinking twice, while we are	1471	functionality in incompatible ways without thinking twice, while we are
1094	considerably more conservative with documented things.	1472	considerably more conservative with documented things.
1095		1473
1096	=head1 AUTHORS	1474	=head1 AUTHORS
1097		1475
1098	C<libecb> is designed and maintained by:	1476	C<libecb> is designed and maintained by:
1099		1477
1100	Emanuele Giaquinta <e.giaquinta@glauco.it>	1478	Emanuele Giaquinta <e.giaquinta@glauco.it>
1101	Marc Alexander Lehmann <schmorp@schmorp.de>	1479	Marc Alexander Lehmann <schmorp@schmorp.de>
1102
1103

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs. Revision 1.107 by root, Fri Mar 25 15:28:08 2022 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs.
Revision 1.107 by root, Fri Mar 25 15:28:08 2022 UTC