cellstr 0.2.1__py3-none-any.whl

cellstr/__init__.py

@@ -0,0 +1,41 @@
+"""Display-cell-accurate length, slicing, padding and truncation for terminal text.
+
+Every function measures what a terminal draws: ANSI escape sequences count as nothing,
+East Asian wide characters as two cells, combining marks and other zero-width code
+points as nothing, and an emoji sequence or a flag as one two-cell glyph. Width data
+comes from the Unicode Character Database, version ``UNICODE_VERSION``.
+"""
+
+from __future__ import annotations
+
+from ._ansi import strip_ansi
+from ._cells import Cell, cell_len, expand_tabs, iter_cells
+from ._graphemes import iter_graphemes
+from ._ops import cell_slice, center, ljust, rjust
+from ._props import UNICODE_VERSION
+from ._truncate import Align, Position, Truncation, fit, truncate, truncate_detailed
+from ._width import char_width, grapheme_width
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "UNICODE_VERSION",
+    "Align",
+    "Cell",
+    "Position",
+    "Truncation",
+    "cell_len",
+    "cell_slice",
+    "center",
+    "char_width",
+    "expand_tabs",
+    "fit",
+    "grapheme_width",
+    "iter_cells",
+    "iter_graphemes",
+    "ljust",
+    "rjust",
+    "strip_ansi",
+    "truncate",
+    "truncate_detailed",
+]

