ghc-lib-parser-9.10.1.20250103: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Data.FastString

Contents

- ByteString
- ShortByteString
- ShortText
- FastZString
- FastStrings
  - Construction
  - Deconstruction
  - Encoding
  - Operations
  - Outputting
  - 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.
- Generated by `fsLit`.
- You can get a `Unique` from them.
- Equality test is O(1) (it uses the Unique).
- Comparison is O(1) or O(n):
- O(n) but deterministic with lexical comparison (`lexicalCompareFS`)
- O(1) but non-deterministic with Unique comparison (`uniqCompareFS`)
- Turn into `SDoc` with `ftext`.

`PtrString`

- Pointer and size of a Latin-1 encoded string.
- Practically no operations.
- Outputting them is fast.
- Generated by `mkPtrString#`.
- Length of string literals (mkPtrString# "abc"#) is computed statically
- 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
- fastStringToShortByteString :: FastString -> ShortByteString
- mkFastStringShortByteString :: ShortByteString -> FastString
- fastStringToShortText :: FastString -> ShortText
- data FastZString
- hPutFZS :: Handle -> FastZString -> IO ()
- zString :: FastZString -> String
- zStringTakeN :: Int -> FastZString -> String
- lengthFZS :: FastZString -> Int
- data FastString = FastString {
  - uniq :: !Int
  - n_chars :: !Int
  - fs_sbs :: !ShortByteString
  - fs_zenc :: FastZString
  }
- newtype NonDetFastString = NonDetFastString FastString
- newtype LexicalFastString = LexicalFastString FastString
- fsLit :: String -> FastString
- mkFastString :: String -> FastString
- mkFastStringBytes :: Ptr Word8 -> Int -> FastString
- mkFastStringByteList :: [Word8] -> FastString
- mkFastString# :: Addr# -> FastString
- unpackFS :: FastString -> String
- unconsFS :: FastString -> Maybe (Char, FastString)
- zEncodeFS :: FastString -> FastZString
- uniqueOfFS :: FastString -> Int
- lengthFS :: FastString -> Int
- nullFS :: FastString -> Bool
- appendFS :: FastString -> FastString -> FastString
- concatFS :: [FastString] -> FastString
- consFS :: Char -> FastString -> FastString
- nilFS :: FastString
- lexicalCompareFS :: FastString -> FastString -> Ordering
- uniqCompareFS :: FastString -> FastString -> Ordering
- hPutFS :: Handle -> FastString -> IO ()
- getFastStringTable :: IO [[[FastString]]]
- getFastStringZEncCounter :: IO Int
- data PtrString = PtrString !(Ptr Word8) !Int
- mkPtrString# :: Addr# -> PtrString
- unpackPtrString :: PtrString -> String
- unpackPtrStringTakeN :: Int -> PtrString -> String
- lengthPS :: PtrString -> Int

# ByteString

bytesFS :: FastString -> ByteString #

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

fastStringToByteString :: FastString -> ByteString #

Deprecated: Use `bytesFS` instead

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

mkFastStringByteString :: ByteString -> FastString #

Create a `FastString` by copying an existing `ByteString`

fastZStringToByteString :: FastZString -> ByteString #

unsafeMkByteString :: String -> ByteString #

# ShortByteString

fastStringToShortByteString :: FastString -> ShortByteString #

mkFastStringShortByteString :: ShortByteString -> FastString #

Create a `FastString` from an existing `ShortByteString` without copying.

# ShortText

fastStringToShortText :: FastString -> ShortText #

# FastZString

data FastZString #

#### Instances

Instances details

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

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

zString :: FastZString -> String #

zStringTakeN :: Int -> FastZString -> String #

`zStringTakeN n = `take` n . `zString`` but is performed in \(O(\min(n,l))\) rather than \(O(l)\), where \(l\) is the length of the `FastZString`.

lengthFZS :: FastZString -> Int #

# FastStrings

data FastString #

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_sbs :: !ShortByteString
- fs_zenc :: FastZString

  Lazily computed Z-encoding of this string. See Note [Z-Encoding] in GHC.Utils.Encoding.

  Since `FastString`s are globally memoized this is computed at most once for any given string.

#### Instances

Instances details

NFData FastString # |
Instance details Defined in GHC.Data.FastString Methods rnf :: FastString -> () #
Monoid FastString # |
Instance details Defined in GHC.Data.FastString Methods mempty :: FastString # mappend :: FastString -> FastString -> FastString # mconcat :: [FastString] -> FastString #
Semigroup FastString # |
Instance details Defined in GHC.Data.FastString Methods (<>) :: FastString -> FastString -> FastString # sconcat :: NonEmpty FastString -> FastString # stimes :: Integral b => b -> FastString -> FastString #
Data FastString # |

Instance details

Defined in GHC.Data.FastString

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> FastString -> c FastString #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c FastString #

toConstr :: FastString -> Constr #

dataTypeOf :: FastString -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c FastString) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c FastString) #

