mirror of https://github.com/MLXXXp/Arduboy2.git
Add a template overload of 'readUnitName'
This template function is provided as a convinience to help users to avoid potential buffer overrun errors at compile time. It performs a `static_assert` to check if the provided `char` array is large enough to receive the unit name. There should be no additional cost as the template simply calls the other `readUnitName` overload (and thus should always be inlined).
This commit is contained in:
parent
3f9e86ab99
commit
fe9efee4e3
|
@ -1108,6 +1108,49 @@ class Arduboy2Base : public Arduboy2Core
|
||||||
*/
|
*/
|
||||||
void writeUnitID(uint16_t id);
|
void writeUnitID(uint16_t id);
|
||||||
|
|
||||||
|
/** \brief
|
||||||
|
* Read the unit name from system EEPROM.
|
||||||
|
*
|
||||||
|
* \param name A char array variable where the unit name will be placed.
|
||||||
|
* The array will be up to 6 characters and terminated with a
|
||||||
|
* null (0x00) character, so the provided array must be at least 7 bytes long.
|
||||||
|
* This template enforces the size restriction with a `static_assert`.
|
||||||
|
*
|
||||||
|
* \return The length of the string (0-6).
|
||||||
|
*
|
||||||
|
* \details
|
||||||
|
* This function reads the unit name that has been set in system EEPROM. The
|
||||||
|
* name is in ASCII and can contain any values except 0xFF and the
|
||||||
|
* null (0x00) terminator value.
|
||||||
|
*
|
||||||
|
* The name can be used for any purpose. It could identify the owner or
|
||||||
|
* give the unit itself a nickname. A sketch could use it to automatically
|
||||||
|
* fill in a name or initials in a high score table, or display it as the
|
||||||
|
* "player" when the opponent is the computer.
|
||||||
|
*
|
||||||
|
* \note
|
||||||
|
* Sketches can use the defined value `ARDUBOY_UNIT_NAME_LEN` instead of
|
||||||
|
* hard coding a 6 when working with the unit name. For example, to allocate
|
||||||
|
* a buffer and read the unit name into it:
|
||||||
|
* \code{.cpp}
|
||||||
|
* // Buffer for maximum name length plus the terminator
|
||||||
|
* char unitName[ARDUBOY_UNIT_NAME_LEN + 1];
|
||||||
|
*
|
||||||
|
* // The actual name length
|
||||||
|
* byte unitNameLength;
|
||||||
|
*
|
||||||
|
* unitNameLength = arduboy.readUnitName(unitName);
|
||||||
|
* \endcode
|
||||||
|
*
|
||||||
|
* \see readUnitName() writeUnitName() readUnitID() Arduboy2::bootLogoExtra()
|
||||||
|
*/
|
||||||
|
template<size_t size>
|
||||||
|
uint8_t readUnitName(char (&name)[size])
|
||||||
|
{
|
||||||
|
static_assert(size >= (ARDUBOY_UNIT_NAME_LEN + 1), "Provided array is not large enough to hold a unit name");
|
||||||
|
return readUnitName(&name[0]);
|
||||||
|
}
|
||||||
|
|
||||||
/** \brief
|
/** \brief
|
||||||
* Read the unit name from system EEPROM.
|
* Read the unit name from system EEPROM.
|
||||||
*
|
*
|
||||||
|
|
Loading…
Reference in New Issue