C11 Public API

This C11 API is a release candidate.

wcwidth.h

Unicode character display width: wcwidth, wcswidth, wcstwidth.

int wcwidth_u32(uint32_t codepoint, int ambiguous_width)

Return the display width of a single Unicode codepoint.

Returns: 1 or 2: display cells occupied 0: zero-width codepoint (combining marks, ZWJ, etc.) -1: non-printable control character

Parameters:

• ambiguous_width – width for East Asian Ambiguous (A) characters. 1 = narrow (default), 2 = wide (CJK context).

int wcswidth_u32(const uint32_t *codepoints, size_t n, int ambiguous_width)

Return the display width of a string of Unicode codepoints.

This function handles grapheme clusters (ZWJ, VS16, virama, RI pairs, etc.).

Parameters:

• n – number of codepoints in the array.

int wcswidth_u8(const char *utf8, size_t n, int ambiguous_width)

UTF-8 variant of wcswidth_u32().

Parameters:

• n – number of UTF-8 bytes to process. Exactly *n* bytes are read, never treating the text as NUL-terminated; pass strlen(utf8) for a C string.

int wcstwidth_u32(const uint32_t *codepoints, size_t n, int ambiguous_width, const char *term_program)

Terminal-aware variant of wcswidth_u32().

Parameters:

• term_program – terminal name for override tables (e.g. “kitty”, “xterm”, “ghostty”). Use NULL for no terminal overrides.

int wcstwidth_u8(const char *utf8, size_t n, int ambiguous_width, const char *term_program)

Terminal-aware variant of wcswidth_u8().

width.h

Main entry-points for string display width: wcwidth_width_u32 / wcwidth_width_u8.

enum wcwidth_control_mode_t

How wcwidth_width_u32() and wcwidth_width_u8() treat control characters and sequences.

enumerator WCWIDTH_PARSE

track horizontal cursor movement

enumerator WCWIDTH_STRICT

raise errors on indeterminate sequences

enumerator WCWIDTH_IGNORE

strip all control codes and sequences

enum wcwidth_error_t

Error codes written to the *error out-param of wcwidth_width_u32() and wcwidth_width_u8(), and of the string transforms in clip.h and align.h. Distinct codes let callers distinguish the failure cause.

Every out-param is int, whose size is fixed. The underlying type of an enum is implementation-defined, so int keeps the ABI stable across compilers. Compare against these constants directly.

enumerator WCWIDTH_ERROR_NONE

no error

enumerator WCWIDTH_ERROR_INDETERMINATE

indeterminate terminal sequence

enumerator WCWIDTH_ERROR_ILLEGAL_CTRL

illegal C0/C1 control character

enumerator WCWIDTH_ERROR_VERTICAL_CTRL

vertical movement control character

enumerator WCWIDTH_ERROR_CURSOR_LEFT_EXCEED

CUB/backspace moves before column 0

enumerator WCWIDTH_ERROR_CURSOR_LEFT_ABSOLUTE

HPA to an indeterminate column

enumerator WCWIDTH_ERROR_HORIZONTAL_MOVEMENT

CR with indeterminate starting column

enumerator WCWIDTH_ERROR_UNSUPPORTED

unsupported terminal sequence

struct wcwidth_width_opts_t

Measurement options for wcwidth_width_u32() and wcwidth_width_u8().

int tabsize

tab stop width (default 8)

int ambiguous_width

1 or 2

const char *term_program

NULL or terminal name

const wcwidth_width_opts_t WCWIDTH_WIDTH_OPTS_DEFAULT

Default options for wcwidth_width_u32() and wcwidth_width_u8().

int wcwidth_width_u32(const uint32_t *codepoints, size_t n, wcwidth_control_mode_t mode, const wcwidth_width_opts_t *opts, int *error)

Measure the visible width of text, including terminal control sequences such as colors, bold, tabstops, cursor movement, and OSC 66 Text Sizing. wcwidth_width_u32() measures the codepoints directly.

