Revert "Revert "Add documentation and test for Val{T}""

This reverts commit ef7f5d4.

This is modified to incorporate the verdict in the discussion
of #9452.

NEWS.md

@@ -143,6 +143,7 @@ Library improvements
 
   * The `randexp` and `randexp!` functions are exported ([#9144])
 
+  * A new `Val{T}` type allows one to dispatch on bits-type values ([#9452])
 
 Deprecated or removed
 ---------------------
@@ -1145,3 +1146,4 @@ Too numerous to mention.
 [#9271]: https://github.com/JuliaLang/julia/issues/9271
 [#9294]: https://github.com/JuliaLang/julia/issues/9294
 [#9569]: https://github.com/JuliaLang/julia/issues/9569
+[#9452]: https://github.com/JuliaLang/julia/issues/9452

doc/manual/types.rst

@@ -692,7 +692,7 @@ surrounded by curly braces::
 This declaration defines a new parametric type, ``Point{T}``, holding
 two "coordinates" of type ``T``. What, one may ask, is ``T``? Well,
 that's precisely the point of parametric types: it can be any type at
-all (or an integer, actually, although here it's clearly used as a
+all (or any bits type, actually, although here it's clearly used as a
 type). ``Point{Float64}`` is a concrete type equivalent to the type
 defined by replacing ``T`` in the definition of ``Point`` with
 :class:`Float64`. Thus, this single declaration actually declares an
@@ -1243,6 +1243,39 @@ If you apply :func:`super` to other type objects (or non-type objects), a
     julia> super((Float64,Int64))
     ERROR: `super` has no method matching super(::Type{(Float64,Int64)})
 
+"Value types"
+-------------
+
+As one application of these ideas, Julia includes a parametric type,
+``Val{T}``, designated for dispatching on bits-type *values*.  For
+example, if you pass a boolean to a function, you have to test the
+value at run-time:
+
+.. doctest::
+
+    function firstlast(b::Bool)
+        return b ? "First" : "Last"
+    end
+
+    println(firstlast(true))
+
+You can instead cause the conditional to be evaluated during function
+compilation by using the ``Val`` trick:
+
+.. doctest::
+
+    firstlast(::Type{Val{true}}) = "First"
+    firstlast(::Type{Val{false}}) = "Last"
+
+    println(firstlast(Val{true}))
+
+Any legal type parameter (Types, Symbols, Integers, floating-point
+numbers, tuples, etc.) can be passed via ``Val``.
+
+For consistency across Julia, the call site should always pass a
+``Val`` type rather than creating an instance, i.e., use
+``foo(Val{:bar})`` rather than ``foo(Val{:bar}())``.
+
 Nullable Types: Representing Missing Values
 -------------------------------------------
 

doc/stdlib/base.rst

@@ -438,6 +438,14 @@ Types
 
    Compute a type that contains the intersection of ``T`` and ``S``. Usually this will be the smallest such type or one close to it.
 
+.. function:: Val{c}
+
+   Create a "value type" out of ``c``, which must be an ``isbits``
+   value. The intent of this construct is to be able to dispatch on
+   constants, e.g., ``f(Val{false})`` allows you to dispatch directly
+   (at compile-time) to an implementation ``f(::Type{Val{false}})``,
+   without having to test the boolean value at runtime.
+
 Generic Functions
 -----------------
 

test/core.jl

@@ -502,6 +502,16 @@ begin
     @test is(g(a),a)
 end
 
+# dispatch using Val{T}. See discussion in #9452 for instances vs types
+begin
+    local firstlast
+    firstlast(::Type{Val{true}}) = "First"
+    firstlast(::Type{Val{false}}) = "Last"
+
+    @test firstlast(Val{true}) == "First"
+    @test firstlast(Val{false}) == "Last"
+end
+
 # try/finally
 begin
     after = 0