ColrC  0.4.0
An easy to use C library for linux terminal colors/escape-codes.
colr.c File Reference

(0.4.0)

Implements everything in the colr.h header. More...

#include "colr.h"

Functions

void _colr_free (void *p)
 Calls Colr *_free() functions for Colr objects, otherwise just calls free(). More...
 
bool _colr_is_last_arg (void *p)
 Determines if a void pointer is _ColrLastArg (the last-arg-marker). More...
 
char * _colr_join (void *joinerp,...)
 Joins ColorArgs, ColorTexts, and strings (char*) into one long string separated by it's first argument. More...
 
size_t _colr_join_array_length (void *ps)
 Determine the length of a NULL-terminated array of strings (char*), ColorArgs, ColorResults, or ColorTexts. More...
 
size_t _colr_join_arrayn_size (void *joinerp, void *ps, size_t count)
 Get the size in bytes needed to join an array of strings (char*), ColorArgs, ColorResults, or ColorTexts by another string (char*), ColorArg, ColorResult, or ColorText. More...
 
size_t _colr_join_size (void *joinerp, va_list args)
 Parse arguments, just as in _colr_join(), but only return the size needed to allocate the resulting string. More...
 
size_t _colr_ptr_length (void *p)
 Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char*) into a string. More...
 
char * _colr_ptr_repr (void *p)
 Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obtain an allocated string representation. More...
 
char * _colr_ptr_to_str (void *p)
 Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to obtain an allocated string. More...
 
char * _rainbow (RGB_fmter fmter, const char *s, double freq, size_t offset, size_t spread)
 Handles multibyte character string (char*) conversion and character iteration for all of the rainbow_ functions. More...
 
bool ArgType_eq (ArgType a, ArgType b)
 Compares two ArgTypes. More...
 
char * ArgType_repr (ArgType type)
 Creates a string (char*) representation of a ArgType. More...
 
char * ArgType_to_str (ArgType type)
 Creates a human-friendly string (char*) from an ArgType. More...
 
bool BasicValue_eq (BasicValue a, BasicValue b)
 Compares two BasicValues. More...
 
BasicValue BasicValue_from_esc (const char *s)
 Convert an escape-code string (char*) to an actual BasicValue enum value. More...
 
BasicValue BasicValue_from_str (const char *arg)
 Convert named argument to an actual BasicValue enum value. More...
 
bool BasicValue_is_invalid (BasicValue bval)
 Determines whether a BasicValue is invalid. More...
 
bool BasicValue_is_valid (BasicValue bval)
 Determines whether a BasicValue is valid. More...
 
char * BasicValue_repr (BasicValue bval)
 Creates a string (char*) representation of a BasicValue. More...
 
int BasicValue_to_ansi (ArgType type, BasicValue bval)
 Converts a fore/back BasicValue to the actual ansi code number. More...
 
char * BasicValue_to_str (BasicValue bval)
 Create a human-friendly string (char*) representation for a BasicValue. More...
 
ColorArg ColorArg_empty (void)
 Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE. More...
 
bool ColorArg_eq (ColorArg a, ColorArg b)
 Compares two ColorArg structs. More...
 
char * ColorArg_example (ColorArg carg, bool colorized)
 Create a string (char*) representation of a ColorArg with a stylized type/name using escape codes built from the ColorArg's values. More...
 
void ColorArg_free (ColorArg *p)
 Free allocated memory for a ColorArg. More...
 
ColorArg ColorArg_from_BasicValue (ArgType type, BasicValue value)
 Explicit version of ColorArg_from_value that only handles BasicValues. More...
 
ColorArg ColorArg_from_esc (const char *s)
 Parse an escape-code string (char*) into a ColorArg. More...
 
ColorArg ColorArg_from_ExtendedValue (ArgType type, ExtendedValue value)
 Explicit version of ColorArg_from_value that only handles ExtendedValues. More...
 
ColorArg ColorArg_from_RGB (ArgType type, RGB value)
 Explicit version of ColorArg_from_value that only handles RGB structs. More...
 
ColorArg ColorArg_from_str (ArgType type, const char *colorname)
 Build a ColorArg (fore, back, or style value) from a known color name/style. More...
 
ColorArg ColorArg_from_StyleValue (ArgType type, StyleValue value)
 Explicit version of ColorArg_from_value that only handles StyleValues. More...
 
ColorArg ColorArg_from_value (ArgType type, ColorType colrtype, void *p)
 Used with the color_arg macro to dynamically create a ColorArg based on it's argument type. More...
 
bool ColorArg_is_empty (ColorArg carg)
 Checks to see if a ColorArg is an empty placeholder. More...
 
bool ColorArg_is_invalid (ColorArg carg)
 Checks to see if a ColorArg holds an invalid value. More...
 
bool ColorArg_is_ptr (void *p)
 Checks a void pointer to see if it contains a ColorArg struct. More...
 
bool ColorArg_is_valid (ColorArg carg)
 Checks to see if a ColorArg holds a valid value. More...
 
size_t ColorArg_length (ColorArg carg)
 Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc(). More...
 
char * ColorArg_repr (ColorArg carg)
 Creates a string (char*) representation for a ColorArg. More...
 
char * ColorArg_to_esc (ColorArg carg)
 Converts a ColorArg into an escape code string (char*). More...
 
bool ColorArg_to_esc_s (char *dest, ColorArg carg)
 Converts a ColorArg into an escape code string (char*) and fills the destination string. More...
 
ColorArgColorArg_to_ptr (ColorArg carg)
 Copies a ColorArg into memory and returns the pointer. More...
 
void ColorArgs_array_free (ColorArg **ps)
 Free an allocated array of ColorArgs, including the array itself. More...
 
char * ColorArgs_array_repr (ColorArg **lst)
 Creates a string representation for an array of ColorArg pointers. More...
 
ColorArg ** ColorArgs_from_str (const char *s, bool unique)
 Create an array of ColorArgs from escape-codes found in a string (char*). More...
 
ColorJustify ColorJustify_empty (void)
 Creates an "empty" ColorJustify, with JUST_NONE set. More...
 
bool ColorJustify_eq (ColorJustify a, ColorJustify b)
 Compares two ColorJustify structs. More...
 
bool ColorJustify_is_empty (ColorJustify cjust)
 Checks to see if a ColorJustify is "empty". More...
 
ColorJustify ColorJustify_new (ColorJustifyMethod method, int width, char padchar)
 Creates a ColorJustify. More...
 
char * ColorJustify_repr (ColorJustify cjust)
 Creates a string (char*) representation for a ColorJustify. More...
 
char * ColorJustifyMethod_repr (ColorJustifyMethod meth)
 Creates a string (char*) representation for a ColorJustifyMethod. More...
 
ColorResultColorResult_center (ColorResult *cres, int width, char padchar)
 Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More...
 
ColorResultColorResult_Colr (ColorResult *cres,...)
 Colorize a ColorResult, and return a new allocated ColorResult. More...
 
ColorResult ColorResult_empty (void)
 Creates a ColorResult with .result=NULL and .length=-1, with the appropriate struct marker. More...
 
bool ColorResult_eq (ColorResult a, ColorResult b)
 Compares two ColorResults. More...
 
void ColorResult_free (ColorResult *p)
 Free allocated memory for a ColorResult and it's .result member. More...
 
ColorResult ColorResult_from_str (const char *s)
 Allocates a copy of a string, and creates a ColorResult from it. More...
 
ColorResultColorResult_from_stra (const char *s)
 Allocates a copy of a string, and creates an allocated ColorResult from it. More...
 
bool ColorResult_is_empty (ColorResult cres)
 Checks to see if a ColorResult is "empty" (NULL or empty string). More...
 
bool ColorResult_is_ptr (void *p)
 Checks a void pointer to see if it contains a ColorResult struct. More...
 
size_t ColorResult_length (ColorResult cres)
 Return the length in bytes (including the null-terminator), that is needed to store the return from ColorResult_to_str() (.result). More...
 
ColorResultColorResult_ljust (ColorResult *cres, int width, char padchar)
 Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More...
 
ColorResult ColorResult_new (char *s)
 Initialize a new ColorResult with an allocated string (char*). More...
 
char * ColorResult_repr (ColorResult cres)
 Create a string representation for a ColorResult. More...
 
char * ColorResult_rip_str (ColorResult *cres)
 Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char*)). More...
 
ColorResultColorResult_rjust (ColorResult *cres, int width, char padchar)
 Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More...
 
ColorResultColorResult_to_ptr (ColorResult cres)
 Allocate memory for a ColorResult, fill it, and return it. More...
 
char * ColorResult_to_str (ColorResult cres)
 Convert a ColorResult into a string (char*). More...
 
ColorText ColorText_empty (void)
 Creates an "empty" ColorText with pointers set to NULL. More...
 
void ColorText_free (ColorText *p)
 Frees a ColorText and it's ColorArgs. More...
 
void ColorText_free_args (ColorText *p)
 Frees the ColorArg members of a ColorText. More...
 
ColorText ColorText_from_values (char *text,...)
 Builds a ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More...
 
ColorText ColorText_from_valuesv (char *text, va_list args)
 Builds a ColorText from 1 mandatory string (char*), and a va_list with optional fore, back, and style args (pointers to ColorArgs). More...
 
bool ColorText_has_arg (ColorText ctext, ColorArg carg)
 Checks to see if a ColorText has a certain ColorArg value set. More...
 
bool ColorText_has_args (ColorText ctext)
 Checks to see if a ColorText has any argument values set. More...
 
bool ColorText_is_empty (ColorText ctext)
 Checks to see if a ColorText has no usable values. More...
 
bool ColorText_is_ptr (void *p)
 Checks a void pointer to see if it contains a ColorText struct. More...
 
size_t ColorText_length (ColorText ctext)
 Returns the length in bytes needed to allocate a string (char*) built with ColorText_to_str() with the current text, fore, back, and style members. More...
 
char * ColorText_repr (ColorText ctext)
 Allocate a string (char*) representation for a ColorText. More...
 
ColorTextColorText_set_center (ColorText *ctext, int width, char padchar)
 Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string. More...
 
ColorTextColorText_set_just (ColorText *ctext, ColorJustify cjust)
 Set the ColorJustify method for a ColorText, and return the ColorText. More...
 
ColorTextColorText_set_ljust (ColorText *ctext, int width, char padchar)
 Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string. More...
 
ColorTextColorText_set_rjust (ColorText *ctext, int width, char padchar)
 Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string. More...
 
void ColorText_set_values (ColorText *ctext, char *text,...)
 Initializes an existing ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More...
 
ColorTextColorText_to_ptr (ColorText ctext)
 Copies a ColorText into allocated memory and returns the pointer. More...
 
char * ColorText_to_str (ColorText ctext)
 Stringifies a ColorText struct, creating a mix of escape codes and text. More...
 
bool ColorType_eq (ColorType a, ColorType b)
 Compares two ColorTypes. More...
 
ColorType ColorType_from_str (const char *arg)
 Determine which type of color value is desired by name. More...
 
bool ColorType_is_invalid (ColorType type)
 Check to see if a ColorType value is considered invalid. More...
 
bool ColorType_is_valid (ColorType type)
 Check to see if a ColorType value is considered valid. More...
 
char * ColorType_repr (ColorType type)
 Creates a string (char*) representation of a ColorType. More...
 
char * ColorType_to_str (ColorType type)
 Create a human-friendly string (char*) representation for a ColorType. More...
 
ColorValue ColorValue_empty (void)
 Create an "empty" ColorValue. More...
 
bool ColorValue_eq (ColorValue a, ColorValue b)
 Compares two ColorValue structs. More...
 
char * ColorValue_example (ColorValue cval)
 Create a string (char*) representation of a ColorValue with a human-friendly type/name. More...
 
ColorValue ColorValue_from_esc (const char *s)
 Convert an escape-code string (char*) into a ColorValue. More...
 
ColorValue ColorValue_from_str (const char *s)
 Create a ColorValue from a known color name, or RGB string (char*). More...
 
ColorValue ColorValue_from_value (ColorType type, void *p)
 Used with the color_val macro to dynamically create a ColorValue based on it's argument type. More...
 
bool ColorValue_has_BasicValue (ColorValue cval, BasicValue bval)
 Checks to see if a ColorValue has a BasicValue set. More...
 
bool ColorValue_has_ExtendedValue (ColorValue cval, ExtendedValue eval)
 Checks to see if a ColorValue has a ExtendedValue set. More...
 
bool ColorValue_has_RGB (ColorValue cval, RGB rgb)
 Checks to see if a ColorValue has a RGB value set. More...
 
bool ColorValue_has_StyleValue (ColorValue cval, StyleValue sval)
 Checks to see if a ColorValue has a StyleValue set. More...
 
bool ColorValue_is_empty (ColorValue cval)
 Checks to see if a ColorValue is an empty placeholder. More...
 
bool ColorValue_is_invalid (ColorValue cval)
 Checks to see if a ColorValue holds an invalid value. More...
 
bool ColorValue_is_valid (ColorValue cval)
 Checks to see if a ColorValue holds a valid value. More...
 
size_t ColorValue_length (ArgType type, ColorValue cval)
 Returns the length in bytes needed to allocate a string (char*) built with ColorValue_to_esc() with the specified ArgType and ColorValue. More...
 
char * ColorValue_repr (ColorValue cval)
 Creates a string (char*) representation of a ColorValue. More...
 
char * ColorValue_to_esc (ArgType type, ColorValue cval)
 Converts a ColorValue into an escape code string (char*). More...
 
bool ColorValue_to_esc_s (char *dest, ArgType type, ColorValue cval)
 Converts a ColorValue into an escape code string (char*) and fills the destination string. More...
 
regmatch_t * colr_alloc_regmatch (regmatch_t match)
 Allocates space for a regmatch_t, initializes it, and returns a pointer to it. More...
 
void colr_append_reset (char *s)
 Appends CODE_RESET_ALL to a string (char*), but makes sure to do it before any newlines. More...
 
ColorResultColr_center_char (void *x, int width, char padchar)
 Returns a center-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More...
 
char colr_char_escape_char (const char c)
 Returns the char needed to represent an escape sequence in C. More...
 
bool colr_char_in_str (const char *s, const char c)
 Determines if a character exists in the given string (char*). More...
 
bool colr_char_is_code_end (const char c)
 Determines if a character is suitable for an escape code ending. More...
 
char * colr_char_repr (char c)
 Creates a string (char*) representation for a char. More...
 
bool colr_char_should_escape (const char c)
 Determines if an ascii character has an escape sequence in C. More...
 
bool colr_check_marker (uint32_t marker, void *p)
 Checks an unsigned int against the individual bytes behind a pointer's value. More...
 
char * colr_empty_str (void)
 Allocates an empty string (char*). More...
 
ColorResultColr_fmt_str (const char *fmt,...)
 Allocate and format a string like asprintf, but wrap it in an allocated ColorResult. More...
 
void colr_free_argsv (va_list args)
 Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list. More...
 
void colr_free_re_matches (regmatch_t **matches)
 Free an array of allocated regmatch_t, like the return from colr_re_matches(). More...
 
bool colr_is_colr_ptr (void *p)
 Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer. More...
 
char * colr_join_array (void *joinerp, void *ps)
 Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText. More...
 
char * colr_join_arrayn (void *joinerp, void *ps, size_t count)
 Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText. More...
 
ColorResultColr_ljust_char (void *x, int width, char padchar)
 Returns a left-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More...
 
size_t colr_mb_len (const char *s, size_t length)
 Like mbrlen, except it will return the length of the next N (length) multibyte characters in bytes. More...
 
int colr_printf_handler (FILE *fp, const struct printf_info *info, const void *const *args)
 Handles printing with printf for Colr objects. More...
 
int colr_printf_info (const struct printf_info *info, size_t n, int *argtypes, int *sz)
 Handles the arg count/size for the Colr printf handler. More...
 
void colr_printf_register (void)
 Registers COLR_FMT_CHAR to handle Colr objects in the printf-family functions. More...
 
regmatch_t ** colr_re_matches (const char *s, regex_t *repattern)
 Returns all regmatch_t matches for regex pattern in a string (char*). More...
 
ColorResultColr_rjust_char (void *x, int width, char padchar)
 Returns a right-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More...
 
bool colr_set_locale (void)
 Sets the locale to (LC_ALL, "") if it hasn't already been set. More...
 
bool colr_str_array_contains (char **lst, const char *s)
 Determine if a string (char*) is in an array of strings (char**, where the last element is NULL). More...
 
void colr_str_array_free (char **ps)
 Free an allocated array of strings, including the array itself. More...
 
char * colr_str_center (const char *s, int width, const char padchar)
 Center-justifies a string (char*), ignoring escape codes when measuring the width. More...
 
size_t colr_str_char_count (const char *s, const char c)
 Counts the number of characters (c) that are found in a string (char*) (s). More...
 
size_t colr_str_char_lcount (const char *s, const char c)
 Counts the number of characters (c) that are found at the beginning of a string (char*) (s). More...
 
size_t colr_str_chars_lcount (const char *restrict s, const char *restrict chars)
 Counts the number of characters that are found at the beginning of a string (char*) (s), where the character can be any of chars. More...
 
size_t colr_str_code_count (const char *s)
 Return the number of escape-codes in a string (char*). More...
 
size_t colr_str_code_len (const char *s)
 Return the number of bytes that make up all the escape-codes in a string (char*). More...
 
char * colr_str_copy (char *restrict dest, const char *restrict src, size_t length)
 Copies a string (char*) like strncpy, but ensures null-termination. More...
 
bool colr_str_ends_with (const char *restrict s, const char *restrict suffix)
 Determine if one string (char*) ends with another. More...
 
char ** colr_str_get_codes (const char *s, bool unique)
 Get an array of escape-codes from a string (char*). More...
 
bool colr_str_has_codes (const char *s)
 Determines if a string (char*) has ANSI escape codes in it. More...
 
bool colr_str_has_ColorArg (const char *s, ColorArg *carg)
 Determines whether a string contains a specific color code. More...
 
ColrHash colr_str_hash (const char *s)
 Hash a string using djb2. More...
 
bool colr_str_is_all (const char *s, const char c)
 Determines whether a string (char*) consists of only one character, possibly repeated. More...
 
bool colr_str_is_codes (const char *s)
 Determines if a string (char*) is composed entirely of escape codes. More...
 
bool colr_str_is_digits (const char *s)
 Determines whether all characters in a string (char*) are digits. More...
 
bool colr_str_is_empty (const char *s)
 Checks to see if a string empty. More...
 
char * colr_str_ljust (const char *s, int width, const char padchar)
 Left-justifies a string (char*), ignoring escape codes when measuring the width. More...
 
void colr_str_lower (char *s)
 Converts a string (char*) into lower case in place. More...
 
size_t colr_str_lstrip (char *restrict dest, const char *restrict s, size_t length, const char c)
 Strip a leading character from a string (char*), filling another string (char*) with the result. More...
 
char * colr_str_lstrip_char (const char *s, const char c)
 Strips a leading character from a string (char*), and allocates a new string with the result. More...
 
