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

(0.3.7)

Declarations for ColrC functions, enums, structs, etc. More...

#include <assert.h>
#include <ctype.h>
#include <math.h>
#include <limits.h>
#include <locale.h>
#include <printf.h>
#include <regex.h>
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/ioctl.h>
#include <unistd.h>
#include <wchar.h>
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  BasicInfo
 Holds a known color name and it's BasicValue. More...
 
struct  ColorArg
 Holds an ArgType, and a ColorValue. More...
 
struct  ColorJustify
 Holds a string justification method, width, and padding character for ColorTexts. More...
 
struct  ColorNameData
 Holds info about a known color name, like it's ExtendedValue and it's RGB value. More...
 
struct  ColorResult
 Holds a string (char*) that was definitely allocated by Colr. More...
 
union  ColorStructMarker
 Breaks down Colr struct markers, such as COLORARG_MARKER, into individual bytes. More...
 
struct  ColorStructMarker.bytes
 Individual bytes that make up the marker. More...
 
struct  ColorText
 Holds a string of text, and optional fore, back, and style ColorArgs. More...
 
struct  ColorValue
 Holds a color type and it's value. More...
 
struct  ExtendedInfo
 Holds a known color name and it's ExtendedValue. More...
 
struct  RGB
 Container for RGB values. More...
 
struct  StyleInfo
 Holds a known style name and it's StyleValue. More...
 
struct  TermSize
 Holds a terminal size, usually retrieved with colr_term_size(). More...
 

Macros

#define alloc_basic()   calloc(CODE_LEN, sizeof(char))
 Allocate enough for a basic code. More...
 
#define alloc_extended()   calloc(CODEX_LEN, sizeof(char))
 Allocate enough for an extended code. More...
 
#define alloc_rgb()   calloc(CODE_RGB_LEN, sizeof(char))
 Allocate enough for an rgb code. More...
 
#define alloc_style()   calloc(STYLE_LEN, sizeof(char))
 Allocate enough for a style code. More...
 
#define asprintf_or_return(retval, ...)   if_not_asprintf(__VA_ARGS__) return retval
 Convenience macro for bailing out of a function when asprintf fails. More...
 
#define back(x)   ColorArg_to_ptr(back_arg(x))
 Create a back color suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros. More...
 
#define back_arg(x)
 Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument. More...
 
#define back_str(x)   ColorArg_to_esc(back_arg(x))
 Return just the escape code string for a back color. More...
 
#define back_str_static(x)
 Creates a stack-allocated escape code string (char*) for a back color. More...
 
#define basic(x)   ((BasicValue)(x))
 Casts to BasicValue. More...
 
#define bool_colr_enum(x)   (x < 0 ? false: true)
 Returns the "truthiness" of the enums used in ColrC (BasicValue, ExtendedValue function-returns, StyleValue, ColorType, ArgType). More...
 
#define CODE_ANY_LEN   46
 Maximum length in chars for any possible escape code mixture for one complete style (one of each: fore, back, and style). More...
 
#define CODE_LEN   14
 Maximum length for a basic fore/back escape code, including `'\0'`. More...
 
#define CODE_LEN_MIN   5
 Minimum length for the shortest basic fore/back escape code, including `'\0'`. More...
 
#define CODE_RESET_ALL   "\x1b[0m"
 Convenience definition, because this is used a lot.
 
#define CODE_RESET_BACK   "\x1b[49m"
 Convenience definition for resetting the back color.
 
#define CODE_RESET_FORE   "\x1b[39m"
 Convenience definition for resetting the fore color.
 
#define CODE_RESET_LEN   5
 Length of CODE_RESET_ALL, including `'\0'`.
 
#define CODE_RGB_LEN   20
 Maximum length in chars for an RGB fore/back escape code, including `'\0'`.
 
#define CODE_RGB_LEN_MIN   14
 Minimum length for the shortest RGB fore/back escape code, including `'\0'`. More...
 
#define CODEX_LEN   12
 Maximum length for an extended fore/back escape code, including `'\0'`.
 
#define CODEX_LEN_MIN   10
 Minimum length for the shortest extended fore/back escape code, including `'\0'`. More...
 
#define color_arg(type, x)
 Builds a correct ColorArg struct according to the type of it's second argument. More...
 
#define COLOR_INVALID   (-2)
 Possible error return value for BasicValue_from_str(), ExtendedValue_from_str(), and colorname_to_rgb().
 
#define COLOR_INVALID_RANGE   (-3)
 Possible error return value for RGB_from_str().
 
#define COLOR_LEN   30
 Maximum length in chars for any combination of basic/extended escape codes for one complete style (one of each: fore, back, style). More...
 
#define color_name_is_invalid(x)   ColorType_is_invalid(ColorType_from_str(x))
 Convenience macro for checking if a color name is invalid. More...
 
#define color_name_is_valid(x)   ColorType_is_valid(ColorType_from_str(x))
 Convenience macro for checking if a color name is valid. More...
 
#define COLOR_RGB_LEN   26
 Maximum length in chars added to a rgb colorized string. More...
 
#define color_val(x)
 Builds a correct ColorValue struct according to the type of it's first argument. More...
 
#define COLORARG_MARKER   UINT32_MAX
 Marker for the ColorArg struct, for identifying a void pointer as a ColorArg. More...
 
#define COLORJUSTIFY_MARKER   (UINT32_MAX - 30)
 Marker for the ColorJustify struct, for identifying a void pointer as a ColorJustify.
 
#define COLORLASTARG_MARKER   (UINT32_MAX - 20)
 Marker for the _ColrLastArg_s struct, for identifying a void pointer as a _ColrLastArg_s.
 
#define COLORRESULT_MARKER   (UINT32_MAX - 40)
 Marker for the ColorResult struct, for identifying a void pointer as a ColorResult.
 
#define COLORTEXT_MARKER   (UINT32_MAX - 50)
 Marker for the ColorText struct, for identifying a void pointer as a ColorText.
 
#define ColorValue_has(cval, val)
 Call the current ColorValue_has_<type> function for the given value. More...
 
#define Colr(text, ...)   ColorText_to_ptr(ColorText_from_values(text, __VA_ARGS__, _ColrLastArg))
 Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros. More...
 
#define colr(text, ...)   colr_cat(Colr(text, __VA_ARGS__))
 Create an allocated string directly from Colr() arguments. More...
 
#define colr_alloc_len(x)
 Return the number of bytes needed to allocate an escape code string based on the color type. More...
 
#define colr_asprintf(...)   colr_printf_macro(asprintf, __VA_ARGS__)
 Ensure colr_printf_register() has been called, and then call asprintf. More...
 
#define Colr_cat(...)   ColorResult_to_ptr(ColorResult_new(colr_cat(__VA_ARGS__)))
 Like colr_cat(), but returns an allocated ColorResult that the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros will automatically free(). More...
 
#define colr_cat(...)   _colr_join("", __VA_ARGS__, _ColrLastArg)
 Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string. More...
 
#define Colr_center(text, justwidth, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define Colr_center_char(text, justwidth, c, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define colr_eq(a, b)
 Calls the <type>_eq functions for the supported types. More...
 
#define colr_example(x)
 Calls the <type>_example functions for the supported types. More...
 
#define COLR_FMT   "R"
 Format character string suitable for use in the printf-family of functions. More...
 
#define Colr_fmt(fmt, value, ...)
 Format and colorize a value like the printf-family. More...
 
#define COLR_FMT_CHAR   COLR_FMT[0]
 Character used in printf format strings for Colr objects.
 
#define COLR_FMT_MOD_ESC   "/"
 Modifier for Colr printf character to produce escaped output.
 
#define COLR_FMT_MOD_ESC_CHAR   COLR_FMT_MOD_ESC[0]
 Modifier for Colr printf character to produce escaped output, in char form.
 
#define colr_fprint(file, ...)
 Create a string from a colr_cat() call, print it to file (without a newline), and free it. More...
 
#define colr_fprintf(...)   colr_printf_macro(fprintf, __VA_ARGS__)
 Ensure colr_printf_register() has been called, and then call fprintf. More...
 
#define colr_free(x)
 Calls the <type>_free functions for the supported types. More...
 
#define COLR_GNU
 Defined when __GNUC__ is available, to enable statement-expressions and register_printf_specifier . More...
 
#define COLR_HASH_SEED   5381
 Seed value for colr_str_hash().
 
#define colr_is_empty(x)
 Calls the <type>is_empty functions for the supported types. More...
 
#define colr_is_invalid(x)
 Calls the <type>is_invalid functions for the supported types. More...
 
#define colr_is_valid(x)
 Calls the <type>is_valid functions for the supported types. More...
 
#define colr_is_valid_mblen(x)   ((x) && ((x) != (size_t)-1) && ((x) != (size_t)-2))
 Checks return values from mbrlen() and colr_mb_len(). More...
 
#define colr_istr_either(s1, s2, s3)
 Convenience macro for !strcasecmp(s1, s2) || !strcasecmp(s1, s3). More...
 
#define colr_istr_eq(s1, s2)
 Convenience macro for !strcasecmp(s1, s2). More...
 
#define Colr_join(joiner, ...)   ColrResult(colr_join(joiner, __VA_ARGS__))
 Joins Colr objects and strings, exactly like colr_join(), but returns an allocated ColorResult that the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros will automatically free() for you. More...
 
#define colr_join(joiner, ...)   _colr_join(joiner, __VA_ARGS__, _ColrLastArg)
 Join ColorArg pointers, ColorText pointers, and strings by another ColorArg pointer, ColorText pointer, or string. More...
 
#define colr_length(x)
 Calls the <type>_length functions for the supported types. More...
 
#define Colr_ljust(text, justwidth, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define Colr_ljust_char(text, justwidth, c, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define colr_max(a, b)   (a > b ? a : b)
 Macro for (a > b ? a : b). More...
 
#define colr_print(...)
 Create a string from a colr_cat() call, print it to stdout (without a newline), and free it. More...
 
#define colr_printf(...)   colr_printf_macro(printf, __VA_ARGS__)
 Ensure colr_printf_register() has been called, and then call printf. More...
 
#define colr_printf_macro(func, ...)
 Calls one of the printf-family functions, with format warnings disabled for the call, and returns the result. More...
 
#define colr_puts(...)
 Create a string from a colr_cat() call, print it (with a newline), and free it. More...
 
#define colr_replace(s, target, repl)
 Replace a substring in s with another string, ColorArg string, ColorResult string, or ColorText string. More...
 
#define colr_replace_all(s, target, repl)
 Replace all substrings in s with another string, ColorArg string, ColorResult string, or ColorText string. More...
 
#define colr_replace_re(s, target, repl, flags)
 Replace a regex pattern string (char*) in s with another string, ColorArg string, ColorResult string, or ColorText string. More...
 
#define colr_replace_re_all(s, target, repl, flags)
 Replace all matches to a regex pattern string (char*) in s with another string, ColorArg string, ColorResult string, or ColorText string. More...
 
#define colr_repr(x)
 Transforms several ColrC objects into their string representations. More...
 
#define Colr_rjust(text, justwidth, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define Colr_rjust_char(text, justwidth, c, ...)
 Sets the JustifyMethod for a ColorText while allocating it. More...
 
#define colr_snprintf(...)   colr_printf_macro(snprintf, __VA_ARGS__)
 Ensure colr_printf_register() has been called, and then call snprintf. More...
 
#define colr_sprintf(...)   colr_printf_macro(sprintf, __VA_ARGS__)
 Ensure colr_printf_register() has been called, and then call sprintf. More...
 
#define colr_str_either(s1, s2, s3)   (colr_str_eq(s1, s2) || colr_str_eq(s1, s3))
 Convenience macro for !strcmp(s1, s2) || !strcmp(s1, s3). More...
 
#define colr_str_eq(s1, s2)
 Convenience macro for !strcmp(s1, s2). More...
 
#define colr_to_str(x)
 Calls the <type>_to_str functions for the supported types. More...
 
#define COLR_VERSION   "0.3.7"
 Current version for ColrC.
 
#define Colra(text, ...)   ColorText_from_values(text, __VA_ARGS__, _ColrLastArg)
 Returns an initialized stack-allocated ColorText. More...
 
#define ColrColorResult(cres, ...)   ColorResult_Colr(cres, __VA_ARGS__, _ColrLastArg)
 Like Colr(), but it operates on a ColorResult to generate a new colorized ColorResult. More...
 
#define ColrResult(s)   ColorResult_to_ptr(ColorResult_new(s))
 Wraps an allocated string in a ColorResult, which marks it as "freeable" in the colr macros. More...
 
#define ext(x)   ((ExtendedValue)x)
 Casts to ExtendedValue (unsigned char). More...
 
#define ext_hex(s)   ext_hex_or(s, ext(0))
 Like hex(), but force a conversion to the closest ExtendedValue (256-colors). More...
 
#define ext_hex_or(s, default_value)   ExtendedValue_from_hex_default(s, default_value)
 Like hex_or(), but force a conversion to the closest ExtendedValue (256-colors). More...
 
#define EXT_INVALID   COLOR_INVALID
 Alias for COLOR_INVALID. More...
 
#define EXT_INVALID_RANGE   COLOR_INVALID_RANGE
 Possible error return value for ExtendedValue_from_str() or ExtendedValue_from_esc(). More...
 
#define ext_rgb(r, g, b)   ExtendedValue_from_RGB((RGB){.red=r, .green=g, .blue=b})
 Creates the closest matching ExtendedValue from separate red, green, and blue values. More...
 
#define ext_RGB(rgbval)   ExtendedValue_from_RGB(rgbval)
 Creates the closest matching ExtendedValue from an RGB value. More...
 
#define fore(x)   ColorArg_to_ptr(fore_arg(x))
 Create a fore color suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros. More...
 
#define fore_arg(x)
 Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument. More...
 
#define fore_str(x)   ColorArg_to_esc(fore_arg(x))
 Return just the escape code string for a fore color. More...
 
#define fore_str_static(x)
 Creates a stack-allocated escape code string (char*) for a fore color. More...
 
#define hex(s)   hex_or(s, rgb(0, 0, 0))
 Use RGB_from_hex_default() to create an RGB value. More...
 
#define hex_or(s, default_rgb)   RGB_from_hex_default(s, default_rgb)
 Use RGB_from_hex_default() to create an RGB value. More...
 
#define if_not_asprintf(...)   if (asprintf(__VA_ARGS__) < 1)
 Convenience macro for checking asprintf's return value. More...
 
#define NC   CODE_RESET_ALL
 Short-hand for CODE_RESET_ALL, stands for "No Color".
 
#define NCNL   CODE_RESET_ALL "\n"
 Short-hand for CODE_RESET_ALL "\n", stands for "No Color, New Line".
 
#define rgb(r, g, b)   ((RGB){.red=r, .green=g, .blue=b})
 Creates an anonymous RGB struct for use in function calls. More...
 
#define style(x)   ColorArg_to_ptr(style_arg(x))
 Create a style suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros. More...
 
#define style_arg(x)
 Uses ColorArg_from_StyleValue to build a ColorArg with the appropriate color type/value. More...
 
#define STYLE_LEN   6
 Maximum length for a style escape code, including `'\0'`.
 
#define STYLE_LEN_MIN   5
 Minimum length for the shortest style escape code, including `'\0'`. More...
 
#define STYLE_MAX_VALUE   ((StyleValue)OVERLINE)
 Maximum value allowed for a StyleValue.
 
#define STYLE_MIN_VALUE   ((StyleValue)STYLE_INVALID_RANGE)
 Minimum value allowed for a StyleValue.
 
#define style_str(x)   ColorArg_to_esc(style_arg(x))
 Return just the escape code string for a style. More...
 
#define style_str_static(x)
 A less-flexible style_str() that returns a static escape code string for a style. More...
 
#define WCODE_RESET_ALL   L"\x1b[0m"
 Convenience definition for wide chars.
 
#define WCODE_RESET_BACK   L"\x1b[49m"
 Convenience definition for resetting the back color.
 
#define WCODE_RESET_FORE   L"\x1b[39m"
 Convenience definition for resetting the fore color.
 