Returns the width in display cells, or -1 on error.

Parameters:

• mode – how control characters and sequences are treated (WCWIDTH_PARSE, WCWIDTH_STRICT, or WCWIDTH_IGNORE).

• opts – measurement options, or NULL for defaults.

• error – written with a wcwidth_error_t code when mode is WCWIDTH_STRICT and the input is indeterminate; may be NULL.

int wcwidth_width_u8(const char *utf8, size_t n, wcwidth_control_mode_t mode, const wcwidth_width_opts_t *opts, int *error)

UTF-8 variant of wcwidth_width_u32().

textwrap.h

Text wrapping with ANSI-aware display width measurement.

struct wcwidth_wrap_opts_t

Options for wcwidth_wrap_u8() and wcwidth_wrap_u8_text().

int width

max line width in display cells

wcwidth_control_mode_t control_codes

int tabsize

tab stop width; <= 0 passes tabs through as-is

int ambiguous_width

const char *term_program

bool expand_tabs

bool replace_whitespace

bool break_long_words

bool drop_whitespace

int max_lines

0 = no limit

const char *initial_indent

const char *subsequent_indent

const char *placeholder

for truncation, default “ […]”

const wcwidth_wrap_opts_t WCWIDTH_WRAP_OPTS_DEFAULT

Default options for wrap().

int wcwidth_wrap_u8(const char *text, size_t text_len, const wcwidth_wrap_opts_t *opts, char **out, size_t *out_len)

Wrap UTF-8 text into lines.

Treats all whitespace (including ‘n’) as inter-word spaces and collapses it. Use wcwidth_wrap_u8_text() to preserve input newlines as paragraph breaks.

Returns 0 on success, -1 on allocation error, and -2 when the placeholder does not fit within the given width (max_lines truncation). On success, *out points to a single malloc’d buffer containing all lines, separated by ‘n’ (no trailing newline). *out_len is the total byte length. The caller does a single free(*out) to release memory.

int wcwidth_wrap_lines_u8(const char *text, size_t text_len, const wcwidth_wrap_opts_t *opts, char **out, size_t *out_len, size_t **offsets, size_t *offset_count)

Like wcwidth_wrap_u8(), but also reports the start offset of each line in the output buffer. Lines are joined by ‘n’, so a line’s byte length is *offsets*[i+1] - *offsets*[i] - 1 (or *out_len* - *offsets*[i] for the last), and a line may itself contain ‘n’ when the placeholder does.

Returns the same codes as wcwidth_wrap_u8(). On success, *offsets* is a malloc’d array of *offset_count* start offsets; the caller does free(*offsets) in addition to free(*out). Empty output yields *offset_count* == 0.

int wcwidth_wrap_u8_text(const char *text, size_t text_len, const wcwidth_wrap_opts_t *opts, char **out, size_t *out_len)

Wrap UTF-8 text preserving input newlines as paragraph breaks.

Splits text on ‘n’, wraps each non-empty line individually with wcwidth_wrap_u8(), and preserves empty or whitespace-only lines as paragraph breaks. Paragraph breaks appear as “nn” in the output.

Returns 0 on success, -1 on allocation error. On success, *out points to a single malloc’d buffer containing all lines, separated by ‘n’ (no trailing newline). *out_len is the total byte length. The caller does a single free(*out) to release memory.

int wcwidth_wrap_u32(const uint32_t *codepoints, size_t n, const wcwidth_wrap_opts_t *opts, uint32_t **out, size_t *out_len)

Codepoint-array variant of wcwidth_wrap_u8(): encodes the codepoints to UTF-8, wraps, and decodes the result back to a codepoint array. The output is a malloc’d array of *out_len* codepoints and the caller does a single free() of it, exactly as wcwidth_wrap_u8() returns UTF-8 bytes.

Returns 0 on success, -1 on allocation error.

