git.iko.soy/streamly
on 0ae75fb help sign in
streamly/src/Streamly/String.hs
165 lines 5.3 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.
88decodeChar8 :: (IsStream t, Monad m) => t m Word8 -> t m Char
89decodeChar8 = S.map (unsafeChr . fromIntegral)
91-- | Encode a stream of Unicode characters to bytes by mapping each character
92-- to a byte in 0-255 range. Throws an error if the input stream contains
93-- characters beyond 255.
94encodeChar8 :: (IsStream t, Monad m) => t m Char -> t m Word8
95encodeChar8 = S.map convert
96 where
97 convert c =
98 let codepoint = ord c
99 in if codepoint > 255
100 then error $ "Streamly.String.encodeChar8 invalid \
101 \input char codepoint " ++ show codepoint
102 else fromIntegral codepoint
104-- | Like 'encodeChar8' but silently truncates and maps input characters beyond
105-- 255 to (incorrect) chars in 0-255 range. No error or exception is thrown
106-- when such truncation occurs.
107encodeChar8Unchecked :: (IsStream t, Monad m) => t m Char -> t m Word8
108encodeChar8Unchecked = S.map (fromIntegral . ord)
110{-
111-- | Decode a UTF-8 encoded bytestream to a stream of Unicode characters.
112decodeUtf8 :: IsStream t => t m Word8 -> t m Char
113decodeUtf8 = undefined
115-- | Encode a stream of Unicode characters to a UTF-8 encoded bytestream.
116encodeUtf8 :: IsStream t => t m Char -> t m Word8
117encodeUtf8 = undefined
119-------------------------------------------------------------------------------
120-- Unicode aware operations on strings
121-------------------------------------------------------------------------------
123toCaseFold :: IsStream t => t m Char -> t m Char
124toCaseFold = undefined
126toLower :: IsStream t => t m Char -> t m Char
127toLower = undefined
129toUpper :: IsStream t => t m Char -> t m Char
130toUpper = undefined
132toTitle :: IsStream t => t m Char -> t m Char
133toTitle = undefined
135-------------------------------------------------------------------------------
136-- Utility operations on strings
137-------------------------------------------------------------------------------
139strip :: IsStream t => t m Char -> t m Char
140strip = undefined
142stripStart :: IsStream t => t m Char -> t m Char
143stripStart = undefined
145stripEnd :: IsStream t => t m Char -> t m Char
146stripEnd = undefined
148foldLines :: IsStream t => t m Char -> Fold m Char b -> t m b
149foldLines = undefined
151foldWords :: IsStream t => t m Char -> Fold m Char b -> t m b
152foldWords = undefined
154lines :: IsStream t => t m Char -> t m (Array Char)
155lines = undefined
157words :: IsStream t => t m Char -> t m (Array Char)
158words = undefined
160unlines :: IsStream t => t m (Array Char) -> t m Char
161unlines = undefined
163unwords :: IsStream t => t m (Array Char) -> t m Char
164unwords = undefined
165-}