#define while_colr_va_arg(ap, vartype, x)   while (x = va_arg(ap, vartype), !_colr_is_last_arg(x))
 Construct a while-loop over a va_list, where the last argument is expected to be _ColrLastArg, or a pointer to a _ColrLastArg_s with the same values as _ColrLastArg. More...
 
#define WNC   WCODE_RESET_ALL
 Short-hand for WCODE_RESET_ALL, stands for "Wide No Color".
 
#define WNCNL   WCODE_RESET_ALL L"\n"
 Short-hand for WCODE_RESET_ALL "\n", stands for "Wide No Color, New Line".
 

Typedefs

typedef unsigned char ExtendedValue
 Convenience typedef for clarity when dealing with extended (256) colors.
 
typedef char *(* rainbow_creator) (const char *s, double freq, size_t offset, size_t spread)
 A function type that knows how to create rainbowized text.
 
typedef void(* RGB_fmter) (char *out, RGB rgb)
 A function type that knows how to fill a string with an rgb escape code. More...
 

Enumerations

enum  ArgType {
  ARGTYPE_NONE = -1,
  FORE = 0,
  BACK = 1,
  STYLE = 2
}
 Argument types (fore, back, style).
 
enum  BasicValue {
  BASIC_INVALID_RANGE = COLOR_INVALID_RANGE,
  BASIC_INVALID = COLOR_INVALID,
  BASIC_NONE = -1,
  BLACK = 0,
  RED = 1,
  GREEN = 2,
  YELLOW = 3,
  BLUE = 4,
  MAGENTA = 5,
  CYAN = 6,
  WHITE = 7,
  UNUSED = 8,
  RESET = 9,
  LIGHTBLACK = 10,
  LIGHTRED = 11,
  LIGHTGREEN = 12,
  LIGHTYELLOW = 13,
  LIGHTBLUE = 14,
  LIGHTMAGENTA = 15,
  LIGHTCYAN = 16,
  LIGHTWHITE = 17
}
 Basic color values, with a few convenience values for extended colors. More...
 
enum  ColorJustifyMethod {
  JUST_NONE = -1,
  JUST_LEFT = 0,
  JUST_RIGHT = 1,
  JUST_CENTER = 2
}
 Justification style for ColorTexts.
 
enum  ColorType {
  TYPE_NONE = -6,
  TYPE_INVALID_STYLE = -5,
  TYPE_INVALID_RGB_RANGE = -4,
  TYPE_INVALID_EXT_RANGE = COLOR_INVALID_RANGE,
  TYPE_INVALID = COLOR_INVALID,
  TYPE_BASIC = 0,
  TYPE_EXTENDED = 1,
  TYPE_RGB = 2,
  TYPE_STYLE = 3
}
 Color/Style code types. Used with ColorType_from_str() and ColorValue.
 
enum  StyleValue {
  STYLE_INVALID_RANGE = COLOR_INVALID_RANGE,
  STYLE_INVALID = COLOR_INVALID,
  STYLE_NONE = -1,
  RESET_ALL = 0,
  BRIGHT = 1,
  DIM = 2,
  ITALIC = 3,
  UNDERLINE = 4,
  FLASH = 5,
  HIGHLIGHT = 7,
  STRIKETHRU = 9,
  NORMAL = 22,
  FRAME = 51,
  ENCIRCLE = 52,
  OVERLINE = 53
}
 Style values.
 

Functions

void _colr_free (void *p)
 Calls Colr *_free() functions for Colr objects, otherwise just calls free(). More...
 
bool _colr_is_last_arg (void *p)
 Determines if a void pointer is _ColrLastArg (the last-arg-marker). More...
 
char * _colr_join (void *joinerp,...)
 Joins ColorArgs, ColorTexts, and strings (char*) into one long string separated by it's first argument. More...
 
size_t _colr_join_array_length (void *ps)
 Determine the length of a NULL-terminated array of strings (char*), ColorArgs, ColorResults, or ColorTexts. More...
 
size_t _colr_join_arrayn_size (void *joinerp, void *ps, size_t count)
 Get the size in bytes needed to join an array of strings (char*), ColorArgs, ColorResults, or ColorTexts by another string (char*), ColorArg, ColorResult, or ColorText. More...
 
size_t _colr_join_size (void *joinerp, va_list args)
 Parse arguments, just as in _colr_join(), but only return the size needed to allocate the resulting string. More...
 
size_t _colr_ptr_length (void *p)
 Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char*) into a string. More...
 
char * _colr_ptr_repr (void *p)
 Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obtain an allocated string representation. More...
 
char * _colr_ptr_to_str (void *p)
 Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to obtain an allocated string. More...
 
char * _rainbow (RGB_fmter fmter, const char *s, double freq, size_t offset, size_t spread)
 Handles multibyte character string (char*) conversion and character iteration for all of the rainbow_ functions. More...
 
bool ArgType_eq (ArgType a, ArgType b)
 Compares two ArgTypes. More...
 
char * ArgType_repr (ArgType type)
 Creates a string (char*) representation of a ArgType. More...
 
char * ArgType_to_str (ArgType type)
 Creates a human-friendly string (char*) from an ArgType. More...
 
bool BasicValue_eq (BasicValue a, BasicValue b)
 Compares two BasicValues. More...
 
BasicValue BasicValue_from_esc (const char *s)
 Convert an escape-code string (char*) to an actual BasicValue enum value. More...
 
BasicValue BasicValue_from_str (const char *arg)
 Convert named argument to an actual BasicValue enum value. More...
 
bool BasicValue_is_invalid (BasicValue bval)
 Determines whether a BasicValue is invalid. More...
 
bool BasicValue_is_valid (BasicValue bval)
 Determines whether a BasicValue is valid. More...
 
char * BasicValue_repr (BasicValue bval)
 Creates a string (char*) representation of a BasicValue. More...
 
int BasicValue_to_ansi (ArgType type, BasicValue bval)
 Converts a fore/back BasicValue to the actual ansi code number. More...
 
char * BasicValue_to_str (BasicValue bval)
 Create a human-friendly string (char*) representation for a BasicValue. More...
 
ColorArg ColorArg_empty (void)
 Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE. More...
 
bool ColorArg_eq (ColorArg a, ColorArg b)
 Compares two ColorArg structs. More...
 
char * ColorArg_example (ColorArg carg, bool colorized)
 Create a string (char*) representation of a ColorArg with a stylized type/name using escape codes built from the ColorArg's values. More...
 
void ColorArg_free (ColorArg *p)
 Free allocated memory for a ColorArg. More...
 
ColorArg ColorArg_from_BasicValue (ArgType type, BasicValue value)
 Explicit version of ColorArg_from_value that only handles BasicValues. More...
 
ColorArg ColorArg_from_esc (const char *s)
 Parse an escape-code string (char*) into a ColorArg. More...
 
ColorArg ColorArg_from_ExtendedValue (ArgType type, ExtendedValue value)
 Explicit version of ColorArg_from_value that only handles ExtendedValues. More...
 
ColorArg ColorArg_from_RGB (ArgType type, RGB value)
 Explicit version of ColorArg_from_value that only handles RGB structs. More...
 
ColorArg ColorArg_from_str (ArgType type, const char *colorname)
 Build a ColorArg (fore, back, or style value) from a known color name/style. More...
 
ColorArg ColorArg_from_StyleValue (ArgType type, StyleValue value)
 Explicit version of ColorArg_from_value that only handles StyleValues. More...
 
ColorArg ColorArg_from_value (ArgType type, ColorType colrtype, void *p)
 Used with the color_arg macro to dynamically create a ColorArg based on it's argument type. More...
 
bool ColorArg_is_empty (ColorArg carg)
 Checks to see if a ColorArg is an empty placeholder. More...
 
bool ColorArg_is_invalid (ColorArg carg)
 Checks to see if a ColorArg holds an invalid value. More...
 
bool ColorArg_is_ptr (void *p)
 Checks a void pointer to see if it contains a ColorArg struct. More...
 
bool ColorArg_is_valid (ColorArg carg)
 Checks to see if a ColorArg holds a valid value. More...
 
size_t ColorArg_length (ColorArg carg)
 Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc(). More...
 
char * ColorArg_repr (ColorArg carg)
 Creates a string (char*) representation for a ColorArg. More...
 
char * ColorArg_to_esc (ColorArg carg)
 Converts a ColorArg into an escape code string (char*). More...
 
bool ColorArg_to_esc_s (char *dest, ColorArg carg)
 Converts a ColorArg into an escape code string (char*) and fills the destination string. More...
 
ColorArgColorArg_to_ptr (ColorArg carg)
 Copies a ColorArg into memory and returns the pointer. More...
 
void ColorArgs_array_free (ColorArg **ps)
 Free an allocated array of ColorArgs, including the array itself. More...
 
char * ColorArgs_array_repr (ColorArg **lst)
 Creates a string representation for an array of ColorArg pointers. More...
 
ColorArg ** ColorArgs_from_str (const char *s, bool unique)
 Create an array of ColorArgs from escape-codes found in a string (char*). More...
 
ColorJustify ColorJustify_empty (void)
 Creates an "empty" ColorJustify, with JUST_NONE set. More...
 
bool ColorJustify_eq (ColorJustify a, ColorJustify b)
 Compares two ColorJustify structs. More...
 
bool ColorJustify_is_empty (ColorJustify cjust)
 Checks to see if a ColorJustify is "empty". More...
 
ColorJustify ColorJustify_new (ColorJustifyMethod method, int width, char padchar)
 Creates a ColorJustify. More...
 
char * ColorJustify_repr (ColorJustify cjust)
 Creates a string (char*) representation for a ColorJustify. More...
 
char * ColorJustifyMethod_repr (ColorJustifyMethod meth)
 Creates a string (char*) representation for a ColorJustifyMethod. More...
 
ColorResultColorResult_Colr (ColorResult *cres,...)
 Colorize a ColorResult, and return a new allocated ColorResult. More...
 
ColorResult ColorResult_empty (void)
 Creates a ColorResult with .result=NULL and .length=-1, with the appropriate struct marker. More...
 
bool ColorResult_eq (ColorResult a, ColorResult b)
 Compares two ColorResults. More...
 
void ColorResult_free (ColorResult *p)
 Free allocated memory for a ColorResult and it's .result member. More...
 
ColorResult ColorResult_from_str (const char *s)
 Allocates a copy of a string, and creates a ColorResult from it. More...
 
ColorResultColorResult_from_stra (const char *s)
 Allocates a copy of a string, and creates an allocated ColorResult from it. More...
 
bool ColorResult_is_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_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...
 
ColorResultColorResult_to_ptr (ColorResult cres)
 Allocate memory for a ColorResult, fill it, and return it. More...
 
char * ColorResult_to_str (ColorResult cres)
 Convert a ColorResult into a string (char*). More...
 
ColorText ColorText_empty (void)
 Creates an "empty" ColorText with pointers set to NULL. More...
 
void ColorText_free (ColorText *p)
 Frees a ColorText and it's ColorArgs. More...
 
void ColorText_free_args (ColorText *p)
 Frees the ColorArg members of a ColorText. More...
 
ColorText ColorText_from_values (char *text,...)
 Builds a ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More...
 
ColorText ColorText_from_valuesv (char *text, va_list args)
 Builds a ColorText from 1 mandatory string (char*), and a va_list with optional fore, back, and style args (pointers to ColorArgs). More...
 
bool ColorText_has_arg (ColorText ctext, ColorArg carg)
 Checks to see if a ColorText has a certain ColorArg value set. More...
 
bool ColorText_has_args (ColorText ctext)
 Checks to see if a ColorText has any argument values set. More...
 
bool ColorText_is_empty (ColorText ctext)
 Checks to see if a ColorText has no usable values. More...
 
bool ColorText_is_ptr (void *p)
 Checks a void pointer to see if it contains a ColorText struct. More...
 
size_t ColorText_length (ColorText ctext)
 Returns the length in bytes needed to allocate a string (char*) built with ColorText_to_str() with the current text, fore, back, and style members. More...
 
char * ColorText_repr (ColorText ctext)
 Allocate a string (char*) representation for a ColorText. More...
 
ColorTextColorText_set_just (ColorText *ctext, ColorJustify cjust)
 Set the ColorJustify method for a ColorText, and return the ColorText. More...
 
void ColorText_set_values (ColorText *ctext, char *text,...)
 Initializes an existing ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More...
 
ColorTextColorText_to_ptr (ColorText ctext)
 Copies a ColorText into allocated memory and returns the pointer. More...
 
char * ColorText_to_str (ColorText ctext)
 Stringifies a ColorText struct, creating a mix of escape codes and text. More...
 
bool ColorType_eq (ColorType a, ColorType b)
 Compares two ColorTypes. More...
 
ColorType ColorType_from_str (const char *arg)
 Determine which type of color value is desired by name. More...
 
bool ColorType_is_invalid (ColorType type)
 Check to see if a ColorType value is considered invalid. More...
 
bool ColorType_is_valid (ColorType type)
 Check to see if a ColorType value is considered valid. More...
 
char * ColorType_repr (ColorType type)
 Creates a string (char*) representation of a ColorType. More...
 
char * ColorType_to_str (ColorType type)
 Create a human-friendly string (char*) representation for a ColorType. More...
 
ColorValue ColorValue_empty (void)
 Create an "empty" ColorValue. More...
 
bool ColorValue_eq (ColorValue a, ColorValue b)
 Compares two ColorValue structs. More...
 
char * ColorValue_example (ColorValue cval)
 Create a string (char*) representation of a ColorValue with a human-friendly type/name. More...
 
ColorValue ColorValue_from_esc (const char *s)
 Convert an escape-code string (char*) into a ColorValue. More...
 
ColorValue ColorValue_from_str (const char *s)
 Create a ColorValue from a known color name, or RGB string (char*). More...
 
ColorValue ColorValue_from_value (ColorType type, void *p)
 Used with the color_val macro to dynamically create a ColorValue based on it's argument type. More...
 
bool ColorValue_has_BasicValue (ColorValue cval, BasicValue bval)
 Checks to see if a ColorValue has a BasicValue set. More...
 
bool ColorValue_has_ExtendedValue (ColorValue cval, ExtendedValue eval)
 Checks to see if a ColorValue has a ExtendedValue set. More...
 
bool ColorValue_has_RGB (ColorValue cval, RGB rgb)
 Checks to see if a ColorValue has a RGB value set. More...
 
bool ColorValue_has_StyleValue (ColorValue cval, StyleValue sval)
 Checks to see if a ColorValue has a StyleValue set. More...
 
bool ColorValue_is_empty (ColorValue cval)
 Checks to see if a ColorValue is an empty placeholder. More...
 
bool ColorValue_is_invalid (ColorValue cval)
 Checks to see if a ColorValue holds an invalid value. More...
 
bool ColorValue_is_valid (ColorValue cval)
 Checks to see if a ColorValue holds a valid value. More...
 
size_t ColorValue_length (ArgType type, ColorValue cval)
 Returns the length in bytes needed to allocate a string (char*) built with ColorValue_to_esc() with the specified ArgType and ColorValue. More...
 
char * ColorValue_repr (ColorValue cval)
 Creates a string (char*) representation of a ColorValue. More...
 
char * ColorValue_to_esc (ArgType type, ColorValue cval)
 Converts a ColorValue into an escape code string (char*). More...
 
bool ColorValue_to_esc_s (char *dest, ArgType type, ColorValue cval)
 Converts a ColorValue into an escape code string (char*) and fills the destination string. More...
 
regmatch_t * colr_alloc_regmatch (regmatch_t match)
 Allocates space for a regmatch_t, initializes it, and returns a pointer to it. More...
 
void colr_append_reset (char *s)
 Appends CODE_RESET_ALL to a string (char*), but makes sure to do it before any newlines. More...
 
char colr_char_escape_char (const char c)
 Returns the char needed to represent an escape sequence in C. More...
 
bool colr_char_in_str (const char *s, const char c)
 Determines if a character exists in the given string (char*). More...
 
bool colr_char_is_code_end (const char c)
 Determines if a character is suitable for an escape code ending. More...
 
char * colr_char_repr (char c)
 Creates a string (char*) representation for a char. More...
 
bool colr_char_should_escape (const char c)
 Determines if an ascii character has an escape sequence in C. More...
 
