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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.27 by root, Wed Jun 1 01:29:36 2011 UTC vs.
Revision 1.46 by sf-exg, Tue May 29 14:57:24 2012 UTC

…		…
53	C<uint32_t>, then the corresponding function works only with that type. If	53	C<uint32_t>, then the corresponding function works only with that type. If
54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then	54	only a generic name is used (C<expr>, C<cond>, C<value> and so on), then
55	the corresponding function relies on C to implement the correct types, and	55	the corresponding function relies on C to implement the correct types, and
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
		59	=head2 TYPES / TYPE SUPPORT
		60
		61	ecb.h makes sure that the following types are defined (in the expected way):
		62
		63	int8_t uint8_t int16_t uint16_t
		64	int32_t uint32_t int64_t uint64_t
		65	intptr_t uintptr_t ptrdiff_t
		66
		67	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
		69	expressions.
		70
		71	=head2 LANGUAGE/COMPILER VERSIONS
		72
		73	All the following symbols expand to an expression that can be tested in
		74	preprocessor instructions as well as treated as a boolean (use C<!!> to
		75	ensure it's either C<0> or C<1> if you need that).
		76
		77	=over 4
		78
		79	=item ECB_C
		80
		81	True if the implementation defines the C<__STDC__> macro to a true value,
		82	which is typically true for both C and C++ compilers.
		83
		84	=item ECB_C99
		85
		86	True if the implementation claims to be C99 compliant.
		87
		88	=item ECB_C11
		89
		90	True if the implementation claims to be C11 compliant.
		91
		92	=item ECB_CPP
		93
		94	True if the implementation defines the C<__cplusplus__> macro to a true
		95	value, which is typically true for C++ compilers.
		96
		97	=item ECB_CPP98
		98
		99	True if the implementation claims to be compliant to ISO/IEC 14882:1998
		100	(the first C++ ISO standard) or any later version. Typically true for all
		101	C++ compilers.
		102
		103	=item ECB_CPP11
		104
		105	True if the implementation claims to be compliant to ISO/IEC 14882:2011
		106	(C++11) or any later version.
		107
		108	=item ECB_GCC_VERSION(major,minor)
		109
		110	Expands to a true value (suitable for testing in by the preprocessor)
		111	if the compiler used is GNU C and the version is the given version, or
		112	higher.
		113
		114	This macro tries to return false on compilers that claim to be GCC
		115	compatible but aren't.
		116
		117	=back
58		118
59	=head2 GCC ATTRIBUTES	119	=head2 GCC ATTRIBUTES
60		120
61	A major part of libecb deals with GCC attributes. These are additional	121	A major part of libecb deals with GCC attributes. These are additional
62	attributes that you can assign to functions, variables and sometimes even	122	attributes that you can assign to functions, variables and sometimes even
…		…
101	#else	161	#else
102	return 0;	162	return 0;
103	#endif	163	#endif
104	}	164	}
105		165
		166	=item ecb_inline
		167
		168	This is not actually an attribute, but you use it like one. It expands
		169	either to C<static inline> or to just C<static>, if inline isn't
		170	supported. It should be used to declare functions that should be inlined,
		171	for code size or speed reasons.
		172
		173	Example: inline this function, it surely will reduce codesize.
		174
		175	ecb_inline int
		176	negmul (int a, int b)
		177	{
		178	return - (a * b);
		179	}
		180
106	=item ecb_noinline	181	=item ecb_noinline
107		182
108	Prevent a function from being inlined - it might be optimised away, but	183	Prevent a function from being inlined - it might be optimised away, but
109	not inlined into other functions. This is useful if you know your function	184	not inlined into other functions. This is useful if you know your function
110	is rarely called and large enough for inlining not to be helpful.	185	is rarely called and large enough for inlining not to be helpful.
…		…
381	After processing the node, (part of) the next node might already be in	456	After processing the node, (part of) the next node might already be in
382	cache.	457	cache.
383		458
384	=back	459	=back
385		460
386	=head2 BIT FIDDLING / BITSTUFFS	461	=head2 BIT FIDDLING / BIT WIZARDRY
387		462
388	=over 4	463	=over 4
389		464
390	=item bool ecb_big_endian ()	465	=item bool ecb_big_endian ()
391		466
…		…
397		472
398	On systems that are neither, their return values are unspecified.	473	On systems that are neither, their return values are unspecified.
399		474
400	=item int ecb_ctz32 (uint32_t x)	475	=item int ecb_ctz32 (uint32_t x)
401		476
		477	=item int ecb_ctz64 (uint64_t x)
		478