char * colr_str_lstrip_chars (const char *restrict s, const char *restrict chars)
 Removes certain characters from the start of a string (char*) and allocates a new string with the result. More...
 
size_t colr_str_mb_len (const char *s)
 Returns the number of characters in a string (char*), taking into account possibly multibyte characters. More...
 
size_t colr_str_noncode_len (const char *s)
 Returns the length of string (char*), ignoring escape codes and the the null-terminator. More...
 
char * colr_str_replace (const char *restrict s, const char *restrict target, const char *restrict repl)
 Replaces the first substring found in a string (char*). More...
 
char * colr_str_replace_all (const char *restrict s, const char *restrict target, const char *restrict repl)
 Replaces the first substring found in a string (char*). More...
 
char * colr_str_replace_all_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl)
 Replace all substrings in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_all_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl)
 Replace all substrings in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_all_ColorText (const char *restrict s, const char *restrict target, ColorText *repl)
 Replace all substrings in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_cnt (const char *restrict s, const char *restrict target, const char *restrict repl, int count)
 Replaces one or more substrings in a string (char*). More...
 
char * colr_str_replace_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl)
 Replace a substring in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl)
 Replace a substring in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_ColorText (const char *restrict s, const char *restrict target, ColorText *repl)
 Replace a substring in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags)
 Replaces a substring from a regex pattern string (char*) in a string (char*). More...
 
char * colr_str_replace_re_all (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags)
 Replaces all substrings from a regex pattern string (char*) in a string (char*). More...
 
char * colr_str_replace_re_all_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags)
 Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_all_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags)
 Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_all_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags)
 Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags)
 Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags)
 Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags)
 Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re_match (const char *restrict s, regmatch_t *match, const char *restrict repl)
 Replaces substrings from a single regex match (regmatch_t*) in a string (char*). More...
 
char * colr_str_replace_re_match_ColorArg (const char *restrict s, regmatch_t *match, ColorArg *repl)
 Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_match_ColorResult (const char *restrict s, regmatch_t *match, ColorResult *repl)
 Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_match_ColorText (const char *restrict s, regmatch_t *match, ColorText *repl)
 Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re_match_i (const char *restrict ref, char *target, regmatch_t *match, const char *restrict repl)
 Replaces substrings from a regex match (regmatch_t*) in a string (char*). More...
 
char * colr_str_replace_re_matches (const char *restrict s, regmatch_t **matches, const char *restrict repl)
 Replaces substrings from an array of regex match (regmatch_t*) in a string (char*). More...
 
char * colr_str_replace_re_matches_ColorArg (const char *restrict s, regmatch_t **matches, ColorArg *repl)
 Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_matches_ColorResult (const char *restrict s, regmatch_t **matches, ColorResult *repl)
 Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_matches_ColorText (const char *restrict s, regmatch_t **matches, ColorText *repl)
 Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re_pat (const char *restrict s, regex_t *repattern, const char *restrict repl)
 Replaces regex patterns in a string (char*). More...
 
char * colr_str_replace_re_pat_all (const char *restrict s, regex_t *repattern, const char *restrict repl)
 Replaces all matches to a regex pattern in a string (char*). More...
 
char * colr_str_replace_re_pat_all_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl)
 Replace all matches to a regex pattern in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_pat_all_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl)
 Replace all matches to a regex pattern in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_pat_all_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl)
 Replace all matches to a regex pattern in a string (char*) with a ColorText's string result. More...
 
char * colr_str_replace_re_pat_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl)
 Replace regex patterns in a string (char*) with a ColorArg's string result. More...
 
char * colr_str_replace_re_pat_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl)
 Replace regex patterns in a string (char*) with a ColorResult's string result. More...
 
char * colr_str_replace_re_pat_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl)
 Replace regex patterns in a string (char*) with a ColorText's string result. More...
 
char * colr_str_repr (const char *s)
 Convert a string (char*) into a representation of a string, by wrapping it in quotes and escaping characters that need escaping. More...
 
char * colr_str_rjust (const char *s, int width, const char padchar)
 Right-justifies a string (char*), ignoring escape codes when measuring the width. More...
 
bool colr_str_starts_with (const char *restrict s, const char *restrict prefix)
 Checks a string (char*) for a certain prefix substring. More...
 
char * colr_str_strip_codes (const char *s)
 Strips escape codes from a string (char*), resulting in a new allocated string. More...
 
char * colr_str_to_lower (const char *s)
 Allocate a new lowercase version of a string (char*). More...
 
bool colr_supports_rgb (void)
 Determine whether the current environment support RGB (True Colors). More...
 
bool colr_supports_rgb_static (void)
 Same as colr_supports_rgb(), but the environment is only checked on the first call. More...
 
TermSize colr_term_size (void)
 Attempts to retrieve the row/column size of the terminal and returns a TermSize. More...
 
struct winsize colr_win_size (void)
 Attempts to retrieve a winsize struct from an ioctl call. More...
 
struct winsize colr_win_size_env (void)
 Get window/terminal size using the environment variables LINES, COLUMNS, or COLS. More...
 
bool ExtendedValue_eq (ExtendedValue a, ExtendedValue b)
 Compares two ExtendedValues. More...
 
int ExtendedValue_from_BasicValue (BasicValue bval)
 Convert a BasicValue into an ExtendedValue. More...
 
int ExtendedValue_from_esc (const char *s)
 Convert an escape-code string (char*) to an ExtendedValue. More...
 
int ExtendedValue_from_hex (const char *hexstr)
 Create an ExtendedValue from a hex string (char*). More...
 
ExtendedValue ExtendedValue_from_hex_default (const char *hexstr, ExtendedValue default_value)
 Create an ExtendedValue from a hex string (char*), but return a default value if the hex string is invalid. More...
 
ExtendedValue ExtendedValue_from_RGB (RGB rgb)
 Convert an RGB value into the closest matching ExtendedValue. More...
 
int ExtendedValue_from_str (const char *arg)
 Converts a known name, integer string (0-255), or a hex string (char*), into an ExtendedValue suitable for the extended-value-based functions. More...
 
bool ExtendedValue_is_invalid (int eval)
 Determines whether an integer is an invalid ExtendedValue. More...
 
bool ExtendedValue_is_valid (int eval)
 Determines whether an integer is a valid ExtendedValue. More...
 
char * ExtendedValue_repr (int eval)
 Creates a string (char*) representation of a ExtendedValue. More...
 
char * ExtendedValue_to_str (ExtendedValue eval)
 Creates a human-friendly string (char*) from an ExtendedValue's actual value, suitable for use with ExtendedValue_from_str(). More...
 
void format_bg (char *out, BasicValue value)
 Create an escape code for a background color. More...
 
void format_bg_RGB (char *out, RGB rgb)
 Create an escape code for a true color (rgb) background color using values from an RGB struct. More...
 
void format_bg_RGB_term (char *out, RGB rgb)
 Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More...
 
void format_bgx (char *out, unsigned char num)
 Create an escape code for an extended background color. More...
 
void format_fg (char *out, BasicValue value)
 Create an escape code for a fore color. More...
 
void format_fg_RGB (char *out, RGB rgb)
 Create an escape code for a true color (rgb) fore color using an RGB struct's values. More...
 
void format_fg_RGB_term (char *out, RGB rgb)
 Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More...
 
void format_fgx (char *out, unsigned char num)
 Create an escape code for an extended fore color. More...
 
void format_style (char *out, StyleValue style)
 Create an escape code for a style. More...
 
char * rainbow_bg (const char *s, double freq, size_t offset, size_t spread)
 Rainbow-ize some text using rgb back colors, lolcat style. More...
 
char * rainbow_bg_term (const char *s, double freq, size_t offset, size_t spread)
 This is exactly like rainbow_bg(), except it uses colors that are closer to the standard 256-color values. More...
 
char * rainbow_fg (const char *s, double freq, size_t offset, size_t spread)
 Rainbow-ize some text using rgb fore colors, lolcat style. More...
 
char * rainbow_fg_term (const char *s, double freq, size_t offset, size_t spread)
 This is exactly like rainbow_fg(), except it uses colors that are closer to the standard 256-color values. More...
 
RGB rainbow_step (double freq, size_t offset)
 A single step in rainbow-izing produces the next color in the "rainbow" as an RGB value. More...
 
unsigned char RGB_average (RGB rgb)
 Return the average for an RGB value. More...
 
bool RGB_eq (RGB a, RGB b)
 Compare two RGB structs. More...
 
RGB RGB_from_BasicValue (BasicValue bval)
 Return an RGB value from a known BasicValue. More...
 
int RGB_from_esc (const char *s, RGB *rgb)
 Convert an escape-code string (char*) to an actual RGB value. More...
 
RGB RGB_from_ExtendedValue (ExtendedValue eval)
 Return an RGB value from a known ExtendedValue. More...
 
int RGB_from_hex (const char *hexstr, RGB *rgb)
 Convert a hex color into an RGB value. More...
 
RGB RGB_from_hex_default (const char *hexstr, RGB default_value)
 Convert a hex color into an RGB value, but use a default value when errors occur. More...
 
int RGB_from_str (const char *arg, RGB *rgb)
 Convert an RGB string (char*) into an RGB value. More...
 
RGB RGB_grayscale (RGB rgb)
 Return a grayscale version of an RGB value. More...
 
RGB RGB_inverted (RGB rgb)
 Make a copy of an RGB value, with the colors "inverted" (like highlighting text in the terminal). More...
 
RGB RGB_monochrome (RGB rgb)
 Convert an RGB value into either black or white, depending on it's average grayscale value. More...
 
char * RGB_repr (RGB rgb)
 Creates a string (char*) representation for an RGB value. More...
 
char * RGB_to_hex (RGB rgb)
 Converts an RGB value into a hex string (char*). More...
 
char * RGB_to_str (RGB rgb)
 Convert an RGB value into a human-friendly RGB string (char*) suitable for input to RGB_from_str(). More...
 
RGB RGB_to_term_RGB (RGB rgb)
 Convert an RGB value into it's nearest terminal-friendly RGB value. More...
 
bool StyleValue_eq (StyleValue a, StyleValue b)
 Compares two StyleValues. More...
 
StyleValue StyleValue_from_esc (const char *s)
 Convert an escape-code string (char*) to an actual StyleValue enum value. More...
 
StyleValue StyleValue_from_str (const char *arg)
 Convert a named argument to actual StyleValue enum value. More...
 
bool StyleValue_is_invalid (StyleValue sval)
 Determines whether a StyleValue is invalid. More...
 
bool StyleValue_is_valid (StyleValue sval)
 Determines whether a StyleValue is valid. More...
 
char * StyleValue_repr (StyleValue sval)
 Creates a string (char*) representation of a StyleValue. More...
 
char * StyleValue_to_str (StyleValue sval)
 Create a human-friendly string (char*) representation for a StyleValue. More...
 
char * TermSize_repr (TermSize ts)
 Create a string (char*) representation for a TermSize. More...
 

Variables

const BasicInfo basic_names []
 An array of BasicInfo items, used with BasicValue_from_str(). More...
 
const size_t basic_names_len = (sizeof(basic_names) / sizeof(basic_names[0])) - 1
 Length of usable values basic_names.
 
const ColorNameData colr_name_data []
 An array that holds a known color name, it's ExtendedValue, and it's RGB value.
 
const size_t colr_name_data_len = sizeof(colr_name_data) / sizeof(colr_name_data[0])
 Length of colr_name_data.
 
int colr_printf_esc_mod = 0
 Integer to test for the presence of the "escaped output modifier" in colr_printf_handler. More...
 
const RGB ext2rgb_map []
 A map from ExtendedValue (256-color) to RGB value, where the index is the is the ExtendedValue, and the value is the RGB. More...
 
const size_t ext2rgb_map_len = sizeof(ext2rgb_map) / sizeof(ext2rgb_map[0])
 Length of ext2rgb_map (should always be 256).
 
const ExtendedInfo extended_names []
 An array of ExtendedInfo, used with ExtendedValue_from_str(). More...
 
const size_t extended_names_len = (sizeof(extended_names) / sizeof(extended_names[0])) - 1
 Length of usable values in extended_names.
 
const StyleInfo style_names []
 An array of StyleInfo items, used with StyleName_from_str(). More...
 
const size_t style_names_len = (sizeof(style_names) / sizeof(style_names[0])) - 1
 Length of usable values in style_names.
 

Detailed Description

Implements everything in the colr.h header.

Function Documentation

◆ _colr_free()

void _colr_free ( void *  p)

Calls Colr *_free() functions for Colr objects, otherwise just calls free().

You should use the colr_free() macro instead.

Warning
This is for internal use only.
Parameters
[in]pPointer to a heap-allocated object.

◆ _colr_is_last_arg()

bool _colr_is_last_arg ( void *  p)

Determines if a void pointer is _ColrLastArg (the last-arg-marker).

Warning
This is for internal use only.
Parameters
[in]pThe pointer to check.
Returns
true if the pointer is _ColrLastArg, otherwise false.

◆ _colr_join()

char* _colr_join ( void *  joinerp,
  ... 
)

Joins ColorArgs, ColorTexts, and strings (char*) into one long string separated by it's first argument.

This will free() any ColorArgs, ColorResults, or ColorTexts that are passed in. It is backing the colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros, and enables easy throw-away color values.

Any plain strings that are passed in are left alone. It is up to the caller to free those. ColrC only manages the temporary Colr-based objects needed to build up these strings.

You should use colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros instead.

Warning
This is for internal use only.
Parameters
[in]joinerpThe joiner (any ColorArg, ColorResult, ColorText, or string).
[in]...Zero or more ColorArgs, ColorResults, ColorTexts, or strings to join by the joiner.
Returns

An allocated string with mixed escape codes/strings. CODE_RESET_ALL is appended to all ColorText arguments. This allows easy part-colored messages.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned. Also, NULL will be returned if joinerp is NULL.

◆ _colr_join_array_length()

size_t _colr_join_array_length ( void *  ps)

Determine the length of a NULL-terminated array of strings (char*), ColorArgs, ColorResults, or ColorTexts.

Warning
This is for internal use only.
Parameters
[in]psA NULL-terminated array of ColorArgs, ColorResults, ColorTexts, or strings (char*).
Returns
The number of items (before NULL) in the array.

Referenced by colr_join_array().

◆ _colr_join_arrayn_size()

size_t _colr_join_arrayn_size ( void *  joinerp,
void *  ps,
size_t  count 
)

Get the size in bytes needed to join an array of strings (char*), ColorArgs, ColorResults, or ColorTexts by another string (char*), ColorArg, ColorResult, or ColorText.

This is used to allocate memory in the colr_join_array() function.

Warning
This is for internal use only.
Parameters
[in]joinerpThe joiner (any ColorArg, ColorResult, ColorText, or string).
[in]psAn array of pointers to ColorArgs, ColorResults, ColorTexts, or strings. The array must have NULL as the last item if count is greater than the total number of items.
[in]countTotal number of items in the array.
Returns
The number of bytes needed to allocate the result of colr_join_arrayn(), possibly 0.
See also
colr
colr_join
colr_join_array

Referenced by colr_join_arrayn().

◆ _colr_join_size()

size_t _colr_join_size ( void *  joinerp,
va_list  args 
)

Parse arguments, just as in _colr_join(), but only return the size needed to allocate the resulting string.

This allows _colr_join() to allocate once, instead of reallocating for each argument that is passed.

Warning
This is for internal use only.
Parameters
[in]joinerpThe joiner (any ColorArg, ColorText, or string (char*)).
[in]argsA va_list with zero or more ColorArgs, ColorTexts, or strings (char*) to join.
Returns
The length (in bytes) needed to allocate a string built with _colr_cat(). This function will return 0 if joinerp is NULL/empty). Except for 0, it will never return anything less than CODE_RESET_LEN.
See also
_colr

Referenced by _colr_join().

◆ _colr_ptr_length()

size_t _colr_ptr_length ( void *  p)

Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char*) into a string.

This is used in the variadic _colr* functions.

Warning
This is for internal use only.
Parameters
[in]pA ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char*).
Returns
The length needed to convert the object into a string (strlen() + 1 for strings).

Referenced by _colr_join_arrayn_size(), and _colr_join_size().

◆ _colr_ptr_repr()

char* _colr_ptr_repr ( void *  p)

Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obtain an allocated string representation.

You should use colr_repr() instead.

Warning
This is for internal use only.
Parameters
[in]pA ColorArg pointer, ColorResult pointer, ColorText pointer, or string.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_repr

◆ _colr_ptr_to_str()

char* _colr_ptr_to_str ( void *  p)

Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to obtain an allocated string.

Warning
This is for internal use only.
Parameters
[in]pA ColorArg pointer, ColorResult pointer, ColorText pointer, or string.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ _rainbow()

char* _rainbow ( RGB_fmter  fmter,
const char *  s,
double  freq,
size_t  offset,
size_t  spread 
)

Handles multibyte character string (char*) conversion and character iteration for all of the rainbow_ functions.

Warning
This is for internal use only.
Parameters
[in]fmterA formatter function (RGB_fmter) that can create escape codes from RGB values.
[in]s

The string to "rainbowize".

Input must be null-terminated.

[in]freqThe "tightness" for colors.
[in]offsetThe starting offset into the rainbow.
[in]spreadNumber of characters per color.
Returns

An allocated string (char*) with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Referenced by rainbow_bg(), rainbow_bg_term(), rainbow_fg(), and rainbow_fg_term().

◆ ArgType_eq()

bool ArgType_eq ( ArgType  a,
ArgType  b 
)

Compares two ArgTypes.

This is used to implement colr_eq().

Parameters
[in]aThe first ArgType to compare.
[in]bThe second ArgType to compare.
Returns
true if they are equal, otherwise false.

◆ ArgType_repr()

char* ArgType_repr ( ArgType  type)

Creates a string (char*) representation of a ArgType.

Parameters
[in]typeAn ArgType to get the type from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ArgType

Referenced by ColorArg_repr().

◆ ArgType_to_str()

char* ArgType_to_str ( ArgType  type)

Creates a human-friendly string (char*) from an ArgType.

Parameters
[in]typeAn ArgType to get the type from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ArgType

Referenced by ColorArg_example().

◆ BasicValue_eq()

bool BasicValue_eq ( BasicValue  a,
BasicValue  b 
)

Compares two BasicValues.

This is used to implement colr_eq().

Parameters
[in]aThe first BasicValue to compare.
[in]bThe second BasicValue to compare.
Returns
true if they are equal, otherwise false.
See also
BasicValue

◆ BasicValue_from_esc()

BasicValue BasicValue_from_esc ( const char *  s)

Convert an escape-code string (char*) to an actual BasicValue enum value.

Parameters
[in]s

Escape-code string.

Must be null-terminated.

Return values
BasicValuevalue on success.
BASIC_INVALIDon error (or if s is NULL).
BASIC_INVALID_RANGEif the code number was outside of the range 0-255.
See also
BasicValue

◆ BasicValue_from_str()

