mirror of
https://github.com/ETLCPP/etl.git
synced 2026-07-31 08:46:17 +08:00
421 lines
10 KiB
Markdown
421 lines
10 KiB
Markdown
---
|
|
title: "bitset"
|
|
---
|
|
|
|
{{< callout >}}
|
|
Header: `bitset.h`
|
|
Since: 20.33.0
|
|
Similar to: [std::bitset](https://en.cppreference.com/w/cpp/utility/bitset.html)
|
|
{{< /callout >}}
|
|
|
|
This is the new default bitset implementation, from 20.33.0 onwards.
|
|
For the older version, see [etl::bitset (legacy)]().
|
|
|
|
A fixed capacity bitset.
|
|
Has a number of extensions over `std::bitset`. Can be considered similar to an array of `bool`.
|
|
|
|
Internally defined buffers
|
|
```cpp
|
|
etl::bitset<size_t N>
|
|
etl::bitset<size_t N, typename TElement>
|
|
```
|
|
|
|
Externally defined buffers from `20.34.0`
|
|
```cpp
|
|
etl::bitset_ext<size_t N>
|
|
etl::bitset_ext<size_t N, typename TElement>
|
|
```
|
|
|
|
The template parameters will determine whether the bitset uses a common implementation or one of four fixed sized
|
|
implementations.
|
|
|
|
Note: `etl::ibitset` is no longer a reference type for any size `etl::bitset`.
|
|
|
|
---
|
|
|
|
`etl::bitset<size_t N>` and `etl::bitset_ext<size_t N>` on their own will use `unsigned char` as the underlying element type and the operations will be implemented by the generic protected member functions in `etl::ibitset`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset<size_t N, typename TElement>
|
|
```
|
|
```cpp
|
|
etl::bitset_ext<size_t N, typename TElement>
|
|
```
|
|
Specifying a type for `TElement` will override the default element type and define it as the *unsigned* type of `TElement`.
|
|
|
|
**Specialisations for maximum efficiency**
|
|
|
|
There are specialisations for when the required number of bits matches the number of bits in the element type.
|
|
These specialisations are considerably faster and more efficient.
|
|
|
|
```cpp
|
|
etl::bitset<8, uint8_t>
|
|
etl::bitset<16, uint16_t>
|
|
etl::bitset<32, uint32_t>
|
|
etl::bitset<8, uint64_t>
|
|
```
|
|
|
|
`any()`, `none()` and `all()` are overloaded in these specialisations to allow a mask to be specified, so that a bitset that requires less bits than the element type may still use the most efficient implementation.
|
|
|
|
```cpp
|
|
etl::bitset<8, uint8_t> bst; // But only want to use 6 bits.
|
|
bool any = bst.any(0x3F); // Check the lower 6 bits.
|
|
```
|
|
|
|
## Types
|
|
|
|
| Type | |
|
|
| - | - |
|
|
|`span_type` | A mutable span type. |
|
|
|`const_span_type`| A non-mutable span type. |
|
|
|`element_type` | The type used as the internal storage for a bitset. By default, this is unsigned char. |
|
|
|`buffer_type` | The type used as the to define the external buffer. Defined in `etl::bitset_ext` only. `20.34.0` |
|
|
|
|
## Constants
|
|
|
|
All `npos` values are equivalent.
|
|
```cpp
|
|
etl::bitset_constants::npos
|
|
```
|
|
```cpp
|
|
etl::bitset<>::npos
|
|
```
|
|
```cpp
|
|
template <size_t Size, typename TElement>
|
|
etl::bitset<Size, TElement>::npos
|
|
```
|
|
`Number_Of_Elements`
|
|
`Bits_Per_Element`
|
|
`Allocated_Bits`
|
|
`All_Set_Element`
|
|
`All_Clear_Element`
|
|
|
|
From: 20.38.11
|
|
`Storage_Model` `etl::bitset_storage_model::Single` or `etl::bitset_storage_model::Multi`
|
|
|
|
## Constructors
|
|
|
|
The initial state of the bitset is all clear (`false`).
|
|
|
|
```cpp
|
|
etl::bitset();
|
|
etl::bitset(unsigned long value);
|
|
etl::bitset(const char* str);
|
|
etl::bitset(const wchar_t* str);
|
|
etl::bitset(const char16_t* str);
|
|
etl::bitset(const char32_t* str);
|
|
```
|
|
**Description**
|
|
The bitset is either default constructed, initialised with a numeric value, or a text string of zeros and ones.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset_ext(element_type* pbuffer);
|
|
etl::bitset_ext(unsigned long value, element_type* pbuffer);
|
|
etl::bitset_ext(const char* str, element_type* pbuffer);
|
|
etl::bitset_ext(const wchar_t* str, element_type* pbuffer);
|
|
etl::bitset_ext(const char16_t* str, element_type* pbuffer);
|
|
etl::bitset_ext(const char32_t* str, element_type* pbuffer);
|
|
```
|
|
**Description**
|
|
The bitset is either default constructed, initialised with a numeric value, or a text string of zeros and ones.
|
|
A pointer to an external must be supplied that is large enough to hold the bitset.
|
|
The buffer may be defined as follows:-
|
|
```cpp
|
|
using Bitset = etl::bitset_ext<32>;
|
|
|
|
Bitset::element_type buffer[Bitset::Number_Of_Elements];
|
|
```
|
|
From: 20.34.0
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset_ext(buffer_type& buffer);
|
|
etl::bitset_ext(unsigned long value, buffer_type& buffer);
|
|
etl::bitset_ext(const char* str, buffer_type& buffer);
|
|
etl::bitset_ext(const wchar_t* str, buffer_type& buffer);
|
|
etl::bitset_ext(const char16_t* str, buffer_type& buffer);
|
|
etl::bitset_ext(const char32_t* str, buffer_type& buffer);
|
|
```
|
|
**Description**
|
|
The bitset is either default constructed, initialised with a numeric value, or a text string of zeros and ones.
|
|
An external buffer must be supplied that is large enough to hold the bitset.
|
|
The buffer may be defined as follows:-
|
|
```cpp
|
|
using Bitset = etl::bitset_ext<32>;
|
|
|
|
Bitset::buffer_type buffer;
|
|
```
|
|
From: 20.34.0
|
|
|
|
## Modifiers
|
|
|
|
```cpp
|
|
etl::bitset& set();
|
|
```
|
|
**Description**
|
|
Set all bits.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& set(element_type value);
|
|
```
|
|
**Description**
|
|
Set the bits to `value`.
|
|
Valid when the bitset width matches the element type width.
|
|
From: `20.34.0`
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& set(const char* str);
|
|
etl::bitset& set(const wchar_t* str);
|
|
etl::bitset& set(const char16_t* str);
|
|
etl::bitset& set(const char32_t* str);
|
|
```
|
|
**Description**
|
|
Set with a text string of `0` and `1` characters.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& set(size_t position, bool value = true);
|
|
```
|
|
**Description**
|
|
Set a position to a one or zero, default one.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& reset();
|
|
```
|
|
**Description**
|
|
Reset all bits.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& reset(size_t position);
|
|
```
|
|
**Description**
|
|
Set a position to a zero.
|
|
|
|
---
|
|
|
|
```cpp
|
|
etl::bitset& from_string(const char*);
|
|
etl::bitset& from_string(const wchar_t*);
|
|
etl::bitset& from_string(const char16_t*);
|
|
etl::bitset& from_string(const char32_t*);
|
|
```
|
|
**Description**
|
|
Alias of set.
|
|
The bitset is built from a string of `0` and `1` characters.
|
|
|
|
## Access
|
|
|
|
```cpp
|
|
template <typename T>
|
|
T value() const
|
|
```
|
|
**Description**
|
|
Returns the value corresponding to the bitset.
|
|
`T` specifies the integral type to convert to.
|
|
|
|
---
|
|
|
|
```cpp
|
|
unsigned long to_ulong() const
|
|
unsigned long long to_ullong() const
|
|
```
|
|
**Description**
|
|
Functions for compatibility with the STL.
|
|
Calls value<unsigned long>() or value<unsigned long long>().
|
|
|
|
If the type is too small to contain the bitset size, a compile time error will result.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename TString>
|
|
TString to_string(typename TString::value_type zero = typename TString::value_type('0'),
|
|
typename TString::value_type one = typename TString::value_type('1')) const
|
|
```
|
|
Returns the value as a string of `0` and `1` characters.
|
|
If the string type is not large enough to contain the digits then an `etl::bitset_string_too_small` is emitted.
|
|
|
|
---
|
|
|
|
```cpp
|
|
span_type span()
|
|
const_span_type span() const
|
|
```
|
|
**Description**
|
|
Returns an `etl::span` of the underlying binary data.
|
|
The span is ordered LSB to MSB.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T>
|
|
ETL_CONSTEXPR14
|
|
T extract(size_t position, size_t length = etl::integral_limits<T>::bits) const
|
|
```
|
|
**Description**
|
|
Extract an integral value from an arbitrary position and length.
|
|
Run time position and length.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T, size_t Position, size_t Length = etl::integral_limits<T>::bits>
|
|
ETL_CONSTEXPR14
|
|
T extract() const
|
|
```
|
|
**Description**
|
|
Extract an integral value from an arbitrary position and length.
|
|
Compile time position and length.
|
|
From: 20.38.11
|
|
For C++11 and above
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename T, size_t Position, size_t Length>
|
|
T extract() const
|
|
```
|
|
**Description**
|
|
Extract an integral value from an arbitrary position and length.
|
|
Compile time position and length.
|
|
From: `20.38.11`
|
|
For C++98/03
|
|
|
|
## Bit access
|
|
|
|
```cpp
|
|
bool operator[](size_t position) const
|
|
```
|
|
**Description**
|
|
Returns the boolean state of the indexed bit.
|
|
position is not checked for validity.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t count() const
|
|
```
|
|
**Description**
|
|
Returns the number of set bits.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t size() const
|
|
```
|
|
**Description**
|
|
Returns the number of bits supported by this bitset.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bool test(size_t position) const
|
|
```
|
|
**Description**
|
|
Returns the boolean state of the indexed bit.
|
|
position is not checked for validity.
|
|
|
|
---
|
|
|
|
```cpp
|
|
bool any() const
|
|
```
|
|
**Description**
|
|
Returns true if any of the bits are set, otherwise false.
|
|
|
|
```cpp
|
|
bool any(element_type mask) const
|
|
```
|
|
**Description**
|
|
Only enabled for bitsets that fit within one element.
|
|
Returns `true` if any of the bits are set, after the mask has been applied, otherwise `false`.
|
|
Valid when the bitset width matches the element type width.
|
|
From: `20.34.0`
|
|
|
|
---
|
|
|
|
```cpp
|
|
bool none() const
|
|
```
|
|
**Description**
|
|
Returns true if none of the bits are set, otherwise false.
|
|
|
|
```cpp
|
|
bool none(element_type mask) const
|
|
```
|
|
**Description**
|
|
Only enabled for bitsets that fit within one element.
|
|
Returns `true` if none of the bits are set, after the mask has been applied, otherwise `false`.
|
|
Valid when the bitset width matches the element type width.
|
|
From: `20.34.0`
|
|
|
|
---
|
|
|
|
```cpp
|
|
bool all() const
|
|
```
|
|
**Description**
|
|
Returns `true` if al of the bits are set, otherwise `false`.
|
|
|
|
```cpp
|
|
bool all(element_type mask) const
|
|
```
|
|
**Description**
|
|
Only enabled for bitsets that fit within one element.
|
|
Returns `true` if al of the bits are set, after the mask has been applied, otherwise `false`.
|
|
Valid when the bitset width matches the element type width.
|
|
From: `20.34.0`
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t find_first(bool state) const
|
|
```
|
|
**Description**
|
|
Returns the position of the first bit in the specified state. If not found then returns `bitset<>::npos`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t find_next(bool state, size_t position) const
|
|
```
|
|
**Description**
|
|
Returns the position of the next bit in the specified state, starting from position. If not found then returns `bitset<>::npos`.
|
|
`position` is not checked for validity.
|
|
|
|
## Bit operations
|
|
|
|
```cpp
|
|
bitset<size_t Size>& operator &= (const bitset<size_t Size>& rhs);
|
|
bitset<size_t Size>& operator |= (const bitset<size_t Size>& rhs);
|
|
bitset<size_t Size>& operator ^= (const bitset<size_t Size>& rhs);
|
|
bitset<size_t Size>& operator <<= (size_t shift);
|
|
bitset<size_t Size>& operator >>= (size_t shift);
|
|
bool operator == (const bitset<size_t Size>& rhs);
|
|
bool operator != (const bitset<size_t Size>& rhs);
|
|
```
|
|
|
|
## Non-member functions
|
|
|
|
```cpp
|
|
void swap(etl::bitset<Size>& lhs, etl::bitset<Size>& rhs)
|
|
```
|
|
**Description**
|
|
Swaps the contents of the two bitsets.
|
|
The bitsets must be the same size.
|
|
|