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

Comparing libecb/ecb.pod (file contents):
Revision 1.22 by root, Fri May 27 00:18:14 2011 UTC vs.
Revision 1.24 by root, Tue May 31 21:10:37 2011 UTC

… …
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around GCC built-ins, together
16with replacement functions for other compilers. In addition to this, 16with replacement functions for other compilers. In addition to this,
17it provides a number of other lowlevel C utilities, such as endianness 17it provides a number of other lowlevel C utilities, such as endianness
18detection, byte swapping or bit rotations. 18detection, byte swapping or bit rotations.
19 19
20Or in other words, things that should be built-in into any standard C 20Or in other words, things that should be built into any standard C system,
21system, but aren't. 21but aren't, implemented as efficient as possible with GCC, and still
22correct with other compilers.
22 23
23More might come. 24More might come.
24 25
25=head2 ABOUT THE HEADER 26=head2 ABOUT THE HEADER
26 27
… …
386 387
387These two functions return true if the byte order is big endian 388These two functions return true if the byte order is big endian
388(most-significant byte first) or little endian (least-significant byte 389(most-significant byte first) or little endian (least-significant byte
389first) respectively. 390first) respectively.
390 391
392On systems that are neither, their return values are unspecified.
393
391=item int ecb_ctz32 (uint32_t x) 394=item int ecb_ctz32 (uint32_t x)
392 395
393Returns the index of the least significant bit set in C<x> (or 396Returns the index of the least significant bit set in C<x> (or
394equivalently the number of bits set to 0 before the least significant 397equivalently the number of bits set to 0 before the least significant bit
395bit set), starting from 0. If C<x> is 0 the result is undefined. A 398set), starting from 0. If C<x> is 0 the result is undefined. A common use
396common use case is to compute the integer binary logarithm, i.e., 399case is to compute the integer binary logarithm, i.e., C<floor (log2
397floor(log2(n)). For example: 400(n))>. For example:
398 401
399 ecb_ctz32 (3) = 0 402 ecb_ctz32 (3) = 0
400 ecb_ctz32 (6) = 1 403 ecb_ctz32 (6) = 1
401 404
402=item int ecb_popcount32 (uint32_t x) 405=item int ecb_popcount32 (uint32_t x)
… …
430=over 4 433=over 4
431 434
432=item x = ecb_mod (m, n) 435=item x = ecb_mod (m, n)
433 436
434Returns the positive remainder of the modulo operation between C<m> and 437Returns the positive remainder of the modulo operation between C<m> and
435C<n>. Unlike the C modulo operator C<%>, this function ensures that the 438C<n>, using floored division. Unlike the C modulo operator C<%>, this
436return value is always positive - ISO C guarantees very little when 439function ensures that the return value is always positive and that the two
437negative numbers are used with C<%>. 440numbers I<m> and I<m' = m + i * n> result in the same value modulo I<n> -
441the C<%> operator usually has a behaviour change at C<m = 0>.
438 442
439C<n> must be strictly positive (i.e. C<< >1 >>), while C<m> must be 443C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
440negatable, that is, both C<m> and C<-m> must be representable in its 444negatable, that is, both C<m> and C<-m> must be representable in its
441type. 445type.
442 446
447Current GCC versions compile this into an efficient branchless sequence on
448many systems.
449
450For example, when you want to rotate forward through the members of an
451array for increasing C<m> (which might be negative), then you should use
452C<ecb_mod>, as the C<%> operator might give either negative results, or
453change direction for negative values:
454
455 for (m = -100; m <= 100; ++m)
456 int elem = myarray [ecb_mod (m, ecb_array_length (myarray))];
457
443=back 458=back
444 459
445=head2 UTILITY 460=head2 UTILITY
446 461
447=over 4 462=over 4
448 463
449=item element_count = ecb_array_length (name) [MACRO] 464=item element_count = ecb_array_length (name)
450 465
451Returns the number of elements in the array C<name>. For example: 466Returns the number of elements in the array C<name>. For example:
452 467
453 int primes[] = { 2, 3, 5, 7, 11 }; 468 int primes[] = { 2, 3, 5, 7, 11 };
454 int sum = 0; 469 int sum = 0;

Diff Legend

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