402	Returns the index of the least significant bit set in C<x> (or	479	Returns the index of the least significant bit set in C<x> (or
403	equivalently the number of bits set to 0 before the least significant bit	480	equivalently the number of bits set to 0 before the least significant bit
404	set), starting from 0. If C<x> is 0 the result is undefined. A common use	481	set), starting from 0. If C<x> is 0 the result is undefined.
405	case is to compute the integer binary logarithm, i.e., C<floor (log2	482
		483	For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
		484
406	(n))>. For example:	485	For example:
407		486
408	ecb_ctz32 (3) = 0	487	ecb_ctz32 (3) = 0
409	ecb_ctz32 (6) = 1	488	ecb_ctz32 (6) = 1
410		489
		490	=item bool ecb_is_pot32 (uint32_t x)
		491
		492	=item bool ecb_is_pot64 (uint32_t x)
		493
		494	Return true iff C<x> is a power of two or C<x == 0>.
		495
		496	For smaller types then C<uint32_t> you can safely use C<ecb_is_pot32>.
		497
		498	=item int ecb_ld32 (uint32_t x)
		499
		500	=item int ecb_ld64 (uint64_t x)
		501
		502	Returns the index of the most significant bit set in C<x>, or the number
		503	of digits the number requires in binary (so that C<< 2**ld <= x <
		504	2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
		505	to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
		506	example to see how many bits a certain number requires to be encoded.
		507
		508	This function is similar to the "count leading zero bits" function, except
		509	that that one returns how many zero bits are "in front" of the number (in
		510	the given data type), while C<ecb_ld> returns how many bits the number
		511	itself requires.
		512
		513	For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
		514
411	=item int ecb_popcount32 (uint32_t x)	515	=item int ecb_popcount32 (uint32_t x)
412		516
		517	=item int ecb_popcount64 (uint64_t x)
		518
413	Returns the number of bits set to 1 in C<x>. For example:	519	Returns the number of bits set to 1 in C<x>.
		520
		521	For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
		522
		523	For example:
414		524
415	ecb_popcount32 (7) = 3	525	ecb_popcount32 (7) = 3
416	ecb_popcount32 (255) = 8	526	ecb_popcount32 (255) = 8
417		527
		528	=item uint8_t ecb_bitrev8 (uint8_t x)
		529
		530	=item uint16_t ecb_bitrev16 (uint16_t x)
		531
		532	=item uint32_t ecb_bitrev32 (uint32_t x)
		533
		534	Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
		535	and so on.
		536
		537	Example:
		538
		539	ecb_bitrev8 (0xa7) = 0xea
		540	ecb_bitrev32 (0xffcc4411) = 0x882233ff
		541
418	=item uint32_t ecb_bswap16 (uint32_t x)	542	=item uint32_t ecb_bswap16 (uint32_t x)
419		543
420	=item uint32_t ecb_bswap32 (uint32_t x)	544	=item uint32_t ecb_bswap32 (uint32_t x)
421		545
		546	=item uint64_t ecb_bswap64 (uint64_t x)
		547
422	These two functions return the value of the 16-bit (32-bit) value C<x>	548	These functions return the value of the 16-bit (32-bit, 64-bit) value
423	after reversing the order of bytes (0x11223344 becomes 0x44332211).	549	C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
		550	C<ecb_bswap32>).
		551
		552	=item uint8_t ecb_rotl8 (uint8_t x, unsigned int count)
		553
		554	=item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
		555
		556	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
		557
		558	=item uint64_t ecb_rotl64 (uint64_t x, unsigned int count)
		559
		560	=item uint8_t ecb_rotr8 (uint8_t x, unsigned int count)
		561
		562	=item uint16_t ecb_rotr16 (uint16_t x, unsigned int count)
