starwing / luautf8 / 19302506971

99%

Build Type

push

github

Committed by starwing

Commit Message

feat!: add widthlimit API and modernize width functions (v0.2.0)

BREAKING CHANGES:
- `utf8.width()` and `utf8.widthindex()` now use integer `ambiwidth`
  parameter instead of boolean `ambi_is_double`
- New optional byte range parameters `i, j` added before `ambiwidth`

New Features:
- Add `utf8.widthlimit(s, i, j[, limit[, ambiwidth[, default]]])`
  - Unified function for width measurement and truncation
  - Positive limit: truncate from front (keep prefix)
  - Negative limit: truncate from back (keep suffix)
  - Omit limit: measure display width of byte range [i, j]
  - Returns: (pos, remain) where pos is truncation point or j if measuring
- Add `utf8.version` constant (set to "0.2.0")

API Changes:
- `utf8.width(s[, i[, j[, ambiwidth[, default]]]])`
  - Old: `utf8.width(s[, ambi_is_double[, default]])`
  - New: `ambi_is_double` (boolean) → `ambiwidth` (integer 1 or 2)
  - New: Optional byte range parameters `i, j` for substring width

- `utf8.widthindex(s, width[, i[, j[, ambiwidth[, default]]]])`
  - Same parameter changes as `utf8.width()`

Documentation:
- Rewrite all API docs in Lua official manual style
- Add comprehensive examples for all functions
- Add migration guide in Breaking Changes section
- Unify parameter naming: `s` (string), `i`/`j` (byte positions),
  `n` (character index)
- Fix grammar and formatting issues throughout README

Tests:
- Add comprehensive test coverage for `utf8.widthlimit()`
  - Basic truncation (positive/negative limits)
  - Fullwidth characters, mixed width strings
  - Substring ranges, ambiguous-width characters
  - Edge cases (empty strings, zero limit, out of bounds)
- Update existing tests for new API signatures

Migration Guide:
- `ambi_is_double = true` → `ambiwidth = 2`
- `ambi_is_double = false/nil` → `ambiwidth = 1` or omit
- Most users unaffected (only passing string parameter)

Version: 0.2.0

Run Details

85 of 87 new or added lines in 1 file covered. (97.7%)

5 existing lines in 1 file now uncovered.

1118 of 1129 relevant lines covered (99.03%)

671848.07 hits per line