RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-01-18 12:52:44 +01:00
Code Releases Activity

Merge pull request #18315 from miri64/fmt/doc/wording

Browse Source 
fmt: unify and align wording regarding characters, digits, and bytes
This commit is contained in:
Kaspar Schleiser 2022-09-01 21:46:22 +02:00 committed by GitHub
commit fcf3e01eb7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
sys/include/fmt.h
View File

@ -22,7 +22,7 @@
* This *MUST* be ensured by the caller.
*
* @note Each fmt function will not write anything to `out` if it is `NULL`, but
* still return the number of bytes that would have been written.
* still return the number of characters that would have been written.
* This can be used to ensure the `out` buffer is large enough.
*
* @note The print functions in this library do not buffer any output.
@ -81,7 +81,7 @@ static inline int fmt_is_upper(char c)
*
* @param[in] str String to test, **must be `\0` terminated**
*
* @return true if @p str solely contains digits, false otherwise
* @return true if @p str solely contains decimal digits, false otherwise
*/
int fmt_is_number(const char *str);
@ -90,8 +90,8 @@ int fmt_is_number(const char *str);
*
* E.g., converts byte value 0 to the string 00, 255 to the string FF.
*
* Will write two bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write two characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -102,10 +102,10 @@ int fmt_is_number(const char *str);
size_t fmt_byte_hex(char *out, uint8_t byte);
/**
* @brief Formats a sequence of bytes as hex bytes
* @brief Formats a sequence of bytes as hex characters
*
* Will write 2*n bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write 2*n characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -117,10 +117,10 @@ size_t fmt_byte_hex(char *out, uint8_t byte);
size_t fmt_bytes_hex(char *out, const uint8_t *ptr, size_t n);
/**
* @brief Formats a sequence of bytes as hex bytes, starting with the last byte
* @brief Formats a sequence of bytes as hex characters, starting with the last byte
*
* Will write 2*n bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write 2*n characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -143,7 +143,7 @@ size_t fmt_bytes_hex_reverse(char *out, const uint8_t *ptr, size_t n);
uint8_t fmt_hex_byte(const char *hex);
/**
* @brief Converts a sequence of hex bytes to an array of bytes
* @brief Converts a sequence of hex characters to an array of bytes
*
* The sequence of hex characters must have an even length:
* 2 hex character => 1 byte. If the sequence of hex has an odd length, this
@ -162,8 +162,8 @@ size_t fmt_hex_bytes(uint8_t *out, const char *hex);
/**
* @brief Convert a uint16 value to hex string.
*
* Will write 4 bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write 4 characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -176,8 +176,8 @@ size_t fmt_u16_hex(char *out, uint16_t val);
/**
* @brief Convert a uint32 value to hex string.
*
* Will write 8 bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write 8 characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -190,8 +190,8 @@ size_t fmt_u32_hex(char *out, uint32_t val);
/**
* @brief Convert a uint64 value to hex string.
*
* Will write 16 bytes to @p out.
* If @p out is NULL, will only return the number of bytes that would have
* Will write 16 characters to @p out.
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -204,20 +204,20 @@ size_t fmt_u64_hex(char *out, uint64_t val);
/**
* @brief Convert a uint32 value to decimal string.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
* @param[in] val Value to convert
*
* @return nr of digits written to (or needed in) @p out
* @return nr of characters written to (or needed in) @p out
*/
size_t fmt_u32_dec(char *out, uint32_t val);
/**
* @brief Convert a uint64 value to decimal string.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @note This adds ~400b of code when used.
@ -225,20 +225,20 @@ size_t fmt_u32_dec(char *out, uint32_t val);
* @param[out] out Pointer to output buffer, or NULL
* @param[in] val Value to convert
*
* @return nr of digits written to (or needed in) @p out
* @return nr of characters written to (or needed in) @p out
*/
size_t fmt_u64_dec(char *out, uint64_t val);
/**
* @brief Convert a uint16 value to decimal string.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
* @param[in] val Value to convert
*
* @return nr of digits written to (or needed in) @p out
* @return nr of characters written to (or needed in) @p out
*/
size_t fmt_u16_dec(char *out, uint16_t val);
@ -247,7 +247,7 @@ size_t fmt_u16_dec(char *out, uint16_t val);
*
* Will add a leading "-" if @p val is negative.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -262,7 +262,7 @@ size_t fmt_s64_dec(char *out, int64_t val);
*
* Will add a leading "-" if @p val is negative.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -277,7 +277,7 @@ size_t fmt_s32_dec(char *out, int32_t val);
*
* Will add a leading "-" if @p val is negative.
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -324,7 +324,7 @@ size_t fmt_s32_dfp(char *out, int32_t val, int scale);
*
* Converts float value @p f to string
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @attention This function is using floating point math.
@ -337,20 +337,20 @@ size_t fmt_s32_dfp(char *out, int32_t val, int scale);
* @param[in] f float value to convert
* @param[in] precision number of digits after decimal point
*
* @returns nr of bytes the function did or would write to out
* @returns nr of characters the function did or would write to out
*/
size_t fmt_float(char *out, float f, unsigned precision);
/**
* @brief Copy @p in char to string (without terminating '\0')
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out string to write to (or NULL)
* @param[in] c char value to append
*
* @return nr of bytes the function did or would write to out
* @return nr of characters the function did or would write to out
*/
size_t fmt_char(char *out, char c);
@ -377,7 +377,7 @@ size_t fmt_strnlen(const char *str, size_t maxlen);
/**
* @brief Copy null-terminated string (excluding terminating \0)
*
* If @p out is NULL, will only return the number of bytes that would have
* If @p out is NULL, will only return the number of characters that would have
* been written.
*
* @param[out] out Pointer to output buffer, or NULL
@ -396,7 +396,7 @@ size_t fmt_str(char *out, const char *str);
size_t fmt_to_lower(char *out, const char *str);
/**
* @brief Convert digits to uint32
* @brief Convert string of decimal digits to uint32
*
* Will convert up to @p n digits. Stops at any non-digit or '\0' character.
*
@ -408,9 +408,9 @@ size_t fmt_to_lower(char *out, const char *str);
uint32_t scn_u32_dec(const char *str, size_t n);
/**
* @brief Convert hexadecimal characters to uin32_t
* @brief Convert string hexadecimal digits to uin32_t
*
* Will convert up to @p n char. Stop at any non-hexadecimal or '\0' character
* Will convert up to @p n digits. Stop at any non-hexadecimal or '\0' character
*
* @param[in] str Pointer to string to read from
* @param[in] n Maximum number of characters to consider
@ -422,10 +422,10 @@ uint32_t scn_u32_hex(const char *str, size_t n);
/**
* @brief Print string to stdout
*
* Writes @p n bytes from @p s to STDOUT_FILENO.
* Writes @p n characters from @p s to STDOUT_FILENO.
*
* @param[out] s Pointer to string to print
* @param[in] n Number of bytes to print
* @param[in] n Number of characters to print
*/
void print(const char* s, size_t n);