Utilities ============= --------------------------------------------------------------- Lookups: --------------------------------------------------------------- --------------------------------------------------------------- Types --------------------------------------------------------------- --------------------------------------------------------------- Macros --------------------------------------------------------------- .. c:macro:: YMO_MIN Simple min macro. .. code-block:: c :caption: Definition #define YMO_MIN(x,y) ((x < y) ? x : y) .. c:macro:: YMO_MAX Simple max macro. .. code-block:: c :caption: Definition #define YMO_MAX(x,y) ((x > y) ? x : y) .. c:macro:: YMO_TOLOWER Fast single-char to lower macro. .. code-block:: c :caption: Definition #define YMO_TOLOWER(c) \ (c ^ (( ((0x40 - c) ^ (0x5a - c)) >> 2) & 0x20)) .. c:macro:: YMO_TOUPPER Fast single-char to upper macro. .. code-block:: c :caption: Definition #define YMO_TOUPPER(c) \ (c ^ (( ((0x60 - c) ^ (0x7a - c)) >> 2) & 0x20)) .. c:macro:: YMO_BASE64_LEN Given a string length in bytes, return the number of bytes required to store the same string, base64 encoded. .. code-block:: c :caption: Definition #define YMO_BASE64_LEN(len) \ ( (4*(len+2)) / 3) .. c:macro:: YMO_PTR_FLOOR Round a pointer DOWN to the nearest void* alignment boundary. .. code-block:: c :caption: Definition #define YMO_PTR_FLOOR(p) (((uintptr_t)p) & ~YMO_PTR_ALIGN_MASK) .. c:macro:: YMO_PTR_CEIL Round a pointer UP to the nearest void* alignment boundary. .. code-block:: c :caption: Definition #define YMO_PTR_CEIL(p) ((((uintptr_t)p) + YMO_PTR_ALIGN_MASK) & ~YMO_PTR_ALIGN_MASK) .. c:macro:: YMO_TYPE_ALIGN(t) Get the alignment for the given type, ``t``. .. c:macro:: YMO_PTR32_FLOOR Round pointer value down to next 32-bit word boundary: .. code-block:: c :caption: Definition #define YMO_PTR32_FLOOR(p) (((uintptr_t)p) & ~YMO_PTR32_ALIGN_MASK) .. c:macro:: YMO_PTR32_CEIL Round pointer value up to next 32-bit word boundary: .. code-block:: c :caption: Definition #define YMO_PTR32_CEIL(p) ((((uintptr_t)p) + YMO_PTR32_ALIGN_MASK) & ~YMO_PTR32_ALIGN_MASK) .. c:macro:: YMO_TYPE_FLOOR Round the input address DOWN to the nearest value that's a multiple of the alignment for the type given by ``s``. .. code-block:: c :caption: Definition #define YMO_TYPE_FLOOR(s, p) ( ((uintptr_t)p) & ~YMO_TYPE_ALIGN(s)) .. c:macro:: YMO_TYPE_CEIL Round the input address UP to the nearest value that's a multiple of the alignment for the type given by ``s``. .. code-block:: c :caption: Definition #define YMO_TYPE_CEIL(s, p) (( ((uintptr_t)p) + YMO_TYPE_ALIGN(s)) & ~YMO_TYPE_ALIGN(s)) --------------------------------------------------------------- Functions --------------------------------------------------------------- .. c:function:: static inline char ymo_tolower(char c) Fast, single-char, tolower function. .. c:function:: static inline char ymo_toupper(char c) Fast, single-char, toupper function. .. c:function:: void ymo_ntolower(char* dst, const char* src, size_t len) Fast full-string tolower implementation. (See `fast_tolower `_). :param dst: destination string (may be same as src) :param src: source string (may be same as dst) :param len: number of characters in the string .. c:function:: void ymo_ntoupper(char* dst, const char* src, size_t len) Fast full-string toupper implementation. (See `fast_tolower `_). :param dst: destination string (may be same as src) :param src: source string (may be same as dst) :param len: number of characters in the string .. c:function:: ymo_status_t ymo_base64_encode(char* dst, const char* src, size_t len) Base64-encode a string into the given buffer. .. warning:: ``dst`` must point to a location in memory with enough space to encode all of ``src`` as base64. Use :c:macro:`YMO_BASE64_LEN` to determine the length, if need be. :param dst: destination buffer :param src: input string :param len: length of ``src`` :returns: ``YMO_OKAY`` on success .. c:function:: char* ymo_base64_encoded(const char* src, size_t len) Allocate enough space to store ``src`` base64-encoded, encode it and return a pointer to the new buffer on success. :param src: input string :param len: length of ``src`` :returns: pointer to new buffer on success; ``NULL`` on failure .. note:: Use :c:macro:`YMO_FREE` to deallocate the returned buffer. .. c:function:: static inline int ymo_strcmp( const char* s1, size_t l1, const char* s2, size_t l2 ) String compare when the length of both strings are known. :param s1: string 1 :param l1: string 1 length :param s2: string 2 :param le: string 2 length :returns: ``0`` if the strings are equal; **non-zero**, otherwise. .. c:function:: static inline int ymo_strcasecmp( const char* s1, size_t l1, const char* s2, size_t l2 ) Case insensitive string compare when the length of both strings are known. :param s1: string 1 :param l1: string 1 length :param s2: string 2 :param le: string 2 length :returns: ``0`` if the strings are equal; **non-zero**, otherwise. .. c:macro:: ymo_utf8_state_reset Initialize or reset a UTF-8 state object. .. code-block:: c :caption: Definition #define ymo_utf8_state_reset(s) ((s)->flags = 0) .. c:function:: ymo_status_t ymo_check_utf8( ymo_utf8_state_t* state, const char* buffer, size_t len, int done) Check that a given string of bytes is valid UTF-8. :param state: present UTF-8 validator state :param buffer: the buffer to check :param len: the length of the buffer to check :param done: if true, ``buffer + (len-1)`` is the last byte in the stream :returns: ``YMO_OKAY`` on success; errno value otherwise .. code-block:: c :caption: Example char buffer[BUFF_MAX]; ymo_utf8_state_t state; ymo_utf8_state_reset(&state); // (read some data into buffer) // Check that what we've got so is valid: ymo_status_t u_status; if( (u_status = ymo_check_utf8(&state, buffer, len, 0)) != YMO_OKAY ) { ymo_log_info("Invalid UTF-8: %s", strerror(u_status)); } // (read some more data into buffer; set done=1 if that's the EOM) if( (u_status = ymo_check_utf8(&state, buffer, len, 1)) != YMO_OKAY ) { ymo_log_info("Invalid UTF-8: %s", strerror(u_status)); }