|
ColrC
0.4.0
An easy to use C library for linux terminal colors/escape-codes.
|
|
|
|
ColrC
0.4.0
An easy to use C library for linux terminal colors/escape-codes.
|
|
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>
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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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_center(text, justwidth, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #define | ColorText_center_char(text, justwidth, c, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #define | ColorText_ljust(text, justwidth, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #define | ColorText_ljust_char(text, justwidth, c, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #define | COLORTEXT_MARKER (UINT32_MAX - 50) |
| Marker for the ColorText struct, for identifying a void pointer as a ColorText. | |
| #define | ColorText_rjust(text, justwidth, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #define | ColorText_rjust_char(text, justwidth, c, ...) |
| Sets the JustifyMethod for a ColorText while allocating it. More... | |
| #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(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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(x, width) |
Like Colr_center_char, it center-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character. More... | |
| #define | colr_center(x, width) colr_center_char(x, width, ' ') |
Like Colr_center it center-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`). More... | |
| #define | colr_center_char(x, width, padchar) |
Like Colr_center_char it left-justifies ColrC objects and strings (char*), except it returns an allocated string (char*). 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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(x, width) |
Like Colr_ljust_char, it left-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character. More... | |
| #define | colr_ljust(x, width) colr_ljust_char(x, width, ' ') |
Like Colr_ljust it left-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`). More... | |
| #define | colr_ljust_char(x, width, padchar) |
Like Colr_ljust_char it left-justifies ColrC objects and strings (char*), except it returns an allocated string (char*). 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(x, width) |
Like Colr_rjust_char, it right-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character. More... | |
| #define | colr_rjust(x, width) colr_rjust_char(x, width, ' ') |
Like Colr_rjust it right-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`). More... | |
| #define | colr_rjust_char(x, width, padchar) |
Like Colr_rjust_char it right-justifies ColrC objects and strings (char*), except it returns an allocated string (char*). 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.4.0" |
| 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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... | |
| ColorArg * | ColorArg_to_ptr (ColorArg carg) |
| Copies a ColorArg into memory and returns the pointer. More... | |
| void | ColorArgs_array_free (ColorArg **ps) |
| Free an allocated array of ColorArgs, including the array itself. More... | |
| char * | ColorArgs_array_repr (ColorArg **lst) |
| Creates a string representation for an array of ColorArg pointers. More... | |
| ColorArg ** | ColorArgs_from_str (const char *s, bool unique) |
Create an array of ColorArgs from escape-codes found in a string (char*). More... | |
| ColorJustify | ColorJustify_empty (void) |
| Creates an "empty" ColorJustify, with JUST_NONE set. More... | |
| bool | ColorJustify_eq (ColorJustify a, ColorJustify b) |
| Compares two ColorJustify structs. More... | |
| bool | ColorJustify_is_empty (ColorJustify cjust) |
| Checks to see if a ColorJustify is "empty". More... | |
| ColorJustify | ColorJustify_new (ColorJustifyMethod method, int width, char padchar) |
| Creates a ColorJustify. More... | |
| char * | ColorJustify_repr (ColorJustify cjust) |
Creates a string (char*) representation for a ColorJustify. More... | |
| char * | ColorJustifyMethod_repr (ColorJustifyMethod meth) |
Creates a string (char*) representation for a ColorJustifyMethod. More... | |
| ColorResult * | ColorResult_center (ColorResult *cres, int width, char padchar) |
| Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
| ColorResult * | ColorResult_Colr (ColorResult *cres,...) |
| Colorize a ColorResult, and return a new allocated ColorResult. More... | |
| ColorResult | ColorResult_empty (void) |
Creates a ColorResult with .result=NULL and .length=-1, with the appropriate struct marker. More... | |
| bool | ColorResult_eq (ColorResult a, ColorResult b) |
| Compares two ColorResults. More... | |
| void | ColorResult_free (ColorResult *p) |
Free allocated memory for a ColorResult and it's .result member. More... | |
| ColorResult | ColorResult_from_str (const char *s) |
| Allocates a copy of a string, and creates a ColorResult from it. More... | |
| ColorResult * | ColorResult_from_stra (const char *s) |
| Allocates a copy of a string, and creates an allocated ColorResult from it. More... | |
| bool | ColorResult_is_empty (ColorResult cres) |
| Checks to see if a ColorResult is "empty" (NULL or empty string). More... | |
| bool | ColorResult_is_ptr (void *p) |
| Checks a void pointer to see if it contains a ColorResult struct. More... | |
| size_t | ColorResult_length (ColorResult cres) |
Return the length in bytes (including the null-terminator), that is needed to store the return from ColorResult_to_str() (.result). More... | |
| ColorResult * | ColorResult_ljust (ColorResult *cres, int width, char padchar) |
| Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
| ColorResult | ColorResult_new (char *s) |
Initialize a new ColorResult with an allocated string (char*). More... | |
| char * | ColorResult_repr (ColorResult cres) |
| Create a string representation for a ColorResult. More... | |
| char * | ColorResult_rip_str (ColorResult *cres) |
Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char*)). More... | |
| ColorResult * | ColorResult_rjust (ColorResult *cres, int width, char padchar) |
| Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty"). More... | |
| ColorResult * | ColorResult_to_ptr (ColorResult cres) |
| Allocate memory for a ColorResult, fill it, and return it. More... | |
| char * | ColorResult_to_str (ColorResult cres) |
Convert a ColorResult into a string (char*). More... | |
| ColorText | ColorText_empty (void) |
Creates an "empty" ColorText with pointers set to NULL. More... | |
| void | ColorText_free (ColorText *p) |
| Frees a ColorText and it's ColorArgs. More... | |
| void | ColorText_free_args (ColorText *p) |
| Frees the ColorArg members of a ColorText. More... | |
| ColorText | ColorText_from_values (char *text,...) |
Builds a ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More... | |
| ColorText | ColorText_from_valuesv (char *text, va_list args) |
Builds a ColorText from 1 mandatory string (char*), and a va_list with optional fore, back, and style args (pointers to ColorArgs). More... | |
| bool | ColorText_has_arg (ColorText ctext, ColorArg carg) |
| Checks to see if a ColorText has a certain ColorArg value set. More... | |
| bool | ColorText_has_args (ColorText ctext) |
| Checks to see if a ColorText has any argument values set. More... | |
| bool | ColorText_is_empty (ColorText ctext) |
| Checks to see if a ColorText has no usable values. More... | |
| bool | ColorText_is_ptr (void *p) |
| Checks a void pointer to see if it contains a ColorText struct. More... | |
| size_t | ColorText_length (ColorText ctext) |
Returns the length in bytes needed to allocate a string (char*) built with ColorText_to_str() with the current text, fore, back, and style members. More... | |
| char * | ColorText_repr (ColorText ctext) |
Allocate a string (char*) representation for a ColorText. More... | |
| ColorText * | ColorText_set_center (ColorText *ctext, int width, char padchar) |
| Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string. More... | |
| ColorText * | ColorText_set_just (ColorText *ctext, ColorJustify cjust) |
| Set the ColorJustify method for a ColorText, and return the ColorText. More... | |
| ColorText * | ColorText_set_ljust (ColorText *ctext, int width, char padchar) |
| Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string. More... | |
| ColorText * | ColorText_set_rjust (ColorText *ctext, int width, char padchar) |
| Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string. More... | |
| void | ColorText_set_values (ColorText *ctext, char *text,...) |
Initializes an existing ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs). More... | |
| ColorText * | ColorText_to_ptr (ColorText ctext) |
| Copies a ColorText into allocated memory and returns the pointer. More... | |
| char * | ColorText_to_str (ColorText ctext) |
| Stringifies a ColorText struct, creating a mix of escape codes and text. More... | |
| bool | ColorType_eq (ColorType a, ColorType b) |
| Compares two ColorTypes. More... | |
| ColorType | ColorType_from_str (const char *arg) |
| Determine which type of color value is desired by name. More... | |
| bool | ColorType_is_invalid (ColorType type) |
| Check to see if a ColorType value is considered invalid. More... | |
| bool | ColorType_is_valid (ColorType type) |
| Check to see if a ColorType value is considered valid. More... | |
| char * | ColorType_repr (ColorType type) |
Creates a string (char*) representation of a ColorType. More... | |
| char * | ColorType_to_str (ColorType type) |
Create a human-friendly string (char*) representation for a ColorType. More... | |
| ColorValue | ColorValue_empty (void) |
| Create an "empty" ColorValue. More... | |
| bool | ColorValue_eq (ColorValue a, ColorValue b) |
| Compares two ColorValue structs. More... | |
| char * | ColorValue_example (ColorValue cval) |
Create a string (char*) representation of a ColorValue with a human-friendly type/name. More... | |
| ColorValue | ColorValue_from_esc (const char *s) |
Convert an escape-code string (char*) into a ColorValue. More... | |
| ColorValue | ColorValue_from_str (const char *s) |
Create a ColorValue from a known color name, or RGB string (char*). More... | |
| ColorValue | ColorValue_from_value (ColorType type, void *p) |
| Used with the color_val macro to dynamically create a ColorValue based on it's argument type. More... | |
| bool | ColorValue_has_BasicValue (ColorValue cval, BasicValue bval) |
| Checks to see if a ColorValue has a BasicValue set. More... | |
| bool | ColorValue_has_ExtendedValue (ColorValue cval, ExtendedValue eval) |
| Checks to see if a ColorValue has a ExtendedValue set. More... | |
| bool | ColorValue_has_RGB (ColorValue cval, RGB rgb) |
| Checks to see if a ColorValue has a RGB value set. More... | |
| bool | ColorValue_has_StyleValue (ColorValue cval, StyleValue sval) |
| Checks to see if a ColorValue has a StyleValue set. More... | |
| bool | ColorValue_is_empty (ColorValue cval) |
| Checks to see if a ColorValue is an empty placeholder. More... | |
| bool | ColorValue_is_invalid (ColorValue cval) |
| Checks to see if a ColorValue holds an invalid value. More... | |
| bool | ColorValue_is_valid (ColorValue cval) |
| Checks to see if a ColorValue holds a valid value. More... | |
| size_t | ColorValue_length (ArgType type, ColorValue cval) |
Returns the length in bytes needed to allocate a string (char*) built with ColorValue_to_esc() with the specified ArgType and ColorValue. More... | |
| char * | ColorValue_repr (ColorValue cval) |
Creates a string (char*) representation of a ColorValue. More... | |
| char * | ColorValue_to_esc (ArgType type, ColorValue cval) |
Converts a ColorValue into an escape code string (char*). More... | |
| bool | ColorValue_to_esc_s (char *dest, ArgType type, ColorValue cval) |
Converts a ColorValue into an escape code string (char*) and fills the destination string. More... | |
| regmatch_t * | colr_alloc_regmatch (regmatch_t match) |
| Allocates space for a regmatch_t, initializes it, and returns a pointer to it. More... | |
| void | colr_append_reset (char *s) |
Appends CODE_RESET_ALL to a string (char*), but makes sure to do it before any newlines. More... | |
| ColorResult * | Colr_center_char (void *x, int width, char padchar) |
Returns a center-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More... | |
| char | colr_char_escape_char (const char c) |
| Returns the char needed to represent an escape sequence in C. More... | |
| bool | colr_char_in_str (const char *s, const char c) |
Determines if a character exists in the given string (char*). More... | |
| bool | colr_char_is_code_end (const char c) |
| Determines if a character is suitable for an escape code ending. More... | |
| char * | colr_char_repr (char c) |
Creates a string (char*) representation for a char. More... | |
| bool | colr_char_should_escape (const char c) |
| Determines if an ascii character has an escape sequence in C. More... | |
| bool | colr_check_marker (uint32_t marker, void *p) |
| Checks an unsigned int against the individual bytes behind a pointer's value. More... | |
| char * | colr_empty_str (void) |
Allocates an empty string (char*). More... | |
| ColorResult * | Colr_fmt_str (const char *fmt,...) |
Allocate and format a string like asprintf, but wrap it in an allocated ColorResult. More... | |
| void | colr_free_argsv (va_list args) |
Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list. More... | |
| void | colr_free_re_matches (regmatch_t **matches) |
Free an array of allocated regmatch_t, like the return from colr_re_matches(). More... | |
| bool | colr_is_colr_ptr (void *p) |
| Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer. More... | |
| char * | colr_join_array (void *joinerp, void *ps) |
Join an array of strings (char*), 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... | |
| ColorResult * | Colr_ljust_char (void *x, int width, char padchar) |
Returns a left-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More... | |
| size_t | colr_mb_len (const char *s, size_t length) |
Like mbrlen, except it will return the length of the next N (length) multibyte characters in bytes. More... | |
| int | colr_printf_handler (FILE *fp, const struct printf_info *info, const void *const *args) |
| Handles printing with printf for Colr objects. More... | |
| int | colr_printf_info (const struct printf_info *info, size_t n, int *argtypes, int *sz) |
| Handles the arg count/size for the Colr printf handler. More... | |
| void | colr_printf_register (void) |
| Registers COLR_FMT_CHAR to handle Colr objects in the printf-family functions. More... | |
| regmatch_t ** | colr_re_matches (const char *s, regex_t *repattern) |
Returns all regmatch_t matches for regex pattern in a string (char*). More... | |
| ColorResult * | Colr_rjust_char (void *x, int width, char padchar) |
Returns a right-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character. More... | |
| bool | colr_set_locale (void) |
Sets the locale to (LC_ALL, "") if it hasn't already been set. More... | |
| bool | colr_str_array_contains (char **lst, const char *s) |
Determine if a string (char*) is in an array of strings (char**, where the last element is NULL). More... | |
| void | colr_str_array_free (char **ps) |
| Free an allocated array of strings, including the array itself. More... | |
| char * | colr_str_center (const char *s, int width, const char padchar) |
Center-justifies a string (char*), ignoring escape codes when measuring the width. More... | |
| size_t | colr_str_char_count (const char *s, const char c) |
Counts the number of characters (c) that are found in a string (char*) (s). More... | |
| size_t | colr_str_char_lcount (const char *s, const char c) |
Counts the number of characters (c) that are found at the beginning of a string (char*) (s). More... | |
| size_t | colr_str_chars_lcount (const char *restrict s, const char *restrict chars) |
Counts the number of characters that are found at the beginning of a string (char*) (s), where the character can be any of chars. More... | |
| size_t | colr_str_code_count (const char *s) |
Return the number of escape-codes in a string (char*). More... | |
| size_t | colr_str_code_len (const char *s) |
Return the number of bytes that make up all the escape-codes in a string (char*). More... | |
| char * | colr_str_copy (char *restrict dest, const char *restrict src, size_t length) |
Copies a string (char*) like strncpy, but ensures null-termination. More... | |
| bool | colr_str_ends_with (const char *restrict s, const char *restrict suffix) |
Determine if one string (char*) ends with another. More... | |
| char ** | colr_str_get_codes (const char *s, bool unique) |
Get an array of escape-codes from a string (char*). More... | |
| bool | colr_str_has_codes (const char *s) |
Determines if a string (char*) has ANSI escape codes in it. More... | |
| bool | colr_str_has_ColorArg (const char *s, ColorArg *carg) |
| Determines whether a string contains a specific color code. More... | |
| ColrHash | colr_str_hash (const char *s) |
| Hash a string using djb2. More... | |
| bool | colr_str_is_all (const char *s, const char c) |
Determines whether a string (char*) consists of only one character, possibly repeated. More... | |
| bool | colr_str_is_codes (const char *s) |
Determines if a string (char*) is composed entirely of escape codes. More... | |
| bool | colr_str_is_digits (const char *s) |
Determines whether all characters in a string (char*) are digits. More... | |
| bool | colr_str_is_empty (const char *s) |
| Checks to see if a string empty. More... | |
| char * | colr_str_ljust (const char *s, int width, const char padchar) |
Left-justifies a string (char*), ignoring escape codes when measuring the width. More... | |
| void | colr_str_lower (char *s) |
Converts a string (char*) into lower case in place. More... | |
| size_t | colr_str_lstrip (char *restrict dest, const char *restrict s, size_t length, const char c) |
Strip a leading character from a string (char*), filling another string (char*) with the result. More... | |
| char * | colr_str_lstrip_char (const char *s, const char c) |
Strips a leading character from a string (char*), and allocates a new string with the result. More... | |
| char * | colr_str_lstrip_chars (const char *restrict s, const char *restrict chars) |
Removes certain characters from the start of a string (char*) and allocates a new string with the result. More... | |
| size_t | colr_str_mb_len (const char *s) |
Returns the number of characters in a string (char*), taking into account possibly multibyte characters. More... | |
| size_t | colr_str_noncode_len (const char *s) |
Returns the length of string (char*), ignoring escape codes and the the null-terminator. More... | |
| char * | colr_str_replace (const char *restrict s, const char *restrict target, const char *restrict repl) |
Replaces the first substring found in a string (char*). More... | |
| char * | colr_str_replace_all (const char *restrict s, const char *restrict target, const char *restrict repl) |
Replaces the first substring found in a string (char*). More... | |
| char * | colr_str_replace_all_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl) |
Replace all substrings in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_all_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl) |
Replace all substrings in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_all_ColorText (const char *restrict s, const char *restrict target, ColorText *repl) |
Replace all substrings in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_cnt (const char *restrict s, const char *restrict target, const char *restrict repl, int count) |
Replaces one or more substrings in a string (char*). More... | |
| char * | colr_str_replace_ColorArg (const char *restrict s, const char *restrict target, ColorArg *repl) |
Replace a substring in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_ColorResult (const char *restrict s, const char *restrict target, ColorResult *repl) |
Replace a substring in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_ColorText (const char *restrict s, const char *restrict target, ColorText *repl) |
Replace a substring in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags) |
Replaces a substring from a regex pattern string (char*) in a string (char*). More... | |
| char * | colr_str_replace_re_all (const char *restrict s, const char *restrict pattern, const char *restrict repl, int re_flags) |
Replaces all substrings from a regex pattern string (char*) in a string (char*). More... | |
| char * | colr_str_replace_re_all_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_all_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_all_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re_ColorArg (const char *restrict s, const char *restrict pattern, ColorArg *repl, int re_flags) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_ColorResult (const char *restrict s, const char *restrict pattern, ColorResult *repl, int re_flags) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_ColorText (const char *restrict s, const char *restrict pattern, ColorText *repl, int re_flags) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re_match (const char *restrict s, regmatch_t *match, const char *restrict repl) |
Replaces substrings from a single regex match (regmatch_t*) in a string (char*). More... | |
| char * | colr_str_replace_re_match_ColorArg (const char *restrict s, regmatch_t *match, ColorArg *repl) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_match_ColorResult (const char *restrict s, regmatch_t *match, ColorResult *repl) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_match_ColorText (const char *restrict s, regmatch_t *match, ColorText *repl) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re_match_i (const char *restrict ref, char *target, regmatch_t *match, const char *restrict repl) |
Replaces substrings from a regex match (regmatch_t*) in a string (char*). More... | |
| char * | colr_str_replace_re_matches (const char *restrict s, regmatch_t **matches, const char *restrict repl) |
Replaces substrings from an array of regex match (regmatch_t*) in a string (char*). More... | |
| char * | colr_str_replace_re_matches_ColorArg (const char *restrict s, regmatch_t **matches, ColorArg *repl) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_matches_ColorResult (const char *restrict s, regmatch_t **matches, ColorResult *repl) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_matches_ColorText (const char *restrict s, regmatch_t **matches, ColorText *repl) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re_pat (const char *restrict s, regex_t *repattern, const char *restrict repl) |
Replaces regex patterns in a string (char*). More... | |
| char * | colr_str_replace_re_pat_all (const char *restrict s, regex_t *repattern, const char *restrict repl) |
Replaces all matches to a regex pattern in a string (char*). More... | |
| char * | colr_str_replace_re_pat_all_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl) |
Replace all matches to a regex pattern in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_pat_all_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl) |
Replace all matches to a regex pattern in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_pat_all_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl) |
Replace all matches to a regex pattern in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_replace_re_pat_ColorArg (const char *restrict s, regex_t *repattern, ColorArg *repl) |
Replace regex patterns in a string (char*) with a ColorArg's string result. More... | |
| char * | colr_str_replace_re_pat_ColorResult (const char *restrict s, regex_t *repattern, ColorResult *repl) |
Replace regex patterns in a string (char*) with a ColorResult's string result. More... | |
| char * | colr_str_replace_re_pat_ColorText (const char *restrict s, regex_t *repattern, ColorText *repl) |
Replace regex patterns in a string (char*) with a ColorText's string result. More... | |
| char * | colr_str_repr (const char *s) |
Convert a string (char*) into a representation of a string, by wrapping it in quotes and escaping characters that need escaping. More... | |
| char * | colr_str_rjust (const char *s, int width, const char padchar) |
Right-justifies a string (char*), ignoring escape codes when measuring the width. More... | |
| bool | colr_str_starts_with (const char *restrict s, const char *restrict prefix) |
Checks a string (char*) for a certain prefix substring. More... | |
| char * | colr_str_strip_codes (const char *s) |
Strips escape codes from a string (char*), resulting in a new allocated string. More... | |
| char * | colr_str_to_lower (const char *s) |
Allocate a new lowercase version of a string (char*). More... | |
| bool | colr_supports_rgb (void) |
| Determine whether the current environment support RGB (True Colors). More... | |
| bool | colr_supports_rgb_static (void) |
| Same as colr_supports_rgb(), but the environment is only checked on the first call. More... | |
| TermSize | colr_term_size (void) |
| Attempts to retrieve the row/column size of the terminal and returns a TermSize. More... | |
| struct winsize | colr_win_size (void) |
Attempts to retrieve a winsize struct from an ioctl call. More... | |
| struct winsize | colr_win_size_env (void) |
Get window/terminal size using the environment variables LINES, COLUMNS, or COLS. More... | |
| bool | ExtendedValue_eq (ExtendedValue a, ExtendedValue b) |
| Compares two ExtendedValues. More... | |
| int | ExtendedValue_from_BasicValue (BasicValue bval) |
| Convert a BasicValue into an ExtendedValue. More... | |
| int | ExtendedValue_from_esc (const char *s) |
Convert an escape-code string (char*) to an ExtendedValue. More... | |
| int | ExtendedValue_from_hex (const char *hexstr) |
Create an ExtendedValue from a hex string (char*). More... | |
| ExtendedValue | ExtendedValue_from_hex_default (const char *hexstr, ExtendedValue default_value) |
Create an ExtendedValue from a hex string (char*), but return a default value if the hex string is invalid. More... | |
| ExtendedValue | ExtendedValue_from_RGB (RGB rgb) |
| Convert an RGB value into the closest matching ExtendedValue. More... | |
| int | ExtendedValue_from_str (const char *arg) |
Converts a known name, integer string (0-255), or a hex string (char*), into an ExtendedValue suitable for the extended-value-based functions. More... | |
| bool | ExtendedValue_is_invalid (int eval) |
| Determines whether an integer is an invalid ExtendedValue. More... | |
| bool | ExtendedValue_is_valid (int eval) |
| Determines whether an integer is a valid ExtendedValue. More... | |
| char * | ExtendedValue_repr (int eval) |
Creates a string (char*) representation of a ExtendedValue. More... | |
| char * | ExtendedValue_to_str (ExtendedValue eval) |
Creates a human-friendly string (char*) from an ExtendedValue's actual value, suitable for use with ExtendedValue_from_str(). More... | |
| void | format_bg (char *out, BasicValue value) |
| Create an escape code for a background color. More... | |
| void | format_bg_RGB (char *out, RGB rgb) |
| Create an escape code for a true color (rgb) background color using values from an RGB struct. More... | |
| void | format_bg_RGB_term (char *out, RGB rgb) |
| Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More... | |
| void | format_bgx (char *out, unsigned char num) |
| Create an escape code for an extended background color. More... | |
| void | format_fg (char *out, BasicValue value) |
| Create an escape code for a fore color. More... | |
| void | format_fg_RGB (char *out, RGB rgb) |
| Create an escape code for a true color (rgb) fore color using an RGB struct's values. More... | |
| void | format_fg_RGB_term (char *out, RGB rgb) |
| Create an escape code for a true color (rgb) fore color using an RGB struct's values, approximating 256-color values. More... | |
| void | format_fgx (char *out, unsigned char num) |
| Create an escape code for an extended fore color. More... | |
| void | format_style (char *out, StyleValue style) |
| Create an escape code for a style. More... | |
| char * | rainbow_bg (const char *s, double freq, size_t offset, size_t spread) |
| Rainbow-ize some text using rgb back colors, lolcat style. More... | |
| char * | rainbow_bg_term (const char *s, double freq, size_t offset, size_t spread) |
| This is exactly like rainbow_bg(), except it uses colors that are closer to the standard 256-color values. More... | |
| char * | rainbow_fg (const char *s, double freq, size_t offset, size_t spread) |
| Rainbow-ize some text using rgb fore colors, lolcat style. More... | |
| char * | rainbow_fg_term (const char *s, double freq, size_t offset, size_t spread) |
| This is exactly like rainbow_fg(), except it uses colors that are closer to the standard 256-color values. More... | |
| RGB | rainbow_step (double freq, size_t offset) |
| A single step in rainbow-izing produces the next color in the "rainbow" as an RGB value. More... | |
| unsigned char | RGB_average (RGB rgb) |
| Return the average for an RGB value. More... | |
| bool | RGB_eq (RGB a, RGB b) |
| Compare two RGB structs. More... | |
| RGB | RGB_from_BasicValue (BasicValue bval) |
| Return an RGB value from a known BasicValue. More... | |
| int | RGB_from_esc (const char *s, RGB *rgb) |
Convert an escape-code string (char*) to an actual RGB value. More... | |
| RGB | RGB_from_ExtendedValue (ExtendedValue eval) |
| Return an RGB value from a known ExtendedValue. More... | |
| int | RGB_from_hex (const char *hexstr, RGB *rgb) |
| Convert a hex color into an RGB value. More... | |
| RGB | RGB_from_hex_default (const char *hexstr, RGB default_value) |
| Convert a hex color into an RGB value, but use a default value when errors occur. More... | |
| int | RGB_from_str (const char *arg, RGB *rgb) |
Convert an RGB string (char*) into an RGB value. More... | |
| RGB | RGB_grayscale (RGB rgb) |
| Return a grayscale version of an RGB value. More... | |
| RGB | RGB_inverted (RGB rgb) |
| Make a copy of an RGB value, with the colors "inverted" (like highlighting text in the terminal). More... | |
| RGB | RGB_monochrome (RGB rgb) |
| Convert an RGB value into either black or white, depending on it's average grayscale value. More... | |
| char * | RGB_repr (RGB rgb) |
Creates a string (char*) representation for an RGB value. More... | |
| char * | RGB_to_hex (RGB rgb) |
Converts an RGB value into a hex string (char*). More... | |
| char * | RGB_to_str (RGB rgb) |
Convert an RGB value into a human-friendly RGB string (char*) suitable for input to RGB_from_str(). More... | |
| RGB | RGB_to_term_RGB (RGB rgb) |
| Convert an RGB value into it's nearest terminal-friendly RGB value. More... | |
| bool | StyleValue_eq (StyleValue a, StyleValue b) |
| Compares two StyleValues. More... | |
| StyleValue | StyleValue_from_esc (const char *s) |
Convert an escape-code string (char*) to an actual StyleValue enum value. More... | |
| StyleValue | StyleValue_from_str (const char *arg) |
| Convert a named argument to actual StyleValue enum value. More... | |
| bool | StyleValue_is_invalid (StyleValue sval) |
| Determines whether a StyleValue is invalid. More... | |
| bool | StyleValue_is_valid (StyleValue sval) |
| Determines whether a StyleValue is valid. More... | |
| char * | StyleValue_repr (StyleValue sval) |
Creates a string (char*) representation of a StyleValue. More... | |
| char * | StyleValue_to_str (StyleValue sval) |
Create a human-friendly string (char*) representation for a StyleValue. More... | |
| char * | TermSize_repr (TermSize ts) |
Create a string (char*) representation for a TermSize. More... | |
Variables | |
| int | colr_printf_esc_mod |
| Integer to test for the presence of the "escaped output modifier" in colr_printf_handler. More... | |
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.
| 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 | |
| struct ColorArg |
Holds an ArgType, and a ColorValue.
| 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. |
| 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(). |
| 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.
| 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. |
| struct ColorResult |
Holds a string (char*) that was definitely allocated by Colr.
| 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 |
| 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. |
| 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. |
| struct ColorStructMarker.bytes |
| struct ColorText |
Holds a string of text, and optional fore, back, and style ColorArgs.
| 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. |
| 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.
| Data Fields | ||
|---|---|---|
| BasicValue | basic | |
| ExtendedValue | ext | |
| RGB | rgb | |
| StyleValue | style | |
| ColorType | type | |
| 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 | |
| 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. |
| 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 | |
| struct TermSize |
Holds a terminal size, usually retrieved with colr_term_size().
| Data Fields | ||
|---|---|---|
| unsigned short | columns | |
| unsigned short | rows | |
| #define alloc_basic | ( | ) | calloc(CODE_LEN, sizeof(char)) |
Allocate enough for a basic code.
Pointer to the allocated string, or NULL on error.
You must free() the memory allocated by this function.
| #define alloc_extended | ( | ) | calloc(CODEX_LEN, sizeof(char)) |
Allocate enough for an extended code.
Pointer to the allocated string, or NULL on error.
You must free() the memory allocated by this function.
| #define alloc_rgb | ( | ) | calloc(CODE_RGB_LEN, sizeof(char)) |
Allocate enough for an rgb code.
Pointer to the allocated string, or NULL on error.
You must free() the memory allocated by this function.
| #define alloc_style | ( | ) | calloc(STYLE_LEN, sizeof(char)) |
Allocate enough for a style code.
Pointer to the allocated string, or NULL on error.
You must free() the memory allocated by this function.
| #define asprintf_or_return | ( | retval, | |
| ... | |||
| ) | if_not_asprintf(__VA_ARGS__) return retval |
Convenience macro for bailing out of a function when asprintf fails.
| [in] | retval | Value to return if the asprintf fails. |
| [in] | ... | Arguments for asprintf. |
Referenced by BasicValue_to_str(), ColorArg_repr(), ColorArgs_array_repr(), ColorJustify_repr(), ColorText_repr(), colr_char_repr(), 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(), Colr_scroll_up(), colr_str_center(), colr_str_ljust(), colr_str_replace_re_match(), colr_str_repr(), colr_str_rjust(), ExtendedValue_repr(), ExtendedValue_to_str(), RGB_repr(), RGB_to_hex(), RGB_to_str(), StyleValue_to_str(), and TermSize_repr().
| #define back | ( | x | ) | ColorArg_to_ptr(back_arg(x)) |
Create a back color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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.
| [in] | x | A BasicValue, ExtendedValue, or RGB struct to use for the color value. |
free() the result. Otherwise, you are responsible for calling free(). | #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.
Uses _Generic (C11 standard) to dynamically create a ColorArg. This is used by the back() macro.
| [in] | x | BasicValue, Extended (unsigned char), RGB struct, or string (color name) for back color. |
.value.type set for the appropriate color type/value..value.type may be set to TYPE_INVALID.free() the memory allocated by this function. | #define back_str | ( | x | ) | ColorArg_to_esc(back_arg(x)) |
| #define back_str_static | ( | x | ) |
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().
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().
| [in] | x | A BasicValue, ExtendedValue, or RGB value. |
| #define basic | ( | x | ) | ((BasicValue)(x)) |
| #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.
| [in] | x | An enum to convert to boolean. |
| true | if the value is considered valid, or non-empty. |
| false | if 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().
| #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).
Referenced by colr_str_has_ColorArg().
| #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().
| #define CODE_LEN_MIN 5 |
Minimum length for the shortest basic fore/back escape code, including `'\0'`.
Use CODE_LEN for allocation.
| #define CODE_RGB_LEN_MIN 14 |
Minimum length for the shortest RGB fore/back escape code, including `'\0'`.
Use CODE_RGB_LEN for allocation.
| #define CODEX_LEN_MIN 10 |
Minimum length for the shortest extended fore/back escape code, including `'\0'`.
Use CODEX_LEN for allocation.
| #define color_arg | ( | type, | |
| x | |||
| ) |
Builds a correct ColorArg struct according to the type of it's second argument.
Uses _Generic (C11 standard) to dynamically create a ColorArg.
| [in] | type | ArgType (FORE, BACK, STYLE) to build the ColorArg. |
| [in] | x | BasicValue, Extended (unsigned char). or RGB value. |
| #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.
| #define color_name_is_invalid | ( | x | ) | ColorType_is_invalid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is invalid.
| [in] | x | string (char*) to check (a name, hex-string, rgb-string, or integer-string). |
true if the name is an invalid color name, otherwise false.| #define color_name_is_valid | ( | x | ) | ColorType_is_valid(ColorType_from_str(x)) |
Convenience macro for checking if a color name is valid.
| [in] | x | string (char*) to check (a name, hex-string, rgb-string, or integer-string). |
true if the name is a valid color name, otherwise false.| #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.
| #define color_val | ( | x | ) |
Builds a correct ColorValue struct according to the type of it's first argument.
Uses _Generic (C11 standard) to dynamically create a ColorValue.
| [in] | x | BasicValue, Extended (unsigned char). or RGB value. |
| #define COLORARG_MARKER UINT32_MAX |
Marker for the ColorArg struct, for identifying a void pointer as a ColorArg.
Referenced by ColorArg_empty(), ColorArg_from_BasicValue(), ColorArg_from_esc(), ColorArg_from_ExtendedValue(), ColorArg_from_RGB(), ColorArg_from_StyleValue(), ColorArg_from_value(), ColorArg_is_ptr(), and ColorArg_to_ptr().
| #define ColorText_center | ( | text, | |
| justwidth, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_center_char(), except is uses space as the default character.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorText_center_char | ( | text, | |
| justwidth, | |||
| c, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | c | The character to pad with. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorText_ljust | ( | text, | |
| justwidth, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_ljust_char(), except is uses space as the default character.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorText_ljust_char | ( | text, | |
| justwidth, | |||
| c, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | c | The character to pad with. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorText_rjust | ( | text, | |
| justwidth, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
This is like ColorText_rjust_char(), except is uses space as the default character.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorText_rjust_char | ( | text, | |
| justwidth, | |||
| c, | |||
| ... | |||
| ) |
Sets the JustifyMethod for a ColorText while allocating it.
| [in] | text | Text to colorize. |
| [in] | justwidth | Width for justification. |
| [in] | c | The character to pad with. |
| [in] | ... | Fore, back, or style ColorArgs for Colr(). |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ColorValue_has | ( | cval, | |
| val | |||
| ) |
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.
| [in] | cval | The ColorValue to check. |
| [in] | val | A BasicValue, ExtendedValue, StyleValue, or RGB value. |
true if the ColorValue has the correct .type and it's value matches val, otherwise false.| #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(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
You must free() the resulting ColorText struct using ColorText_free(), unless you pass it to colr_cat(), which will free() it for you.
| [in] | text | String to colorize/style. |
| [in] | ... | One to three ColorArg pointers for fore, back, and style in any order. |
An allocated ColorText.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
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.
| [in] | text | String 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. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #define colr_alloc_len | ( | x | ) |
Return the number of bytes needed to allocate an escape code string based on the color type.
| [in] | x | A BasicValue, ExtendedValue, RGB value, or StyleValue. |
| #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.
| [in] | ... | Arguments for `asprintf colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
asprintf. | #define Colr_cat | ( | ... | ) | ColorResult_to_ptr(ColorResult_new(colr_cat(__VA_ARGS__))) |
Like colr_cat(), but returns an allocated ColorResult that the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free().
| [in] | ... | Arguments for colr_cat(), to concatenate. colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
Referenced by Colr_erase_display().
| #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.
| [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. |
free() the memory allocated by this function. | #define Colr_center | ( | x, | |
| width | |||
| ) |
Like Colr_center_char, it center-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| #define colr_center | ( | x, | |
| width | |||
| ) | colr_center_char(x, width, ' ') |
Like Colr_center it center-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #define colr_center_char | ( | x, | |
| width, | |||
| padchar | |||
| ) |
Like Colr_center_char it left-justifies ColrC objects and strings (char*), except it returns an allocated string (char*).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| [in] | padchar | Pad character to use. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #define colr_eq | ( | a, | |
| b | |||
| ) |
Calls the <type>_eq functions for the supported types.
The types for a and b must be the same.
| [in] | a | First supported type to compare. |
| [in] | b | Second supported type to compare. |
true if the values are equal, otherwise false. | #define colr_example | ( | x | ) |
Calls the <type>_example functions for the supported types.
This is used to create a human-friendly representation for ColorArgs or ColorValues.
| [in] | x | A supported type to get an example string for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #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.
| #define Colr_fmt | ( | fmt, | |
| value, | |||
| ... | |||
| ) |
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.
| [in] | fmt | The format string. |
| [in] | value | The value to format. |
| [in] | ... | At least one of fore(), back(), or style() arguments in any order. |
An allocated ColorResult.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define colr_fprint | ( | file, | |
| ... | |||
| ) |
Create a string from a colr_cat() call, print it to file (without a newline), and free it.
| [in] | file | FILE stream for output. |
| [in] | ... | Arguments for colr_cat(). |
| #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.
| [in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
fprintf. | #define colr_free | ( | x | ) |
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).
| [in] | x | A pointer to a supported type to free. |
Referenced by colr_free_argsv().
| #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.
| #define colr_is_empty | ( | x | ) |
Calls the <type>is_empty functions for the supported types.
| [in] | x | A supported type to build a string from. |
| #define colr_is_invalid | ( | x | ) |
Calls the <type>is_invalid functions for the supported types.
| [in] | x | A supported type to build a string from. |
| #define colr_is_valid | ( | x | ) |
Calls the <type>is_valid functions for the supported types.
| [in] | x | A supported type to build a string from. |
| #define colr_is_valid_mblen | ( | x | ) | ((x) && ((x) != (size_t)-1) && ((x) != (size_t)-2)) |
Checks return values from mbrlen() and colr_mb_len().
| [in] | x | A size_t return value to check, from mbrlen() or colr_mb_len(). |
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().
| #define colr_istr_either | ( | s1, | |
| s2, | |||
| s3 | |||
| ) |
Convenience macro for !strcasecmp(s1, s2) || !strcasecmp(s1, s3).
| [in] | s1 | The string to compare against the other two strings. |
| [in] | s2 | The first string to compare with. |
| [in] | s3 | The second string to compare with. |
1 if s1 is equal to s2 or s3, otherwise 0. Referenced by colr_supports_rgb().
| #define colr_istr_eq | ( | s1, | |
| s2 | |||
| ) |
Convenience macro for !strcasecmp(s1, s2).
| [in] | s1 | The first string to compare. |
| [in] | s2 | The second string to compare. |
1 if s1 and s2 are equal, otherwise 0. | #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(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros will automatically free() for you.
| [in] | joiner | What to put between the other arguments. ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char*). |
| [in] | ... | Other arguments to join, with colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated ColorResult.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #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.
| [in] | joiner | What 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. |
An allocated string.
You must free() the memory allocated by this function.
| #define colr_length | ( | x | ) |
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.
| [in] | x | A supported type to build a string from. |
| #define Colr_ljust | ( | x, | |
| width | |||
| ) |
Like Colr_ljust_char, it left-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| #define colr_ljust | ( | x, | |
| width | |||
| ) | colr_ljust_char(x, width, ' ') |
Like Colr_ljust it left-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #define colr_ljust_char | ( | x, | |
| width, | |||
| padchar | |||
| ) |
Like Colr_ljust_char it left-justifies ColrC objects and strings (char*), except it returns an allocated string (char*).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| [in] | padchar | Pad character to use. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #define colr_max | ( | a, | |
| b | |||
| ) | (a > b ? a : b) |
Macro for (a > b ? a : b).
| [in] | a | First value to compare. |
| [in] | b | Second value to compare. |
a if a > b, otherwise b. Referenced by ColorText_length().
| #define colr_print | ( | ... | ) |
Create a string from a colr_cat() call, print it to stdout (without a newline), and free it.
| [in] | ... | Arguments for colr_cat(). |
| #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.
| [in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
printf. | #define colr_printf_macro | ( | func, | |
| ... | |||
| ) |
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.
| [in] | func | The standard printf function to call, with a return type of int. |
| [in] | ... | Arguments for the printf function. |
func(...). | #define colr_puts | ( | ... | ) |
Create a string from a colr_cat() call, print it (with a newline), and free it.
| [in] | ... | Arguments for colr_cat(). |
| #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().
| [in] | s | The string to operate on. Must be |
| [in] | target | A 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 colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #define colr_replace_all | ( | s, | |
| target, | |||
| repl | |||
| ) |
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().
| [in] | s | The string to operate on. Must be |
| [in] | target | A 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 colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #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.
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().
| [in] | s | The string to operate on. Must be |
| [in] | target | A 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 colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
| [in] | flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #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.
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().
| [in] | s | The string to operate on. Must be |
| [in] | target | A 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 colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
| [in] | flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| #define colr_repr | ( | x | ) |
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:
| [in] | x | A value with one of the supported types to transform into a string. |
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().
| #define Colr_rjust | ( | x, | |
| width | |||
| ) |
Like Colr_rjust_char, it right-justifies ColrC objects and strings (char*), except it uses `' '` (space) as the pad character.
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| #define colr_rjust | ( | x, | |
| width | |||
| ) | colr_rjust_char(x, width, ' ') |
Like Colr_rjust it right-justifies ColrC objects and strings (char*) using `' '(space) as the pad character, except it returns an allocated string (char*`).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #define colr_rjust_char | ( | x, | |
| width, | |||
| padchar | |||
| ) |
Like Colr_rjust_char it right-justifies ColrC objects and strings (char*), except it returns an allocated string (char*).
This macro uses a _Generic() match to help with type safety.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*) to justify. |
| [in] | width | Maximum width for justification. |
| [in] | padchar | Pad character to use. |
An allocated string (char*) with the justification result.
You must free() the memory allocated by this function. maybenullalloc
| #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.
| [in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
snprintf. | #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.
| [in] | ... | Arguments for colr_free() will be called on any ColorArg, ColorResult, or ColorText pointer passed to this function. |
sprintf. | #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).
| [in] | s1 | The string to compare against the other two strings. |
| [in] | s2 | The first string to compare with. |
| [in] | s3 | The second string to compare with. |
1 if s1 is equal to s2 or s3, otherwise 0. | #define colr_str_eq | ( | s1, | |
| s2 | |||
| ) |
Convenience macro for !strcmp(s1, s2).
| [in] | s1 | The first string to compare. |
| [in] | s2 | The second string to compare. |
1 if s1 and s2 are equal, otherwise 0. Referenced by ColorResult_eq(), and RGB_from_str().
| #define colr_to_str | ( | x | ) |
Calls the <type>_to_str functions for the supported types.
If a string is given, it is duplicated like strdup().
| [in] | x | A supported type to build a string from. |
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.
| #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.
free() on it.| [in] | text | String to colorize/style. |
| [in] | ... | No more than 3 ColorArg pointers for fore, back, and style in any order. |
| #define ColrColorResult | ( | cres, | |
| ... | |||
| ) | ColorResult_Colr(cres, __VA_ARGS__, _ColrLastArg) |
Like Colr(), but it operates on a ColorResult to generate a new colorized ColorResult.
| [in] | cres | An 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. |
An allocated ColorResult.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #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.
| [in] | s | An allocated string. |
An allocated ColorResult.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define ext | ( | x | ) | ((ExtendedValue)x) |
Casts to ExtendedValue (unsigned char).
| [in] | x | Value to cast to unsigned char/ExtendedValue. |
Referenced by ExtendedValue_from_BasicValue(), and ExtendedValue_from_RGB().
| #define ext_hex | ( | s | ) | ext_hex_or(s, ext(0)) |
Like hex(), but force a conversion to the closest ExtendedValue (256-colors).
| [in] | s | A hex string to convert. |
| #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().
| [in] | s | A hex string to convert. |
| [in] | default_value | ExtendedValue to use if the hex string is not valid. |
default_value for bad hex strings.| #define EXT_INVALID COLOR_INVALID |
Alias for COLOR_INVALID.
All color values share an _INVALID member with the same value, so:
Referenced by ExtendedValue_from_BasicValue(), ExtendedValue_from_esc(), and ExtendedValue_from_str().
| #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.
Referenced by ExtendedValue_from_esc(), and ExtendedValue_from_str().
| #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.
This is short-hand for ExtendedValue_from_RGB((RGB){r, g, b}).
| [in] | r | The red value. |
| [in] | g | The green value. |
| [in] | b | The blue value. |
| #define ext_RGB | ( | rgbval | ) | ExtendedValue_from_RGB(rgbval) |
| #define fore | ( | x | ) | ColorArg_to_ptr(fore_arg(x)) |
Create a fore color suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() 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.
| [in] | x | A BasicValue, ExtendedValue, or RGB struct to use for the color value. |
A pointer to a heap-allocated ColorArg struct.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #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.
Uses _Generic (C11 standard) to dynamically create a ColorArg. This is used by the fore() macro.
| [in] | x | BasicValue, Extended (unsigned char), RGB struct, or string (color name) for fore color. |
.value.type set for the appropriate color type/value. For invalid values the .value.type may be set to TYPE_INVALID.| #define fore_str | ( | x | ) | ColorArg_to_esc(fore_arg(x)) |
| #define fore_str_static | ( | x | ) |
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().
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().
| [in] | x | A BasicValue, ExtendedValue, or RGB value. |
Use RGB_from_hex_default() to create an RGB value.
| [in] | s | A hex string to convert. |
rgb(0, 0, 0) for bad hex strings.| #define hex_or | ( | s, | |
| default_rgb | |||
| ) | RGB_from_hex_default(s, default_rgb) |
Use RGB_from_hex_default() to create an RGB value.
| [in] | s | A hex string to convert. |
| [in] | default_rgb | Default RGB value to use if the hex string is not valid. |
default_rgb for bad hex strings.| #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)
| [in] | ... | Arguments for asprintf. |
| #define rgb | ( | r, | |
| g, | |||
| b | |||
| ) | ((RGB){.red=r, .green=g, .blue=b}) |
Creates an anonymous RGB struct for use in function calls.
| [in] | r | unsigned char Red value. |
| [in] | g | unsigned char Blue value. |
| [in] | b | unsigned char Green value. |
Referenced by ExtendedValue_from_hex(), rainbow_step(), RGB_from_hex_default(), RGB_grayscale(), RGB_inverted(), and RGB_monochrome().
| #define style | ( | x | ) | ColorArg_to_ptr(style_arg(x)) |
Create a style suitable for use with the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
This macro accepts strings (style names) and StyleValues.
Style names (char*) can be passed to generate the appropriate style value.
| [in] | x | A StyleValue. |
A pointer to a heap-allocated ColorArg struct.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| #define style_arg | ( | x | ) |
Uses ColorArg_from_StyleValue to build a ColorArg with the appropriate color type/value.
| [in] | x | StyleValue for the style. |
.value.type set for the appropriate color type/value. For invalid values the .value.type may be set to TYPE_INVALID.| #define STYLE_LEN_MIN 5 |
Minimum length for the shortest style escape code, including `'\0'`.
Use STYLE_LEN for allocation.
| #define style_str | ( | x | ) | ColorArg_to_esc(style_arg(x)) |
| #define style_str_static | ( | x | ) |
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).
| [in] | x | A StyleValue to use. |
| #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.
| [in] | ap | The va_list to use. |
| [in] | vartype | Expected type of the argument. |
| [in] | x | The variable to assign to (usually arg). |
Referenced by _colr_join(), _colr_join_size(), ColorText_from_valuesv(), ColorText_set_values(), and colr_free_argsv().
A function type that knows how to fill a string with an rgb escape code.
| enum BasicValue |
Basic color values, with a few convenience values for extended colors.
| void _colr_free | ( | void * | p | ) |
Calls Colr *_free() functions for Colr objects, otherwise just calls free().
You should use the colr_free() macro instead.
| [in] | p | Pointer to a heap-allocated object. |
| bool _colr_is_last_arg | ( | void * | p | ) |
Determines if a void pointer is _ColrLastArg (the last-arg-marker).
| [in] | p | The pointer to check. |
true if the pointer is _ColrLastArg, otherwise false. | 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.
| [in] | joinerp | The joiner (any ColorArg, ColorResult, ColorText, or string). |
| [in] | ... | Zero or more ColorArgs, ColorResults, ColorTexts, or strings to join by the joiner. |
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.
| size_t _colr_join_array_length | ( | void * | ps | ) |
Determine the length of a NULL-terminated array of strings (char*), ColorArgs, ColorResults, or ColorTexts.
| [in] | ps | A NULL-terminated array of ColorArgs, ColorResults, ColorTexts, or strings (char*). |
NULL) in the array. Referenced by colr_join_array().
| 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.
| [in] | joinerp | The joiner (any ColorArg, ColorResult, ColorText, or string). |
| [in] | ps | An 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] | count | Total number of items in the array. |
0.Referenced by colr_join_arrayn().
| 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.
| [in] | joinerp | The joiner (any ColorArg, ColorText, or string (char*)). |
| [in] | args | A va_list with zero or more ColorArgs, ColorTexts, or strings (char*) to join. |
0 if joinerp is NULL/empty). Except for 0, it will never return anything less than CODE_RESET_LEN. Referenced by _colr_join().
| 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.
| [in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string (char*). |
strlen() + 1 for strings). Referenced by _colr_join_arrayn_size(), and _colr_join_size().
| 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.
| [in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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.
| [in] | p | A ColorArg pointer, ColorResult pointer, ColorText pointer, or string. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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.
| [in] | fmter | A formatter function (RGB_fmter) that can create escape codes from RGB values. |
| [in] | s | The string to "rainbowize". Input must be |
| [in] | freq | The "tightness" for colors. |
| [in] | offset | The starting offset into the rainbow. |
| [in] | spread | Number of characters per color. |
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().
Compares two ArgTypes.
This is used to implement colr_eq().
| [in] | a | The first ArgType to compare. |
| [in] | b | The second ArgType to compare. |
true if they are equal, otherwise false. | char* ArgType_repr | ( | ArgType | type | ) |
Creates a string (char*) representation of a ArgType.
| [in] | type | An ArgType to get the type from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorArg_repr().
| char* ArgType_to_str | ( | ArgType | type | ) |
Creates a human-friendly string (char*) from an ArgType.
| [in] | type | An ArgType to get the type from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorArg_example().
| bool BasicValue_eq | ( | BasicValue | a, |
| BasicValue | b | ||
| ) |
Compares two BasicValues.
This is used to implement colr_eq().
| [in] | a | The first BasicValue to compare. |
| [in] | b | The second BasicValue to compare. |
true if they are equal, otherwise false.| BasicValue BasicValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*) to an actual BasicValue enum value.
| [in] | s | Escape-code string. Must be |
| BasicValue | value on success. |
| BASIC_INVALID | on error (or if s is NULL). |
| BASIC_INVALID_RANGE | if the code number was outside of the range 0-255. |
| BasicValue BasicValue_from_str | ( | const char * | arg | ) |
Convert named argument to an actual BasicValue enum value.
| [in] | arg | Color name to find the BasicValue for. |
| bool BasicValue_is_invalid | ( | BasicValue | bval | ) |
Determines whether a BasicValue is invalid.
| [in] | bval | A BasicValue to check. |
true if the value is considered invalid, otherwise false.Referenced by ExtendedValue_from_BasicValue().
| bool BasicValue_is_valid | ( | BasicValue | bval | ) |
Determines whether a BasicValue is valid.
| [in] | bval | A BasicValue to check. |
true if the value is considered valid, otherwise false.| char* BasicValue_repr | ( | BasicValue | bval | ) |
Creates a string (char*) representation of a BasicValue.
| [in] | bval | A BasicValue to get the value from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| int BasicValue_to_ansi | ( | ArgType | type, |
| BasicValue | bval | ||
| ) |
Converts a fore/back BasicValue to the actual ansi code number.
| [in] | type | ArgType (FORE/BACK). |
| [in] | bval | BasicValue to convert. |
Referenced by format_bg(), and format_fg().
| char* BasicValue_to_str | ( | BasicValue | bval | ) |
Create a human-friendly string (char*) representation for a BasicValue.
| [in] | bval | BasicValue to get the name for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| ColorArg ColorArg_empty | ( | void | ) |
Create a ColorArg with ARGTYPE_NONE and ColorValue.type.TYPE_NONE.
This is used to pass "empty" fore/back/style args to the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, where NULL may have a different meaning for users of the ColorArg.
(ColorArg){.type=ARGTYPE_NONE, .value.type=TYPE_NONE}Compares two ColorArg structs.
They are considered "equal" if their .type and .value match.
true if they are equal, otherwise false.Referenced by ColorText_has_arg().
| 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.
| [in] | carg | A ColorArg to get an example string for. |
| [in] | colorized | Whether to include a colorized example. If set to false, there will be no escape-codes in the string. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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).
| [in] | p | ColorArg to free. |
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 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.
| [in] | type | ArgType (FORE, BACK, STYLE). |
| [in] | value | BasicValue to use. |
.value.type member possibly set to TYPE_INVALID.| 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.
| [in] | s | The escape code to parse. It must not have extra characters. |
Referenced by ColorArgs_from_str().
| 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.
| [in] | type | ArgType (FORE, BACK, STYLE). |
| [in] | value | ExtendedValue to use. |
.value.type member possibly set to TYPE_INVALID.Explicit version of ColorArg_from_value that only handles RGB structs.
This is used in some macros to aid in dynamic escape code creation.
| [in] | type | ArgType (FORE, BACK, STYLE). |
| [in] | value | RGB struct to use. |
.value.type member possibly set to TYPE_INVALID.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).
| [in] | type | ArgType (FORE, BACK, STYLE). |
| [in] | colorname | A known color name/style. |
| 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.
| [in] | type | ArgType (FORE, BACK, STYLE). |
| [in] | value | StyleValue to use. |
.value.type member possibly set to TYPE_INVALID.Used with the color_arg macro to dynamically create a ColorArg based on it's argument type.
| [in] | type | ArgType value, to mark the type of ColorArg. |
| [in] | colrtype | ColorType value, to mark the type of ColorValue. |
| [in] | p | A pointer to either a BasicValue, ExtendedValue, or a RGB. |
.value.type member set for the value that was passed. For invalid types the .value.type member may be set to one of:| 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.
| [in] | carg | A ColorArg to check. |
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().
| bool ColorArg_is_invalid | ( | ColorArg | carg | ) |
| 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.
| [in] | p | A void pointer to check. |
true if the pointer is a ColorArg, otherwise false.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().
| bool ColorArg_is_valid | ( | ColorArg | carg | ) |
| size_t ColorArg_length | ( | ColorArg | carg | ) |
Returns the length in bytes needed to allocate a string (char*) built with ColorArg_to_esc().
| [in] | carg | ColorArg to use. |
size_t) needed to allocate a ColorArg's string, or 1 (size of an empty string) for invalid/empty arg types/values.Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_length().
| char* ColorArg_repr | ( | ColorArg | carg | ) |
Creates a string (char*) representation for a ColorArg.
Allocates memory for the string representation.
| [in] | carg | ColorArg struct to get the representation for. |
Allocated string for the representation.
You must free() the memory allocated by this function.
Referenced by _colr_ptr_repr(), and ColorText_repr().
| 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.
| [in] | carg | ColorArg to get the ArgType and ColorValue from. |
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.
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().
| 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'`.
| [in] | dest | Destination for the escape code string. Must have room for the code type being used. See ColorArg_length() for determining the size needed. |
| [in] | carg | ColorArg to get the ArgType and ColorValue from. |
true if the ColorArg was valid, otherwise false.Referenced by colr_str_has_ColorArg().
Copies a ColorArg into memory and returns the pointer.
You must free() the memory if you call this directly.
| [in] | carg | ColorArg to copy/allocate for. |
Pointer to a heap-allocated ColorArg.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorArgs_from_str().
| 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.
| [in] | ps | A pointer to an array of ColorArgs, where NULL is the last item. |
| char* ColorArgs_array_repr | ( | ColorArg ** | lst | ) |
Creates a string representation for an array of ColorArg pointers.
| [in] | lst | The ColorArg array to create the representation for (ColorArg**). |
NULL if lst is NULL, or the allocation fails.| 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.
| [in] | s | A string to get the escape-codes from. Must be |
| [in] | unique | Whether to only include unique ColorArgs. |
An allocated array of ColorArg pointers, where the last element is NULL.
You must free() the memory allocated by this function.
| If | s is NULL, or empty, or there are otherwise no escape-codes found in the string, then NULL is returned. |
| On | success, there will be at least two pointers behind the return value. The last pointer is always NULL. |
| ColorJustify ColorJustify_empty | ( | void | ) |
Creates an "empty" ColorJustify, with JUST_NONE set.
Referenced by ColorText_empty().
| bool ColorJustify_eq | ( | ColorJustify | a, |
| ColorJustify | b | ||
| ) |
Compares two ColorJustify structs.
They are considered "equal" if their member values match.
| [in] | a | First ColorJustify to compare. |
| [in] | b | Second ColorJustify to compare. |
true if they are equal, otherwise false.| 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.
| [in] | cjust | The ColorJustify to check. |
true if the ColorJustify is empty, otherwise false.Referenced by ColorText_is_empty(), and ColorText_length().
| 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.
| [in] | method | ColorJustifyMethod to use. |
| [in] | width | Width for justification. If 0 is given, ColorText will use the width from colr_term_size(). |
| [in] | padchar | Padding character to use. If 0 is given, the default, space (`' '`), is used. |
Referenced by ColorText_set_center(), ColorText_set_ljust(), and ColorText_set_rjust().
| char* ColorJustify_repr | ( | ColorJustify | cjust | ) |
Creates a string (char*) representation for a ColorJustify.
Allocates memory for the string representation.
| [in] | cjust | ColorJustify struct to get the representation for. |
Allocated string for the representation.
You must free() the memory allocated by this function.
Referenced by ColorText_repr().
| char* ColorJustifyMethod_repr | ( | ColorJustifyMethod | meth | ) |
Creates a string (char*) representation for a ColorJustifyMethod.
Allocates memory for the string representation.
| [in] | meth | ColorJustifyMethod to get the representation for. |
Allocated string for the representation.
You must free() the memory allocated by this function.
Referenced by ColorJustify_repr().
| ColorResult* ColorResult_center | ( | ColorResult * | cres, |
| int | width, | ||
| char | padchar | ||
| ) |
Centers a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
| [in] | cres | A ColorResult pointer to center. It will be free'd after this. |
| [in] | width | Maximum width in characters, or 0 for current terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
Referenced by Colr_center_char().
| 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.
| [in] | cres | An allocated ColorResult to colorize. This will be released to create the new ColorResult. |
| [in] | ... | One or more fore(), back(), or style() arguments (ColorArgs). The last argument must be _ColrLastArg. The allocated ColorArgs will be free()'d. |
An allocated ColorResult, or NULL if cres is NULL.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| ColorResult ColorResult_empty | ( | void | ) |
Creates a ColorResult with .result=NULL and .length=-1, with the appropriate struct marker.
Referenced by ColorResult_from_stra(), and ColorResult_new().
| 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.
| [in] | a | First ColorResult to compare. |
| [in] | b | Second ColorResult to compare. |
true if they are equal, otherwise false.| void ColorResult_free | ( | ColorResult * | p | ) |
Free allocated memory for a ColorResult and it's .result member.
| [in] | p | A ColorResult with a NULL or heap-allocated .result member. |
Referenced by _colr_free(), _colr_join(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rip_str(), ColorResult_rjust(), colr_printf_handler(), colr_str_replace_all_ColorResult(), colr_str_replace_ColorResult(), colr_str_replace_re_all_ColorResult(), colr_str_replace_re_ColorResult(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_ColorResult().
| ColorResult ColorResult_from_str | ( | const char * | s | ) |
Allocates a copy of a string, and creates a ColorResult from it.
| [in] | s | The string to copy. |
s is NULL. | ColorResult* ColorResult_from_stra | ( | const char * | s | ) |
Allocates a copy of a string, and creates an allocated ColorResult from it.
| [in] | s | The string to copy. |
An allocated ColorResult. The ColorResult may be "empty" if s is NULL.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
Referenced by Colr_cursor_hide(), Colr_cursor_show(), Colr_erase_display(), Colr_erase_line(), Colr_move_return(), Colr_pos_restore(), and Colr_pos_save().
| bool ColorResult_is_empty | ( | ColorResult | cres | ) |
Checks to see if a ColorResult is "empty" (NULL or empty string).
| [in] | cres | ColorResult to check. |
true if the ColorResult is "empty", otherwise false. Referenced by ColorResult_center(), ColorResult_ljust(), and ColorResult_rjust().
| 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.
| [in] | p | A void pointer to check. |
true if the pointer is a ColorResult, otherwise false.Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().
| 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).
| [in] | cres | A ColorResult to calculate the length for. |
0 if .result is NULL.Referenced by _colr_join_arrayn_size(), and _colr_ptr_length().
| ColorResult* ColorResult_ljust | ( | ColorResult * | cres, |
| int | width, | ||
| char | padchar | ||
| ) |
Left-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
| [in] | cres | A ColorResult pointer to center. It will be free'd after this. |
| [in] | width | Maximum width in characters, or 0 for current terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
Referenced by Colr_ljust_char().
| ColorResult ColorResult_new | ( | char * | s | ) |
Initialize a new ColorResult with an allocated string (char*).
| [in] | s | An allocated string to use for the .result member. |
s is NULL Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_str(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().
| 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.
| [in] | cres | A ColorResult to create the representation string for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by _colr_ptr_repr().
| char* ColorResult_rip_str | ( | ColorResult * | cres | ) |
Returns the string from a ColorResult pointer, but frees the ColorResult itself (without destroying the string (char*)).
| [in] | cres | ColorResult to get the string from and free(). |
The string (char*) from the result member.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| ColorResult* ColorResult_rjust | ( | ColorResult * | cres, |
| int | width, | ||
| char | padchar | ||
| ) |
Right-justifies a ColorResult's string result and returns an allocated ColorResult (may be the same ColorResult if it is "empty").
| [in] | cres | A ColorResult pointer to center. It will be free'd after this. |
| [in] | width | Maximum width in characters, or 0 for current terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult, or NULL if cres is NULL. If cres is empty, it is simply returned.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
Referenced by Colr_rjust_char().
| 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.
| [in] | cres | A ColorResult to use. |
An allocated ColorResult.
You must free() the memory allocated by this function.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
If allocation fails, NULL is returned.
Referenced by ColorResult_center(), ColorResult_Colr(), ColorResult_from_stra(), ColorResult_ljust(), ColorResult_rjust(), Colr_center_char(), Colr_fmt_str(), Colr_ljust_char(), Colr_move_back(), Colr_move_column(), Colr_move_down(), Colr_move_forward(), Colr_move_next(), Colr_move_pos(), Colr_move_prev(), Colr_move_up(), Colr_rjust_char(), Colr_scroll_down(), and Colr_scroll_up().
| 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.
| [in] | cres | A ColorResult to use. |
.result member. If you free the result of this function, the original string used to create the ColorResult will be lost. Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_center(), ColorResult_Colr(), ColorResult_ljust(), ColorResult_rjust(), colr_join_arrayn(), colr_printf_handler(), colr_str_replace_all_ColorResult(), colr_str_replace_ColorResult(), colr_str_replace_re_all_ColorResult(), colr_str_replace_re_ColorResult(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_ColorResult().
| ColorText ColorText_empty | ( | void | ) |
Creates an "empty" ColorText with pointers set to NULL.
Referenced by ColorText_from_valuesv(), and ColorText_set_values().
| void ColorText_free | ( | ColorText * | p | ) |
Frees a ColorText and it's ColorArgs.
The text member is left alone, because it wasn't created by ColrC.
| [in] | p | Pointer to ColorText to free, along with it's Colr-based members. |
Referenced by _colr_free(), _colr_join(), Colr_center_char(), Colr_ljust_char(), colr_printf_handler(), Colr_rjust_char(), colr_str_replace_all_ColorText(), colr_str_replace_ColorText(), colr_str_replace_re_all_ColorText(), colr_str_replace_re_ColorText(), colr_str_replace_re_match_ColorText(), colr_str_replace_re_matches_ColorText(), colr_str_replace_re_pat_all_ColorText(), and colr_str_replace_re_pat_ColorText().
| 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.
| [in] | p | Pointer to a ColorText. |
Referenced by ColorResult_Colr(), and ColorText_free().
| ColorText ColorText_from_values | ( | char * | text, |
| ... | |||
| ) |
Builds a ColorText from 1 mandatory string (char*), and optional fore, back, and style args (pointers to ColorArgs).
| [in] | text | Text to colorize (a regular string). |
| [in] | ... | ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you. |
| 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).
| [in] | text | Text to colorize (a regular string). |
| [in] | args | va_list with ColorArgs for fore, back, and style, in any order. The last argument must be _ColrLastArg. The Colr() macro takes care of this for you, and should be used for basic text colorization. |
Referenced by ColorResult_Colr(), and ColorText_from_values().
Checks to see if a ColorText has a certain ColorArg value set.
Uses ColorArg_eq() to inspect the fore, back, and style members.
true if the fore, back, or style arg matches carg, otherwise false.| bool ColorText_has_args | ( | ColorText | ctext | ) |
| 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.
| [in] | ctext | The ColorText to check. |
true if the ColorText is empty, otherwise false.| 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.
| [in] | p | A void pointer to check. |
true if the pointer is a ColorText, otherwise false.Referenced by _colr_free(), _colr_join(), _colr_join_array_length(), _colr_join_arrayn_size(), _colr_ptr_length(), _colr_ptr_repr(), _colr_ptr_to_str(), Colr_center_char(), colr_is_colr_ptr(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), and Colr_rjust_char().
| 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.
| [in] | ctext | ColorText to use. |
size_t) needed to allocate a ColorText's string, or 1 (size of an empty string) for invalid/empty arg types/values.Referenced by _colr_join_arrayn_size(), _colr_ptr_length(), and ColorText_to_str().
| char* ColorText_repr | ( | ColorText | ctext | ) |
Allocate a string (char*) representation for a ColorText.
| [in] | ctext | ColorText to get the string representation for. |
Referenced by _colr_ptr_repr().
Modify a ColorText to include a ColorJustify member to center-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_center and friends.
| [out] | ctext | The ColorText to set the justification method for. |
| [in] | width | Maximum width for the justification. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext. Referenced by Colr_center_char().
| 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.
| [out] | ctext | The ColorText to set the justification method for. |
| [in] | cjust | The ColorJustify struct to use. |
ctext.Modify a ColorText to include a ColorJustify member to left-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_ljust and friends.
| [out] | ctext | The ColorText to set the justification method for. |
| [in] | width | Maximum width for the justification. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext. Referenced by Colr_ljust_char().
Modify a ColorText to include a ColorJustify member to right-justify text when it is converted into a string.
This is to facilitate the justification macros. You can create a justified ColorText using ColorText_rjust and friends.
| [out] | ctext | The ColorText to set the justification method for. |
| [in] | width | Maximum width for the justification. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
ctext. Referenced by Colr_rjust_char().
| 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).
| [out] | ctext | A ColorText to initialize with values. |
| [in] | text | Text to colorize (a regular string). |
| [in] | ... | A va_list with ColorArgs pointers for fore, back, and style, in any order. |
Copies a ColorText into allocated memory and returns the pointer.
You must free() the memory if you call this directly.
| [in] | ctext | ColorText to copy/allocate for. |
Pointer to a heap-allocated ColorText.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| char* ColorText_to_str | ( | ColorText | ctext | ) |
Stringifies a ColorText struct, creating a mix of escape codes and text.
| [in] | ctext | ColorText to stringify. |
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.
Referenced by _colr_join(), _colr_ptr_to_str(), ColorResult_Colr(), Colr_center_char(), colr_join_arrayn(), Colr_ljust_char(), colr_printf_handler(), Colr_rjust_char(), colr_str_replace_all_ColorText(), colr_str_replace_ColorText(), colr_str_replace_re_all_ColorText(), colr_str_replace_re_ColorText(), colr_str_replace_re_match_ColorText(), colr_str_replace_re_matches_ColorText(), colr_str_replace_re_pat_all_ColorText(), and colr_str_replace_re_pat_ColorText().
| ColorType ColorType_from_str | ( | const char * | arg | ) |
Determine which type of color value is desired by name.
Example:
| [in] | arg | Color name to get the ColorType for. |
| ColorType | value on success. |
| TYPE_INVALID | for invalid color names/strings. |
| TYPE_INVALID_EXT_RANGE | for ExtendedValues outside of 0-255. |
| TYPE_INVALID_RGB_RANGE | for rgb values outside of 0-255. |
| bool ColorType_is_invalid | ( | ColorType | type | ) |
Check to see if a ColorType value is considered invalid.
| [in] | type | ColorType value to check. |
true if the value is considered invalid, otherwise false.| bool ColorType_is_valid | ( | ColorType | type | ) |
Check to see if a ColorType value is considered valid.
| [in] | type | ColorType value to check. |
true if the value is considered valid, otherwise false.| char* ColorType_repr | ( | ColorType | type | ) |
Creates a string (char*) representation of a ColorType.
| [in] | type | A ColorType to get the type from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* ColorType_to_str | ( | ColorType | type | ) |
Create a human-friendly string (char*) representation for a ColorType.
| [in] | type | A ColorType to get the name for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorValue_example().
| ColorValue ColorValue_empty | ( | void | ) |
Create an "empty" ColorValue.
This is used with ColorArg_empty() to build ColorArgs that don't do anything, where using NULL has a different meaning inside the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros.
(ColorValue){.type=TYPE_NONE, .basic=0, .ext=0, .rgb=(RGB){0, 0, 0}}| bool ColorValue_eq | ( | ColorValue | a, |
| ColorValue | b | ||
| ) |
Compares two ColorValue structs.
They are considered "equal" if all of their members match.
| [in] | a | First ColorValue to compare. |
| [in] | b | Second ColorValue to compare. |
true if they are equal, otherwise false.Referenced by ColorArg_eq().
| char* ColorValue_example | ( | ColorValue | cval | ) |
Create a string (char*) representation of a ColorValue with a human-friendly type/name.
| [in] | cval | A ColorValue to get an example string for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorArg_example().
| ColorValue ColorValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*) into a ColorValue.
| [in] | s | An escape-code string to parse. Must be |
| For | invalid strings, the .type member can be one of:
|
Referenced by ColorArg_from_esc().
| ColorValue ColorValue_from_str | ( | const char * | s | ) |
Create a ColorValue from a known color name, or RGB string (char*).
| [in] | s | A string to parse the color name from (can be an RGB string). |
| For | invalid strings, the .type member can be one of:
|
Referenced by ColorArg_from_str().
| 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.
| [in] | type | A ColorType value, to mark the type of ColorValue. |
| [in] | p | A pointer to either a BasicValue, ExtendedValue, or a RGB. |
.type member set for the value that was passed. For invalid types the .type member may be set to one of:Referenced by ColorArg_from_BasicValue(), ColorArg_from_ExtendedValue(), ColorArg_from_RGB(), ColorArg_from_StyleValue(), ColorValue_from_esc(), and ColorValue_from_str().
| bool ColorValue_has_BasicValue | ( | ColorValue | cval, |
| BasicValue | bval | ||
| ) |
Checks to see if a ColorValue has a BasicValue set.
| [in] | cval | ColorValue to check. |
| [in] | bval | BasicValue to look for. |
true if the ColorValue has the exact BasicValue set.| bool ColorValue_has_ExtendedValue | ( | ColorValue | cval, |
| ExtendedValue | eval | ||
| ) |
Checks to see if a ColorValue has a ExtendedValue set.
| [in] | cval | ColorValue to check. |
| [in] | eval | ExtendedValue to look for. |
true if the ColorValue has the exact ExtendedValue set.| bool ColorValue_has_RGB | ( | ColorValue | cval, |
| RGB | rgb | ||
| ) |
Checks to see if a ColorValue has a RGB value set.
| [in] | cval | ColorValue to check. |
| [in] | rgb | RGB value to look for. |
true if the ColorValue has the exact RGB value set.| bool ColorValue_has_StyleValue | ( | ColorValue | cval, |
| StyleValue | sval | ||
| ) |
Checks to see if a ColorValue has a StyleValue set.
| [in] | cval | ColorValue to check. |
| [in] | sval | StyleValue to look for. |
true if the ColorValue has the exact StyleValue set.| bool ColorValue_is_empty | ( | ColorValue | cval | ) |
Checks to see if a ColorValue is an empty placeholder.
| [in] | cval | ColorValue to check. |
true if the ColorValue is "empty", otherwise false.| bool ColorValue_is_invalid | ( | ColorValue | cval | ) |
Checks to see if a ColorValue holds an invalid value.
| [in] | cval | ColorValue struct to check. |
true if the value is invalid, otherwise false.Referenced by ColorArg_from_esc().
| bool ColorValue_is_valid | ( | ColorValue | cval | ) |
Checks to see if a ColorValue holds a valid value.
| [in] | cval | ColorValue struct to check. |
true if the value is valid, otherwise false.| 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.
| [in] | type | ArgType (FORE, BACK, STYLE) |
| [in] | cval | ColorValue to use. |
size_t) needed to allocate a ColorValue's string, or 1 (size of an empty string) for invalid/empty arg types/values.Referenced by ColorArg_length().
| char* ColorValue_repr | ( | ColorValue | cval | ) |
Creates a string (char*) representation of a ColorValue.
| [in] | cval | A ColorValue to get the type and value from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorArg_repr().
| char* ColorValue_to_esc | ( | ArgType | type, |
| ColorValue | cval | ||
| ) |
Converts a ColorValue into an escape code string (char*).
| [in] | type | ArgType (FORE, BACK, STYLE) to build the escape code for. |
| [in] | cval | ColorValue to get the color value from. |
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.
Referenced by ColorArg_to_esc().
| 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'`.
| [out] | dest | Destination string for the escape code string. Must have room for the code type being used. |
| [in] | type | ArgType (FORE, BACK, STYLE) to build the escape code for. |
| [in] | cval | ColorValue to get the color value from. |
true if a proper ArgType/ColorValue combination was used, otherwise false.Referenced by ColorArg_to_esc_s().
| regmatch_t* colr_alloc_regmatch | ( | regmatch_t | match | ) |
Allocates space for a regmatch_t, initializes it, and returns a pointer to it.
| [in] | match | A regmatch_t to allocate for and copy. |
regmatch_t. Referenced by colr_re_matches().
| void colr_append_reset | ( | char * | s | ) |
Appends CODE_RESET_ALL to a string (char*), but makes sure to do it before any newlines.
| [in] | s | The string to append to. Must have extra room for CODE_RESET_ALL. Must be |
Referenced by _colr_join(), _rainbow(), ColorText_to_str(), and colr_join_arrayn().
| ColorResult* Colr_center_char | ( | void * | x, |
| int | width, | ||
| char | padchar | ||
| ) |
Returns a center-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*). |
| [in] | width | Maximum width for the justified text, or 0 to use the terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult with the justified text as the result member.
You must free() the memory allocated by this function.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
If allocation fails, NULL is returned.
| 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 |
| [in] | c | The character to check. |
Referenced by colr_str_repr().
| bool colr_char_in_str | ( | const char * | s, |
| const char | c | ||
| ) |
Determines if a character exists in the given string (char*).
| [in] | c | Character to search for. |
| [in] | s | String to check. Input must be |
true if c is found in s, otherwise false. Referenced by colr_str_chars_lcount(), and colr_str_lstrip_chars().
| 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
| [in] | c | Character to test. |
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().
| char* colr_char_repr | ( | char | c | ) |
Creates a string (char*) representation for a char.
| [in] | c | Value to create the representation for. |
An allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorJustify_repr().
| 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 |
| [in] | c | The character to check. |
true if the character needs an escape sequence, otherwise false. Referenced by colr_str_repr().
| 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.
| [in] | marker | A colr marker, like COLORARG_MARKER, COLORTEXT_MARKER, etc. |
| [in] | p | A pointer to check, to see if it starts with the marker. |
true if all bytes match the marker, otherwise false.Referenced by _colr_is_last_arg(), ColorArg_is_ptr(), ColorResult_is_ptr(), and ColorText_is_ptr().
| 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.
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().
| 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.
| [in] | fmt | Format string for asprintf. |
| [in] | ... | Other arguments for asprintf. |
An allocated ColorResult, or NULL if fmt is NULL.
If allocation fails, NULL is returned.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
| void colr_free_argsv | ( | va_list | args | ) |
Free any ColrC objects (ColorArg, ColorResult, or ColorText pointer) passed in through a va_list.
| [in] | args | The va_list with ColrC objects (ColorArg, ColorResult, or ColorText pointer). The last argument must be _ColrLastArg. |
Referenced by ColorResult_Colr().
| void colr_free_re_matches | ( | regmatch_t ** | matches | ) |
Free an array of allocated regmatch_t, like the return from colr_re_matches().
| [out] | matches | A pointer to an array of regmatch_t pointers. |
Referenced by colr_str_replace_re_pat_all().
| bool colr_is_colr_ptr | ( | void * | p | ) |
Determines whether a void pointer is a ColorArg, ColorResult, or ColorText pointer.
| [in] | p | A pointer to a possible ColrC object. |
true if p is a ColorArg, ColorResult, or ColorText pointer, otherwise false. Referenced by colr_free_argsv().
| char* colr_join_array | ( | void * | joinerp, |
| void * | ps | ||
| ) |
Join an array of strings (char*), ColorArgs, or ColorTexts by another string (char*), ColorArg, or ColorText.
| [in] | joinerp | The joiner (any ColorArg, ColorText, or string (char*)). |
| [in] | ps | An array of pointers to ColorArgs, ColorTexts, or strings (char*). The array must have NULL as the last item. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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.
| [in] | joinerp | The joiner (any ColorArg, ColorText, or string (char*)). |
| [in] | ps | An 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] | count | The total number of items in the array. |
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.
Referenced by colr_join_array().
| ColorResult* Colr_ljust_char | ( | void * | x, |
| int | width, | ||
| char | padchar | ||
| ) |
Returns a left-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*). |
| [in] | width | Maximum width for the justified text, or 0 to use the terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult with the justified text as the result member.
You must free() the memory allocated by this function.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
If allocation fails, NULL is returned.
| 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.
| [in] | s | The string to check. |
| [in] | length | Number of multibyte characters to get the length for. |
s to get at least length multibyte characters. | 0 | if s is NULL/empty, or length is 0. |
| (size_t)-1 | if an invalid multibyte sequence is found at the start of s. |
Referenced by _rainbow().
| 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.
| [in] | fp | FILE pointer for output. |
| [in] | info | Info from printf about how to format the argument. |
| [in] | args | Argument list (with only 1 argument), containing a ColorArg, ColorResult, ColorText, or string (char*) to format. |
Referenced by colr_printf_register().
| 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.
| [in] | info | Info from printf about how to format the argument. |
| [in] | n | Number of arguments for the format char. |
| [out] | argtypes | Type of arguments being handled, from an enum defined in printf. Colr uses/sets one argument, a PA_POINTER type. |
| [out] | sz | Size of the arguments. Not used in Colr. |
argtypes. Referenced by 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.
| regmatch_t** colr_re_matches | ( | const char * | s, |
| regex_t * | repattern | ||
| ) |
Returns all regmatch_t matches for regex pattern in a string (char*).
| [in] | s | The string to search. |
| [in] | repattern | The pattern to look for. |
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.
Referenced by colr_str_replace_re_pat_all().
| ColorResult* Colr_rjust_char | ( | void * | x, |
| int | width, | ||
| char | padchar | ||
| ) |
Returns a right-justified (allocated) ColorResult when given a ColorText, ColorResult, or string (char*), along with the desired width and pad character.
| [in] | x | ColorText pointer, ColorResult pointer, or string (char*). |
| [in] | width | Maximum width for the justified text, or 0 to use the terminal width. |
| [in] | padchar | Character to pad with, or 0 for `' '` (space). |
An allocated ColorResult with the justified text as the result member.
You must free() the memory allocated by this function.
If used inside of the Colr(), colr_cat(), colr_join(), Colr_cat(), Colr_join(), Colr_center(), Colr_ljust(), and Colr_rjust() macros, or their backing functions, they will free() the result. Otherwise, you are responsible for calling free().
If allocation fails, NULL is returned.
| 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.
true if the locale had to be set, false if it was already set. Referenced by colr_mb_len(), and colr_str_mb_len().
| 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).
| [in] | lst | The string array to look in. |
| [in] | s | The string to look for. |
true if the string is found, otherwise false. | <tt>false</tt> | if lst is NULL or s is NULL. |
Referenced by colr_str_get_codes().
| 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.
| [in] | ps | A pointer to an array of strings. |
Referenced by ColorArgs_from_str().
| char* colr_str_center | ( | const char * | s, |
| int | width, | ||
| const char | padchar | ||
| ) |
Center-justifies a string (char*), ignoring escape codes when measuring the width.
| [in] | s | The string to justify. Input must be |
| [in] | width | The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size(). |
| [in] | padchar | The character to pad with. If '0', then `' '` is used. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorResult_center(), Colr_center_char(), and colr_printf_handler().
| 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'`.
| [in] | s | The string to examine. Must be |
| [in] | c | The character to count. Must not be |
c occurs in s.Referenced by _rainbow().
| 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.
| [in] | s | The string to examine. Must be |
| [in] | c | The character to count. Must not be |
c occurs at the start of s.Referenced by colr_str_lstrip_char().
| 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.
| [in] | s | The string to examine. Must be |
| [in] | chars | The characters to count, in any order. Must not be |
chars occurs at the start of s.Referenced by colr_str_lstrip_chars().
| size_t colr_str_code_count | ( | const char * | s | ) |
Return the number of escape-codes in a string (char*).
| [in] | s | A string to count the escape-codes for. Must be |
0 if s is NULL, or doesn't contain any escape-codes.Referenced by colr_str_get_codes().
| 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*).
| [in] | s | A string to count the code-chars for. Must be |
0 if s is NULL, or doesn't contain any escape-codes.| 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.
| [in] | dest | Memory allocated for new string. Must have room for strlen(src) + 1 or length + 1. |
| [in] | src | Source string to copy. |
| [in] | length | Maximum characters to copy. This does not include the null-terminator. Usually set to strlen(dest). |
Referenced by ColorResult_from_stra().
| 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.
| [in] | s | String to check. Must be |
| [in] | suffix | Suffix to check for. Must be |
str ends with suffix. Referenced by colr_append_reset().
| char** colr_str_get_codes | ( | const char * | s, |
| bool | unique | ||
| ) |
Get an array of escape-codes from a string (char*).
This function copies the escape-code strings, and the pointers to the heap, if any escape-codes are found in the string.
colr_str_array_free() can be used to easily free() the result of this function.
| [in] | s | A string to get the escape-codes from. Must be |
| [in] | unique | Whether to only include unique escape codes. |
An allocated array of string (char*) pointers, where the last element is NULL.
You must free() the memory allocated by this function.
| If | s is NULL, or empty, or there are otherwise no escape-codes found in the string, or allocation fails for the strings/array, then NULL is returned. |
| On | success, there will be at least two pointers behind the return value. The last pointer is always NULL. |
Referenced by ColorArgs_from_str().
| bool colr_str_has_codes | ( | const char * | s | ) |
Determines if a string (char*) has ANSI escape codes in it.
This will detect any ansi escape code, not just colors.
| [in] | s | The string to check. Can be Input must be |
true if the string has at least one escape code, otherwise false.| bool colr_str_has_ColorArg | ( | const char * | s, |
| ColorArg * | carg | ||
| ) |
Determines whether a string contains a specific color code.
true if the string contains the escape codes formed by the ColorArg* given, otherwise false. If s is NULL/empty, or carg is NULL/empty, this will return false. | ColrHash colr_str_hash | ( | const char * | s | ) |
Hash a string using djb2.
This is only used for simple, short, string (char*) hashing. It is not designed for cryptography.
There are some notes about collision rates for this function here.
| [in] | s | The string to hash. Must be |
unsigned long) value with the hash. | 0 | if s is NULL. |
| COLR_HASH_SEED | if s is an empty string. |
Referenced by colr_str_array_contains().
| bool colr_str_is_all | ( | const char * | s, |
| const char | c | ||
| ) |
Determines whether a string (char*) consists of only one character, possibly repeated.
| [in] | s | String to check. |
| [in] | c | Character to test for. Must not be 0. |
true if s contains only the character c, otherwise false. | bool colr_str_is_codes | ( | const char * | s | ) |
Determines if a string (char*) is composed entirely of escape codes.
Returns false if the string is NULL, or empty.
| [in] | s | The string to check. Input must be |
true if the string is escape-codes only, otherwise false.| bool colr_str_is_digits | ( | const char * | s | ) |
Determines whether all characters in a string (char*) are digits.
If s is NULL or an empty string (""), false is returned.
| [in] | s | String to check. Input must be |
true if all characters are digits (0-9), otherwise false. Referenced by ExtendedValue_from_str().
| bool colr_str_is_empty | ( | const char * | s | ) |
Checks to see if a string empty.
This for compatibility with the colr_is_empty() macro.
| [in] | s | The string to check. |
true if s is an "empty" string or NULL, otherwise false. | char* colr_str_ljust | ( | const char * | s, |
| int | width, | ||
| const char | padchar | ||
| ) |
Left-justifies a string (char*), ignoring escape codes when measuring the width.
| [in] | s | The string to justify. Input must be |
| [in] | width | The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size(). |
| [in] | padchar | The character to pad with. If '0', then `' '` is used. |
An allocated string with the result, or NULL if s is NULL.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorResult_ljust(), Colr_ljust_char(), and colr_printf_handler().
| void colr_str_lower | ( | char * | s | ) |
Converts a string (char*) into lower case in place.
Input must be null-terminated.
If s is NULL, nothing is done.
| [in] | s | The input string to convert to lower case. |
| size_t colr_str_lstrip | ( | char *restrict | dest, |
| const char *restrict | s, | ||
| size_t | length, | ||
| const char | c | ||
| ) |
Strip a leading character from a string (char*), filling another string (char*) with the result.
dest and s should not overlap.
| [out] | dest | Destination char array. Must have room for strlen(s) + 1. |
| [in] | s | String to strip the character from. |
| [in] | length | Length of s, the input string. |
| [in] | c | Character to strip. If set to 0, all whitespace characters will be used (' ', '\n', '\t', '\v', '\f', '\r'). |
c characters removed. May return 0 if s is NULL/empty, dest is NULL. Referenced by colr_str_lstrip_char(), and RGB_from_hex().
| 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.
| [in] | s | String to strip the character from. |
| [in] | c | Character to strip. If set to 0, all whitespace characters will be used (' ', '\n', '\t'). |
An allocated string with the result. May return NULL if s is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_lstrip_chars | ( | const char *restrict | s, |
| const char *restrict | chars | ||
| ) |
Removes certain characters from the start of a string (char*) and allocates a new string with the result.
The order of the characters in chars does not matter. If any of them are found at the start of a string, they will be removed.
colr_str_lstrip_chars("aabbccTEST", "bca") == "TEST"
s and chars must not overlap.
| [in] | s | The string to strip. s Must be null-terminated. |
| [in] | chars | A string of characters to remove. Each will be removed from the start of the string. chars Must be null-terminated. |
An allocated string with the result. May return NULL if s or chars is NULL.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| size_t colr_str_mb_len | ( | const char * | s | ) |
Returns the number of characters in a string (char*), taking into account possibly multibyte characters.
| [in] | s | The string to get the length of. |
0 if s is NULL, empty, or has invalid multibyte sequences.Referenced by _rainbow().
| size_t colr_str_noncode_len | ( | const char * | s | ) |
Returns the length of string (char*), ignoring escape codes and the the null-terminator.
| [in] | s | String to get the length for. Input must be |
strlen(). For NULL or "empty" strings, 0 is returned.Referenced by ColorText_length(), colr_str_center(), colr_str_ljust(), and colr_str_rjust().
| char* colr_str_replace | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| const char *restrict | repl | ||
| ) |
Replaces the first substring found in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
For a more dynamic version, see the colr_replace and colr_replace_re macros.
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_ColorArg(), colr_str_replace_ColorResult(), and colr_str_replace_ColorText().
| char* colr_str_replace_all | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| const char *restrict | repl | ||
| ) |
Replaces the first substring found in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
For a more dynamic version, see the colr_replace and colr_replace_re macros.
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_all_ColorArg(), colr_str_replace_all_ColorResult(), and colr_str_replace_all_ColorText().
| char* colr_str_replace_all_ColorArg | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorArg * | repl | ||
| ) |
Replace all substrings in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_all_ColorResult | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorResult * | repl | ||
| ) |
Replace all substrings in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_all_ColorText | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorText * | repl | ||
| ) |
Replace all substrings in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_cnt | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| const char *restrict | repl, | ||
| int | count | ||
| ) |
Replaces one or more substrings in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
For a more dynamic version, see the colr_replace and colr_replace_re macros.
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The string to replace with. |
| [in] | count | Number of substrings to replace, or 0 to replace all substrings. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace(), and colr_str_replace_all().
| char* colr_str_replace_ColorArg | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorArg * | repl | ||
| ) |
Replace a substring in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_ColorResult | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorResult * | repl | ||
| ) |
Replace a substring in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_ColorText | ( | const char *restrict | s, |
| const char *restrict | target, | ||
| ColorText * | repl | ||
| ) |
Replace a substring in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | target | The string to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, or target is NULL/empty.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| const char *restrict | repl, | ||
| int | re_flags | ||
| ) |
Replaces a substring from a regex pattern string (char*) in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The string to replace with. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern
doesn't compile/match.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_ColorArg(), colr_str_replace_re_ColorResult(), and colr_str_replace_re_ColorText().
| char* colr_str_replace_re_all | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| const char *restrict | repl, | ||
| int | re_flags | ||
| ) |
Replaces all substrings from a regex pattern string (char*) in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The string to replace with. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern
doesn't compile/match.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_all_ColorArg(), colr_str_replace_re_all_ColorResult(), and colr_str_replace_re_all_ColorText().
| char* colr_str_replace_re_all_ColorArg | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorArg * | repl, | ||
| int | re_flags | ||
| ) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex pattern to compile. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_all_ColorResult | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorResult * | repl, | ||
| int | re_flags | ||
| ) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_all_ColorText | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorText * | repl, | ||
| int | re_flags | ||
| ) |
Replace all substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_ColorArg | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorArg * | repl, | ||
| int | re_flags | ||
| ) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex pattern to compile. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_ColorResult | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorResult * | repl, | ||
| int | re_flags | ||
| ) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_ColorText | ( | const char *restrict | s, |
| const char *restrict | pattern, | ||
| ColorText * | repl, | ||
| int | re_flags | ||
| ) |
Replace substrings from a regex pattern string (char*) in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | pattern | The regex match object to find text to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
| [in] | re_flags | Flags for regcomp(). REG_EXTENDED is always used, whether flags are provided or not. |
An allocated string with the result, or NULL if s is NULL/empty, pattern is NULL, or the regex pattern doesn't compile/match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_match | ( | const char *restrict | s, |
| regmatch_t * | match, | ||
| const char *restrict | repl | ||
| ) |
Replaces substrings from a single regex match (regmatch_t*) in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | match | The regex match object to find text to replace. |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_match_ColorArg(), colr_str_replace_re_match_ColorResult(), colr_str_replace_re_match_ColorText(), and colr_str_replace_re_pat().
| char* colr_str_replace_re_match_ColorArg | ( | const char *restrict | s, |
| regmatch_t * | match, | ||
| ColorArg * | repl | ||
| ) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | match | The regex match object to find text to replace. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_match_ColorResult | ( | const char *restrict | s, |
| regmatch_t * | match, | ||
| ColorResult * | repl | ||
| ) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | match | The regex match object to find text to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_match_ColorText | ( | const char *restrict | s, |
| regmatch_t * | match, | ||
| ColorText * | repl | ||
| ) |
Replace substrings from a regex match (regmatch_t*) in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | match | The regex match object to find text to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_match_i | ( | const char *restrict | ref, |
| char * | target, | ||
| regmatch_t * | match, | ||
| const char *restrict | repl | ||
| ) |
Replaces substrings from a regex match (regmatch_t*) in a string (char*).
This modifies target in place. It must have capacity for the result.
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | ref | The string to use for offset references. Can be target. Set this to the source string if target has not been filled yet. If target has been filled, you may use target for both ref and target. |
| [out] | target | The string to modify. Must have room for the resulting string. |
| [in] | match | The regex match object to find text to replace. |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_matches().
| char* colr_str_replace_re_matches | ( | const char *restrict | s, |
| regmatch_t ** | matches, | ||
| const char *restrict | repl | ||
| ) |
Replaces substrings from an array of regex match (regmatch_t*) in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | matches | Regex match objects to find text to replace. The array must have NULL as the last member. |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_matches_ColorArg(), colr_str_replace_re_matches_ColorResult(), colr_str_replace_re_matches_ColorText(), and colr_str_replace_re_pat_all().
| char* colr_str_replace_re_matches_ColorArg | ( | const char *restrict | s, |
| regmatch_t ** | matches, | ||
| ColorArg * | repl | ||
| ) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | matches | The regex match objects to find text to replace. |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_matches_ColorResult | ( | const char *restrict | s, |
| regmatch_t ** | matches, | ||
| ColorResult * | repl | ||
| ) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | matches | The regex match objects to find text to replace. |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_matches_ColorText | ( | const char *restrict | s, |
| regmatch_t ** | matches, | ||
| ColorText * | repl | ||
| ) |
Replace substrings from an array of regex matches (regmatch_t**) in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | matches | The regex match objects to find text to replace. |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, match is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| const char *restrict | repl | ||
| ) |
Replaces regex patterns in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re(), colr_str_replace_re_pat_ColorArg(), colr_str_replace_re_pat_ColorResult(), and colr_str_replace_re_pat_ColorText().
| char* colr_str_replace_re_pat_all | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| const char *restrict | repl | ||
| ) |
Replaces all matches to a regex pattern in a string (char*).
Using NULL as a replacement is like using an empty string (""), which removes the target string from s.
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The string to replace with. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_str_replace_re_all(), colr_str_replace_re_pat_all_ColorArg(), colr_str_replace_re_pat_all_ColorResult(), and colr_str_replace_re_pat_all_ColorText().
| char* colr_str_replace_re_pat_all_ColorArg | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorArg * | repl | ||
| ) |
Replace all matches to a regex pattern in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat_all_ColorResult | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorResult * | repl | ||
| ) |
Replace all matches to a regex pattern in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat_all_ColorText | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorText * | repl | ||
| ) |
Replace all matches to a regex pattern in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat_ColorArg | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorArg * | repl | ||
| ) |
Replace regex patterns in a string (char*) with a ColorArg's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorArg to produce escape-codes to replace with. ColorArg_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat_ColorResult | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorResult * | repl | ||
| ) |
Replace regex patterns in a string (char*) with a ColorResult's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorResult to produce escape-codes to replace with. ColorResult_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_replace_re_pat_ColorText | ( | const char *restrict | s, |
| regex_t * | repattern, | ||
| ColorText * | repl | ||
| ) |
Replace regex patterns in a string (char*) with a ColorText's string result.
Using NULL as a replacement is like using an empty string ("").
| [in] | s | The string to operate on. |
| [in] | repattern | The regex pattern to match (regex_t*). |
| [in] | repl | The ColorText to produce text/escape-codes to replace with. ColorText_free() is called after the replacement is done. |
An allocated string with the result, or NULL if s is NULL/empty, repattern is NULL, or the regex pattern doesn't match.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* colr_str_repr | ( | const char * | s | ) |
Convert a string (char*) into a representation of a string, by wrapping it in quotes and escaping characters that need escaping.
If s is NULL, then an allocated string containing the string "NULL" is returned (without quotes).
Escape codes will be escaped, so the terminal will ignore them if the result is printed.
| [in] | s | The string to represent. |
An allocated string with the representation.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by _colr_ptr_repr(), ColorResult_repr(), and ColorText_repr().
| char* colr_str_rjust | ( | const char * | s, |
| int | width, | ||
| const char | padchar | ||
| ) |
Right-justifies a string (char*), ignoring escape codes when measuring the width.
| [in] | s | The string to justify. Input must be |
| [in] | width | The overall width for the resulting string. If set to '0', the terminal width will be used from colr_term_size(). |
| [in] | padchar | The character to pad with. If '0', then `' '` is used. |
An allocated string with the result, or NULL if s is NULL.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ColorResult_rjust(), colr_printf_handler(), and Colr_rjust_char().
| bool colr_str_starts_with | ( | const char *restrict | s, |
| const char *restrict | prefix | ||
| ) |
Checks a string (char*) for a certain prefix substring.
prefix Must be null-terminated.
| [in] | s | The string to check. |
| [in] | prefix | The prefix string to look for. |
s starts with prefix. | char* colr_str_strip_codes | ( | const char * | s | ) |
Strips escape codes from a string (char*), resulting in a new allocated string.
| [in] | s | The string to strip escape codes from. Input must be |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by colr_printf_handler().
| char* colr_str_to_lower | ( | const char * | s | ) |
Allocate a new lowercase version of a string (char*).
You must free() the memory allocated by this function.
| [in] | s | The input string to convert to lower case. Must be |
The allocated string, or NULL if s is NULL.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
Referenced by ExtendedValue_from_str(), and RGB_from_str().
| bool colr_supports_rgb | ( | void | ) |
Determine whether the current environment support RGB (True Colors).
This checks $COLORTERM for the appropriate value ('truecolor' or '24bit'). On "dumber" terminals, RGB codes are probably ignored or mistaken for a 256-color or even 8-color value.
For instance, RGB is supported in konsole, but not in xterm or linux ttys. Using RGB codes in xterm makes the colors appear as though a 256-color value was used (closest matching value, like RGB_to_term_RGB()). Using RGB codes in a simpler linux tty makes them appear as though an 8-color value was used. Very ugly, but not a disaster.
I haven't seen a modern linux terminal spew garbage across the screen from using RGB codes when they are not supported, but I could be wrong. I would like to see that terminal if you know of one.
true if 24-bit (true color, or "rgb") support is detected, otherwise false. Referenced by colr_supports_rgb_static().
| bool colr_supports_rgb_static | ( | void | ) |
Same as colr_supports_rgb(), but the environment is only checked on the first call.
All other calls return the same result as the first call.
true if 24-bit (true color, or "rgb") support is detected, otherwise false. | TermSize colr_term_size | ( | void | ) |
Attempts to retrieve the row/column size of the terminal and returns a TermSize.
If the call fails, the environment variables LINES and COLUMNS are checked. If that fails, a default TermSize struct is returned:
Referenced by ColorResult_center(), ColorResult_ljust(), ColorResult_rjust(), ColorText_length(), colr_str_center(), colr_str_ljust(), and colr_str_rjust().
| struct winsize colr_win_size | ( | void | ) |
Attempts to retrieve a winsize struct from an ioctl call.
If the call fails, the environment variables LINES and COLUMNS are checked. If that fails, a default winsize struct is returned:
man ioctl_tty says that .ws_xpixel and .ws_ypixel are unused.
winsize struct (sys/ioctl.h) with window size information. Referenced by colr_term_size().
| struct winsize colr_win_size_env | ( | void | ) |
Get window/terminal size using the environment variables LINES, COLUMNS, or COLS.
This is used as a fallback if the ioctl() call fails in colr_win_size(). If environment variables are not available, a default winsize struct is returned:
winsize struct (sys/ioctl.h) with window size information. Referenced by colr_win_size().
| bool ExtendedValue_eq | ( | ExtendedValue | a, |
| ExtendedValue | b | ||
| ) |
Compares two ExtendedValues.
This is used to implement colr_eq().
| [in] | a | The first ExtendedValue to compare. |
| [in] | b | The second ExtendedValue to compare. |
true if they are equal, otherwise false.| int ExtendedValue_from_BasicValue | ( | BasicValue | bval | ) |
Convert a BasicValue into an ExtendedValue.
BASIC_INVALID, and other invalid BasicValues will return EXT_INVALID.
| [in] | bval | BasicValue to convert. |
0-15 on success, otherwise EXT_INVALID.| int ExtendedValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*) to an ExtendedValue.
| [in] | s | Escape-code string. Must be |
| An | integer in the range 0-255 on success. |
| EXT_INVALID | on error (or if s is NULL). |
| EXT_INVALID_RANGE | if the code number was outside of the range 0-255. |
| int ExtendedValue_from_hex | ( | const char * | hexstr | ) |
Create an ExtendedValue from a hex string (char*).
This is not a 1:1 translation of hex to rgb. Use RGB_from_hex() for that. This will convert the hex string to the closest matching ExtendedValue value.
The format for hex strings can be one of:
| [in] | hexstr | Hex string to convert. |
| COLOR_INVALID | on error or bad values. |
Referenced by ExtendedValue_from_hex_default(), and ExtendedValue_from_str().
| ExtendedValue ExtendedValue_from_hex_default | ( | const char * | hexstr, |
| ExtendedValue | default_value | ||
| ) |
Create an ExtendedValue from a hex string (char*), but return a default value if the hex string is invalid.
This is not a 1:1 translation of hex to rgb. Use RGB_from_hex_default() for that. This will convert the hex string to the closest matching ExtendedValue value.
The format for hex strings can be one of:
| [in] | hexstr | Hex string to convert. |
| [in] | default_value | ExtendedValue to use for bad hex strings. |
default_value on error.| ExtendedValue ExtendedValue_from_RGB | ( | RGB | rgb | ) |
Convert an RGB value into the closest matching ExtendedValue.
| [in] | rgb | RGB value to convert. |
Referenced by ExtendedValue_from_hex(), format_bg_RGB_term(), and format_fg_RGB_term().
| int ExtendedValue_from_str | ( | const char * | arg | ) |
Converts a known name, integer string (0-255), or a hex string (char*), into an ExtendedValue suitable for the extended-value-based functions.
Hex strings can be used:
The `'#'` is not optional for hex strings because it is impossible to tell the difference between the hex value '111' and the extended value '111' without it.
| [in] | arg | Color name to find the ExtendedValue for. |
| EXT_INVALID | on error or bad values. |
| EXT_INVALID_RANGE | if the number was outside of the range 0-255. |
| bool ExtendedValue_is_invalid | ( | int | eval | ) |
Determines whether an integer is an invalid ExtendedValue.
| [in] | eval | A number to check. |
true if the value is considered invalid, otherwise false.| bool ExtendedValue_is_valid | ( | int | eval | ) |
Determines whether an integer is a valid ExtendedValue.
| [in] | eval | A number to check. |
true if the value is considered valid, otherwise false.| char* ExtendedValue_repr | ( | int | eval | ) |
Creates a string (char*) representation of a ExtendedValue.
| [in] | eval | A ExtendedValue to get the value from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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().
| [in] | eval | A ExtendedValue to get the value from. |
A pointer to an allocated string
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| void format_bg | ( | char * | out, |
| BasicValue | value | ||
| ) |
Create an escape code for a background color.
| [out] | out | Memory allocated for the escape code string. Must have enough room for CODEX_LEN. |
| [in] | value | BasicValue value to use for background. |
| 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.
| [out] | out | Memory allocated for the escape code string. Must have enough room for CODE_RGB_LEN. |
| [in] | rgb | RGB struct to get red, blue, and green values from. |
Referenced by _rainbow(), and rainbow_bg().
| 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.
| [out] | out | Memory allocated for the escape code string. |
| [in] | rgb | Pointer to an RGB struct. |
Referenced by _rainbow(), and rainbow_bg_term().
| void format_bgx | ( | char * | out, |
| unsigned char | num | ||
| ) |
Create an escape code for an extended background color.
| [out] | out | Memory allocated for the escape code string. Must have enough room for CODEX_LEN. |
| [in] | num | Value to use for background. |
Referenced by format_bg_RGB_term().
| void format_fg | ( | char * | out, |
| BasicValue | value | ||
| ) |
Create an escape code for a fore color.
| [out] | out | Memory allocated for the escape code string. Must have enough room for CODEX_LEN. |
| [in] | value | BasicValue value to use for fore. |
| 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.
| [out] | out | Memory allocated for the escape code string. |
| [in] | rgb | Pointer to an RGB struct. |
Referenced by rainbow_fg().
| 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.
| [out] | out | Memory allocated for the escape code string. |
| [in] | rgb | Pointer to an RGB struct. |
Referenced by rainbow_fg_term().
| void format_fgx | ( | char * | out, |
| unsigned char | num | ||
| ) |
Create an escape code for an extended fore color.
| [out] | out | Memory allocated for the escape code string. Must have enough room for CODEX_LEN. |
| [in] | num | Value to use for fore. |
Referenced by format_fg_RGB_term().
| void format_style | ( | char * | out, |
| StyleValue | style | ||
| ) |
Create an escape code for a style.
| [out] | out | Memory allocated for the escape code string. Must have enough room for STYLE_LEN. |
| [in] | style | StyleValue value to use for style. |
| char* rainbow_bg | ( | const char * | s, |
| double | freq, | ||
| size_t | offset, | ||
| size_t | spread | ||
| ) |
Rainbow-ize some text using rgb back colors, lolcat style.
This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.
The CODE_RESET_ALL code is appended to the result.
| [in] | s | The string to colorize. Input must be |
| [in] | freq | Frequency ("tightness") for the colors. |
| [in] | offset | Starting offset in the rainbow. |
| [in] | spread | Number of characters per color. |
The allocated/formatted string on success.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* rainbow_bg_term | ( | const char * | s, |
| double | freq, | ||
| size_t | offset, | ||
| size_t | spread | ||
| ) |
This is exactly like rainbow_bg(), except it uses colors that are closer to the standard 256-color values.
This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.
The CODE_RESET_ALL code is appended to the result.
| [in] | s | The string to colorize. Input must be |
| [in] | freq | Frequency ("tightness") for the colors. |
| [in] | offset | Starting offset in the rainbow. |
| [in] | spread | Number of characters per color. |
The allocated/formatted string on success.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* rainbow_fg | ( | const char * | s, |
| double | freq, | ||
| size_t | offset, | ||
| size_t | spread | ||
| ) |
Rainbow-ize some text using rgb fore colors, lolcat style.
This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.
The CODE_RESET_ALL code is appended to the result.
| [in] | s | The string to colorize. Input must be |
| [in] | freq | Frequency ("tightness") for the colors. |
| [in] | offset | Starting offset in the rainbow. |
| [in] | spread | Number of characters per color. |
The allocated/formatted string on success.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* rainbow_fg_term | ( | const char * | s, |
| double | freq, | ||
| size_t | offset, | ||
| size_t | spread | ||
| ) |
This is exactly like rainbow_fg(), except it uses colors that are closer to the standard 256-color values.
This prepends a color code to every character in the string. Multi-byte characters are handled properly by checking colr_mb_len(), and copying the bytes to the resulting string without codes between the multibyte characters.
The CODE_RESET_ALL code is appended to the result.
| [in] | s | The string to colorize. Input must be |
| [in] | freq | Frequency ("tightness") for the colors. |
| [in] | offset | Starting offset in the rainbow. |
| [in] | spread | Number of characters per color. |
The allocated/formatted string on success.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| 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.
| [in] | freq | Frequency ("tightness") of the colors. |
| [in] | offset | Starting offset in the rainbow. |
Referenced by _rainbow().
| unsigned char RGB_average | ( | RGB | rgb | ) |
Return the average for an RGB value.
This is also it's "grayscale" value.
| [in] | rgb | The RGB value to get the average for. |
0-255.Referenced by RGB_grayscale().
Compare two RGB structs.
true if a and b have the same r, g, and b values, otherwise false.Referenced by ColorValue_eq(), and ExtendedValue_from_RGB().
| RGB RGB_from_BasicValue | ( | BasicValue | bval | ) |
Return an RGB value from a known BasicValue.
Terminals use different values to render basic 3/4-bit escape-codes. The values returned from this function match the names found in colr_name_data[].
| [in] | bval | A BasicValue to get the RGB value for. |
| int RGB_from_esc | ( | const char * | s, |
| RGB * | rgb | ||
| ) |
Convert an escape-code string (char*) to an actual RGB value.
| [in] | s | Escape-code string. Must be |
| [out] | rgb | Pointer to an RGB struct to fill in the values for. |
| <tt>0</tt> | on success, with rgb filled with values. |
| COLOR_INVALID | on error (or if s is NULL). |
| COLOR_INVALID_RANGE | if any code numbers were outside of the range 0-255. |
| RGB RGB_from_ExtendedValue | ( | ExtendedValue | eval | ) |
| int RGB_from_hex | ( | const char * | hexstr, |
| RGB * | rgb | ||
| ) |
Convert a hex color into an RGB value.
The format for hex strings can be one of:
| [in] | hexstr | String to check for hex values. Input must be |
| [out] | rgb | Pointer to an RGB struct to fill in the values for. |
| 0 | on success, with rgb filled with the values. |
| COLOR_INVALID | for non-hex strings. |
Referenced by ExtendedValue_from_hex(), RGB_from_hex_default(), and RGB_from_str().
Convert a hex color into an RGB value, but use a default value when errors occur.
The format for hex strings can be one of:
| [in] | hexstr | String to check for RGB values. Input must be |
| [out] | default_value | An RGB value to use when errors occur. |
default_value on error.| int RGB_from_str | ( | const char * | arg, |
| RGB * | rgb | ||
| ) |
Convert an RGB string (char*) into an RGB value.
The format for RGB strings can be one of:
| [in] | arg | String to check for RGB values. Input must be |
| [out] | rgb | Pointer to an RGB struct to fill in the values for. |
| 0 | on success, with rgb filled with the values. |
| COLOR_INVALID | for non-rgb strings. |
| COLOR_INVALID_RANGE | for rgb values outside of 0-255. |
Convert an RGB value into either black or white, depending on it's average grayscale value.
| [in] | rgb | The RGB value to convert. |
rgb(1, 1, 1) or rgb(255, 255, 255).| char* RGB_repr | ( | RGB | rgb | ) |
| char* RGB_to_hex | ( | RGB | rgb | ) |
| char* RGB_to_str | ( | RGB | rgb | ) |
Convert an RGB value into a human-friendly RGB string (char*) suitable for input to RGB_from_str().
| [in] | rgb | RGB value to convert. |
An allocated string in the form "red;green;blue".
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| bool StyleValue_eq | ( | StyleValue | a, |
| StyleValue | b | ||
| ) |
Compares two StyleValues.
This is used to implement colr_eq().
| [in] | a | The first StyleValue to compare. |
| [in] | b | The second StyleValue to compare. |
true if they are equal, otherwise false.| StyleValue StyleValue_from_esc | ( | const char * | s | ) |
Convert an escape-code string (char*) to an actual StyleValue enum value.
| [in] | s | Escape-code string. Must be |
| StyleValue | value on success. |
| STYLE_INVALID | on error (or if s is NULL). |
| STYLE_INVALID_RANGE | if the code number was outside of the range 0-255. |
| StyleValue StyleValue_from_str | ( | const char * | arg | ) |
Convert a named argument to actual StyleValue enum value.
| [in] | arg | Style name to convert into a StyleValue. |
| bool StyleValue_is_invalid | ( | StyleValue | sval | ) |
Determines whether a StyleValue is invalid.
| [in] | sval | A StyleValue to check. |
true if the value is considered invalid, otherwise false.| bool StyleValue_is_valid | ( | StyleValue | sval | ) |
Determines whether a StyleValue is valid.
| [in] | sval | A StyleValue to check. |
true if the value is considered valid, otherwise false.| char* StyleValue_repr | ( | StyleValue | sval | ) |
Creates a string (char*) representation of a StyleValue.
| [in] | sval | A StyleValue to get the value from. |
A pointer to an allocated string.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* StyleValue_to_str | ( | StyleValue | sval | ) |
Create a human-friendly string (char*) representation for a StyleValue.
| [in] | sval | StyleValue to get the name for. |
An allocated string with the result.
You must free() the memory allocated by this function.
If allocation fails, NULL is returned.
| char* TermSize_repr | ( | TermSize | ts | ) |
| int colr_printf_esc_mod |
Integer to test for the presence of the "escaped output modifier" in colr_printf_handler.
This is set in colr_printf_register.
It is used to trigger "escaped output mode" when printing ColrC objects, where the color codes are escaped so you can see what they look like (instead of affecting the terminal).
The character used as the "escaped output modifier" is COLR_FMT_MOD_ESC, from colr.h.
This is set in colr_printf_register when the modifier is registered. On a successful call to register_printf_modifier, it will be a positive number representing the bit set in the USER field in 'struct printf_info'. So later on, in colr_printf_handler():
Referenced by colr_printf_handler(), and colr_printf_register().