@@ -253,6 +253,8 @@ unpack :: Text -> String
253253unpack t = S.unstreamList (stream t)
254254{-# INLINE [1] unpack #-}
255255
256+-- | /O(1)/ Convert a character into a Text.
257+-- Subject to fusion.
256258singleton :: Char -> Text
257259singleton c = Chunk (T.singleton c) Empty
258260{-# INLINE [1] singleton #-}
@@ -272,14 +274,22 @@ fromChunks cs = L.foldr chunk Empty cs
272274toChunks :: Text -> [T.Text]
273275toChunks cs = foldrChunks (:) [] cs
274276
277+-- | /O(n)/ Convert a lazy 'Text' into a strict 'T.Text'.
275278toStrict :: Text -> T.Text
276279toStrict t = T.concat (toChunks t)
277280{-# INLINE [1] toStrict #-}
278281
282+-- | /O(c)/ Convert a strict 'T.Text' into a lazy 'Text'.
279283fromStrict :: T.Text -> Text
280284fromStrict t = chunk t Empty
281285{-# INLINE [1] fromStrict #-}
282286
287+-- -----------------------------------------------------------------------------
288+-- * Basic functions
289+
290+-- | /O(n)/ Adds a character to the front of a 'Text'. This function
291+-- is more costly than its 'List' counterpart because it requires
292+-- copying a new array. Subject to fusion.
283293cons :: Char -> Text -> Text
284294cons c t = Chunk (T.singleton c) t
285295{-# INLINE [1] cons #-}
@@ -291,6 +301,8 @@ cons c t = Chunk (T.singleton c) t
291301 unstream (S.cons c (stream t)) = cons c t
292302 #-}
293303
304+-- | /O(n)/ Adds a character to the end of a 'Text'. This copies the
305+-- entire array in the process, unless fused. Subject to fusion.
294306snoc :: Text -> Char -> Text
295307snoc t c = foldrChunks Chunk (singleton c) t
296308{-# INLINE [1] snoc #-}
@@ -396,6 +408,8 @@ last (Chunk t ts) = go t ts
396408 S.last (stream t) = last t
397409 #-}
398410
411+-- | /O(n)/ Returns the number of characters in a 'Text'.
412+-- Subject to fusion.
399413length :: Text -> Int64
400414length = foldlChunks go 0
401415 where go l t = l + fromIntegral (T.length t)