Base/code/exports/librr/runes.h

#ifndef RR_RUNES_H
#define RR_RUNES_H

#include <librr/types.h>

/// @brief 
/// @param string 
/// @param offset 
/// @param increase 
/// @return The UTF-8 character which was extracted OR 0 is the function failed.
rune_t rr_extract_utf8(const char *string, usz_t offset, usz_t *increase);

/// @brief Extracts a lowercase letter at some offset in an UTF-8 - string.
///  The function adds the rest length of the found lowercase letter to an
///  integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not a lowercase letter.
/// @return The rune which was extracted or ZERO if the found rune is not a lowercase letter.
rune_t rr_extract_lower(const char *string, usz_t offset, usz_t *advance);

/// @brief Extracts an uppercase letter at some offset in an UTF-8 - string.
///  The function adds the rest length of the found uppercase letter to an
///  integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not an uppercase letter.
/// @return The rune which was extracted or ZERO if the found rune is not an uppercase letter.
rune_t rr_extract_upper(const char *string, usz_t offset, usz_t *advance);

/// @brief Extracts a letter at some offset in an UTF-8 - string.
///  The function adds the rest length of the found letter to an
///  integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not a letter.
/// @return The rune which was extracted or ZERO if the found rune is not a letter.
rune_t rr_extract_letter(const char *string, usz_t offset, usz_t *advance);

/// @brief Extracts a digit at some offset in an UTF-8 - string.
///  The function adds the rest length of the found digit to an
///  integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not a digit.
/// @return The rune which was extracted or ZERO if the found rune is not a digit.
rune_t rr_extract_digit(const char *string, usz_t offset, usz_t *advance);

/// @brief Extracts an alphanumeric rune at some offset in an UTF-8 - string.
///  The function adds the rest length of the alphanumeric rune found to an
///  integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not an alphanumeric rune.
/// @return The rune which was extracted or ZERO if the found rune is not alphanumeric.
rune_t rr_extract_alphanumeric(const char *string, usz_t offset, usz_t *advance);

/// @brief Extracts a special sign (such as slash, at, the hash sign, etc.)
///  at some offset in an UTF-8 - string. The function adds the rest length
///  of the found sign to an integer to which a pointer was given.
/// @attention 'advance' will be ADDED TO, it won't be set to a comletely new value.
/// @attention Not the full length of the rune but rather the rest length,
///  the length starting from the reading offset going to the end of the rune
///  will be added onto 'advance'.
/// @param string Null-terminated UTF-8 (or ASCII) string from which the
///  rune should be extracted. This will not be modified.
/// @param offset Offset from the start of the string at which the rune will
///  be read. This doesn't have to point to the start of the rune; the start
///  will be found.
/// @param advance How many bytes 'offset' must be advanced to get to the first
///  byte of the next rune. This will NOT be set if the rune is not a sign.
/// @return The rune which was extracted or ZERO if the found rune is not a sign.
rune_t rr_extract_sign(const char *string, usz_t offset, usz_t *advance);

/// @brief Checks if there is a newline delimiter at a specific offset in a string
///  and writes the offset right after it to a given pointer's destination.
/// @attention The next rune's offset will replace the previous content of the given pointer,
///  the offset will not be added to.
/// @param string The string in question
/// @param offset The offset in the string at which the test should be done.
/// @param next The pointer to the integer to which the offset will be written.
///  in contrast to the other rune functions, this does NOT add, it SETS the value
///  relative to 'offset'. This will NOT be set if no newline was found.
/// @return TRUE if there is a newline at that point and FALSE if not.
bool_t rr_check_newline(const char *string, usz_t offset, usz_t *next);

#endif // LIBRR_RUNES_H