New functions: iter_graphemes_reverse(), grapheme_boundary_before() (#192)

As I audit and integrate with dependent libraries, in [urwid](https://github.com/urwid/urwid/) I find the need to help "move the cursor left" and look backwards from a location in a string to the previous boundary, while looking forward using ``iter_graphemes()``.

Looking backwards is provided by new function ``grapheme_boundary_before()``.

The more obvious function, ``iter_graphemes_reverse()`` is provided (though not useful to urwid). @penguinolog

Author: jquast

docs/api.rst

@@ -16,6 +16,10 @@ requirements.txt or equivalent. Their signatures will never change.
 
 .. autofunction:: wcwidth.iter_graphemes
 
+.. autofunction:: wcwidth.iter_graphemes_reverse
+
+.. autofunction:: wcwidth.grapheme_boundary_before
+
 .. autofunction:: wcwidth.ljust
 
 .. autofunction:: wcwidth.rjust

docs/intro.rst

@@ -48,8 +48,10 @@ Text-justification is solved by the grapheme and sequence-aware functions `ljust
 of the same names.
 
 The iterator functions `iter_graphemes()`_ and `iter_sequences()`_ allow for careful navigation of
-grapheme and terminal control sequence boundaries.  The `clip()`_ function extracts substrings by
-display column positions, and `strip_sequences()`_ removes terminal escape sequences from text.
+grapheme and terminal control sequence boundaries.  `iter_graphemes_reverse()`_, and
+`grapheme_boundary_before()`_ are useful for editing and searching of complex unicode.  The
+`clip()`_ function extracts substrings by display column positions, and `strip_sequences()`_ removes
+terminal escape sequences from text altogether.
 
 Discrepancies
 -------------
@@ -442,7 +444,8 @@ languages.
 History
 =======
 
-*next release*
+0.4.0 *2026-01-25*
+  * **New** Functions `iter_graphemes_reverse()`_, `grapheme_boundary_before()`_.
   * **Bugfix** OSC Hyperlinks should not be broken by ``wrap()``
 
 0.3.5 *2026-01-24*
@@ -663,6 +666,8 @@ https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c::
 .. _`wcswidth()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.wcswidth
 .. _`width()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.width
 .. _`iter_graphemes()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.iter_graphemes
+.. _`iter_graphemes_reverse()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.iter_graphemes_reverse
+.. _`grapheme_boundary_before()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.grapheme_boundary_before
 .. _`ljust()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.ljust
 .. _`rjust()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.rjust
 .. _`center()`: https://wcwidth.readthedocs.io/en/latest/api.html#wcwidth.center

pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "wcwidth"
-version = "0.3.5"
+version = "0.4.0"
 description = "Measures the displayed width of unicode strings in a terminal"
 readme = "README.rst"
 keywords = [

tests/test_benchmarks.py

@@ -1,6 +1,7 @@
 """Performance benchmarks for wcwidth module."""
 # std imports
 import os
+import unicodedata
 
 # local
 import wcwidth
@@ -54,6 +55,31 @@ def test_wcswidth_emoji_sequence(benchmark):
     benchmark(wcwidth.wcswidth, text)
 
 
+# NFC vs NFD comparison - text with combining marks
+DIACRITICS_COMPOSED = 'café résumé naïve ' * 100
+DIACRITICS_DECOMPOSED = unicodedata.normalize('NFD', DIACRITICS_COMPOSED)
+
+
+def test_wcswidth_composed(benchmark):
+    """Benchmark wcswidth() with NFC-composed text."""
+    benchmark(wcwidth.wcswidth, DIACRITICS_COMPOSED)
+
+
+def test_wcswidth_decomposed(benchmark):
+    """Benchmark wcswidth() with NFD-decomposed text."""
+    benchmark(wcwidth.wcswidth, DIACRITICS_DECOMPOSED)
+
+
+def test_width_composed(benchmark):
+    """Benchmark width() with NFC-composed text."""
+    benchmark(wcwidth.width, DIACRITICS_COMPOSED)
+
+
+def test_width_decomposed(benchmark):
+    """Benchmark width() with NFD-decomposed text."""
+    benchmark(wcwidth.width, DIACRITICS_DECOMPOSED)
+
+
 def test_width_ascii(benchmark):
     """Benchmark width() with ASCII string."""
     benchmark(wcwidth.width, 'hello world')
@@ -88,6 +114,36 @@ def test_iter_graphemes_combining(benchmark):
     benchmark(lambda: list(wcwidth.iter_graphemes(text)))
 
 
+def test_grapheme_boundary_before_short(benchmark):
+    """Benchmark grapheme_boundary_before() near start of short string."""
+    text = 'Hello 👋🏻!'
+    benchmark(wcwidth.grapheme_boundary_before, text, 8)
+
+
+def test_grapheme_boundary_before_long_end(benchmark):
+    """Benchmark grapheme_boundary_before() near end of long line."""
+    text = 'x' * 95 + '👨\u200d👩\u200d👧!'
+    benchmark(wcwidth.grapheme_boundary_before, text, 100)
+
+
+def test_grapheme_boundary_before_long_mid(benchmark):
+    """Benchmark grapheme_boundary_before() in middle of long line."""
+    text = 'x' * 50 + '👨\u200d👩\u200d👧' + 'y' * 50
+    benchmark(wcwidth.grapheme_boundary_before, text, 55)
+
+
+def test_iter_graphemes_reverse_short(benchmark):
+    """Benchmark iter_graphemes_reverse() with short string."""
+    text = 'café\u0301 🇫🇷!'
+    benchmark(lambda: list(wcwidth.iter_graphemes_reverse(text)))
+
+
+def test_iter_graphemes_reverse_long(benchmark):
+    """Benchmark iter_graphemes_reverse() with long string."""
+    text = 'The quick brown 🦊 jumps over the lazy 🐕. ' * 5
+    benchmark(lambda: list(wcwidth.iter_graphemes_reverse(text)))
+
+
 def test_ljust_ascii(benchmark):
     """Benchmark ljust() with ASCII string."""
     benchmark(wcwidth.ljust, 'hello', 20)

tests/test_grapheme.py

@@ -6,7 +6,7 @@
 import pytest
 
 # local
-from wcwidth import iter_graphemes
+from wcwidth import iter_graphemes, iter_graphemes_reverse, grapheme_boundary_before
 
 try:
     chr(0x2fffe)
@@ -144,3 +144,112 @@ def test_wide_unicode_graphemes(input_str, expected):
 def test_unicode_grapheme_break_test(input_str, expected):
     """Validate against official Unicode GraphemeBreakTest.txt."""
     assert list(iter_graphemes(input_str)) == expected
+
+
+# Prepend: Arabic Number Sign
+PREPEND_CHAR = '\u0600'
+# Multiple combining marks: e + acute + grave
+MULTI_COMBINE = 'e\u0301\u0300'
+
+
+# grapheme_boundary_before(text, pos) returns start of grapheme cluster before pos.
+# (text, pos, expected): pos=search from here, expected=where cluster starts
+@pytest.mark.parametrize(("text", "pos", "expected"), [
+    # 'abc': 0=a, 1=b, 2=c
+    ('abc', 3, 2),  # from end -> 'c' at 2
+    ('abc', 2, 1),  # from 'c' -> 'b' at 1
+    ('abc', 1, 0),  # from 'b' -> 'a' at 0
+    # 'a\r\nb': CRLF is one cluster (GB3)
+    ('a\r\nb', 3, 1),  # from 'b' -> '\r\n' at 1
+    # 'café': e + combining acute is one cluster (GB9)
+    ('cafe\u0301', 5, 3),  # from end -> 'é' at 3
+    ('cafe\u0301', 4, 3),  # from acute -> still 'é' at 3
+    # Multiple combining marks: e + acute + grave (GB9)
+    ('a' + MULTI_COMBINE + 'b', 4, 1),  # from 'b' -> e+marks at 1
+    # Prepend + char is one cluster (GB9b)
+    (PREPEND_CHAR + 'a', 2, 0),  # whole cluster
+    # Prepend + Control: control breaks (GB4)
+    (PREPEND_CHAR + '\n', 2, 1),  # '\n' separate at 1
+    # C1 control (NEL, 0x85) stops backward scan in _find_cluster_start (GB4)
+    ('X\x85\u0301', 3, 2),
+])
+def test_grapheme_boundary_before_basic(text, pos, expected):
+    """Basic grapheme_boundary_before tests."""
+    assert grapheme_boundary_before(text, pos) == expected
+
+
+@pytest.mark.skipif(NARROW_ONLY, reason="requires wide Unicode")
+@pytest.mark.parametrize(("text", "pos", "expected"), [
+    # 'Hi 👋🏻!': 0=H,1=i,2=space,3=wave,4=skin,5=!; wave+skin is one cluster
+    ('Hi \U0001F44B\U0001F3FB!', 6, 5),  # from end -> '!' at 5
+    ('Hi \U0001F44B\U0001F3FB!', 5, 3),  # from '!' -> wave+skin at 3
+    ('Hi \U0001F44B\U0001F3FB!', 3, 2),  # from wave -> space at 2
+    # 'a🇺🇸b': 0=a,1-2=flag,3=b; flag is one cluster (GB12/13)
+    ('a' + FLAG_US + 'b', 4, 3),  # from end -> 'b' at 3
+    ('a' + FLAG_US + 'b', 3, 1),  # from 'b' -> flag at 1
+    # Three RIs (🇺🇸🇦): flag + solo RI
+    (FLAG_US + RI_A, 3, 2),  # from end -> solo RI at 2
+    (FLAG_US + RI_A, 2, 0),  # from solo -> flag at 0
+    # 'a👨‍👩‍👧b': 0=a,1-5=family,6=b; ZWJ sequence is one cluster (GB11)
+    ('a' + FAMILY + 'b', 7, 6),  # from end -> 'b' at 6
+    ('a' + FAMILY + 'b', 6, 1),  # from 'b' -> family at 1
+])
+def test_grapheme_boundary_before_unicode(text, pos, expected):
+    """grapheme_boundary_before with emoji and wide Unicode."""
+    assert grapheme_boundary_before(text, pos) == expected
+
+
+@pytest.mark.parametrize(("input_str", "expected"), [
+    ('', []),
+    ('abc', ['c', 'b', 'a']),
+    # café with combining mark mixed with CRLF
+    ('cafe\u0301\r\nok', ['k', 'o', '\r\n', 'e\u0301', 'f', 'a', 'c']),
+])
+def test_iter_graphemes_reverse_basic(input_str, expected):
+    """Basic iter_graphemes_reverse tests."""
+    assert list(iter_graphemes_reverse(input_str)) == expected
+
+
+@pytest.mark.skipif(NARROW_ONLY, reason="requires wide Unicode")
+@pytest.mark.parametrize(("input_str", "expected"), [
+    # Multiple emoji types in one string
+    ('cafe\u0301 ' + WAVE_SKIN + ' ' + FLAG_US + '!',
+     ['!', FLAG_US, ' ', WAVE_SKIN, ' ', 'e\u0301', 'f', 'a', 'c']),
+    # Two families
+    (FAMILY + FAMILY, [FAMILY, FAMILY]),
+    # Flag + solo RI + text
+    ('Hi' + FLAG_US + RI_A + '!', ['!', RI_A, FLAG_US, 'i', 'H']),
+])
+def test_iter_graphemes_reverse_unicode(input_str, expected):
+    """iter_graphemes_reverse with wide Unicode."""
+    assert list(iter_graphemes_reverse(input_str)) == expected
+
+
+@pytest.mark.skipif(NARROW_ONLY, reason="requires wide Unicode")
+@pytest.mark.parametrize(("input_str", "expected"), read_grapheme_break_test())
+def test_grapheme_roundtrip_consistency(input_str, expected):
+    """Forward and reverse iteration produce identical boundaries."""
+    forward = list(iter_graphemes(input_str))
+    reverse = list(iter_graphemes_reverse(input_str))[::-1]
+    assert forward == reverse
+
+
+def test_grapheme_boundary_before_edge_cases():
+    """Edge cases for grapheme_boundary_before."""
+    assert grapheme_boundary_before('abc', 0) == 0
+    assert grapheme_boundary_before('abc', 100) == 2  # pos > len clamps
+    assert grapheme_boundary_before('', 0) == 0
+
+
+def test_iter_graphemes_reverse_edge_cases():
+    """Edge cases for iter_graphemes_reverse."""
+    assert list(iter_graphemes_reverse('abcdef', start=2, end=5)) == ['e', 'd', 'c']
+    assert list(iter_graphemes_reverse('abc', start=0, end=100)) == ['c', 'b', 'a']
+    assert not list(iter_graphemes_reverse('abc', start=5))
+    assert not list(iter_graphemes_reverse('abc', start=2, end=2))
+    # PREPEND + char is one grapheme (GB9b), so start=1 yields nothing (won't split)
+    assert not list(iter_graphemes_reverse(PREPEND_CHAR + 'a', start=1))
+    # But start=0 yields the full grapheme
+    assert list(iter_graphemes_reverse(PREPEND_CHAR + 'a', start=0)) == [PREPEND_CHAR + 'a']
+    # Negative start is clamped to 0
+    assert list(iter_graphemes_reverse('abc', start=-5)) == ['c', 'b', 'a']

wcwidth/__init__.py

@@ -26,16 +26,18 @@
                       _wcmatch_version,
                       _wcversion_value)
 from .bisearch import bisearch as _bisearch
-from .grapheme import iter_graphemes  # noqa
+from .grapheme import grapheme_boundary_before  # noqa
+from .grapheme import iter_graphemes, iter_graphemes_reverse
 from .textwrap import SequenceTextWrapper, wrap
 
 # The __all__ attribute defines the items exported from statement,
 # 'from wcwidth import *', but also to say, "This is the public API".
 __all__ = ('wcwidth', 'wcswidth', 'width', 'iter_sequences', 'iter_graphemes',
+           'iter_graphemes_reverse', 'grapheme_boundary_before',
            'ljust', 'rjust', 'center', 'wrap', 'clip', 'strip_sequences',
            'list_versions')
 
 # We also used pkg_resources to load unicode version tables from version.json,
 # generated by bin/update-tables.py, but some environments are unable to
 # import pkg_resources for one reason or another, yikes!
-__version__ = '0.3.5'
+__version__ = '0.4.0'