cellstr/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m cellstr``."""
+
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

cellstr/_ansi.py

@@ -0,0 +1,62 @@
+"""ANSI escape sequence detection and removal."""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+# One alternative per ECMA-48 escape family, longest first so a string introducer is never
+# mistaken for a two-character escape:
+#   CSI     ESC [ params intermediates final        colours (SGR), cursor moves
+#   OSC     ESC ] ... BEL or ST                     titles, OSC 8 hyperlinks
+#   strings ESC P / X / ^ / _ ... ST                DCS, SOS, PM, APC
+#   nF      ESC intermediates final                 charset designation such as ESC ( B
+#   Fp/Fe/Fs ESC one final byte                     ESC 7, ESC 8, ESC =, ESC c, ESC M
+# An unterminated OSC or string sequence is never swallowed to the end of the text: at most
+# its introducer counts as an escape and the rest is measured as text, so nothing visible
+# silently disappears.
+_ANSI_RE = re.compile(
+    r"\x1b(?:"
+    r"\[[0-?]*[ -/]*[@-~]"
+    r"|\][^\x07\x1b]*(?:\x07|\x1b\\)"
+    r"|[PX^_][^\x1b]*\x1b\\"
+    r"|[ -/]+[0-~]"
+    r"|[0-Z\\`-~]"
+    r")"
+)
+
+
+def strip_ansi(text: str) -> str:
+    """Return ``text`` with every ANSI escape sequence removed.
+
+    Recognised: CSI sequences (SGR colours and styles, cursor movement), OSC sequences
+    ended by BEL or ST (window titles, OSC 8 hyperlinks), DCS, SOS, PM and APC strings,
+    charset designations and the single-byte escapes.
+
+    >>> strip_ansi("\\x1b[1;31merror\\x1b[0m: \\x1b]8;;https://example.com\\x07docs\\x1b]8;;\\x07")
+    'error: docs'
+    """
+    return _ANSI_RE.sub("", text)
+
+
+class Segment(NamedTuple):
+    """A run of ``text`` tagged as either an escape sequence or printable text."""
+
+    text: str
+    is_escape: bool
+
+
+def segments(text: str) -> list[Segment]:
+    """Split ``text`` into ordered printable and escape segments."""
+    if "\x1b" not in text:
+        return [Segment(text, False)] if text else []
+    out: list[Segment] = []
+    last = 0
+    for match in _ANSI_RE.finditer(text):
+        if match.start() > last:
+            out.append(Segment(text[last : match.start()], False))
+        out.append(Segment(match.group(), True))
+        last = match.end()
+    if last < len(text):
+        out.append(Segment(text[last:], False))
+    return out

cellstr/_cells.py

@@ -0,0 +1,113 @@
+"""Typed iteration over the cells of terminal text, measuring and tab expansion."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import NamedTuple
+
+from ._ansi import segments
+from ._graphemes import grapheme_ends
+from ._width import check_ambiguous, cluster_width, text_width
+
+_LINE_BREAKS = frozenset({"\n", "\r", "\r\n"})
+
+
+class Cell(NamedTuple):
+    """One drawable unit of terminal text, or one escape sequence.
+
+    ``text`` is a whole grapheme cluster or a whole escape sequence, ``width`` the cells
+    it occupies (always 0 for an escape), ``column`` the cell offset where it starts,
+    counted from the start of the text, and ``escape`` tells the two kinds apart.
+    """
+
+    text: str
+    width: int
+    column: int
+    escape: bool
+
+
+def check_tabsize(tabsize: int | None) -> int | None:
+    """Return ``tabsize`` after checking it is None or a positive integer."""
+    if tabsize is not None and (type(tabsize) is not int or tabsize < 1):
+        raise ValueError(f"tabsize must be a positive integer or None, not {tabsize!r}")
+    return tabsize
+
+
+def iter_cells(text: str, *, ambiguous: int = 1, tabsize: int | None = None) -> Iterator[Cell]:
+    """Yield the escape sequences and grapheme clusters of ``text`` with their widths.
+
+    With ``tabsize`` set, a tab advances to the next multiple of ``tabsize`` counted from
+    the start of the current line (a CR or LF starts a new line); otherwise a tab is a
+    zero-width control like every other one. The texts of the cells concatenate back to
+    ``text`` exactly.
+
+    >>> [(len(c.text), c.width, c.column) for c in iter_cells("a\\u4f60\\U0001f1ea\\U0001f1f8")]
+    [(1, 1, 0), (1, 2, 1), (2, 2, 3)]
+    """
+    check_ambiguous(ambiguous)
+    check_tabsize(tabsize)
+    column = 0
+    line_start = 0
+    for segment in segments(text):
+        if segment.is_escape:
+            yield Cell(segment.text, 0, column, True)
+            continue
+        part = segment.text
+        start = 0
+        for end in grapheme_ends(part):
+            cluster = part[start:end]
+            start = end
+            if tabsize is not None and cluster == "\t":
+                width = tabsize - (column - line_start) % tabsize
+            else:
+                width = cluster_width(cluster, ambiguous)
+            yield Cell(cluster, width, column, False)
+            column += width
+            if cluster in _LINE_BREAKS:
+                line_start = column
+
+
+def cell_len(text: str, *, ambiguous: int = 1, tabsize: int | None = None) -> int:
+    """Number of display cells ``text`` occupies, ignoring ANSI escape sequences.
+
+    Clusters are measured whole (see ``grapheme_width``), so an emoji ZWJ sequence or a
+    flag counts once; an escape sequence ends the cluster before it. Controls, including
+    CR and LF, add nothing, so this is the width of a single line. ``ambiguous`` and
+    ``tabsize`` are explained in ``char_width`` and ``iter_cells``.
+
+    >>> cell_len("\\x1b[31mWARN\\x1b[0m"), cell_len("\\u4f60\\u597d"), cell_len("\\u00e9")
+    (4, 4, 1)
+    >>> cell_len("\\U0001f469\\u200d\\U0001f4bb"), cell_len("\\u03b1\\u03b2", ambiguous=2)
+    (2, 4)
+    >>> cell_len("a\\tb", tabsize=8)
+    9
+    """
+    check_ambiguous(ambiguous)
+    if check_tabsize(tabsize) is None or "\t" not in text:
+        return text_width(text, ambiguous)
+    return sum(cell.width for cell in iter_cells(text, ambiguous=ambiguous, tabsize=tabsize))
+
+
+def expand_tabs(text: str, tabsize: int = 8, *, ambiguous: int = 1) -> str:
+    """Replace every tab with the spaces it covers on screen.
+
+    Unlike ``str.expandtabs`` the columns are display cells, so wide characters, emoji
+    and escape sequences before a tab do not throw it off. Escapes are kept in place.
+
+    >>> expand_tabs("\\u4f60\\tx", 4) == "\\u4f60  x"
+    True
+    """
+    if check_tabsize(tabsize) is None:
+        raise ValueError("tabsize must be a positive integer")
+    if "\t" not in text:
+        check_ambiguous(ambiguous)
+        return text
+    return "".join(
+        " " * cell.width if cell.text == "\t" and not cell.escape else cell.text
+        for cell in iter_cells(text, ambiguous=ambiguous, tabsize=tabsize)
+    )
+
+
+def total_width(cells: list[Cell]) -> int:
+    """Width of a list of cells produced by ``iter_cells``."""
+    return cells[-1].column + cells[-1].width if cells else 0

