[project @ 2003-02-17 15:13:56 by simonpj]

[ghc-base.git] / Data / PackedString.hs

diff --git a/Data/PackedString.hs b/Data/PackedString.hs
index d2998bd..f82b756 100644 (file)
--- a/Data/PackedString.hs
+++ b/Data/PackedString.hs
@@ -8,23 +8,28 @@
 -- Stability   :  experimental
 -- Portability :  portable
 --
--- The PackedString type, and associated operations.
+-- An efficient implementation of strings.
 --
+-----------------------------------------------------------------------------
+
 -- Original GHC implementation by Bryan O\'Sullivan, 
 -- rewritten to use UArray by Simon Marlow.
---
------------------------------------------------------------------------------
 
 module Data.PackedString (
+       -- * The @PackedString@ type
         PackedString,      -- abstract, instances: Eq, Ord, Show, Typeable
 
-         -- Creating the beasts
-       packString,  -- :: [Char] -> PackedString
-       unpackPS,    -- :: PackedString -> [Char]
+         -- * Converting to and from @PackedString@s
+       packString,  -- :: String -> PackedString
+       unpackPS,    -- :: PackedString -> String
 
+#ifndef __NHC__
+       -- * I\/O with @PackedString@s  
        hPutPS,      -- :: Handle -> PackedString -> IO ()
        hGetPS,      -- :: Handle -> Int -> IO PackedString
+#endif
 
+       -- * List-like manipulation functions
        nilPS,       -- :: PackedString
        consPS,      -- :: Char -> PackedString -> PackedString
        headPS,      -- :: PackedString -> Char
@@ -61,6 +66,8 @@ module Data.PackedString (
 
 import Prelude
 
+#ifndef __NHC__
+
 import Data.Array.Unboxed
 import Data.Array.IO
 import Data.Dynamic
@@ -71,6 +78,8 @@ import System.IO
 -- -----------------------------------------------------------------------------
 -- PackedString type declaration
 
+-- | A space-efficient representation of a 'String', which supports various
+-- efficient operations.  A 'PackedString' contains full Unicode 'Char's.
 newtype PackedString = PS (UArray Int Char)
 
 instance Eq PackedString where
@@ -96,7 +105,8 @@ nilPS = PS (array (0,-1) [])
 consPS :: Char -> PackedString -> PackedString
 consPS c cs = packString (c : (unpackPS cs)) -- ToDo:better
 
-packString :: [Char] -> PackedString
+-- | Convert a 'String' into a 'PackedString'
+packString :: String -> PackedString
 packString str = packNChars (length str) str
 
 packNChars :: Int -> [Char] -> PackedString
@@ -105,7 +115,8 @@ packNChars len str = PS (array (0,len-1) (zip [0..] str))
 -- -----------------------------------------------------------------------------
 -- Destructor functions (taking PackedStrings apart)
 
-unpackPS :: PackedString -> [Char]
+-- | Convert a 'PackedString' into a 'String'
+unpackPS :: PackedString -> String
 unpackPS (PS ps) = elems ps
 
 -- -----------------------------------------------------------------------------
@@ -237,7 +248,7 @@ splitWithPS pred (PS ps) =
          : splitify (break_pt + 1)
 
 first_pos_that_satisfies pred ps len n = 
-   case [ m | m <- [n..len], pred (ps ! m) ] of
+   case [ m | m <- [n..len-1], pred (ps ! m) ] of
        []    -> len
        (m:_) -> m
 
@@ -253,6 +264,11 @@ substrPS (PS ps) begin end = packString [ ps ! i | i <- [begin..end] ]
 -- -----------------------------------------------------------------------------
 -- hPutPS
 
+-- | Outputs a 'PackedString' to the specified 'Handle'.  
+--
+-- NOTE: the representation of the 'PackedString' in the file is assumed to
+-- be in the ISO-8859-1 encoding.  In other words, only the least signficant
+-- byte is taken from each character in the 'PackedString'.
 hPutPS :: Handle -> PackedString -> IO ()
 hPutPS h (PS ps) = do
   let l = lengthPS (PS ps)
@@ -263,9 +279,87 @@ hPutPS h (PS ps) = do
 -- -----------------------------------------------------------------------------
 -- hGetPS
 
+-- | Read a 'PackedString' directly from the specified 'Handle'.  This
+-- is far more efficient than reading the characters into a 'String'
+-- and then using 'packString'.  
+--
+-- NOTE: as with 'hPutPS', the string representation in the file is 
+-- assumed to be ISO-8859-1.
 hGetPS :: Handle -> Int -> IO PackedString
 hGetPS h i = do
   arr <- newArray_ (0, i-1)
   l <- hGetArray h arr i
   chars <- mapM (\i -> readArray arr i >>= return.chr.fromIntegral) [0..l-1]
   return (packString chars)
+
+#else  /* __NHC__ */
+
+--import Prelude hiding (append, break, concat, cons, drop, dropWhile,
+--                       filter, foldl, foldr, head, length, lines, map,
+--                       nil, null, reverse, span, splitAt, subst, tail,
+--                       take, takeWhile, unlines, unwords, words)
+-- also hiding: Ix(..), Functor(..)
+import NHC.PackedString
+
+
+nilPS       :: PackedString
+consPS      :: Char -> PackedString -> PackedString
+headPS      :: PackedString -> Char
+tailPS      :: PackedString -> PackedString
+nullPS      :: PackedString -> Bool
+appendPS    :: PackedString -> PackedString -> PackedString
+lengthPS    :: PackedString -> Int
+indexPS     :: PackedString -> Int -> Char
+mapPS       :: (Char -> Char) -> PackedString -> PackedString
+filterPS    :: (Char -> Bool) -> PackedString -> PackedString
+reversePS   :: PackedString -> PackedString
+concatPS    :: [PackedString] -> PackedString
+elemPS      :: Char -> PackedString -> Bool
+substrPS    :: PackedString -> Int -> Int -> PackedString
+takePS      :: Int -> PackedString -> PackedString
+dropPS      :: Int -> PackedString -> PackedString
+splitAtPS   :: Int -> PackedString -> (PackedString, PackedString)
+
+foldlPS     :: (a -> Char -> a) -> a -> PackedString -> a
+foldrPS     :: (Char -> a -> a) -> a -> PackedString -> a
+takeWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+dropWhilePS :: (Char -> Bool) -> PackedString -> PackedString
+spanPS      :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+breakPS     :: (Char -> Bool) -> PackedString -> (PackedString, PackedString)
+linesPS     :: PackedString -> [PackedString]
+
+wordsPS     :: PackedString -> [PackedString]
+splitPS     :: Char -> PackedString -> [PackedString]
+splitWithPS :: (Char -> Bool) -> PackedString -> [PackedString]
+
+nilPS       = NHC.PackedString.nil
+consPS      = NHC.PackedString.cons
+headPS      = NHC.PackedString.head
+tailPS      = NHC.PackedString.tail
+nullPS      = NHC.PackedString.null
+appendPS    = NHC.PackedString.append
+lengthPS    = NHC.PackedString.length
+indexPS p i = (unpackPS p) !! i
+mapPS       = NHC.PackedString.map
+filterPS    = NHC.PackedString.filter
+reversePS   = NHC.PackedString.reverse
+concatPS    = NHC.PackedString.concat
+elemPS c p  = c `elem` unpackPS p
+substrPS    = NHC.PackedString.substr
+takePS      = NHC.PackedString.take
+dropPS      = NHC.PackedString.drop
+splitAtPS   = NHC.PackedString.splitAt
+
+foldlPS     = NHC.PackedString.foldl
+foldrPS     = NHC.PackedString.foldr
+takeWhilePS = NHC.PackedString.takeWhile
+dropWhilePS = NHC.PackedString.dropWhile
+spanPS      = NHC.PackedString.span
+breakPS     = NHC.PackedString.break
+linesPS     = NHC.PackedString.lines
+
+wordsPS     = NHC.PackedString.words
+splitPS c   = splitWithPS (==c)
+splitWithPS = error "Data.PackedString: splitWithPS not implemented"
+
+#endif