git.iko.soy/streamly
on cfd77bd help sign in
streamly/src/Streamly/String.hs
168 lines 5.4 kB history raw
1-- |
2-- Module : Streamly.String
3-- Copyright : (c) 2018 Composewell Technologies
4--
5-- License : BSD3
6-- Maintainer : harendra.kumar@gmail.com
7-- Stability : experimental
8-- Portability : GHC
9--
10-- Stream of 'Char' are the equivalent of Haskell Strings but without any
11-- performance issues that are usually associated with the 'String' type.
12-- Haskell lists are not suitable for storage in GC memory. We use streams for
13-- processing and arrays for storing. We can use the usual stream processing
14-- routines on these 'Char' streams. Stream processing is very efficient due to
15-- stream fusion. If strings are to be stored or buffered in memory, they can
16-- be encoded to 'Word8' arrays using the encoding routines provided in the
17-- module. Therefore, a separate type for text representation is not required.
19-- The 'String' type in this module is just a synonym for the type @List Char@.
20-- It provides better performance compared to the standard Haskell @String@
21-- type and can be used almost as a drop-in replacement, especially when used
22-- with @OverloadedStrings@ extension, with little differences.
23--
24-- See "Streamly.List", <src/docs/streamly-vs-lists.md> for more details and
25-- <src/test/PureStreams.hs> for comprehensive usage examples.
27-- TBD write a note on performance comparison with text, bytestrings, lists and
28-- vector.
29--
30module Streamly.String
31 (
32 -- String
34 -- * Encoding and Decoding
35 encodeChar8
36 , encodeChar8Unchecked
37 , decodeChar8
38{-
39 , encodeUtf8
40 , decodeUtf8
42 -- * Unicode aware operations
43 , toCaseFold
44 , toLower
45 , toUpper
46 , toTitle
48 -- * Operations on character strings
49 , strip -- (dropAround isSpace)
50 , stripStart
51 , stripEnd
52 , foldLines
53 , foldWords
54 , lines
55 , words
56 , unlines
57 , unwords
58-}
59 )
60where
62import Data.Char (ord)
63import Data.Word (Word8)
64import GHC.Base (unsafeChr)
65import Streamly (IsStream)
66-- import Streamly.List (List)
67import Prelude hiding (String, lines, words, unlines, unwords)
68-- import Streamly.Fold (Fold)
69-- import Streamly.Array (Array)
71import qualified Streamly.Prelude as S
73-- type String = List Char
75-------------------------------------------------------------------------------
76-- Encoding/Decoding Characters
77-------------------------------------------------------------------------------
79-- decodeWith :: TextEncoding -> t m Word8 -> t m Char
80-- decodeWith = undefined
82-------------------------------------------------------------------------------
83-- Encoding/Decoding Unicode Characters
84-------------------------------------------------------------------------------
86-- | Decode a stream of bytes to Unicode characters by mapping each byte to a
87-- corresponding Unicode 'Char' in 0-255 range.
88{-# INLINE decodeChar8 #-}
89decodeChar8 :: (IsStream t, Monad m) => t m Word8 -> t m Char
90decodeChar8 = S.map (unsafeChr . fromIntegral)
92-- | Encode a stream of Unicode characters to bytes by mapping each character
93-- to a byte in 0-255 range. Throws an error if the input stream contains
94-- characters beyond 255.
95{-# INLINE encodeChar8 #-}
96encodeChar8 :: (IsStream t, Monad m) => t m Char -> t m Word8
97encodeChar8 = S.map convert
98 where
99 convert c =
100 let codepoint = ord c
101 in if codepoint > 255
102 then error $ "Streamly.String.encodeChar8 invalid \
103 \input char codepoint " ++ show codepoint
104 else fromIntegral codepoint
106-- | Like 'encodeChar8' but silently truncates and maps input characters beyond
107-- 255 to (incorrect) chars in 0-255 range. No error or exception is thrown
108-- when such truncation occurs.
109{-# INLINE encodeChar8Unchecked #-}
110encodeChar8Unchecked :: (IsStream t, Monad m) => t m Char -> t m Word8
111encodeChar8Unchecked = S.map (fromIntegral . ord)
113{-
114-- | Decode a UTF-8 encoded bytestream to a stream of Unicode characters.
115decodeUtf8 :: IsStream t => t m Word8 -> t m Char
116decodeUtf8 = undefined
118-- | Encode a stream of Unicode characters to a UTF-8 encoded bytestream.
119encodeUtf8 :: IsStream t => t m Char -> t m Word8
120encodeUtf8 = undefined
122-------------------------------------------------------------------------------
123-- Unicode aware operations on strings
124-------------------------------------------------------------------------------
126toCaseFold :: IsStream t => t m Char -> t m Char
127toCaseFold = undefined
129toLower :: IsStream t => t m Char -> t m Char
130toLower = undefined
132toUpper :: IsStream t => t m Char -> t m Char
133toUpper = undefined
135toTitle :: IsStream t => t m Char -> t m Char
136toTitle = undefined
138-------------------------------------------------------------------------------
139-- Utility operations on strings
140-------------------------------------------------------------------------------
142strip :: IsStream t => t m Char -> t m Char
143strip = undefined
145stripStart :: IsStream t => t m Char -> t m Char
146stripStart = undefined
148stripEnd :: IsStream t => t m Char -> t m Char
149stripEnd = undefined
151foldLines :: IsStream t => t m Char -> Fold m Char b -> t m b
152foldLines = undefined
154foldWords :: IsStream t => t m Char -> Fold m Char b -> t m b
155foldWords = undefined
157lines :: IsStream t => t m Char -> t m (Array Char)
158lines = undefined
160words :: IsStream t => t m Char -> t m (Array Char)
161words = undefined
163unlines :: IsStream t => t m (Array Char) -> t m Char
164unlines = undefined
166unwords :: IsStream t => t m (Array Char) -> t m Char
167unwords = undefined
168-}