(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*`), `ColorArg`s, `ColorResult`s, or `ColorText`s. 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`), `ColorArg`s, `ColorResult`s, or `ColorText`s 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...

ColorArg *	ColorArg_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...

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"). More...

ColorResult *	ColorResult_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...

ColorResult *	ColorResult_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...

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"). 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...

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"). More...

ColorResult *	ColorResult_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...

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. More...

ColorText *	ColorText_set_just (ColorText *ctext, ColorJustify cjust)
	Set the ColorJustify method for a ColorText, and return the ColorText. More...

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. More...

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. 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...

ColorText *	ColorText_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...

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. 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...

ColorResult *	Colr_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`), `ColorArg`s, or `ColorText`s 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`), `ColorArg`s, or `ColorText`s by another string (`char`), ColorArg, or ColorText. More...

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. 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...

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. 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] p Pointer 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] p The 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]	joinerp	The 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] ps A 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]	joinerp	The joiner (any ColorArg, ColorResult, ColorText, or string).
[in]	ps	An array of pointers to `ColorArg`s, `ColorResult`s, `ColorText`s, or strings. The array must have `NULL` as the last item if `count` is greater than the total number of items.
[in]	count	Total 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]	joinerp	The joiner (any ColorArg, ColorText, or string (`char*`)).
[in]	args	A `va_list` with zero or more `ColorArg`s, `ColorText`s, 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] p A 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] p A 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] p A 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]	fmter	A formatter function (RGB_fmter) that can create escape codes from RGB values.
[in]	s	The string to "rainbowize". Input must be `null`-terminated.
[in]	freq	The "tightness" for colors.
[in]	offset	The starting offset into the rainbow.
[in]	spread	Number 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]	a	The first ArgType to compare.
[in]	b	The 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] type An 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] type An 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]	a	The first BasicValue to compare.
[in]	b	The 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

BasicValue	value on success.
BASIC_INVALID	on error (or if `s` is `NULL`).
BASIC_INVALID_RANGE	if 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] arg Color 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] bval A 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] bval A 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] bval A 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]	type	ArgType (FORE/BACK).
[in]	bval	BasicValue 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] bval BasicValue 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]	a	First ColorArg to compare.
[in]	b	Second 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]	carg	A ColorArg to get an example string for.
[in]	colorized	Whether 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] p ColorArg 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]	type	ArgType (FORE, BACK, STYLE).
[in]	value	BasicValue 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] s The 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]	type	ArgType (FORE, BACK, STYLE).
[in]	value	ExtendedValue 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]	type	ArgType (FORE, BACK, STYLE).
[in]	value	RGB 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]	type	ArgType (FORE, BACK, STYLE).
[in]	colorname	A 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]	type	ArgType (FORE, BACK, STYLE).
[in]	value	StyleValue 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]	type	ArgType value, to mark the type of ColorArg.
[in]	colrtype	ColorType value, to mark the type of ColorValue.
[in]	p	A 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] carg A 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] carg ColorArg 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] p A 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] carg ColorArg 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] carg ColorArg 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] carg ColorArg 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] carg ColorArg 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]	dest	Destination for the escape code string. Must have room for the code type being used. See ColorArg_length() for determining the size needed.
[in]	carg	ColorArg 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] carg ColorArg 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] ps A 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_free(carg_array);

◆ ColorArgs_array_repr()

char* ColorArgs_array_repr ( ColorArg ** lst )

Creates a string representation for an array of ColorArg pointers.

Parameters

[in] lst The 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);
ColorArgs_array_free(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] unique Whether 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

If	`s` is `NULL`, or empty, or there are otherwise no escape-codes found in the string, then `NULL` is returned.
On	success, 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]	a	First ColorJustify to compare.
[in]	b	Second 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] cjust The 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]	method	ColorJustifyMethod to use.
[in]	width	Width for justification. If `0` is given, ColorText will use the width from colr_term_size().
[in]	padchar	Padding 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] cjust ColorJustify 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] meth ColorJustifyMethod 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]	cres	A ColorResult pointer to center. It will be `free`'d after this.
[in]	width	Maximum width in characters, or `0` for current terminal width.
[in]	padchar	Character 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]	cres	An 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]	a	First ColorResult to compare.
[in]	b	Second ColorResult to compare.

Returns: true if they are equal, otherwise false.

See also: ColorResult

◆ ColorResult_free()

void ColorResult_free ( ColorResult * p )

Free allocated memory for a ColorResult and it's .result member.

Parameters

[in] p A ColorResult with a NULL or heap-allocated .result member.

See also: ColorResult

