path: root/include/lib.h

#pragma once

#include <stdarg.h>
#include <stddef.h>


//
//  memory operations
//


/**
 * 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, size_t n);

/**
 * 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, size_t n);

/**
 * 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 *restrict dest, const volatile void *restrict src, size_t n);

/**
 * 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, size_t n);

/**
 * 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 *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
//


/**
 * 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
 */
size_t strlen(const char *str);

/**
 * 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, size_t n);


//
//  string copying and concatenation
//


/**
 * 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);

/**
 * 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, size_t n);

/**
 * 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
 */
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 dest.
 * @param dest - the destination
 * @param src - the source
 * @returns a pointer to dest
 */
char *strcat(char *restrict dest, const char *restrict src);


//
//  character operations
//


/**
 * @returns 1 if c is a space
 */
int isspace(int c);

/**
 * @returns 1 if c is a digit (0 - 9)
 */
int isdigit(int c);

/**
 * converts single digit int to base 36
 * @param i - int
 * @returns c - base 36 char
 */
char itoc(int i);

/**
 * converts single base 36 chat into int
 * @param c - base 36 char
 * @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
 * @returns the number inside s or 0 on error
 */
int atoi(const char *s);

/**
 * Converts the initial portiion of the string pointed to by s to long.
 * @param s - the string to convert
 * @returns the number inside s or 0 on error
 */
long int atol(const char *s);

/**
 * Converts the initial portiion of the string pointed to by s to long long.
 * @param s - the string to convert
 * @returns the number inside s or 0 on error
 */
long long int atoll(const char *s);

/**
 * Converts a integer to asci inside a string with a given radix (base).
 * @param n - the number to convert
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *itoa(int n, char *buffer, int radix);

/**
 * Converts a long to asci inside a string with a given radix (base).
 * @param n - the number to convert
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *ltoa(long int n, char *buffer, int radix);

/**
 * Converts a long long to asci inside a string with a given radix (base).
 * @param n - the number to conver
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *lltoa(long long int n, char *buffer, int radix);

/**
 * Converts a unsigned integer to asci inside a string with a given radix (base).
 * @param n - the number to convert
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *utoa(unsigned int n, char *buffer, int radix);

/**
 * Converts a unsigned long to asci inside a string with a given radix (base).
 * @param n - the number to convert
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *ultoa(unsigned long int n, char *buffer, int radix);

/**
 * Converts a unsigned long long to asci inside a string with a given radix (base).
 * @param n - the number to conver
 * @param buffer - the string buffer
 * @param radix - the base to convert
 */
char *ulltoa(unsigned long long int n, char *buffer, int radix);

/**
 * 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
 * @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
 */
int strtoi(const char *str, char **endptr, int 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
 * @param base - the base to convert to
 * @returns 0 on error or success, error if endptr is still equal to str
 */
long int strtol(const char *str, char **endptr, int 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
 * @param base - the base to convert to
 * @returns 0 on error or success, error if endptr is still equal to str
 */
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
 */
void kputc(char c);

/**
 * Prints out a null terminated string
 * @param s - the string
 */
void kputs(const char *s);

/**
 * Prints out a formatted string
 * @param format - the format string
 * @param ... - variable args for the format
 */
void kvprintf(const char *format, va_list args);

/**
 * Prints out a formatted string
 * @param format - the format string
 * @param ... - variable args for the format
 */
__attribute__((format(printf, 1, 2)))
void kprintf(const char *format, ...);