ghc-7.0.3: The GHC API

FastString

Contents

- FastStrings
  - Construction
  - Deconstruction
  - Encoding
  - Operations
  - Outputing
  - Internal
- LitStrings
  - Construction
  - Deconstruction
  - Operations

Description

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`.

Synopsis

- data FastString = FastString {
  - uniq :: !Int
  - n_bytes :: !Int
  - n_chars :: !Int
  - buf :: !(ForeignPtr Word8)
  - enc :: FSEncoding
  }
- fsLit :: String -> FastString
- mkFastString :: String -> FastString
- mkFastStringBytes :: Ptr Word8 -> Int -> FastString
- mkFastStringByteList :: [Word8] -> FastString
- mkFastStringForeignPtr :: Ptr Word8 -> ForeignPtr Word8 -> Int -> IO FastString
- mkFastString# :: Addr# -> FastString
- mkZFastString :: String -> FastString
- mkZFastStringBytes :: Ptr Word8 -> Int -> FastString
- unpackFS :: FastString -> String
- bytesFS :: FastString -> [Word8]
- isZEncoded :: FastString -> Bool
- zEncodeFS :: FastString -> FastString
- uniqueOfFS :: FastString -> FastInt
- lengthFS :: FastString -> Int
- nullFS :: FastString -> Bool
- appendFS :: FastString -> FastString -> FastString
- headFS :: FastString -> Char
- tailFS :: FastString -> FastString
- concatFS :: [FastString] -> FastString
- consFS :: Char -> FastString -> FastString
- nilFS :: FastString
- hPutFS :: Handle -> FastString -> IO ()
- getFastStringTable :: IO [[FastString]]
- hasZEncoding :: FastString -> Bool
- type LitString = Ptr Word8
- sLit :: String -> LitString
- mkLitString# :: Addr# -> LitString
- mkLitString :: String -> LitString
- unpackLitString :: LitString -> String
- lengthLS :: LitString -> Int

# FastStrings

data FastString

A `FastString` is an array of bytes, hashed to support fast O(1) comparison. It is also associated with a character encoding, so that we know how to convert a `FastString` to the local encoding, or to the Z-encoding used by the compiler internally.

`FastString`s support a memoized conversion to the Z-encoding via zEncodeFS.

Constructors

FastString |

Fields

uniq :: !Int
n_bytes :: !Int
n_chars :: !Int
buf :: !(ForeignPtr Word8)
enc :: FSEncoding

Instances

Eq FastString |
Data FastString |
Ord FastString |
Show FastString |
Typeable FastString |
Outputable FastString |
Uniquable FastString |
Binary FastString |

## Construction

fsLit :: String -> FastString

mkFastString :: String -> FastString

Creates a UTF-8 encoded `FastString` from a `String`

mkFastStringBytes :: Ptr Word8 -> Int -> FastString

mkFastStringByteList :: [Word8] -> FastString

Creates a `FastString` from a UTF-8 encoded `[Word8]`

mkFastStringForeignPtr :: Ptr Word8 -> ForeignPtr Word8 -> Int -> IO FastString

Create a `FastString` from an existing `ForeignPtr`; the difference between this and `mkFastStringBytes` is that we don't have to copy the bytes if the string is new to the table.

mkFastString# :: Addr# -> FastString

mkZFastString :: String -> FastString

Creates a Z-encoded `FastString` from a `String`

mkZFastStringBytes :: Ptr Word8 -> Int -> FastString

## Deconstruction

unpackFS :: FastString -> String

Unpacks and decodes the FastString

bytesFS :: FastString -> [Word8]

## Encoding

isZEncoded :: FastString -> Bool

Returns `True` if the `FastString` is Z-encoded

zEncodeFS :: FastString -> FastString

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.

## Operations

uniqueOfFS :: FastString -> FastInt

lengthFS :: FastString -> Int

Returns the length of the `FastString` in characters

nullFS :: FastString -> Bool

Returns `True` if the `FastString` is empty

appendFS :: FastString -> FastString -> FastString

headFS :: FastString -> Char

tailFS :: FastString -> FastString

concatFS :: [FastString] -> FastString

consFS :: Char -> FastString -> FastString

nilFS :: FastString

## Outputing

hPutFS :: Handle -> FastString -> IO ()

Outputs a `FastString` with no decoding at all, that is, you get the actual bytes in the `FastString` written to the `Handle`.

## Internal

getFastStringTable :: IO [[FastString]]

hasZEncoding :: FastString -> Bool

Returns `True` if this `FastString` is not Z-encoded but already has a Z-encoding cached (used in producing stats).

# LitStrings

type LitString = Ptr Word8

## Construction

sLit :: String -> LitString

mkLitString# :: Addr# -> LitString

mkLitString :: String -> LitString

## Deconstruction

unpackLitString :: LitString -> String

## Operations

lengthLS :: LitString -> Int