README.md

@@ -3,13 +3,13 @@
 [![Go Reference](https://pkg.go.dev/badge/github.com/rivo/uniseg.svg)](https://pkg.go.dev/github.com/rivo/uniseg)
 [![Go Report](https://img.shields.io/badge/go%20report-A%2B-brightgreen.svg)](https://goreportcard.com/report/github.com/rivo/uniseg)
 
-This Go package implements Unicode Text Segmentation according to [Unicode Standard Annex #29](https://unicode.org/reports/tr29/) and Unicode Line Breaking according to [Unicode Standard Annex #14](https://unicode.org/reports/tr14/) (Unicode version 14.0.0).
+This Go package implements Unicode Text Segmentation according to [Unicode Standard Annex #29](https://unicode.org/reports/tr29/), Unicode Line Breaking according to [Unicode Standard Annex #14](https://unicode.org/reports/tr14/) (Unicode version 15.0.0), and monospace font string width calculation similar to [wcwidth](https://man7.org/linux/man-pages/man3/wcwidth.3.html).
 
 ## Background
 
 ### Grapheme Clusters
 
-In Go, [strings are read-only slices of bytes](https://blog.golang.org/strings). They can be turned into Unicode code points using the `for` loop or by casting: `[]rune(str)`. However, multiple code points may be combined into one user-perceived character or what the Unicode specification calls "grapheme cluster". Here are some examples:
+In Go, [strings are read-only slices of bytes](https://go.dev/blog/strings). They can be turned into Unicode code points using the `for` loop or by casting: `[]rune(str)`. However, multiple code points may be combined into one user-perceived character or what the Unicode specification calls "grapheme cluster". Here are some examples:
 
 |String|Bytes (UTF-8)|Code points (runes)|Grapheme clusters|
 |-|-|-|-|
@@ -31,6 +31,10 @@ Sentence boundaries are often used for triple-click or some other method of sele
 
 Line breaking, also known as word wrapping, is the process of breaking a section of text into lines such that it will fit in the available width of a page, window or other display area. This package provides tools to determine where a string may or may not be broken and where it must be broken (for example after newline characters).
 
+### Monospace Width
+
+Most terminals or text displays / text editors using a monospace font (for example source code editors) use a fixed width for each character. Some characters such as emojis or characters found in Asian and other languages may take up more than one character cell. This package provides tools to determine the number of cells a string will take up when displayed in a monospace font. See [here](https://pkg.go.dev/github.com/rivo/uniseg#hdr-Monospace_Width) for more information.
+
 ## Installation
 
 ```bash
@@ -47,6 +51,14 @@ fmt.Println(n)
 // 2
 ```
 
+### Calculating the Monospace String Width
+
+```go
+width := uniseg.StringWidth("🇩🇪🏳️‍🌈!")
+fmt.Println(width)
+// 5
+```
+
 ### Using the [`Graphemes`](https://pkg.go.dev/github.com/rivo/uniseg#Graphemes) Class
 
 This is the most convenient method of iterating over grapheme clusters:
@@ -61,7 +73,7 @@ for gr.Next() {
 
 ### Using the [`Step`](https://pkg.go.dev/github.com/rivo/uniseg#Step) or [`StepString`](https://pkg.go.dev/github.com/rivo/uniseg#StepString) Function
 
-This is orders of magnitude faster than the `Graphemes` class, but it requires the handling of states and boundaries:
+This avoids allocating a new `Graphemes` object but it requires the handling of states and boundaries:
 
 ```go
 str := "🇩🇪🏳️‍🌈"
@@ -76,29 +88,7 @@ for len(str) > 0 {
 
 ### Advanced Examples
 
-Breaking into grapheme clusters and evaluating line breaks:
-
-```go
-str := "First line.\nSecond line."
-state := -1
-var (
-	c          string
-	boundaries int
-)
-for len(str) > 0 {
-	c, str, boundaries, state = uniseg.StepString(str, state)
-	fmt.Print(c)
-	if boundaries&uniseg.MaskLine == uniseg.LineCanBreak {
-		fmt.Print("|")
-	} else if boundaries&uniseg.MaskLine == uniseg.LineMustBreak {
-		fmt.Print("‖")
-	}
-}
-// First |line.
-// ‖Second |line.‖
-```
-
-If you're only interested in word segmentation, use [`FirstWord`](https://pkg.go.dev/github.com/rivo/uniseg#FirstWord) or [`FirstWordInString`](https://pkg.go.dev/github.com/rivo/uniseg#FirstWordInString):
+The [`Graphemes`](https://pkg.go.dev/github.com/rivo/uniseg#Graphemes) class offers the most convenient way to access all functionality of this package. But in some cases, it may be better to use the specialized functions directly. For example, if you're only interested in word segmentation, use [`FirstWord`](https://pkg.go.dev/github.com/rivo/uniseg#FirstWord) or [`FirstWordInString`](https://pkg.go.dev/github.com/rivo/uniseg#FirstWordInString):
 
 ```go
 str := "Hello, world!"
@@ -121,6 +111,15 @@ Similarly, use
 - [`FirstSentence`](https://pkg.go.dev/github.com/rivo/uniseg#FirstSentence) or [`FirstSentenceInString`](https://pkg.go.dev/github.com/rivo/uniseg#FirstSentenceInString) for sentence segmentation only, and
 - [`FirstLineSegment`](https://pkg.go.dev/github.com/rivo/uniseg#FirstLineSegment) or [`FirstLineSegmentInString`](https://pkg.go.dev/github.com/rivo/uniseg#FirstLineSegmentInString) for line breaking / word wrapping (although using [`Step`](https://pkg.go.dev/github.com/rivo/uniseg#Step) or [`StepString`](https://pkg.go.dev/github.com/rivo/uniseg#StepString) is preferred as it will observe grapheme cluster boundaries).
 
+If you're only interested in the width of characters, use [`FirstGraphemeCluster`](https://pkg.go.dev/github.com/rivo/uniseg#FirstGraphemeCluster) or [`FirstGraphemeClusterInString`](https://pkg.go.dev/github.com/rivo/uniseg#FirstGraphemeClusterInString). It is much faster than using [`Step`](https://pkg.go.dev/github.com/rivo/uniseg#Step), [`StepString`](https://pkg.go.dev/github.com/rivo/uniseg#StepString), or the [`Graphemes`](https://pkg.go.dev/github.com/rivo/uniseg#Graphemes) class because it does not include the logic for word / sentence / line boundaries.
+
+Finally, if you need to reverse a string while preserving grapheme clusters, use [`ReverseString`](https://pkg.go.dev/github.com/rivo/uniseg#ReverseString):
+
+```go
+fmt.Println(uniseg.ReverseString("🇩🇪🏳️‍🌈"))
+// 🏳️‍🌈🇩🇪
+```
+
 ## Documentation
 
 Refer to https://pkg.go.dev/github.com/rivo/uniseg for the package's documentation.

doc.go

@@ -1,8 +1,9 @@
 /*
-Package uniseg implements Unicode Text Segmentation and Unicode Line Breaking.
-Unicode Text Segmentation conforms to Unicode Standard Annex #29
-(https://unicode.org/reports/tr29/) and Unicode Line Breaking conforms to
-Unicode Standard Annex #14 (https://unicode.org/reports/tr14/).
+Package uniseg implements Unicode Text Segmentation, Unicode Line Breaking, and
+string width calculation for monospace fonts. Unicode Text Segmentation conforms
+to Unicode Standard Annex #29 (https://unicode.org/reports/tr29/) and Unicode
+Line Breaking conforms to Unicode Standard Annex #14
+(https://unicode.org/reports/tr14/).
 
 In short, using this package, you can split a string into grapheme clusters
 (what people would usually refer to as a "character"), into words, and into
@@ -12,42 +13,97 @@ as emojis, combining characters, or characters from Asian, Arabic, Hebrew, or
 other languages. Additionally, you can use it to implement line breaking (or
 "word wrapping"), that is, to determine where text can be broken over to the
 next line when the width of the line is not big enough to fit the entire text.
+Finally, you can use it to calculate the display width of a string for monospace
+fonts.
 
-Grapheme Clusters
+# Getting Started
+
+If you just want to count the number of characters in a string, you can use
+[GraphemeClusterCount]. If you want to determine the display width of a string,
+you can use [StringWidth]. If you want to iterate over a string, you can use
+[Step], [StepString], or the [Graphemes] class (more convenient but less
+performant). This will provide you with all information: grapheme clusters,
+word boundaries, sentence boundaries, line breaks, and monospace character
+widths. The specialized functions [FirstGraphemeCluster],
+[FirstGraphemeClusterInString], [FirstWord], [FirstWordInString],
+[FirstSentence], and [FirstSentenceInString] can be used if only one type of
+information is needed.
+
+# Grapheme Clusters
 
 Consider the rainbow flag emoji: 🏳️‍🌈. On most modern systems, it appears as one
 character. But its string representation actually has 14 bytes, so counting
 bytes (or using len("🏳️‍🌈")) will not work as expected. Counting runes won't,
 either: The flag has 4 Unicode code points, thus 4 runes. The stdlib function
 utf8.RuneCountInString("🏳️‍🌈") and len([]rune("🏳️‍🌈")) will both return 4.
 
-The uniseg.GraphemeClusterCount(str) function will return 1 for the rainbow flag
-emoji. The Graphemes class and a variety of functions in this package will allow
-you to split strings into its grapheme clusters.
+The [GraphemeClusterCount] function will return 1 for the rainbow flag emoji.
+The Graphemes class and a variety of functions in this package will allow you to
+split strings into its grapheme clusters.
 
-Word Boundaries
+# Word Boundaries
 
 Word boundaries are used in a number of different contexts. The most familiar
 ones are selection (double-click mouse selection), cursor movement ("move to
 next word" control-arrow keys), and the dialog option "Whole Word Search" for
 search and replace. This package provides methods for determining word
 boundaries.
 
-Sentence Boundaries
+# Sentence Boundaries
 
 Sentence boundaries are often used for triple-click or some other method of
 selecting or iterating through blocks of text that are larger than single words.
 They are also used to determine whether words occur within the same sentence in
 database queries. This package provides methods for determining sentence
 boundaries.
 
-Line Breaking
+# Line Breaking
 
 Line breaking, also known as word wrapping, is the process of breaking a section
 of text into lines such that it will fit in the available width of a page,
 window or other display area. This package provides methods to determine the
 positions in a string where a line must be broken, may be broken, or must not be
 broken.
 
+# Monospace Width
+
+Monospace width, as referred to in this package, is the width of a string in a
+monospace font. This is commonly used in terminal user interfaces or text
+displays or editors that don't support proportional fonts. A width of 1
+corresponds to a single character cell. The populear C function [wcswidth()] and
+its implementation in other programming languages is in widespread use for the
+same purpose. However, there is no standard for the calculation of such widths,
+and this package differs from wcswidth() in a number of ways, presumably to
+generate more visually pleasing results.
+
+To start, we assume that every code point has a width of 1, with the following
+exceptions:
+
+  - Code points with grapheme cluster break properties Control, CR, LF, Extend,
+    and ZWJ have a width of 0.
+  - U+2E3A, Two-Em Dash, has a width of 3.
+  - U+2E3B, Three-Em Dash, has a width of 4.
+  - Characters with the East-Asian Width properties "Fullwidth" (F) and "Wide"
+    (W) have a width of 2. "Ambiguous" (A) can be configured with
+    [EastAsianAmbiguousWidth], with a default of 1. ("Neutral" (N) always has a
+    width of 1.)
+  - Code points with grapheme cluster break property Regional Indicator have a
+    width of 2.
+  - Code points with grapheme cluster break property Extended Pictographic have
+    a width of 2, unless their Emoji Presentation flag is "No", in which case
+    the width is 1.
+
+For Hangul grapheme clusters composed of conjoining Jamo and for Regional
+Indicators (flags), all code points except the first one have a width of 0. For
+grapheme clusters starting with an Extended Pictographic, any additional code
+point will force a total width of 2, except if the Variation Selector-15
+(U+FE0E) is included, in which case the total width is always 1. Grapheme
+clusters ending with Variation Selector-16 (U+FE0F) have a width of 2.
+
+Note that whether these widths appear correct depends on your application's
+render engine, to which extent it conforms to the Unicode Standard, and its
+choice of font.
+
+[wcswidth()]: https://man7.org/linux/man-pages/man3/wcswidth.3.html
 */
 package uniseg