Commit 9ef40dc2 authored by batterseapower's avatar batterseapower
Browse files

Document FastString and rename strLength to lengthLS

parent f9cde00b
......@@ -10,26 +10,30 @@
-- We always optimise this, otherwise performance of a non-optimised
-- compiler is severely affected
{-
FastString: A compact, hash-consed, representation of character strings.
Comparison is O(1), and you can get a Unique from them.
Generated by fsLit
Turn into SDoc with Outputable.ftext
LitString: Just a wrapper for the Addr# of a C string (Ptr CChar).
Practically no operations
Outputing them is fast
Generated by sLit
Turn into SDoc with Outputable.ptext
Use LitString unless you want the facilities of FastString
-}
-- |
-- There are two principal string types used internally by GHC:
--
-- 'FastString':
-- * A compact, hash-consed, representation of character strings.
-- * Comparison is O(1), and you can get a 'Unique.Unique' from them.
-- * Generated by 'fsLit'.
-- * Turn into 'Outputable.SDoc' with 'Outputable.ftext'.
--
-- 'LitString':
-- * Just a wrapper for the @Addr#@ of a C string (@Ptr CChar@).
-- * Practically no operations.
-- * Outputing them is fast.
-- * Generated by 'sLit'.
-- * Turn into 'Outputable.SDoc' with 'Outputable.ptext'
--
-- Use 'LitString' unless you want the facilities of 'FastString'.
module FastString
(
-- * FastStrings
FastString(..), -- not abstract, for now.
-- ** Construction
fsLit,
mkFastString,
mkFastStringBytes,
mkFastStringByteList,
......@@ -68,17 +72,19 @@ module FastString
-- * LitStrings
LitString,
-- ** Construction
sLit,
#if defined(__GLASGOW_HASKELL__)
mkLitString#,
#endif
mkLitString,
-- ** Deconstruction
unpackLitString,
strLength,
ptrStrLength,
sLit,
fsLit,
-- ** Operations
lengthLS
) where
#include "HsVersions.h"
......@@ -385,12 +391,12 @@ hashStr (Ptr a#) (I# len#) = loop 0# 0#
lengthFS :: FastString -> Int
lengthFS f = n_chars f
-- | Returns 'True' if the 'FastString' is Z-encoded
-- | Returns @True@ if the 'FastString' is Z-encoded
isZEncoded :: FastString -> Bool
isZEncoded fs | ZEncoded <- enc fs = True
| otherwise = False
-- | Returns 'True' if this 'FastString' is not Z-encoded but already has
-- | Returns @True@ if this 'FastString' is not Z-encoded but already has
-- a Z-encoding cached (used in producing stats).
hasZEncoding :: FastString -> Bool
hasZEncoding (FastString _ _ _ _ enc) =
......@@ -401,11 +407,11 @@ hasZEncoding (FastString _ _ _ _ enc) =
m <- readIORef ref
return (isJust m)
-- | Returns 'True' if the 'FastString' is empty
-- | Returns @True@ if the 'FastString' is empty
nullFS :: FastString -> Bool
nullFS f = n_bytes f == 0
-- | unpacks and decodes the FastString
-- | Unpacks and decodes the FastString
unpackFS :: FastString -> String
unpackFS (FastString _ n_bytes _ buf enc) =
inlinePerformIO $ withForeignPtr buf $ \ptr ->
......@@ -418,7 +424,7 @@ bytesFS (FastString _ n_bytes _ buf _) =
inlinePerformIO $ withForeignPtr buf $ \ptr ->
peekArray n_bytes ptr
-- | returns a Z-encoded version of a 'FastString'. This might be the
-- | Returns a Z-encoded version of a 'FastString'. This might be the
-- original, if it was already Z-encoded. The first time this
-- function is applied to a particular 'FastString', the results are
-- memoized.
......@@ -545,8 +551,8 @@ unpackLitString p_ = case pUnbox p_ of
ch -> if ch `eqFastChar` _CLIT('\0')
then [] else cBox ch : unpack (n +# _ILIT(1))
strLength :: LitString -> Int
strLength = ptrStrLength
lengthLS :: LitString -> Int
lengthLS = ptrStrLength
-- for now, use a simple String representation
--no, let's not do that right now - it's work in other places
......@@ -559,8 +565,8 @@ mkLitString = id
unpackLitString :: LitString -> String
unpackLitString = id
strLength :: LitString -> Int
strLength = length
lengthLS :: LitString -> Int
lengthLS = length
#endif
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment