GHC.Types.Literal

Core literals

Main data type

data Literal

So-called Literals are one of:

• An unboxed numeric literal or floating-point literal 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 in the LitNumber constructor is actually in the (possibly target-dependent) range. The mkLit{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 (LitLabel)
• A LitRubbish to be used in place of values of UnliftedRep (i.e. MutVar#) when the value is never used.
• A character
• A string
• The NULL pointer

Constructors

LitChar Char

Char# - at least 31 bits. Create with mkLitChar

LitNumber !LitNumType !Integer

Any numeric literal that can be internally represented with an Integer.

LitString !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 mkLitString

LitNullAddr

The NULL pointer, the only pointer value that can be represented as a Literal. Create with nullAddrLit

LitRubbish Bool

A nonsense value; always boxed, but True = lifted, False = unlifted Used when a binding is absent. See Note [Rubbish literals]

LitFloat Rational

Float#. Create with mkLitFloat

LitDouble Rational

Double#. Create with mkLitDouble

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

3) Flag indicating whether the symbol references a function or a data

Instances

Eq Literal

Defined in GHC.Types.Literal

Methods

(==) :: Literal -> Literal -> Bool

(/=) :: Literal -> Literal -> Bool

Data Literal

Defined in GHC.Types.Literal

Methods

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

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

toConstr :: Literal -> Constr

dataTypeOf :: Literal -> DataType

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

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

gmapT :: (forall b. Data b => b -> b) -> Literal -> Literal

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

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

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

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

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

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

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

Ord Literal

Needed for the Ord instance of AltCon, which in turn is needed in CoreMap.

Defined in GHC.Types.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

Defined in GHC.Types.Literal

Methods

ppr :: Literal -> SDoc

Binary Literal

Defined in GHC.Types.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 [BigNum literals])

LitNumNatural

Natural (see Note [BigNum literals])

LitNumInt

Int# - according to target machine

LitNumInt8

Int8# - exactly 8 bits

LitNumInt16

Int16# - exactly 16 bits

LitNumInt32

Int32# - exactly 32 bits

LitNumInt64

Int64# - exactly 64 bits

LitNumWord

Word# - according to target machine

LitNumWord8

Word8# - exactly 8 bits

LitNumWord16

Word16# - exactly 16 bits

LitNumWord32

Word32# - exactly 32 bits

LitNumWord64

Word64# - exactly 64 bits

Instances

Enum LitNumType

Defined in GHC.Types.Literal

Methods

succ :: LitNumType -> LitNumType

pred :: LitNumType -> LitNumType

toEnum :: Int -> LitNumType

fromEnum :: LitNumType -> Int

enumFrom :: LitNumType -> [LitNumType]

enumFromThen :: LitNumType -> LitNumType -> [LitNumType]

enumFromTo :: LitNumType -> LitNumType -> [LitNumType]

enumFromThenTo :: LitNumType -> LitNumType -> LitNumType -> [LitNumType]

Eq LitNumType

Defined in GHC.Types.Literal

Methods

(==) :: LitNumType -> LitNumType -> Bool

(/=) :: LitNumType -> LitNumType -> Bool

Data LitNumType

Defined in GHC.Types.Literal

Methods

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

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

toConstr :: LitNumType -> Constr

dataTypeOf :: LitNumType -> DataType

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

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

gmapT :: (forall b. Data b => b -> b) -> LitNumType -> LitNumType

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

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

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

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

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

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

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

Ord LitNumType

Defined in GHC.Types.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

Defined in GHC.Types.Literal

Methods

put_ :: BinHandle -> LitNumType -> IO ()

put :: BinHandle -> LitNumType -> IO (Bin LitNumType)

get :: BinHandle -> IO LitNumType

Creating Literals

mkLitInt :: Platform -> Integer -> Literal

Creates a Literal of type Int#

mkLitIntWrap :: Platform -> 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]

mkLitIntWrapC :: Platform -> Integer -> (Literal, Bool)

Creates a Literal of type Int#, as well as a Boolean 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]

mkLitIntUnchecked :: Integer -> Literal

Creates a Literal of type Int# without checking its range.

mkLitWord :: Platform -> Integer -> Literal

Creates a Literal of type Word#

mkLitWordWrap :: Platform -> 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]

mkLitWordWrapC :: Platform -> Integer -> (Literal, Bool)

