qh_str_to_bytes()

Updated: April 19, 2023

Safely converts a string representing a size in bytes with an optional size suffix into a uint64_t

Synopsis:

#include <qh/string.h>
int qh_str_to_bytes(const char *str,
                    uint64_t *number,
                    size_t *end_offset)

Arguments:

str
The string to convert into a number.
number
Pointer to the location where the number can be stored.
end_offset
The offset where parsing stopped.

Library:

qh

Description:

The string is interpreted as a decimal (base 10) and if a suffix is specified, the value is multiplied by a corresponding amount. Valid suffixes are k, m, g, and t, each of which represents the appropriate power of 1024. Note that suffixes are case insensitive and must come directly after the number, with no whitespace in between.

This function is similar to strtoull(), but does more error checking on the result of the conversion and ensures that the result fits in a uint64_t. This simplifies the work the caller is required to do, which is only to validate that the return value from qh_str_to_bytes() is EOK.

For conversion of strings that are part of a longer one (e.g., a comma-separated list), an optional end_offset parameter can be specified. When you specify end_offset, the function returns successfully even if there are trailing characters. When non-NULL, end_offset is always updated with the offset of the last character the function parsed. When NULL, the function treats trailing characters as invalid, except for characters recognized by isspace().

For more information on using this function, see the documentation for strtoull().

Returns:

EOK on success or a standard errno on failure (errno is also set, and number isn't updated except for ERANGE).

ERANGE
The number value is larger than UINT64_MAX and UINT64_MAX is returned.