text.truncate

def truncate(value: str, max_length: int, ellipsis: str) -> str

from fune.text.truncate import truncate  # text.truncate@^1

from typing import Any


def _whole(value: Any) -> bool:
    # bool is an int in Python; True is not a length of one here.
    return isinstance(value, int) and not isinstance(value, bool)


def _is_whitespace(ch: str) -> bool:
    """The Unicode White_Space property, spelled out so all three languages
    agree: str.isspace also accepts U+001C-U+001F, which JavaScript and Rust
    do not.
    """
    cp = ord(ch)
    return (
        0x09 <= cp <= 0x0D
        or cp == 0x20
        or cp == 0x85
        or cp == 0xA0
        or cp == 0x1680
        or 0x2000 <= cp <= 0x200A
        or cp == 0x2028
        or cp == 0x2029
        or cp == 0x202F
        or cp == 0x205F
        or cp == 0x3000
    )


def _is_trailing_punctuation(ch: str) -> bool:
    # Punctuation that reads badly directly before an ellipsis.
    return ch in (",", ";", ":", "-", ".")


def truncate(value: str, max_length: int, ellipsis: str) -> str:
    """Shorten ``value`` to at most ``max_length`` code points, ellipsis
    included, cutting at a word boundary where there is one.
    """
    if not isinstance(value, str):
        raise TypeError("truncate needs a string, received %r" % (value,))
    if not _whole(max_length):
        raise TypeError("maxLength must be a whole number, received %r" % (max_length,))
    if max_length < 0:
        raise ValueError("maxLength must be 0 or greater, received %d" % (max_length,))
    if not isinstance(ellipsis, str):
        raise TypeError("ellipsis must be a string, received %r" % (ellipsis,))
    # A Python str is indexed by code point already.
    if len(ellipsis) > max_length:
        raise ValueError(
            "maxLength must be at least the length of the ellipsis, received %d" % (max_length,)
        )
    if len(value) <= max_length:
        return value

    budget = max_length - len(ellipsis)
    end = budget
    # A cut just before whitespace is already a clean boundary.
    if not _is_whitespace(value[budget]):
        last_space = -1
        for i in range(budget - 1, -1, -1):
            if _is_whitespace(value[i]):
                last_space = i
                break
        # No boundary to move back to: one long word is cut hard rather than
        # reduced to a bare ellipsis.
        if last_space > 0:
            end = last_space

    while end > 0 and (_is_whitespace(value[end - 1]) or _is_trailing_punctuation(value[end - 1])):
        end -= 1
    return value[:end] + ellipsis

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add text.truncate

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./text.truncate-1.0.0-python.fune, or fetch it from a terminal with fune pull text.truncate@1.0.0:python.

The whole function, every language, is one file too: text.truncate-1.0.0.fune, 14,096 bytes, sha256 b7ad085ce8cf8efc872eace07a79adef908cc5061bb91d369cc64baf1819ae77. It installs into a project of any language.

# fune: before text.truncate

# fune: after text.truncate

# fune: step text.truncate after <n|label>

More from the author

1. If the text already fits in `maxLength`, it is returned unchanged, with no ellipsis. Nothing is trimmed or normalised. 2. Otherwise the text is cut to leave room for the ellipsis inside the limit: the result, ellipsis included, is never longer than `maxLength`. 3. If the cut lands exactly before whitespace, that is a clean word boundary and the cut stands. Otherwise it moves back to the last whitespace inside the kept part, so no word is split. 4. If there is no whitespace to move back to (one very long word, a URL, text in a script written without spaces), the word is cut hard at the limit. Splitting a word is better than returning nothing but an ellipsis. 5. Trailing whitespace and the trailing punctuation `, ; : - .` are removed from the cut before the ellipsis goes on, so "Hello, world" gives "Hello..." and not "Hello,...".

Whitespace is the Unicode White_Space set, spelled out character by character (tab, line feed, vertical tab, form feed, carriage return, space, U+0085, U+00A0, U+1680, U+2000-U+200A, U+2028, U+2029, U+202F, U+205F, U+3000) so all three languages agree; each language's built-in notion of "space" differs.

## Counting: code points, not graphemes

Length is counted in Unicode code points in all three languages. JavaScript's `.length` counts UTF-16 units, so a naive TypeScript version would count an emoji as two and disagree with Python; this one does not.

Code points are still not what a reader sees as one character. An accented letter written as a base letter plus a combining accent ("e" + U+0301) is two code points and a hard cut can separate them; a flag or a family emoji is several code points and can be cut in the middle. Getting that right needs the Unicode grapheme cluster rules (UAX #29), which none of the three standard libraries provides the same way, so this capability does not attempt it. If your text may contain such sequences, normalise it to NFC first (which fixes the accented letters) and leave some slack in `maxLength`.

## Errors

`maxLength` must be 0 or more, and at least the length of the ellipsis, since otherwise no truncated result can fit.

Files