bool colr_check_marker (uint32_t marker, void *p)
 Checks an unsigned int against the individual bytes behind a pointer's value. More...
 
char * colr_empty_str (void)
 Allocates an empty string (char*). More...
 
ColorResultColr_fmt_str (const char *fmt,...)
 Allocate and format a string like asprintf, but wrap it in an allocated ColorResult. More...
 
void colr_free_argsv (va_list args)
 Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list. More...
 
void colr_free_re_matches (regmatch_t **matches)
 Free an array of allocated regmatch_t, like the return from colr_re_matches(). More...
 
bool colr_is_colr_ptr (void *p)
 Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer. More...
 
char * colr_join_array (void *joinerp, void *ps)
 Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText. More...
 
char * colr_join_arrayn (void *joinerp, void *ps, size_t count)
 Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText. More...
 
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...
 
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...
 
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

int colr_printf_esc_mod
 Integer to test for the presence of the "escaped output modifier" in colr_printf_handler. More...
 

Detailed Description

Declarations for ColrC functions, enums, structs, etc.

Common macros and definitions are found here in colr.h, however the functions are documented in colr.c.


Data Structure Documentation

◆ BasicInfo

struct BasicInfo

Holds a known color name and it's BasicValue.

This is used for the basic_names array in colr.c.

Data Fields
char * name
BasicValue value

◆ ColorArg

struct ColorArg

Holds an ArgType, and a ColorValue.

Collaboration diagram for ColorArg:
Data Fields
uint32_t marker A marker used to inspect void pointers and determine if they are ColorArgs.
ArgType type Fore, back, style, invalid.
ColorValue value Color type and value.

◆ ColorJustify

struct ColorJustify

Holds a string justification method, width, and padding character for ColorTexts.

Data Fields
uint32_t marker A marker used to inspect void pointers and determine if they are ColorJustifys.
ColorJustifyMethod method The justification method, can be JUST_NONE.
char padchar The desired padding character, or 0 to use the default (`' '`).
int width The desired width for the final string, or 0 to use colr_term_size().

◆ ColorNameData

struct ColorNameData

Holds info about a known color name, like it's ExtendedValue and it's RGB value.

Some of the names have the same ExtendedValue, and not all ExtendedValues have names.

This is used in the colr_name_data array.

Collaboration diagram for ColorNameData:
Data Fields
ExtendedValue ext ExtendedValue (256-colors) for the color.
char * name The known name of the color.
RGB rgb RGB (TrueColor) for the color.

◆ ColorResult

struct ColorResult

Holds a string (char*) that was definitely allocated by Colr.

Examples:
ColorResult_example.c.
Data Fields
size_t length A length in bytes for the string result.

Set when the ColorResult is initialized with a string (ColorResult_new()). Initially set to -1.

uint32_t marker A marker used to inspect void pointers and determine if they are ColorResults.
char * result A string (char*) result from one of the colr functions.

◆ ColorStructMarker

union ColorStructMarker

Breaks down Colr struct markers, such as COLORARG_MARKER, into individual bytes.

Data Fields
struct ColorStructMarker bytes Individual bytes that make up the marker.
uint32_t marker The actual uint32_t marker value.

◆ ColorStructMarker.bytes

struct ColorStructMarker.bytes

Individual bytes that make up the marker.

Data Fields
uint8_t b1
uint8_t b2
uint8_t b3
uint8_t b4

◆ ColorText

struct ColorText

Holds a string of text, and optional fore, back, and style ColorArgs.

Examples:
colr_join_example.c, and simple_example.c.
Collaboration diagram for ColorText:
Data Fields
ColorArg * back ColorArg for back color. Can be NULL.
ColorArg * fore ColorArg for fore color. Can be NULL.
ColorJustify just ColorJustify info, set to JUST_NONE by default.
uint32_t marker A marker used to inspect void pointers and determine if they are ColorTexts.
ColorArg * style ColorArg for style value. Can be NULL.
char * text Text to colorize.

◆ ColorValue

struct ColorValue

Holds a color type and it's value.

The .type member must always match the type of color value it is holding.

This is internal. It's used to make the final interface easier to use. You probably shouldn't be using it.

Collaboration diagram for ColorValue:
Data Fields
BasicValue basic
ExtendedValue ext
RGB rgb
StyleValue style
ColorType type

◆ ExtendedInfo

struct ExtendedInfo

Holds a known color name and it's ExtendedValue.

This is used for the basic_names array in colr.c.

Data Fields
char * name
ExtendedValue value

◆ RGB

struct RGB

Container for RGB values.

Data Fields
unsigned char blue Blue value for a color.
unsigned char green Green value for a color.
unsigned char red Red value for a color.

◆ StyleInfo

struct StyleInfo

Holds a known style name and it's StyleValue.

This is used for the style_names array in colr.c.

Data Fields
char * name
StyleValue value

◆ TermSize

struct TermSize

Holds a terminal size, usually retrieved with colr_term_size().

Data Fields
unsigned short columns
unsigned short rows

Macro Definition Documentation

◆ alloc_basic

#define alloc_basic ( )    calloc(CODE_LEN, sizeof(char))

Allocate enough for a basic code.

Returns

Pointer to the allocated string, or NULL on error.

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

◆ alloc_extended

#define alloc_extended ( )    calloc(CODEX_LEN, sizeof(char))

Allocate enough for an extended code.

Returns

Pointer to the allocated string, or NULL on error.

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

◆ alloc_rgb

#define alloc_rgb ( )    calloc(CODE_RGB_LEN, sizeof(char))

Allocate enough for an rgb code.

Returns

Pointer to the allocated string, or NULL on error.

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

◆ alloc_style

#define alloc_style ( )    calloc(STYLE_LEN, sizeof(char))

Allocate enough for a style code.

Returns

Pointer to the allocated string, or NULL on error.

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

◆ asprintf_or_return

◆ back

#define back (   x)    ColorArg_to_ptr(back_arg(x))

Create a back color suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros.

Technically, this macro accepts BasicValues, ExtendedValues, or RGB structs. However, for some of these you should be using the macros that create those things.

BasicValues can be used by their names (RED, YELLOW, etc.).

ExtendedValues can be created on the fly with ext().

RGB structs can be easily created with rgb().

Color names (char*) can be passed to generate the appropriate color value.

Parameters
[in]xA BasicValue, ExtendedValue, or RGB struct to use for the color value.
Returns
A pointer to a heap-allocated ColorArg struct.
If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().
See also
back_arg
back_str
colr
Colr
Examples:
back_example.c, ColorResult_example.c, Colr_example.c, fore_example.c, and simple_example.c.

◆ back_arg

#define back_arg (   x)
Value:
_Generic( \
(x), \
char* : ColorArg_from_str, \
)(BACK, x)
ColorArg ColorArg_from_str(ArgType type, const char *colorname)
Build a ColorArg (fore, back, or style value) from a known color name/style.
Definition: colr.c:5327
ColorArg ColorArg_from_ExtendedValue(ArgType type, ExtendedValue value)
Explicit version of ColorArg_from_value that only handles ExtendedValues.
Definition: colr.c:5226
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
ColorArg ColorArg_from_RGB(ArgType type, RGB value)
Explicit version of ColorArg_from_value that only handles RGB structs.
Definition: colr.c:5249
ColorArg ColorArg_from_StyleValue(ArgType type, StyleValue value)
Explicit version of ColorArg_from_value that only handles StyleValues.
Definition: colr.c:5366
Container for RGB values.
Definition: colr.h:2614
ColorArg ColorArg_from_BasicValue(ArgType type, BasicValue value)
Explicit version of ColorArg_from_value that only handles BasicValues.
Definition: colr.c:5203
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
StyleValue
Style values.
Definition: colr.h:2628

Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument.

Uses _Generic (C11 standard) to dynamically create a ColorArg. This is used by the back() macro.

Parameters
[in]xBasicValue, Extended (unsigned char), RGB struct, or string (color name) for back color.
Returns
A ColorArg with the BACK type set, and it's .value.type set for the appropriate color type/value.
For invalid values the .value.type may be set to TYPE_INVALID.
You must free() the memory allocated by this function.
See also
back
back_str

◆ back_str

#define back_str (   x)    ColorArg_to_esc(back_arg(x))

Return just the escape code string for a back color.

Parameters
[in]xA BasicValue, ExtendedValue, or RGB struct.
Returns

An allocated string.

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

See also
back
back_arg

◆ back_str_static

#define back_str_static (   x)
Value:
__extension__ ({ \
__typeof(x) _bss_val = x; \
ColorArg _bss_carg = back_arg(_bss_val); \
size_t _bss_len = ColorArg_length(_bss_carg); \
char* _bss_codes = alloca(_bss_len); \
ColorArg_to_esc_s(_bss_codes, _bss_carg); \
_bss_codes; \
})
#define back_arg(x)
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of i...
Definition: colr.h:476
size_t ColorArg_length(ColorArg carg)
Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc().
Definition: colr.c:5475

Creates a stack-allocated escape code string (char*) for a back color.

These are not constant strings, but they are stored on the stack. A Statement Expression is used to build a string of the correct length and content using ColorArg_to_esc_s().

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Warning
This uses alloca to reserve space on the stack inside of a Statement Expression. A Variable Length Array will not work inside of a statement expression. If the call causes a stack overflow, program behavior is undefined. See previous links, and here.

You can also create stack-allocated escape code strings using format_bg(), format_bgx(), format_bg_RGB(), and format_bg_RGB_term().

Parameters
[in]xA BasicValue, ExtendedValue, or RGB value.
Returns
A stack-allocated escape code string.
See also
back_str_static
style_str_static
format_fg
format_bg
◆  back_str_static example:
// This results in a call to sprintf(), to format an extended escape code.
// The string is stored on the stack.
char* backwhite = back_str_static(WHITE);
char* foreblue = fore_str_static(BLUE);
printf("%s%sBlue on White." NCNL, backwhite, foreblue);
RGB rgbval = rgb(255, 34, 0);
printf("%sA reddish." NCNL, back_str_static(rgbval));
printf("%sAquaMarine." NCNL, back_str_static("aquamarine"));

◆ basic

#define basic (   x)    ((BasicValue)(x))

Casts to BasicValue.

Parameters
[in]xValue to case to BasicValue.
Returns
A BasicValue.
See also
fore
back
colr
Colr

◆ bool_colr_enum

#define bool_colr_enum (   x)    (x < 0 ? false: true)

Returns the "truthiness" of the enums used in ColrC (BasicValue, ExtendedValue function-returns, StyleValue, ColorType, ArgType).

Any value less than 0 is considered false.

Parameters
[in]xAn enum to convert to boolean.
Return values
trueif the value is considered valid, or non-empty.
falseif the value is considered invalid, or empty.

Referenced by ColorArg_is_invalid(), ColorArg_is_valid(), ColorType_is_invalid(), ColorType_is_valid(), ColorValue_is_invalid(), and ColorValue_is_valid().

◆ CODE_ANY_LEN

#define CODE_ANY_LEN   46

Maximum length in chars for any possible escape code mixture for one complete style (one of each: fore, back, and style).

(basically (CODE_RGB_LEN * 2) + STYLE_LEN since rgb codes are the longest).

Examples:
colr_printf_example.c.

Referenced by colr_str_has_ColorArg().

◆ CODE_LEN

#define CODE_LEN   14

Maximum length for a basic fore/back escape code, including `'\0'`.

Keep in mind that BasicValue actually has some "light" colors (104).

Referenced by format_bg(), and format_fg().

◆ CODE_LEN_MIN

#define CODE_LEN_MIN   5

Minimum length for the shortest basic fore/back escape code, including `'\0'`.

Use CODE_LEN for allocation.

◆ CODE_RGB_LEN_MIN

#define CODE_RGB_LEN_MIN   14

Minimum length for the shortest RGB fore/back escape code, including `'\0'`.

Use CODE_RGB_LEN for allocation.

◆ CODEX_LEN_MIN

#define CODEX_LEN_MIN   10

Minimum length for the shortest extended fore/back escape code, including `'\0'`.

Use CODEX_LEN for allocation.

◆ color_arg

#define color_arg (   type,
 
)
Value:
_Generic( \
(x), \
char*: ColorArg_from_str(type, x), \
BasicValue: ColorArg_from_value(type, TYPE_BASIC, &x), \
ExtendedValue: ColorArg_from_value(type, TYPE_EXTENDED, &x), \
StyleValue: ColorArg_from_value(type, TYPE_STYLE, &x), \
RGB: ColorArg_from_value(type, TYPE_RGB, &x) \
)
ColorArg ColorArg_from_str(ArgType type, const char *colorname)
Build a ColorArg (fore, back, or style value) from a known color name/style.
Definition: colr.c:5327
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
ColorArg ColorArg_from_value(ArgType type, ColorType colrtype, void *p)
Used with the color_arg macro to dynamically create a ColorArg based on it&#39;s argument type...
Definition: colr.c:5395
Container for RGB values.
Definition: colr.h:2614
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
StyleValue
Style values.
Definition: colr.h:2628

Builds a correct ColorArg struct according to the type of it's second argument.

Uses _Generic (C11 standard) to dynamically create a ColorArg.

Parameters
[in]typeArgType (FORE, BACK, STYLE) to build the ColorArg.
[in]xBasicValue, Extended (unsigned char). or RGB value.
Returns
ColorArg_from_value(type, [appropriate type], x)

◆ COLOR_LEN

#define COLOR_LEN   30

Maximum length in chars for any combination of basic/extended escape codes for one complete style (one of each: fore, back, style).

Should be (CODEX_LEN * 2) + STYLE_LEN. Allocating for a string that will be colorized must account for this.

◆ color_name_is_invalid

#define color_name_is_invalid (   x)    ColorType_is_invalid(ColorType_from_str(x))

Convenience macro for checking if a color name is invalid.

Parameters
[in]xstring (char*) to check (a name, hex-string, rgb-string, or integer-string).
Returns
true if the name is an invalid color name, otherwise false.
See also
color_name_is_valid
◆  color_name_is_invalid example:
char* names[] = {
// Valid names:
"red",
"lightblue",
"127",
"123,54,67",
"#ff0000",
"#fff",
"aliceblue",
// Invalid names:
"NOTACOLOR",
// Invalid range (not 0-255):
"345",
// Bad RGB strings:
"1;",
"1;2;",
// Bad RGB ranges:
"345;345;345",
"-1;0;0",
"0;0;256",
};
size_t names_len = sizeof(names) / sizeof(names[0]);
for (size_t i = 0; i < names_len; i++) {
if (color_name_is_invalid(names[i])) {
printf("Invalid name: %s\n", names[i]);
} else {
printf(" Valid name: %s\n", names[i]);
}
}

◆ color_name_is_valid

#define color_name_is_valid (   x)    ColorType_is_valid(ColorType_from_str(x))

Convenience macro for checking if a color name is valid.

Parameters
[in]xstring (char*) to check (a name, hex-string, rgb-string, or integer-string).
Returns
true if the name is a valid color name, otherwise false.
See also
color_name_is_invalid
◆  color_name_is_valid example:
char* names[] = {
// Valid names:
"red",
"lightblue",
"127",
"123,54,67",
"#ff0000",
"#fff",
"aliceblue",
// Invalid names:
"NOTACOLOR",
// Invalid range (not 0-255):
"345",
// Bad RGB strings:
"1;",
"1;2;",
// Bad RGB ranges:
"345;345;345",
"-1;0;0",
"0;0;256",
};
size_t names_len = sizeof(names) / sizeof(names[0]);
for (size_t i = 0; i < names_len; i++) {
if (color_name_is_valid(names[i])) {
printf(" Valid name: %s\n", names[i]);
} else {
printf("Invalid name: %s\n", names[i]);
}
}

◆ COLOR_RGB_LEN

#define COLOR_RGB_LEN   26

Maximum length in chars added to a rgb colorized string.

Should be CODE_RGB_LEN + STYLE_LEN Allocating for a string that will be colorized with rgb values must account for this.

◆ color_val

