Literal

ghc-8.6.3: The GHC API

Safe Haskell | None
Language | Haskell2010

Literal

Contents

- Main data type
  - Creating Literals
  - Operations on Literals
  - Predicates on Literals and their contents
  - Coercions

Synopsis

- data Literal
  - = MachChar Char
  - | LitNumber !LitNumType !Integer Type
  - | MachStr ByteString
  - | MachNullAddr
  - | MachFloat Rational
  - | MachDouble Rational
  - | MachLabel FastString (Maybe Int) FunctionOrData
- data LitNumType
  - = LitNumInteger
  - | LitNumNatural
  - | LitNumInt
  - | LitNumInt64
  - | LitNumWord
  - | LitNumWord64
- mkMachInt :: DynFlags -> Integer -> Literal
- mkMachIntWrap :: DynFlags -> Integer -> Literal
- mkMachIntWrapC :: DynFlags -> Integer -> (Literal, Bool)
- mkMachWord :: DynFlags -> Integer -> Literal
- mkMachWordWrap :: DynFlags -> Integer -> Literal
- mkMachWordWrapC :: DynFlags -> Integer -> (Literal, Bool)
- mkMachInt64 :: Integer -> Literal
- mkMachInt64Wrap :: DynFlags -> Integer -> Literal
- mkMachWord64 :: Integer -> Literal
- mkMachWord64Wrap :: DynFlags -> Integer -> Literal
- mkMachFloat :: Rational -> Literal
- mkMachDouble :: Rational -> Literal
- mkMachChar :: Char -> Literal
- mkMachString :: String -> Literal
- mkLitInteger :: Integer -> Type -> Literal
- mkLitNatural :: Integer -> Type -> Literal
- mkLitNumber :: DynFlags -> LitNumType -> Integer -> Type -> Literal
- mkLitNumberWrap :: DynFlags -> LitNumType -> Integer -> Type -> Literal
- literalType :: Literal -> Type
- absentLiteralOf :: TyCon -> Maybe Literal
- pprLiteral :: (SDoc -> SDoc) -> Literal -> SDoc
- litNumIsSigned :: LitNumType -> Bool
- litNumCheckRange :: DynFlags -> LitNumType -> Integer -> Bool
- litIsDupable :: DynFlags -> Literal -> Bool
- litIsTrivial :: Literal -> Bool
- litIsLifted :: Literal -> Bool
- inIntRange :: DynFlags -> Integer -> Bool
- inWordRange :: DynFlags -> Integer -> Bool
- tARGET_MAX_INT :: DynFlags -> Integer
- inCharRange :: Char -> Bool
- isZeroLit :: Literal -> Bool
- litFitsInChar :: Literal -> Bool
- litValue :: Literal -> Integer
- isLitValue :: Literal -> Bool
- isLitValue_maybe :: Literal -> Maybe Integer
- mapLitValue :: DynFlags -> (Integer -> Integer) -> Literal -> Literal
- word2IntLit :: DynFlags -> Literal -> Literal
- int2WordLit :: DynFlags -> Literal -> Literal
- narrowLit :: forall a. Integral a => Proxy a -> Literal -> Literal
- narrow8IntLit :: Literal -> Literal
- narrow16IntLit :: Literal -> Literal
- narrow32IntLit :: Literal -> Literal
- narrow8WordLit :: Literal -> Literal
- narrow16WordLit :: Literal -> Literal
- narrow32WordLit :: Literal -> Literal
- char2IntLit :: Literal -> Literal
- int2CharLit :: Literal -> Literal
- float2IntLit :: Literal -> Literal
- int2FloatLit :: Literal -> Literal
- double2IntLit :: Literal -> Literal
- int2DoubleLit :: Literal -> Literal
- nullAddrLit :: Literal
- float2DoubleLit :: Literal -> Literal
- double2FloatLit :: Literal -> Literal

# Main data type

data Literal #

So-called `Literal`s are one of:

- An unboxed (machine) literal (`MachInt`, `MachFloat`, etc.), which is presumed to be surrounded by appropriate constructors (`Int#`, etc.), so that the overall thing makes sense.

We maintain the invariant that the `Integer` the Mach{Int,Word}* constructors are actually in the (possibly target-dependent) range. The mkMach{Int,Word}*Wrap smart constructors ensure this by applying the target machine's wrapping semantics. Use these in situations where you know the wrapping semantics are correct.

- The literal derived from the label mentioned in a "foreign label" declaration (`MachLabel`)

Constructors

MachChar Char | `Char#` - at least 31 bits. Create with `mkMachChar`
LitNumber !LitNumType !Integer Type |
MachStr ByteString | A string-literal: stored and emitted UTF-8 encoded, we'll arrange to decode it at runtime. Also emitted with a `'\0'` terminator. Create with `mkMachString`
MachNullAddr | The `NULL` pointer, the only pointer value that can be represented as a Literal. Create with `nullAddrLit`
MachFloat Rational | `Float#`. Create with `mkMachFloat`
MachDouble Rational | `Double#`. Create with `mkMachDouble`
MachLabel FastString (Maybe Int) FunctionOrData | A label literal. Parameters: 1) The name of the symbol mentioned in the declaration 2) The size (in bytes) of the arguments the label expects. Only applicable with `stdcall` labels. `Just x` => `<x>` will be appended to label name when emitting assembly.

Instances

Eq Literal # |
Instance details Defined in Literal Methods (==) :: Literal -> Literal -> Bool # (/=) :: Literal -> Literal -> Bool #
Data Literal # |
Instance details Defined in Literal Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Literal -> c Literal Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Literal Source # toConstr :: Literal -> Constr Source # dataTypeOf :: Literal -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Literal) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Literal) Source # gmapT :: (forall b. Data b => b -> b) -> Literal -> Literal Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Literal -> r Source # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Literal -> r Source # gmapQ :: (forall d. Data d => d -> u) -> Literal -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> Literal -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Literal -> m Literal Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Literal -> m Literal Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Literal -> m Literal Source #
Ord Literal # |
Instance details Defined in Literal Methods compare :: Literal -> Literal -> Ordering # (<) :: Literal -> Literal -> Bool # (<=) :: Literal -> Literal -> Bool # (>) :: Literal -> Literal -> Bool # (>=) :: Literal -> Literal -> Bool # max :: Literal -> Literal -> Literal # min :: Literal -> Literal -> Literal #
Outputable Literal # |
Instance details Defined in Literal Methods ppr :: Literal -> SDoc # pprPrec :: Rational -> Literal -> SDoc #
Binary Literal # |
Instance details Defined in Literal Methods put_ :: BinHandle -> Literal -> IO () # put :: BinHandle -> Literal -> IO (Bin Literal) # get :: BinHandle -> IO Literal #

data LitNumType #

Numeric literal type

Constructors

LitNumInteger | `Integer` (see Note [Integer literals])
LitNumNatural | `Natural` (see Note [Natural literals])
LitNumInt | `Int#` - according to target machine
LitNumInt64 | `Int64#` - exactly 64 bits
LitNumWord | `Word#` - according to target machine
LitNumWord64 | `Word64#` - exactly 64 bits

Instances