Referenced by _colr_free(), _colr_join(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rip_str(), ColorResult_rjust(), 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().

◆ ColorResult_from_str()

ColorResult ColorResult_from_str ( const char * s )

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

Parameters

[in] s The 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] s The 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] cres ColorResult 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] p A 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] cres A 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]	cres	A ColorResult pointer to center. It will be `free`'d after this.
[in]	width	Maximum width in characters, or `0` for current terminal width.
[in]	padchar	Character 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] s An 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] cres A 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] cres ColorResult 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]	cres	A ColorResult pointer to center. It will be `free`'d after this.
[in]	width	Maximum width in characters, or `0` for current terminal width.
[in]	padchar	Character 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] cres A 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] cres A 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()

void ColorText_free ( ColorText * p )

Frees a ColorText and it's ColorArgs.

The text member is left alone, because it wasn't created by ColrC.

Parameters

[in] p Pointer to ColorText to free, along with it's Colr-based members.

See also: ColorText

Referenced by _colr_free(), _colr_join(), Colr_center_char(), 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().

◆ 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] p Pointer 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]	text	Text 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]	text	Text to colorize (a regular string).
[in]	args	`va_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]	ctext	The ColorText to inspect.
[in]	carg	The 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] ctext A 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] ctext The 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] p A 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] ctext ColorText 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] ctext ColorText 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]	ctext	The ColorText to set the justification method for.
[in]	width	Maximum width for the justification.
[in]	padchar	Character 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]	ctext	The ColorText to set the justification method for.
[in]	cjust	The 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]	ctext	The ColorText to set the justification method for.
[in]	width	Maximum width for the justification.
[in]	padchar	Character 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]	ctext	The ColorText to set the justification method for.
[in]	width	Maximum width for the justification.
[in]	padchar	Character 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]	ctext	A ColorText to initialize with values.
[in]	text	Text 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] ctext ColorText 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] ctext ColorText 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]	a	The first ColorType to compare.
[in]	b	The 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] arg Color name to get the ColorType for.

Return values

ColorType	value on success.
TYPE_INVALID	for invalid color names/strings.
TYPE_INVALID_EXT_RANGE	for ExtendedValues outside of 0-255.
TYPE_INVALID_RGB_RANGE	for 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] type ColorType 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] type ColorType 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] type A 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] type A 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]	a	First ColorValue to compare.
[in]	b	Second 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] cval A 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

For	invalid 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] s A 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

For	invalid 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]	type	A ColorType value, to mark the type of ColorValue.
[in]	p	A 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]	cval	ColorValue to check.
[in]	bval	BasicValue 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]	cval	ColorValue to check.
[in]	eval	ExtendedValue 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]	cval	ColorValue to check.
[in]	rgb	RGB 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]	cval	ColorValue to check.
[in]	sval	StyleValue 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] cval ColorValue 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] cval ColorValue 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] cval ColorValue 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]	type	ArgType (`FORE`, `BACK`, `STYLE`)
[in]	cval	ColorValue 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] cval A 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]	type	ArgType (FORE, BACK, STYLE) to build the escape code for.
[in]	cval	ColorValue 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]	dest	Destination string for the escape code string. Must have room for the code type being used.
[in]	type	ArgType (FORE, BACK, STYLE) to build the escape code for.
[in]	cval	ColorValue 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] match A 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]	x	ColorText pointer, ColorResult pointer, or string (`char*`).
[in]	width	Maximum width for the justified text, or `0` to use the terminal width.
[in]	padchar	Character 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] c The 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] c Character 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] c Character 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] c Value 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] c The 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]	marker	A colr marker, like COLORARG_MARKER, COLORTEXT_MARKER, etc.
[in]	p	A 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);
assert(colr_check_marker(COLORARG_MARKER, cargp));
colr_free(cargp);
char* s = "Not a ColorText at all.";
assert(!colr_check_marker(COLORTEXT_MARKER, s));
ColorText* ctextp = Colr("But this is a ColorText.", fore(GREEN));
assert(colr_check_marker(COLORTEXT_MARKER, ctextp));
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]	fmt	Format 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] args The 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] matches A 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] p A 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]	joinerp	The joiner (any ColorArg, ColorText, or string (`char*`)).
[in]	ps	An array of pointers to `ColorArg`s, `ColorText`s, 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]	joinerp	The joiner (any ColorArg, ColorText, or string (`char*`)).
[in]	ps	An array of pointers to `ColorArg`s, `ColorText`s, or strings (`char*`). The array must have at least a length of `count`, unless a `NULL` element is placed at the end.
[in]	count	The 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]	x	ColorText pointer, ColorResult pointer, or string (`char*`).
[in]	width	Maximum width for the justified text, or `0` to use the terminal width.
[in]	padchar	Character 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]	s	The string to check.
[in]	length	Number 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

0	if `s` is `NULL`/empty, or `length` is `0`.
(size_t)-1	if 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 = "１３３７";
    // 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, "３７") == 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]	fp	FILE pointer for output.
[in]	info	Info from printf about how to format the argument.
[in]	args	Argument 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]	info	Info from printf about how to format the argument.
[in]	n	Number of arguments for the format char.
[out]	argtypes	Type of arguments being handled, from an `enum` defined in `printf`. Colr uses/sets one argument, a `PA_POINTER` type.
[out]	sz	Size 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) {
    colr_printf_register();
    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]	s	The string to search.
[in]	repattern	The 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]	x	ColorText pointer, ColorResult pointer, or string (`char*`).
[in]	width	Maximum width for the justified text, or `0` to use the terminal width.
[in]	padchar	Character 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]	lst	The string array to look in.
[in]	s	The 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] ps A 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] width The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().

[in] padchar The 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]	dest	Memory allocated for new string. Must have room for `strlen(src) + 1` or `length + 1`.
[in]	src	Source string to copy.
[in]	length	Maximum 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] unique Whether 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

If	`s` 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.
On	success, 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]	s	The string to check.
[in]	carg	The 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

0	if `s` is `NULL`.
COLR_HASH_SEED	if `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]	s	String to check.
[in]	c	Character 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] s The 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] width The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().