gmapT :: (forall b. Data b => b -> b) -> FastString -> FastString #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> FastString -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> FastString -> r #

gmapQ :: (forall d. Data d => d -> u) -> FastString -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> FastString -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> FastString -> m FastString #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> FastString -> m FastString #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> FastString -> m FastString #

IsString FastString # |
Instance details Defined in GHC.Data.FastString Methods fromString :: String -> FastString #
Show FastString # |
Instance details Defined in GHC.Data.FastString Methods showsPrec :: Int -> FastString -> ShowS # show :: FastString -> String # showList :: [FastString] -> ShowS #
ToJExpr FastString # |
Instance details Defined in GHC.JS.Make Methods toJExpr :: FastString -> JStgExpr # toJExprFromList :: [FastString] -> JStgExpr #
Uniquable FastString # |
Instance details Defined in GHC.Types.Unique Methods getUnique :: FastString -> Unique #
Binary FastString # |
Instance details Defined in GHC.Utils.Binary Methods put_ :: BinHandle -> FastString -> IO () # put :: BinHandle -> FastString -> IO (Bin FastString) # get :: BinHandle -> IO FastString #
Outputable FastString # |
Instance details Defined in GHC.Utils.Outputable Methods ppr :: FastString -> SDoc #
Eq FastString # |
Instance details Defined in GHC.Data.FastString Methods (==) :: FastString -> FastString -> Bool # (/=) :: FastString -> FastString -> Bool #
ToJExpr a => ToJExpr (UniqMap FastString a) # |
Instance details Defined in GHC.JS.Make Methods toJExpr :: UniqMap FastString a -> JStgExpr # toJExprFromList :: [UniqMap FastString a] -> JStgExpr #
type Anno FastString # |
Instance details Defined in GHC.Hs.Expr type Anno FastString = EpAnnCO
type Anno (SourceText, RuleName) # |
Instance details Defined in GHC.Hs.Decls type Anno (SourceText, RuleName) = EpAnnCO

newtype NonDetFastString #

Non-deterministic FastString

This is a simple FastString wrapper with an Ord instance using `uniqCompareFS` (i.e. which compares FastStrings on their Uniques). Hence it is not deterministic from one run to the other.

Constructors

NonDetFastString FastString |

#### Instances

Instances details

Data NonDetFastString # |

Instance details

Defined in GHC.Data.FastString

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> NonDetFastString -> c NonDetFastString #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c NonDetFastString #

toConstr :: NonDetFastString -> Constr #

dataTypeOf :: NonDetFastString -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c NonDetFastString) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c NonDetFastString) #

gmapT :: (forall b. Data b => b -> b) -> NonDetFastString -> NonDetFastString #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> NonDetFastString -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> NonDetFastString -> r #

gmapQ :: (forall d. Data d => d -> u) -> NonDetFastString -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> NonDetFastString -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> NonDetFastString -> m NonDetFastString #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> NonDetFastString -> m NonDetFastString #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> NonDetFastString -> m NonDetFastString #

Show NonDetFastString # |
Instance details Defined in GHC.Data.FastString Methods showsPrec :: Int -> NonDetFastString -> ShowS # show :: NonDetFastString -> String # showList :: [NonDetFastString] -> ShowS #
Binary NonDetFastString # |
Instance details Defined in GHC.Utils.Binary Methods put_ :: BinHandle -> NonDetFastString -> IO () # put :: BinHandle -> NonDetFastString -> IO (Bin NonDetFastString) # get :: BinHandle -> IO NonDetFastString #
Outputable NonDetFastString # |
Instance details Defined in GHC.Utils.Outputable Methods ppr :: NonDetFastString -> SDoc #
Eq NonDetFastString # |
Instance details Defined in GHC.Data.FastString Methods (==) :: NonDetFastString -> NonDetFastString -> Bool # (/=) :: NonDetFastString -> NonDetFastString -> Bool #
Ord NonDetFastString # |

Instance details

Defined in GHC.Data.FastString

Methods

compare :: NonDetFastString -> NonDetFastString -> Ordering #