BasicValue BasicValue_from_str ( const char *  arg)

Convert named argument to an actual BasicValue enum value.

Parameters
[in]argColor name to find the BasicValue for.
Returns
BasicValue value on success, or BASIC_INVALID on error.
See also
BasicValue

◆ BasicValue_is_invalid()

bool BasicValue_is_invalid ( BasicValue  bval)

Determines whether a BasicValue is invalid.

Parameters
[in]bvalA BasicValue to check.
Returns
true if the value is considered invalid, otherwise false.
See also
BasicValue

Referenced by ExtendedValue_from_BasicValue().

◆ BasicValue_is_valid()

bool BasicValue_is_valid ( BasicValue  bval)

Determines whether a BasicValue is valid.

Parameters
[in]bvalA BasicValue to check.
Returns
true if the value is considered valid, otherwise false.
See also
BasicValue

◆ BasicValue_repr()

char* BasicValue_repr ( BasicValue  bval)

Creates a string (char*) representation of a BasicValue.

Parameters
[in]bvalA BasicValue to get the value from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
BasicValue

◆ BasicValue_to_ansi()

int BasicValue_to_ansi ( ArgType  type,
BasicValue  bval 
)

Converts a fore/back BasicValue to the actual ansi code number.

Parameters
[in]typeArgType (FORE/BACK).
[in]bvalBasicValue to convert.
Returns
An integer usable with basic escape code fore/back colors.
See also
BasicValue

Referenced by format_bg(), and format_fg().

◆ BasicValue_to_str()

char* BasicValue_to_str ( BasicValue  bval)

Create a human-friendly string (char*) representation for a BasicValue.

Parameters
[in]bvalBasicValue to get the name for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
BasicValue

◆ ColorArg_empty()

ColorArg ColorArg_empty ( void  )

Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE.

This is used to pass "empty" fore/back/style args to the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, where NULL may have a different meaning for users of the ColorArg.

Returns
(ColorArg){.type=ARGTYPE_NONE, .value.type=TYPE_NONE}
See also
ColorArg_is_empty
ColorValue_empty

◆ ColorArg_eq()

bool ColorArg_eq ( ColorArg  a,
ColorArg  b 
)

Compares two ColorArg structs.

They are considered "equal" if their .type and .value match.

Parameters
[in]aFirst ColorArg to compare.
[in]bSecond ColorArg to compare.
Returns
true if they are equal, otherwise false.
See also
ColorArg

Referenced by ColorText_has_arg().

◆ ColorArg_example()

char* ColorArg_example ( ColorArg  carg,
bool  colorized 
)

Create a string (char*) representation of a ColorArg with a stylized type/name using escape codes built from the ColorArg's values.

Parameters
[in]cargA ColorArg to get an example string for.
[in]colorizedWhether to include a colorized example. If set to false, there will be no escape-codes in the string.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorArg
◆  ColorArg_example example:
ColorArg args[] = {
fore_arg(rgb(75, 25, 155)),
fore_arg(ext_hex("#ff00bb")),
back_arg(RED),
style_arg(UNDERLINE),
fore_arg("NOT_VALID"),
back_arg("NOT_VALID"),
style_arg("NOT_VALID")
};
size_t arg_len = sizeof(args) / sizeof(args[0]);
for (size_t i = 0; i < arg_len; i++) {
char* example = ColorArg_example(args[i], true);
if (!example) continue;
printf("%s\n", example);
free(example);
}

◆ ColorArg_free()

void ColorArg_free ( ColorArg p)

Free allocated memory for a ColorArg.

This has no advantage over free(colorarg) right now, it is used in debugging, and may be extended in the future. It's better just to use it (or the colr_free() macro).

Parameters
[in]pColorArg to free.
See also
ColorArg

Referenced by _colr_free(), _colr_join(), ColorText_free_args(), colr_printf_handler(), colr_str_replace_all_ColorArg(), colr_str_replace_ColorArg(), colr_str_replace_re_all_ColorArg(), colr_str_replace_re_ColorArg(), colr_str_replace_re_match_ColorArg(), colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_pat_all_ColorArg(), and colr_str_replace_re_pat_ColorArg().

◆ ColorArg_from_BasicValue()

ColorArg ColorArg_from_BasicValue ( ArgType  type,
BasicValue  value 
)

Explicit version of ColorArg_from_value that only handles BasicValues.

This is used in some macros to aid in dynamic escape code creation.

Parameters
[in]typeArgType (FORE, BACK, STYLE).
[in]valueBasicValue to use.
Returns
A ColorArg, with the .value.type member possibly set to TYPE_INVALID.
See also
ColorArg

◆ ColorArg_from_esc()

ColorArg ColorArg_from_esc ( const char *  s)

Parse an escape-code string (char*) into a ColorArg.

For malformed escape-codes the .type member will be ARGTYPE_NONE, and the .value.type member will be set to TYPE_INVALID. This means that ColorArg_is_invalid(carg) == true.

Parameters
[in]sThe escape code to parse. It must not have extra characters.
Returns
An initialized ColorArg, possibly invalid.
See also
ColorArg
colr_str_get_codes
ColorValue_from_esc
BasicValue_from_esc
ExtendedValue_from_esc
StyleValue_from_esc
RGB_from_esc

Referenced by ColorArgs_from_str().

◆ ColorArg_from_ExtendedValue()

ColorArg ColorArg_from_ExtendedValue ( ArgType  type,
ExtendedValue  value 
)

Explicit version of ColorArg_from_value that only handles ExtendedValues.

This is used in some macros to aid in dynamic escape code creation.

Parameters
[in]typeArgType (FORE, BACK, STYLE).
[in]valueExtendedValue to use.
Returns
A ColorArg, with the .value.type member possibly set to TYPE_INVALID.
See also
ColorArg

◆ ColorArg_from_RGB()

ColorArg ColorArg_from_RGB ( ArgType  type,
RGB  value 
)

Explicit version of ColorArg_from_value that only handles RGB structs.

This is used in some macros to aid in dynamic escape code creation.

Parameters
[in]typeArgType (FORE, BACK, STYLE).
[in]valueRGB struct to use.
Returns
A ColorArg, with the .value.type member possibly set to TYPE_INVALID.
See also
ColorArg

◆ ColorArg_from_str()

ColorArg ColorArg_from_str ( ArgType  type,
const char *  colorname 
)

Build a ColorArg (fore, back, or style value) from a known color name/style.

The .value.type attribute can be checked for an invalid type, or you can call ColorArg_is_invalid(x).

Parameters
[in]typeArgType (FORE, BACK, STYLE).
[in]colornameA known color name/style.
Returns
A ColorArg struct with usable values.
See also
ColorArg

◆ ColorArg_from_StyleValue()

ColorArg ColorArg_from_StyleValue ( ArgType  type,
StyleValue  value 
)

Explicit version of ColorArg_from_value that only handles StyleValues.

This is used in some macros to aid in dynamic escape code creation.

Parameters
[in]typeArgType (FORE, BACK, STYLE).
[in]valueStyleValue to use.
Returns
A ColorArg, with the .value.type member possibly set to TYPE_INVALID.
See also
ColorArg

◆ ColorArg_from_value()

ColorArg ColorArg_from_value ( ArgType  type,
ColorType  colrtype,
void *  p 
)

Used with the color_arg macro to dynamically create a ColorArg based on it's argument type.

Parameters
[in]typeArgType value, to mark the type of ColorArg.
[in]colrtypeColorType value, to mark the type of ColorValue.
[in]pA pointer to either a BasicValue, ExtendedValue, or a RGB.
Returns
A ColorArg struct with the appropriate .value.type member set for the value that was passed. For invalid types the .value.type member may be set to one of:
  • TYPE_INVALID
  • TYPE_INVALID_EXT_RANGE
  • TYPE_INVALID_RGB_RANGE
See also
ColorArg

◆ ColorArg_is_empty()

bool ColorArg_is_empty ( ColorArg  carg)

Checks to see if a ColorArg is an empty placeholder.

A ColorArg is empty if it's .type is set to ARGTYPE_NONE.

Parameters
[in]cargA ColorArg to check.
Returns
true if the ColorArg is considered "empty", otherwise false.

Referenced by ColorArg_length(), ColorArg_to_esc(), ColorArg_to_esc_s(), ColorText_has_args(), and ColorText_to_str().

◆ ColorArg_is_invalid()

bool ColorArg_is_invalid ( ColorArg  carg)

Checks to see if a ColorArg holds an invalid value.

Parameters
[in]cargColorArg struct to check.
Returns
true if the value is invalid, otherwise false.
See also
ColorArg

◆ ColorArg_is_ptr()

bool ColorArg_is_ptr ( void *  p)

Checks a void pointer to see if it contains a ColorArg struct.

The first member of a ColorArg is a marker.

Parameters
[in]pA void pointer to check.
Returns
true if the pointer is a ColorArg, otherwise false.
See also
ColorArg

Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), ColorText_from_valuesv(), ColorText_set_values(), colr_is_colr_ptr(), colr_join_arrayn(), and colr_printf_handler().

◆ ColorArg_is_valid()

bool ColorArg_is_valid ( ColorArg  carg)

Checks to see if a ColorArg holds a valid value.

Parameters
[in]cargColorArg struct to check.
Returns
true if the value is valid, otherwise false.
See also
ColorArg

◆ ColorArg_length()

size_t ColorArg_length ( ColorArg  carg)

Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc().

Parameters
[in]cargColorArg to use.
Returns
The length (size_t) needed to allocate a ColorArg's string, or 1 (size of an empty string) for invalid/empty arg types/values.
See also
ColorArg

Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_length().

◆ ColorArg_repr()

char* ColorArg_repr ( ColorArg  carg)

Creates a string (char*) representation for a ColorArg.

Allocates memory for the string representation.

Parameters
[in]cargColorArg struct to get the representation for.
Returns

Allocated string for the representation.

You must free() the memory allocated by this function.

See also
ColorArg

Referenced by _colr_ptr_repr(), and ColorText_repr().

◆ ColorArg_to_esc()

char* ColorArg_to_esc ( ColorArg  carg)

Converts a ColorArg into an escape code string (char*).

Allocates memory for the string.

If the ColorArg is empty (ARGTYPE_NONE), an empty string is returned.

If the ColorValue is invalid, an empty string is returned. You must still free the empty string.

Parameters
[in]cargColorArg to get the ArgType and ColorValue from.
Returns

Allocated string for the escape code.

You must free() the memory allocated by this function. If the ColorArg is considered "empty", or the ColorValue is invalid, then NULL is returned.

See also
ColorArg

Referenced by _colr_join(), _colr_ptr_to_str(), ColorText_to_str(), colr_join_arrayn(), colr_printf_handler(), colr_str_replace_all_ColorArg(), colr_str_replace_ColorArg(), colr_str_replace_re_all_ColorArg(), colr_str_replace_re_ColorArg(), colr_str_replace_re_match_ColorArg(), colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_pat_all_ColorArg(), and colr_str_replace_re_pat_ColorArg().

◆ ColorArg_to_esc_s()

bool ColorArg_to_esc_s ( char *  dest,
ColorArg  carg 
)

Converts a ColorArg into an escape code string (char*) and fills the destination string.

If the ColorArg is empty (ARGTYPE_NONE), dest[0] is set to `'\0'`.

If the ColorValue is invalid, dest[0] is set to `'\0'`.

Parameters
[in]destDestination for the escape code string. Must have room for the code type being used. See ColorArg_length() for determining the size needed.
[in]cargColorArg to get the ArgType and ColorValue from.
Returns
true if the ColorArg was valid, otherwise false.
See also
ColorArg

Referenced by colr_str_has_ColorArg().

◆ ColorArg_to_ptr()

ColorArg* ColorArg_to_ptr ( ColorArg  carg)

Copies a ColorArg into memory and returns the pointer.

You must free() the memory if you call this directly.

Parameters
[in]cargColorArg to copy/allocate for.
Returns

Pointer to a heap-allocated ColorArg.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorArg

Referenced by ColorArgs_from_str().

◆ ColorArgs_array_free()

void ColorArgs_array_free ( ColorArg **  ps)

Free an allocated array of ColorArgs, including the array itself.

Each individual ColorArg will be released, and finally the allocated memory for the array of pointers will be released.

Parameters
[in]psA pointer to an array of ColorArgs, where NULL is the last item.
◆  ColorArgs_array_free example:
char* s = colr("Test", fore(RED), back(WHITE), style(BRIGHT));
if (!s) exit(1);
// Call something that creates an array of ColorArgs on the heap.
ColorArg** carg_array = ColorArgs_from_str(s, false);
free(s);
if (!carg_array) exit(1);
// ... do something with the array of ColorArgs.
// And then free it:

◆ ColorArgs_array_repr()

char* ColorArgs_array_repr ( ColorArg **  lst)

Creates a string representation for an array of ColorArg pointers.

Parameters
[in]lstThe ColorArg array to create the representation for (ColorArg**).
Returns
An allocated string, or NULL if lst is NULL, or the allocation fails.
◆  ColorArgs_array_repr example:
char* s = colr("Test", fore(RED), back(WHITE), style(BRIGHT));
if (!s) exit(1);
// Call something that creates an array of ColorArgs on the heap.
ColorArg** carg_array = ColorArgs_from_str(s, false);
free(s);
if (!carg_array) exit(1);
char* lst_repr = ColorArgs_array_repr(carg_array);
if (!lst_repr) exit(1);
printf("ColorArg carg_array[] = %s\n", lst_repr);
// And then free it:
free(lst_repr);

◆ ColorArgs_from_str()

ColorArg** ColorArgs_from_str ( const char *  s,
bool  unique 
)

Create an array of ColorArgs from escape-codes found in a string (char*).

This uses ColorArg_from_esc() and colr_str_get_codes() to build a heap-allocated array of heap-allocated ColorArgs.

Parameters
[in]s

A string to get the escape-codes from.

Must be null-terminated.

[in]uniqueWhether to only include unique ColorArgs.
Returns

An allocated array of ColorArg pointers, where the last element is NULL.

You must free() the memory allocated by this function.

Return values
Ifs is NULL, or empty, or there are otherwise no escape-codes found in the string, then NULL is returned.
Onsuccess, there will be at least two pointers behind the return value. The last pointer is always NULL.
◆  ColorArgs_from_str example:
#include <stdio.h>
#include "colr.h"
int main(void) {
char* s = colr_cat(
Colr("Testing this out.", fore(RED), back(WHITE)),
Colr("Again.", fore(RED), style(UNDERLINE))
);
if (!s) return EXIT_FAILURE;
ColorArg** carg_array = ColorArgs_from_str(s, false);
free(s);
if (!carg_array) {
fprintf(stderr, "No code found? Impossible!\n");
return EXIT_FAILURE;
}
// Iterate over the ColorArg array.
for (size_t i = 0; carg_array[i]; i++) {
char* carg_example = ColorArg_example(*(carg_array[i]), true);
if (!carg_example) continue;
printf("%s\n", carg_example);
free(carg_example);
}
// Free the ColorArgs, and the array of pointers.
ColorArgs_array_free(carg_array);
}

◆ ColorJustify_empty()

ColorJustify ColorJustify_empty ( void  )

Creates an "empty" ColorJustify, with JUST_NONE set.

Returns
An initialized ColorJustify, with no justification method set.
See also
ColorJustify

Referenced by ColorText_empty().

◆ ColorJustify_eq()

bool ColorJustify_eq ( ColorJustify  a,
ColorJustify  b 
)

Compares two ColorJustify structs.

They are considered "equal" if their member values match.

Parameters
[in]aFirst ColorJustify to compare.
[in]bSecond ColorJustify to compare.
Returns
true if they are equal, otherwise false.
See also
ColorJustify

◆ ColorJustify_is_empty()

bool ColorJustify_is_empty ( ColorJustify  cjust)

Checks to see if a ColorJustify is "empty".

A ColorJustify is considered "empty" if the .method member is set to JUST_NONE.

Parameters
[in]cjustThe ColorJustify to check.
Returns
true if the ColorJustify is empty, otherwise false.
See also
ColorJustify
ColorJustify_empty

Referenced by ColorText_is_empty(), and ColorText_length().

◆ ColorJustify_new()

ColorJustify ColorJustify_new ( ColorJustifyMethod  method,
int  width,
char  padchar 
)

Creates a ColorJustify.

This is used to ensure every ColorJustify has it's .marker member set correctly.

Parameters
[in]methodColorJustifyMethod to use.
[in]widthWidth for justification. If 0 is given, ColorText will use the width from colr_term_size().
[in]padcharPadding character to use. If 0 is given, the default, space (`' '`), is used.
Returns
An initialized ColorJustify.

Referenced by ColorText_set_center(), ColorText_set_ljust(), and ColorText_set_rjust().

◆ ColorJustify_repr()

char* ColorJustify_repr ( ColorJustify  cjust)

Creates a string (char*) representation for a ColorJustify.

Allocates memory for the string representation.

Parameters
[in]cjustColorJustify struct to get the representation for.
Returns

Allocated string for the representation.

You must free() the memory allocated by this function.

See also
ColorJustify

Referenced by ColorText_repr().

◆ ColorJustifyMethod_repr()

char* ColorJustifyMethod_repr ( ColorJustifyMethod  meth)

Creates a string (char*) representation for a ColorJustifyMethod.

Allocates memory for the string representation.

Parameters
[in]methColorJustifyMethod to get the representation for.
Returns

Allocated string for the representation.

You must free() the memory allocated by this function.

See also
ColorJustifyMethod

Referenced by ColorJustify_repr().

◆ ColorResult_center()

ColorResult* ColorResult_center ( ColorResult cres,
int  width,
char  padchar 
)

Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").

Parameters
[in]cresA ColorResult pointer to center. It will be free'd after this.
[in]widthMaximum width in characters, or 0 for current terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

Referenced by Colr_center_char().

◆ ColorResult_Colr()

ColorResult* ColorResult_Colr ( ColorResult cres,
  ... 
)

Colorize a ColorResult, and return a new allocated ColorResult.

This is like ColorText_from_value(), except it accepts an allocated ColorResult as the first argument.

Parameters
[in]cresAn allocated ColorResult to colorize. This will be released to create the new ColorResult.
[in]...One or more fore(), back(), or style() arguments (ColorArgs). The last argument must be _ColrLastArg. The allocated ColorArgs will be free()'d.
Returns

An allocated ColorResult, or NULL if cres is NULL.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

◆ ColorResult_empty()

ColorResult ColorResult_empty ( void  )

Creates a ColorResult with .result=NULL and .length=-1, with the appropriate struct marker.

Returns
An "empty" (initialized) ColorResult.
See also
ColorResult

Referenced by ColorResult_from_stra(), and ColorResult_new().

◆ ColorResult_eq()

bool ColorResult_eq ( ColorResult  a,
ColorResult  b 
)

Compares two ColorResults.

They are equal if all of their members are equal, excluding the memory address for the .result member.

