diff options
Diffstat (limited to 'include/lib.h')
| -rw-r--r-- | include/lib.h | 224 |
1 files changed, 178 insertions, 46 deletions
diff --git a/include/lib.h b/include/lib.h index 7c74fa2..b5f6ccc 100644 --- a/include/lib.h +++ b/include/lib.h @@ -3,77 +3,156 @@ #include <stdarg.h> #include <stddef.h> + +// +// memory operations +// + + /** - * The memcmp() function compares the first n bytes (each interpreted as unsigned char) of the memory - * areas s1 and s2. + * Compare the first n bytes (interpreted as unsigned char) of the memory areas s1 and s2 + * @param s1 - the first memory area + * @param s2 - the second memory area + * @param n - the byte count + * @returns an interger less than, equal to, or greater than 0 if the first n bytes + * of s1 are less than, equal to, or greater than s2. */ -int memcmp(const void *restrict s1, const void *restrict s2, unsigned long n); +int memcmp(const void *restrict s1, const void *restrict s2, size_t n); /** - * the memcpy() function copies n bytes from memory area src to memory area dest. - * the memory areas must not overlap. + * Copy the first n bytes from memory area src to memory area dest. The memory + * areas must not overlap. + * @param dest - the destination + * @param src - the source + * @param n - the byte count + * @returns a pointer to dest */ -void *memcpy(void *restrict dest, const void *restrict src, unsigned long n); +void *memcpy(void *restrict dest, const void *restrict src, size_t n); /** - * the memcpy() function copies n bytes from memory area src to memory area dest. - * the memory areas must not overlap. + * Volatile version of memcpy. + * Copy the first n bytes from memory area src to memory area dest. The memory + * areas must not overlap. + * @param dest - the destination + * @param src - the source + * @param n - the byte count + * @returns a pointer to dest */ -volatile void *memcpyv(volatile void *dest, const volatile void *src, unsigned long n); +volatile void *memcpyv(volatile void *restrict dest, const volatile void *restrict src, size_t n); /** - * The memmove() function copies n bytes from memory area src to memory area dest. The memory areas - * may overlap: copying takes place as though the bytes in src are first copied into a temporary array - * that does not overlap src or dest, and the bytes are then copied from the temporary array to dest. + * Copy the first n bytes from memory area src to memory area dest. The memory + * areas may overlap; memmove behaves as though the bytes are first copied to a + * temporary array. + * @param dest - the destination + * @param src - the source + * @param n - the byte count + * @returns a pointer to dest */ -void *memmove(void *dest, const void *src, unsigned long n); +void *memmove(void *dest, const void *src, size_t n); /** - * The memset() function fills the first n bytes of the memory area pointed to by s with the constant - * byte c. + * Fill the first n bytes of the memory region dest with the constant byte c. + * @param dest - the destination + * @param c - the byte to write + * @param n - the byte count + * @returns a pointer to dest */ -void *memset(void *restrict dest, int c, unsigned long n); +void *memset(void *dest, int c, size_t n); + +/** + * Volatile version of memset. + * Fill the first n bytes of the memory region dest with the constant byte c. + * @param c - the byte to write + * @param n - the byte count + * @returns a pointer to dest + */ +volatile void *memsetv(volatile void *dest, int c, size_t n); + + +// +// string operations +// + /** - * The memset() function fills the first n bytes of the memory area pointed to by s with the constant - * byte c. + * Calculates the length of the string pointed to by str, excluding + * the terminating null byte + * @param str - the string pointer + * @returns the length of the string in bytes */ -volatile void *memsetv(volatile void *dest, int c, unsigned long n); +size_t strlen(const char *str); /** - * The strcmp() function compares the two strings s1 and s2. The locale is not taken into account - * (for a locale-aware comparison, see strcoll(3)). The comparison is done using unsigned characters. + * Compare at most the first n bytes of the strings s1 and s2. The comparison is + * done using unsigned characters. + * @param s1 - a pointer to the first string + * @param s2 - a pointer to the second string + * @param n - the maximum number of bytes + * @returns an interger less than, equal to, or greater than 0 if s1 compares less + * than, equal to, or greater than s2 */ -int strncmp(const char *restrict s1, const char *restrict s2, unsigned long n); +int strncmp(const char *restrict s1, const char *restrict s2, size_t n); + + +// +// string copying and concatenation +// + /** - * Copys the string pointed to by src , into a string at the buffer pointer to by dest. + * Copies the string pointed to by src into the buffer pointer to by dest. * The dest buffer must be long enough to hold src. + * @param dest - the destination + * @param src - the source + * @returns a pointer to dest */ char *strcpy(char *restrict dest, const char *restrict src); /** - * Copys the string pointed to by src , into a string at the buffer pointer to by dest. + * Copies the string pointed to by src into the buffer pointer to by dest. * The dest buffer must be long enough to hold src or size n. + * @param dest - the destination + * @param src - the source + * @param n - the maximum number of bytes + * @returns a pointer to dest */ -char *strncpy(char *restrict dest, const char *restrict src, unsigned long n); +char *strncpy(char *restrict dest, const char *restrict src, size_t n); /** - * Calculates the length of the string pointed to by str, excluding - * the terminating null byte - * @param str - the string pointer - * @returns the length of the string in bytes + * Copies the string pointed to by src into the buffer pointed to by dest. + * The dest buffer must be long enough to hold src. + * @param dest - the destination + * @param src - the source + * @param n - the maximum number of bytes + * @returns a pointer to the terminating null byte */ -size_t strlen(const char *str); +char *stpcpy(char *restrict dest, const char *restrict src); + +/** + * Copies the string pointed to by src into the buffer pointed to by dest. + * The dest buffer must be long enough to hold src or size n. + * @param dest - the destination + * @param src - the source + * @param n - the maximum number of bytes + * @returns a pointer to the byte after the last character copied + */ +char *stpncpy(char *restrict dest, const char *restrict src, size_t n); /** * Concatenate the string pointed to by src after the string pointed - * to by dst. - * @param dst - the pointer to the destination string - * @param src - the pointer to the source string - * @returns dst + * to by dest. + * @param dest - the destination + * @param src - the source + * @returns a pointer to dest */ -char *strcat(char *restrict dst, const char *restrict src); +char *strcat(char *restrict dest, const char *restrict src); + + +// +// character operations +// + /** * @returns 1 if c is a space @@ -95,10 +174,16 @@ char itoc(int i); /** * converts single base 36 chat into int * @param c - base 36 char - * @returns i - int + * @returns i - int, or -1 if the char was invalid */ int ctoi(char c); + +// +// string/numeric conversions +// + + /** * Converts the initial portiion of the string pointed to by s to int. * @param s - the string to convert @@ -169,14 +254,6 @@ char *ultoa(unsigned long int n, char *buffer, int radix); char *ulltoa(unsigned long long int n, char *buffer, int radix); /** - * Converts a byte count to a human readable file size - * @param bytes - the bytes to convert - * @param buf - the buffer to store it in - * @preturns - bus - */ -char *btoa(size_t bytes, char *buf); - -/** * Converts the string in str to an int value based on the given base. * The endptr is updated to where the string was no longer valid. * @param str - the string buffer @@ -187,7 +264,7 @@ char *btoa(size_t bytes, char *buf); int strtoi(const char *str, char **endptr, int base); /** - * Converts the string in str to an long value based on the given base. + * Converts the string in str to a long value based on the given base. * The endptr is updated to where the string was no longer valid. * @param str - the string buffer * @param endptr - the endptr @@ -197,7 +274,7 @@ int strtoi(const char *str, char **endptr, int base); long int strtol(const char *str, char **endptr, int base); /** - * Converts the string in str to an long long value based on the given base. + * Converts the string in str to a long long value based on the given base. * The endptr is updated to where the string was no longer valid. * @param str - the string buffer * @param endptr - the endptr @@ -207,6 +284,61 @@ long int strtol(const char *str, char **endptr, int base); long long int strtoll(const char *str, char **endptr, int base); /** + * Converts the string in str to an unsigned int value based on the given base. + * The endptr is updated to where the string was no longer valid. + * @param str - the string buffer + * @param endptr - the endptr + * @param base - the base to convert to + * @returns 0 on error or success, error if endptr is still equal to str + */ +unsigned int strtoui(const char *str, char **endptr, int base); + +/** + * Converts the string in str to an unsigned long value based on the given base. + * The endptr is updated to where the string was no longer valid. + * @param str - the string buffer + * @param endptr - the endptr + * @param base - the base to convert to + * @returns 0 on error or success, error if endptr is still equal to str + */ +unsigned long int strtoul(const char *str, char **endptr, int base); + +/** + * Converts the string in str to an unsigned long long value based on the given base. + * The endptr is updated to where the string was no longer valid. + * @param str - the string buffer + * @param endptr - the endptr + * @param base - the base to convert to + * @returns 0 on error or success, error if endptr is still equal to str + */ +unsigned long long int strtoull(const char *str, char **endptr, int base); + +/** + * Converts a byte count to a human readable file size of at most four characters + * using binary suffixes. + * + * The following rules are applied: + * - If the byte count is less than 1024, the count is written in decimal + * and no suffix is applied + * - Otherwise, repeatedly divide by 1024 until the value is under 1000. + * - If the value has two or three decimal digits, print it followed by the + * approprate suffix. + * - If the value has one decimal digit, print it along with a single fractional + * digit. This also applies if the value is zero. + * + * @param bytes - the bytes to convert + * @param buf - a pointer to the buffer to store it in (which must be at least five + * bytes long) + * @returns - buf + */ +char *btoa(size_t bytes, char *buf); + + +// +// printing and formatting +// + +/** * Prints out a char * @param c - the char */ |