424		563
425	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)	564	=item uint32_t ecb_rotr32 (uint32_t x, unsigned int count)
426		565
427	=item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)	566	=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
428		567
429	These two functions return the value of C<x> after rotating all the bits	568	These two families of functions return the value of C<x> after rotating
430	by C<count> positions to the right or left respectively.	569	all the bits by C<count> positions to the right (C<ecb_rotr>) or left
		570	(C<ecb_rotl>).
431		571
432	Current GCC versions understand these functions and usually compile them	572	Current GCC versions understand these functions and usually compile them
433	to "optimal" code (e.g. a single C<roll> on x86).	573	to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
		574	x86).
434		575
435	=back	576	=back
436		577
437	=head2 ARITHMETIC	578	=head2 ARITHMETIC
438		579
…		…
448	C<ecb_mod> implements the mathematical modulo operation, which is missing	589	C<ecb_mod> implements the mathematical modulo operation, which is missing
449	in the language.	590	in the language.
450		591
451	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be	592	C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
452	negatable, that is, both C<m> and C<-m> must be representable in its	593	negatable, that is, both C<m> and C<-m> must be representable in its
453	type (this typically includes the minimum signed integer value, the same	594	type (this typically excludes the minimum signed integer value, the same
454	limitation as for C</> and C<%> in C).	595	limitation as for C</> and C<%> in C).
455		596
456	Current GCC versions compile this into an efficient branchless sequence on	597	Current GCC versions compile this into an efficient branchless sequence on
457	many systems.	598	almost all CPUs.
458		599
459	For example, when you want to rotate forward through the members of an	600	For example, when you want to rotate forward through the members of an
460	array for increasing C<m> (which might be negative), then you should use	601	array for increasing C<m> (which might be negative), then you should use
461	C<ecb_mod>, as the C<%> operator might give either negative results, or	602	C<ecb_mod>, as the C<%> operator might give either negative results, or
462	change direction for negative values:	603	change direction for negative values:
463		604
464	for (m = -100; m <= 100; ++m)	605	for (m = -100; m <= 100; ++m)
465	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];	606	int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
466		607
		608	=item x = ecb_div_rd (val, div)
		609
		610	=item x = ecb_div_ru (val, div)
		611
		612	Returns C<val> divided by C<div> rounded down or up, respectively.
		613	C<val> and C<div> must have integer types and C<div> must be strictly
		614	positive. Note that these functions are implemented with macros in C
		615	and with function templates in C++.
		616
467	=back	617	=back
468		618
469	=head2 UTILITY	619	=head2 UTILITY
470		620
471	=over 4	621	=over 4
…		…
480	for (i = 0; i < ecb_array_length (primes); i++)	630	for (i = 0; i < ecb_array_length (primes); i++)
481	sum += primes [i];	631	sum += primes [i];
482		632
483	=back	633	=back
484		634
		635	=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
485		636
		637	These symbols need to be defined before including F<ecb.h> the first time.
		638
		639	=over 4
		640
		641	=item ECB_NO_THRADS
		642
		643	If F<ecb.h> is never used from multiple threads, then this symbol can
		644	be defined, in which case memory fences (and similar constructs) are
		645	completely removed, leading to more efficient code and fewer dependencies.
		646
		647	Setting this symbol to a true value implies C<ECB_NO_SMP>.
		648
		649	=item ECB_NO_SMP
		650
		651	The weaker version of C<ECB_NO_THREADS> - if F<ecb.h> is used from
		652	multiple threads, but never concurrently (e.g. if the system the program
		653	runs on has only a single CPU with a single core, no hyperthreading and so
		654	on), then this symbol can be defined, leading to more efficient code and
		655	fewer dependencies.
		656
		657	=back
		658
		659

Diff Legend

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

Comparing cvsroot/libecb/ecb.pod (file contents): Revision 1.27 by root, Wed Jun 1 01:29:36 2011 UTC vs. Revision 1.46 by sf-exg, Tue May 29 14:57:24 2012 UTC

Diff Legend

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.27 by root, Wed Jun 1 01:29:36 2011 UTC vs.
Revision 1.46 by sf-exg, Tue May 29 14:57:24 2012 UTC