Parameters
[in]aFirst ColorResult to compare.
[in]bSecond ColorResult to compare.
Returns
true if they are equal, otherwise false.
See also
ColorResult

◆ ColorResult_free()

◆ ColorResult_from_str()

ColorResult ColorResult_from_str ( const char *  s)

Allocates a copy of a string, and creates a ColorResult from it.

Parameters
[in]sThe string to copy.
Returns
An initialized ColorResult. The ColorResult may be "empty" if s is NULL.
See also
ColorResult

◆ ColorResult_from_stra()

ColorResult* ColorResult_from_stra ( const char *  s)

Allocates a copy of a string, and creates an allocated ColorResult from it.

Parameters
[in]sThe string to copy.
Returns

An allocated ColorResult. The ColorResult may be "empty" if s is NULL.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

Referenced by Colr_cursor_hide(), Colr_cursor_show(), Colr_erase_display(), Colr_erase_line(), Colr_move_return(), Colr_pos_restore(), and Colr_pos_save().

◆ ColorResult_is_empty()

bool ColorResult_is_empty ( ColorResult  cres)

Checks to see if a ColorResult is "empty" (NULL or empty string).

Parameters
[in]cresColorResult to check.
Returns
true if the ColorResult is "empty", otherwise false.

Referenced by ColorResult_center(), ColorResult_ljust(), and ColorResult_rjust().

◆ ColorResult_is_ptr()

bool ColorResult_is_ptr ( void *  p)

Checks a void pointer to see if it contains a ColorResult struct.

The first member of a ColorResult is a marker.

Parameters
[in]pA void pointer to check.
Returns
true if the pointer is a ColorResult, otherwise false.
See also
ColorResult

Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().

◆ ColorResult_length()

size_t ColorResult_length ( ColorResult  cres)

Return the length in bytes (including the null-terminator), that is needed to store the return from ColorResult_to_str() (.result).

Parameters
[in]cresA ColorResult to calculate the length for.
Returns
The length of a ColorResult, possibly 0 if .result is NULL.
See also
ColorResult

Referenced by _colr_join_arrayn_size(), and _colr_ptr_length().

◆ ColorResult_ljust()

ColorResult* ColorResult_ljust ( ColorResult cres,
int  width,
char  padchar 
)

Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").

Parameters
[in]cresA ColorResult pointer to center. It will be free'd after this.
[in]widthMaximum width in characters, or 0 for current terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

Referenced by Colr_ljust_char().

◆ ColorResult_new()

ColorResult ColorResult_new ( char *  s)

Initialize a new ColorResult with an allocated string (char*).

Parameters
[in]sAn allocated string to use for the .result member.
Returns
An initialized ColorResult. The ColorResult will be considered "empty" if s is NULL
See also
ColorResult

Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_str(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().

◆ ColorResult_repr()

char* ColorResult_repr ( ColorResult  cres)

Create a string representation for a ColorResult.

This happens to be the same as colr_str_repr(cres.result) right now.

Parameters
[in]cresA ColorResult to create the representation string for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorResult

Referenced by _colr_ptr_repr().

◆ ColorResult_rip_str()

char* ColorResult_rip_str ( ColorResult cres)

Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char*)).

Parameters
[in]cresColorResult to get the string from and free().
Returns

The string (char*) from the result member.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ ColorResult_rjust()

ColorResult* ColorResult_rjust ( ColorResult cres,
int  width,
char  padchar 
)

Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").

Parameters
[in]cresA ColorResult pointer to center. It will be free'd after this.
[in]widthMaximum width in characters, or 0 for current terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

Referenced by Colr_rjust_char().

◆ ColorResult_to_ptr()

ColorResult* ColorResult_to_ptr ( ColorResult  cres)

Allocate memory for a ColorResult, fill it, and return it.

This ensure the appropriate struct marker is set, for use with Colr.

Parameters
[in]cresA ColorResult to use.
Returns

An allocated ColorResult.

You must free() the memory allocated by this function.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

If allocation fails, NULL is returned.

See also
ColorResult

Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_stra(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().

◆ ColorResult_to_str()

char* ColorResult_to_str ( ColorResult  cres)

Convert a ColorResult into a string (char*).

This simply returns the .result member right now. It is used for compatibility with the colr_to_str() macro.

Parameters
[in]cresA ColorResult to use.
Returns
A stringified-version if this ColorResult, which happens to be the .result member. If you free the result of this function, the original string used to create the ColorResult will be lost.
See also
ColorResult

Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rjust(), colr_join_arrayn(), colr_printf_handler(), colr_str_replace_all_ColorResult(), colr_str_replace_ColorResult(), colr_str_replace_re_all_ColorResult(), colr_str_replace_re_ColorResult(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_ColorResult().

◆ ColorText_empty()

ColorText ColorText_empty ( void  )

Creates an "empty" ColorText with pointers set to NULL.

Returns
An initialized ColorText.
See also
ColorText

Referenced by ColorText_from_valuesv(), and ColorText_set_values().

◆ ColorText_free()

◆ ColorText_free_args()

void ColorText_free_args ( ColorText p)

Frees the ColorArg members of a ColorText.

The ColorText itself is not free'd.

This is safe to use on a stack-allocated ColorText with heap-allocated ColorArgs.

Parameters
[in]pPointer to a ColorText.
See also
ColorText

Referenced by ColorResult_Colr(), and ColorText_free().

◆ ColorText_from_values()

ColorText ColorText_from_values ( char *  text,
  ... 
)

Builds a ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs).

Parameters
[in]textText to colorize (a regular string).
[in]...ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you.
Returns
An initialized ColorText struct.
See also
ColorText

◆ ColorText_from_valuesv()

ColorText ColorText_from_valuesv ( char *  text,
va_list  args 
)

Builds a ColorText from 1 mandatory string (char*), and a va_list with optional fore, back, and style args (pointers to ColorArgs).

Parameters
[in]textText to colorize (a regular string).
[in]argsva_list with ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you, and should be used for basic text colorization.
Returns
An initialized ColorText struct.
See also
ColorText

Referenced by ColorResult_Colr(), and ColorText_from_values().

◆ ColorText_has_arg()

bool ColorText_has_arg ( ColorText  ctext,
ColorArg  carg 
)

Checks to see if a ColorText has a certain ColorArg value set.

Uses ColorArg_eq() to inspect the fore, back, and style members.

Parameters
[in]ctextThe ColorText to inspect.
[in]cargThe ColorArg to look for.
Returns
true if the fore, back, or style arg matches carg, otherwise false.
See also
ColorText

◆ ColorText_has_args()

bool ColorText_has_args ( ColorText  ctext)

Checks to see if a ColorText has any argument values set.

Parameters
[in]ctextA ColorText to check.
Returns
true if .fore, .back, or .style is set to a non-empty ColorArg, otherwise false.
See also
ColorText

◆ ColorText_is_empty()

bool ColorText_is_empty ( ColorText  ctext)

Checks to see if a ColorText has no usable values.

A ColorText is considered "empty" if the .text, .fore, .back, and .style pointers are NULL, and the .just member is set to an "empty" ColorJustify.

Parameters
[in]ctextThe ColorText to check.
Returns
true if the ColorText is empty, otherwise false.
See also
ColorText
ColorText_empty

◆ ColorText_is_ptr()

bool ColorText_is_ptr ( void *  p)

Checks a void pointer to see if it contains a ColorText struct.

The first member of a ColorText is a marker.

Parameters
[in]pA void pointer to check.
Returns
true if the pointer is a ColorText, otherwise false.
See also
ColorText

Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().

◆ ColorText_length()

size_t ColorText_length ( ColorText  ctext)

Returns the length in bytes needed to allocate a string (char*) built with ColorText_to_str() with the current text, fore, back, and style members.

Parameters
[in]ctextColorText to use.
Returns
The length (size_t) needed to allocate a ColorText's string, or 1 (size of an empty string) for invalid/empty arg types/values.
See also
ColorText

Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_to_str().

◆ ColorText_repr()

char* ColorText_repr ( ColorText  ctext)

Allocate a string (char*) representation for a ColorText.

Parameters
[in]ctextColorText to get the string representation for.
Returns
Allocated string for the ColorText.
See also
ColorText

Referenced by _colr_ptr_repr().

◆ ColorText_set_center()

ColorText* ColorText_set_center ( ColorText ctext,
int  width,
char  padchar 
)

Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string.

This is to facilitate the justification macros. You can create a justified ColorText using ColorText_center and friends.

Parameters
[out]ctextThe ColorText to set the justification method for.
[in]widthMaximum width for the justification.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns
The same pointer that was given as ctext.

Referenced by Colr_center_char().

◆ ColorText_set_just()

ColorText* ColorText_set_just ( ColorText ctext,
ColorJustify  cjust 
)

Set the ColorJustify method for a ColorText, and return the ColorText.

This is to facilitate the justification macros. If you already have a pointer to a ColorText, you can just do ctext->just = just;. The purpose of this is to allow ColorText_set_just(ColorText_to_ptr(...), ...) to work.

Parameters
[out]ctextThe ColorText to set the justification method for.
[in]cjustThe ColorJustify struct to use.
Returns
The same pointer that was given as ctext.
See also
ColorText

◆ ColorText_set_ljust()

ColorText* ColorText_set_ljust ( ColorText ctext,
int  width,
char  padchar 
)

Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string.

This is to facilitate the justification macros. You can create a justified ColorText using ColorText_ljust and friends.

Parameters
[out]ctextThe ColorText to set the justification method for.
[in]widthMaximum width for the justification.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns
The same pointer that was given as ctext.

Referenced by Colr_ljust_char().

◆ ColorText_set_rjust()

ColorText* ColorText_set_rjust ( ColorText ctext,
int  width,
char  padchar 
)

Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string.

This is to facilitate the justification macros. You can create a justified ColorText using ColorText_rjust and friends.

Parameters
[out]ctextThe ColorText to set the justification method for.
[in]widthMaximum width for the justification.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns
The same pointer that was given as ctext.

Referenced by Colr_rjust_char().

◆ ColorText_set_values()

void ColorText_set_values ( ColorText ctext,
char *  text,
  ... 
)

Initializes an existing ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs).

Parameters
[out]ctextA ColorText to initialize with values.
[in]textText to colorize (a regular string).
[in]...A va_list with ColorArgs pointers for fore, back, and style, in any order.
Returns
An initialized ColorText struct.
See also
ColorText

◆ ColorText_to_ptr()

ColorText* ColorText_to_ptr ( ColorText  ctext)

Copies a ColorText into allocated memory and returns the pointer.

You must free() the memory if you call this directly.

Parameters
[in]ctextColorText to copy/allocate for.
Returns

Pointer to a heap-allocated ColorText.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorText

◆ ColorText_to_str()

char* ColorText_to_str ( ColorText  ctext)

Stringifies a ColorText struct, creating a mix of escape codes and text.

Parameters
[in]ctextColorText to stringify.
Returns

An allocated string with text/escape-codes.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned. If the ColorText has a NULL .text member, NULL is returned.

See also
ColorText

Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_Colr(), Colr_center_char(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), Colr_rjust_char(), colr_str_replace_all_ColorText(), colr_str_replace_ColorText(), colr_str_replace_re_all_ColorText(), colr_str_replace_re_ColorText(), colr_str_replace_re_match_ColorText(), colr_str_replace_re_matches_ColorText(), colr_str_replace_re_pat_all_ColorText(), and colr_str_replace_re_pat_ColorText().

◆ ColorType_eq()

bool ColorType_eq ( ColorType  a,
ColorType  b 
)

Compares two ColorTypes.

This is used to implement colr_eq().

Parameters
[in]aThe first ColorType to compare.
[in]bThe second ColorType to compare.
Returns
true if they are equal, otherwise false.
See also
ColorType

◆ ColorType_from_str()

ColorType ColorType_from_str ( const char *  arg)

Determine which type of color value is desired by name.

Example:

  • "red" == TYPE_BASIC
  • "253" == TYPE_EXTENDED
  • "123,55,67" == TYPE_RGB
Parameters
[in]argColor name to get the ColorType for.
Return values
ColorTypevalue on success.
TYPE_INVALIDfor invalid color names/strings.
TYPE_INVALID_EXT_RANGEfor ExtendedValues outside of 0-255.
TYPE_INVALID_RGB_RANGEfor rgb values outside of 0-255.
◆  ColorType_from_str example:
#include "colr.h"
int main(int argc, char** argv) {
char* userarg;
if (argc == 1) {
if (asprintf(&userarg, "%s", "123,54,25") < 1) return EXIT_FAILURE;
} else {
if (asprintf(&userarg, "%s", argv[1]) < 1) return EXIT_FAILURE;
}
ColorType type = ColorType_from_str(userarg);
if (!ColorType_is_invalid(type)) {
char* repr = colr_repr(type);
printf("User passed in a %s, %s\n", repr, userarg);
free(repr);
} else {
printf("User passed in an invalid color name: %s\n", userarg);
}
free(userarg);
}
See also
ColorType

◆ ColorType_is_invalid()

bool ColorType_is_invalid ( ColorType  type)

Check to see if a ColorType value is considered invalid.

Parameters
[in]typeColorType value to check.
Returns
true if the value is considered invalid, otherwise false.
See also
ColorType

◆ ColorType_is_valid()

bool ColorType_is_valid ( ColorType  type)

Check to see if a ColorType value is considered valid.

Parameters
[in]typeColorType value to check.
Returns
true if the value is considered valid, otherwise false.
See also
ColorType

◆ ColorType_repr()

char* ColorType_repr ( ColorType  type)

Creates a string (char*) representation of a ColorType.

Parameters
[in]typeA ColorType to get the type from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorType

◆ ColorType_to_str()

char* ColorType_to_str ( ColorType  type)

Create a human-friendly string (char*) representation for a ColorType.

Parameters
[in]typeA ColorType to get the name for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorType

Referenced by ColorValue_example().

◆ ColorValue_empty()

ColorValue ColorValue_empty ( void  )

Create an "empty" ColorValue.

This is used with ColorArg_empty() to build ColorArgs that don't do anything, where using NULL has a different meaning inside the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.

Returns
(ColorValue){.type=TYPE_NONE, .basic=0, .ext=0, .rgb=(RGB){0, 0, 0}}
See also
ColorArg
ColorArg_empty
ColorArg_is_empty
ColorValue_is_empty

◆ ColorValue_eq()

bool ColorValue_eq ( ColorValue  a,
ColorValue  b 
)

Compares two ColorValue structs.

They are considered "equal" if all of their members match.

Parameters
[in]aFirst ColorValue to compare.
[in]bSecond ColorValue to compare.
Returns
true if they are equal, otherwise false.
See also
ColorValue

Referenced by ColorArg_eq().

◆ ColorValue_example()

char* ColorValue_example ( ColorValue  cval)

Create a string (char*) representation of a ColorValue with a human-friendly type/name.

Parameters
[in]cvalA ColorValue to get an example string for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_example().

◆ ColorValue_from_esc()

ColorValue ColorValue_from_esc ( const char *  s)

Convert an escape-code string (char*) into a ColorValue.

Parameters
[in]s

An escape-code string to parse.

Must be null-terminated.

Returns
A ColorValue (with no fore/back information, only the color type and value).
Return values
Forinvalid strings, the .type member can be one of:
  • TYPE_INVALID
  • TYPE_INVALID_EXT_RANGE
  • TYPE_INVALID_RGB_RANGE
See also
ColorValue
ColorArg_from_esc

Referenced by ColorArg_from_esc().

◆ ColorValue_from_str()

ColorValue ColorValue_from_str ( const char *  s)

Create a ColorValue from a known color name, or RGB string (char*).

Parameters
[in]sA string to parse the color name from (can be an RGB string).
Returns
A ColorValue (with no fore/back information, only the color type and value).
Return values
Forinvalid strings, the .type member can be one of:
  • TYPE_INVALID
  • TYPE_INVALID_EXT_RANGE
  • TYPE_INVALID_RGB_RANGE
See also
ColorValue

Referenced by ColorArg_from_str().

◆ ColorValue_from_value()

ColorValue ColorValue_from_value ( ColorType  type,
void *  p 
)

Used with the color_val macro to dynamically create a ColorValue based on it's argument type.

Parameters
[in]typeA ColorType value, to mark the type of ColorValue.
[in]pA pointer to either a BasicValue, ExtendedValue, or a RGB.
Returns
A ColorValue struct with the appropriate .type member set for the value that was passed. For invalid types the .type member may be set to one of:
  • TYPE_INVALID
  • TYPE_INVALID_EXT_RANGE
  • TYPE_INVALID_RGB_RANGE
See also
ColorValue

Referenced by ColorArg_from_BasicValue(), ColorArg_from_ExtendedValue(), ColorArg_from_RGB(), ColorArg_from_StyleValue(), ColorValue_from_esc(), and ColorValue_from_str().

◆ ColorValue_has_BasicValue()

bool ColorValue_has_BasicValue ( ColorValue  cval,
BasicValue  bval 
)

Checks to see if a ColorValue has a BasicValue set.

Parameters
[in]cvalColorValue to check.
[in]bvalBasicValue to look for.
Returns
true if the ColorValue has the exact BasicValue set.
See also
ColorValue

◆ ColorValue_has_ExtendedValue()

bool ColorValue_has_ExtendedValue ( ColorValue  cval,
ExtendedValue  eval 
)

Checks to see if a ColorValue has a ExtendedValue set.

Parameters
[in]cvalColorValue to check.
[in]evalExtendedValue to look for.
Returns
true if the ColorValue has the exact ExtendedValue set.
See also
ColorValue

◆ ColorValue_has_RGB()

bool ColorValue_has_RGB ( ColorValue  cval,
RGB  rgb 
)

Checks to see if a ColorValue has a RGB value set.

Parameters
[in]cvalColorValue to check.
[in]rgbRGB value to look for.
Returns
true if the ColorValue has the exact RGB value set.
See also
ColorValue

◆ ColorValue_has_StyleValue()

bool ColorValue_has_StyleValue ( ColorValue  cval,
StyleValue  sval 
)

Checks to see if a ColorValue has a StyleValue set.

Parameters
[in]cvalColorValue to check.
[in]svalStyleValue to look for.
Returns
true if the ColorValue has the exact StyleValue set.
See also
ColorValue

◆ ColorValue_is_empty()

bool ColorValue_is_empty ( ColorValue  cval)

Checks to see if a ColorValue is an empty placeholder.

Parameters
[in]cvalColorValue to check.
Returns
true if the ColorValue is "empty", otherwise false.
See also
ColorValue
ColorValue_empty
ColorArg_empty
ColorArg_is_empty

◆ ColorValue_is_invalid()

bool ColorValue_is_invalid ( ColorValue  cval)

Checks to see if a ColorValue holds an invalid value.

Parameters
[in]cvalColorValue struct to check.
Returns
true if the value is invalid, otherwise false.
See also
ColorValue

Referenced by ColorArg_from_esc().

◆ ColorValue_is_valid()

bool ColorValue_is_valid ( ColorValue  cval)

Checks to see if a ColorValue holds a valid value.

