Be more precise about meaning of "character"
authorBen Gamari <ben@smart-cactus.org>
Mon, 9 Oct 2017 21:11:20 +0000 (17:11 -0400)
committerBen Gamari <ben@smart-cactus.org>
Mon, 9 Oct 2017 21:34:04 +0000 (17:34 -0400)
Data/Text.hs
Data/Text/Internal/Fusion/Types.hs

index d217b11..77694f6 100644 (file)
@@ -34,6 +34,7 @@
 -- with Unicode text (including normalization, regular expressions,
 -- non-standard encodings, text breaking, and locales), see
 -- <http://hackage.haskell.org/package/text-icu the text-icu package >.
+--
 
 module Data.Text
     (
@@ -43,6 +44,9 @@ module Data.Text
     -- * Acceptable data
     -- $replacement
 
+    -- * Definition of character
+    -- $character_definition
+
     -- * Fusion
     -- $fusion
 
@@ -247,6 +251,17 @@ import qualified GHC.Exts as Exts
 import Text.Printf (PrintfArg, formatArg, formatString)
 #endif
 
+-- $character-definition
+--
+-- This package uses the word /character/ to denote Unicode code points.
+--
+-- Note that this is not the same thing as a grapheme (e.g. a composition of
+-- code points that form one visual symbol). For instance, consider the grapheme
+-- @รค@. This symbol has two Unicode representations: a single code-point
+-- representation @U+00E4@ (the @LATIN SMALL LETTER A WITH DIAERESIS@ code
+-- point), and a two code point representation @U+0061@ (the @A@ code point) and
+-- @U+0308@ (the @COMBINING DIAERESIS@ code point).
+
 -- $strict
 --
 -- This package provides both strict and lazy 'Text' types.  The
index 54a64dd..d181ea2 100644 (file)
@@ -75,16 +75,16 @@ instance (Ord a) => Ord (Stream a) where
 -- unstreaming functions must be able to cope with the hint being too
 -- small or too large.
 --
--- The size hint tries to track the UTF-16 code points in a stream,
--- but often counts the number of characters instead.  It can easily
+-- The size hint tries to track the UTF-16 code units in a stream,
+-- but often counts the number of code points instead.  It can easily
 -- undercount if, for instance, a transformed stream contains astral
--- plane characters (those above 0x10000).
+-- plane code points (those above 0x10000).
 
 data Stream a =
     forall s. Stream
     (s -> Step s a)             -- stepper function
     !s                          -- current state
-    !Size                       -- size hint
+    !Size                       -- size hint in code units
 
 -- | /O(n)/ Determines if two streams are equal.
 eq :: (Eq a) => Stream a -> Stream a -> Bool