Document const fns

Author: oli-obk

src/items/functions.md

@@ -8,7 +8,7 @@
 >       [_BlockExpression_]
 >
 > _FunctionFront_ :\
-> &nbsp;&nbsp; `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
+> &nbsp;&nbsp; `const`<sup>?</sup> `unsafe`<sup>?</sup> (`extern` _Abi_<sup>?</sup>)<sup>?</sup>
 >
 > _Abi_ :\
 > &nbsp;&nbsp; [STRING_LITERAL] | [RAW_STRING_LITERAL]
@@ -160,6 +160,38 @@ attributes], [`must_use`], [the procedural macro attributes], [the testing
 attributes], and [the optimization hint
 attributes].
 
+## Const functions
+
+Functions can be `const`, meaning they can be called from within array length expressions and the initializer of constants, statics and enum discriminants. When called from such a so-called "const context", the function is interpreted by the compiler at compile time. The interpretation happens in the environment of the compilation target and not the host. So `usize` is `32` bits if you are compiling against a `32` bit system, irrelevant of whether you are building on a `64` bit or a `32` bit system.
+
+If a `const fn` is called outside a "const context", it is indistinguishable from any other function. You can freely do anything with a `const fn` that you can do with a regular fn.
+
+`const fn`s have various restrictions to makes sure that you cannot define a `const fn` that can't be evaluated at compile-time. You will, for example, never be able to write a random number generator as a const fn. Calling a const fn at compile-time will always yield the same result as calling it at runtime, even if you call it multiple times. There's one exception to this rule: if you are doing complex floating point operations in extreme situations, then you might get (very slightly) different results. It is adviseable to not make array lengths and enum discriminants depend on floating point computations.
+
+Exhaustive list of permitted structures in `const fn`:
+
+1. type parameters where the parameters have any of the following as part of their bounds (either on `where` or directly on the parameters):
+    1. lifetimes
+    2. `Sized`
+
+    This means that `<T: 'a + ?Sized>` and `<T: 'b + Sized>` + `<T>` are all permitted.
+    Note that `?Sized` is the absence of a constraint when bounds have been fully elaborated
+    which includes adding implicit `Sized` bounds.
+    This entails that permitting `Sized` + lifetimes allows the above examples.
+
+    This rule also applies to type parameters of items that contain `const fn`s.
+
+2. arithmetic operators on integers
+3. boolean operators (except for `&&` and `||` which are banned since they are short-circuiting).
+4. any kind of aggregate constructor (array, `struct`, `enum`, tuple, ...)
+5. calls to other *safe* `const fn`s (methods and functions)
+6. index operations on arrays and slices
+7. field accesses on structs and tuples
+8. reading from constants (but not statics, not even taking a reference to a static)
+9. `&` and `*` (only dereferencing of references, not raw pointers)
+10. casts except for raw pointer to `usize` casts
+11. `const unsafe fn` is allowed, but the body must consist of safe operations only and you won't be able to call the `const unsafe fn` from within another `const fn` even if you use `unsafe`
+
 [IDENTIFIER]: identifiers.html
 [RAW_STRING_LITERAL]: tokens.html#raw-string-literals
 [STRING_LITERAL]: tokens.html#string-literals