Creates a Literal of type Word#, as well as a Boolean 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]

mkLitInt8 :: Integer -> Literal

Creates a Literal of type Int8#

mkLitInt8Wrap :: Integer -> Literal

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

mkLitWord8 :: Integer -> Literal

Creates a Literal of type Word8#

mkLitWord8Wrap :: Integer -> Literal

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

mkLitInt16 :: Integer -> Literal

Creates a Literal of type Int16#

mkLitInt16Wrap :: Integer -> Literal

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

mkLitWord16 :: Integer -> Literal

Creates a Literal of type Word16#

mkLitWord16Wrap :: Integer -> Literal

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

mkLitInt32 :: Integer -> Literal

Creates a Literal of type Int32#

mkLitInt32Wrap :: Integer -> Literal

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

mkLitWord32 :: Integer -> Literal

Creates a Literal of type Word32#

mkLitWord32Wrap :: Integer -> Literal

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

mkLitInt64 :: Integer -> Literal

Creates a Literal of type Int64#

mkLitInt64Wrap :: Integer -> Literal

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

mkLitWord64 :: Integer -> Literal

Creates a Literal of type Word64#

mkLitWord64Wrap :: Integer -> Literal

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

mkLitFloat :: Rational -> Literal

Creates a Literal of type Float#

mkLitDouble :: Rational -> Literal

Creates a Literal of type Double#

mkLitChar :: Char -> Literal

Creates a Literal of type Char#

mkLitString :: 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 -> Literal

mkLitNatural :: Integer -> Literal

mkLitNumber :: Platform -> LitNumType -> Integer -> Literal

Create a numeric Literal of the given type

mkLitNumberWrap :: Platform -> LitNumType -> Integer -> Literal

Make a literal number using wrapping semantics if the value is out of bound.

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 :: Platform -> LitNumType -> Integer -> Bool

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

litNumWrap :: Platform -> Literal -> Literal

Wrap a literal number according to its type using wrapping semantics.

litNumCoerce :: LitNumType -> Platform -> Literal -> Literal

Coerce a literal number into another using wrapping semantics.

litNumNarrow :: LitNumType -> Platform -> Literal -> Literal

Narrow a literal number by converting it into another number type and then converting it back to its original type.

litNumBitSize :: Platform -> LitNumType -> Maybe Word

Number of bits

isMinBound :: Platform -> Literal -> Bool

isMaxBound :: Platform -> Literal -> Bool

Predicates on Literals and their contents

litIsDupable :: Platform -> 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

inCharRange :: Char -> Bool

isZeroLit :: Literal -> Bool

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

isOneLit :: Literal -> Bool

Tests whether the literal represents a one 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.

mapLitValue :: Platform -> (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]

isLitValue_maybe :: Literal -> Maybe Integer

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

Coercions

narrowInt8Lit :: Literal -> Literal

narrowInt16Lit :: Literal -> Literal

narrowInt32Lit :: Literal -> Literal

narrowInt64Lit :: Literal -> Literal

narrowWord8Lit :: Literal -> Literal

narrowWord16Lit :: Literal -> Literal

narrowWord32Lit :: Literal -> Literal

narrowWord64Lit :: Literal -> Literal

convertToIntLit :: Platform -> Literal -> Literal

Extend or narrow a fixed-width literal (e.g. Int16#) to a target word-sized literal (Int# or Word#). Narrowing can only happen on 32-bit architectures when we convert a 64-bit literal into a 32-bit one.

convertToWordLit :: Platform -> Literal -> Literal

Extend or narrow a fixed-width literal (e.g. Int16#) to a target word-sized literal (Int# or Word#). Narrowing can only happen on 32-bit architectures when we convert a 64-bit literal into a 32-bit one.

charToIntLit :: Literal -> Literal

intToCharLit :: Literal -> Literal

floatToIntLit :: Literal -> Literal

intToFloatLit :: Literal -> Literal

doubleToIntLit :: Literal -> Literal

intToDoubleLit :: Literal -> Literal

nullAddrLit :: Literal

floatToDoubleLit :: Literal -> Literal

doubleToFloatLit :: Literal -> Literal

rubbishLit :: Bool -> Literal

A rubbish literal; see Note [Rubbish literals]

isRubbishLit :: Literal -> Bool