FastString

ghc-8.10.0.20191123: The GHC API

Safe Haskell | None
Language | Haskell2010

FastString

Contents

- ByteString
- FastZString
- FastStrings
  - Construction
  - Deconstruction
  - Encoding
  - Operations
  - Outputing
  - Internal
- PtrStrings
  - 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` from them.
- Generated by `fsLit`.
- Turn into `SDoc` with `ftext`.

`PtrString`

- Pointer and size of a Latin-1 encoded string.
- Practically no operations.
- Outputing them is fast.
- Generated by `sLit`.
- Turn into `SDoc` with `ptext`
- Requires manual memory management. Improper use may lead to memory leaks or dangling pointers.
- It assumes Latin-1 as the encoding, therefore it cannot represent arbitrary Unicode strings.

Use `PtrString` unless you want the facilities of `FastString`.

Synopsis

- bytesFS :: FastString -> ByteString
- fastStringToByteString :: FastString -> ByteString
- mkFastStringByteString :: ByteString -> FastString
- fastZStringToByteString :: FastZString -> ByteString
- unsafeMkByteString :: String -> ByteString
- data FastZString
- hPutFZS :: Handle -> FastZString -> IO ()
- zString :: FastZString -> String
- lengthFZS :: FastZString -> Int
- data FastString = FastString {
  - uniq :: !Int
  - n_chars :: !Int
  - fs_bs :: !ByteString
  - fs_zenc :: FastZString
  }
- 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
- unpackFS :: FastString -> String
- zEncodeFS :: FastString -> FastZString
- uniqueOfFS :: FastString -> Int
- 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
- isUnderscoreFS :: FastString -> Bool
- hPutFS :: Handle -> FastString -> IO ()
- getFastStringTable :: IO [[[FastString]]]
- getFastStringZEncCounter :: IO Int
- data PtrString = PtrString !(Ptr Word8) !Int
- sLit :: String -> PtrString
- mkPtrString# :: Addr# -> PtrString
- mkPtrString :: String -> PtrString
- unpackPtrString :: PtrString -> String
- lengthPS :: PtrString -> Int

# ByteString

bytesFS :: FastString -> ByteString Source #

Gives the UTF-8 encoded bytes corresponding to a `FastString`

fastStringToByteString :: FastString -> ByteString Source #

Deprecated: Use `bytesFS` instead

mkFastStringByteString :: ByteString -> FastString Source #

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.

fastZStringToByteString :: FastZString -> ByteString Source #

unsafeMkByteString :: String -> ByteString Source #

# FastZString

data FastZString Source #

#### Instances

Instances details

NFData FastZString # |
Instance details Defined in FastString Methods rnf :: FastZString -> () Source #

hPutFZS :: Handle -> FastZString -> IO () Source #

zString :: FastZString -> String Source #

lengthFZS :: FastZString -> Int Source #

# FastStrings

data FastString Source #

A `FastString` is a UTF-8 encoded string together with a unique ID. All `FastString`s are stored in a global hashtable to support fast O(1) comparison.

It is also associated with a lazy reference to the Z-encoding of this string which is used by the compiler internally.

Constructors

FastString |
Fields uniq :: !Int n_chars :: !Int fs_bs :: !ByteString fs_zenc :: FastZString Lazily computed z-encoding of this string. Since `FastString`s are globally memoized this is computed at most once for any given string.

#### Instances

Instances details

Eq FastString # |
Instance details Defined in FastString Methods (==) :: FastString -> FastString -> Bool # (/=) :: FastString -> FastString -> Bool #
Data FastString # |
Instance details Defined in FastString Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> FastString -> c FastString Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c FastString Source # toConstr :: FastString -> Constr Source # dataTypeOf :: FastString -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c FastString) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c FastString) Source # gmapT :: (forall b. Data b => b -> b) -> FastString -> FastString Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> FastString -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> FastString -> r Source # gmapQ :: (forall d. Data d => d -> u) -> FastString -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> FastString -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> FastString -> m FastString Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> FastString -> m FastString Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> FastString -> m FastString Source #
Ord FastString # |
Instance details Defined in FastString Methods compare :: FastString -> FastString -> Ordering # (<) :: FastString -> FastString -> Bool # (<=) :: FastString -> FastString -> Bool # (>) :: FastString -> FastString -> Bool # (>=) :: FastString -> FastString -> Bool # max :: FastString -> FastString -> FastString # min :: FastString -> FastString -> FastString #
Show FastString # |
Instance details Defined in FastString Methods showsPrec :: Int -> FastString -> ShowS Source # show :: FastString -> String Source # showList :: [FastString] -> ShowS Source #
IsString FastString # |
Instance details Defined in FastString Methods fromString :: String -> FastString Source #
Semigroup FastString # |
Instance details Defined in FastString Methods (<>) :: FastString -> FastString -> FastString Source # sconcat :: NonEmpty FastString -> FastString Source # stimes :: Integral b => b -> FastString -> FastString Source #
Monoid FastString # |
Instance details Defined in FastString Methods mempty :: FastString Source # mappend :: FastString -> FastString -> FastString Source # mconcat :: [FastString] -> FastString Source #
NFData FastString # |
Instance details Defined in FastString Methods rnf :: FastString -> () Source #
Outputable FastString # |
Instance details Defined in Outputable Methods ppr :: FastString -> SDoc Source # pprPrec :: Rational -> FastString -> SDoc Source #
Uniquable FastString # |
Instance details Defined in Unique Methods getUnique :: FastString -> Unique Source #
Binary FastString # |
Instance details Defined in Binary Methods put_ :: BinHandle -> FastString -> IO () Source # put :: BinHandle -> FastString -> IO (Bin FastString) Source # get :: BinHandle -> IO FastString Source #

## Construction

fsLit :: String -> FastString Source #

mkFastString :: String -> FastString Source #

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

mkFastStringBytes :: Ptr Word8 -> Int -> FastString Source #

mkFastStringByteList :: [Word8] -> FastString Source #

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

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

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 Source #

## Deconstruction

unpackFS :: FastString -> String Source #

Unpacks and decodes the FastString

## Encoding

zEncodeFS :: FastString -> FastZString Source #

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 -> Int Source #

lengthFS :: FastString -> Int Source #

Returns the length of the `FastString` in characters

nullFS :: FastString -> Bool Source #

Returns `True` if the `FastString` is empty

appendFS :: FastString -> FastString -> FastString Source #

headFS :: FastString -> Char Source #

tailFS :: FastString -> FastString Source #

concatFS :: [FastString] -> FastString Source #

consFS :: Char -> FastString -> FastString Source #

nilFS :: FastString Source #

isUnderscoreFS :: FastString -> Bool Source #

## Outputing

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

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]]] Source #

getFastStringZEncCounter :: IO Int Source #

# PtrStrings

data PtrString Source #

A `PtrString` is a pointer to some array of Latin-1 encoded chars.

Constructors

PtrString !(Ptr Word8) !Int |

## Construction

sLit :: String -> PtrString Source #

mkPtrString# :: Addr# -> PtrString Source #

Wrap an unboxed address into a `PtrString`.

mkPtrString :: String -> PtrString Source #

Encode a `String` into a newly allocated `PtrString` using Latin-1 encoding. The original string must not contain non-Latin-1 characters (above codepoint `0xff`).

## Deconstruction

unpackPtrString :: PtrString -> String Source #

Decode a `PtrString` back into a `String` using Latin-1 encoding. This does not free the memory associated with `PtrString`.

## Operations

lengthPS :: PtrString -> Int Source #

Return the length of a `PtrString`