Literals

A literal is the text of a value written directly into the source. There is one literal form per kind of built-in value: a number, a character in single quotes, and text in double quotes. A literal has its own type until the context expects a different one, and then it adapts to that type instead.

Example#

const decimal = 10
const million = 1_000_000
const byte: UInt8 = 0xFF
const flags = 0b1010
const ratio = 3.14
const large = 1e9
const letter = 'A'
const wave = '\u{1F44B}'
const greeting = "Grüße"

print "{decimal} {million} {byte} {flags} {ratio} {large} {letter} {wave} {greeting}"

Syntax#

10  1_000_000  0xFF  0b1010            an integer literal; `_` groups digits anywhere between them
3.14  1e9  1.5e-3                      a float literal: a fraction, an exponent, or both
'A'  '\n'  '\u{1F44B}'                 a character literal: exactly one character
"text"  "line {expression}"            a string literal, with interpolation
raw"text"                              a raw string literal: no escapes, no interpolation

Rules#

1. An integer literal without an expected type is Int64, a literal with a fraction or an exponent is Float64. This does not follow the Int/Float aliases; it is fixed.

   const wholeNumber = 7
   const withFraction = 7.0
   print "{wholeNumber} {withFraction}"

2. A literal adapts to the type it is expected to have, and one that does not fit is a compile error at the literal. The error names the literal and the type, not a range.

   const byte: UInt8 = 200
   print byte

   Kompiliert nicht

   const small: Int8 = 300
   // error: `300` does not fit into `Int8`

3. 0x starts a hexadecimal literal, 0b a binary one, and both take only integer types. There is no octal literal form.

   const byte: UInt8 = 0xFF
   const flags: UInt8 = 0b1010
   print "{byte} {flags}"

   Kompiliert nicht

   const mask: Float = 0xFF
   // error: `0xFF` is written in another base, and only an integer type takes it: `Float64` is not one

4. _ groups the digits of a number literal and carries no value of its own. It may stand between digits of an integer or a float literal in any position; the formatter canon does not require a particular grouping.

5. A float literal has a fraction, an exponent, or both. 1e9 needs no fraction, and an exponent takes an optional + or - sign: 1.5e-3.

6. A character literal is exactly one character, in single quotes. An escape sequence counts as the one character; anything else between the quotes is an error.

   Kompiliert nicht

   const both = 'ab'
   // error: A character literal contains exactly one character and ends with `'`

7. A character or string literal escapes six named characters plus one general escape. \n, \r, \t, \0, \\, \" and \' name themselves; \u{1F44B} names a Unicode scalar value by its hexadecimal code point. An escape that is none of these is an error at the backslash.

   Kompiliert nicht

   const wrong = '\q'
   // error: Unknown escape sequence `\q`

8. A string literal interpolates {expression} and escapes a literal brace as \{ or \}. See String interpolation for what may stand inside the braces.

9. A raw string (raw"text") has no escapes and no interpolation. \ and { are ordinary characters inside one, which is what a path, a regular expression or a snippet of JSON needs. raw is a contextual keyword: it is the prefix only directly in front of ", and an ordinary name everywhere else, so const raw = 1 still declares a binding called raw.

   const pattern = raw"C:\Users\{name}"
   print pattern

10. A string literal where a Path, a Uri, a UriTemplate, a Regex or a resource type is expected is read by the compiler. One that is not a valid value of the type is an error at the literal, and a Regex or a UriTemplate literal is read verbatim - with no escape sequences and no interpolation, as a raw string is - so its backslashes and braces need no raw. See Checked literals.

    use Regex from "std/regex"
    
    const digits: Regex = "\d+"
    print digits.matches("2026")

What this is not#

A number literal is not typed by its spelling alone. 0xFF is not "a hex number type"; it is an Int64 like 255 unless the context says otherwise, and the same literal fits any integer type it is small enough for.

const asByte: UInt8 = 0xFF
const asWord: UInt16 = 0xFF
print "{asByte} {asWord}"

const asByte: UInt8 = 0x1FF
// error: `0x1FF` does not fit into `UInt8`

A character literal is not a one-character string. 'A' is a Char, "A" is a String of one character, and neither converts to the other implicitly. See Strings for the boundary between the two.

Related#

• String interpolation - what {expression} inside a string does.
• Multi-line strings - the """ form and how it is dedented.
• Integers - the eight sized types a literal can adapt to.
• Checked literals - the string literals the compiler reads as a Uri, a Regex or a Path.
• Bindings - how a type annotation changes what a literal is.