coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-06-15 16:36:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
etl/docs/binary/binary.md
John Wellbelove 4a88884b39
Issue/add hugo support for documentation (#1449) 
* Add ranges

* Initial Hugo setup

* Work in progress

* Added selection for local or remote site

* Updated to 'light' theme

* Changed to using Hextra Hugo theme

* Changed to using Hextra Hugo theme

* Changed to Hextra Hugo theme

* Change to Hextra Hugo theme

* Updated Hugo setup.

* Updated Hugo setup.

# Conflicts:
#	docs/releases/_index.md

* Work in progress

* Added new fonts

Added new documentation

* Latest documentation updates

* Latest documentation updates

# Conflicts:
#	docs/containers/array.md
#	docs/containers/array_view.md
#	docs/containers/array_wrapper.md
#	docs/containers/bip_buffer_spsc_atomic.md
#	docs/containers/bitset.md
#	docs/containers/indirect_vector.md
#	docs/containers/vector.md
#	docs/getting-started/compilers.md

* Added bloom_filter markdown doc

* Added more documentation

Updated CSS for light and dark modes

* Fixed some menus

Added mode documentation files

* Updated CSS rules

Added badges to home page
Added uniqur_ptr + pool tutorial

* Fixed formatting on the home page markdown

Modified light amd dark code formatting

* Updated unique_ptr-with-pool

* Added container and shared message tutorials

* Updates to documentation

* Added const_multimap

* Updated source-formatting.md

* Added initial raw text files form Web site editor

* Innore coverage build directory

* Exported raw text documentation files from the web site editor

* Hugo updates

* Added Hugo intalation and markdown descriptions

* More addition to the documentation

* Added closure.md and updates to delegate.md

* Added format.md

* Added documentation for etl::delegate_observable, etl::function, Base64 codec

* Added io_port documentation

* Added basic_format_spec

* Added documentation for string_stream and string utilities.

* Added more documentation

Updated the documentation CSS

* Added documentation for clocks, day, duration

* Added more documentation for chrono classes

Updated callouts

* More chrono documentation

* Completed chrono documentation

* Maths functions documentation

* Completed maths documentation

* Completed maths documentation

* Completed maths documentation

* Completed maths documentation

* Added multiple documentation files

* Added iterator.md

* Added debug_count.md and versions.md

* Added debug_count.md and versions.md

* Added more documentation

* More documentation

* Added some design pattern documentation

Modified some of the layout files
Modified the About documentation

* Converted more documentation pages

Modified the site CSS

* Added more documentation

Moced some documentation files to new directories

* Added more documentation

Tweaks to CSS

* Added callback_timer_deferred_locked documentation

* Added callback_timer_locked documentation

* More documentation updates

* More documentation updates

* More documentation updates

* New documentation files.

Harmonised file name format

* New documentation files.

* Multiple document updates

* Multiple document updates

* Final conversion of web pages

* Updates before PR

* Updates before PR

* Updates before PR

# Conflicts:
#	docs/blog/_index.md

* Final pre PR updates

* Updates to message framework documentation

* Renamed directory

* Fix spelling

* Added author and date to blog files

Moved documentation files merged from development

* Fixed 'Description' typo

* Fix typos

# Conflicts:
#	docs/IO/io_port.md
#	docs/containers/sets/const-multiset.md
#	docs/containers/sets/const-set.md
#	docs/maths/correlation.md
#	docs/maths/gamma.md

* Renamed two files to lower case

* Minor renaming

* Added author and date

* Updated callout on bresenham_line.md

Added support for showing the ETL version on the documentation first page, by copying the version.txt file as a hugo asset.
Updated the Python 'update_release.py' to copy 'version.txt'

* Replace space in filename with hyphen.

Added more information to hugo-commands.md

* Replace space in filename with hyphen.

Added more information to hugo-commands.md

# Conflicts:
#	docs/getting-started/view-the-docs-locally/hugo-commands.md

* Added a link to pseudo_moving_average.md

* Updated title pages for groups

* Fixed missing 404 for non-existent pages

* Fixed coordinate variable names in the 'Calculating the intersection' example

---------

Co-authored-by: Roland Reichwein <Roland.Reichwein@bmw.de>
Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.com>
Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.co.uk>
2026-06-06 13:12:44 +01:00

575 lines
11 KiB
Markdown
Raw Blame History

---
title: binary
---
{{< callout type="info">}}
Header: `binary.h`
Since: `TBC`
{{< /callout >}}
Utility functions for manipulating binary numbers.
## Rotate
Rotate the bits in the value left or right.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value)
```
**Return**
`value` rotated left by one bit.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_left(T value, size_t distance)
```
**Return**
`value` rotated left by `distance`.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value)
```
**Return**
`value` rotated right by one bit.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate_right(T value, size_t distance)
```
**Return**
`value` rotated right by `distance`.
```cpp
template <typename T>
ETL_CONSTEXPR14 T rotate(T value, typename etl::make_signed<size_t>::type distance)
```
**Parameters**
`distance` Positive is left, negative is right.
**Return**
`value` rotated left or right by `distance`.
## reverse_bits
Reverse the order of the bits in a value.
```cpp
template <typename T>
ETL_CONSTEXPR14 T reverse_bits(T value)
```
The structures below define a member constant value that is Value reversed in bits.
```cpp
template <int8_t Value>
struct reverse_bits_const<int8_t, Value>
```
```cpp
template <uint8_t Value>
struct reverse_bits_const<uint8_t, Value>
```
```cpp
template <int16_t Value>
struct reverse_bits_const<int16_t, Value>
```
```cpp
template <uint16_t Value>
struct reverse_bits_const<uint16_t, Value>
```
```cpp
template <int32_t Value>
struct reverse_bits_const<int32_t, Value>
```
```cpp
template <uint32_t Value>
struct reverse_bits_const<uint32_t, Value>
```
```cpp
template <int64_t Value>
struct reverse_bits_const<int64_t, Value>
```
```cpp
template <uint64_t Value>
struct reverse_bits_const<uint64_t, Value>
```
Defines `value` The reversed bits.
## reverse_bytes
Reverse the order of the bytes in a value.
```cpp
template <typename T>
ETL_CONSTEXPR14 T reverse_bytes(T value)
```
## gray_to_binary
```cpp
template <typename T>
ETL_CONSTEXPR14 T gray_to_binary(T value)
```
Converts a gray code value to binary.
## binary_to_gray
```cpp
template <typename T>
ETL_CONSTEXPR T binary_to_gray(T value)
```
Converts a binary value to the gray code equivalent.
## count_bits
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t count_bits(T value)
```
**Return**
The number of set bits in `value`.
## parity
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t parity(T value)
```
**Return**
`1` if the parity of the value is odd, `0` if it is even.
## max_value_for_nbits
```cpp
template <size_t NBits>
struct max_value_for_nbits
```
**Return**
Maximum unsigned value a particular number of bits can represent.
`value_type` The type for the value.
`value` The maximum value.
## fold_bits
```cpp
template <typename TReturn, size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn fold_bits(TValue value)
```
**Description**
Fold a binary number down to a set number of bits using XOR.
**Example**
`0xE8C9AACCBC3D9A8F` folded down to 20 bits = `0x998E8`
```cpp
uint32_t result = etl::fold_bits<uint32_t, 20>(0xE8C9AACCBC3D9A8F);
```
## sign_extend
Sign extends a binary number.
```cpp
template <typename TReturn, size_t NBits, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
---
```cpp
template <typename TReturn, size_t NBits, size_t Shift, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, and `Shift` is the right shift amount, to a signed integral type.
---
```cpp
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, to a signed integral type.
---
```cpp
template <typename TReturn, typename TValue>
ETL_CONSTEXPR14 TReturn sign_extend(TValue value, size_t nbits, size_t shift)
```
**Description**
Converts an N bit binary number, where bit N-1 is the sign bit, and shift is the right shift amount, to a signed integral type.
## count_leading_zeros
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t count_leading_zeros(T value)
```
**Description**
Counts the number of leading zeros in a binary number
## count_trailing_zeros
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t count_trailing_zeros(T value)
```
**Description**
Counts the number of trailing zeros in a binary number
## count_leading_ones
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t count_leading_ones(T value)
```
**Description**
Counts the number of leading ones in a binary number
## count_trailing_ones
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t count_trailing_ones(T value)
```
**Description**
Counts the number of trailing ones in a binary number
## first_set_bit_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_set_bit_position(T value)
```
**Description**
Finds the index of the first set bit from lsb.
## first_clear_bit_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_clear_bit_position(T value)
```
**Description**
Finds the index of the first clear bit from lsb.
## first_bit_position
```cpp
template <typename T>
ETL_CONSTEXPR14 uint_least8_t first_bit_position(bool state, T value)
```
**Description**
Finds the index of the first bit in the specified state, from lsb.
## binary_fill
```cpp
template <typename TResult, typename TValue>
ETL_CONSTEXPR TResult binary_fill(TValue value)
```
Fills a value of the specified width with a repeating binary pattern.
*Run time*
Generate `0x12121212`
```cpp
etl::binary_fill<uint32_t>(uint8_t(0x12));
```
---
```cpp
template <typename TResult, typename TValue, TValue Value>
ETL_CONSTEXPR TResult binary_fill()
```
*Partial compile time*
Generate `0x12121212`
```cpp
etl::binary_fill<uint32_t, uint8_t, 0x12>();
```
## has_zero_byte
```cpp
template <typename TValue>
ETL_CONSTEXPR14 bool has_zero_byte(TValue value)
```
*Run time*
Checks to see if a value contains a byte of value zero.
**Example**
`etl::has_zero_byte(uint32_t(0x01234567)) == false`
`etl::has_zero_byte(uint32_t(0x01230067)) == true`
---
```cpp
template <typename TValue, TValue Value>
ETL_CONSTEXPR14 bool has_zero_byte()
```
Checks to see if `Value` contains a byte of value zero.
*Compile time value*
## has_byte_n
Checks to see if a value contains a byte of a particular value.
```cpp
template <typename TValue>
ETL_CONSTEXPR14 bool has_byte_n(TValue value, uint8_t n)
```
*Run time*
```cpp
etl::has_byte_n(uint32_t(0x01234567), 0x12) == false
etl::has_byte_n(uint32_t(0x01234567), 0x45) == true
```
---
```cpp
template <typename TValue, TValue Value>
ETL_CONSTEXPR14 bool has_byte_n(TValue value)
```
*Partial compile time*
```cpp
etl::has_byte_n<0x12>(uint32_t(0x01234567)) == false
etl::has_byte_n<0x45>(uint32_t(0x01234567)) == true
```
## binary_merge
Merges two binary values according to a mask.
Bits set in the mask select bits in the first value, clear bits select those in the second.
```cpp
template <typename T>
ETL_CONSTEXPR T binary_merge(T first, T second, T mask)
```
```cpp
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge(first, second, mask) Equals 0x14
```
---
```cpp
template <typename T, T Mask>
ETL_CONSTEXPR T binary_merge(T first, T second)
```
```cpp
uint8_t first = 0x12;
uint8_t second = 0x34;
const uint8_t mask = 0xF0;
etl::binary_merge<uint8_t, mask>(first, second) Equals 0x14
```
## binary_interleave
Interleaves two values such that bits abcd and efgh will result in eafbgchd.
```cpp
ETL_CONSTEXPR14 uint16_t binary_interleave(uint8_t first, uint8_t second);
ETL_CONSTEXPR14 uint32_t binary_interleave(uint16_t first, uint16_t second);
ETL_CONSTEXPR14 uint64_t binary_interleave(uint32_t first, uint32_t second);
```
## Odd / Even
Determines the odd or evenness of a value.
```cpp
template <typename T>
ETL_CONSTEXPR bool is_odd(T value)
```
```cpp
template <typename T>
ETL_CONSTEXPR bool is_even(T value)
```
## Constants
```cpp
enum binary_constant
```
An enumeration of 256 constants from `b00000000` to `b11111111` (`0` to `255`)
---
```cpp
enum bit_constant
```
An enumeration of 32 constants from `b0` to `b31` (`1` to `4294967296`)
---
```cpp
template <size_t Position>
struct bit
```
`value_type` The type of the value.
`value` The value of the bit at `Position`.
## Creating bit masks
These classes and constexpr functions help create lsb and msb masks.
```cpp
template <typename T, size_t NBits>
class lsb_mask;
```
Defines the member constant value as a binary value of NBits `1` shift to the LSB.
e.g. `lsb_mask<int8_t, 3>::value == 0b00000111`
From: `20.34.0`
---
```cpp
template <typename T>
ETL_CONSTEXPR T make_lsb_mask(size_t nbits)
```
Returns a binary value of nbits `1` shift to the LSB.
e.g. `make_lsb_mask<int8_t>(3) == 0b00000111`
From: `20.34.0`
---
```cpp
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_lsb_mask()
```
**Description**
Returns a binary value of nbits `1` shift to the LSB.
e.g. `make_lsb_mask<int8_t, 3>() == 0b00000111`
From: `20.38.7`
---
```cpp
template <typename T, size_t NBits>
class msb_mask;
```
**Return**
A binary value of nbits `1` shift to the MSB.
e.g. `msb_mask<int8_t, 3>::value == 0b11100000`
From: `20.34.0`
---
```cpp
template <typename T>
ETL_CONSTEXPR T make_msb_mask(size_t nbits)
```
**Description**
Defines the member constant value as a binary value of NBits `1` shift to the MSB.
e.g. `make_msb_mask<int8_t>(3) == 0b11100000`
20.34.0
---
```cpp
template <typename T, size_t NBits>
ETL_CONSTEXPR T make_msb_mask()
```
**Description**
Defines the member constant value as a binary value of NBits `1` shift to the MSB.
e.g. `make_msb_mask<int8_t, 3>() == 0b11100000`
From: `20.38.7`
## Bit manipulation functors
These functors are most useful where lambdas are not available.
## binary_not
```cpp
template <typename T>
struct binary_not : public etl::unary_function<T, T>;
```
From: `20.38.11`
---
```cpp
ETL_CONSTEXPR
binary_not()
```
**Description**
Default constructor.
---
```cpp
ETL_CONSTEXPR
ETL_NODISCARD
T operator()(T value) const ETL_NOEXCEPT
```
**Return**
~value.
## binary_and
```cpp
template <typename T>
struct binary_and : public etl::unary_function<T, T>;
```
From: `20.38.11`
---
```cpp
ETL_CONSTEXPR
explicit binary_and(T and_value)
```
**Description**
Constructor.
---
```cpp
ETL_CONSTEXPR
ETL_NODISCARD
T operator()(T value) const ETL_NOEXCEPT
```
**Return**
`value & and_value`.
## binary_or
```cpp
template <typename T>
struct binary_or : public etl::unary_function<T, T>;
```
From: `20.38.11`
---
```cpp
ETL_CONSTEXPR
explicit binary_or(T or_value)
```
**Description**
Constructor.
---
```cpp
ETL_CONSTEXPR
ETL_NODISCARD
T operator()(T value) const ETL_NOEXCEPT
```
**Return**
`value | or_value`.
## binary_xor
```cpp
template <typename T>
struct binary_xor : public etl::unary_function<T, T>;
```
From: `20.38.11`
---
```cpp
ETL_CONSTEXPR
explicit binary_xor(T xor_value)
```
**Description**
Constructor.
---
```cpp
ETL_CONSTEXPR
ETL_NODISCARD
T operator()(T value) const ETL_NOEXCEPT
```
**Return**
value ^ xor_value.
Reference in New Issue View Git Blame Copy Permalink