Literal Overloading

Natural numbers

By default natural number literals are mapped to the built-in natural number type. This can be changed with the FROMNAT built-in, which binds to a function accepting a natural number:

  1. {-# BUILTIN FROMNAT fromNat #-}

This causes natural number literals n to be desugared to fromNat n, whenever fromNat is in scope unqualified (renamed or not). Note that the desugaring happens before implicit argument are inserted so fromNat can have any number of implicit or instance arguments. This can be exploited to support overloaded literals by defining a type class containing fromNat:

  1. module number-simple where
  3.   record Number {a} (A : Set a) : Set a where
  4.     field fromNat : Nat → A
  6.   open Number {{...}} public
  1. {-# BUILTIN FROMNAT fromNat #-}

This definition requires that any natural number can be mapped into the given type, so it won’t work for types like Fin n. This can be solved by refining the Number class with an additional constraint:

  1. record Number {a} (A : Set a) : Set (lsuc a) where
  2.   field
  3.     Constraint : Nat → Set a
  4.     fromNat : (n : Nat) {{_ : Constraint n}} → A
  6. open Number {{...}} public using (fromNat)
  8. {-# BUILTIN FROMNAT fromNat #-}

This is the definition used in Agda.Builtin.FromNat. A Number instance for Nat is simply this:

  1. instance
  2.   NumNat : Number Nat
  3.   NumNat .Number.Constraint _ = ⊤
  4.   NumNat .Number.fromNat    m = m

A Number instance for Fin n can be defined as follows:

  1. _≤_ : (m n : Nat) → Set
  2. zero  ≤ n     = ⊤
  3. suc m ≤ zero  = ⊥
  4. suc m ≤ suc n = m ≤ n
  6. fromN≤ : ∀ m n → m ≤ n → Fin (suc n)
  7. fromN≤ zero    _       _  = zero
  8. fromN≤ (suc _) zero    ()
  9. fromN≤ (suc m) (suc n) p  = suc (fromN≤ m n p)
  11. instance
  12.   NumFin : ∀ {n} → Number (Fin (suc n))
  13.   NumFin {n} .Number.Constraint m         = m ≤ n
  14.   NumFin {n} .Number.fromNat    m {{m≤n}} = fromN≤ m n m≤n
  16. test : Fin 5
  17. test = 3

It is important that the constraint for literals is trivial. Here, 3 ≤ 5 evaluates to ⊤ whose inhabitant is found by unification.

Using predefined function from the standard library and instance NumNat, the NumFin instance can be simply:

  1. open import Data.Fin using (Fin; #_)
  2. open import Data.Nat using (suc; _≤?_)
  3. open import Relation.Nullary.Decidable using (True)
  5. instance
  6.   NumFin : ∀ {n} → Number (Fin n)
  7.   NumFin {n} .Number.Constraint m         = True (suc m ≤? n)
  8.   NumFin {n} .Number.fromNat    m {{m<n}} = #_ m {m<n = m<n}

Negative numbers

Negative integer literals have no default mapping and can only be used through the FROMNEG built-in. Binding this to a function fromNeg causes negative integer literals -n to be desugared to fromNeg n, where n is a built-in natural number. From Agda.Builtin.FromNeg:

  1. record Negative {a} (A : Set a) : Set (lsuc a) where
  2.   field
  3.     Constraint : Nat → Set a
  4.     fromNeg : (n : Nat) {{_ : Constraint n}} → A
  6. open Negative {{...}} public using (fromNeg)
  7. {-# BUILTIN FROMNEG fromNeg #-}

Strings

String literals are overloaded with the FROMSTRING built-in, which works just like FROMNAT. If it is not bound string literals map to built-in strings. From Agda.Builtin.FromString:

  1. record IsString {a} (A : Set a) : Set (lsuc a) where
  2.   field
  3.     Constraint : String → Set a
  4.     fromString : (s : String) {{_ : Constraint s}} → A
  6. open IsString {{...}} public using (fromString)
  7. {-# BUILTIN FROMSTRING fromString #-}

Restrictions

Currently only integer and string literals can be overloaded.

Overloading does not work in patterns yet.