Parameters
[in]cvalColorValue struct to check.
Returns
true if the value is valid, otherwise false.
See also
ColorValue

◆ ColorValue_length()

size_t ColorValue_length ( ArgType  type,
ColorValue  cval 
)

Returns the length in bytes needed to allocate a string (char*) built with ColorValue_to_esc() with the specified ArgType and ColorValue.

Parameters
[in]typeArgType (FORE, BACK, STYLE)
[in]cvalColorValue to use.
Returns
The length (size_t) needed to allocate a ColorValue's string, or 1 (size of an empty string) for invalid/empty arg types/values.
See also
ColorValue

Referenced by ColorArg_length().

◆ ColorValue_repr()

char* ColorValue_repr ( ColorValue  cval)

Creates a string (char*) representation of a ColorValue.

Parameters
[in]cvalA ColorValue to get the type and value from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_repr().

◆ ColorValue_to_esc()

char* ColorValue_to_esc ( ArgType  type,
ColorValue  cval 
)

Converts a ColorValue into an escape code string (char*).

Parameters
[in]typeArgType (FORE, BACK, STYLE) to build the escape code for.
[in]cvalColorValue to get the color value from.
Returns

An allocated string with the appropriate escape code. For invalid values, an empty string is returned.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_to_esc().

◆ ColorValue_to_esc_s()

bool ColorValue_to_esc_s ( char *  dest,
ArgType  type,
ColorValue  cval 
)

Converts a ColorValue into an escape code string (char*) and fills the destination string.

For invalid ArgType/ColorValue combinations, dest[0] is set to `'\0'`.

Parameters
[out]destDestination string for the escape code string. Must have room for the code type being used.
[in]typeArgType (FORE, BACK, STYLE) to build the escape code for.
[in]cvalColorValue to get the color value from.
Returns
true if a proper ArgType/ColorValue combination was used, otherwise false.
See also
ColorValue

Referenced by ColorArg_to_esc_s().

◆ colr_alloc_regmatch()

regmatch_t* colr_alloc_regmatch ( regmatch_t  match)

Allocates space for a regmatch_t, initializes it, and returns a pointer to it.

Parameters
[in]matchA regmatch_t to allocate for and copy.
Returns
An allocated copy of the regmatch_t.

Referenced by colr_re_matches().

◆ colr_append_reset()

void colr_append_reset ( char *  s)

Appends CODE_RESET_ALL to a string (char*), but makes sure to do it before any newlines.

Parameters
[in]s

The string to append to. Must have extra room for CODE_RESET_ALL.

Must be null-terminated.

Referenced by _colr_join(), _rainbow(), ColorText_to_str(), and colr_join_arrayn().

◆ Colr_center_char()

ColorResult* Colr_center_char ( void *  x,
int  width,
char  padchar 
)

Returns a center-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.

Parameters
[in]xColorText pointer, ColorResult pointer, or string (char*).
[in]widthMaximum width for the justified text, or 0 to use the terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult with the justified text as the result member.

You must free() the memory allocated by this function.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

If allocation fails, NULL is returned.

◆ colr_char_escape_char()

char colr_char_escape_char ( const char  c)

Returns the char needed to represent an escape sequence in C.

The following characters are supported:

Escape Sequence Description Representation
\ ' single quote
\ " double quote
\ ? question mark
\ \ backslash
\ a audible bell
\ b backspace
\ f form feed - new page
\ n line feed - new line
\ r carriage return
\ t horizontal tab
\ v vertical tab
Parameters
[in]cThe character to check.
Returns
The letter, without a backslash, needed to create an escape sequence. If the char doesn't need an escape sequence, it is simply returned.
◆  colr_char_escape_char example:
char constantchar = colr_char_escape_char('\n');
assert(constantchar == 'n');
char constantquote = colr_char_escape_char('"');
assert(constantquote == '"');
// The actual escape sequence would need the backslash added to it:
char* escaped;
asprintf(&escaped, "\\%c", colr_char_escape_char('\t'));
free(escaped);

Referenced by colr_str_repr().

◆ colr_char_in_str()

bool colr_char_in_str ( const char *  s,
const char  c 
)

Determines if a character exists in the given string (char*).

Parameters
[in]cCharacter to search for.
[in]s

String to check.

Input must be null-terminated.

Returns
true if c is found in s, otherwise false.

Referenced by colr_str_chars_lcount(), and colr_str_lstrip_chars().

◆ colr_char_is_code_end()

bool colr_char_is_code_end ( const char  c)

Determines if a character is suitable for an escape code ending.

m is used as the last character in color codes, but other characters can be used for escape sequences (such as "\x1b[2A", cursor up). Actual escape code endings can be in the range (char) 64-126 (inclusive).

Since ColrC only deals with color codes and maybe some cursor/erase codes, this function tests if the character is either A-Z or a-z.

For more information, see: https://en.wikipedia.org/wiki/ANSI_escape_code

Parameters
[in]cCharacter to test.
Returns
true if the character is a possible escape code ending, otherwise false.

Referenced by colr_str_code_count(), colr_str_code_len(), colr_str_get_codes(), colr_str_is_codes(), colr_str_noncode_len(), and colr_str_strip_codes().

◆ colr_char_repr()

char* colr_char_repr ( char  c)

Creates a string (char*) representation for a char.

Parameters
[in]cValue to create the representation for.
Returns

An allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Referenced by ColorJustify_repr().

◆ colr_char_should_escape()

bool colr_char_should_escape ( const char  c)

Determines if an ascii character has an escape sequence in C.

The following characters are supported:

Escape Sequence Description Representation
\ ' single quote
\ " double quote
\ ? question mark
\ \ backslash
\ a audible bell
\ b backspace
\ f form feed - new page
\ n line feed - new line
\ r carriage return
\ t horizontal tab
\ v vertical tab
Parameters
[in]cThe character to check.
Returns
true if the character needs an escape sequence, otherwise false.

Referenced by colr_str_repr().

◆ colr_check_marker()

bool colr_check_marker ( uint32_t  marker,
void *  p 
)

Checks an unsigned int against the individual bytes behind a pointer's value.

This helps to guard against overflows, because only a single byte is checked at a time. If any byte doesn't match the marker, false is immediately returned, instead of continuing past the pointer's bounds.

Parameters
[in]markerA colr marker, like COLORARG_MARKER, COLORTEXT_MARKER, etc.
[in]pA pointer to check, to see if it starts with the marker.
Returns
true if all bytes match the marker, otherwise false.
See also
ColorArg_is_ptr
ColorText_is_ptr
◆  colr_check_marker example:
// This is actually used with void pointer, where the type is not known.
// It's only known that the pointer will be 1 of 3 types.
ColorArg* cargp = fore(GREEN);
colr_free(cargp);
char* s = "Not a ColorText at all.";
ColorText* ctextp = Colr("But this is a ColorText.", fore(GREEN));
colr_free(ctextp);
printf("colr_check_marker() assertions held up.\n");

Referenced by _colr_is_last_arg(), ColorArg_is_ptr(), ColorResult_is_ptr(), and ColorText_is_ptr().

◆ colr_empty_str()

char* colr_empty_str ( void  )

Allocates an empty string (char*).

This is for keeping the interface simple, so the return values from color functions with invalid values can be consistent.

Returns

Pointer to an allocated string consisting of '\0'.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Referenced by colr_str_center(), colr_str_ljust(), colr_str_replace_re_match(), colr_str_rjust(), and colr_str_strip_codes().

◆ Colr_fmt_str()

ColorResult* Colr_fmt_str ( const char *  fmt,
  ... 
)

Allocate and format a string like asprintf, but wrap it in an allocated ColorResult.

This is declared with __attribute__((__format__(__printf__, 1, 2))) so the compiler can check for bad format strings.

Parameters
[in]fmtFormat string for asprintf.
[in]...Other arguments for asprintf.
Returns

An allocated ColorResult, or NULL if fmt is NULL.

If allocation fails, NULL is returned.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_fmt_str example:
int i = 2600;
double d = 1.337;
colr_puts(Colr_fmt_str("<%d> <%0.3f>", i, d));

◆ colr_free_argsv()

void colr_free_argsv ( va_list  args)

Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list.

Parameters
[in]argsThe va_list with ColrC objects (ColorArg, ColorResult, or ColorText pointer). The last argument must be _ColrLastArg.

Referenced by ColorResult_Colr().

◆ colr_free_re_matches()

void colr_free_re_matches ( regmatch_t **  matches)

Free an array of allocated regmatch_t, like the return from colr_re_matches().

Parameters
[out]matchesA pointer to an array of regmatch_t pointers.

Referenced by colr_str_replace_re_pat_all().

◆ colr_is_colr_ptr()

bool colr_is_colr_ptr ( void *  p)

Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer.

Parameters
[in]pA pointer to a possible ColrC object.
Returns
true if p is a ColorArg, ColorResult, or ColorText pointer, otherwise false.

Referenced by colr_free_argsv().

◆ colr_join_array()

char* colr_join_array ( void *  joinerp,
void *  ps 
)

Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText.

Parameters
[in]joinerpThe joiner (any ColorArg, ColorText, or string (char*)).
[in]psAn array of pointers to ColorArgs, ColorTexts, or strings (char*). The array must have NULL as the last item.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆  colr_join_array example:
char* joiner = " [and] ";
ColorText* words[] = {
Colr("this", fore(RED)),
Colr("that", fore(hex("ff3599"))),
Colr("the other", fore(BLUE), style(UNDERLINE)),
NULL
};
char* s = colr_join_array(joiner, words);
if (!s) exit(1);
printf("%s\n", s);
free(s);
// Don't forget to free the ColorTexts/ColorArgs.
size_t i = 0;
while (words[i]) ColorText_free(words[i++]);
See also
colr
colr_join
colr_join_arrayn
Examples:
colr_join_example.c.

◆ colr_join_arrayn()

char* colr_join_arrayn ( void *  joinerp,
void *  ps,
size_t  count 
)

Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText.

Parameters
[in]joinerpThe joiner (any ColorArg, ColorText, or string (char*)).
[in]psAn array of pointers to ColorArgs, ColorTexts, or strings (char*). The array must have at least a length of count, unless a NULL element is placed at the end.
[in]countThe total number of items in the array.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned. If any parameter is NULL, NULL is returned.

◆  colr_join_arrayn example:
char* joiner = " [and] ";
ColorText* words[] = {
Colr("this", fore(RED)),
Colr("that", fore(hex("ff3599"))),
Colr("the other", fore(BLUE), style(UNDERLINE))
};
// This only works for actual arrays, not malloc'd stuff.
size_t arr_length = sizeof(words) / sizeof(words[0]);
char* s = colr_join_arrayn(joiner, words, arr_length);
if (!s) exit(1);
printf("%s\n", s);
free(s);
// Don't forget to free the ColorTexts/ColorArgs.
for (size_t i = 0; i < arr_length; i++) ColorText_free(words[i]);
See also
colr
colr_join

Referenced by colr_join_array().

◆ Colr_ljust_char()

ColorResult* Colr_ljust_char ( void *  x,
int  width,
char  padchar 
)

Returns a left-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.

Parameters
[in]xColorText pointer, ColorResult pointer, or string (char*).
[in]widthMaximum width for the justified text, or 0 to use the terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult with the justified text as the result member.

You must free() the memory allocated by this function.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

If allocation fails, NULL is returned.

Examples:
Colr_example.c.

◆ colr_mb_len()

size_t colr_mb_len ( const char *  s,
size_t  length 
)

Like mbrlen, except it will return the length of the next N (length) multibyte characters in bytes.

/details Unlike colr_str_mb_len(), which returns the number of multibyte characters, this function will return the number of bytes that make up the next number (length) of multibyte characters.

Parameters
[in]sThe string to check.
[in]lengthNumber of multibyte characters to get the length for.
Returns
The number of bytes parsed in s to get at least length multibyte characters.
Return values
0if s is NULL/empty, or length is 0.
(size_t)-1if an invalid multibyte sequence is found at the start of s.
See also
colr_str_mb_len
colr_is_valid_mblen
◆  colr_mb_len example:
#include "colr.h"
int main(void) {
// There are 4 multibyte characters in the string.
// There are multiple bytes making up each character, probably 3 each,
// which makes the byte-length 12.
char* s = "1337";
// Calling colr_mb_len(s, 1) is like calling mbrlen().
size_t first_len = colr_mb_len(s, 1);
mbstate_t st;
memset(&st, 0, sizeof(mbstate_t));
assert(first_len == (size_t)mbrlen(s, MB_LEN_MAX, &st));
size_t first_two_len = colr_mb_len(s, 2);
// This assertion doesn't hold for ALL characters, but it should hold
// for these, because they are all FULLWIDTH DIGIT chars.
assert(first_two_len == (first_len * 2));
// Skip about 6 bytes, to get past the first 2
char* skip2 = s + first_two_len;
assert(strcmp(skip2, "37") == 0);
// There are only about 7 bytes (6 + 1 for the null).
// Calling colr_mb_len with a `length` that is too large is okay.
size_t length = colr_mb_len(skip2, 100);
assert(length == strlen(skip2));
size_t charlength = colr_str_mb_len(skip2);
printf("\"%s\" contains %lu bytes for %lu chars.\n", skip2, length, charlength);
// This should always hold true, even though it is useless:
assert(colr_mb_len(s, strlen(s)) == strlen(s));
}

Referenced by _rainbow().

◆ colr_printf_handler()

int colr_printf_handler ( FILE *  fp,
const struct printf_info *  info,
const void *const *  args 
)

Handles printing with printf for Colr objects.

This function matches the required typedef in printf.h (printf_function), for handling a custom printf format char with register_printf_specifier.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]fpFILE pointer for output.
[in]infoInfo from printf about how to format the argument.
[in]argsArgument list (with only 1 argument), containing a ColorArg, ColorResult, ColorText, or string (char*) to format.
Returns
The number of characters written.

Referenced by colr_printf_register().

◆ colr_printf_info()

int colr_printf_info ( const struct printf_info *  info,
size_t  n,
int *  argtypes,
int *  sz 
)

Handles the arg count/size for the Colr printf handler.

This function matches the required typedef in printf.h (printf_arginfo_size_function) for handling a custom printf format char with register_printf_specifier.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]infoInfo from printf about how to format the argument.
[in]nNumber of arguments for the format char.
[out]argtypesType of arguments being handled, from an enum defined in printf. Colr uses/sets one argument, a PA_POINTER type.
[out]szSize of the arguments. Not used in Colr.
Returns
The number of argument types set in argtypes.

Referenced by colr_printf_register().

◆ colr_printf_register()

void colr_printf_register ( void  )

Registers COLR_FMT_CHAR to handle Colr objects in the printf-family functions.

This function only needs to be called once and register_printf_specifier is only called the first time this function is called.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
◆  colr_printf_register example:
#include "colr.h"
// These are needed if you have certain warnings enabled.
#pragma clang diagnostic ignored "-Winvalid-format-specifier"
#pragma GCC diagnostic ignored "-Wformat="
#pragma GCC diagnostic ignored "-Wformat-extra-args"
int main(void) {
printf("A colr object: %R\n", Colr("Hello", fore(RED)));
char* colorized = NULL;
asprintf(
&colorized,
"I made this: %R",
Colr("No, I made this.", style(UNDERLINE))
);
puts(colorized);
free(colorized);
}

◆ colr_re_matches()

regmatch_t** colr_re_matches ( const char *  s,
regex_t *  repattern 
)

Returns all regmatch_t matches for regex pattern in a string (char*).

Parameters
[in]sThe string to search.
[in]repatternThe pattern to look for.
Returns

A pointer to an allocated array of regmatch_t*, or NULL if s is NULL or repattern is NULL. The last member is always NULL.

You must free() the memory allocated by this function.

◆  colr_re_matches example:
#include "colr.h"
int main(void) {
// Compile a regex pattern.
regex_t pat;
if (regcomp(&pat, "foo", 0)) {
regfree(&pat);
return EXIT_FAILURE;
}
// The string to operate on.
const char* s = "This foo is a foo string, foo?";
// Get all matches.
regmatch_t** matches = colr_re_matches(s, &pat);
if (!matches) {
// This should be impossible (for this example).
fprintf(stderr, "No matches?\n");
return EXIT_FAILURE;
}
puts(s);
// `colr_re_matches` always leaves `NULL` as the last member.
size_t cnt = 0;
while (matches[cnt]) {
printf("Found a match at: %d-%d\n", matches[cnt]->rm_so, matches[cnt]->rm_eo);
cnt++;
}
// Free all of your resources.
colr_free(matches);
regfree(&pat);
}
Examples:
colr_replace_all_example.c.

Referenced by colr_str_replace_re_pat_all().

◆ Colr_rjust_char()

ColorResult* Colr_rjust_char ( void *  x,
int  width,
char  padchar 
)

Returns a right-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.

Parameters
[in]xColorText pointer, ColorResult pointer, or string (char*).
[in]widthMaximum width for the justified text, or 0 to use the terminal width.
[in]padcharCharacter to pad with, or 0 for `' '` (space).
Returns

An allocated ColorResult with the justified text as the result member.

You must free() the memory allocated by this function.

If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().

If allocation fails, NULL is returned.

◆ colr_set_locale()

bool colr_set_locale ( void  )

Sets the locale to (LC_ALL, "") if it hasn't already been set.

This is used for functions dealing with multibyte strings.

Returns
true if the locale had to be set, false if it was already set.

Referenced by colr_mb_len(), and colr_str_mb_len().

◆ colr_str_array_contains()

bool colr_str_array_contains ( char **  lst,
const char *  s 
)

Determine if a string (char*) is in an array of strings (char**, where the last element is NULL).

Parameters
[in]lstThe string array to look in.
[in]sThe string to look for.
Returns
true if the string is found, otherwise false.
Return values
<tt>false</tt>if lst is NULL or s is NULL.
◆  colr_str_array_contains example:
char* strarray[] = {
"this",
"that",
NULL
};
if (colr_str_array_contains(strarray, "that")) {
printf("List contained \"that\".\n");
}
if (!colr_str_array_contains(strarray, "NONEXISTENT")) {
printf("List did not contain \"NONEXISTENT\".\n");
}

Referenced by colr_str_get_codes().

◆ colr_str_array_free()

void colr_str_array_free ( char **  ps)

Free an allocated array of strings, including the array itself.

Each individual string will be released, and finally the allocated memory for the array of pointers will be released.

Parameters
[in]psA pointer to an array of strings.
◆  colr_str_array_free example:
char* s = colr("Test", fore(RED), back(WHITE), style(BRIGHT));
if (!s) exit(1);
// Call something that creates an array of strings on the heap.
char** code_array = colr_str_get_codes(s, false);
free(s);
if (!code_array) exit(1);
// ... do something with the array of strings.
// And then free it:
colr_str_array_free(code_array);

Referenced by ColorArgs_from_str().

◆ colr_str_center()

char* colr_str_center ( const char *  s,
int  width,
const char  padchar 
)