#define color_val (   x)
Value:
_Generic( \
(x), \
BasicValue: ColorValue_from_value(TYPE_BASIC, &x), \
ExtendedValue: ColorValue_from_value(TYPE_EXTENDED, &x), \
StyleValue: ColorValue_from_value(TYPE_STYLE, &x), \
RGB: ColorValue_from_value(TYPE_RGB, &x) \
)
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
Container for RGB values.
Definition: colr.h:2614
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
StyleValue
Style values.
Definition: colr.h:2628
ColorValue ColorValue_from_value(ColorType type, void *p)
Used with the color_val macro to dynamically create a ColorValue based on it&#39;s argument type...
Definition: colr.c:6998

Builds a correct ColorValue struct according to the type of it's first argument.

Uses _Generic (C11 standard) to dynamically create a ColorValue.

Parameters
[in]xBasicValue, Extended (unsigned char). or RGB value.
Returns
ColorValue_from_value([appropriate type], x)

◆ COLORARG_MARKER

#define COLORARG_MARKER   UINT32_MAX

◆ ColorValue_has

#define ColorValue_has (   cval,
  val 
)
Value:
_Generic( \
(val), \
)(cval, val)
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
bool ColorValue_has_ExtendedValue(ColorValue cval, ExtendedValue eval)
Checks to see if a ColorValue has a ExtendedValue set.
Definition: colr.c:7057
Container for RGB values.
Definition: colr.h:2614
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
bool ColorValue_has_StyleValue(ColorValue cval, StyleValue sval)
Checks to see if a ColorValue has a StyleValue set.
Definition: colr.c:7070
bool ColorValue_has_BasicValue(ColorValue cval, BasicValue bval)
Checks to see if a ColorValue has a BasicValue set.
Definition: colr.c:7044
bool ColorValue_has_RGB(ColorValue cval, RGB rgb)
Checks to see if a ColorValue has a RGB value set.
Definition: colr.c:7083
StyleValue
Style values.
Definition: colr.h:2628

Call the current ColorValue_has_<type> function for the given value.

Given the correct type of value, this will check to see if a ColorValue has the correct .type set for the value, and the values match.

Parameters
[in]cvalThe ColorValue to check.
[in]valA BasicValue, ExtendedValue, StyleValue, or RGB value.
Returns
true if the ColorValue has the correct .type and it's value matches val, otherwise false.
See also
ColorValue
ColorValue_has_BasicValue
ColorValue_has_ExtendedValue
ColorValue_has_StyleValue
ColorValue_has_RGB

◆ Colr

#define Colr (   text,
  ... 
)    ColorText_to_ptr(ColorText_from_values(text, __VA_ARGS__, _ColrLastArg))

Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat(), colr_join(), Colr_cat(), and Colr_join() macros.

You must free() the resulting ColorText struct using ColorText_free(), unless you pass it to colr_cat(), which will free() it for you.

Parameters
[in]textString to colorize/style.
[in]...One to three ColorArg pointers for fore, back, and style in any order.
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
Colra
Examples:
back_example.c, ColorResult_example.c, colr_cat_example.c, Colr_example.c, colr_join_example.c, colr_printf_example.c, colr_replace_all_example.c, colr_replace_example.c, colr_replace_re_all_example.c, colr_replace_re_example.c, fore_example.c, simple_example.c, and style_example.c.

◆ colr

#define colr (   text,
  ... 
)    colr_cat(Colr(text, __VA_ARGS__))

Create an allocated string directly from Colr() arguments.

This is a wrapper around colr_cat(Colr(text, ...)), which will automatically free() the ColorText, and return a string that you are responsible for.

Parameters
[in]textString to colorize/style.
[in]...

No more than 3 ColorArg pointers for fore, back, and style in any order.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns

An allocated string with the result.
You must free() the memory allocated by this function.

If allocation fails, NULL is returned.

Examples:
ColorResult_example.c, Colr_example.c, and simple_example.c.

◆ colr_alloc_len

#define colr_alloc_len (   x)
Value:
_Generic( \
(x), \
)
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
#define CODE_RGB_LEN
Maximum length in chars for an RGB fore/back escape code, including `&#39;\0&#39;`.
Definition: colr.h:233
#define CODE_LEN
Maximum length for a basic fore/back escape code, including `&#39;\0&#39;`.
Definition: colr.h:202
#define STYLE_LEN
Maximum length for a style escape code, including `&#39;\0&#39;`.
Definition: colr.h:218
Container for RGB values.
Definition: colr.h:2614
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
#define CODEX_LEN
Maximum length for an extended fore/back escape code, including `&#39;\0&#39;`.
Definition: colr.h:210
StyleValue
Style values.
Definition: colr.h:2628

Return the number of bytes needed to allocate an escape code string based on the color type.

Parameters
[in]xA BasicValue, ExtendedValue, RGB value, or StyleValue.
Returns
The number of bytes needed to allocate a string using the color value.

◆ colr_asprintf

#define colr_asprintf (   ...)    colr_printf_macro(asprintf, __VA_ARGS__)

Ensure colr_printf_register() has been called, and then call asprintf.

Will call free() on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]...

