diff options
author | Ben Orchard <thefirstmuffinman@gmail.com> | 2022-05-24 14:18:45 +0100 |
---|---|---|
committer | Marge Bot <ben+marge-bot@smart-cactus.org> | 2023-05-03 20:16:18 -0400 |
commit | 931c8d82f28fb98a7e0ad0a837eff05c08021cbe (patch) | |
tree | 2c23bfc55f915762e43d4cf87aff21991b8a73d0 /docs/users_guide | |
parent | 00a8a5ff9abf5bb1a0c2a9225c7bca5ec3bdf306 (diff) | |
download | haskell-931c8d82f28fb98a7e0ad0a837eff05c08021cbe.tar.gz |
Add sized primitive literal syntax
Adds a new LANGUAGE pragma ExtendedLiterals, which enables defining
unboxed numeric literals such as `0xFF#Word8 :: Word8#`.
Implements GHC proposal 0451:
https://github.com/ghc-proposals/ghc-proposals/blob/b384a538b34f79d18a0201455b7b3c473bc8c936/proposals/0451-sized-literals.rst
Fixes #21422.
Bumps haddock submodule.
Co-authored-by: Krzysztof Gogolewski <krzysztof.gogolewski@tweag.io>
Diffstat (limited to 'docs/users_guide')
-rw-r--r-- | docs/users_guide/9.8.1-notes.rst | 4 | ||||
-rw-r--r-- | docs/users_guide/exts/extended_literals.rst | 47 | ||||
-rw-r--r-- | docs/users_guide/exts/literals.rst | 1 | ||||
-rw-r--r-- | docs/users_guide/exts/primitives.rst | 3 | ||||
-rw-r--r-- | docs/users_guide/exts/stolen_syntax.rst | 3 |
5 files changed, 58 insertions, 0 deletions
diff --git a/docs/users_guide/9.8.1-notes.rst b/docs/users_guide/9.8.1-notes.rst index 9f2d51d329..e7e9acdf75 100644 --- a/docs/users_guide/9.8.1-notes.rst +++ b/docs/users_guide/9.8.1-notes.rst @@ -6,6 +6,10 @@ Version 9.8.1 Language ~~~~~~~~ +- There is a new extension :extension:`ExtendedLiterals`, which enables + sized primitive literals, e.g. ``123#Int8`` is a literal of type ``Int8#``. + See the GHC proposal `#451 <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0451-sized-literals.rst>`_. + Compiler ~~~~~~~~ diff --git a/docs/users_guide/exts/extended_literals.rst b/docs/users_guide/exts/extended_literals.rst new file mode 100644 index 0000000000..ac61f2d410 --- /dev/null +++ b/docs/users_guide/exts/extended_literals.rst @@ -0,0 +1,47 @@ +.. _extended-literals: + +Sized primitive literal syntax +------------------------------ + +.. extension:: ExtendedLiterals + :shortdesc: Enable numeric literal postfix syntax for unboxed integers. + + :since: 9.8.1 + + Allows defining unboxed numeric primitive values through ``#Type`` suffixes + on numeric literals e.g. ``0xFF#Word8 :: Word8#``. + +The :extension:`MagicHash` extension enables some new literals, including ``3# +:: Int#``, ``3## :: Word#``. This does not extend to all unboxed values. For +example, there is no literal syntax for ``Word8#``: you must write something +such as ``wordToWord8 (3## :: Word#) :: Word8#``. + +:extension:`ExtendedLiterals` enables further syntax for defining primitive +numeric literals. Suffix any Haskell integer lexeme with a hash sign ``#`` +followed by a primitive numeric type (without its hash suffix) to obtain a value +of that type. For example, ``0xFF#Word8 :: Word8#``. There must be no spaces +between the parts of the literal. + +The primitive numeric types allowed are: + +- ``Int8#`` +- ``Int16#`` +- ``Int32#`` +- ``Int64#`` +- ``Int#`` +- ``Word8#`` +- ``Word16#`` +- ``Word32#`` +- ``Word64#`` +- ``Word#`` + +All types permit any nonnegative Haskell integer lexeme, e.g. ``70``, ``0x2A``, +``0o1276``, ``0b1010`` (with :extension:`BinaryLiterals`). The signed ``Int`` +types also permit negative integer lexemes. Defining a literal with a value that +can't fit in its requested type will emit an overflow warning by default, the +same as boxed numeric literals. + +As with :extension:`MagicHash`, this extension does not bring anything into +scope, nor change any semantics. The syntax only applies to numeric literals. +You may want to import ``GHC.Exts`` (see :ref:`primitives`) to refer to the +types of the literals you define. diff --git a/docs/users_guide/exts/literals.rst b/docs/users_guide/exts/literals.rst index fbb613333f..6061bdfec7 100644 --- a/docs/users_guide/exts/literals.rst +++ b/docs/users_guide/exts/literals.rst @@ -10,6 +10,7 @@ Literals binary_literals hex_float_literals num_decimals + extended_literals numeric_underscores overloaded_strings overloaded_labels diff --git a/docs/users_guide/exts/primitives.rst b/docs/users_guide/exts/primitives.rst index 9caab6b146..ef8cb32523 100644 --- a/docs/users_guide/exts/primitives.rst +++ b/docs/users_guide/exts/primitives.rst @@ -19,6 +19,9 @@ your program, you must first import ``GHC.Exts`` to bring them into scope. Many of them have names ending in ``#``, and to mention such names you need the :extension:`MagicHash` extension. +To enable defining literals for other primitive data types, see the +:extension:`ExtendedLiterals` extension. + The primops make extensive use of `unboxed types <#glasgow-unboxed>`__ and `unboxed tuples <#unboxed-tuples>`__, which we briefly summarise here. diff --git a/docs/users_guide/exts/stolen_syntax.rst b/docs/users_guide/exts/stolen_syntax.rst index 746daebd7c..39747bc745 100644 --- a/docs/users_guide/exts/stolen_syntax.rst +++ b/docs/users_guide/exts/stolen_syntax.rst @@ -80,6 +80,9 @@ The following syntax is stolen: ⟨varid⟩, ``#``\ ⟨char⟩, ``#``, ⟨string⟩, ``#``, ⟨integer⟩, ``#``, ⟨float⟩, ``#``, ⟨float⟩, ``##`` Stolen by: :extension:`MagicHash` +⟨integer⟩, ``#(Int|Word)(8|16|32|64)?`` + Stolen by: :extension:`ExtendedLiterals` + ``(#``, ``#)`` Stolen by: :extension:`UnboxedTuples` |