Center-justifies a string (char*), ignoring escape codes when measuring the width.

Parameters
[in]s

The string to justify.

Input must be null-terminated.

[in]widthThe overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().
[in]padcharThe character to pad with. If '0', then `' '` is used.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_str_ljust
colr_str_rjust
colr_term_size
◆  colr_str_center example:
char* colorized = colr("This.", fore(RED), back(WHITE));
char* justified = colr_str_center(colorized, 9, ' ');
free(colorized);
// The string still has codes, but only 4 spaces were added.
assert(colr_str_starts_with(justified, " "));
assert(colr_str_ends_with(justified, " "));
// It was "justified" to 9 characters long, but it is well over that.
assert(strlen(justified) > 9);
printf("'%s'\n", justified);
free(justified);

Referenced by ColorResult_center(), Colr_center_char(), and colr_printf_handler().

◆ colr_str_char_count()

size_t colr_str_char_count ( const char *  s,
const char  c 
)

Counts the number of characters (c) that are found in a string (char*) (s).

Returns 0 if s is NULL, or c is `'\0'`.

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]c

The character to count.

Must not be 0.

Returns
The number of times c occurs in s.
◆  colr_str_char_count example:
size_t ps = colr_str_char_count("apple", 'p');
assert(ps == 2);
printf("Found %lu 'p' characters.\n", ps)

Referenced by _rainbow().

◆ colr_str_char_lcount()

size_t colr_str_char_lcount ( const char *  s,
const char  c 
)

Counts the number of characters (c) that are found at the beginning of a string (char*) (s).

Returns 0 if s is NULL, c is `'\0'`, or the string doesn't start with c.

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]c

The character to count.

Must not be 0.

Returns
The number of times c occurs at the start of s.
◆  colr_str_char_lcount example:
size_t xs = colr_str_char_lcount("xxApple", 'x');
assert(xs == 2);
printf("Found %lu 'x' characters.\n", xs)

Referenced by colr_str_lstrip_char().

◆ colr_str_chars_lcount()

size_t colr_str_chars_lcount ( const char *restrict  s,
const char *restrict  chars 
)

Counts the number of characters that are found at the beginning of a string (char*) (s), where the character can be any of chars.

Returns 0 if s is NULL/empty, chars is NULL/empty, or the string doesn't start with any of the characters in chars.

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]chars

The characters to count, in any order.

Must not be 0.

Returns
The number of times a character in chars occurs at the start of s.
◆  colr_str_chars_lcount example:
size_t chars = colr_str_chars_lcount("cbaabcbbccApple", "abc");
assert(chars == 10);
printf("Found %lu 'a', 'b', or 'c' characters.\n", chars)

Referenced by colr_str_lstrip_chars().

◆ colr_str_code_count()

size_t colr_str_code_count ( const char *  s)

Return the number of escape-codes in a string (char*).

Parameters
[in]s

A string to count the escape-codes for.

Must be null-terminated.

Returns
The number of escape-codes, or 0 if s is NULL, or doesn't contain any escape-codes.
◆  colr_str_code_count example:
char* s = colr("Testing this out.", fore(RED), back(WHITE));
if (!s) exit(1);
size_t code_cnt = colr_str_code_count(s);
assert(code_cnt == 3); // The reset code is also appended.
printf("Found codes: %zu\n", code_cnt);
free(s);

Referenced by colr_str_get_codes().

◆ colr_str_code_len()

size_t colr_str_code_len ( const char *  s)

Return the number of bytes that make up all the escape-codes in a string (char*).

Parameters
[in]s

A string to count the code-chars for.

Must be null-terminated.

Returns
The number of escape-code characters, or 0 if s is NULL, or doesn't contain any escape-codes.
◆  colr_str_code_len example:
char* s = colr("Testing this out.", fore(RED), back(WHITE));
if (!s) exit(1);
size_t code_len = colr_str_code_len(s);
assert(code_len == 14); // The reset code is also appended.
printf("Found code chars: %zu\n", code_len);
free(s);

◆ colr_str_copy()

char* colr_str_copy ( char *restrict  dest,
const char *restrict  src,
size_t  length 
)

Copies a string (char*) like strncpy, but ensures null-termination.

If src is NULL, or dest is NULL, NULL is returned.

If src does not contain a null-terminator, this function will truncate at length characters.

If src is an empty string, then dest[0] will be `'\0'` (an empty string).

A null-terminator is always appended to dest.

src and dest must not overlap.

Parameters
[in]destMemory allocated for new string. Must have room for strlen(src) + 1 or length + 1.
[in]srcSource string to copy.
[in]lengthMaximum characters to copy. This does not include the null-terminator. Usually set to strlen(dest).
Returns
On success, a pointer to dest is returned.
◆  colr_str_copy example:
char* s = "testing";
size_t length = strlen(s);
char* dest = malloc(length + 1);
// Copy the entire string:
colr_str_copy(dest, s, length);
assert(strcmp(dest, "testing") == 0);
printf("Copied: %s\n", dest);
// Copy only 4 bytes:
colr_str_copy(dest, s, 4);
assert(strcmp(dest, "test") == 0);
printf("Truncated: %s\n", dest);
// String gets truncated when dest is too small:
colr_str_copy(dest, "this is too long.", length);
assert(strcmp(dest, "this is") == 0);
assert(dest[length] == '\0');
printf("Truncated: %s\n", dest);
free(dest);

Referenced by ColorResult_from_stra().

◆ colr_str_ends_with()

bool colr_str_ends_with ( const char *restrict  s,
const char *restrict  suffix 
)

Determine if one string (char*) ends with another.

str and suffix must not overlap.

Parameters
[in]s

String to check.

Must be null-terminated.

[in]suffix

Suffix to check for.

Must be null-terminated.

Returns
True if str ends with suffix.
False if either is NULL, or the string doesn't end with the suffix.

Referenced by colr_append_reset().

◆ colr_str_get_codes()

char** colr_str_get_codes ( const char *  s,
bool  unique 
)

Get an array of escape-codes from a string (char*).

This function copies the escape-code strings, and the pointers to the heap, if any escape-codes are found in the string.

colr_str_array_free() can be used to easily free() the result of this function.

Parameters
[in]s

A string to get the escape-codes from.

Must be null-terminated.

[in]uniqueWhether to only include unique escape codes.
Returns

An allocated array of string (char*) pointers, where the last element is NULL.

You must free() the memory allocated by this function.

Return values
Ifs is NULL, or empty, or there are otherwise no escape-codes found in the string, or allocation fails for the strings/array, then NULL is returned.
Onsuccess, there will be at least two pointers behind the return value. The last pointer is always NULL.
◆  colr_str_get_codes example:
#include <stdio.h>
#include "colr.h"
int main(void) {
char* s = colr_cat(
Colr("Testing this out.", fore(RED), back(WHITE)),
Colr("Again.", fore(RED), style(UNDERLINE))
);
if (!s) return EXIT_FAILURE;
char** code_array = colr_str_get_codes(s, false);
free(s);
if (!code_array) {
fprintf(stderr, "No code found? Impossible!\n");
return EXIT_FAILURE;
}
// Iterate over the code array.
for (size_t i = 0; code_array[i]; i++) {
char* code_repr = colr_repr(code_array[i]);
printf("Found code: %s\n", code_repr);
free(code_repr);
}
// Free the strings, and the array of pointers.
colr_str_array_free(code_array);
}

Referenced by ColorArgs_from_str().

◆ colr_str_has_codes()

bool colr_str_has_codes ( const char *  s)

Determines if a string (char*) has ANSI escape codes in it.

This will detect any ansi escape code, not just colors.

Parameters
[in]s

The string to check. Can be NULL.

Input must be null-terminated.

Returns
true if the string has at least one escape code, otherwise false.
See also
colr_str_is_codes

◆ colr_str_has_ColorArg()

bool colr_str_has_ColorArg ( const char *  s,
ColorArg carg 
)

Determines whether a string contains a specific color code.

Parameters
[in]sThe string to check.
[in]cargThe fore(), back(), or style() ColorArg to check for.
Returns
true if the string contains the escape codes formed by the ColorArg* given, otherwise false. If s is NULL/empty, or carg is NULL/empty, this will return false.
◆  colr_str_has_ColorArg example:
ColorArg* forered = fore(RED);
char* s = colr("Testing", fore(RED));
if (colr_str_has_ColorArg(s, forered)) {
puts("Yep, there's a fore:red in there.");
} else {
puts("Hmmm...no red?");
}
// That ColorArg was allocated, free() it.
colr_free(forered);
ColorArg* backblue = back(BLUE);
if (colr_str_has_ColorArg(s, backblue)) {
fprintf(stderr, "Illegal back:blue found in a red string!\n");
}
// Free this one too.
// If it was used inside of a colr/Colr macro call, we wouldn't have to do this.
colr_free(backblue);
// Free the string we created to test with.
free(s);

◆ colr_str_hash()

ColrHash colr_str_hash ( const char *  s)

Hash a string using djb2.

This is only used for simple, short, string (char*) hashing. It is not designed for cryptography.

There are some notes about collision rates for this function here.

Parameters
[in]s

The string to hash.

Must be null-terminated.

Returns
A ColrHash (unsigned long) value with the hash.
Return values
0if s is NULL.
COLR_HASH_SEEDif s is an empty string.
◆  colr_str_hash example:
char* strings[] = {
"fore",
"back",
"style",
"invalid",
"red",
"\x1b[4m",
"\x1b[0m"
};
size_t strings_len = sizeof(strings) / sizeof(strings[0]);
for (size_t i = 0; i < strings_len; i++) {
ColrHash hashval = colr_str_hash(strings[i]);
printf("%8s: hash=%lu\n", strings[i], hashval);
}

Referenced by colr_str_array_contains().

◆ colr_str_is_all()

bool colr_str_is_all ( const char *  s,
const char  c 
)

Determines whether a string (char*) consists of only one character, possibly repeated.

Parameters
[in]sString to check.
[in]cCharacter to test for. Must not be 0.
Returns
true if s contains only the character c, otherwise false.

◆ colr_str_is_codes()

bool colr_str_is_codes ( const char *  s)

Determines if a string (char*) is composed entirely of escape codes.

Returns false if the string is NULL, or empty.

Parameters
[in]s

The string to check.

Input must be null-terminated.

Returns
true if the string is escape-codes only, otherwise false.
See also
colr_str_has_codes

◆ colr_str_is_digits()

bool colr_str_is_digits ( const char *  s)

Determines whether all characters in a string (char*) are digits.

If s is NULL or an empty string (""), false is returned.

Parameters
[in]s

String to check.

Input must be null-terminated.

Returns
true if all characters are digits (0-9), otherwise false.

Referenced by ExtendedValue_from_str().

◆ colr_str_is_empty()

bool colr_str_is_empty ( const char *  s)

Checks to see if a string empty.

This for compatibility with the colr_is_empty() macro.

Parameters
[in]sThe string to check.
Returns
true if s is an "empty" string or NULL, otherwise false.

◆ colr_str_ljust()

char* colr_str_ljust ( const char *  s,
int  width,
const char  padchar 
)

Left-justifies a string (char*), ignoring escape codes when measuring the width.

Parameters
[in]s

The string to justify.

Input must be null-terminated.

[in]widthThe overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().
[in]padcharThe character to pad with. If '0', then `' '` is used.
Returns

An allocated string with the result, or NULL if s is NULL.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_str_center
colr_str_rjust
colr_term_size
◆  colr_str_ljust example:
char* colorized = colr("This.", fore(RED), back(WHITE));
char* justified = colr_str_ljust(colorized, 8, ' ');
free(colorized);
// The string still has codes, but only 3 spaces were added.
assert(colr_str_ends_with(justified, " "));
// It was "justified" to 8 characters long, but it is well over that.
assert(strlen(justified) > 8);
printf("'%s'\n", justified);
free(justified);

Referenced by ColorResult_ljust(), Colr_ljust_char(), and colr_printf_handler().

◆ colr_str_lower()

void colr_str_lower ( char *  s)

Converts a string (char*) into lower case in place.

Input must be null-terminated.

If s is NULL, nothing is done.

Parameters
[in]sThe input string to convert to lower case.

◆ colr_str_lstrip()

size_t colr_str_lstrip ( char *restrict  dest,
const char *restrict  s,
size_t  length,
const char  c 
)

Strip a leading character from a string (char*), filling another string (char*) with the result.

dest and s should not overlap.

Parameters
[out]destDestination char array. Must have room for strlen(s) + 1.
[in]sString to strip the character from.
[in]lengthLength of s, the input string.
[in]cCharacter to strip. If set to 0, all whitespace characters will be used (' ', '\n', '\t', '\v', '\f', '\r').
Returns
The number of c characters removed. May return 0 if s is NULL/empty, dest is NULL.

Referenced by colr_str_lstrip_char(), and RGB_from_hex().

◆ colr_str_lstrip_char()

char* colr_str_lstrip_char ( const char *  s,
const char  c 
)

Strips a leading character from a string (char*), and allocates a new string with the result.

Parameters
[in]sString to strip the character from.
[in]cCharacter to strip. If set to 0, all whitespace characters will be used (' ', '\n', '\t').
Returns

An allocated string with the result. May return NULL if s is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ colr_str_lstrip_chars()

char* colr_str_lstrip_chars ( const char *restrict  s,
const char *restrict  chars 
)

Removes certain characters from the start of a string (char*) and allocates a new string with the result.

The order of the characters in chars does not matter. If any of them are found at the start of a string, they will be removed.

colr_str_lstrip_chars("aabbccTEST", "bca") == "TEST"

s and chars must not overlap.

Parameters
[in]sThe string to strip. s Must be null-terminated.
[in]charsA string of characters to remove. Each will be removed from the start of the string. chars Must be null-terminated.
Returns

An allocated string with the result. May return NULL if s or chars is NULL.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ colr_str_mb_len()

size_t colr_str_mb_len ( const char *  s)

Returns the number of characters in a string (char*), taking into account possibly multibyte characters.

Parameters
[in]sThe string to get the length of.
Returns
The number of characters, single and multibyte, or 0 if s is NULL, empty, or has invalid multibyte sequences.
See also
colr_mb_len
◆  colr_str_mb_len example:
#include "colr.h"
int main(void) {
char* s = "1337";
// There are 4 multibyte characters in the string.
assert(colr_str_mb_len(s) == 4);
// There are multiple bytes making up each characters, probably 3 each,
// which makes the byte-length 12.
assert(strlen(s) > 4);
}

Referenced by _rainbow().

◆ colr_str_noncode_len()

size_t colr_str_noncode_len ( const char *  s)

Returns the length of string (char*), ignoring escape codes and the the null-terminator.

Parameters
[in]s

String to get the length for.

Input must be null-terminated.

Returns
The length of the string, as if it didn't contain escape codes. For non-escape-code strings, this is like strlen(). For NULL or "empty" strings, 0 is returned.
See also
colr_str_strip_codes

Referenced by ColorText_length(), colr_str_center(), colr_str_ljust(), and colr_str_rjust().

◆ colr_str_replace()

char* colr_str_replace ( const char *restrict  s,
const char *restrict  target,
const char *restrict  repl 
)

Replaces the first substring found in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

For a more dynamic version, see the colr_replace and colr_replace_re macros.

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo foo foo line.";
char* replaced = colr_str_replace_cnt(mystring, "foo", "replaced", 2);
if (!replaced) {
fprintf(stderr, "Failed to allocate for new string!\n");
return EXIT_FAILURE;
}
printf("%s\n", replaced);
// Don't forget to free the new string.
free(replaced);
return EXIT_SUCCESS;
}

Referenced by colr_str_replace_ColorArg(), colr_str_replace_ColorResult(), and colr_str_replace_ColorText().

◆ colr_str_replace_all()

char* colr_str_replace_all ( const char *restrict  s,
const char *restrict  target,
const char *restrict  repl 
)

Replaces the first substring found in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

For a more dynamic version, see the colr_replace and colr_replace_re macros.

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_all example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo foo foo line.";
char* replaced = colr_str_replace_all(mystring, "foo", "replaced");
if (!replaced) {
fprintf(stderr, "Failed to allocate for new string!\n");
return EXIT_FAILURE;
}
printf("%s\n", replaced);
// Don't forget to free the new string.
free(replaced);
return EXIT_SUCCESS;
}

Referenced by colr_str_replace_all_ColorArg(), colr_str_replace_all_ColorResult(), and colr_str_replace_all_ColorText().

◆ colr_str_replace_all_ColorArg()

char* colr_str_replace_all_ColorArg ( const char *restrict  s,
const char *restrict  target,
ColorArg repl 
)

Replace all substrings in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_all_ColorResult()

char* colr_str_replace_all_ColorResult ( const char *restrict  s,
const char *restrict  target,
ColorResult repl 
)

Replace all substrings in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_all_ColorText()

char* colr_str_replace_all_ColorText ( const char *restrict  s,
const char *restrict  target,
ColorText repl 
)

Replace all substrings in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_cnt()

char* colr_str_replace_cnt ( const char *restrict  s,
const char *restrict  target,
const char *restrict  repl,
int  count 
)

Replaces one or more substrings in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

For a more dynamic version, see the colr_replace and colr_replace_re macros.

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe string to replace with.
[in]countNumber of substrings to replace, or 0 to replace all substrings.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_cnt example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo foo foo line.";
char* replaced = colr_str_replace_cnt(mystring, "foo", "replaced", 2);
if (!replaced) {
fprintf(stderr, "Failed to allocate for new string!\n");
return EXIT_FAILURE;
}
printf("%s\n", replaced);
// Don't forget to free the new string.
free(replaced);
return EXIT_SUCCESS;
}

Referenced by colr_str_replace(), and colr_str_replace_all().

◆ colr_str_replace_ColorArg()

char* colr_str_replace_ColorArg ( const char *restrict  s,
const char *restrict  target,
ColorArg repl 
)

Replace a substring in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_ColorResult()

char* colr_str_replace_ColorResult ( const char *restrict  s,
const char *restrict  target,
ColorResult repl 
)

Replace a substring in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_ColorText()

char* colr_str_replace_ColorText ( const char *restrict  s,
const char *restrict  target,
ColorText repl 
)

Replace a substring in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]targetThe string to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re()

char* colr_str_replace_re ( const char *restrict  s,
const char *restrict  pattern,
const char *restrict  repl,
int  re_flags 
)

Replaces a substring from a regex pattern string (char*) in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe string to replace with.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern

doesn't compile/match.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo line.";
char* replaced = colr_str_replace_re(mystring, "foo", "replaced", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
replaced = colr_str_replace_re(mystring, "^([^ ]+)", "That", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}

Referenced by colr_str_replace_re_ColorArg(), colr_str_replace_re_ColorResult(), and colr_str_replace_re_ColorText().

◆ colr_str_replace_re_all()

char* colr_str_replace_re_all ( const char *restrict  s,
const char *restrict  pattern,
const char *restrict  repl,
int  re_flags 
)

Replaces all substrings from a regex pattern string (char*) in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe string to replace with.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern

doesn't compile/match.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re_all example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo bar line.";
char* replaced = colr_str_replace_re_all(mystring, "(foo)|(bar)", "replaced", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
replaced = colr_str_replace_re_all(mystring, "^([^ ]+)", "That", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}

Referenced by colr_str_replace_re_all_ColorArg(), colr_str_replace_re_all_ColorResult(), and colr_str_replace_re_all_ColorText().

◆ colr_str_replace_re_all_ColorArg()

char* colr_str_replace_re_all_ColorArg ( const char *restrict  s,
const char *restrict  pattern,
ColorArg repl,
int  re_flags 
)

Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex pattern to compile.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_all_ColorResult()

char* colr_str_replace_re_all_ColorResult ( const char *restrict  s,
const char *restrict  pattern,
ColorResult repl,
int  re_flags 
)

Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_all_ColorText()

char* colr_str_replace_re_all_ColorText ( const char *restrict  s,
const char *restrict  pattern,
ColorText repl,
int  re_flags 
)

Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_ColorArg()

char* colr_str_replace_re_ColorArg ( const char *restrict  s,
const char *restrict  pattern,
ColorArg repl,
int  re_flags 
)

Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex pattern to compile.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_ColorResult()

char* colr_str_replace_re_ColorResult ( const char *restrict  s,
const char *restrict  pattern,
ColorResult repl,
int  re_flags 
)

Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_ColorText()

char* colr_str_replace_re_ColorText ( const char *restrict  s,
const char *restrict  pattern,
ColorText repl,
int  re_flags 
)

Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]patternThe regex match object to find text to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
[in]re_flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
Returns

An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_match()

char* colr_str_replace_re_match ( const char *restrict  s,
regmatch_t *  match,
const char *restrict  repl 
)

Replaces substrings from a single regex match (regmatch_t*) in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]matchThe regex match object to find text to replace.
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re_match example:
#include "colr.h"
int main(void) {
// Build a regex pattern.
regex_t pat;
if (regcomp(&pat, "foo", 0)) {
// Failed to compile the pattern.
regfree(&pat);
return EXIT_FAILURE;
}
// Set up our matches (only 1 can be used with colr_replace_re_match).
size_t matchcnt = 1;
regmatch_t rematches[matchcnt];
// Run the regex and we should get an initialized `regmatch_t`.
char* mystring = "This is a foo line.";
if (regexec(&pat, mystring, matchcnt, rematches, 0)) {
fprintf(stderr, "No matches!?");
return EXIT_FAILURE;
}
// Replace the matched text with our string.
char* replaced = colr_str_replace_re_match(
mystring,
rematches,
"REPLACED"
);
// Don't forget to free your regex object (even if stack-allocated).
regfree(&pat);
if (!replaced) {
fprintf(stderr, "Cannot allocate for replaced string!\n");
return EXIT_FAILURE;
}
printf("%s\n", replaced);
free(replaced);
return EXIT_SUCCESS;
}

Referenced by colr_str_replace_re_match_ColorArg(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_match_ColorText(), and colr_str_replace_re_pat().

◆ colr_str_replace_re_match_ColorArg()

char* colr_str_replace_re_match_ColorArg ( const char *restrict  s,
regmatch_t *  match,
ColorArg repl 
)

Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchThe regex match object to find text to replace.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_match_ColorResult()

char* colr_str_replace_re_match_ColorResult ( const char *restrict  s,
regmatch_t *  match,
ColorResult repl 
)

Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchThe regex match object to find text to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_match_ColorText()

char* colr_str_replace_re_match_ColorText ( const char *restrict  s,
regmatch_t *  match,
ColorText repl 
)

Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchThe regex match object to find text to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_match_i()

char* colr_str_replace_re_match_i ( const char *restrict  ref,
char *  target,
regmatch_t *  match,
const char *restrict  repl 
)

Replaces substrings from a regex match (regmatch_t*) in a string (char*).

This modifies target in place. It must have capacity for the result.

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]refThe string to use for offset references. Can be target. Set this to the source string if target has not been filled yet. If target has been filled, you may use target for both ref and target.
[out]targetThe string to modify. Must have room for the resulting string.
[in]matchThe regex match object to find text to replace.
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re_match_i example:
#include "colr.h"
int main(void) {
// Build a regex pattern.
regex_t pat;
if (regcomp(&pat, "foo", 0)) {
// Failed to compile the pattern.
regfree(&pat);
return EXIT_FAILURE;
}
// Set up our matches (only 1 can be used with colr_replace_re_match_i).
size_t matchcnt = 1;
regmatch_t rematches[matchcnt];
// Run the regex and we should get an initialized `regmatch_t`.
char* mystring = "This is a foo line.";
char* replacement = "REPLACED";
size_t length = strlen(mystring);
char* targetstring = calloc(length + strlen(replacement) + 1, sizeof(char));
strncpy(targetstring, mystring, length + 1);
if (regexec(&pat, mystring, matchcnt, rematches, 0)) {
fprintf(stderr, "No matches!?");
return EXIT_FAILURE;
}
// Don't forget to free your regex object (even if stack-allocated).
regfree(&pat);
// Replace the matched text with our string.
char* replaced = colr_str_replace_re_match_i(
mystring,
targetstring,
rematches,
replacement
);
if (!replaced) {
fprintf(stderr, "An error occurred!\n");
return EXIT_FAILURE;
}
printf("%s\n", replaced);
free(targetstring);
return EXIT_SUCCESS;
}

Referenced by colr_str_replace_re_matches().

◆ colr_str_replace_re_matches()

char* colr_str_replace_re_matches ( const char *restrict  s,
regmatch_t **  matches,
const char *restrict  repl 
)

Replaces substrings from an array of regex match (regmatch_t*) in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]matchesRegex match objects to find text to replace. The array must have NULL as the last member.
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

Referenced by colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_matches_ColorText(), and colr_str_replace_re_pat_all().

◆ colr_str_replace_re_matches_ColorArg()

char* colr_str_replace_re_matches_ColorArg ( const char *restrict  s,
regmatch_t **  matches,
ColorArg repl 
)

Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchesThe regex match objects to find text to replace.
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_matches_ColorResult()

char* colr_str_replace_re_matches_ColorResult ( const char *restrict  s,
regmatch_t **  matches,
ColorResult repl 
)

Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchesThe regex match objects to find text to replace.
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_matches_ColorText()

char* colr_str_replace_re_matches_ColorText ( const char *restrict  s,
regmatch_t **  matches,
ColorText repl 
)

Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]matchesThe regex match objects to find text to replace.
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat()

char* colr_str_replace_re_pat ( const char *restrict  s,
regex_t *  repattern,
const char *restrict  repl 
)

Replaces regex patterns in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re_pat example:
#include "colr.h"
int main(void) {
// Compile a regex pattern.
regex_t pat;
if (regcomp(&pat, "foo", 0)) {
// Failed to compile the pattern.
regfree(&pat);
return EXIT_FAILURE;
}
char* mystring = "This is a foo line.";
char* replaced = colr_str_replace_re_pat(mystring, &pat, "replaced");
// Don't forget to free your regex pattern.
regfree(&pat);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}

Referenced by colr_str_replace_re(), colr_str_replace_re_pat_ColorArg(), colr_str_replace_re_pat_ColorResult(), and colr_str_replace_re_pat_ColorText().

◆ colr_str_replace_re_pat_all()

char* colr_str_replace_re_pat_all ( const char *restrict  s,
regex_t *  repattern,
const char *restrict  repl 
)

Replaces all matches to a regex pattern in a string (char*).

Using NULL as a replacement is like using an empty string (""), which removes the target string from s.

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe string to replace with.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re
◆  colr_str_replace_re_pat_all example:
#include "colr.h"
int main(void) {
// Compile a regex pattern.
regex_t pat;
if (regcomp(&pat, "[1-9]", REG_EXTENDED)) {
// Failed to compile the pattern.
fprintf(stderr, "Cannot compile the pattern!\n");
regfree(&pat);
return EXIT_FAILURE;
}
char* mystring = "1 2 everywhere, but still no 3 to spare.";
char* replaced = colr_str_replace_re_pat_all(mystring, &pat, "numbers");
// Don't forget to free your regex pattern.
regfree(&pat);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}

