diff --git a/docs/about.md b/docs/about.md index 344a96f8..6ca552de 100644 --- a/docs/about.md +++ b/docs/about.md @@ -40,6 +40,13 @@ The application is liable to have a close coupling with the solution. For exampl >ISEP - It's Somebody Else's Problem >GIRFT - Get It Right First Time +## Why not use 'C'? +**Greenspun's Tenth Rule** has an unofficial C corollary: +*"Any sufficiently advanced C program contains an ad hoc, informally specified, bug-ridden, slow implementation of half of C++."* + +I spent 12 years programming in pure C. +I discovered that I had been reverse engineering C++ all that time. + ## About me I have been involved in technology and computer systems for all of my working life and have amassed considerable knowledge of designing and implementing systems that are both performant and correct. My role normally encompasses the entire project life-cycle, from specification to maintenance phase. diff --git a/docs/callbacks/delegate_observable.md b/docs/callbacks/delegate_observable.md new file mode 100644 index 00000000..d611c1e1 --- /dev/null +++ b/docs/callbacks/delegate_observable.md @@ -0,0 +1,115 @@ +--- +title: "delegate_observable" +--- + +{{< callout type="info">}} + Header: `delegate_observable.h` + Supported: `TBC` +{{< /callout >}} + +`etl::delegate_observable` is a variation on the observer pattern idea, but using delegates as the callback mechanism. + +```cpp +template +class delegate_observable +``` + +`TNotification` is the notification type. +`Max_Observers` is the maximum number of observers that can be handled. + +## Template deduction guide + +```cpp +template +delegate_observable(TNotification, TDelegates...) + -> delegate_observable; +``` + +**Example** +```cpp +etl::delegate delegate1; +etl::delegate delegate2; + +etl::delegate_observable observable(int{}, delegate1, delegate2); +``` + +## Public types + +| Type | Description | +| ------------------- | ------------------------------------------- | +| `delegate_type` | The type of delegate used in this observer. | +| `size_type` | The type used internally for sizes. | +| `notification_type` | The type of the notification. | + +## Construction + +```cpp +ETL_CONSTEXPR14 delegate_observable() +``` +**Description** +Default constructor. + +--- + +```cpp +template +ETL_CONSTEXPR14 delegate_observable(TDelegate&&... delegates) +``` +**Description** +Construct from a collection of observers. + +--- + +```cpp +template +ETL_CONSTEXPR14 delegate_observable(notification_type, TDelegate&&... delegates) +``` +**Description** +Construct from notification type and a list of observers. +Variant for template deduction guide. +The notification value is ignored. It is here to allow deduction of the notification type for the template deduction guide. + +## Modifiers + +```cpp +ETL_CONSTEXPR14 bool add_observer(delegate_type observer) +``` +**Description** +Add an observer to the list. + +**Return** +`true` if the observer was removed, `false` if not. + +--- + +```cpp +ETL_CONSTEXPR14 bool remove_observer(const delegate_type& observer) +``` +**Description** +Remove a particular observer from the list. +**Return** +`true if the observer was removed, false if not. + +--- + +```cpp +ETL_CONSTEXPR14 void clear_observers() +``` +**Description** +Clear all observers. + +## Status + +```cpp +ETL_CONSTEXPR14 size_type number_of_observers() const +``` +**Return** +The number of observers. + +## Notofication + +```cpp +ETL_CONSTEXPR14 void notify_observers(notification_type n) const +``` +**Description** +Notify all of the observers, sending them the notification. diff --git a/docs/callbacks/function.md b/docs/callbacks/function.md new file mode 100644 index 00000000..e9b37849 --- /dev/null +++ b/docs/callbacks/function.md @@ -0,0 +1,332 @@ +--- +title: "function" +--- + +{{< callout type="warning">}} + Deprecated: Please use the more versatile `etl::delegate` or `etl::inplace_function` classes instead. +{{< /callout >}} + +{{< callout type="info">}} + Header: `function.h` + Supported: `TBC` +{{< /callout >}} + +A set of wrapper templates to allow a member or static function to be called without the caller having to know the specific details of the callee apart from the parameter type. The templates allow the called function to be abstracted. + +This may be used to implement a platform abstraction layer that allows an embedded application to interface with multiple hardware platforms. + +| Template | Description | +| ----------------- | ------------------------------------------------------------------------- | +| etl::function | Callbacks to free or member functions taking zero or one parameter.
Function pointer at runtime. | +| etl::function_fv | Callback to a free function taking no parameters. (Functiion Void).
Function pointer at compile time. | +| etl::function_fp | Callback to a free function taking one parameter. (Function Parameter).
Function pointer at compile time. +| etl::function_mv | Callback to a member function taking no parameters. (Member Void).
Function pointer at compile time. | +| etl::function_imv | Callback to a member function taking no parameters. (Instance Member Void ).
Instance reference and function pointer at compile time. | +| etl::function_mp | Callback to a member function taking one parameter. (Member Parameter).
Function pointer at compile time.| +| etl::function_imp | Callback to a member function taking one parameter. (Instance Member Parameter).
Instance reference and function pointer at compile time.| + +*Instances of any of these types may be passed as pointers or references to etl::ifunction.* + +## Interface classes. + +```cpp +template +class ifunction +``` +**Description** +Interface class for a function taking one parameter. + +--- + +```cpp +template <> +class ifunction +``` +**Description** +Interface class for a function taking no parameters. + +**All of the following classes are derived from the above interface classes.** + +## Function address at run time. +The functions are called indirectly through an internal pointer. + +```cpp +template +class function : public ifunction +``` +**Description** +Class for a member function taking one parameter. + +--- + +```cpp +template +class function : public ifunction +``` +**Description** +Class for a member function taking no parameters. + +```cpp +template +class function : public ifunction +``` +**Description** +Class for a free function taking one parameter. + +--- + +```cpp +template <> +class function : public ifunction +``` +**Description** +Class for a free function taking no parameters. + +## Function address at compile time. +These will be more efficient than the previous definitions, as the one level of indirection is eliminated. + +```cpp +template +class function_mv : public ifunction +``` +**Description** +Class for a member function taking no parameters. + +--- + +```cpp +template +class function_imv : public ifunction +``` +**Description** +Class for a member function taking no parameters. + +--- + +```cpp +template +class function_mp : public ifunction +``` +**Description** +Class for a member function taking one parameter. + +--- + +```cpp +template +class function_imp : public ifunction +``` +**Description** +Class for a member function taking one parameter. + +--- + +```cpp +template +class function_fv : public ifunction +``` +**Description** +Class for a free function taking no parameters. + +--- + +```cpp +template +class function_fp : public ifunction +``` +**Description** +Class for a free function taking one parameter. + +## Example + +```cpp +etl::function +``` + +These templates are designed to enable easy creation of callbacks to global, static and class member functions without the caller having to know which type actually it is. + +One use that is applicable to embedded platforms is to use them connect interrupt vectors to class member handling functions. Particularly useful when the code is applicable to multiple targets devices. + +The template is designed in such a way that the caller does not need to be aware of the type of the callee. + +The caller declares an instance of `etl::function` or one of its variants. The caller defines a pointer or reference to an `etl::ifunction`. This pointer or reference will be initialised with the instance defined in the caller. + +**Example** + +The interrupt vector table contains entries for three timer timeouts and two uart character rx handlers. These are vectored to normal static functions. + +```cpp +void Timer1TimeoutInterrupt(); +void Timer2TimeoutInterrupt(); +void Timer3TimeoutInterrupt(); +void Uart1RxInterrupt(); +void Uart2RxInterrupt(); +``` + +The timer timeout interrupts are handled by an instance of the class `Timer` and the free function `FreeTimerInterruptHandler`. The UART Rx interrupts are handled by instances of the class `Uart`. + +`Timer1` interrupts call the member function of an instance of `Timer`. +`Timer2` interrupts call the static member function of `Timer`. +`Timer3` interrupts call the free function `FreeTimerInterruptHandler`. +`UART1` interrupts call the member function of instance 1 of `Uart`. +`UART1` interrupts call the member function of instance 2 of `Uart`. + +```cpp +#include +#include + +#include "function.h" + +//******************************** +// Fake UART Rx register. +//******************************** +char get_char() +{ + static char c = 'A'; + return c++; +} + +//******************************** +// Interrupt vectors & callbacks. +//******************************** +// Callback interfaces. +// Note that they do not require any knowledge about the callee apart from the parameter type. +etl::ifunction* timer1_callback; // A pointer to a callback taking no parameters. +etl::ifunction* timer2_callback; // A pointer to a callback taking no parameters. +etl::ifunction* timer3_callback; // A pointer to a callback taking no parameters. +etl::ifunction* uart1_rx_callback; // A pointer to a callback taking a char parameter. +etl::ifunction* uart2_rx_callback; // A pointer to a callback taking a char parameter. + +extern "C" +{ +// Function called from the timer1 interrupt vector. +void Timer1Interrupt() +{ + (*timer1_callback)(); +} + +// Function called from the timer2 interrupt vector. +void Timer2Interrupt() +{ + (*timer2_callback)(); +} + +// Function called from the timer3 interrupt vector. +void Timer3Interrupt() +{ + (*timer3_callback)(); +} + +// Function called from the UART1 rx interrupt vector. +void Uart1RxInterrupt() +{ + (*uart1_rx_callback)(get_char()); +} + +// Function called from the UART2 rx interrupt vector. +void Uart2RxInterrupt() +{ + (*uart2_rx_callback)(get_char()); +} +} + +//******************************** +// Timer driver. +//******************************** +class Timer +{ +public: + + // Constructor. + Timer() + { + } + + // Handler for interrupts from the timer. + void MemberTimerInterruptHandler() + { + std::cout << "Timer interrupt (member)\n"; + } + + // Static handler for interrupts from the timer. + static void StaticTimerInterruptHandler() + { + std::cout << "Timer interrupt (static)\n"; + } +}; + +//******************************** +// Free function timer driver. +//******************************** +void FreeTimerInterruptHandler() +{ + std::cout << "Timer interrupt (free)\n"; +} + +etl::function_fv free_callback; + +//******************************** +// UART driver. +//******************************** +class Uart +{ +public: + + // Constructor. + Uart(int port_id) + : port_id(port_id) + { + } + + // Handler for rx interrupts from the UART. + void RxInterruptHandler(char c) + { + std::cout << "UART" << port_id << " Rx char interrupt : Received '" << c << "'\n"; + } + + int port_id; +}; + +// Declare the driver instances. +Timer timer; +Uart uart1(0); +Uart uart2(1); + +etl::function_imv timer_member_callback; +etl::function_fv<&Timer::StaticTimerInterruptHandler> timer_static_callback; +etl::function_imp uart1_callback; +etl::function_imp uart2_callback; + +//******************************** +// Test it out. +//******************************** +int main() +{ + + // Setup the callbacks. + timer1_callback = &timer_member_callback; + timer2_callback = &timer_static_callback; + timer3_callback = &free_callback; + uart1_rx_callback = &uart1_callback; + uart2_rx_callback = &uart2_callback; + + // Simulate the interrupts. + Timer1Interrupt(); + Timer2Interrupt(); + Timer3Interrupt(); + Uart1RxInterrupt(); + Uart2RxInterrupt(); + + return 0; +} +``` diff --git a/docs/codecs/base64.md b/docs/codecs/base64.md new file mode 100644 index 00000000..0da2d4d1 --- /dev/null +++ b/docs/codecs/base64.md @@ -0,0 +1,313 @@ +--- +title: "Base64" +--- + +{{< callout type="info">}} + Headers: + `base64.h` Common definitions + `base64_encoder.h` Encoder class + `base64_decoder.h` Decoder class + Supported: `20.38.4` +{{< /callout >}} + +Encodes and decodes data to and from Base64 format. + +## Encode + +**Input -> pointer/length : Output -> pointer/length** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const T* input, size_t input_length, + char* output, size_t output_length) +``` +**Description** +Transforms the input data described by input and input_length to Base64 format to be stored in output output_length. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. + +**Return** +The length of the encoded data. + +**Error** +If output_length is not large enough to hold the encoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> pointer/length : Output -> string** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const T* input, size_t input_length, + etl::istring& output) +``` +**Description** +Transforms the input data described by input and input_length to Base64 format to be stored in output. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. +The output string must have capacity of at least `etl::base64::encode_size(input)`. + +**Return** +The length of the encoded data. + +**Error** +If output_length is not large enough to hold the encoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> pointer/pointer : Output -> pointer/pointer** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const T* input_begin, const T* input_end, + char* output_begin, char* output_end) +``` +**Description** +Transforms the input data described by input_begin and input_end to Base64 format to be stored in output_begin to output_end. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. + +**Return** +The length of the encoded data. + +**Error** +If the output buffer is not large enough to hold the encoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> pointer/pointer : Output -> string** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const T* input_begin, const T* input_end, + etl::istring& output) +``` +**Description** +Transforms the input data described by input_begin and input_end to Base64 format to be stored in output. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. +The output string must have capacity of at least `etl::base64::encode_size(input)`. + +**Return** +The length of the encoded data. + +**Error** +If the output buffer is not large enough to hold the encoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> span : Output -> span** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const etl::span& input_span, + const etl::span& output_span) +``` +**Description** +Transforms the input data described by input_span to Base64 format to be stored in output_span. +Enabled if etl::is_integral is true and etl::integral_limits::bits == 8. + +**Return** +The length of the encoded data. + +**Error** +If the output span is not large enough to hold the encoded data then an etl::base64_overflow is raised. + +--- + +**Input -> span : Output -> string** +```cpp +template +ETL_CONSTEXPR14 +static +size_t encode(const etl::span& input_span, + etl::istring& output) +``` +**Description** +Transforms the input data described by input_span to Base64 format to be stored in output. +Enabled if etl::is_integral is true and etl::integral_limits::bits == 8 +The output string must have capacity of at least etl::base64::encode_size(input). + +**Return** +The length of the encoded data. + +**Error** +If the output span is not large enough to hold the encoded data then an etl::base64_overflow is raised. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +static +size_t encode_size(size_t input_length) +``` +**Return** +Returns the size of the output buffer required to encode the specified input data length. + +## Decode + +**Input -> pointer/length : Output -> pointer/length** +```cpp +template +ETL_CONSTEXPR14 +static +size_t decode(const char* input, size_t input_length, + T* output, size_t output_length) +``` +**Description** +Transforms the Base64 format input data described by input and input_length to by output and output_length. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. + +**Return** +The length of the decoded data. + +**Error** +If `output_length` is not large enough to hold the decoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> pointer/pointer: Output -> pointer/pointer** +```cpp +template +ETL_CONSTEXPR14 +static +size_t decode(const char* input_begin, const char* input_end, + T* output_begin, T* output_end) +``` +**Description*** +Transforms the Base64 format input data described by `input_begin` and `input_end` to `output_begin` and `output_end`. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. + +**Return** +The length of the decoded data. + +**Error** +If the output buffer is not large enough to hold the decoded data then an `etl::base64_overflow` is raised. + +--- + +**Input -> span: Output -> span** +```cpp +template +ETL_CONSTEXPR14 +static +size_t decode(const etl::span& input_span, + const etl::span& output_span) +``` +**Description** +Transforms the Base64 format input data described by input_span to output_span. +Enabled if `etl::is_integral` is `true` and `etl::integral_limits::bits == 8`. + +**Return** +The length of the decoded data. + +**Error** +If the output span is not large enough to hold the decoded data then an `etl::base64_overflow` is raised. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +static +size_t decode_size(const char* input, size_t input_length) +``` +**Return** +The size of the output buffer required to decode the specified input Base64 data length. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +static +size_t decode_size(const char* input_begin, const char* input_end) +``` +**Return** +The size of the output buffer required to decode the specified input Base64 data length. + +--- + +```cpp +ETL_NODISCARD +ETL_CONSTEXPR14 +static +size_t decode_size(etl::span input) +``` +**Return** +The size of the output buffer required to decode the specified input Base64 data length. + +## Examples + +### Encode +```cpp +const etl::array input = +{ + 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, + 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21 // "Hello World!" +}; + +etl::string<20> encoded; + +size_t encoded_size = etl::base64::encode(input.data(), input.size(), + encoded.data(), encoded.size()); + +encoded.resize(encoded_size); +// encoded == "OycDQy37KCphrg==" +``` + +--- + +*For C++14 or above* +```cpp +const etl::array input = +{ + 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, + 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21 // "Hello World!" +}; + +constexpr size_t length = etl::base64::encode_size(input.size()); +etl::string output; +output.uninitialized_resize(output.capacity()); + +etl::base64::encode(input.data(), input.size(), output.data(), output.size()); +// output == "OycDQy37KCphrg==" +``` + +--- + +### Decode +```cpp +const etl::string<16> encoded = "OycDQy37KCphrg=="; + +etl::vector output; + +size_t decoded_size = etl::base64::decode(encoded.data(), encoded.size(), + output.data(), output.size()); + +output.resize(decoded_size); +// output == { 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, +// 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21 }; +``` + +--- + +*For C++14 or above* +```cpp +// "OycDQy37KCphrg==" +constexpr const etl::array input = +{ + 0x4F, 0x79, 0x63, 0x44, 0x51, 0x79, 0x33, 0x37, + 0x4B, 0x43, 0x70, 0x68, 0x72, 0x67, 0x3D, 0x3D +}; + +constexpr size_t length = etl::base64::decode_size(input.data(), input.size()); +etl::vector output; + +etl::base64::decode(input.data(), input.size(), output.data(), output.size()); +// output == { 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, +// 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21 }; +``` + diff --git a/docs/raw/callbacks/delegate_observable.txt b/docs/raw/callbacks/delegate_observable.txt deleted file mode 100644 index 5e40ea56..00000000 --- a/docs/raw/callbacks/delegate_observable.txt +++ /dev/null @@ -1,79 +0,0 @@ -delegate_observable - -etl::delegate_observable is a variation on the observer pattern idea, but using delegates as the callback mechanism. - -template -class delegate_observable - -TNotification is the notification type. -Max_Observers is the maximum number of observers that can be handled. -____________________________________________________________________________________________________ -Template deduction guide - -template -delegate_observable(TNotification, TDelegates...) - -> delegate_observable; - -Example -etl::delegate delegate1; -etl::delegate delegate2; - -etl::delegate_observable observable(int{}, delegate1, delegate2); -____________________________________________________________________________________________________ -Public types - -delegate_type The type of delegate used in this observer. -size_type The type used internally for sizes. -notification_type The type of the notification. -____________________________________________________________________________________________________ -Construction - -ETL_CONSTEXPR14 delegate_observable() -Default constructor. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 delegate_observable(TDelegate&&... delegates) -Construct from a collection of observers. -____________________________________________________________________________________________________ -template -ETL_CONSTEXPR14 delegate_observable(notification_type, TDelegate&&... delegates) -Construct from notification type and a list of observers. -Variant for template deduction guide. -The notification value is ignored. It is here to allow deduction of the notification type for the template deduction guide. -____________________________________________________________________________________________________ -Modifiers - -ETL_CONSTEXPR14 bool add_observer(delegate_type observer) -Add an observer to the list. -Returns true if the observer was removed, false if not. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 bool remove_observer(const delegate_type& observer) -Remove a particular observer from the list. -Returns true if the observer was removed, false if not. -____________________________________________________________________________________________________ -ETL_CONSTEXPR14 void clear_observers() -Clear all observers. -____________________________________________________________________________________________________ -Status - -ETL_CONSTEXPR14 size_type number_of_observers() const -Returns the number of observers. -____________________________________________________________________________________________________ -Notofication - -ETL_CONSTEXPR14 void notify_observers(notification_type n) const -Notify all of the observers, sending them the notification. - - - - - - - - - - - - - - diff --git a/docs/raw/callbacks/function.txt b/docs/raw/callbacks/function.txt deleted file mode 100644 index d4daa9e8..00000000 --- a/docs/raw/callbacks/function.txt +++ /dev/null @@ -1,104 +0,0 @@ -function -Note: This class is deprecated. Please use the more versatile etl::delegate class here. - -A set of wrapper templates to allow a member or static function to be called without the caller having to know the specific details of the callee apart from the parameter type. The templates allow the called function to be abstracted. - -This may be used to implement a platform abstraction layer that allows an embedded application to interface with multiple hardware platforms. - -etl::function Callbacks to free or member functions taking zero or one parameter. - Function pointer at runtime. - -etl::function_fv Callback to a free function taking no parameters. (Functiion Void) - Function pointer at compile time. - -etl::function_fp Callback to a free function taking one parameter. (Functiion Parameter) - Function pointer at compile time. - -etl::function_mv Callback to a member function taking no parameters. (Member Void) - Function pointer at compile time. - -etl::function_imv Callback to a member function taking no parameters. (Instance Member Void) - Instance reference and function pointer at compile time. - -etl::function_mp Callback to a member function taking one parameter. (Member Parameter) - Function pointer at compile time. - -etl::function_imp Callback to a member function taking one parameter. (Instance Member Parameter) - Instance reference and function pointer at compile time. - -See the tutorial. - -____________________________________________________________________________________________________ -Interface classes. - -template -class ifunction - -Interface class for a function taking one parameter. -____________________________________________________________________________________________________ -template <> -class ifunction - -Interface class for a function taking no parameters. - -All of the following classes are derived from the above. - -____________________________________________________________________________________________________ -Function address at run time. -The functions are called indirectly through an internal pointer. - -template -class function : public ifunction - -Class for a member function taking one parameter. -____________________________________________________________________________________________________ -template -class function : public ifunction - -Class for a member function taking no parameters. -____________________________________________________________________________________________________ -template -class function : public ifunction - -Class for a free function taking one parameter. -____________________________________________________________________________________________________ -template <> -class function : public ifunction - -Class for a free function taking no parameters. - -____________________________________________________________________________________________________ -Function address at compile time. -These will be more efficient than the previous definitions, as the one level of indirection is eliminated. - -template -class function_mv : public ifunction - -Class for a member function taking no parameters. -____________________________________________________________________________________________________ - -template -class function_imv : public ifunction - -Class for a member function taking no parameters. -____________________________________________________________________________________________________ -template -class function_mp : public ifunction - -Class for a member function taking one parameter. -____________________________________________________________________________________________________ -template -class function_imp : public ifunction - -Class for a member function taking one parameter. -____________________________________________________________________________________________________ -template -class function_fv : public ifunction - -Class for a free function taking no parameters. -____________________________________________________________________________________________________ -template -class function_fp : public ifunction - -Class for a free function taking one parameter. - diff --git a/docs/raw/codecs/Base64.txt b/docs/raw/codecs/Base64.txt index 2757e042..a7ab22ed 100644 --- a/docs/raw/codecs/Base64.txt +++ b/docs/raw/codecs/Base64.txt @@ -1,7 +1,15 @@ -Base64 +--- +title: "Base64" +--- + +{{< callout type="info">}} + Header: `base64.h` + `base64_encoder.h` + `base64_decoder.h + Supported: `20.38.4` +{{< /callout >}} + Encodes and decodes data to and from Base64 format. -etl::base64 -20.38.4 ____________________________________________________________________________________________________ Encode diff --git a/docs/raw/tutorials/function_tutorial.txt b/docs/raw/tutorials/function_tutorial.txt deleted file mode 100644 index 2c85f683..00000000 --- a/docs/raw/tutorials/function_tutorial.txt +++ /dev/null @@ -1,208 +0,0 @@ -etl::function - -Note: This class is deprecated. Please use the more versatile etl::delegate class here. - -These templates are designed to enable easy creation of callbacks to global, static and class member functions without the caller having to know which type actually it is. - -etl::function -Callback to free or member functions taking zero or one parameter. -Function pointer at runtime. - -etl::function_fv -Callback to a free function taking no parameters. -Function pointer at compile time. - -etl::function_fp -Callback to a free function taking one parameter. -Function pointer at compile time. - -etl::function_mv -Callback to a member function taking no parameters. -Function pointer at compile time. - -etl::function_imv -Callback to a member function taking no parameters. - Instance reference and function pointer at compile time. - -etl::function_mp -Callback to a member function taking one parameter. -Function pointer at compile time. - -etl::function_imp -Callback to a member function taking one parameter. -Instance reference and function pointer at compile time. - -Instances of any of these types may be passed as pointers or references to etl::ifunction. - -One use that is applicable to embedded platforms is to use them connect interrupt vectors to class member handling functions. Particularly useful when the code is applicable to multiple targets devices. - -The template is designed in such a way that the caller does not need to be aware of the type of the callee. - -The caller declares an instance of etl::function or one of its variants. The caller defines a pointer or reference to an etl::ifunction. This pointer or reference will be initialised with the instance defined in the caller. - -Example - -The interrupt vector table contains entries for three timer timeouts and two uart character rx handlers. These are vectored to normal static functions. - -void Timer1TimeoutInterrupt(); -void Timer2TimeoutInterrupt(); -void Timer3TimeoutInterrupt(); -void Uart1RxInterrupt(); -void Uart2RxInterrupt(); - -The timer timeout interrupts are handled by an instance of the class Timer and the free function FreeTimerInterruptHandler. The UART Rx interrupts are handled by instances of the class Uart. - -Timer1 interrupts call the member function of an instance of Timer. -Timer2 interrupts call the static member function of Timer. -Timer3 interrupts call the free function FreeTimerInterruptHandler. -UART1 interrupts call the member function of instance 1 of Uart. -UART1 interrupts call the member function of instance 2 of Uart. - -#include -#include - -#include "function.h" - -//******************************** -// Fake UART Rx register. -//******************************** -char get_char() -{ - static char c = 'A'; - return c++; -} - -//******************************** -// Interrupt vectors & callbacks. -//******************************** -// Callback interfaces. -// Note that they do not require any knowledge about the callee apart from the parameter type. -etl::ifunction* timer1_callback; // A pointer to a callback taking no parameters. -etl::ifunction* timer2_callback; // A pointer to a callback taking no parameters. -etl::ifunction* timer3_callback; // A pointer to a callback taking no parameters. -etl::ifunction* uart1_rx_callback; // A pointer to a callback taking a char parameter. -etl::ifunction* uart2_rx_callback; // A pointer to a callback taking a char parameter. - -extern "C" -{ -// Function called from the timer1 interrupt vector. -void Timer1Interrupt() -{ - (*timer1_callback)(); -} - -// Function called from the timer2 interrupt vector. -void Timer2Interrupt() -{ - (*timer2_callback)(); -} - -// Function called from the timer3 interrupt vector. -void Timer3Interrupt() -{ - (*timer3_callback)(); -} - -// Function called from the UART1 rx interrupt vector. -void Uart1RxInterrupt() -{ - (*uart1_rx_callback)(get_char()); -} - -// Function called from the UART2 rx interrupt vector. -void Uart2RxInterrupt() -{ - (*uart2_rx_callback)(get_char()); -} -} - -//******************************** -// Timer driver. -//******************************** -class Timer -{ -public: - - // Constructor. - Timer() - { - } - - // Handler for interrupts from the timer. - void MemberTimerInterruptHandler() - { - std::cout << "Timer interrupt (member)\n"; - } - - // Static handler for interrupts from the timer. - static void StaticTimerInterruptHandler() - { - std::cout << "Timer interrupt (static)\n"; - } -}; - -//******************************** -// Free function timer driver. -//******************************** -void FreeTimerInterruptHandler() -{ - std::cout << "Timer interrupt (free)\n"; -} - -etl::function_fv free_callback; - -//******************************** -// UART driver. -//******************************** -class Uart -{ -public: - - // Constructor. - Uart(int port_id) - : port_id(port_id) - { - } - - // Handler for rx interrupts from the UART. - void RxInterruptHandler(char c) - { - std::cout << "UART" << port_id << " Rx char interrupt : Received '" << c << "'\n"; - } - - int port_id; -}; - -// Declare the driver instances. -Timer timer; -Uart uart1(0); -Uart uart2(1); - -etl::function_imv timer_member_callback; -etl::function_fv<&Timer::StaticTimerInterruptHandler> timer_static_callback; -etl::function_imp uart1_callback; -etl::function_imp uart2_callback; - -//******************************** -// Test it out. -//******************************** -int main() -{ - - // Setup the callbacks. - timer1_callback = &timer_member_callback; - timer2_callback = &timer_static_callback; - timer3_callback = &free_callback; - uart1_rx_callback = &uart1_callback; - uart2_rx_callback = &uart2_callback; - - // Simulate the interrupts. - Timer1Interrupt(); - Timer2Interrupt(); - Timer3Interrupt(); - Uart1RxInterrupt(); - Uart2RxInterrupt(); - - return 0; -} -