[in] padchar The 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] s The 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]	dest	Destination `char` array. Must have room for `strlen(s) + 1`.
[in]	s	String to strip the character from.
[in]	length	Length of `s`, the input string.
[in]	c	Character 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]	s	String to strip the character from.
[in]	c	Character 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]	s	The string to strip. `s` Must be `null`-terminated.
[in]	chars	A 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] s The 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 = "１３３７";
    // 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The string to replace with.
[in]	count	Number 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	target	The string to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The string to replace with.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The string to replace with.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex pattern to compile.
[in]	repl	The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex pattern to compile.
[in]	repl	The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	pattern	The regex match object to find text to replace.
[in]	repl	The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done.
[in]	re_flags	Flags 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]	s	The string to operate on.
[in]	match	The regex match object to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	match	The regex match object to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	match	The regex match object to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	match	The regex match object to find text to replace.
[in]	repl	The 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]	ref	The 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]	target	The string to modify. Must have room for the resulting string.
[in]	match	The regex match object to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	matches	Regex match objects to find text to replace. The array must have `NULL` as the last member.
[in]	repl	The 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]	s	The string to operate on.
[in]	matches	The regex match objects to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	matches	The regex match objects to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	matches	The regex match objects to find text to replace.
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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]	s	The string to operate on.
[in]	repattern	The regex pattern to match (`regex_t*`).
[in]	repl	The 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] s The 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] width The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size().

[in] padchar The 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]	s	The string to check.
[in]	prefix	The 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]	a	The first ExtendedValue to compare.
[in]	b	The 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] bval BasicValue 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

An	integer in the range `0-255` on success.
EXT_INVALID	on error (or if `s` is `NULL`).
EXT_INVALID_RANGE	if 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] hexstr Hex string to convert.

Returns: A value between 0 and 255 on success.

Return values

COLOR_INVALID on 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]	hexstr	Hex string to convert.
[in]	default_value	ExtendedValue 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] rgb RGB 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] arg Color name to find the ExtendedValue for.

Returns: A value between 0 and 255 on success.

Return values

EXT_INVALID	on error or bad values.
EXT_INVALID_RANGE	if 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] eval A 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] eval A 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] eval A 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] eval A 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]	out	Memory allocated for the escape code string. Must have enough room for `CODEX_LEN`.
[in]	value	BasicValue 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]	out	Memory allocated for the escape code string. Must have enough room for `CODE_RGB_LEN`.
[in]	rgb	RGB 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]	out	Memory allocated for the escape code string.
[in]	rgb	Pointer 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]	out	Memory allocated for the escape code string. Must have enough room for `CODEX_LEN`.
[in]	num	Value 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]	out	Memory allocated for the escape code string. Must have enough room for `CODEX_LEN`.
[in]	value	BasicValue 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]	out	Memory allocated for the escape code string.
[in]	rgb	Pointer 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]	out	Memory allocated for the escape code string.
[in]	rgb	Pointer 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]	out	Memory allocated for the escape code string. Must have enough room for `CODEX_LEN`.
[in]	num	Value 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]	out	Memory allocated for the escape code string. Must have enough room for `STYLE_LEN`.
[in]	style	StyleValue 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]	freq	Frequency ("tightness") for the colors.
[in]	offset	Starting offset in the rainbow.
[in]	spread	Number 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]	freq	Frequency ("tightness") for the colors.
[in]	offset	Starting offset in the rainbow.
[in]	spread	Number 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]	freq	Frequency ("tightness") for the colors.
[in]	offset	Starting offset in the rainbow.
[in]	spread	Number 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]	freq	Frequency ("tightness") for the colors.
[in]	offset	Starting offset in the rainbow.
[in]	spread	Number 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]	freq	Frequency ("tightness") of the colors.
[in]	offset	Starting 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] rgb The 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]	a	First RGB value to check.
[in]	b	Second 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] bval A 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] rgb Pointer to an RGB struct to fill in the values for.