Referenced by colr_str_replace_re_all(), colr_str_replace_re_pat_all_ColorArg(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_all_ColorText().

◆ colr_str_replace_re_pat_all_ColorArg()

char* colr_str_replace_re_pat_all_ColorArg ( const char *restrict  s,
regex_t *  repattern,
ColorArg repl 
)

Replace all matches to a regex pattern in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat_all_ColorResult()

char* colr_str_replace_re_pat_all_ColorResult ( const char *restrict  s,
regex_t *  repattern,
ColorResult repl 
)

Replace all matches to a regex pattern in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat_all_ColorText()

char* colr_str_replace_re_pat_all_ColorText ( const char *restrict  s,
regex_t *  repattern,
ColorText repl 
)

Replace all matches to a regex pattern in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat_ColorArg()

char* colr_str_replace_re_pat_ColorArg ( const char *restrict  s,
regex_t *  repattern,
ColorArg repl 
)

Replace regex patterns in a string (char*) with a ColorArg's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat_ColorResult()

char* colr_str_replace_re_pat_ColorResult ( const char *restrict  s,
regex_t *  repattern,
ColorResult repl 
)

Replace regex patterns in a string (char*) with a ColorResult's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_replace_re_pat_ColorText()

char* colr_str_replace_re_pat_ColorText ( const char *restrict  s,
regex_t *  repattern,
ColorText repl 
)

Replace regex patterns in a string (char*) with a ColorText's string result.

Using NULL as a replacement is like using an empty string ("").

Parameters
[in]sThe string to operate on.
[in]repatternThe regex pattern to match (regex_t*).
[in]replThe ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
Returns

An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_replace
colr_replace_re

◆ colr_str_repr()

char* colr_str_repr ( const char *  s)

Convert a string (char*) into a representation of a string, by wrapping it in quotes and escaping characters that need escaping.

If s is NULL, then an allocated string containing the string "NULL" is returned (without quotes).

Escape codes will be escaped, so the terminal will ignore them if the result is printed.

Parameters
[in]sThe string to represent.
Returns

An allocated string with the representation.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_char_should_escape
colr_char_escape_char
◆  colr_str_repr example:
char* s = colr_str_repr("This\nhas \bspecial\tchars.");
// The string `s` contains an escaped string, it *looks like* the definition,
// but no real newlines, backspaces, or tabs are in it.
assert(strcmp(s, "\"This\\nhas \\bspecial\\tchars.\"") == 0);
free(s);

Referenced by _colr_ptr_repr(), ColorResult_repr(), and ColorText_repr().

◆ colr_str_rjust()

char* colr_str_rjust ( const char *  s,
int  width,
const char  padchar 
)

Right-justifies a string (char*), ignoring escape codes when measuring the width.

Parameters
[in]s

The string to justify.

Input must be null-terminated.

[in]widthThe overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().
[in]padcharThe character to pad with. If '0', then `' '` is used.
Returns

An allocated string with the result, or NULL if s is NULL.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_str_center
colr_str_ljust
colr_term_size
◆  colr_str_rjust example:
char* colorized = colr("This.", fore(RED), back(WHITE));
char* justified = colr_str_rjust(colorized, 8, ' ');
free(colorized);
// The string still has codes, but only 3 spaces were added.
assert(colr_str_starts_with(justified, " "));
// It was "justified" to 8 characters long, but it is well over that.
assert(strlen(justified) > 8);
printf("'%s'\n", justified);
free(justified);

Referenced by ColorResult_rjust(), colr_printf_handler(), and Colr_rjust_char().

◆ colr_str_starts_with()

bool colr_str_starts_with ( const char *restrict  s,
const char *restrict  prefix 
)

Checks a string (char*) for a certain prefix substring.

prefix Must be null-terminated.

Parameters
[in]sThe string to check.
[in]prefixThe prefix string to look for.
Returns
True if the string s starts with prefix.
False if one of the strings is null, or the prefix isn't found.
◆  colr_str_starts_with example:
char* s = "This is my string.";
assert(colr_str_starts_with(s, "This"));
assert(!colr_str_starts_with(s, "that"));

◆ colr_str_strip_codes()

char* colr_str_strip_codes ( const char *  s)

Strips escape codes from a string (char*), resulting in a new allocated string.

Parameters
[in]s

The string to strip escape codes from.

Input must be null-terminated.

Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
colr_str_noncode_len
◆  colr_str_strip_codes example:
char* s = "\x1b[31mRed text.\x1b[0m";
printf("With codes: %s\n", s);
char* stripped = colr_str_strip_codes(s);
if (!stripped) exit(1);
assert(!colr_str_has_codes(stripped));
assert(strlen(stripped) == 9);
printf("Without codes: %s\n", stripped);
// Don't forget to free the string:
free(stripped);

Referenced by colr_printf_handler().

◆ colr_str_to_lower()

char* colr_str_to_lower ( const char *  s)

Allocate a new lowercase version of a string (char*).

You must free() the memory allocated by this function.

Parameters
[in]s

The input string to convert to lower case.

Must be null-terminated.

Returns

The allocated string, or NULL if s is NULL.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Referenced by ExtendedValue_from_str(), and RGB_from_str().

◆ colr_supports_rgb()

bool colr_supports_rgb ( void  )

Determine whether the current environment support RGB (True Colors).

This checks $COLORTERM for the appropriate value ('truecolor' or '24bit'). On "dumber" terminals, RGB codes are probably ignored or mistaken for a 256-color or even 8-color value.

For instance, RGB is supported in konsole, but not in xterm or linux ttys. Using RGB codes in xterm makes the colors appear as though a 256-color value was used (closest matching value, like RGB_to_term_RGB()). Using RGB codes in a simpler linux tty makes them appear as though an 8-color value was used. Very ugly, but not a disaster.

I haven't seen a modern linux terminal spew garbage across the screen from using RGB codes when they are not supported, but I could be wrong. I would like to see that terminal if you know of one.

Returns
true if 24-bit (true color, or "rgb") support is detected, otherwise false.
Examples:
colr_cat_example.c.

Referenced by colr_supports_rgb_static().

◆ colr_supports_rgb_static()

bool colr_supports_rgb_static ( void  )

Same as colr_supports_rgb(), but the environment is only checked on the first call.

All other calls return the same result as the first call.

Returns
true if 24-bit (true color, or "rgb") support is detected, otherwise false.

◆ colr_term_size()

TermSize colr_term_size ( void  )

Attempts to retrieve the row/column size of the terminal and returns a TermSize.

If the call fails, the environment variables LINES and COLUMNS are checked. If that fails, a default TermSize struct is returned:

(TermSize){.rows=35, .columns=80}
Returns
A TermSize struct with terminal size information.

Referenced by ColorResult_center(), ColorResult_ljust(), ColorResult_rjust(), ColorText_length(), colr_str_center(), colr_str_ljust(), and colr_str_rjust().

◆ colr_win_size()

struct winsize colr_win_size ( void  )

Attempts to retrieve a winsize struct from an ioctl call.

If the call fails, the environment variables LINES and COLUMNS are checked. If that fails, a default winsize struct is returned:

(struct winsize){.ws_row=35, .ws_col=80, .ws_xpixel=0, .ws_ypixel=0}

man ioctl_tty says that .ws_xpixel and .ws_ypixel are unused.

Returns
A winsize struct (sys/ioctl.h) with window size information.

Referenced by colr_term_size().

◆ colr_win_size_env()

struct winsize colr_win_size_env ( void  )

Get window/terminal size using the environment variables LINES, COLUMNS, or COLS.

This is used as a fallback if the ioctl() call fails in colr_win_size(). If environment variables are not available, a default winsize struct is returned:

(struct winsize){.ws_row=35, .ws_col=80, .ws_xpixel=0, .ws_ypixel=0}
Returns
A winsize struct (sys/ioctl.h) with window size information.

Referenced by colr_win_size().

◆ ExtendedValue_eq()

bool ExtendedValue_eq ( ExtendedValue  a,
ExtendedValue  b 
)

Compares two ExtendedValues.

This is used to implement colr_eq().

Parameters
[in]aThe first ExtendedValue to compare.
[in]bThe second ExtendedValue to compare.
Returns
true if they are equal, otherwise false.
See also
ExtendedValue

◆ ExtendedValue_from_BasicValue()

int ExtendedValue_from_BasicValue ( BasicValue  bval)

Convert a BasicValue into an ExtendedValue.

BASIC_INVALID, and other invalid BasicValues will return EXT_INVALID.

Parameters
[in]bvalBasicValue to convert.
Returns
An ExtendedValue 0-15 on success, otherwise EXT_INVALID.
See also
ExtendedValue

◆ ExtendedValue_from_esc()

int ExtendedValue_from_esc ( const char *  s)

Convert an escape-code string (char*) to an ExtendedValue.

Parameters
[in]s

Escape-code string.

Must be null-terminated.

Return values
Aninteger in the range 0-255 on success.
EXT_INVALIDon error (or if s is NULL).
EXT_INVALID_RANGEif the code number was outside of the range 0-255.
See also
ExtendedValue

◆ ExtendedValue_from_hex()

int ExtendedValue_from_hex ( const char *  hexstr)

Create an ExtendedValue from a hex string (char*).

This is not a 1:1 translation of hex to rgb. Use RGB_from_hex() for that. This will convert the hex string to the closest matching ExtendedValue value.

The format for hex strings can be one of:

  • "[#]ffffff" (Leading hash symbol is optional)
  • "[#]fff" (short-form)
Parameters
[in]hexstrHex string to convert.
Returns
A value between 0 and 255 on success.
Return values
COLOR_INVALIDon error or bad values.
See also
ExtendedValue

Referenced by ExtendedValue_from_hex_default(), and ExtendedValue_from_str().

◆ ExtendedValue_from_hex_default()

ExtendedValue ExtendedValue_from_hex_default ( const char *  hexstr,
ExtendedValue  default_value 
)

Create an ExtendedValue from a hex string (char*), but return a default value if the hex string is invalid.

This is not a 1:1 translation of hex to rgb. Use RGB_from_hex_default() for that. This will convert the hex string to the closest matching ExtendedValue value.

The format for hex strings can be one of:

  • "[#]ffffff" (Leading hash symbol is optional)
  • "[#]fff" (short-form)
Parameters
[in]hexstrHex string to convert.
[in]default_valueExtendedValue to use for bad hex strings.
Returns
An ExtendedValue on success, or default_value on error.
See also
ExtendedValue
ExtendedValue_from_hex

◆ ExtendedValue_from_RGB()

ExtendedValue ExtendedValue_from_RGB ( RGB  rgb)

Convert an RGB value into the closest matching ExtendedValue.

Parameters
[in]rgbRGB value to convert.
Returns
An ExtendedValue that closely matches the original RGB value.
See also
ExtendedValue

Referenced by ExtendedValue_from_hex(), format_bg_RGB_term(), and format_fg_RGB_term().

◆ ExtendedValue_from_str()

int ExtendedValue_from_str ( const char *  arg)

Converts a known name, integer string (0-255), or a hex string (char*), into an ExtendedValue suitable for the extended-value-based functions.

Hex strings can be used:

  • "#ffffff" (Leading hash symbol is NOT optional)
  • "#fff" (short-form)

The `'#'` is not optional for hex strings because it is impossible to tell the difference between the hex value '111' and the extended value '111' without it.

Parameters
[in]argColor name to find the ExtendedValue for.
Returns
A value between 0 and 255 on success.
Return values
EXT_INVALIDon error or bad values.
EXT_INVALID_RANGEif the number was outside of the range 0-255.
See also
ExtendedValue

◆ ExtendedValue_is_invalid()

bool ExtendedValue_is_invalid ( int  eval)

Determines whether an integer is an invalid ExtendedValue.

Parameters
[in]evalA number to check.
Returns
true if the value is considered invalid, otherwise false.
See also
ExtendedValue

◆ ExtendedValue_is_valid()

bool ExtendedValue_is_valid ( int  eval)

Determines whether an integer is a valid ExtendedValue.

Parameters
[in]evalA number to check.
Returns
true if the value is considered valid, otherwise false.
See also
ExtendedValue

◆ ExtendedValue_repr()

char* ExtendedValue_repr ( int  eval)

Creates a string (char*) representation of a ExtendedValue.

Parameters
[in]evalA ExtendedValue to get the value from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ExtendedValue

◆ ExtendedValue_to_str()

char* ExtendedValue_to_str ( ExtendedValue  eval)

Creates a human-friendly string (char*) from an ExtendedValue's actual value, suitable for use with ExtendedValue_from_str().

Parameters
[in]evalA ExtendedValue to get the value from.
Returns

A pointer to an allocated string
You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
ExtendedValue

◆ format_bg()

void format_bg ( char *  out,
BasicValue  value 
)

Create an escape code for a background color.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for CODEX_LEN.
[in]valueBasicValue value to use for background.

◆ format_bg_RGB()

void format_bg_RGB ( char *  out,
RGB  rgb 
)

Create an escape code for a true color (rgb) background color using values from an RGB struct.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for CODE_RGB_LEN.
[in]rgbRGB struct to get red, blue, and green values from.

Referenced by _rainbow(), and rainbow_bg().

◆ format_bg_RGB_term()

void format_bg_RGB_term ( char *  out,
RGB  rgb 
)

Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values.

Parameters
[out]outMemory allocated for the escape code string.
[in]rgbPointer to an RGB struct.

Referenced by _rainbow(), and rainbow_bg_term().

◆ format_bgx()

void format_bgx ( char *  out,
unsigned char  num 
)

Create an escape code for an extended background color.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for CODEX_LEN.
[in]numValue to use for background.

Referenced by format_bg_RGB_term().

◆ format_fg()

void format_fg ( char *  out,
BasicValue  value 
)

Create an escape code for a fore color.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for CODEX_LEN.
[in]valueBasicValue value to use for fore.

◆ format_fg_RGB()

void format_fg_RGB ( char *  out,
RGB  rgb 
)

Create an escape code for a true color (rgb) fore color using an RGB struct's values.

Parameters
[out]outMemory allocated for the escape code string.
[in]rgbPointer to an RGB struct.

Referenced by rainbow_fg().

◆ format_fg_RGB_term()

void format_fg_RGB_term ( char *  out,
RGB  rgb 
)

Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values.

Parameters
[out]outMemory allocated for the escape code string.
[in]rgbPointer to an RGB struct.

Referenced by rainbow_fg_term().

◆ format_fgx()

void format_fgx ( char *  out,
unsigned char  num 
)

Create an escape code for an extended fore color.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for CODEX_LEN.
[in]numValue to use for fore.

Referenced by format_fg_RGB_term().

◆ format_style()

void format_style ( char *  out,
StyleValue  style 
)

Create an escape code for a style.

Parameters
[out]outMemory allocated for the escape code string. Must have enough room for STYLE_LEN.
[in]styleStyleValue value to use for style.

◆ rainbow_bg()

char* rainbow_bg ( const char *  s,
double  freq,
size_t  offset,
size_t  spread 
)

Rainbow-ize some text using rgb back colors, lolcat style.

This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.

The CODE_RESET_ALL code is appended to the result.

Parameters
[in]s

The string to colorize.

Input must be null-terminated.

[in]freqFrequency ("tightness") for the colors.
[in]offsetStarting offset in the rainbow.
[in]spreadNumber of characters per color.
Returns

The allocated/formatted string on success.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ rainbow_bg_term()

char* rainbow_bg_term ( const char *  s,
double  freq,
size_t  offset,
size_t  spread 
)

This is exactly like rainbow_bg(), except it uses colors that are closer to the standard 256-color values.

This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.

The CODE_RESET_ALL code is appended to the result.

Parameters
[in]s

The string to colorize.

Input must be null-terminated.

[in]freqFrequency ("tightness") for the colors.
[in]offsetStarting offset in the rainbow.
[in]spreadNumber of characters per color.
Returns

The allocated/formatted string on success.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

◆ rainbow_fg()

char* rainbow_fg ( const char *  s,
double  freq,
size_t  offset,
size_t  spread 
)

Rainbow-ize some text using rgb fore colors, lolcat style.

This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.

The CODE_RESET_ALL code is appended to the result.

Parameters
[in]s

The string to colorize.

Input must be null-terminated.

[in]freqFrequency ("tightness") for the colors.
[in]offsetStarting offset in the rainbow.
[in]spreadNumber of characters per color.
Returns

The allocated/formatted string on success.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Examples:
colr_cat_example.c.

◆ rainbow_fg_term()

char* rainbow_fg_term ( const char *  s,
double  freq,
size_t  offset,
size_t  spread 
)

This is exactly like rainbow_fg(), except it uses colors that are closer to the standard 256-color values.

This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.

The CODE_RESET_ALL code is appended to the result.

Parameters
[in]s

The string to colorize.

Input must be null-terminated.

[in]freqFrequency ("tightness") for the colors.
[in]offsetStarting offset in the rainbow.
[in]spreadNumber of characters per color.
Returns

The allocated/formatted string on success.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Examples:
colr_cat_example.c.

◆ rainbow_step()

RGB rainbow_step ( double  freq,
size_t  offset 
)

A single step in rainbow-izing produces the next color in the "rainbow" as an RGB value.

Parameters
[in]freqFrequency ("tightness") of the colors.
[in]offsetStarting offset in the rainbow.
Returns
An RGB value with the next "step" in the "rainbow".

Referenced by _rainbow().

◆ RGB_average()

unsigned char RGB_average ( RGB  rgb)

Return the average for an RGB value.

This is also it's "grayscale" value.

Parameters
[in]rgbThe RGB value to get the average for.
Returns
A value between 0-255.
See also
RGB

Referenced by RGB_grayscale().

◆ RGB_eq()

bool RGB_eq ( RGB  a,
RGB  b 
)

Compare two RGB structs.

Parameters
[in]aFirst RGB value to check.
[in]bSecond RGB value to check.
Returns
true if a and b have the same r, g, and b values, otherwise false.
See also
RGB

Referenced by ColorValue_eq(), and ExtendedValue_from_RGB().

◆ RGB_from_BasicValue()

RGB RGB_from_BasicValue ( BasicValue  bval)

Return an RGB value from a known BasicValue.

Terminals use different values to render basic 3/4-bit escape-codes. The values returned from this function match the names found in colr_name_data[].

Parameters
[in]bvalA BasicValue to get the RGB value for.
Returns
An RGB value that matches the BasicValue's color.
See also
RGB

◆ RGB_from_esc()

int RGB_from_esc ( const char *  s,
RGB rgb 
)

Convert an escape-code string (char*) to an actual RGB value.

Parameters
[in]s

Escape-code string.

Must be null-terminated.

[out]rgbPointer to an RGB struct to fill in the values for.
Return values
<tt>0</tt>on success, with rgb filled with values.
COLOR_INVALIDon error (or if s is NULL).
COLOR_INVALID_RANGEif any code numbers were outside of the range 0-255.
See also
RGB

◆ RGB_from_ExtendedValue()

RGB RGB_from_ExtendedValue ( ExtendedValue  eval)

Return an RGB value from a known ExtendedValue.

This is just a type/bounds-checked alias for ext2rgb_map[eval].

Parameters
[in]evalAn ExtendedValue to get the RGB value for.
Returns
An RGB value from ext2rgb_map[].
See also
RGB

◆ RGB_from_hex()

int RGB_from_hex ( const char *  hexstr,
RGB rgb 
)

Convert a hex color into an RGB value.

The format for hex strings can be one of:

  • "[#]ffffff" (Leading hash symbol is optional)
  • "[#]fff" (short-form)
Parameters
[in]hexstr

String to check for hex values.

Input must be null-terminated.

[out]rgbPointer to an RGB struct to fill in the values for.
Return values
0on success, with rgb filled with the values.
COLOR_INVALIDfor non-hex strings.
See also
RGB

Referenced by ExtendedValue_from_hex(), RGB_from_hex_default(), and RGB_from_str().

◆ RGB_from_hex_default()

RGB RGB_from_hex_default ( const char *  hexstr,
RGB  default_value 
)

Convert a hex color into an RGB value, but use a default value when errors occur.

The format for hex strings can be one of:

  • "[#]ffffff" (Leading hash symbol is optional)
  • "[#]fff" (short-form)
Parameters
[in]hexstr

String to check for RGB values.

Input must be null-terminated.

[out]default_valueAn RGB value to use when errors occur.
Returns
A valid RGB value on success, or default_value on error.
See also
RGB
hex

◆ RGB_from_str()

int RGB_from_str ( const char *  arg,
RGB rgb 
)

Convert an RGB string (char*) into an RGB value.

The format for RGB strings can be one of:

  • "RED,GREEN,BLUE"
  • "RED GREEN BLUE"
  • "RED:GREEN:BLUE"
  • "RED;GREEN;BLUE" Or hex strings can be used:
  • "#ffffff" (Leading hash symbol is NOT optional)
  • "#fff" (short-form)
Parameters
[in]arg

String to check for RGB values.

Input must be null-terminated.

[out]rgbPointer to an RGB struct to fill in the values for.
Return values
0on success, with rgb filled with the values.
COLOR_INVALIDfor non-rgb strings.
COLOR_INVALID_RANGEfor rgb values outside of 0-255.
◆  RGB_from_str example:
RGB rgbval;
int ret = RGB_from_str("123,0,234", &rgbval);
if (ret == 0) {
char* s = colr_cat(Colr("Test", fore(rgbval)));
printf("%s\n", s);
free(s);
}
See also
RGB

◆ RGB_grayscale()

RGB RGB_grayscale ( RGB  rgb)

Return a grayscale version of an RGB value.

Parameters
[in]rgbThe RGB value to convert.
Returns
A grayscale RGB value.
See also
RGB

◆ RGB_inverted()

RGB RGB_inverted ( RGB  rgb)

Make a copy of an RGB value, with the colors "inverted" (like highlighting text in the terminal).

Parameters
[in]rgbThe RGB value to invert.
Returns
An "inverted" RGB value.
See also
RGB

◆ RGB_monochrome()

RGB RGB_monochrome ( RGB  rgb)

Convert an RGB value into either black or white, depending on it's average grayscale value.

Parameters
[in]rgbThe RGB value to convert.
Returns
Either rgb(1, 1, 1) or rgb(255, 255, 255).
See also
RGB

◆ RGB_repr()

char* RGB_repr ( RGB  rgb)

Creates a string (char*) representation for an RGB value.

Allocates memory for the string representation.

Parameters
[in]rgbRGB struct to get the representation for.
Returns

Allocated string for the representation.

You must free() the memory allocated by this function.

See also
RGB

◆ RGB_to_hex()

char* RGB_to_hex ( RGB  rgb)

Converts an RGB value into a hex string (char*).

Parameters
[in]rgbRGB value to convert.
Returns
An allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
RGB

◆ RGB_to_str()

char* RGB_to_str ( RGB  rgb)

Convert an RGB value into a human-friendly RGB string (char*) suitable for input to RGB_from_str().

Parameters
[in]rgbRGB value to convert.
Returns

An allocated string in the form "red;green;blue".

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
RGB

◆ RGB_to_term_RGB()

RGB RGB_to_term_RGB ( RGB  rgb)

Convert an RGB value into it's nearest terminal-friendly RGB value.

This is a helper for the 'to_term' functions.

Parameters
[in]rgbRGB to convert.
Returns
A new RGB with values close to a terminal code color.
See also
RGB

Referenced by ExtendedValue_from_RGB().

◆ StyleValue_eq()

bool StyleValue_eq ( StyleValue  a,
StyleValue  b 
)

Compares two StyleValues.

This is used to implement colr_eq().

Parameters
[in]aThe first StyleValue to compare.
[in]bThe second StyleValue to compare.
Returns
true if they are equal, otherwise false.
See also
StyleValue

◆ StyleValue_from_esc()

StyleValue StyleValue_from_esc ( const char *  s)

Convert an escape-code string (char*) to an actual StyleValue enum value.

Parameters
[in]s

Escape-code string.

Must be null-terminated.

Return values
StyleValuevalue on success.
STYLE_INVALIDon error (or if s is NULL).
STYLE_INVALID_RANGEif the code number was outside of the range 0-255.
See also
StyleValue

◆ StyleValue_from_str()

StyleValue StyleValue_from_str ( const char *  arg)

Convert a named argument to actual StyleValue enum value.

Parameters
[in]argStyle name to convert into a StyleValue.
Returns
A usable StyleValue value on success, or STYLE_INVALID on error.
See also
StyleValue

◆ StyleValue_is_invalid()

bool StyleValue_is_invalid ( StyleValue  sval)

Determines whether a StyleValue is invalid.

Parameters
[in]svalA StyleValue to check.
Returns
true if the value is considered invalid, otherwise false.
See also
StyleValue

◆ StyleValue_is_valid()

bool StyleValue_is_valid ( StyleValue  sval)

Determines whether a StyleValue is valid.

Parameters
[in]svalA StyleValue to check.
Returns
true if the value is considered valid, otherwise false.
See also
StyleValue

◆ StyleValue_repr()

char* StyleValue_repr ( StyleValue  sval)

Creates a string (char*) representation of a StyleValue.

Parameters
[in]svalA StyleValue to get the value from.
Returns

A pointer to an allocated string.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
StyleValue

◆ StyleValue_to_str()

char* StyleValue_to_str ( StyleValue  sval)

Create a human-friendly string (char*) representation for a StyleValue.

Parameters
[in]svalStyleValue to get the name for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
StyleValue

◆ TermSize_repr()

char* TermSize_repr ( TermSize  ts)

Create a string (char*) representation for a TermSize.

Parameters
[in]tsTermSize to get the representation for.
Returns

An allocated string with the result.

You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

See also
TermSize

Variable Documentation

◆ basic_names

const BasicInfo basic_names[]
Initial value:
= {
{"reset", RESET},
{"none", RESET},
{"black", BLACK},
{"blue", BLUE},
{"cyan", CYAN},
{"green", GREEN},
{"magenta", MAGENTA},
{"red", RED},
{"white", WHITE},
{"normal", WHITE},
{"yellow", YELLOW},
{"lightblack", LIGHTBLACK},
{"lightblue", LIGHTBLUE},
{"lightcyan", LIGHTCYAN},
{"lightgreen", LIGHTGREEN},
{"lightmagenta", LIGHTMAGENTA},
{"lightred", LIGHTRED},
{"lightwhite", LIGHTWHITE},
{"lightnormal", LIGHTWHITE},
{"lightyellow", LIGHTYELLOW},
{NULL, RESET},
}

An array of BasicInfo items, used with BasicValue_from_str().

◆ colr_printf_esc_mod

int colr_printf_esc_mod = 0

Integer to test for the presence of the "escaped output modifier" in colr_printf_handler.

It is used to trigger "escaped output mode" when printing ColrC objects, where the color codes are escaped so you can see what they look like (instead of affecting the terminal).

The character used as the "escaped output modifier" is COLR_FMT_MOD_ESC, from colr.h.

Warning
This is for ColrC only. You should have no reason to use or modify this variable.

This is set in colr_printf_register when the modifier is registered. On a successful call to register_printf_modifier, it will be a positive number representing the bit set in the USER field in 'struct printf_info'. So later on, in colr_printf_handler():

using_escape_modifier = (info->user & colr_printf_esc_mod);

Referenced by colr_printf_handler(), and colr_printf_register().

◆ ext2rgb_map

const RGB ext2rgb_map[]

A map from ExtendedValue (256-color) to RGB value, where the index is the is the ExtendedValue, and the value is the RGB.

This is used in several RGB/ExtendedValue functions.

See also
ExtendedValue_from_RGB
RGB_to_term_RGB
◆  ext2rgb_map example:
// Fast map an ExtendedValue to an RGB value.
ExtendedValue eval = 9; // 9 happens to be XRED (255;85;85 in RGB).
RGB rgbval = ext2rgb_map[eval];
// The result from ExtendedValue_from_RGB should always match the map.
assert(ExtendedValue_from_RGB(rgbval) == eval);

◆ extended_names

const ExtendedInfo extended_names[]
Initial value:
= {
{"xred", XRED},
{"xgreen", XGREEN},
{"xyellow", XYELLOW},
{"xblue", XBLUE},
{"xmagenta", XMAGENTA},
{"xcyan", XCYAN},
{"xwhite", XWHITE},
{"xnormal", XWHITE},
{"xlightred", XLIGHTRED},
{"xlightgreen", XLIGHTGREEN},
{"xlightyellow", XLIGHTYELLOW},
{"xlightblack", XLIGHTBLACK},
{"xlightblue", XLIGHTBLUE},
{"xlightmagenta", XLIGHTMAGENTA},
{"xlightwhite", XLIGHTWHITE},
{"xlightnormal", XLIGHTWHITE},
{"xlightcyan", XLIGHTCYAN},
{NULL, RESET},
}

An array of ExtendedInfo, used with ExtendedValue_from_str().

◆ style_names

const StyleInfo style_names[]
Initial value:
= {
{"reset", RESET_ALL},
{"none", RESET_ALL},
{"resetall", RESET_ALL},
{"reset-all", RESET_ALL},
{"reset_all", RESET_ALL},
{"bold", BRIGHT},
{"bright", BRIGHT},
{"dim", DIM},
{"italic", ITALIC},
{"underline", UNDERLINE},
{"flash", FLASH},
{"highlight", HIGHLIGHT},
{"normal", NORMAL},
{"strikethru", STRIKETHRU},
{"strike", STRIKETHRU},
{"strikethrough", STRIKETHRU},
{"frame", FRAME},
{"encircle", ENCIRCLE},
{"circle", ENCIRCLE},
{"overline", OVERLINE},
{NULL, RESET_ALL},
}

An array of StyleInfo items, used with StyleName_from_str().