Enum LitNumType # |
Instance details Defined in Literal Methods succ :: LitNumType -> LitNumType Source # pred :: LitNumType -> LitNumType Source # toEnum :: Int -> LitNumType Source # fromEnum :: LitNumType -> Int Source # enumFrom :: LitNumType -> [LitNumType] Source # enumFromThen :: LitNumType -> LitNumType -> [LitNumType] Source # enumFromTo :: LitNumType -> LitNumType -> [LitNumType] Source # enumFromThenTo :: LitNumType -> LitNumType -> LitNumType -> [LitNumType] Source #
Eq LitNumType # |
Instance details Defined in Literal Methods (==) :: LitNumType -> LitNumType -> Bool # (/=) :: LitNumType -> LitNumType -> Bool #
Data LitNumType # |
Instance details Defined in Literal Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> LitNumType -> c LitNumType Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c LitNumType Source # toConstr :: LitNumType -> Constr Source # dataTypeOf :: LitNumType -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c LitNumType) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c LitNumType) Source # gmapT :: (forall b. Data b => b -> b) -> LitNumType -> LitNumType Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> LitNumType -> r Source # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> LitNumType -> r Source # gmapQ :: (forall d. Data d => d -> u) -> LitNumType -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> LitNumType -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> LitNumType -> m LitNumType Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> LitNumType -> m LitNumType Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> LitNumType -> m LitNumType Source #
Ord LitNumType # |
Instance details Defined in Literal Methods compare :: LitNumType -> LitNumType -> Ordering # (<) :: LitNumType -> LitNumType -> Bool # (<=) :: LitNumType -> LitNumType -> Bool # (>) :: LitNumType -> LitNumType -> Bool # (>=) :: LitNumType -> LitNumType -> Bool # max :: LitNumType -> LitNumType -> LitNumType # min :: LitNumType -> LitNumType -> LitNumType #
Binary LitNumType # |
Instance details Defined in Literal Methods put_ :: BinHandle -> LitNumType -> IO () # put :: BinHandle -> LitNumType -> IO (Bin LitNumType) # get :: BinHandle -> IO LitNumType #

## Creating Literals

mkMachInt :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Int#`

mkMachIntWrap :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Int#`. If the argument is out of the (target-dependent) range, it is wrapped. See Note [WordInt underflowoverflow]

mkMachIntWrapC :: DynFlags -> Integer -> (Literal, Bool) #

Creates a `Literal` of type `Int#`, as well as a `Bool`ean flag indicating overflow. That is, if the argument is out of the (target-dependent) range the argument is wrapped and the overflow flag will be set. See Note [WordInt underflowoverflow]

mkMachWord :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Word#`

mkMachWordWrap :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Word#`. If the argument is out of the (target-dependent) range, it is wrapped. See Note [WordInt underflowoverflow]

mkMachWordWrapC :: DynFlags -> Integer -> (Literal, Bool) #

Creates a `Literal` of type `Word#`, as well as a `Bool`ean flag indicating carry. That is, if the argument is out of the (target-dependent) range the argument is wrapped and the carry flag will be set. See Note [WordInt underflowoverflow]

mkMachInt64 :: Integer -> Literal #

Creates a `Literal` of type `Int64#`

mkMachInt64Wrap :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Int64#`. If the argument is out of the range, it is wrapped.

mkMachWord64 :: Integer -> Literal #

Creates a `Literal` of type `Word64#`

mkMachWord64Wrap :: DynFlags -> Integer -> Literal #

Creates a `Literal` of type `Word64#`. If the argument is out of the range, it is wrapped.

mkMachFloat :: Rational -> Literal #

Creates a `Literal` of type `Float#`

mkMachDouble :: Rational -> Literal #

Creates a `Literal` of type `Double#`

mkMachChar :: Char -> Literal #

Creates a `Literal` of type `Char#`

mkMachString :: String -> Literal #

Creates a `Literal` of type `Addr#`, which is appropriate for passing to e.g. some of the "error" functions in GHC.Err such as `GHC.Err.runtimeError`

mkLitInteger :: Integer -> Type -> Literal #

mkLitNatural :: Integer -> Type -> Literal #

mkLitNumber :: DynFlags -> LitNumType -> Integer -> Type -> Literal #

Create a numeric `Literal` of the given type

mkLitNumberWrap :: DynFlags -> LitNumType -> Integer -> Type -> Literal #

Create a numeric `Literal` of the given type

## Operations on Literals

literalType :: Literal -> Type #

Find the Haskell `Type` the literal occupies

absentLiteralOf :: TyCon -> Maybe Literal #

pprLiteral :: (SDoc -> SDoc) -> Literal -> SDoc #

litNumIsSigned :: LitNumType -> Bool #

Indicate if a numeric literal type supports negative numbers

litNumCheckRange :: DynFlags -> LitNumType -> Integer -> Bool #

Check that a given number is in the range of a numeric literal

## Predicates on Literals and their contents

litIsDupable :: DynFlags -> Literal -> Bool #

True if code space does not go bad if we duplicate this literal

litIsTrivial :: Literal -> Bool #

True if there is absolutely no penalty to duplicating the literal. False principally of strings.

"Why?", you say? I'm glad you asked. Well, for one duplicating strings would blow up code sizes. Not only this, it's also unsafe.

Consider a program that wants to traverse a string. One way it might do this is to first compute the Addr# pointing to the end of the string, and then, starting from the beginning, bump a pointer using eqAddr# to determine the end. For instance,

    -- Given pointers to the start and end of a string, count how many zeros
    -- the string contains.
    countZeros :: Addr -> -> Int
    countZeros start end = go start 0
      where
        go off n
          | off `addrEq#` end = n
          | otherwise         = go (off `plusAddr#` 1) n'
          where n' | isTrue off 0 0#) = n + 1
                   | otherwise                                 = n

Consider what happens if we considered strings to be trivial (and therefore duplicable) and emitted a call like `countZeros "hello" `plusAddr`# 5)`. The beginning and end pointers do not belong to the same string, meaning that an iteration like the above would blow up terribly. This is what happened in #12757.

Ultimately the solution here is to make primitive strings a bit more structured, ensuring that the compiler can't inline in ways that will break user code. One approach to this is described in #8472.

litIsLifted :: Literal -> Bool #

inIntRange :: DynFlags -> Integer -> Bool #

inWordRange :: DynFlags -> Integer -> Bool #

tARGET_MAX_INT :: DynFlags -> Integer #

inCharRange :: Char -> Bool #

isZeroLit :: Literal -> Bool #

Tests whether the literal represents a zero of whatever type it is

litFitsInChar :: Literal -> Bool #

litValue :: Literal -> Integer #

Returns the `Integer` contained in the `Literal`, for when that makes sense, i.e. for `Char`, `Int`, `Word`, `LitInteger` and `LitNatural`.

isLitValue :: Literal -> Bool #

Indicate if the `Literal` contains an `Integer` value, e.g. `Char`, `Int`, `Word`, `LitInteger` and `LitNatural`.

isLitValue_maybe :: Literal -> Maybe Integer #

Returns the `Integer` contained in the `Literal`, for when that makes sense, i.e. for `Char` and numbers.

mapLitValue :: DynFlags -> (Integer -> Integer) -> Literal -> Literal #

Apply a function to the `Integer` contained in the `Literal`, for when that makes sense, e.g. for `Char` and numbers. For fixed-size integral literals, the result will be wrapped in accordance with the semantics of the target type. See Note [WordInt underflowoverflow]

## Coercions

word2IntLit :: DynFlags -> Literal -> Literal #

int2WordLit :: DynFlags -> Literal -> Literal #

narrowLit :: forall a. Integral a => Proxy a -> Literal -> Literal #

Narrow a literal number (unchecked result range)

narrow8IntLit :: Literal -> Literal #

narrow16IntLit :: Literal -> Literal #

narrow32IntLit :: Literal -> Literal #

narrow8WordLit :: Literal -> Literal #

narrow16WordLit :: Literal -> Literal #

narrow32WordLit :: Literal -> Literal #

char2IntLit :: Literal -> Literal #

int2CharLit :: Literal -> Literal #

float2IntLit :: Literal -> Literal #

int2FloatLit :: Literal -> Literal #

double2IntLit :: Literal -> Literal #

int2DoubleLit :: Literal -> Literal #

nullAddrLit :: Literal #

float2DoubleLit :: Literal -> Literal #

double2FloatLit :: Literal -> Literal #