Skip to content

ssfhex.md

Latest commit

 

History

History
243 lines (170 loc) · 8.86 KB

ssfhex.md

File metadata and controls

243 lines (170 loc) · 8.86 KB

ssfhex — Binary-to-Hex ASCII Encoder/Decoder

SSF | Codecs

Encodes binary bytes to hexadecimal ASCII strings and decodes them back, with optional byte-order reversal for little-endian multi-byte values.

Dependencies | Notes | Configuration | API Summary | Function Reference

↑ Dependencies

↑ Notes

↑ Configuration

This module has no compile-time configuration options in ssfoptions.h.

↑ API Summary

Definitions

Symbol Kind Description
SSFHexCase_t Enum Output digit case: SSF_HEX_CASE_LOWER emits a–f; SSF_HEX_CASE_UPPER emits A–F

Functions

Function / Macro Description
e.g. bool SSFHexBinToByte(in, out, outSize, hcase) Encode one byte to a 2-character hex string
e.g. bool SSFHexByteToBin(hex, out) Decode 2 hex characters to one byte
e.g. bool SSFHexBytesToBin(in, inLenLim, out, outSize, outLen, rev) Decode hex ASCII string to binary
e.g. bool SSFHexBinToBytes(in, inLen, out, outSize, outLen, rev, hcase) Encode binary to hex ASCII string
e.g. bool SSFIsHex(h) Macro: true if h is a valid hex digit

↑ Function Reference

↑ bool SSFHexBinToByte()

bool SSFHexBinToByte(uint8_t in, char *out, size_t outSize, SSFHexCase_t hcase);

Converts one binary byte to a 2-character hexadecimal string. If outSize >= 3, also writes a null terminator; with outSize == 2 the output is not null-terminated.

Parameter Direction Type Description
in in uint8_t Binary byte to convert (0–255).
out out char * Output buffer. Must not be NULL. Pass outSize >= 3 for a null-terminated result.
outSize in size_t Allocated size of out in bytes. Must be at least 2.
hcase in SSFHexCase_t SSF_HEX_CASE_LOWER for a–f; SSF_HEX_CASE_UPPER for A–F.

Returns: true if conversion succeeded; false if outSize < 2.

char out[3];

if (SSFHexBinToByte(0xA5u, out, sizeof(out), SSF_HEX_CASE_UPPER))
{
    /* out == "A5" */
}

↑ bool SSFHexByteToBin()

bool SSFHexByteToBin(const char *hex, uint8_t *out);

Converts exactly 2 consecutive hex ASCII characters to one binary byte. Case-insensitive.

Parameter Direction Type Description
hex in const char * Pointer to exactly 2 hex characters (0–9, a–f, A–F). Must not be NULL.
out out uint8_t * Receives the decoded byte. Must not be NULL.

Returns: true if both characters are valid hex digits; false otherwise.

uint8_t out;

if (SSFHexByteToBin("A5", &out))
{
    /* out == 0xA5 */
}

↑ bool SSFHexBytesToBin()

bool SSFHexBytesToBin(SSFCStrIn_t in, size_t inLenLim,
                      uint8_t *out, size_t outSize, size_t *outLen, bool rev);

Decodes a hexadecimal ASCII string into binary bytes. inLenLim must be even; an odd value returns false immediately. Optionally reverses the byte order of the output.

Parameter Direction Type Description
in in SSFCStrIn_t Pointer to the hex ASCII string. Must not be NULL. Must contain only valid hex characters.
inLenLim in size_t Number of input hex characters to decode. Must be even. Must be <= strlen(in).
out out uint8_t * Output buffer receiving decoded bytes. Must not be NULL.
outSize in size_t Allocated size of out in bytes. Must be at least inLenLim / 2.
outLen out size_t * Receives the number of bytes written to out. Must not be NULL.
rev in bool true to decode the hex string in reverse byte order; false to preserve order.

Returns: true if decoding succeeded; false if inLenLim is odd, any input character is not a valid hex digit, or outSize is too small.

uint8_t out[2];
size_t outLen;

if (SSFHexBytesToBin("A5F0", 4u, out, sizeof(out), &outLen, false))
{
    /* outLen == 2, out[0] == 0xA5, out[1] == 0xF0 */
}

↑ bool SSFHexBinToBytes()

bool SSFHexBinToBytes(const uint8_t *in, size_t inLen,
                      SSFCStrOut_t out, size_t outSize, size_t *outLen,
                      bool rev, SSFHexCase_t hcase);

Encodes binary bytes as a null-terminated hexadecimal ASCII string. Optionally reverses the byte order of the input before encoding.

Parameter Direction Type Description
in in const uint8_t * Pointer to the bytes to encode. Must not be NULL.
inLen in size_t Number of bytes to encode from in.
out out SSFCStrOut_t Output buffer receiving the null-terminated hex string. Must not be NULL.
outSize in size_t Allocated size of out in bytes. Must be >= 1. Must be at least (inLen * 2) + 1 to hold the full result.
outLen out (opt) size_t * If not NULL, receives the number of hex characters written, excluding the null terminator.
rev in bool true to encode bytes in reverse order; false to preserve order.
hcase in SSFHexCase_t SSF_HEX_CASE_LOWER for a–f; SSF_HEX_CASE_UPPER for A–F.

Returns: true if encoding succeeded; false if outSize is too small to hold the result.

uint8_t bin[] = {0xA5u, 0xF0u};
char out[5];
size_t outLen;

if (SSFHexBinToBytes(bin, sizeof(bin), out, sizeof(out), &outLen, false, SSF_HEX_CASE_LOWER))
{
    /* outLen == 4, out == "a5f0" */
}

↑ Convenience Macros

↑ bool SSFIsHex()

#define SSFIsHex(h)

Evaluates to true if character h is a valid hexadecimal digit (0–9, a–f, or A–F). h is evaluated exactly once.

Parameter Direction Type Description
h in char Character to test.

Returns: Non-zero (true) if h is a hex digit; zero (false) otherwise.

SSFIsHex('A');    /* returns true  */
SSFIsHex('f');    /* returns true  */
SSFIsHex('3');    /* returns true  */
SSFIsHex('g');    /* returns false */
SSFIsHex(' ');    /* returns false */