Safe Haskell	None
Language	GHC2021

Howl.Symbol

Description

The public symbol type used in Howl expressions.

Symbols are interned names such as x, Plus, or List. By default, Howl uses the symbolize library as its symbol implementation. There is also a simpler implementation in Howl.Symbol.Simple based on a newtype over ShortText, but it is currently turned off by default.

Synopsis

data Symbol
symbolToShortText :: Symbol -> ShortText
symbolFromShortText :: ShortText -> Symbol

Documentation

data Symbol #

A string-like type with O(1) equality and comparison.

A Symbol represents a string (any Textual, so String, Text, ShortText, ByteString, ShortByteString, etc.)

Just like ShortText, ShortByteString and ByteArray, a Symbol has an optimized memory representation, directly wrapping a primitive ByteArray#.

Furthermore, a global symbol table keeps track of which values currently exist, ensuring we always deduplicate symbols. This therefore allows us to: - Check for equality between symbols in constant-time (using pointer equality) - Calculate the hash in constant-time (using StableName) - Keep the memory footprint of repeatedly-seen strings low.

This is very useful if you're frequently comparing strings and the same strings might come up many times. It also makes Symbol a great candidate for a key in e.g. a HashMap or HashSet.

The global symbol table is implemented using weak pointers, which means that unused symbols will be garbage collected. As such, you do not need to be concerned about memory leaks (as is the case with many other symbol table implementations).

Symbols are considered 'the same' regardless of whether they originate from a String, (lazy or strict, normal or short) Text, (lazy or strict, normal or short) ByteString etc.

Instances

Instances details

Binary Symbol	Uses the `ShortByteString` instance of `Textual` under the hood; invalid UTF-8 is replaced by the Unicode replacement character. Since: symbolize-1.0.1.0
Instance details Defined in Symbolize Methods put :: Symbol -> Put # get :: Get Symbol # putList :: [Symbol] -> Put #
NFData Symbol	The contents inside a `Symbol` are always guaranteed to be evaluated, so this only forces the outermost constructor using `seq`.
Instance details Defined in Symbolize Methods rnf :: Symbol -> () #
Data Symbol	This `Data` instance follows the same implementation as the one for `Text` and `ShortText`: It pretends `Symbol` is a a collection holding a `[Char]`. Since: symbolize-1.0.1.0
Instance details Defined in Symbolize Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Symbol -> c Symbol # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Symbol # toConstr :: Symbol -> Constr # dataTypeOf :: Symbol -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Symbol) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Symbol) # gmapT :: (forall b. Data b => b -> b) -> Symbol -> Symbol # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Symbol -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Symbol -> r # gmapQ :: (forall d. Data d => d -> u) -> Symbol -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Symbol -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Symbol -> m Symbol # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Symbol -> m Symbol # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Symbol -> m Symbol #
IsString Symbol
Instance details Defined in Symbolize Methods fromString :: String -> Symbol #
Read Symbol	To be a good citizen w.r.t both `Show` and `IsString`, reading is supported two ways: `>>>` `read @Symbol "Symbolize.intern \"Haskell\""`Symbolize.intern "Haskell" `>>>` `read @Symbol "\"Curry\""`Symbolize.intern "Curry"
Instance details Defined in Symbolize Methods readsPrec :: Int -> ReadS Symbol # readList :: ReadS [Symbol] # readPrec :: ReadPrec Symbol # readListPrec :: ReadPrec [Symbol] #
Show Symbol
Instance details Defined in Symbolize Methods showsPrec :: Int -> Symbol -> ShowS # show :: Symbol -> String # showList :: [Symbol] -> ShowS #
Eq Symbol	Equality checking takes only O(1) time, and is a simple pointer-equality check.
Instance details Defined in Symbolize Methods (==) :: Symbol -> Symbol -> Bool # (/=) :: Symbol -> Symbol -> Bool #
Ord Symbol	Symbols are ordered by their lexicographical UTF-8 representation. Therefore, comparison takes O(n) time.
Instance details Defined in Symbolize Methods compare :: Symbol -> Symbol -> Ordering # (<) :: Symbol -> Symbol -> Bool # (<=) :: Symbol -> Symbol -> Bool # (>) :: Symbol -> Symbol -> Bool # (>=) :: Symbol -> Symbol -> Bool # max :: Symbol -> Symbol -> Symbol # min :: Symbol -> Symbol -> Symbol #
Hashable Symbol	Hashing a `Symbol` is very fast: `hash` takes O(1) and results in zero collisions, as `StableName`s are used. `hashWithSalt` takes O(1) time; just as long as hashWithSalt-ing any other `Int`.
Instance details Defined in Symbolize Methods hashWithSalt :: Int -> Symbol -> Int # hash :: Symbol -> Int #
FromExpr Symbol #
Instance details Defined in Howl.Expr.Internal Methods fromExpr :: Expr -> Maybe Symbol #
ToExpr Symbol #
Instance details Defined in Howl.Expr.Internal Methods toExpr :: Symbol -> Expr #
PPrint Symbol #
Instance details Defined in Howl.Symbol.Symbolize Methods pPrint :: Symbol -> String #

symbolToShortText :: Symbol -> ShortText #

Convert a symbol to its short-text name.

symbolFromShortText :: ShortText -> Symbol #

Intern a short-text name as a symbol.