Return values

<tt>0</tt>	on success, with `rgb` filled with values.
COLOR_INVALID	on error (or if `s` is `NULL`).
COLOR_INVALID_RANGE	if 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] eval An 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] rgb Pointer to an RGB struct to fill in the values for.

Return values

0	on success, with `rgb` filled with the values.
COLOR_INVALID	for 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_value An 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] rgb Pointer to an RGB struct to fill in the values for.

Return values

0	on success, with `rgb` filled with the values.
COLOR_INVALID	for non-rgb strings.
COLOR_INVALID_RANGE	for 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] rgb The 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] rgb The 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] rgb The 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] rgb RGB 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] rgb RGB 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] rgb RGB 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] rgb RGB 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]	a	The first StyleValue to compare.
[in]	b	The 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

StyleValue	value on success.
STYLE_INVALID	on error (or if `s` is `NULL`).
STYLE_INVALID_RANGE	if 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] arg Style 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] sval A 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] sval A 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] sval A 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] sval StyleValue 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] ts TermSize 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().

(0.4.0)

Functions

Variables

Detailed Description

Function Documentation

◆ _colr_free()

◆ _colr_is_last_arg()

◆ _colr_join()

◆ _colr_join_array_length()

◆ _colr_join_arrayn_size()

◆ _colr_join_size()

◆ _colr_ptr_length()

◆ _colr_ptr_repr()

◆ _colr_ptr_to_str()

◆ _rainbow()

◆ ArgType_eq()

◆ ArgType_repr()

◆ ArgType_to_str()

◆ BasicValue_eq()

◆ BasicValue_from_esc()

◆ BasicValue_from_str()

◆ BasicValue_is_invalid()

◆ BasicValue_is_valid()

◆ BasicValue_repr()

◆ BasicValue_to_ansi()

◆ BasicValue_to_str()

◆ ColorArg_empty()

◆ ColorArg_eq()

◆ ColorArg_example()

◆ ColorArg_free()

◆ ColorArg_from_BasicValue()

◆ ColorArg_from_esc()

◆ ColorArg_from_ExtendedValue()

◆ ColorArg_from_RGB()

◆ ColorArg_from_str()

◆ ColorArg_from_StyleValue()

◆ ColorArg_from_value()

◆ ColorArg_is_empty()

◆ ColorArg_is_invalid()

◆ ColorArg_is_ptr()

◆ ColorArg_is_valid()

◆ ColorArg_length()

◆ ColorArg_repr()

◆ ColorArg_to_esc()

◆ ColorArg_to_esc_s()

◆ ColorArg_to_ptr()

◆ ColorArgs_array_free()

◆ ColorArgs_array_repr()

◆ ColorArgs_from_str()

◆ ColorJustify_empty()

◆ ColorJustify_eq()

◆ ColorJustify_is_empty()

◆ ColorJustify_new()

◆ ColorJustify_repr()

◆ ColorJustifyMethod_repr()

◆ ColorResult_center()

◆ ColorResult_Colr()

◆ ColorResult_empty()

◆ ColorResult_eq()

◆ ColorResult_free()

◆ ColorResult_from_str()

◆ ColorResult_from_stra()

◆ ColorResult_is_empty()

◆ ColorResult_is_ptr()

◆ ColorResult_length()

◆ ColorResult_ljust()

◆ ColorResult_new()

◆ ColorResult_repr()

◆ ColorResult_rip_str()

◆ ColorResult_rjust()

◆ ColorResult_to_ptr()

◆ ColorResult_to_str()

◆ ColorText_empty()

◆ ColorText_free()

◆ ColorText_free_args()

◆ ColorText_from_values()

◆ ColorText_from_valuesv()

◆ ColorText_has_arg()

◆ ColorText_has_args()

◆ ColorText_is_empty()