@@ -253,6 +253,8 @@ unpack :: Text -> String
253unpack t = S.unstreamList (stream t)
253unpack t = S.unstreamList (stream t)
254{-# INLINE [1] unpack #-}
254{-# INLINE [1] unpack #-}
256+-- | /O(1)/ Convert a character into a Text.
257+-- Subject to fusion.
256singleton :: Char -> Text
258singleton :: Char -> Text
257singleton c = Chunk (T.singleton c) Empty
259singleton c = Chunk (T.singleton c) Empty
258{-# INLINE [1] singleton #-}
260{-# INLINE [1] singleton #-}
@@ -272,14 +274,22 @@ fromChunks cs = L.foldr chunk Empty cs
272toChunks :: Text -> [T.Text]
274toChunks :: Text -> [T.Text]
273toChunks cs = foldrChunks (:) [] cs
275toChunks cs = foldrChunks (:) [] cs
277+-- | /O(n)/ Convert a lazy 'Text' into a strict 'T.Text'.
275toStrict :: Text -> T.Text
278toStrict :: Text -> T.Text
276toStrict t = T.concat (toChunks t)
279toStrict t = T.concat (toChunks t)
277{-# INLINE [1] toStrict #-}
280{-# INLINE [1] toStrict #-}
282+-- | /O(c)/ Convert a strict 'T.Text' into a lazy 'Text'.
279fromStrict :: T.Text -> Text
283fromStrict :: T.Text -> Text
280fromStrict t = chunk t Empty
284fromStrict t = chunk t Empty
281{-# INLINE [1] fromStrict #-}
285{-# INLINE [1] fromStrict #-}
287+-- -----------------------------------------------------------------------------
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.
283cons :: Char -> Text -> Text
293cons :: Char -> Text -> Text
284cons c t = Chunk (T.singleton c) t
294cons c t = Chunk (T.singleton c) t
285{-# INLINE [1] cons #-}
295{-# INLINE [1] cons #-}
@@ -291,6 +301,8 @@ cons c t = Chunk (T.singleton c) t
291 unstream (S.cons c (stream t)) = cons c t
301 unstream (S.cons c (stream t)) = cons c t
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.
294snoc :: Text -> Char -> Text
306snoc :: Text -> Char -> Text
295snoc t c = foldrChunks Chunk (singleton c) t
307snoc t c = foldrChunks Chunk (singleton c) t
296{-# INLINE [1] snoc #-}
308{-# INLINE [1] snoc #-}
@@ -396,6 +408,8 @@ last (Chunk t ts) = go t ts
396 S.last (stream t) = last t
408 S.last (stream t) = last t
411+-- | /O(n)/ Returns the number of characters in a 'Text'.
412+-- Subject to fusion.
399length :: Text -> Int64
413length :: Text -> Int64
400length = foldlChunks go 0
414length = foldlChunks go 0
401 where go l t = l + fromIntegral (T.length t)
415 where go l t = l + fromIntegral (T.length t)