(<) :: NonDetFastString -> NonDetFastString -> Bool #

(<=) :: NonDetFastString -> NonDetFastString -> Bool #

(>) :: NonDetFastString -> NonDetFastString -> Bool #

(>=) :: NonDetFastString -> NonDetFastString -> Bool #

max :: NonDetFastString -> NonDetFastString -> NonDetFastString #

min :: NonDetFastString -> NonDetFastString -> NonDetFastString #

newtype LexicalFastString #

Lexical FastString

This is a simple FastString wrapper with an Ord instance using `lexicalCompareFS` (i.e. which compares FastStrings on their String representation). Hence it is deterministic from one run to the other.

Constructors

LexicalFastString FastString |

#### Instances

Instances details

Data LexicalFastString # |

Instance details

Defined in GHC.Data.FastString

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> LexicalFastString -> c LexicalFastString #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c LexicalFastString #

toConstr :: LexicalFastString -> Constr #

dataTypeOf :: LexicalFastString -> DataType #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c LexicalFastString) #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c LexicalFastString) #

gmapT :: (forall b. Data b => b -> b) -> LexicalFastString -> LexicalFastString #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> LexicalFastString -> r #

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> LexicalFastString -> r #

gmapQ :: (forall d. Data d => d -> u) -> LexicalFastString -> [u] #

gmapQi :: Int -> (forall d. Data d => d -> u) -> LexicalFastString -> u #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> LexicalFastString -> m LexicalFastString #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> LexicalFastString -> m LexicalFastString #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> LexicalFastString -> m LexicalFastString #

Show LexicalFastString # |
Instance details Defined in GHC.Data.FastString Methods showsPrec :: Int -> LexicalFastString -> ShowS # show :: LexicalFastString -> String # showList :: [LexicalFastString] -> ShowS #
Binary LexicalFastString # |
Instance details Defined in GHC.Utils.Binary Methods put_ :: BinHandle -> LexicalFastString -> IO () # put :: BinHandle -> LexicalFastString -> IO (Bin LexicalFastString) # get :: BinHandle -> IO LexicalFastString #
Outputable LexicalFastString # |
Instance details Defined in GHC.Utils.Outputable Methods ppr :: LexicalFastString -> SDoc #
Eq LexicalFastString # |
Instance details Defined in GHC.Data.FastString Methods (==) :: LexicalFastString -> LexicalFastString -> Bool # (/=) :: LexicalFastString -> LexicalFastString -> Bool #
Ord LexicalFastString # |

Instance details

Defined in GHC.Data.FastString

Methods

compare :: LexicalFastString -> LexicalFastString -> Ordering #

(<) :: LexicalFastString -> LexicalFastString -> Bool #

(<=) :: LexicalFastString -> LexicalFastString -> Bool #

(>) :: LexicalFastString -> LexicalFastString -> Bool #

(>=) :: LexicalFastString -> LexicalFastString -> Bool #

max :: LexicalFastString -> LexicalFastString -> LexicalFastString #

min :: LexicalFastString -> LexicalFastString -> LexicalFastString #

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

mkFastString# :: Addr# -> FastString #

## Deconstruction

unpackFS :: FastString -> String #

Lazily unpacks and decodes the FastString

unconsFS :: FastString -> Maybe (Char, FastString) #

## Encoding

zEncodeFS :: FastString -> FastZString #

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 #

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 #

concatFS :: [FastString] -> FastString #

consFS :: Char -> FastString -> FastString #

nilFS :: FastString #

lexicalCompareFS :: FastString -> FastString -> Ordering #

Compare FastString lexically

If you don't care about the lexical ordering, use `uniqCompareFS` instead.

uniqCompareFS :: FastString -> FastString -> Ordering #

Compare FastString by their Unique (not lexically).

Much cheaper than `lexicalCompareFS` but non-deterministic!

## Outputting

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

getFastStringZEncCounter :: IO Int #

# PtrStrings

data PtrString #

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

Constructors

PtrString !(Ptr Word8) !Int |

## Construction

mkPtrString# :: Addr# -> PtrString #

Wrap an unboxed address into a `PtrString`.

## Deconstruction

unpackPtrString :: PtrString -> String #

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

unpackPtrStringTakeN :: Int -> PtrString -> String #

`unpackPtrStringTakeN n = `take` n . `unpackPtrString`` but is performed in \(O(\min(n,l))\) rather than \(O(l)\), where \(l\) is the length of the `PtrString`.

## Operations

lengthPS :: PtrString -> Int #

Return the length of a `PtrString`