int wcwidth_wrap_u32_text(const uint32_t *codepoints, size_t n, const wcwidth_wrap_opts_t *opts, uint32_t **out, size_t *out_len)

Codepoint-array variant of wcwidth_wrap_u8_text().

align.h

Text alignment: ljust, rjust, center.

struct wcwidth_align_opts_t

Options for the justify functions.

Initialize from WCWIDTH_ALIGN_OPTS_DEFAULT and set only what differs; a NULL opts argument uses the defaults unchanged, justifying to width 0.

size_t dest_width

target display width in cells

const char *fillchar

UTF-8 padding, repeated once per padding cell (default “ “)

size_t fillchar_len

byte length of fillchar

int ambiguous_width

1 or 2

const char *term_program

NULL or terminal name

const wcwidth_align_opts_t WCWIDTH_ALIGN_OPTS_DEFAULT

Default options for the justify functions.

char *wcwidth_ljust_u8(const char *text, size_t text_len, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

Left/right/center justify text to opts->dest_width display cells.

Each returns a malloc’d NUL-terminated string on success, or NULL on error. When NULL is returned and *error is set to a nonzero wcwidth_error_t, the failure is a WCWIDTH_STRICT violation; otherwise it is an allocation failure. *error may be NULL, in which case errors are signaled only by the NULL return. On success, *out_len receives the byte length (excluding NUL) when non-NULL; the caller must free() the result.

Tabs are measured as though text begins at column 0. ‘rjust’ and ‘center’ operations insert padding to the left of the text which move tabstops and return an incorrect result, always expand tabs or clip to opts->dest_width, which expands tabs before using those alignment functions.

Parameters:

• text – UTF-8 input, NOT NUL-terminated.

• text_len – byte length of text.

• mode – how control characters and sequences are treated, as for wcwidth_width_u8().

• opts – alignment options, or NULL for defaults.

• out_len – output: byte length of result (excluding NUL); may be NULL.

• error – output: wcwidth_error_t, WCWIDTH_ERROR_NONE on success.

char *wcwidth_rjust_u8(const char *text, size_t text_len, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

char *wcwidth_center_u8(const char *text, size_t text_len, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

uint32_t *wcwidth_ljust_u32(const uint32_t *codepoints, size_t n, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

Codepoint-array variants of wcwidth_ljust_u8()/wcwidth_rjust_u8()/wcwidth_center_u8(): encode the codepoints to UTF-8, justify, and decode the result back to a codepoint array. The returned array is *out_len* codepoints and the caller does a single free() of it. Error and ownership semantics are as for the _u8() forms: on NULL return, *error* is a nonzero wcwidth_error_t for a WCWIDTH_STRICT violation, or WCWIDTH_ERROR_NONE for an allocation failure. opts->fillchar stays UTF-8 bytes.

uint32_t *wcwidth_rjust_u32(const uint32_t *codepoints, size_t n, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

uint32_t *wcwidth_center_u32(const uint32_t *codepoints, size_t n, wcwidth_control_mode_t mode, const wcwidth_align_opts_t *opts, size_t *out_len, int *error)

clip.h

Clip text to a visible column range [v_start, v_end).

struct wcwidth_clip_opts_t

Options for wcwidth_clip_u32() and wcwidth_clip_u8().

Initialize from WCWIDTH_CLIP_OPTS_DEFAULT and set only what differs; a NULL opts argument uses the defaults unchanged.

size_t v_start

starting column, inclusive (default 0)

size_t v_end

ending column, exclusive. SIZE_MAX (the default) clips through the final column of text, as the -1 default of Python’s clip() does. Clamped to INT_MAX with v_start.

int tabsize

tab stop width, 0 passes tabs through (default 8)

int ambiguous_width

1 or 2

const char *term_program

NULL or terminal name

bool propagate_sgr

wrap result with the SGR state at the first visible character (default true)

const char *fillchar

UTF-8 fill for a partially visible grapheme, display width 1 (default “ “)

size_t fillchar_len

byte length of fillchar

const wcwidth_clip_opts_t WCWIDTH_CLIP_OPTS_DEFAULT

Default options for wcwidth_clip_u32() and wcwidth_clip_u8().

char *wcwidth_clip_u8(const char *text, size_t text_len, wcwidth_control_mode_t mode, const wcwidth_clip_opts_t *opts, size_t *out_len, int *error)

Clip text to the visible column range [opts->v_start, opts->v_end).

Returns a malloc’d string on success, NULL on error. On success, *out_len receives the byte length of the result (excluding the NUL terminator, which is always present), and the caller must free the returned pointer with a single free() call. When NULL is returned, *error (from width.h) is WCWIDTH_ERROR_UNSUPPORTED for a terminal sequence this function does not support, another nonzero wcwidth_error_t for a WCWIDTH_STRICT violation, and WCWIDTH_ERROR_NONE for an allocation failure. *error is always written on return.

Unsupported: horizontal cursor movement (BS, CR, CUF, CUB, HPA), OSC 8 hyperlinks and OSC 66 text sizing.

Parameters:

• text – UTF-8 encoded input string, NOT NUL-terminated.

• text_len – length of text in bytes.

• mode – how control characters and sequences are treated. WCWIDTH_STRICT raises on indeterminate sequences.

• opts – clipping options, or NULL for defaults.

• out_len – output: byte length of result (excluding NUL); may be NULL.

• error – output: wcwidth_error_t, WCWIDTH_ERROR_NONE on success.

uint32_t *wcwidth_clip_u32(const uint32_t *codepoints, size_t n, wcwidth_control_mode_t mode, const wcwidth_clip_opts_t *opts, size_t *out_len, int *error)

Codepoint-array variant of wcwidth_clip_u8(): encodes the codepoints to UTF-8, clips, and decodes the result back to a codepoint array. The returned array is *out_len* codepoints and the caller does a single free() of it. Error and ownership semantics are as for wcwidth_clip_u8(), including WCWIDTH_ERROR_UNSUPPORTED. opts->fillchar stays UTF-8 bytes.

escape.h

Terminal escape sequence classification.

enum wcwidth_esc_type_t

Types of escape sequences the parser can classify.

enumerator WCWIDTH_ESC_NONE

not an escape sequence

enumerator WCWIDTH_ESC_UNRECOGNIZED

lone ESC or malformed

enumerator WCWIDTH_ESC_SGR

CSI … m (Select Graphic Rendition)

enumerator WCWIDTH_ESC_CUF

CSI n C (Cursor Forward)

enumerator WCWIDTH_ESC_CUB

CSI n D (Cursor Backward)

enumerator WCWIDTH_ESC_HPA

CSI n G (Horizontal Position Absolute)

enumerator WCWIDTH_ESC_OSC66

OSC 66;… (Text Sizing)

enumerator WCWIDTH_ESC_INDETERMINATE

clear, scroll, cursor up/down, etc.

enumerator WCWIDTH_ESC_OTHER

any other recognized zero-width sequence

struct wcwidth_esc_result_t

Parsed parameters from a classified escape sequence.

wcwidth_esc_type_t type

const char *start

pointer to start of sequence in original text

size_t length

total length of sequence in bytes

const char *sgr_params

For SGR: pointer to parameter string (after CSI, before ‘m’), length

size_t sgr_params_len

int cursor_n

For CUF/CUB/HPA: parsed numeric parameter (defaults to 1 if absent)

const char *ts_meta

For OSC 66: pointers to meta, text, and terminator parts

size_t ts_meta_len

const char *ts_text

size_t ts_text_len

char ts_terminator

‘x07’ or ‘x1b’ (ST)

bool wcwidth_escape_classify(const char *text, size_t text_len, size_t offset, wcwidth_esc_result_t *result)

Classify the escape sequence starting at *text[offset]*. Returns false if no escape sequence is found (text[offset] != ESC). On success, fills *result with parsed data and returns true.

Parameters:

• text – full input text

• text_len – total length of text

• offset – position of the ESC character

• result – output, filled on success

size_t wcwidth_escape_strip(const char *text, size_t text_len, char *out, size_t out_cap, size_t *out_len)

Strip all terminal escape sequences from text. OSC 66 inner display text is preserved as visible output. Writes result to *out* (caller-provided buffer). Returns the byte length of the stripped text, excluding the NUL terminator, so *out* must have capacity for the return value plus one. Output was truncated when the return value is >= out_cap; pass an out_cap of 0 to measure without writing.

Parameters:

• out_cap – capacity of out buffer.

• out_len – filled with actual bytes written (excluding NUL terminator if any).

uint32_t *wcwidth_escape_strip_u32(const uint32_t *codepoints, size_t n, size_t *out_len)

Codepoint-array variant of wcwidth_escape_strip(): encodes the codepoints to UTF-8, strips, and decodes the result back to a codepoint array. The returned array is *out_len* codepoints and the caller does a single free() of it; returns NULL on allocation failure.

type wcwidth_escape_iter_fn

Callback for iterating over text segments. :param segment: text segment :param seg_len: length of segment :param is_escape: true if this segment is an escape sequence, false if visible text :param userdata: caller-provided pointer

void wcwidth_escape_iter(const char *text, size_t text_len, wcwidth_escape_iter_fn fn, void *userdata)

Iterate over text, calling *fn* for each segment (escape or visible text), without allocating.

bool wcwidth_escape_has_cursor_movement(const char *text, size_t text_len)

Check if text contains any horizontal cursor movement: BS (0x08), CR (0x0d), or CSI n C/D/G Returns true if found.

utf8.h

UTF-8 decoding and encoding.

size_t wcwidth_utf8_decode_single(const char *s, size_t len, uint32_t *cp_out)

Decode one UTF-8 codepoint from *s* (at most *len* bytes). Returns the number of bytes consumed (1-4). On error or truncation, *cp_out* is set to U+FFFD and the return value is the number of bytes to skip (1 for a bad leading byte, the remaining length for a truncated sequence, or 0 when *len* is 0).

*s* must not be NULL. *cp_out* may be NULL to consume the sequence and query the length of the next character.

uint32_t *wcwidth_decode_u32(const char *utf8, size_t n, uint32_t *stack, size_t stack_cap, size_t *count)

Decode *utf8* into a codepoint array. The caller provides *stack* (up to *stack_cap* entries) as scratch space; when the result fits it is returned in *stack* (no allocation), otherwise a heap buffer is allocated. The caller must free() the result only when it is not *stack*; freeing *stack* is undefined behavior. Sets *count* and returns NULL on allocation failure.

*utf8* and *count* must not be NULL; *count* is required because the returned array carries no terminator. A *stack* of NULL forces the heap path. When *n* is 0 and *stack* is NULL, the result is a freeable array with *count* set to 0.

The result type allows a plain free() release, matching wcwidth_encode_u32() below. Treat the contents as read-only.

Decoding reads exactly *n* bytes. A NUL byte counts as an ordinary zero-width codepoint in any position; pass strlen(utf8) for a C string.

uint32_t *wcwidth_decode_u32_heap(const char *utf8, size_t n, size_t *count)

Decode *utf8* into a malloc’d codepoint array (one free()). Returns the array and sets *count*, or NULL on allocation failure. An *n* of 0 returns a freeable array with *count* set to 0.

Follows the length and NUL semantics of wcwidth_decode_u32().

char *wcwidth_encode_u32(const uint32_t *codepoints, size_t n, char *stack, size_t stack_cap, size_t *out_len)

Encode *codepoints* (n entries) to UTF-8. The caller provides *stack* (up to *stack_cap* bytes) as scratch space; when the result fits it is returned in *stack* (no allocation), otherwise a heap buffer is allocated. The caller must free() the result only when it is not *stack*; freeing *stack* is undefined behavior. Sets *out_len* and returns NULL on allocation failure. An *n* of 0 returns a freeable buffer with *out_len* set to 0.

*codepoints* and *out_len* must not be NULL; *out_len* is required because the returned bytes carry no terminator. A *stack* of NULL forces the heap path.

Encoding writes exactly *n* codepoints: a U+0000 becomes a NUL byte, so the output can contain embedded NUL bytes. Invalid codepoints (lone surrogates and values above U+10FFFF) are encoded as U+FFFD.

grapheme.h

Grapheme cluster segmentation for UTF-8 text.

type wcwidth_grapheme_iter_t

Opaque iterator for grapheme cluster segmentation.

wcwidth_grapheme_iter_t *wcwidth_grapheme_iter_new(const char *utf8, size_t len)

Initialize an iterator over grapheme clusters in a UTF-8 string. Returns NULL if allocation fails (malloc for iterator state).

const char *wcwidth_grapheme_next(wcwidth_grapheme_iter_t *iter, size_t *out_len)

Return the next grapheme cluster, or NULL when exhausted. *out_len* receives the byte length of the cluster. The returned pointer is into the original text buffer.

void wcwidth_grapheme_iter_free(wcwidth_grapheme_iter_t *iter)

Free the iterator.

size_t wcwidth_grapheme_boundary_before(const char *utf8, size_t len, size_t pos)

Find the grapheme cluster boundary immediately before *pos*. Returns the byte offset of the cluster start.

size_t wcwidth_grapheme_boundary_after(const char *utf8, size_t len, size_t pos)

Byte offset one past the end of the cluster containing *pos*, or *len* when that cluster runs to the end.

wcwidth_grapheme_iter_t *wcwidth_grapheme_iter_new_u32(const uint32_t *codepoints, size_t n)

Iterate *codepoints*, which the iterator borrows; the caller must keep it alive for the iterator’s lifetime. Returns NULL if allocation fails.

const uint32_t *wcwidth_grapheme_next_u32(wcwidth_grapheme_iter_t *iter, size_t *out_len)

Next cluster, or NULL when exhausted. *out_len* receives its length in codepoints and the returned pointer is into the caller’s array. Only meaningful for an iterator from wcwidth_grapheme_iter_new_u32().

size_t wcwidth_grapheme_boundary_before_u32(const uint32_t *codepoints, size_t n, size_t pos)

Codepoint index of the start of the cluster containing *pos*.

size_t wcwidth_grapheme_boundary_after_u32(const uint32_t *codepoints, size_t n, size_t pos)

Codepoint index one past the end of the cluster containing *pos*, or *n*.

sgr.h

SGR (Select Graphic Rendition) escape sequence state management.

WCWIDTH_SGR_COLOR_MAX

Maximum number of color components stored (e.g. (38, 5, N) or (38, 2, R, G, B)).

Defined as 6.

WCWIDTH_SGR_PROPAGATE_SPARE

Spare capacity, in bytes, that each line passed to wcwidth_sgr_propagate must have beyond its NUL terminator: the carried-over SGR state can expand to this many bytes of prefix plus a reset suffix.

Defined as 256.

struct wcwidth_sgr_state_t

SGR state tracking: boolean attributes + foreground/background color.

bool bold

bool dim

bool italic

bool underline

bool blink

bool rapid_blink

bool inverse

bool hidden

bool strikethrough

bool double_underline

int fg[WCWIDTH_SGR_COLOR_MAX]

Foreground color: first element is 38 or 0; 0 = default/unset.

int fg_len

int bg[WCWIDTH_SGR_COLOR_MAX]

Background color: first element is 48 or 0; 0 = default/unset.

int bg_len

const wcwidth_sgr_state_t WCWIDTH_SGR_STATE_DEFAULT

Default state (no attributes, no colors).

void wcwidth_sgr_update(wcwidth_sgr_state_t *state, const char *sgr_params, size_t sgr_params_len)

Parse an SGR escape sequence and update *state*. :param sgr_params: the parameter string (between ‘[’ and ‘m’), e.g. “1;31;44” :param sgr_params_len: length of parameter string :param state: current state, updated in-place

bool wcwidth_sgr_is_active(const wcwidth_sgr_state_t *state)

Check if any attributes or colors are set (non-default).

size_t wcwidth_sgr_to_escape(const wcwidth_sgr_state_t *state, char *out, size_t out_cap)

Generate the minimal SGR escape sequence needed to restore *state* from reset. Writes to *out* (caller buffer). Returns bytes written (excluding NUL). out_cap must be at least WCWIDTH_SGR_PROPAGATE_SPARE bytes.

int wcwidth_sgr_propagate(char **lines, const size_t *line_lens, size_t *out_lens, size_t nlines)

Propagate SGR codes across an array of wrapped lines. Modifies lines in-place. Each line is NUL-terminated and must have at least WCWIDTH_SGR_PROPAGATE_SPARE bytes of spare capacity beyond *line_lens[i]*. *line_lens* carries the actual byte length of each line (may include embedded NULs); *out_lens* receives the new byte length after SGR prefix/suffix insertion (may be NULL). Returns 0 on success, -1 if any buffer is too small.

text_sizing.h

OSC 66 Text Sizing protocol parsing and measurement.

struct wcwidth_ts_params_t

Parsed OSC 66 Text Sizing parameters.

int scale

repeat count, default 1

int width

0 = auto-width from text, >0 = fixed width

int numerator

fraction numerator (0 = don’t care)

int denominator

fraction denominator (0 = don’t care)

int vertical_align

0=top, 1=bottom, 2=center

int horizontal_align

0=left, 1=right, 2=center

struct wcwidth_text_sizing_t

A parsed OSC 66 Text Sizing sequence.

wcwidth_ts_params_t params

const char *text

pointer into original buffer

size_t text_len

char terminator

‘x07’ or ‘x1b’

bool wcwidth_ts_parse_params(const char *meta, size_t meta_len, wcwidth_ts_params_t *params)

Parse OSC 66 parameters from the colon-separated meta string. :param meta: parameter string, e.g. “s=2:w=3:n=1:d=2:v=1:h=1” :param meta_len: length of meta string. Exactly meta_len bytes are read; *meta* need not be NUL-terminated. Returns true on success.

void wcwidth_ts_from_esc(const wcwidth_esc_result_t *esc, wcwidth_text_sizing_t *ts)

Build a text sizing struct from a classified OSC 66 escape result, applying default parameters.

int wcwidth_ts_display_width(const wcwidth_text_sizing_t *ts, int ambiguous_width)

Compute the display width of a text sizing sequence. :param ambiguous_width: 1 or 2 (see wcwidth.h) Uses wcswidth_u8 internally for width measurement.

terminal_override.h

Terminal override lookup.

Shared by wcstwidth.c and width.c: resolves a terminal identifier to its generated override table and looks up grapheme cluster overrides.

const wcwidth_terminal_override_t *wcwidth_resolve_terminal(const char *term_program)

Resolve a terminal identifier to its generated override table.

*term_program* is a TERM_PROGRAM/TERM value, alias, or canonical terminal name (case-insensitive, surrounding whitespace ignored). Returns NULL when it is NULL/empty or does not name a known terminal; in that case no overrides apply.

int wcwidth_grapheme_override_lookup(const wcwidth_terminal_override_t *term, const uint32_t *cps, size_t len)

Look up a grapheme cluster (a codepoint sequence) in *term*’s override table. Returns the terminal-measured width, or -1 when the cluster is not overridden.

size_t wcwidth_scan_zwj_cluster_end(const uint32_t *cp, size_t n, size_t start)

Scan forward from *start* (a base character) to the end of a ZWJ grapheme cluster, following UAX #29 GB11 (ExtPict Extend* ZWJ x ExtPict, chained). Returns the index just past the cluster.

size_t wcwidth_scan_zwj_cluster_end_u8(const char *utf8, size_t n, size_t start)

UTF-8 variant; *start* is a byte offset and the returned index is a byte offset.

size_t wcwidth_decode_cluster(const char *utf8, size_t lo, size_t hi, uint32_t *cps, size_t cap)

Decode the UTF-8 bytes in utf8[lo..hi) into *cps*, up to *cap* codepoints. Returns the number decoded; when the range holds more than *cap* codepoints the caller must treat the cluster as unmatched (no override key can be that long).

wcwidth_config.h

Library version, Unicode version, and UTF-8 configuration macros.

The version macros track the Python wcwidth package release, so the same version number applies to both.

WCWIDTH_VERSION_MAJOR

Defined as 0.

WCWIDTH_VERSION_MINOR

Defined as 9.

WCWIDTH_VERSION_PATCH

Defined as 3.

WCWIDTH_VERSION

Defined as "0.9.3".

WCWIDTH_UNICODE_VERSION

Unicode version the library tables were generated from.

Defined as "18.0.0".

WCWIDTH_UTF8_MAX_BYTES

Maximum number of bytes needed to decode a single UTF-8 codepoint.

Defined as 4.

WCWIDTH_CTRL_WIDTH

Return value indicating a non-printable control character.

Defined as (-1).

table_types.h

Table data model: the interval type, the terminal-override record layouts, and the binary search over them.

Hand-written. The tables themselves (every WCWIDTH_* interval array, the terminal override and alias arrays, and their entry counts) are declared in tables.h, which update-tables.py generates.

struct wcwidth_interval_t

An interval [start, end] (inclusive) in Unicode codepoint space.

uint32_t start

uint32_t end

int wcwidth_bisearch(uint32_t ucs, const wcwidth_interval_t *table, size_t table_len)

Binary search for *ucs* in a sorted interval table.

Returns 1 if *ucs* is contained within any interval in *table*, 0 otherwise.

*table* must be sorted ascending, with non-overlapping intervals.

static inline unsigned wcwidth_class_paged8_get(uint32_t ucs, uint32_t min, uint32_t max, unsigned shift, const uint8_t *index, const uint8_t *pool)

Look up the 4-bit class of *ucs* in a paged nibble table, or 0 when out of range.

*index* maps each page of [min, max] to a page of *pool*; two codepoints share a byte.

struct wcwidth_override_set_t

Terminal override record layouts.

The six single-codepoint categories are the merged override intervals; grapheme clusters are stored as a flat codepoint pool with sorted lookup entries.

const wcwidth_interval_t *narrower

size_t narrower_len

const wcwidth_interval_t *vs16_narrower

size_t vs16_narrower_len

const wcwidth_interval_t *vs15_wider

size_t vs15_wider_len

const wcwidth_interval_t *zeroer

size_t zeroer_len

const wcwidth_interval_t *narrow_wider

size_t narrow_wider_len

const wcwidth_interval_t *narrow_zeroer

size_t narrow_zeroer_len

struct wcwidth_grapheme_entry_t

uint32_t offset

into the table’s grapheme codepoint pool

uint16_t len

codepoints in the cluster

uint8_t width

terminal-measured width

struct wcwidth_terminal_override_t

const char *name

canonical terminal name

const wcwidth_override_set_t *set

const uint32_t *grapheme_pool

size_t grapheme_pool_len

const wcwidth_grapheme_entry_t *grapheme_entries

size_t grapheme_entries_len

struct wcwidth_terminal_alias_t

const char *alias

TERM/TERM_PROGRAM value, lowercase

const char *canonical

canonical terminal name