diff --git a/docs/raw/IO/Debounce.png b/docs/raw/IO/Debounce.png deleted file mode 100644 index bfc40a8e..00000000 Binary files a/docs/raw/IO/Debounce.png and /dev/null differ diff --git a/docs/raw/IO/io_port.txt b/docs/raw/IO/io_port.txt deleted file mode 100644 index 4a75edc1..00000000 --- a/docs/raw/IO/io_port.txt +++ /dev/null @@ -1,210 +0,0 @@ -io_port - ->= 20.39.0 -A set of templates for building interface classes to memory mapped hardware ports. -They avoid the need to directly map carefully packed (and possibly non-portable) structures onto memory addresses. - -Note: A read from a write-only, or write to a read-only port will result in a compile time error. - -Defines classes for the following IO types:- -Read / Write. -Read only. -Write only. -Write only with shadow register. - -With a shadow register, the value written is stored locally and may be read back. - -The port may either have an address fixed at compile time or set at runtime. The compile time versions require no extra overhead compared to a plain memory mapped structure. - -Ports may be sent as parameters to algorithms that expect iterators, except the runtime address version of io_port_wos, which must use the built-in iterator if the shadow value is to be correctly updated for writes. - -All classes define the following typedefs. - -T value_type -volatile T* pointer -volatile const T* const_pointer -volatile T& reference -volatile const T& const_reference - -Compile time port addresses -____________________________________________________________________________________________________ -io_port_rw -Read/write port. -io_port_rw -____________________________________________________________________________________________________ -iterator -const_iterator -____________________________________________________________________________________________________ -operator T() const -Read the value. Conversion operator to T. -____________________________________________________________________________________________________ -iterator iter() -Get an iterator to this port. -___________________________________________________________________________________________________ -const_iterator iter() const -const_iterator citer() const -Get a const_iterator to this port. -____________________________________________________________________________________________________ -T read() const -Read the value. -____________________________________________________________________________________________________ -void write(T value) -Write the value. -____________________________________________________________________________________________________ -io_port_rw& operator =(T value) -Write the value. -___________________________________________________________________________________________________ -pointer get_address() -const_pointer get_address() const -Gets the address of the port. -___________________________________________________________________________________________________ -io_port_rw& operator |=(value_type value) -Or-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator &=(value_type value) -And-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator ^=(value_type value) -Exclusive-Or-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator <<=(int shift) -Left-Shift-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator >>=(int shift) -Right-Shift-Equals operator. -___________________________________________________________________________________________________ -value_type operator ~() const -Not operator. -____________________________________________________________________________________________________ -io_port_ro -Read only port. -io_port_ro -____________________________________________________________________________________________________ -const_iterator -____________________________________________________________________________________________________ -operator T() const -Read the value. Conversion operator to T. -___________________________________________________________________________________________________ -const_iterator iter() const -const_iterator citer() const -Get a const_iterator to this port. -____________________________________________________________________________________________________ -T read() const -Read the value. -___________________________________________________________________________________________________ -const_pointer get_address() const -Gets the address of the port. -____________________________________________________________________________________________________ -io_port_wo -Write only port. -io_port_wo -____________________________________________________________________________________________________ -iterator -____________________________________________________________________________________________________ -iterator iter() -Get an iterator to this port. -____________________________________________________________________________________________________ -void write(T value) -Write the value. -____________________________________________________________________________________________________ -io_port_wo& operator =(T value) -Write the value. -___________________________________________________________________________________________________ -pointer get_address() -Gets the address of the port. -____________________________________________________________________________________________________ -io_port_wos -Write only port, with shadow register for reading. -io_port_wos -____________________________________________________________________________________________________ -iterator -const_iterator -____________________________________________________________________________________________________ -operator T() const -Read the value. Conversion operator to T. -____________________________________________________________________________________________________ -iterator iter() -Get an iterator to this port. -___________________________________________________________________________________________________ -const_iterator iter() const -const_iterator citer() const -Get a const_iterator to this port. -____________________________________________________________________________________________________ -T read() const -Read the value. -____________________________________________________________________________________________________ -void write(T value) -Write the value. -____________________________________________________________________________________________________ -io_port_rw& operator =(T value) -Write the value. -___________________________________________________________________________________________________ -pointer get_address() -const_pointer get_address() const -Gets the address of the port. -___________________________________________________________________________________________________ -io_port_rw& operator |=(value_type value) -Or-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator &=(value_type value) -And-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator ^=(value_type value) -Exclusive-Or-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator <<=(int shift) -Left-Shift-Equals operator. -___________________________________________________________________________________________________ -io_port_rw& operator >>=(int shift) -Right-Shift-Equals operator. -___________________________________________________________________________________________________ -value_type operator ~() const -Not operator. -____________________________________________________________________________________________________ -Example serial port - -The example uses a port at a compile time address. - -rxdata is an 8 bit read only port. -txdata is an 8 bit write only port. -control is a 16 bit write only port, with shadow register. -status is a 16 bit read only port. It shares an address with control. -option is an 8 bit read/write port. - -template -struct serial_port -{ - etl::io_port_ro rxdata; // Read only rx data register. - etl::io_port_wo txdata; // Write only tx register. - etl::io_port_wos control; // Write only, with shadow, control register. - etl::io_port_ro status; // Read only status register. - etl::io_port_ro option; // Read/Write register. -}; - -serial_port<0x800> port; // A serial port at address 0x800 - -// Read Rx data -char data = port.rxdata; - -// Write Tx data -port.txdata = 'A'; - -// Compile error! txdata is write only. -data = port.txdata; - -// Write to the control register and read back what we wrote. -port.control = 0x1234; -uint16_t control = port.control; - -// Flip bit 3 of the control register. -port.control ^= 0x0080; - -// Read from the status register. -uint16_t status = port.status; - -// Copy data from a buffer to the Tx data port. -std::copy(txBuffer.begin(), txBuffer.end(), serial_port.txdata.iter()); - -// Copy data from the Rx data port to a buffer. -std::copy_n(serial_port.rxdata, serial_port.status, std::back_inserter(rxBuffer)); - diff --git a/docs/raw/strings/basic_format_spec.txt b/docs/raw/strings/basic_format_spec.txt deleted file mode 100644 index ffd61d69..00000000 --- a/docs/raw/strings/basic_format_spec.txt +++ /dev/null @@ -1,211 +0,0 @@ -basic_format_spec -format_spec -wformat_spec -u16format_spec -u32format_spec - -A template class and four typedefs that allow a specification for string formatting functions and streams. -It defines specifications for strings, bool, integrals, floating point and pointers. -Used in conjunction with etl::to_string and string streams - -The class stores the following specifications: -base The number base. Predefined settings for binary, octal, decimal and hex. -width The total minimum field width for the value's text representation. -precision The total number of decimal places. -upper_case If true then numerical digits for bases >10 are in upper case. -left_justified If true then the text representation is left justified with padding up to the field width on the right. -boolalpha If true then Boolean values are rendered as "true" and "false". -showbase If true then binary, octal and hex values are prefixed with the base tag. -fill Determines the character used for the padding for width. -____________________________________________________________________________________________________ -basic_format_spec - -template -class basic_format_spec -____________________________________________________________________________________________________ -basic_format_spec() -The default constructor. -Sets:- -base : 10 -width : 0 -precision : 0 -upper case : false -left justified : false -boolalpha : false -show base -fill : ' ' -____________________________________________________________________________________________________ -basic_format_spec& base(const uint32_t b) -Sets the base to b. -____________________________________________________________________________________________________ -basic_format_spec& binary() -Sets the base to binary. -____________________________________________________________________________________________________ -basic_format_spec& octal() -Sets the base to octal. -____________________________________________________________________________________________________ -basic_format_spec& hex() -Sets the base to hexadecimal. -____________________________________________________________________________________________________ -basic_format_spec& octal() -Sets the base to octal. -____________________________________________________________________________________________________ -uint32_t get_base() const -Returns the current setting for base. -____________________________________________________________________________________________________ -basic_format_spec& width(const uint32_t w) -Sets the width to w. -____________________________________________________________________________________________________ -uint32_t get_width() const -Returns the current width value. -____________________________________________________________________________________________________ -basic_format_spec& precision(const uint32_t p) -Sets the precision to p. -____________________________________________________________________________________________________ -uint32_t get_precision() const -Returns the current precision value. -____________________________________________________________________________________________________ -basic_format_spec& upper_case(const bool b) -Sets the upper case flag to b. -Only affects numerical output such as hexadecimal. -____________________________________________________________________________________________________ -bool is_upper_case() const -Returns true if the upper case flag is set. -____________________________________________________________________________________________________ -basic_format_spec& show_base(const bool b) -Sets the showbase flag to b. -Only affects binary and hexadecimal output. -____________________________________________________________________________________________________ -bool is_show_base() const -Returns true if the showbase flag is set. -____________________________________________________________________________________________________ -basic_format_spec& fill(const typename TString::value_type c) -Sets the fill character to c. -____________________________________________________________________________________________________ -typename TString::value_type get_fill() const -Returns the fill character. -____________________________________________________________________________________________________ -basic_format_spec& left() -Sets the left justified flag to true. -____________________________________________________________________________________________________ -bool is_left() const -Returns true if the left justified flag is set. -____________________________________________________________________________________________________ -basic_format_spec& right() - -Sets the left justified flag to false. -____________________________________________________________________________________________________ -bool is_right() const -Returns true if the left justified flag is clear. -____________________________________________________________________________________________________ -basic_format_spec& boolalpha(bool b) -Sets the bool alpha flag to b. -____________________________________________________________________________________________________ -bool is_boolalpha() const -Returns true if the bool alpha flag is set. -____________________________________________________________________________________________________ -Typedefs - -typedef etl::basic_format_spec format_spec; -typedef etl::basic_format_spec wformat_spec; -typedef etl::basic_format_spec u16format_spec; -typedef etl::basic_format_spec u32format_spec; -____________________________________________________________________________________________________ -Stream manipulators -These manipulators are used in conjunction with the ETL's string streams. -Streams may also use a format spec as a manipulator. - -setbase(uint32_t base) -Sets the base for numerical output to base. -____________________________________________________________________________________________________ -setw(uint32_t width) -Sets the format width to width. -____________________________________________________________________________________________________ -template -setfill(TChar fill) -Sets the fill character to fill. -____________________________________________________________________________________________________ -setprecision(uint32_t precision) -Sets the number of decimal places to precision. -____________________________________________________________________________________________________ -bin -Sets the base for numerical output to binary. -____________________________________________________________________________________________________ -oct -Sets the base for numerical output to octal. -____________________________________________________________________________________________________ -dec -Sets the base for numerical output to decimal. -____________________________________________________________________________________________________ -hex -Sets the base for numerical output to hexadecimal. -____________________________________________________________________________________________________ -left -Sets the alignment to left. -____________________________________________________________________________________________________ -right -Sets the alignment to right. -____________________________________________________________________________________________________ -boolalpha -Sets the boolalpha flag to true. -____________________________________________________________________________________________________ -noboolalpha -Sets the boolalpha flag to false. -____________________________________________________________________________________________________ -uppercase -Sets the uppercase flag to true. -____________________________________________________________________________________________________ -nouppercase -Sets the uppercase flag to false. -____________________________________________________________________________________________________ -showbase -Sets the showbase flag to true. -____________________________________________________________________________________________________ -noshowbase -Sets the showbase flag to false. -____________________________________________________________________________________________________ -Example (to_string) - -etl::format_spec format; - -// Format as a hex character, minimum fill width of 8, fill with zeros. -format.hex().width(8).fill('0'); - -etl::string<8> text; - -// 'text' is set to "00123456" -etl::to_string(1193046, text, format); - -// Format minimum fill width of 8, fill with space and three decimal digits. -format.width(8).fill(' ').precision(3); - -// 'text' is set to " 3.142" -etl::to_string(3.1415, text, format); -____________________________________________________________________________________________________ -Example (string_stream) - -etl::string<20> buffer; -etl::string_stream stream(buffer); - -// Manipulators -stream << etl::showbase - << etl::bin << 123456 << " " - << etl::oct << 123456 << " " - << etl::dec << 123456 << " " - << etl::hex << 123456; - -The generated string:- - -0b11110001001000000 0361100 123456 0x1e240 - -// Format spec -etl::format_spec format; -format.show_base(true).hex(); - -stream << format << 123456; - -The generated string:- - -0x1e240 - - diff --git a/docs/raw/strings/String Utilities.txt b/docs/raw/strings/string_utilities.txt similarity index 100% rename from docs/raw/strings/String Utilities.txt rename to docs/raw/strings/string_utilities.txt diff --git a/docs/strings/_index.md b/docs/strings/_index.md index 34e94330..15de8ffb 100644 --- a/docs/strings/_index.md +++ b/docs/strings/_index.md @@ -2,3 +2,37 @@ title: "Strings" weight: 100 --- + +## String + +The library defines a set of string templates that have been specially tailored for embedded systems. +They have a maximum capacity fixed at compile time and make no calls to `malloc`/`free` or `new`/`delete`0. +They are completely deterministic. +The ETL provides `etl::string`, `etl::wstring`, `etl::u16string` and `etl::u32string`. + +## String View + +The ETL defines string view classes that provide a lost cost view into a string. +The ETL provides `etl::string_view`, `etl::wstring_view`, `etl::u16string_view` and `etl::u32string_view`. + +## To String + +The ETL defines a utility to create strings according to a format. +The ETL provides `etl::to_string`, `etl::to_wstring`, `etl::to_u16string` and `etl::to_u32string`. + +## To Arithmetic + +The ETL defines a utility to convert strings to values. + +## String Stream + +The ETL defines string stream classes that stream values into a string. +The ETL provides `etl::string_stream`, `etl::wstring_stream`, `etl::u16string_stream`, and `etl::u32string_stream`. + +## String Utilities + +The ETL provides a set of string to examine and manipulate strings. + +## Format Specification + +A class is defined to format the output of `etl::to_string`, `etl::to_wstring`, `etl::to_u16string`, and `etl::to_u32string`. diff --git a/docs/strings/basic_format_spec.md b/docs/strings/basic_format_spec.md new file mode 100644 index 00000000..1be768ea --- /dev/null +++ b/docs/strings/basic_format_spec.md @@ -0,0 +1,410 @@ +--- +title: "basic_format_spec" +--- + +`format_spec` +`wformat_spec` +`u16format_spec` +`u32format_spec` + +A template class and four typedefs that allow a specification for string formatting functions and streams. +It defines specifications for strings, bool, integrals, floating point and pointers. +Used in conjunction with `etl::to_string` and string streams + +The class stores the following specifications: +| Specification | Description | +| -------------- | -------------------------------------------------------------------------- | +| base | The number base. Predefined settings for binary, octal, decimal and hex. | +| width | The total minimum field width for the value's text representation. | +| precision | The total number of decimal places. | +| upper_case | If true then numerical digits for bases >10 are in upper case. | +| left_justified | If true then the text representation is left justified with padding up to the field width on the right. | +| boolalpha | If true then Boolean values are rendered as "true" and "false". | +| showbase | If true then binary, octal and hex values are prefixed with the base tag. | +| fill | Determines the character used for the padding for width. | + +## basic_format_spec + +```cpp +template +class basic_format_spec +``` +--- + +```cpp +basic_format_spec() +``` +**Description** +The default constructor. +Sets:- +| Specification | Default | +| ---------------- | ------- | +| `base` | `10` | +| `width` | `0` | +| `precision` | `0` | +| `upper case` | `false` | +| `left justified` | `false` | +| `boolalpha` | `false` | +| `show base` | `false` | +| `fill` | `' '` | + +```cpp +basic_format_spec& base(const uint32_t b) +``` +**Description** +Sets the base to b. + +--- + +```cpp +basic_format_spec& binary() +``` +**Description** +Sets the base to binary. + +--- + +```cpp +basic_format_spec& octal() +``` +**Description** +Sets the base to octal. + +--- + +```cpp +basic_format_spec& hex() +``` +**Description** +Sets the base to hexadecimal. + +--- + +```cpp +basic_format_spec& octal() +``` +**Description** +Sets the base to octal. + +--- + +```cpp +uint32_t get_base() const +``` +**Description** +Returns the current setting for base. + +--- + +```cpp +basic_format_spec& width(const uint32_t w) +``` +**Description** +Sets the width to `w`. + +--- + +```cpp +uint32_t get_width() const +``` +**Description** +Returns the current width value. + +--- + +```cpp +basic_format_spec& precision(const uint32_t p) +``` +**Description** +Sets the precision to `p`. + +```cpp +uint32_t get_precision() const +``` +**Description** +Returns the current precision value. + +--- + +```cpp +basic_format_spec& upper_case(const bool b) +``` +**Description** +Sets the upper case flag to `b`. +Only affects numerical output such as hexadecimal. + +--- + +```cpp +bool is_upper_case() const +``` +**Description** +Returns true if the upper case flag is set. + +--- + +```cpp +basic_format_spec& show_base(const bool b) +``` +**Description** +Sets the showbase flag to `b`. +Only affects binary and hexadecimal output. + +--- + +```cpp +bool is_show_base() const +``` +**Description** +Returns `true` if the `showbase` flag is set. + +--- + +```cpp +basic_format_spec& fill(const typename TString::value_type c) +``` +**Description** +Sets the fill character to `c`. + +--- + +```cpp +typename TString::value_type get_fill() const +``` +**Description** +Returns the fill character. + +--- + +```cpp +basic_format_spec& left() +``` +**Description** +Sets the `left` justified flag to `true`. + +--- + +```cpp +bool is_left() const +``` +**Description** +Returns `true` if the `left` justified flag is set. + +--- + +```cpp +basic_format_spec& right() +``` +**Description** +Sets the left justified flag to false. + +--- + +```cpp +bool is_right() const +``` +**Description** +Returns `true` if the `left` justified flag is clear. + +```cpp +basic_format_spec& boolalpha(bool b) +``` +**Description** +Sets the `bool alpha` flag to `b`. + +--- + +```cpp +bool is_boolalpha() const +``` +Returns `true` if the `bool alpha` flag is set. + +## Typedefs + +| Type | Specialisation | +| -------------- | --------------------------------------- | +| format_spec | etl::basic_format_spec | +| wformat_spec | etl::basic_format_spec | +| u16format_spec | etl::basic_format_spec | +| u32format_spec | etl::basic_format_spec | + +## Stream manipulators +These manipulators are used in conjunction with the ETL's string streams. +Streams may also use a `format_spec` as a manipulator. + +```cpp +setbase(uint32_t base) +``` +**Description** +Sets the base for numerical output to base. + +--- + +```cpp +setw(uint32_t width) +``` +**Description** +Sets the format width to `width`. + +--- + +```cpp +template +setfill(TChar fill) +``` +**Description** +Sets the fill character to fill. + +--- + +```cpp +setprecision(uint32_t precision) +``` +**Description** +Sets the number of decimal places to precision. + +--- + +```cpp +bin +``` +**Description** +Sets the base for numerical output to binary. + +--- + +```cpp +oct +``` +**Description** +Sets the base for numerical output to octal. + +--- + +```cpp +dec +``` +**Description** +Sets the base for numerical output to decimal. + +--- + +```cpp +hex +``` +**Description** +Sets the base for numerical output to hexadecimal. + +--- + +```cpp +left +``` +**Description** +Sets the alignment to left. + +--- + +```cpp +right +``` +**Description** +Sets the alignment to right. + +--- + +```cpp +boolalpha +``` +**Description** +Sets the boolalpha flag to true. + +--- + +```cpp +noboolalpha +``` +**Description** +Sets the boolalpha flag to false. + +--- + +```cpp +uppercase +``` +**Description** +Sets the uppercase flag to true. + +--- + +```cpp +nouppercase +``` +**Description** +Sets the uppercase flag to false. + +--- + +```cpp +showbase +``` +**Description** +Sets the showbase flag to true. + +--- + +```cpp +noshowbase +``` +**Description** +Sets the showbase flag to false. + +## Example (to_string) + +```cpp +etl::format_spec format; + +// Format as a hex character, minimum fill width of 8, fill with zeros. +format.hex().width(8).fill('0'); + +etl::string<8> text; + +// 'text' is set to "00123456" +etl::to_string(1193046, text, format); + +// Format minimum fill width of 8, fill with space and three decimal digits. +format.width(8).fill(' ').precision(3); + +// 'text' is set to " 3.142" +etl::to_string(3.1415, text, format); +``` + +## Example (string_stream) +```cpp +etl::string<20> buffer; +etl::string_stream stream(buffer); + +// Manipulators +stream << etl::showbase + << etl::bin << 123456 << " " + << etl::oct << 123456 << " " + << etl::dec << 123456 << " " + << etl::hex << 123456; +``` +The generated string:- + +`0b11110001001000000 0361100 123456 0x1e240` + +--- + +```cpp +// Format spec +etl::format_spec format; +format.show_base(true).hex(); + +stream << format << 123456; +``` + +The generated string:- + +`0x1e240`