cellstr/_cli.py

@@ -0,0 +1,184 @@
+"""Command line interface: measure, truncate, pad, fit and slice stdin lines by cells."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Callable, Sequence
+from typing import NoReturn
+
+from . import __version__
+from ._cells import cell_len
+from ._ops import cell_slice, center, check_fill, ljust, rjust
+from ._truncate import fit, truncate
+
+EPILOG = """\
+examples:
+  printf 'abc\\n\\344\\275\\240\\345\\245\\275\\n' | cellstr measure
+  printf 'abc\\n\\344\\275\\240\\345\\245\\275\\n' | cellstr measure --max
+  printf 'a long status message\\n' | cellstr truncate 10
+  printf '/usr/local/lib/python3/site-packages\\n' | cellstr truncate 16 --position middle
+  printf 'id\\n12345\\n' | cellstr pad 8 --align right
+  printf 'name\\na much longer name\\n' | cellstr fit 10
+  printf '\\x1b[31mred text\\x1b[0m\\n' | cellstr slice 4
+
+Every command reads UTF-8 lines from stdin and writes one result line per input line,
+keeping each line ending. ANSI escape sequences are ignored when measuring and kept in
+the output. --ambiguous 2 counts East Asian Ambiguous characters (Greek, Cyrillic, box
+drawing) as two cells, as CJK terminals draw them. Errors go to stderr with exit
+status 1.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _cells(text: str) -> int:
+    try:
+        value = int(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not an integer: {text!r}") from None
+    if value < 0:
+        raise argparse.ArgumentTypeError(f"must not be negative: {value}")
+    return value
+
+
+def _positive(text: str) -> int:
+    value = _cells(text)
+    if value == 0:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return value
+
+
+def _add(sub: argparse._SubParsersAction[_Parser], name: str, text: str, example: str) -> _Parser:
+    common = _Parser(add_help=False)
+    common.add_argument(
+        "--ambiguous",
+        type=int,
+        choices=(1, 2),
+        default=1,
+        help="cells for East Asian Ambiguous characters (default 1)",
+    )
+    common.add_argument(
+        "--tabsize",
+        type=_positive,
+        default=None,
+        metavar="N",
+        help="expand tabs to stops every N cells (default: tabs count as zero)",
+    )
+    return sub.add_parser(
+        name,
+        parents=[common],
+        help=text,
+        description=text,
+        epilog=f"example:\n  {example}\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+
+def _cut_options(parser: _Parser) -> None:
+    parser.add_argument("-s", "--suffix", default="...", help="marks the cut (default ...)")
+    parser.add_argument(
+        "--position",
+        choices=("end", "start", "middle"),
+        default="end",
+        help="where to cut (default end)",
+    )
+
+
+def _pad_options(parser: _Parser) -> None:
+    parser.add_argument(
+        "--align", choices=("left", "right", "center"), default="left", help="default left"
+    )
+    parser.add_argument("--fill", default=" ", help="one-cell padding character (default space)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the ``cellstr`` command."""
+    parser = _Parser(
+        prog="cellstr",
+        description="Measure, truncate, pad and slice text by terminal display cells.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"cellstr {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+    measure = _add(sub, "measure", "print the display width of each line", "cellstr measure")
+    measure.add_argument("--max", action="store_true", help="print only the widest width")
+    cut = _add(sub, "truncate", "cut each line to N cells", "cellstr truncate 20 --suffix '~'")
+    cut.add_argument("width", type=_cells, metavar="N", help="maximum width in cells")
+    _cut_options(cut)
+    pad = _add(sub, "pad", "pad each line to N cells", "cellstr pad 12 --align center")
+    pad.add_argument("width", type=_cells, metavar="N", help="target width in cells")
+    _pad_options(pad)
+    fitted = _add(sub, "fit", "truncate or pad each line to exactly N cells", "cellstr fit 12")
+    fitted.add_argument("width", type=_cells, metavar="N", help="exact width in cells")
+    _cut_options(fitted)
+    _pad_options(fitted)
+    piece = _add(sub, "slice", "keep the cells in columns [START, STOP)", "cellstr slice 2 10")
+    piece.add_argument("start", type=_cells, metavar="START", help="first column, from 0")
+    piece.add_argument("stop", type=_cells, nargs="?", metavar="STOP", help="end column")
+    return parser
+
+
+def _lines(text: str) -> list[tuple[str, str]]:
+    """Split ``text`` on LF into ``(body, line ending)`` pairs, keeping CR LF and LF."""
+    pairs: list[tuple[str, str]] = []
+    parts = text.split("\n")
+    for index, body in enumerate(parts):
+        last = index == len(parts) - 1
+        if last and not body:
+            break
+        end = "" if last else "\n"
+        if body.endswith("\r"):
+            body, end = body[:-1], "\r" + end
+        pairs.append((body, end))
+    return pairs
+
+
+def _transform(args: argparse.Namespace) -> Callable[[str], str]:
+    policy = {"ambiguous": args.ambiguous, "tabsize": args.tabsize}
+    if args.command == "truncate":
+        return lambda s: truncate(s, args.width, args.suffix, position=args.position, **policy)
+    if args.command == "fit":
+        options = {"suffix": args.suffix, "position": args.position, "fillchar": args.fill}
+        return lambda s: fit(s, args.width, align=args.align, **options, **policy)
+    if args.command == "pad":
+        pad = {"left": ljust, "right": rjust, "center": center}[args.align]
+        return lambda s: pad(s, args.width, args.fill, **policy)
+    return lambda s: cell_slice(s, args.start, args.stop, **policy)
+
+
+def _run(args: argparse.Namespace, text: str) -> str:
+    lines = _lines(text)
+    if args.command == "measure":
+        widths = [cell_len(b, ambiguous=args.ambiguous, tabsize=args.tabsize) for b, _ in lines]
+        return f"{max(widths, default=0)}\n" if args.max else "".join(f"{w}\n" for w in widths)
+    if args.command in ("pad", "fit"):
+        check_fill(args.fill, args.ambiguous)
+    if args.command == "slice" and args.stop is not None and args.stop < args.start:
+        raise ValueError(f"STOP ({args.stop}) must not be less than START ({args.start})")
+    change = _transform(args)
+    return "".join(change(body) + end for body, end in lines)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line tool and return its exit status."""
+    args = build_parser().parse_args(argv)
+    try:
+        result = _run(args, sys.stdin.buffer.read().decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        print(f"cellstr: error: {exc}", file=sys.stderr)
+        return 1
+    try:
+        sys.stdout.buffer.write(result.encode("utf-8", "surrogatepass"))
+        sys.stdout.buffer.flush()
+    except BrokenPipeError:
+        # The reader went away (for example `| head -1`); exit quietly like other filters.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+    return 0

cellstr/_graphemes.py

@@ -0,0 +1,101 @@
+"""Extended grapheme cluster segmentation per UAX #29, using embedded UCD tables."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from ._props import EXT_PICT_BIT, GCB, INCB_SHIFT, prop
+
+_CR = GCB["CR"]
+_LF = GCB["LF"]
+_CONTROL = GCB["Control"]
+_EXTEND = GCB["Extend"]
+_ZWJ = GCB["ZWJ"]
+_RI = GCB["Regional_Indicator"]
+_PREPEND = GCB["Prepend"]
+_SPACING = GCB["SpacingMark"]
+_L = GCB["L"]
+_V = GCB["V"]
+_T = GCB["T"]
+_LV = GCB["LV"]
+_LVT = GCB["LVT"]
+
+_BREAKERS = frozenset({_CR, _LF, _CONTROL})
+_AFTER_L = frozenset({_L, _V, _LV, _LVT})
+_AFTER_LV_V = frozenset({_V, _T})
+_AFTER_LVT_T = frozenset({_T})
+_INCB_LINKER = 1
+_INCB_CONSONANT = 2
+_INCB_EXTEND = 3
+
+
+def grapheme_ends(s: str) -> Iterator[int]:
+    """Yield the end index (exclusive) of every extended grapheme cluster in ``s``.
+
+    The last value yielded is ``len(s)``; nothing is yielded for the empty string.
+    """
+    if not s:
+        return
+    code = prop(ord(s[0]))
+    prev = code & 0x0F
+    ri_run = 1 if prev == _RI else 0
+    incb = (code >> INCB_SHIFT) & 0x03
+    after_linker = incb == _INCB_LINKER
+    emoji = 1 if code & EXT_PICT_BIT else 0  # 1: pictograph Extend*, 2: then ZWJ
+    for index in range(1, len(s)):
+        code = prop(ord(s[index]))
+        cur = code & 0x0F
+        incb = (code >> INCB_SHIFT) & 0x03
+        pict = code & EXT_PICT_BIT
+        if not _joins(prev, cur, incb, pict, after_linker, emoji, ri_run):
+            yield index
+        after_linker = incb == _INCB_LINKER or (after_linker and incb == _INCB_EXTEND)
+        if pict or (emoji == 1 and cur == _EXTEND):
+            emoji = 1
+        elif emoji == 1 and cur == _ZWJ:
+            emoji = 2
+        else:
+            emoji = 0
+        ri_run = ri_run + 1 if cur == _RI else 0
+        prev = cur
+    yield len(s)
+
+
+def _joins(
+    prev: int, cur: int, incb: int, pict: int, after_linker: bool, emoji: int, ri_run: int
+) -> bool:
+    """Return True when there is no boundary between ``prev`` and ``cur``."""
+    if prev == _CR and cur == _LF:  # GB3
+        return True
+    if prev in _BREAKERS or cur in _BREAKERS:  # GB4, GB5
+        return False
+    if prev == _L and cur in _AFTER_L:  # GB6
+        return True
+    if prev in (_LV, _V) and cur in _AFTER_LV_V:  # GB7
+        return True
+    if prev in (_LVT, _T) and cur in _AFTER_LVT_T:  # GB8
+        return True
+    if cur in (_EXTEND, _ZWJ, _SPACING) or prev == _PREPEND:  # GB9, GB9a, GB9b
+        return True
+    if incb == _INCB_CONSONANT and after_linker:  # GB9c
+        return True
+    if pict and prev == _ZWJ and emoji == 2:  # GB11
+        return True
+    return prev == _RI and cur == _RI and ri_run % 2 == 1  # GB12, GB13
+
+
+def iter_graphemes(s: str) -> Iterator[str]:
+    """Yield the extended grapheme clusters of ``s`` (UAX #29), left to right.
+
+    A grapheme cluster is what a reader perceives as one character: a base letter with
+    its combining marks, a Hangul syllable built from jamo, an emoji ZWJ sequence, a
+    flag made of two regional indicators, an Indic conjunct, or a CR LF pair. The
+    clusters concatenate back to ``s`` exactly.
+
+    >>> [len(g) for g in iter_graphemes("e\\u0301\\U0001f1ea\\U0001f1f8")]
+    [2, 2]
+    """
+    start = 0
+    for end in grapheme_ends(s):
+        yield s[start:end]
+        start = end

cellstr/_ops.py

@@ -0,0 +1,147 @@
+"""Grapheme-safe slicing and padding by display cells.
+
+Escape sequences are always kept in place so colour, style and hyperlinks survive the
+operation, while only printable cells count toward a width.
+"""
+
+from __future__ import annotations
+
+from ._cells import Cell, check_tabsize, expand_tabs, iter_cells, total_width
+from ._graphemes import grapheme_ends
+from ._width import check_ambiguous, cluster_width, text_width
+
+
+def cell_slice(
+    text: str,
+    start: int = 0,
+    stop: int | None = None,
+    *,
+    ambiguous: int = 1,
+    tabsize: int | None = None,
+) -> str:
+    """Return the cells of ``text`` in the half-open column range ``[start, stop)``.
+
+    Grapheme clusters are never split: a letter keeps its accents, a flag or an emoji
+    ZWJ sequence stays whole, and a wide cluster is kept only when all its cells fall
+    inside the range. Every escape sequence is preserved wherever it sits, so styles and
+    OSC 8 hyperlinks still open and close. A zero-width cluster belongs to the column it
+    sits at, and one at the very end belongs to a non-empty range that reaches the end
+    from a column before it (for text with no width at all, to any range starting at 0
+    that is open-ended or non-empty). An empty range holds no printable text. With ``tabsize``
+    set, a tab becomes the spaces it covers inside the range, so the layout survives.
+
+    For plain text, ``cell_slice(t, 0, k) + cell_slice(t, k)`` equals ``t`` whenever
+    ``k`` does not fall inside a wide cluster.
+
+    >>> cell_slice("\\x1b[31mhello\\x1b[0m", 0, 3) == "\\x1b[31mhel\\x1b[0m"
+    True
+    >>> cell_slice("a\\u4f60b", 0, 2), cell_slice("e\\u0301tude", 0, 1) == "e\\u0301"
+    ('a', True)
+    """
+    if start < 0 or (stop is not None and stop < 0):
+        raise ValueError("cell_slice does not support negative indices")
+    cells = list(iter_cells(text, ambiguous=ambiguous, tabsize=tabsize))
+    total = total_width(cells)
+    limit = total if stop is None else min(stop, total)
+    # A zero-width cluster at the very end: who gets it (see the docstring).
+    reach = (start < total) if total else (start == 0 and (stop is None or stop > 0))
+    tail = limit == total and reach
+    return "".join(_keep(cell, start, limit, total, tail, tabsize) for cell in cells)
+
+
+def _keep(cell: Cell, start: int, limit: int, total: int, tail: bool, tabsize: int | None) -> str:
+    if cell.escape:
+        return cell.text
+    if tabsize is not None and cell.text == "\t":
+        return " " * max(0, min(cell.column + cell.width, limit) - max(cell.column, start))
+    if cell.column < start:
+        return ""
+    if cell.width:
+        return "" if cell.column + cell.width > limit else cell.text
+    return cell.text if cell.column < limit or (tail and cell.column == total) else ""
+
+
+def check_fill(fillchar: str, ambiguous: int) -> str:
+    """Return ``fillchar`` after checking it is one grapheme cluster one cell wide."""
+    if (
+        not fillchar
+        or "\x1b" in fillchar
+        or next(grapheme_ends(fillchar)) != len(fillchar)
+        or cluster_width(fillchar, ambiguous) != 1
+    ):
+        raise ValueError(f"fillchar must be a single one-cell character, not {fillchar!r}")
+    return fillchar
+
+
+def _prepare(text: str, fillchar: str, ambiguous: int, tabsize: int | None) -> tuple[str, int]:
+    check_ambiguous(ambiguous)
+    check_fill(fillchar, ambiguous)
+    tabsize = check_tabsize(tabsize)
+    if tabsize is not None:
+        text = expand_tabs(text, tabsize, ambiguous=ambiguous)
+    return text, text_width(text, ambiguous)
+
+
+def ljust(
+    text: str, width: int, fillchar: str = " ", *, ambiguous: int = 1, tabsize: int | None = None
+) -> str:
+    """Pad ``text`` on the right to ``width`` display cells.
+
+    Text already ``width`` cells or wider is returned unchanged. ``fillchar`` must be one
+    cell wide. With ``tabsize`` set, tabs are expanded first (see ``expand_tabs``).
+
+    >>> ljust("\\u4f60", 4) == "\\u4f60  "
+    True
+    """
+    text, used = _prepare(text, fillchar, ambiguous, tabsize)
+    return text + fillchar * max(0, width - used)
+
+
+def rjust(
+    text: str, width: int, fillchar: str = " ", *, ambiguous: int = 1, tabsize: int | None = None
+) -> str:
+    """Pad ``text`` on the left to ``width`` display cells.
+
+    >>> rjust("\\x1b[1m42\\x1b[0m", 5) == "   \\x1b[1m42\\x1b[0m"
+    True
+    """
+    text, used = _prepare(text, fillchar, ambiguous, tabsize)
+    return fillchar * max(0, width - used) + text
+
+
+def center(
+    text: str, width: int, fillchar: str = " ", *, ambiguous: int = 1, tabsize: int | None = None
+) -> str:
+    """Centre ``text`` within ``width`` display cells; an odd cell of padding goes right.
+
+    >>> center("ab", 5)
+    ' ab  '
+    """
+    text, used = _prepare(text, fillchar, ambiguous, tabsize)
+    pad = max(0, width - used)
+    left = pad // 2
+    return fillchar * left + text + fillchar * (pad - left)
+
+
+def splice(text: str, head: int, rstart: int, insert: str, ambiguous: int) -> str:
+    """Keep the clusters in ``[0, head)`` and ``[rstart, end)``, putting ``insert`` between.
+
+    Every escape sequence is kept exactly once, in place, and ``insert`` goes where the
+    first dropped cluster was.
+    """
+    cells = list(iter_cells(text, ambiguous=ambiguous))
+    total = total_width(cells)
+    out: list[str] = []
+    pending = True
+    for cell in cells:
+        end = cell.column + cell.width
+        left = end <= head if cell.width else cell.column < head
+        right = rstart <= cell.column and end <= total
+        if not (cell.escape or left) and pending:
+            out.append(insert)
+            pending = False
+        if cell.escape or left or right:
+            out.append(cell.text)
+    if pending:
+        out.append(insert)
+    return "".join(out)