Revision 1.23 by

Revision 1.24 by

… | … | ||
---|---|---|---|

15 | It mainly provides a number of wrappers around GCC built-ins, together | 15 | It mainly provides a number of wrappers around GCC built-ins, together |

16 | with replacement functions for other compilers. In addition to this, | 16 | with replacement functions for other compilers. In addition to this, |

17 | it provides a number of other lowlevel C utilities, such as endianness | 17 | it provides a number of other lowlevel C utilities, such as endianness |

18 | detection, byte swapping or bit rotations. | 18 | detection, byte swapping or bit rotations. |

19 | 19 | ||

20 | Or in other words, things that should be built-in into any standard C | 20 | Or in other words, things that should be built into any standard C system, |

21 | system, but aren't. | 21 | but aren't, implemented as efficient as possible with GCC, and still |

22 | correct with other compilers. | ||

22 | 23 | ||

23 | More might come. | 24 | More might come. |

24 | 25 | ||

25 | =head2 ABOUT THE HEADER | 26 | =head2 ABOUT THE HEADER |

26 | 27 | ||

… | … | ||

386 | 387 | ||

387 | These two functions return true if the byte order is big endian | 388 | These 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 |

389 | first) respectively. | 390 | first) respectively. |

390 | 391 | ||

392 | On 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 | ||

393 | Returns the index of the least significant bit set in C<x> (or | 396 | Returns the index of the least significant bit set in C<x> (or |

394 | equivalently the number of bits set to 0 before the least significant | 397 | equivalently the number of bits set to 0 before the least significant bit |

395 | bit set), starting from 0. If C<x> is 0 the result is undefined. A | 398 | set), starting from 0. If C<x> is 0 the result is undefined. A common use |

396 | common use case is to compute the integer binary logarithm, i.e., | 399 | case is to compute the integer binary logarithm, i.e., C<floor (log2 |

397 | floor(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 | ||

434 | Returns the positive remainder of the modulo operation between C<m> and | 437 | Returns the positive remainder of the modulo operation between C<m> and |

435 | C<n>. Unlike the C modulo operator C<%>, this function ensures that the | 438 | C<n>, using floored division. Unlike the C modulo operator C<%>, this |

436 | return value is always positive - ISO C guarantees very little when | 439 | function ensures that the return value is always positive and that the two |

437 | negative numbers are used with C<%>. | 440 | numbers I<m> and I<m' = m + i * n> result in the same value modulo I<n> - |

441 | the C<%> operator usually has a behaviour change at C<m = 0>. | ||

438 | 442 | ||

439 | C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be | 443 | C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be |

440 | negatable, that is, both C<m> and C<-m> must be representable in its | 444 | negatable, that is, both C<m> and C<-m> must be representable in its |

441 | type. | 445 | type. |

442 | 446 | ||

447 | Current GCC versions compile this into an efficient branchless sequence on | ||

448 | many systems. | ||

449 | |||

450 | For example, when you want to rotate forward through the members of an | ||

451 | array for increasing C<m> (which might be negative), then you should use | ||

452 | C<ecb_mod>, as the C<%> operator might give either negative results, or | ||

453 | change 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 |

– |
Removed lines |

+ |
Added lines |

< |
Changed lines |

> |
Changed lines |