Arguments for `asprintf

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
Same as asprintf.
Examples:
colr_printf_example.c.

◆ Colr_cat

#define Colr_cat (   ...)    ColorResult_to_ptr(ColorResult_new(colr_cat(__VA_ARGS__)))

Like colr_cat(), but returns an allocated ColorResult that the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros will automatically free().

Parameters
[in]...

Arguments for colr_cat(), to concatenate.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns

An allocated ColorResult with all arguments joined together.

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

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

Examples:
colr_cat_example.c.

Referenced by Colr_erase_display().

◆ colr_cat

#define colr_cat (   ...)    _colr_join("", __VA_ARGS__, _ColrLastArg)

Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string.

To build the ColorArg pointers, it is better to use the fore(), back(), and style() macros. The ColorArgs are heap allocated, but colr_cat() will free() them for you.

To build the ColorText pointers, it is better to use the Colr() macro, along with the fore(), back(), and style() macros. The ColorTexts are heap allocated, but colr_cat() will free() them for you.

You can use ColrResult() to wrap any allocated string and colr_cat() will free it for you. Do not wrap static/stack-allocated strings. It will result in an "invalid free". The result of Colr_join() is an allocated ColorResult, like ColrResult() returns.

If you do not want the colr macros to free your Colr-based structs/strings for you, then you will have to call colr_to_str() on the structs and build or join the resulting strings yourself.

Parameters
[in]...

One or more ColorArg pointers, ColorResult pointers, ColorText pointers, or strings to join.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
An allocated string result.
You must free() the memory allocated by this function.
See also
Colr
Examples:
back_example.c, ColorResult_example.c, colr_cat_example.c, Colr_example.c, fore_example.c, simple_example.c, and style_example.c.

◆ Colr_center

#define Colr_center (   text,
  justwidth,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_CENTER, .width=justwidth, .padchar=' '} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

This is like Colr_center_char(), except is uses space as the default character.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_center example:
char* justified = colr_cat(Colr_center("This.", 9, fore(RED), back(WHITE)));
assert(justified);
// 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);
Examples:
Colr_example.c.

◆ Colr_center_char

#define Colr_center_char (   text,
  justwidth,
  c,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_CENTER, .width=justwidth, .padchar=c} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]cThe character to pad with.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
Colr_center
◆  Colr_center_char example:
char* justified = colr_cat(Colr_center_char("This.", 8, ' ', fore(RED), back(WHITE)));
assert(justified);
// The string still has codes, but only 2 spaces were prepended, and 1 appended.
assert(colr_str_starts_with(justified, " "));
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);

◆ colr_eq

#define colr_eq (   a,
 
)
Value:
_Generic( \
(a), \
RGB: RGB_eq, \
)(a, b)
bool ColorArg_eq(ColorArg a, ColorArg b)
Compares two ColorArg structs.
Definition: colr.c:5075
Holds a color type and it&#39;s value.
Definition: colr.h:2791
bool ArgType_eq(ArgType a, ArgType b)
Compares two ArgTypes.
Definition: colr.c:4982
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
ArgType
Argument types (fore, back, style).
Definition: colr.h:2672
bool ColorType_eq(ColorType a, ColorType b)
Compares two ColorTypes.
Definition: colr.c:6594
bool ColorJustify_eq(ColorJustify a, ColorJustify b)
Compares two ColorJustify structs.
Definition: colr.c:5808
bool ColorValue_eq(ColorValue a, ColorValue b)
Compares two ColorValue structs.
Definition: colr.c:6812
bool StyleValue_eq(StyleValue a, StyleValue b)
Compares two StyleValues.
Definition: colr.c:8385
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
bool ExtendedValue_eq(ExtendedValue a, ExtendedValue b)
Compares two ExtendedValues.
Definition: colr.c:7651
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
bool RGB_eq(RGB a, RGB b)
Compare two RGB structs.
Definition: colr.c:7951
Container for RGB values.
Definition: colr.h:2614
ColorType
Color/Style code types. Used with ColorType_from_str() and ColorValue.
Definition: colr.h:2704
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
bool ColorResult_eq(ColorResult a, ColorResult b)
Compares two ColorResults.
Definition: colr.c:5998
StyleValue
Style values.
Definition: colr.h:2628
bool BasicValue_eq(BasicValue a, BasicValue b)
Compares two BasicValues.
Definition: colr.c:7433

Calls the <type>_eq functions for the supported types.

The types for a and b must be the same.

Parameters
[in]aFirst supported type to compare.
[in]bSecond supported type to compare.
Returns
true if the values are equal, otherwise false.

◆ colr_example

#define colr_example (   x)
Value:
_Generic( \
(x), \
)(x)
Holds a color type and it&#39;s value.
Definition: colr.h:2791
char * ColorArg_example(ColorArg carg, bool colorized)
Create a string (char*) representation of a ColorArg with a stylized type/name using escape codes bui...
Definition: colr.c:5112
char * ColorValue_example(ColorValue cval)
Create a string (char*) representation of a ColorValue with a human-friendly type/name.
Definition: colr.c:6834
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816

Calls the <type>_example functions for the supported types.

This is used to create a human-friendly representation for ColorArgs or ColorValues.

Parameters
[in]xA supported type 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.

◆ COLR_FMT

#define COLR_FMT   "R"

Format character string suitable for use in the printf-family of functions.

This can be defined to any single-char string before including colr.h if you don't want to use the default value.

◆ Colr_fmt

#define Colr_fmt (   fmt,
  value,
  ... 
)
Value:
Colr_fmt_str(fmt, value), \
__VA_ARGS__, \
_ColrLastArg \
)
ColorResult * Colr_fmt_str(const char *fmt,...)
Allocate and format a string like asprintf, but wrap it in an allocated ColorResult.
Definition: colr.c:813
ColorResult * ColorResult_Colr(ColorResult *cres,...)
Colorize a ColorResult, and return a new allocated ColorResult.
Definition: colr.c:5938

Format and colorize a value like the printf-family.

Unlike printf, this only accepts a single value to format. The other arguments are for coloring/styling the value.

Parameters
[in]fmtThe format string.
[in]valueThe value to format.
[in]...At least one of fore(), back(), or style() arguments in any order.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_fmt example:
// Format a number:
for (int i = 1; i < 4; i++) {
colr_puts("Printing line ", Colr_fmt("%d", i, fore(BLUE)));
}
// Format a string:
char* s = "test";
// The coloring/styling applies to the final string value, "[test]".
colr_puts(Colr_fmt("[%s]", s, fore(RED)));
// If you don't want that, use the _join or _cat functions:
colr_puts(Colr_join(Colr(s, fore(RED)), "[", "]"));

◆ colr_fprint

#define colr_fprint (   file,
  ... 
)
Value:
do { \
char* _c_p_s = colr_cat(__VA_ARGS__); \
if (!_c_p_s) break; \
fprintf(file, "%s", _c_p_s); \
colr_free(_c_p_s); \
} while (0)
#define colr_cat(...)
Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string...
Definition: colr.h:1160

Create a string from a colr_cat() call, print it to file (without a newline), and free it.

Parameters
[in]fileFILE stream for output.
[in]...Arguments for colr_cat().

◆ colr_fprintf

#define colr_fprintf (   ...)    colr_printf_macro(fprintf, __VA_ARGS__)

Ensure colr_printf_register() has been called, and then call fprintf.

Will call free() on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]...

Arguments for fprintf.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
Same as fprintf.

◆ colr_free

#define colr_free (   x)
Value:
_Generic( \
(x), \
regmatch_t**: colr_free_re_matches, \
default: _colr_free \
)(x)
void ColorArg_free(ColorArg *p)
Free allocated memory for a ColorArg.
Definition: colr.c:5186
void ColorResult_free(ColorResult *p)
Free allocated memory for a ColorResult and it&#39;s .result member.
Definition: colr.c:6012
void colr_free_re_matches(regmatch_t **matches)
Free an array of allocated regmatch_t, like the return from colr_re_matches().
Definition: colr.c:1169
void _colr_free(void *p)
Calls Colr *_free() functions for Colr objects, otherwise just calls free().
Definition: colr.c:4447
void ColorText_free(ColorText *p)
Frees a ColorText and it&#39;s ColorArgs.
Definition: colr.c:6199
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
void ColorArgs_array_free(ColorArg **ps)
Free an allocated array of ColorArgs, including the array itself.
Definition: colr.c:5608

Calls the <type>_free functions for the supported types.

If the type is not supported, a plain free(x) is used.

Colr objects that have a <type>_free function will be properly released, even through a void pointer (as long as the .marker member is set, which it will be if it was created by the Colr functions/macros).

Parameters
[in]xA pointer to a supported type to free.
Examples:
ColorResult_example.c, colr_join_example.c, and colr_replace_all_example.c.

Referenced by colr_free_argsv().

◆ COLR_GNU

#define COLR_GNU

Defined when __GNUC__ is available, to enable statement-expressions and register_printf_specifier .

There isn't a lot of information available for register_printf_specifier right now. There are a couple of tutorials out there. No man pages though. It looks like it was introduced in glibc-2.27.

See also
back_str_static
fore_str_static
colr_asprintf
colr_printf
colr_printf_handler
colr_printf_info
colr_printf_macro
colr_printf_register
colr_sprintf
colr_snprintf

◆ colr_is_empty

#define colr_is_empty (   x)
Value:
_Generic( \
(x), \
)(x)
Holds a color type and it&#39;s value.
Definition: colr.h:2791
bool ColorArg_is_empty(ColorArg carg)
Checks to see if a ColorArg is an empty placeholder.
Definition: colr.c:5420
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
bool ColorText_is_empty(ColorText ctext)
Checks to see if a ColorText has no usable values.
Definition: colr.c:6344
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
bool ColorJustify_is_empty(ColorJustify cjust)
Checks to see if a ColorJustify is "empty".
Definition: colr.c:5828
bool ColorValue_is_empty(ColorValue cval)
Checks to see if a ColorValue is an empty placeholder.
Definition: colr.c:7097

Calls the <type>is_empty functions for the supported types.

Parameters
[in]xA supported type to build a string from.

◆ colr_is_invalid

#define colr_is_invalid (   x)
Value:
_Generic( \
(x), \
)(x)
Holds a color type and it&#39;s value.
Definition: colr.h:2791
bool ExtendedValue_is_invalid(int eval)
Determines whether an integer is an invalid ExtendedValue.
Definition: colr.c:7868
bool BasicValue_is_invalid(BasicValue bval)
Determines whether a BasicValue is invalid.
Definition: colr.c:7496
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
bool ColorValue_is_invalid(ColorValue cval)
Checks to see if a ColorValue holds an invalid value.
Definition: colr.c:7108
bool ColorArg_is_invalid(ColorArg carg)
Checks to see if a ColorArg holds an invalid value.
Definition: colr.c:5431
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
bool ColorType_is_invalid(ColorType type)
Check to see if a ColorType value is considered invalid.
Definition: colr.c:6673
ColorType
Color/Style code types. Used with ColorType_from_str() and ColorValue.
Definition: colr.h:2704
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
bool StyleValue_is_invalid(StyleValue sval)
Determines whether a StyleValue is invalid.
Definition: colr.c:8446
StyleValue
Style values.
Definition: colr.h:2628

Calls the <type>is_invalid functions for the supported types.

Parameters
[in]xA supported type to build a string from.

◆ colr_is_valid

#define colr_is_valid (   x)
Value:
_Generic( \
(x), \
)(x)
bool ColorArg_is_valid(ColorArg carg)
Checks to see if a ColorArg holds a valid value.
Definition: colr.c:5460
Holds a color type and it&#39;s value.
Definition: colr.h:2791
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
bool StyleValue_is_valid(StyleValue sval)
Determines whether a StyleValue is valid.
Definition: colr.c:8457
bool ExtendedValue_is_valid(int eval)
Determines whether an integer is a valid ExtendedValue.
Definition: colr.c:7879
bool ColorValue_is_valid(ColorValue cval)
Checks to see if a ColorValue holds a valid value.
Definition: colr.c:7119
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
bool ColorType_is_valid(ColorType type)
Check to see if a ColorType value is considered valid.
Definition: colr.c:6684
ColorType
Color/Style code types. Used with ColorType_from_str() and ColorValue.
Definition: colr.h:2704
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
bool BasicValue_is_valid(BasicValue bval)
Determines whether a BasicValue is valid.
Definition: colr.c:7507
StyleValue
Style values.
Definition: colr.h:2628

Calls the <type>is_valid functions for the supported types.

Parameters
[in]xA supported type to build a string from.

◆ colr_is_valid_mblen

#define colr_is_valid_mblen (   x)    ((x) && ((x) != (size_t)-1) && ((x) != (size_t)-2))

Checks return values from mbrlen() and colr_mb_len().

Parameters
[in]xA size_t return value to check, from mbrlen() or colr_mb_len().
Returns
true if at least one valid multibyte character length was detected, otherwise false. Invalid/incomplete multibyte sequences, or empty/ NULL strings will cause this macro to return false.

Referenced by _rainbow(), and colr_mb_len().

◆ colr_istr_either

#define colr_istr_either (   s1,
  s2,
  s3 
)
Value:
( \
((s1) && (s2) && (s3)) ? \
(colr_istr_eq((s1), (s2)) || colr_istr_eq((s1), (s3))) : \
false \
)
#define colr_istr_eq(s1, s2)
Convenience macro for !strcasecmp(s1, s2).
Definition: colr.h:1344

Convenience macro for !strcasecmp(s1, s2) || !strcasecmp(s1, s3).

Parameters
[in]s1The string to compare against the other two strings.
[in]s2The first string to compare with.
[in]s3The second string to compare with.
Returns
1 if s1 is equal to s2 or s3, otherwise 0.

Referenced by colr_supports_rgb().

◆ colr_istr_eq

#define colr_istr_eq (   s1,
  s2 
)
Value:
( \
((s1) && (s2)) ? \
!strcasecmp((s1), (s2)) : \
false \
)

Convenience macro for !strcasecmp(s1, s2).

Parameters
[in]s1The first string to compare.
[in]s2The second string to compare.
Returns
1 if s1 and s2 are equal, otherwise 0.

◆ Colr_join

#define Colr_join (   joiner,
  ... 
)    ColrResult(colr_join(joiner, __VA_ARGS__))

Joins Colr objects and strings, exactly like colr_join(), but returns an allocated ColorResult that the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros will automatically free() for you.

Parameters
[in]joinerWhat to put between the other arguments. ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char*).
[in]...

Other arguments to join, with joiner between them. ColorArg pointers, ColorResult pointers, ColorText pointers, or strings, in any order.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns

An allocated ColorResult.

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

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult
colr_join
colr
Colr
Examples:
ColorResult_example.c, colr_cat_example.c, colr_join_example.c, colr_replace_all_example.c, colr_replace_example.c, colr_replace_re_all_example.c, colr_replace_re_example.c, and simple_example.c.

◆ colr_join

#define colr_join (   joiner,
  ... 
)    _colr_join(joiner, __VA_ARGS__, _ColrLastArg)

Join ColorArg pointers, ColorText pointers, and strings by another ColorArg pointer, ColorText pointer, or string.

To build the ColorArg pointers, it is better to use the fore(), back(), and style() macros. The ColorArgs are heap allocated, but colr_join() will free() them for you.

To build the ColorText pointers, it is better to use the Colr() macro, along with the fore(), back(), and style() macros. The ColorTexts are heap allocated, but colr_join() will free() them for you.

Parameters
[in]joinerWhat to put between the other arguments. ColorArg pointer, ColorText pointer, or string.
[in]...Other arguments to join, with joiner between them. ColorArg pointers, ColorText pointers, or strings, in any order.
Returns

An allocated string.

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

See also
colr
Colr
Examples:
ColorResult_example.c, colr_join_example.c, and simple_example.c.

◆ colr_length

#define colr_length (   x)
Value:
_Generic( \
(x), \
)(x)
Holds a color type and it&#39;s value.
Definition: colr.h:2791
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 t...
Definition: colr.c:7134
size_t ColorText_length(ColorText ctext)
Returns the length in bytes needed to allocate a string (char*) built with ColorText_to_str() with th...
Definition: colr.c:6380
size_t _colr_ptr_length(void *p)
Get the size, in bytes, needed to convert a ColorArg, ColorResult, ColorText, or string (char*) into ...
Definition: colr.c:4888
size_t ColorArg_length(ColorArg carg)
Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc().
Definition: colr.c:5475
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
size_t ColorResult_length(ColorResult cres)
Return the length in bytes (including the null-terminator), that is needed to store the return from C...
Definition: colr.c:6088
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838

Calls the <type>_length functions for the supported types.

If a void pointer is given, _colr_ptr_length() is called on it to determine the length.

Parameters
[in]xA supported type to build a string from.

◆ Colr_ljust

#define Colr_ljust (   text,
  justwidth,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_LEFT, .width=justwidth, .padchar=' '} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

This is like Colr_ljust_char(), except is uses space as the default character.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_ljust example:
char* justified = colr_cat(Colr_ljust("This.", 8, fore(RED), back(WHITE)));
assert(justified);
// 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);
Examples:
Colr_example.c.

◆ Colr_ljust_char

#define Colr_ljust_char (   text,
  justwidth,
  c,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_LEFT, .width=justwidth, .padchar=c} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]cThe character to pad with.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
Colr_ljust
◆  Colr_ljust_char example:
char* justified = colr_cat(Colr_ljust_char("This.", 8, ' ', fore(RED), back(WHITE)));
assert(justified);
// 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);

◆ colr_max

#define colr_max (   a,
 
)    (a > b ? a : b)

Macro for (a > b ? a : b).

Parameters
[in]aFirst value to compare.
[in]bSecond value to compare.
Returns
a if a > b, otherwise b.

Referenced by ColorText_length().

◆ colr_print

#define colr_print (   ...)
Value:
do { \
char* _c_p_s = colr_cat(__VA_ARGS__); \
if (!_c_p_s) break; \
printf("%s", _c_p_s); \
colr_free(_c_p_s); \
} while (0)
#define colr_cat(...)
Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string...
Definition: colr.h:1160

Create a string from a colr_cat() call, print it to stdout (without a newline), and free it.

Parameters
[in]...Arguments for colr_cat().

◆ colr_printf

#define colr_printf (   ...)    colr_printf_macro(printf, __VA_ARGS__)

Ensure colr_printf_register() has been called, and then call printf.

Will call free() on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]...

Arguments for printf.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
Same as printf.
Examples:
colr_printf_example.c.

◆ colr_printf_macro

#define colr_printf_macro (   func,
  ... 
)
Value:
__extension__({ \
_Pragma("GCC diagnostic push"); \
_Pragma("GCC diagnostic ignored \"-Wformat=\""); \
_Pragma("GCC diagnostic ignored \"-Wformat-extra-args\""); \
_Pragma("clang diagnostic push"); \
_Pragma("clang diagnostic ignored \"-Wformat-invalid-specifier\""); \
colr_printf_register(); \
int _c_p_m_ret = func(__VA_ARGS__); \
_Pragma("clang diagnostic pop"); \
_Pragma("GCC diagnostic pop"); \
_c_p_m_ret; \
})

Calls one of the printf-family functions, with format warnings disabled for the call, and returns the result.

This function also ensures that colr_printf_register() is called, which ensures that register_printf_specifier() is called one time.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]funcThe standard printf function to call, with a return type of int.
[in]...Arguments for the printf function.
Returns
Same as func(...).

◆ colr_puts

#define colr_puts (   ...)
Value:
do { \
char* _c_p_s = colr_cat(__VA_ARGS__); \
if (!_c_p_s) break; \
puts(_c_p_s); \
colr_free(_c_p_s); \
} while (0)
#define colr_cat(...)
Join ColorArg pointers, ColorResult pointers, ColorText pointers, and strings into one long string...
Definition: colr.h:1160

Create a string from a colr_cat() call, print it (with a newline), and free it.

Parameters
[in]...Arguments for colr_cat().
Examples:
colr_cat_example.c, colr_join_example.c, and simple_example.c.

◆ colr_replace

#define colr_replace (   s,
  target,
  repl 
)

Replace a substring in s with another string, ColorArg string, ColorResult string, or ColorText string.

If a string (char*) is used as target and repl, this is just a wrapper around colr_str_replace().

If target is a string (char*), this is a plain string-replace.

If target is a regex pattern (regex_t), it's regex match (regmatch_t) will be used to find a target string to replace in s.

If target is a regex match (regmatch_t), it's offsets will be used to find a target string in s.

If target is a NULL-terminated array of regex matches (regmatch_t**), each match will be replaced in the target string, s.

There is no difference between colr_replace() and colr_replace_all() when a NULL-terminated array of regex matches (regmatch_t**) is used.

If a ColorArg, ColorResult, or ColorText is used as repl, the appropriate colr_str_replace_<types> function is called. The function will create a string of escape-codes/text to be used as a replacement.

If repl is NULL, then an empty string ("") is used as the replacement, which causes the target string to be removed.

If you would like to replace all occurrences of the substring, use colr_replace_all().

Parameters
[in]s

The string to operate on.

Must be null-terminated.

[in]targetA target string, regex pattern (regex_t), or regex match (regmatch_t) to replace in s. If a string is given, it must be null-terminated.
[in]repl

A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is NULL, then an empty string is used ("") as the replacement.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

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_replace_all
colr_replace_re
colr_replace_re_all
colr_str_replace
colr_str_replace_ColorArg
colr_str_replace_ColorResult
colr_str_replace_ColorText
colr_str_replace_re_pat
colr_str_replace_re_pat_ColorArg
colr_str_replace_re_pat_ColorResult
colr_str_replace_re_pat_ColorText
colr_str_replace_re_match
colr_str_replace_re_match_ColorArg
colr_str_replace_re_match_ColorResult
colr_str_replace_re_match_ColorText
Examples:
colr_replace_example.c, and simple_example.c.

◆ colr_replace_all

#define colr_replace_all (   s,
  target,
  repl 
)
Value:
_Generic( \
(repl), \
char*: _Generic( \
(target), \
regmatch_t** : colr_str_replace_re_matches \
), \
ColorArg*: _Generic( \
(target), \
), \
ColorResult*: _Generic( \
(target), \
), \
ColorText*: _Generic( \
(target), \
) \
)(s, target, repl)
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&#39;s string result.
Definition: colr.c:2711
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&#39;s string result.
Definition: colr.c:2684
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 ColorResu...
Definition: colr.c:3540
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&#39;...
Definition: colr.c:3509
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*).
Definition: colr.c:3771
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&#39;s string result.
Definition: colr.c:2655
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*).
Definition: colr.c:2632
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&#39;s string result...
Definition: colr.c:3836
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...
Definition: colr.c:3570
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
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&#39;s string result...
Definition: colr.c:3865
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
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&#39;s string result...
Definition: colr.c:3806
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*).
Definition: colr.c:3440

Replace all substrings in s with another string, ColorArg string, ColorResult string, or ColorText string.

If a string (char*) is used as target and repl, this is just a wrapper around colr_str_replace().

If target is a string (char*), this is a plain string-replace.

If target is a regex pattern (regex_t), it's regex match (regmatch_t) will be used to find a target string to replace in s.

If target is a NULL-terminated array of regex matches (regmatch_t**), each match will be replaced in the target string, s.

There is no difference between colr_replace() and colr_replace_all() when a NULL-terminated array of regex matches (regmatch_t**) is used.

If a ColorArg, ColorResult, or ColorText is used as repl, the appropriate colr_str_replace_<types> function is called. The function will create a string of escape-codes/text to be used as a replacement.

If repl is NULL, then an empty string ("") is used as the replacement, which causes the target string to be removed.

If you would like to replace only the first occurrence of the substring, use colr_replace().

Parameters
[in]s

The string to operate on.

Must be null-terminated.

[in]targetA target string, or regex pattern (regex_t) to replace in s. If a string is given, it must be null-terminated.
[in]repl

A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is NULL, then an empty string is used ("") as the replacement.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

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_replace
colr_replace_re
colr_replace_re_all
colr_str_replace_all
colr_str_replace_all_ColorArg
colr_str_replace_all_ColorResult
colr_str_replace_all_ColorText
colr_str_replace_re_pat_all
colr_str_replace_re_pat_all_ColorArg
colr_str_replace_re_pat_all_ColorResult
colr_str_replace_re_pat_all_ColorText
Examples:
colr_replace_all_example.c, and simple_example.c.

◆ colr_replace_re

#define colr_replace_re (   s,
  target,
  repl,
  flags 
)
Value:
_Generic( \
(repl), \
)(s, target, repl, flags)
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*).
Definition: colr.c:2931
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&#39;s string ...
Definition: colr.c:3184
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
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&#39;s strin...
Definition: colr.c:3153
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
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&#39;s string r...
Definition: colr.c:3120

Replace a regex pattern string (char*) in s with another string, ColorArg string, ColorResult string, or ColorText string.

If a string (char*) is used as repl, this is just a wrapper around colr_str_replace_re().

If a ColorArg, ColorResult, or ColorText is used as repl, the appropriate colr_str_replace_re_<type> function is called. The function will create a string of escape-codes/text to be used as a replacement.

If repl is NULL, then an empty string ("") is used as the replacement, which causes the target string to be removed.

If you would like to replace all occurrences of the substring, use colr_replace_re_all().

Parameters
[in]s

The string to operate on.

Must be null-terminated.

[in]targetA regex pattern string (char*), regex pattern (regex_t), or regex match (regmatch_t) to replace in s.
If a string is given, it must be null-terminated.
[in]repl

A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is NULL, then an empty string is used ("") as the replacement.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

[in]flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
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_replace
colr_replace_all
colr_replace_re_all
colr_str_replace_re
colr_str_replace_re_ColorArg
colr_str_replace_re_ColorResult
colr_str_replace_re_ColorText
◆  colr_replace_re example:
#include "colr.h"
int main(void) {
char* mystring = "This is a foo line.";
puts(mystring);
char* replaced = colr_replace_re(mystring, "fo{2}", "replaced", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
// ColorArgs.
replaced = colr_replace_re(mystring, "f\\w\\w ", fore(RED), 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
// No reset code was appended to that last one.
printf("%s", CODE_RESET_ALL);
free(replaced);
// ColorResults.
replaced = colr_replace_re(
mystring,
"\\woo",
Colr_join(" ", Colr("nicely", fore(RED)), Colr("colored", fore(BLUE))),
0
);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
// ColorTexts.
replaced = colr_replace_re(mystring, "f[a-z]{2}", Colr("styled", style(UNDERLINE)) , 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}
Examples:
colr_replace_re_example.c, and simple_example.c.

◆ colr_replace_re_all

#define colr_replace_re_all (   s,
  target,
  repl,
  flags 
)
Value:
_Generic( \
(repl), \
)(s, target, repl, flags)
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&#39;s stri...
Definition: colr.c:3022
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*).
Definition: colr.c:2985
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&#39;s s...
Definition: colr.c:3055
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
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&#39;s str...
Definition: colr.c:3087

Replace all matches to a regex pattern string (char*) in s with another string, ColorArg string, ColorResult string, or ColorText string.

If a string (char*) is used as repl, this is just a wrapper around colr_str_replace_re_all().

If a ColorArg, ColorResult, or ColorText is used as repl, the appropriate colr_str_replace_re_<type> function is called. The function will create a string of escape-codes/text to be used as a replacement.

If repl is NULL, then an empty string ("") is used as the replacement, which causes the target string to be removed.

If you would like to replace only the first occurrence of the substring, use colr_replace_re().

Parameters
[in]s

The string to operate on.

Must be null-terminated.

[in]targetA regex pattern string (char*), regex pattern (regex_t), or regex match (regmatch_t) to replace in s.
If a string is given, it must be null-terminated.
[in]repl

A string, ColorArg, ColorResult, or ColorText to replace the target string with. If this is NULL, then an empty string is used ("") as the replacement.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

[in]flagsFlags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not.
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_replace
colr_replace_all
colr_replace_re
colr_str_replace_re
colr_str_replace_re_ColorArg
colr_str_replace_re_ColorResult
colr_str_replace_re_ColorText
◆  colr_replace_re_all example:
#include "colr.h"
int main(void) {
char* mystring = "This foo is a foo line.";
puts(mystring);
char* replaced = colr_replace_re_all(mystring, "fo{2}", "replacement", 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
// ColorArgs.
replaced = colr_replace_re_all(mystring, "f\\w\\w ", fore(RED), 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
// No reset code was appended to that last one.
printf("%s", CODE_RESET_ALL);
free(replaced);
// ColorResults.
replaced = colr_replace_re_all(
mystring,
"\\woo",
Colr_join(" ", Colr("nicely", fore(RED)), Colr("colored", fore(BLUE))),
0
);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
// ColorTexts.
replaced = colr_replace_re_all(mystring, "f[a-z]{2}", Colr("styled", style(UNDERLINE)) , 0);
if (!replaced) return EXIT_FAILURE;
puts(replaced);
free(replaced);
}
Examples:
colr_replace_re_all_example.c.

◆ colr_repr

#define colr_repr (   x)
Value:
_Generic( \
(x), \
const char*: colr_str_repr, \
char*: colr_str_repr, \
const char: colr_char_repr, \
char: colr_char_repr, \
void*: _colr_ptr_repr \
)(x)
char * ColorArg_repr(ColorArg carg)
Creates a string (char*) representation for a ColorArg.
Definition: colr.c:5494
char * ExtendedValue_repr(int eval)
Creates a string (char*) representation of a ExtendedValue.
Definition: colr.c:7894
Holds a color type and it&#39;s value.
Definition: colr.h:2791
char * ColorResult_repr(ColorResult cres)
Create a string representation for a ColorResult.
Definition: colr.c:6126
char * StyleValue_repr(StyleValue sval)
Creates a string (char*) representation of a StyleValue.
Definition: colr.c:8495
char * ColorType_repr(ColorType type)
Creates a string (char*) representation of a ColorType.
Definition: colr.c:6699
char * ColorJustifyMethod_repr(ColorJustifyMethod meth)
Creates a string (char*) representation for a ColorJustifyMethod.
Definition: colr.c:5898
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
char * colr_char_repr(char c)
Creates a string (char*) representation for a char.
Definition: colr.c:996
char * RGB_repr(RGB rgb)
Creates a string (char*) representation for an RGB value.
Definition: colr.c:8362
ArgType
Argument types (fore, back, style).
Definition: colr.h:2672
char * ColorValue_repr(ColorValue cval)
Creates a string (char*) representation of a ColorValue.
Definition: colr.c:7211
char * ColorJustify_repr(ColorJustify cjust)
Creates a string (char*) representation for a ColorJustify.
Definition: colr.c:5868
char * _colr_ptr_repr(void *p)
Determine what kind of pointer is being passed, and call the appropriate <type>_repr function to obta...
Definition: colr.c:4928
char * ArgType_repr(ArgType type)
Creates a string (char*) representation of a ArgType.
Definition: colr.c:4997
char * TermSize_repr(TermSize ts)
Create a string (char*) representation for a TermSize.
Definition: colr.c:8562
Holds a terminal size, usually retrieved with colr_term_size().
Definition: colr.h:2855
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
char * BasicValue_repr(BasicValue bval)
Creates a string (char*) representation of a BasicValue.
Definition: colr.c:7522
char * ColorArgs_array_repr(ColorArg **lst)
Creates a string representation for an array of ColorArg pointers.
Definition: colr.c:5639
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
char * colr_str_repr(const char *s)
Convert a string (char*) into a representation of a string, by wrapping it in quotes and escaping cha...
Definition: colr.c:3993
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
Container for RGB values.
Definition: colr.h:2614
ColorType
Color/Style code types. Used with ColorType_from_str() and ColorValue.
Definition: colr.h:2704
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
char * ColorText_repr(ColorText ctext)
Allocate a string (char*) representation for a ColorText.
Definition: colr.c:6412
StyleValue
Style values.
Definition: colr.h:2628
ColorJustifyMethod
Justification style for ColorTexts.
Definition: colr.h:2688

Transforms several ColrC objects into their string representations.

Uses _Generic (C11 standard) to dynamically dispatch to the proper *_repr functions.

If a regular string is passed in, it will be escaped and you must still free() the result.

Supported Types:

Parameters
[in]xA value with one of the supported types to transform into a string.
Returns

Stringified representation of what was passed in.

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

Referenced by ColorArgs_array_repr(), colr_printf_handler(), and colr_str_mb_len().

◆ Colr_rjust

#define Colr_rjust (   text,
  justwidth,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_RIGHT, .width=justwidth, .padchar=' '} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

This is like Colr_rjust_char(), except is uses space as the default character.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  Colr_rjust example:
char* justified = colr_cat(Colr_rjust("This.", 8, fore(RED), back(WHITE)));
assert(justified);
// 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);
Examples:
Colr_example.c.

◆ Colr_rjust_char

#define Colr_rjust_char (   text,
  justwidth,
  c,
  ... 
)
Value:
Colr(text, __VA_ARGS__), \
(ColorJustify){.method=JUST_RIGHT, .width=justwidth, .padchar=c} \
)
ColorText * ColorText_set_just(ColorText *ctext, ColorJustify cjust)
Set the ColorJustify method for a ColorText, and return the ColorText.
Definition: colr.c:6451
Holds a string justification method, width, and padding character for ColorTexts. ...
Definition: colr.h:2759
#define Colr(text,...)
Returns a heap-allocated ColorText struct that can be used by itself, or with the colr_cat()...
Definition: colr.h:751

Sets the JustifyMethod for a ColorText while allocating it.

Parameters
[in]textText to colorize.
[in]justwidthWidth for justification.
[in]cThe character to pad with.
[in]...Fore, back, or style ColorArgs for Colr().
Returns

An allocated ColorText.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
Colr_rjust
◆  Colr_rjust_char example:
char* justified = colr_cat(Colr_rjust_char("This.", 8, ' ', fore(RED), back(WHITE)));
assert(justified);
// 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);

◆ colr_snprintf

#define colr_snprintf (   ...)    colr_printf_macro(snprintf, __VA_ARGS__)

Ensure colr_printf_register() has been called, and then call snprintf.

Will call free() on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]...

Arguments for snprintf.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
Same as snprintf.
Examples:
colr_printf_example.c.

◆ colr_sprintf

#define colr_sprintf (   ...)    colr_printf_macro(sprintf, __VA_ARGS__)

Ensure colr_printf_register() has been called, and then call sprintf.

Will call free() on any ColorArg pointer, ColorResult pointer, ColorText pointer, or the strings created by them.

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Parameters
[in]...

Arguments for sprintf.

colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function.

Returns
Same as sprintf.
Examples:
colr_printf_example.c.

◆ colr_str_either

#define colr_str_either (   s1,
  s2,
  s3 
)    (colr_str_eq(s1, s2) || colr_str_eq(s1, s3))

Convenience macro for !strcmp(s1, s2) || !strcmp(s1, s3).

Parameters
[in]s1The string to compare against the other two strings.
[in]s2The first string to compare with.
[in]s3The second string to compare with.
Returns
1 if s1 is equal to s2 or s3, otherwise 0.

◆ colr_str_eq

#define colr_str_eq (   s1,
  s2 
)
Value:
( \
((s1) && (s2)) ? !strcmp((s1), (s2)) : false \
)

Convenience macro for !strcmp(s1, s2).

Parameters
[in]s1The first string to compare.
[in]s2The second string to compare.
Returns
1 if s1 and s2 are equal, otherwise 0.

Referenced by ColorResult_eq(), and RGB_from_str().

◆ colr_to_str

#define colr_to_str (   x)
Value:
_Generic( \
(x), \
)(x)
char * StyleValue_to_str(StyleValue sval)
Create a human-friendly string (char*) representation for a StyleValue.
Definition: colr.c:8472
char * BasicValue_to_str(BasicValue bval)
Create a human-friendly string (char*) representation for a BasicValue.
Definition: colr.c:7628
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
char * ColorType_to_str(ColorType type)
Create a human-friendly string (char*) representation for a ColorType.
Definition: colr.c:6744
char * ColorArg_to_esc(ColorArg carg)
Converts a ColorArg into an escape code string (char*).
Definition: colr.c:5533
ArgType
Argument types (fore, back, style).
Definition: colr.h:2672
char * RGB_to_str(RGB rgb)
Convert an RGB value into a human-friendly RGB string (char*) suitable for input to RGB_from_str()...
Definition: colr.c:8306
char * ColorResult_to_str(ColorResult cres)
Convert a ColorResult into a string (char*).
Definition: colr.c:6169
char * ExtendedValue_to_str(ExtendedValue eval)
Creates a human-friendly string (char*) from an ExtendedValue&#39;s actual value, suitable for use with E...
Definition: colr.c:7921
Holds a string (char*) that was definitely allocated by Colr.
Definition: colr.h:2826
Holds an ArgType, and a ColorValue.
Definition: colr.h:2816
Holds a string of text, and optional fore, back, and style ColorArgs.
Definition: colr.h:2838
Container for RGB values.
Definition: colr.h:2614
ColorType
Color/Style code types. Used with ColorType_from_str() and ColorValue.
Definition: colr.h:2704
char * ColorText_to_str(ColorText ctext)
Stringifies a ColorText struct, creating a mix of escape codes and text.
Definition: colr.c:6533
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
char * ArgType_to_str(ArgType type)
Creates a human-friendly string (char*) from an ArgType.
Definition: colr.c:5027
StyleValue
Style values.
Definition: colr.h:2628
char * _colr_ptr_to_str(void *p)
Determine what kind of pointer is being passed, and call the appropriate <type>_to_str function to ob...
Definition: colr.c:4957

Calls the <type>_to_str functions for the supported types.

If a string is given, it is duplicated like strdup().

Parameters
[in]xA supported type to build a string from.
Returns

An allocated string from the type's *_to_str() function.

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

If allocation fails, NULL is returned.

Examples:
ColorResult_example.c.

◆ Colra

#define Colra (   text,
  ... 
)    ColorText_from_values(text, __VA_ARGS__, _ColrLastArg)

Returns an initialized stack-allocated ColorText.

If this ColorText is manually stored on the heap, and then sent through the colr macros, it's ColorArgs will be free'd. You cannot use the same ColorText twice inside the colr macros/functions.

Attention
The result cannot be used inside the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, because you must not call free() on it.
Parameters
[in]textString to colorize/style.
[in]...No more than 3 ColorArg pointers for fore, back, and style in any order.
Returns
An initialized ColorText.
See also
Colr
◆  Colra example:
// This ColorText is stack-allocated, but it's ColorArgs are not.
ColorText ctext = Colra("This.", fore(RED), back(WHITE));
// You cannot use this in the colr macros.
char* mystring = ColorText_to_str(ctext);
printf("%s\n", mystring);
free(mystring);
// And you are responsible for cleaning up the ColorArgs.
ColorText singleuse = Colra("That.", fore(BLUE));
ColorText* manualalloc = ColorText_to_ptr(singleuse);
assert(singleuse.fore == manualalloc->fore);
colr_printf("Used up: %R\n", manualalloc);
// The ColorArgs associated with `singleuse` were just free'd
// because they were linked with the heap-allocated ColorText.

◆ ColrColorResult

#define ColrColorResult (   cres,
  ... 
)    ColorResult_Colr(cres, __VA_ARGS__, _ColrLastArg)

Like Colr(), but it operates on a ColorResult to generate a new colorized ColorResult.

Parameters
[in]cresAn allocated ColorResult to colorize. This will be free()'d to create the new ColorResult.
[in]...One to three fore(), back(), or style() arguments (ColorArgs). The ColorArgs will be free()'d to generate the new ColorResult.
Returns

An allocated ColorResult.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

◆  ColrColorResult example:
colr_puts(ColrColorResult(Colr_join("test", "[", "]"), fore(BLUE)));

◆ ColrResult

#define ColrResult (   s)    ColorResult_to_ptr(ColorResult_new(s))

Wraps an allocated string in a ColorResult, which marks it as "freeable" in the colr macros.

Parameters
[in]sAn allocated string.
Returns

An allocated ColorResult.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

Examples:
ColorResult_example.c.

◆ ext

#define ext (   x)    ((ExtendedValue)x)

Casts to ExtendedValue (unsigned char).

Parameters
[in]xValue to cast to unsigned char/ExtendedValue.
Returns
An ExtendedValue.
See also
fore
back
colr
Colr
ext_hex
ext_hex_or
ext_rgb
ext_RGB
Examples:
back_example.c, colr_cat_example.c, fore_example.c, and simple_example.c.

Referenced by ExtendedValue_from_BasicValue(), and ExtendedValue_from_RGB().

◆ ext_hex

#define ext_hex (   s)    ext_hex_or(s, ext(0))

Like hex(), but force a conversion to the closest ExtendedValue (256-colors).

Parameters
[in]sA hex string to convert.
Returns
The closest matching ExtendedValue, or 0 for bad hex strings.
See also
ext
ext_hex_or
hex
hex_or
Examples:
back_example.c, Colr_example.c, colr_join_example.c, and simple_example.c.

◆ ext_hex_or

#define ext_hex_or (   s,
  default_value 
)    ExtendedValue_from_hex_default(s, default_value)

Like hex_or(), but force a conversion to the closest ExtendedValue (256-colors).

This is a convenience macro for ExtendedValue_from_hex_default().

Parameters
[in]sA hex string to convert.
[in]default_valueExtendedValue to use if the hex string is not valid.
Returns
The closest matching ExtendedValue, or default_value for bad hex strings.
See also
ext
ext_hex
hex
hex_or
Examples:
back_example.c.

◆ EXT_INVALID

#define EXT_INVALID   COLOR_INVALID

Alias for COLOR_INVALID.

All color values share an _INVALID member with the same value, so:

COLOR_INVALID == BASIC_INVALID == EXT_INVALID == STYLE_INVALID

Referenced by ExtendedValue_from_BasicValue(), ExtendedValue_from_esc(), and ExtendedValue_from_str().

◆ EXT_INVALID_RANGE

#define EXT_INVALID_RANGE   COLOR_INVALID_RANGE

Possible error return value for ExtendedValue_from_str() or ExtendedValue_from_esc().

This is just an alias for COLOR_INVALID_RANGE.

COLOR_INVALID_RANGE == BASIC_INVALID_RANGE == EXT_INVALID_RANGE == STYLE_INVALID_RANGE

Referenced by ExtendedValue_from_esc(), and ExtendedValue_from_str().

◆ ext_rgb

#define ext_rgb (   r,
  g,
 
)    ExtendedValue_from_RGB((RGB){.red=r, .green=g, .blue=b})

Creates the closest matching ExtendedValue from separate red, green, and blue values.

This is short-hand for ExtendedValue_from_RGB((RGB){r, g, b}).

Parameters
[in]rThe red value.
[in]gThe green value.
[in]bThe blue value.
Returns
An ExtendedValue that closely matches the RGB value.
See also
ExtendedValue_from_RGB
RGB_to_term_RGB
Examples:
ColorResult_example.c, and Colr_example.c.

◆ ext_RGB

#define ext_RGB (   rgbval)    ExtendedValue_from_RGB(rgbval)

Creates the closest matching ExtendedValue from an RGB value.

This is short-hand for ExtendedValue_from_RGB(rgbval).

Parameters
[in]rgbvalThe RGB value to use.
Returns
An ExtendedValue that closely matches the RGB value.
See also
ExtendedValue_from_RGB
RGB_to_term_RGB

◆ fore

#define fore (   x)    ColorArg_to_ptr(fore_arg(x))

Create a fore color suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros.

Technically, this macro accepts BasicValues, ExtendedValues, or RGB structs. However, for some of these you should be using the macros that create those things.

BasicValues can be used by their names (RED, YELLOW, etc.).

ExtendedValues can be created on the fly with ext().

RGB structs can be easily created with rgb().

Color names (char*) can be passed to generate the appropriate color value.

Parameters
[in]xA BasicValue, ExtendedValue, or RGB struct to use for the color value.
Returns

A pointer to a heap-allocated ColorArg struct.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
fore_arg
fore_str
colr
Colr
Examples:
back_example.c, ColorResult_example.c, colr_cat_example.c, Colr_example.c, colr_join_example.c, colr_printf_example.c, colr_replace_all_example.c, colr_replace_example.c, colr_replace_re_all_example.c, colr_replace_re_example.c, fore_example.c, and simple_example.c.

◆ fore_arg

#define fore_arg (   x)
Value:
_Generic( \
(x), \
char* : ColorArg_from_str, \
)(FORE, x)
ColorArg ColorArg_from_str(ArgType type, const char *colorname)
Build a ColorArg (fore, back, or style value) from a known color name/style.
Definition: colr.c:5327
ColorArg ColorArg_from_ExtendedValue(ArgType type, ExtendedValue value)
Explicit version of ColorArg_from_value that only handles ExtendedValues.
Definition: colr.c:5226
BasicValue
Basic color values, with a few convenience values for extended colors.
Definition: colr.h:2535
ColorArg ColorArg_from_RGB(ArgType type, RGB value)
Explicit version of ColorArg_from_value that only handles RGB structs.
Definition: colr.c:5249
ColorArg ColorArg_from_StyleValue(ArgType type, StyleValue value)
Explicit version of ColorArg_from_value that only handles StyleValues.
Definition: colr.c:5366
Container for RGB values.
Definition: colr.h:2614
ColorArg ColorArg_from_BasicValue(ArgType type, BasicValue value)
Explicit version of ColorArg_from_value that only handles BasicValues.
Definition: colr.c:5203
unsigned char ExtendedValue
Convenience typedef for clarity when dealing with extended (256) colors.
Definition: colr.h:2611
StyleValue
Style values.
Definition: colr.h:2628

Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of it's argument.

Uses _Generic (C11 standard) to dynamically create a ColorArg. This is used by the fore() macro.

Parameters
[in]xBasicValue, Extended (unsigned char), RGB struct, or string (color name) for fore color.
Returns
A ColorArg with the FORE type set, and it's .value.type set for the appropriate color type/value. For invalid values the .value.type may be set to TYPE_INVALID.
See also
fore
fore_str

◆ fore_str

#define fore_str (   x)    ColorArg_to_esc(fore_arg(x))

Return just the escape code string for a fore color.

Parameters
[in]xA BasicValue, ExtendedValue, or RGB struct.
Returns

An allocated string.

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

See also
fore
fore_arg

◆ fore_str_static

#define fore_str_static (   x)
Value:
__extension__ ({ \
__typeof(x) _fss_val = x; \
ColorArg _fss_carg = fore_arg(_fss_val); \
size_t _fss_len = ColorArg_length(_fss_carg); \
char* _fss_codes = alloca(_fss_len); \
ColorArg_to_esc_s(_fss_codes, _fss_carg); \
_fss_codes; \
})
#define fore_arg(x)
Uses ColorArg_from_<type> to build a ColorArg with the appropriate color type, based on the type of i...
Definition: colr.h:2275
size_t ColorArg_length(ColorArg carg)
Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc().
Definition: colr.c:5475

Creates a stack-allocated escape code string (char*) for a fore color.

These are not constant strings, but they are stored on the stack. A Statement Expression is used to build a string of the correct length and content using ColorArg_to_esc_s().

Attention
This feature uses a GNU extension, and is only available when COLR_GNU is defined. See the documentation for COLR_GNU.
Warning
This uses alloca to reserve space on the stack inside of a Statement Expression. A Variable Length Array will not work inside of a statement expression. If the call causes a stack overflow, program behavior is undefined. See previous links, and here.

You can also create stack-allocated escape code strings using format_fg(), format_fgx(), format_fg_RGB(), and format_fg_RGB_term().

Parameters
[in]xA BasicValue, ExtendedValue, or RGB value.
Returns
A stack-allocated escape code string.
See also
back_str_static
style_str_static
format_fg
format_bg
◆  fore_str_static example:
// This results in a call to sprintf(), to format an extended escape code.
// The string is stored on the stack.
char* foreblue = fore_str_static(BLUE);
char* backwhite = back_str_static(WHITE);
printf("%s%sBlue on White." NCNL, foreblue, backwhite);
RGB rgbval = rgb(255, 34, 0);
printf("%sA reddish." NCNL, fore_str_static(rgbval));
printf("%sAquaMarine." NCNL, fore_str_static("aquamarine"));

◆ hex

#define hex (   s)    hex_or(s, rgb(0, 0, 0))

Use RGB_from_hex_default() to create an RGB value.

Parameters
[in]sA hex string to convert.
Returns
A valid RGB value, or rgb(0, 0, 0) for bad hex strings.
See also
hex_or
ext_hex
ext_hex_or
Examples:
back_example.c, colr_join_example.c, and simple_example.c.

◆ hex_or

#define hex_or (   s,
  default_rgb 
)    RGB_from_hex_default(s, default_rgb)

Use RGB_from_hex_default() to create an RGB value.

Parameters
[in]sA hex string to convert.
[in]default_rgbDefault RGB value to use if the hex string is not valid.
Returns
A valid RGB value, or default_rgb for bad hex strings.
See also
hex
ext_hex
ext_hex_or
Examples:
back_example.c.

◆ if_not_asprintf

#define if_not_asprintf (   ...)    if (asprintf(__VA_ARGS__) < 1)

Convenience macro for checking asprintf's return value.

Should be followed by a block of code.

Note: asprintf returns -1 for errors, but 0 is a valid return (0 bytes written to the string). The string will be untouched (may be NULL if it was initialized as NULL)

Parameters
[in]...Arguments for asprintf.

◆ rgb

#define rgb (   r,
  g,
 
)    ((RGB){.red=r, .green=g, .blue=b})

Creates an anonymous RGB struct for use in function calls.

Parameters
[in]runsigned char Red value.
[in]gunsigned char Blue value.
[in]bunsigned char Green value.
Returns
An RGB struct.
See also
rgb_safe
Examples:
back_example.c, colr_cat_example.c, colr_join_example.c, fore_example.c, and simple_example.c.

Referenced by ExtendedValue_from_hex(), rainbow_step(), RGB_from_hex_default(), RGB_grayscale(), RGB_inverted(), and RGB_monochrome().

◆ style

#define style (   x)    ColorArg_to_ptr(style_arg(x))

Create a style suitable for use with the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros.

This macro accepts strings (style names) and StyleValues.

Style names (char*) can be passed to generate the appropriate style value.

Parameters
[in]xA StyleValue.
Returns

A pointer to a heap-allocated ColorArg struct.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
style_arg
style_str
colr
Colr
Examples:
ColorResult_example.c, colr_cat_example.c, Colr_example.c, colr_join_example.c, colr_printf_example.c, colr_replace_all_example.c, colr_replace_example.c, colr_replace_re_all_example.c, colr_replace_re_example.c, simple_example.c, and style_example.c.

◆ style_arg

#define style_arg (   x)
Value:
_Generic( \
(x), \
char* : ColorArg_from_str, \
)(STYLE, x)
ColorArg ColorArg_from_str(ArgType type, const char *colorname)
Build a ColorArg (fore, back, or style value) from a known color name/style.
Definition: colr.c:5327
ColorArg ColorArg_from_StyleValue(ArgType type, StyleValue value)
Explicit version of ColorArg_from_value that only handles StyleValues.
Definition: colr.c:5366
StyleValue
Style values.
Definition: colr.h:2628

Uses ColorArg_from_StyleValue to build a ColorArg with the appropriate color type/value.

Parameters
[in]xStyleValue for the style.
Returns
A ColorArg with the STYLE type set, and it's .value.type set for the appropriate color type/value. For invalid values the .value.type may be set to TYPE_INVALID.
See also
style
style_str

◆ STYLE_LEN_MIN

#define STYLE_LEN_MIN   5

Minimum length for the shortest style escape code, including `'\0'`.

Use STYLE_LEN for allocation.

◆ style_str

#define style_str (   x)    ColorArg_to_esc(style_arg(x))

Return just the escape code string for a style.

Parameters
[in]xStyleValue to use.
Returns

An allocated string.

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

See also
style
style_arg

◆ style_str_static

#define style_str_static (   x)
Value:
(x == RESET_ALL ? "\x1b[0m" : \
(x ==BRIGHT ? "\x1b[1m" : \
(x == DIM ? "\x1b[2m" : \
(x == ITALIC ? "\x1b[3m" : \
(x == UNDERLINE ? "\x1b[4m" : \
(x == FLASH ? "\x1b[5m" : \
(x == HIGHLIGHT ? "\x1b[7m" : \
(x == STRIKETHRU ? "\x1b[9m" : \
(x == NORMAL ? "\x1b[22m" : \
(x == FRAME ? "\x1b[51m" : \
(x == ENCIRCLE ? "\x1b[52m" : \
(x == OVERLINE ? "\x1b[53m" : "\x1b[" colr_macro_str(x) "m" \
))))))))))))

A less-flexible style_str() that returns a static escape code string for a style.

This macro function does not accept style names. Only StyleValue and literal int values are accepted.

The resulting expression will be optimized into a constant static string (https://gcc.godbolt.org/z/TkoWtc).

Parameters
[in]xA StyleValue to use.
Returns
A stack-allocated (read-only) string.
See also
fore_str_static
back_str_static
format_fg
format_bg
◆  style_str_static example:
// This is optimized into a constant static string, even with -g3.
char* ul_codes = style_str_static(UNDERLINE);
printf("%sUnderlined.\n" NC, ul_codes);
// This is also optimized as if you wrote the string "\x1b[4m".
printf("%sNo branches.\n" NC, style_str_static(UNDERLINE));
// This is only optimized when optimizations are turned on (-O2, -O3)
// because of the variable `sval`.
// When compiling for debug (-g3), the compiler will produce branches/jumps
// for each possible StyleValue case.
StyleValue sval = BRIGHT;
printf("%sBranches in debug mode.\n" NC, style_str_static(sval));

◆ while_colr_va_arg

#define while_colr_va_arg (   ap,
  vartype,
 
)    while (x = va_arg(ap, vartype), !_colr_is_last_arg(x))

Construct a while-loop over a va_list, where the last argument is expected to be _ColrLastArg, or a pointer to a _ColrLastArg_s with the same values as _ColrLastArg.

Parameters
[in]apThe va_list to use.
[in]vartypeExpected type of the argument.
[in]xThe variable to assign to (usually arg).

Referenced by _colr_join(), _colr_join_size(), ColorText_from_valuesv(), ColorText_set_values(), and colr_free_argsv().

Typedef Documentation

◆ RGB_fmter

typedef void(* RGB_fmter) (char *out, RGB rgb)

A function type that knows how to fill a string with an rgb escape code.

Enumeration Type Documentation

◆ BasicValue

enum BasicValue

Basic color values, with a few convenience values for extended colors.

Function Documentation

◆ _colr_free()

void _colr_free ( void *  p)

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

You should use the colr_free() macro instead.

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

◆ _colr_is_last_arg()

bool _colr_is_last_arg ( void *  p)

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

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

◆ _colr_join()

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

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

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

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

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

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

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

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

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

◆ _colr_join_array_length()

size_t _colr_join_array_length ( void *  ps)

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

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

Referenced by colr_join_array().

◆ _colr_join_arrayn_size()

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

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

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

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

Referenced by colr_join_arrayn().

◆ _colr_join_size()

size_t _colr_join_size ( void *  joinerp,
va_list  args 
)

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

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

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

Referenced by _colr_join().

◆ _colr_ptr_length()

size_t _colr_ptr_length ( void *  p)

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

This is used in the variadic _colr* functions.

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

Referenced by _colr_join_arrayn_size(), and _colr_join_size().

◆ _colr_ptr_repr()

char* _colr_ptr_repr ( void *  p)

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

You should use colr_repr() instead.

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

See also
colr_repr

◆ _colr_ptr_to_str()

char* _colr_ptr_to_str ( void *  p)

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

◆ _rainbow()

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

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

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

The string to "rainbowize".

Input must be null-terminated.

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

An allocated string (char*) with the result.

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

If allocation fails, NULL is returned.

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

◆ ArgType_eq()

bool ArgType_eq ( ArgType  a,
ArgType  b 
)

Compares two ArgTypes.

This is used to implement colr_eq().

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

◆ ArgType_repr()

char* ArgType_repr ( ArgType  type)

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

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

A pointer to an allocated string.

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

If allocation fails, NULL is returned.

See also
ArgType

Referenced by ColorArg_repr().

◆ ArgType_to_str()

char* ArgType_to_str ( ArgType  type)

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

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

A pointer to an allocated string.

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

If allocation fails, NULL is returned.

See also
ArgType

Referenced by ColorArg_example().

◆ BasicValue_eq()

bool BasicValue_eq ( BasicValue  a,
BasicValue  b 
)

Compares two BasicValues.

This is used to implement colr_eq().

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

◆ BasicValue_from_esc()

BasicValue BasicValue_from_esc ( const char *  s)

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

Parameters
[in]s

Escape-code string.

Must be null-terminated.

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

◆ BasicValue_from_str()

BasicValue BasicValue_from_str ( const char *  arg)

Convert named argument to an actual BasicValue enum value.

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

◆ BasicValue_is_invalid()

bool BasicValue_is_invalid ( BasicValue  bval)

Determines whether a BasicValue is invalid.

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

Referenced by ExtendedValue_from_BasicValue().

◆ BasicValue_is_valid()

bool BasicValue_is_valid ( BasicValue  bval)

Determines whether a BasicValue is valid.

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

◆ BasicValue_repr()

char* BasicValue_repr ( BasicValue  bval)

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

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

A pointer to an allocated string.

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

If allocation fails, NULL is returned.

See also
BasicValue

◆ BasicValue_to_ansi()

int BasicValue_to_ansi ( ArgType  type,
BasicValue  bval 
)

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

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

Referenced by format_bg(), and format_fg().

◆ BasicValue_to_str()

char* BasicValue_to_str ( BasicValue  bval)

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

See also
BasicValue

◆ ColorArg_empty()

ColorArg ColorArg_empty ( void  )

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

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

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

◆ ColorArg_eq()

bool ColorArg_eq ( ColorArg  a,
ColorArg  b 
)

Compares two ColorArg structs.

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

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

Referenced by ColorText_has_arg().

◆ ColorArg_example()

char* ColorArg_example ( ColorArg  carg,
bool  colorized 
)

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

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

◆ ColorArg_free()

void ColorArg_free ( ColorArg p)

Free allocated memory for a ColorArg.

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

Parameters
[in]pColorArg to free.
See also
ColorArg

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

◆ ColorArg_from_BasicValue()

ColorArg ColorArg_from_BasicValue ( ArgType  type,
BasicValue  value 
)

Explicit version of ColorArg_from_value that only handles BasicValues.

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

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

◆ ColorArg_from_esc()

ColorArg ColorArg_from_esc ( const char *  s)

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

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

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

Referenced by ColorArgs_from_str().

◆ ColorArg_from_ExtendedValue()

ColorArg ColorArg_from_ExtendedValue ( ArgType  type,
ExtendedValue  value 
)

Explicit version of ColorArg_from_value that only handles ExtendedValues.

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

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

◆ ColorArg_from_RGB()

ColorArg ColorArg_from_RGB ( ArgType  type,
RGB  value 
)

Explicit version of ColorArg_from_value that only handles RGB structs.

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

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

◆ ColorArg_from_str()

ColorArg ColorArg_from_str ( ArgType  type,
const char *  colorname 
)

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

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

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

◆ ColorArg_from_StyleValue()

ColorArg ColorArg_from_StyleValue ( ArgType  type,
StyleValue  value 
)

Explicit version of ColorArg_from_value that only handles StyleValues.

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

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

◆ ColorArg_from_value()

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

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

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

◆ ColorArg_is_empty()

bool ColorArg_is_empty ( ColorArg  carg)

Checks to see if a ColorArg is an empty placeholder.

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

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

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

◆ ColorArg_is_invalid()

bool ColorArg_is_invalid ( ColorArg  carg)

Checks to see if a ColorArg holds an invalid value.

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

◆ ColorArg_is_ptr()

bool ColorArg_is_ptr ( void *  p)

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

The first member of a ColorArg is a marker.

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

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

◆ ColorArg_is_valid()

bool ColorArg_is_valid ( ColorArg  carg)

Checks to see if a ColorArg holds a valid value.

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

◆ ColorArg_length()

size_t ColorArg_length ( ColorArg  carg)

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

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

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

◆ ColorArg_repr()

char* ColorArg_repr ( ColorArg  carg)

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

Allocates memory for the string representation.

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

Allocated string for the representation.

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

See also
ColorArg

Referenced by _colr_ptr_repr(), and ColorText_repr().

◆ ColorArg_to_esc()

char* ColorArg_to_esc ( ColorArg  carg)

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

Allocates memory for the string.

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

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

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

Allocated string for the escape code.

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

See also
ColorArg

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

◆ ColorArg_to_esc_s()

bool ColorArg_to_esc_s ( char *  dest,
ColorArg  carg 
)

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

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

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

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

Referenced by colr_str_has_ColorArg().

◆ ColorArg_to_ptr()

ColorArg* ColorArg_to_ptr ( ColorArg  carg)

Copies a ColorArg into memory and returns the pointer.

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

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

Pointer to a heap-allocated ColorArg.

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

If allocation fails, NULL is returned.

See also
ColorArg

Referenced by ColorArgs_from_str().

◆ ColorArgs_array_free()

void ColorArgs_array_free ( ColorArg **  ps)

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

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

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

◆ ColorArgs_array_repr()

char* ColorArgs_array_repr ( ColorArg **  lst)

Creates a string representation for an array of ColorArg pointers.

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

◆ ColorArgs_from_str()

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

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

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

Parameters
[in]s

A string to get the escape-codes from.

Must be null-terminated.

[in]uniqueWhether to only include unique ColorArgs.
Returns

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

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

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

◆ ColorJustify_empty()

ColorJustify ColorJustify_empty ( void  )

Creates an "empty" ColorJustify, with JUST_NONE set.

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

Referenced by ColorText_empty().

◆ ColorJustify_eq()

bool ColorJustify_eq ( ColorJustify  a,
ColorJustify  b 
)

Compares two ColorJustify structs.

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

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

◆ ColorJustify_is_empty()

bool ColorJustify_is_empty ( ColorJustify  cjust)

Checks to see if a ColorJustify is "empty".

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

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

Referenced by ColorText_is_empty(), and ColorText_length().

◆ ColorJustify_new()

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

Creates a ColorJustify.

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

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

◆ ColorJustify_repr()

char* ColorJustify_repr ( ColorJustify  cjust)

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

Allocates memory for the string representation.

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

Allocated string for the representation.

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

See also
ColorJustify

Referenced by ColorText_repr().

◆ ColorJustifyMethod_repr()

char* ColorJustifyMethod_repr ( ColorJustifyMethod  meth)

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

Allocates memory for the string representation.

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

Allocated string for the representation.

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

See also
ColorJustifyMethod

Referenced by ColorJustify_repr().

◆ ColorResult_Colr()

ColorResult* ColorResult_Colr ( ColorResult cres,
  ... 
)

Colorize a ColorResult, and return a new allocated ColorResult.

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

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

An allocated ColorResult, or NULL if cres is NULL.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

See also
ColorResult

◆ ColorResult_empty()

ColorResult ColorResult_empty ( void  )

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

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

Referenced by ColorResult_from_stra(), and ColorResult_new().

◆ ColorResult_eq()

bool ColorResult_eq ( ColorResult  a,
ColorResult  b 
)

Compares two ColorResults.

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

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

◆ ColorResult_free()

◆ ColorResult_from_str()

ColorResult ColorResult_from_str ( const char *  s)

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

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

◆ ColorResult_from_stra()

ColorResult* ColorResult_from_stra ( const char *  s)

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

Parameters
[in]sThe string to copy.
Returns

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

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, 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_ptr()

bool ColorResult_is_ptr ( void *  p)

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

The first member of a ColorResult is a marker.

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

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

◆ ColorResult_length()

size_t ColorResult_length ( ColorResult  cres)

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

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

Referenced by _colr_join_arrayn_size(), and _colr_ptr_length().

◆ ColorResult_new()

ColorResult ColorResult_new ( char *  s)

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

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

Referenced by ColorResult_Colr(), ColorResult_from_str(), Colr_fmt_str(), 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_scroll_down(), and Colr_scroll_up().

◆ ColorResult_repr()

char* ColorResult_repr ( ColorResult  cres)

Create a string representation for a ColorResult.

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

See also
ColorResult

Referenced by _colr_ptr_repr().

◆ ColorResult_to_ptr()

ColorResult* ColorResult_to_ptr ( ColorResult  cres)

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

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

Parameters
[in]cresA ColorResult to use.
Returns

An allocated ColorResult.

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

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

If allocation fails, NULL is returned.

See also
ColorResult

Referenced by ColorResult_Colr(), ColorResult_from_stra(), Colr_fmt_str(), 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_scroll_down(), and Colr_scroll_up().

◆ ColorResult_to_str()

char* ColorResult_to_str ( ColorResult  cres)

Convert a ColorResult into a string (char*).

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

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

Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_Colr(), 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)

◆ ColorText_free_args()

void ColorText_free_args ( ColorText p)

Frees the ColorArg members of a ColorText.

The ColorText itself is not free'd.

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

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

Referenced by ColorResult_Colr(), and ColorText_free().

◆ ColorText_from_values()

ColorText ColorText_from_values ( char *  text,
  ... 
)

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

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

◆ ColorText_from_valuesv()

ColorText ColorText_from_valuesv ( char *  text,
va_list  args 
)

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

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

Referenced by ColorResult_Colr(), and ColorText_from_values().

◆ ColorText_has_arg()

bool ColorText_has_arg ( ColorText  ctext,
ColorArg  carg 
)

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

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

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

◆ ColorText_has_args()

bool ColorText_has_args ( ColorText  ctext)

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

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

◆ ColorText_is_empty()

bool ColorText_is_empty ( ColorText  ctext)

Checks to see if a ColorText has no usable values.

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

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

◆ ColorText_is_ptr()

bool ColorText_is_ptr ( void *  p)

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

The first member of a ColorText is a marker.

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

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

◆ ColorText_length()

size_t ColorText_length ( ColorText  ctext)

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

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

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

◆ ColorText_repr()

char* ColorText_repr ( ColorText  ctext)

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

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

Referenced by _colr_ptr_repr().

◆ ColorText_set_just()

ColorText* ColorText_set_just ( ColorText ctext,
ColorJustify  cjust 
)

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

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

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

◆ ColorText_set_values()

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

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

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

◆ ColorText_to_ptr()

ColorText* ColorText_to_ptr ( ColorText  ctext)

Copies a ColorText into allocated memory and returns the pointer.

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

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

Pointer to a heap-allocated ColorText.

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

If allocation fails, NULL is returned.

See also
ColorText

◆ ColorText_to_str()

char* ColorText_to_str ( ColorText  ctext)

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

Parameters
[in]ctextColorText to stringify.
Returns

An allocated string with text/escape-codes.

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

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

See also
ColorText

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

◆ ColorType_eq()

bool ColorType_eq ( ColorType  a,
ColorType  b 
)

Compares two ColorTypes.

This is used to implement colr_eq().

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

◆ ColorType_from_str()

ColorType ColorType_from_str ( const char *  arg)

Determine which type of color value is desired by name.

Example:

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

◆ ColorType_is_invalid()

bool ColorType_is_invalid ( ColorType  type)

Check to see if a ColorType value is considered invalid.

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

◆ ColorType_is_valid()

bool ColorType_is_valid ( ColorType  type)

Check to see if a ColorType value is considered valid.

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

◆ ColorType_repr()

char* ColorType_repr ( ColorType  type)

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

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

A pointer to an allocated string.

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

If allocation fails, NULL is returned.

See also
ColorType

◆ ColorType_to_str()

char* ColorType_to_str ( ColorType  type)

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

See also
ColorType

Referenced by ColorValue_example().

◆ ColorValue_empty()

ColorValue ColorValue_empty ( void  )

Create an "empty" ColorValue.

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

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

◆ ColorValue_eq()

bool ColorValue_eq ( ColorValue  a,
ColorValue  b 
)

Compares two ColorValue structs.

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

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

Referenced by ColorArg_eq().

◆ ColorValue_example()

char* ColorValue_example ( ColorValue  cval)

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_example().

◆ ColorValue_from_esc()

ColorValue ColorValue_from_esc ( const char *  s)

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

Parameters
[in]s

An escape-code string to parse.

Must be null-terminated.

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

Referenced by ColorArg_from_esc().

◆ ColorValue_from_str()

ColorValue ColorValue_from_str ( const char *  s)

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

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

Referenced by ColorArg_from_str().

◆ ColorValue_from_value()

ColorValue ColorValue_from_value ( ColorType  type,
void *  p 
)

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

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

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

◆ ColorValue_has_BasicValue()

bool ColorValue_has_BasicValue ( ColorValue  cval,
BasicValue  bval 
)

Checks to see if a ColorValue has a BasicValue set.

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

◆ ColorValue_has_ExtendedValue()

bool ColorValue_has_ExtendedValue ( ColorValue  cval,
ExtendedValue  eval 
)

Checks to see if a ColorValue has a ExtendedValue set.

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

◆ ColorValue_has_RGB()

bool ColorValue_has_RGB ( ColorValue  cval,
RGB  rgb 
)

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

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

◆ ColorValue_has_StyleValue()

bool ColorValue_has_StyleValue ( ColorValue  cval,
StyleValue  sval 
)

Checks to see if a ColorValue has a StyleValue set.

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

◆ ColorValue_is_empty()

bool ColorValue_is_empty ( ColorValue  cval)

Checks to see if a ColorValue is an empty placeholder.

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

◆ ColorValue_is_invalid()

bool ColorValue_is_invalid ( ColorValue  cval)

Checks to see if a ColorValue holds an invalid value.

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

Referenced by ColorArg_from_esc().

◆ ColorValue_is_valid()

bool ColorValue_is_valid ( ColorValue  cval)

Checks to see if a ColorValue holds a valid value.

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

◆ ColorValue_length()

size_t ColorValue_length ( ArgType  type,
ColorValue  cval 
)

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

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

Referenced by ColorArg_length().

◆ ColorValue_repr()

char* ColorValue_repr ( ColorValue  cval)

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

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

A pointer to an allocated string.

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

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_repr().

◆ ColorValue_to_esc()

char* ColorValue_to_esc ( ArgType  type,
ColorValue  cval 
)

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

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

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

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

If allocation fails, NULL is returned.

See also
ColorValue

Referenced by ColorArg_to_esc().

◆ ColorValue_to_esc_s()

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

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

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

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

Referenced by ColorArg_to_esc_s().

◆ colr_alloc_regmatch()

regmatch_t* colr_alloc_regmatch ( regmatch_t  match)

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

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

Referenced by colr_re_matches().

◆ colr_append_reset()

void colr_append_reset ( char *  s)

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

Parameters
[in]s

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

Must be null-terminated.

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

◆ colr_char_escape_char()

char colr_char_escape_char ( const char  c)

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

The following characters are supported:

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

Referenced by colr_str_repr().

◆ colr_char_in_str()

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

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

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

String to check.

Input must be null-terminated.

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

Referenced by colr_str_chars_lcount(), and colr_str_lstrip_chars().

◆ colr_char_is_code_end()

bool colr_char_is_code_end ( const char  c)

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

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

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

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

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

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

◆ colr_char_repr()

char* colr_char_repr ( char  c)

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

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

An allocated string.

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

If allocation fails, NULL is returned.

Referenced by ColorJustify_repr().

◆ colr_char_should_escape()

bool colr_char_should_escape ( const char  c)

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

The following characters are supported:

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

Referenced by colr_str_repr().

◆ colr_check_marker()

bool colr_check_marker ( uint32_t  marker,
void *  p 
)

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

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

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

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

◆ colr_empty_str()

char* colr_empty_str ( void  )

Allocates an empty string (char*).

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

Returns

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

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

If allocation fails, NULL is returned.

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

◆ Colr_fmt_str()

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

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

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

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

An allocated ColorResult, or NULL if fmt is NULL.

If allocation fails, NULL is returned.

If used inside of the colr_cat(), colr_join(), Colr(), Colr_cat(), and Colr_join() macros, they will free() the result. Otherwise, you are responsible for calling free().

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

◆ colr_free_argsv()

void colr_free_argsv ( va_list  args)

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

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

Referenced by ColorResult_Colr().

◆ colr_free_re_matches()

void colr_free_re_matches ( regmatch_t **  matches)

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

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

Referenced by colr_str_replace_re_pat_all().

◆ colr_is_colr_ptr()

bool colr_is_colr_ptr ( void *  p)

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

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

Referenced by colr_free_argsv().

◆ colr_join_array()

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

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

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

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

◆ colr_join_arrayn()

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

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

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

An allocated string with the result.

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

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

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

Referenced by colr_join_array().

◆ colr_mb_len()

size_t colr_mb_len ( const char *  s,
size_t  length 
)

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

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

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

Referenced by _rainbow().

◆ colr_printf_handler()

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

Handles printing with printf for Colr objects.

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

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

Referenced by colr_printf_register().

◆ colr_printf_info()

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

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

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

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

Referenced by colr_printf_register().

◆ colr_printf_register()

void colr_printf_register ( void  )

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

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

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

◆ colr_re_matches()

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

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

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

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

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

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

Referenced by colr_str_replace_re_pat_all().

◆ colr_set_locale()

bool colr_set_locale ( void  )

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

This is used for functions dealing with multibyte strings.

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

Referenced by colr_mb_len(), and colr_str_mb_len().

◆ colr_str_array_contains()

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

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

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

Referenced by colr_str_get_codes().

◆ colr_str_array_free()

void colr_str_array_free ( char **  ps)

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

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

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

Referenced by ColorArgs_from_str().

◆ colr_str_center()

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

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

Parameters
[in]s

The string to justify.

Input must be null-terminated.

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

An allocated string with the result.

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

If allocation fails, NULL is returned.

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

Referenced by colr_printf_handler().

◆ colr_str_char_count()

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

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

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

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]c

The character to count.

Must not be 0.

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

Referenced by _rainbow().

◆ colr_str_char_lcount()

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

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

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

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]c

The character to count.

Must not be 0.

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

Referenced by colr_str_lstrip_char().

◆ colr_str_chars_lcount()

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

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

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

Parameters
[in]s

The string to examine.

Must be null-terminated.

[in]chars

The characters to count, in any order.

Must not be 0.

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

Referenced by colr_str_lstrip_chars().

◆ colr_str_code_count()

size_t colr_str_code_count ( const char *  s)

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

Parameters
[in]s

A string to count the escape-codes for.

Must be null-terminated.

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

Referenced by colr_str_get_codes().

◆ colr_str_code_len()

size_t colr_str_code_len ( const char *  s)

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

Parameters
[in]s

A string to count the code-chars for.

Must be null-terminated.

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

◆ colr_str_copy()

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

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

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

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

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

A null-terminator is always appended to dest.

src and dest must not overlap.

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

Referenced by ColorResult_from_stra().

◆ colr_str_ends_with()

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

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

str and suffix must not overlap.

Parameters
[in]s

String to check.

Must be null-terminated.

[in]suffix

Suffix to check for.

Must be null-terminated.

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

Referenced by colr_append_reset().

◆ colr_str_get_codes()

char** colr_str_get_codes ( const char *  s,
bool