Documentation
¶
Overview ¶
Package text provides Unicode grapheme and terminal cell text primitives for Nagi.
Segmentation follows Unicode Standard Annex #29 extended grapheme clusters using the committed Unicode data version. Width is an explicit terminal policy. Unicode normalization is not applied, and invalid UTF-8 runs are replaced before text operations.
Index ¶
- Constants
- func ByteAtCell(input string, cellOffset int, profile WidthProfile) (int, bool)
- func CellAtByte(input string, byteOffset int, profile WidthProfile) (int, bool)
- func GraphemeBoundaries(input string) []int
- func GraphemeWidth(input string, profile WidthProfile) int
- func IsGraphemeBoundary(input string, byteOffset int) bool
- func NextGraphemeBoundary(input string, byteOffset int) (int, bool)
- func NormalizeUTF8(input string) string
- func PreviousGraphemeBoundary(input string, byteOffset int) (int, bool)
- func Truncate(input string, maxCells int, profile WidthProfile) string
- func Width(input string, profile WidthProfile) int
- func Wrap(input string, maxCells int, profile WidthProfile) []string
- type Grapheme
- type GraphemeIterator
- type WidthOverride
- type WidthProfile
- type WrappedLine
- type WrappedLines
Constants ¶
const UnicodeVersion = unicodeVersion
UnicodeVersion is the Unicode data version used by segmentation and width calculations
Variables ¶
This section is empty.
Functions ¶
func ByteAtCell ¶
func ByteAtCell(input string, cellOffset int, profile WidthProfile) (int, bool)
ByteAtCell converts an exact terminal cell boundary to the earliest matching byte boundary
The second result is false for positions inside a wide grapheme or beyond the normalized string
func CellAtByte ¶
func CellAtByte(input string, byteOffset int, profile WidthProfile) (int, bool)
CellAtByte converts an exact grapheme byte boundary to its terminal cell position
The second result is false for offsets inside a grapheme or outside the normalized string
func GraphemeBoundaries ¶
GraphemeBoundaries returns all extended grapheme cluster boundaries, including zero and the normalized UTF-8 length
func GraphemeWidth ¶
func GraphemeWidth(input string, profile WidthProfile) int
GraphemeWidth returns the terminal cell width of input
A single grapheme is the intended input. More than one grapheme returns the total width
func IsGraphemeBoundary ¶
IsGraphemeBoundary reports whether byteOffset is an extended grapheme cluster boundary in the normalized input
func NextGraphemeBoundary ¶
NextGraphemeBoundary returns the nearest strict extended grapheme boundary after byteOffset
The offset may be inside a UTF-8 sequence or grapheme. The second result is false at or beyond the normalized string end
func NormalizeUTF8 ¶
NormalizeUTF8 replaces each run of invalid UTF-8 byte sequences with one U+FFFD
func PreviousGraphemeBoundary ¶
PreviousGraphemeBoundary returns the nearest strict extended grapheme boundary before byteOffset
The offset may be inside a UTF-8 sequence or grapheme. The second result is false at zero or outside the normalized string
func Truncate ¶
func Truncate(input string, maxCells int, profile WidthProfile) string
Truncate returns the longest grapheme-aligned prefix within maxCells
func Width ¶
func Width(input string, profile WidthProfile) int
Width returns the total terminal cell width of input
func Wrap ¶
func Wrap(input string, maxCells int, profile WidthProfile) []string
Wrap hard-wraps input without splitting extended grapheme clusters
CR, LF, and CRLF force a line boundary and are omitted. A grapheme wider than maxCells occupies a line by itself, which guarantees progress when maxCells is zero or negative
Types ¶
type Grapheme ¶
type Grapheme struct {
// Text is the cluster text after invalid UTF-8 replacement; Unicode
// normalization is not applied
Text string
// Start is the inclusive UTF-8 byte offset in the normalized input
Start int
// End is the exclusive UTF-8 byte offset in the normalized input
End int
}
Grapheme is one extended grapheme cluster and its UTF-8 byte range
type GraphemeIterator ¶ added in v0.1.1
type GraphemeIterator struct {
// contains filtered or unexported fields
}
GraphemeIterator traverses normalized extended grapheme clusters without materializing a result slice
func IterateGraphemes ¶ added in v0.1.1
func IterateGraphemes(input string) GraphemeIterator
IterateGraphemes returns an allocation-free iterator for valid UTF-8 input
Invalid UTF-8 runs are normalized once when the iterator is created
func (*GraphemeIterator) Next ¶ added in v0.1.1
func (i *GraphemeIterator) Next() (Grapheme, bool)
Next returns the next grapheme and whether one was available
type WidthOverride ¶
WidthOverride can replace the cell width of a complete grapheme
When override is true, cells must be zero, one, or two. Any other value is a programmer error and causes a panic
type WidthProfile ¶
type WidthProfile struct {
// contains filtered or unexported fields
}
WidthProfile is a terminal cell-width policy
func CJKWidth ¶
func CJKWidth() WidthProfile
CJKWidth returns a profile where East Asian Ambiguous characters occupy two cells
func CustomWidth ¶
func CustomWidth(base WidthProfile, override WidthOverride) WidthProfile
CustomWidth layers override over one of the base width profiles
func ModernWidth ¶
func ModernWidth() WidthProfile
ModernWidth returns a profile where East Asian Ambiguous characters occupy one cell
type WrappedLine ¶ added in v0.1.1
type WrappedLine struct {
// Text is the line content without a mandatory line-break grapheme
Text string
// Width is the line width in terminal cells
Width int
}
WrappedLine is one hard-wrapped line and its terminal cell width
type WrappedLines ¶ added in v0.1.1
type WrappedLines struct {
// contains filtered or unexported fields
}
WrappedLines iterates hard-wrapped lines without materializing a result slice
func IterateWrappedLines ¶ added in v0.1.1
func IterateWrappedLines(input string, maxCells int, profile WidthProfile) WrappedLines
IterateWrappedLines returns an iterator using the same rules as Wrap
func (*WrappedLines) Next ¶ added in v0.1.1
func (i *WrappedLines) Next() (WrappedLine, bool)
Next returns the next wrapped line and whether one was available
Source Files