perldata.pod: add const and coretypes

New paragraph "Constant and typed lexical variables"

Author: Reini Urban

pod/perldata.pod

@@ -167,17 +167,17 @@ conversion from one form to another is transparent.  Although a
 scalar may not directly hold multiple values, it may contain a
 reference to an array or hash which in turn contains multiple values.
 
-Scalars aren't necessarily one thing or another.  There's no place
-to declare a scalar variable to be of type "string", type "number",
-type "reference", or anything else.  Because of the automatic
-conversion of scalars, operations that return scalars don't need
-to care (and in fact, cannot care) whether their caller is looking
-for a string, a number, or a reference.  Perl is a contextually
-polymorphic language whose scalars can be strings, numbers, or
-references (which includes objects).  Although strings and numbers
-are considered pretty much the same thing for nearly all purposes,
-references are strongly-typed, uncastable pointers with builtin
-reference-counting and destructor invocation.
+Scalars aren't necessarily one thing or another.  Unless using
+L<coretypes> there's no place to declare a scalar variable to be of type
+"string", type "number", type "reference", or anything else.  Because
+of the automatic conversion of scalars, operations that return scalars
+don't need to care (and in fact, cannot care) whether their caller is
+looking for a string, a number, or a reference.  Perl is a
+contextually polymorphic language whose scalars can be strings,
+numbers, or references (which includes objects).  Although strings and
+numbers are considered pretty much the same thing for nearly all
+purposes, references are strongly-typed, uncastable pointers with
+builtin reference-counting and destructor invocation.
 
 A scalar value is interpreted as FALSE in the Boolean sense
 if it is undefined, the null string or the number 0 (or its
@@ -363,6 +363,83 @@ anything more complicated in the subscript will be interpreted as an
 expression.  This means for example that C<$version{2.0}++> is
 equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>.
 
+=head3 Constant and typed lexical variables
+X<const> X<type>
+
+You can declare lexical my, our or state variables with the
+type-qualifier C<const>. const is only available in 5.18 or higher,
+and only with a C<use v5.18> or C<use feature "const">
+declaration.
+
+    my const $i = 1;
+    my const @i = (1);
+    my const %i = ('ok' => 1);
+
+You can also declare the type of a lexical variable with an existing
+packagename:
+
+    package Int;
+    my Int $i;
+
+    my const Int $i = 0;
+
+Lexical const variables cannot be modified, and thus better optimized
+internally at compile-time.  This is similar to the L<Readonly>
+module, just not backwards compatible and const can throw errors
+earlier, at compile-time.
+
+The type information can be used by external modules to implement type
+checks and type optimizations, such as using more efficient
+implementations and short-cut method calls. See
+L<perltypes/"Compile-time type optimizations">.
+
+X<coretypes>
+With C<use coretypes> you can declare the type of a lexical variable
+as C<int>, C<double> or C<string>. C<double> uses the internal
+floating point represention, which might be better or worse than IEEE
+doubles.
+
+Such native typed variables can not be magic, i.e. not tied, and type
+violations such as stringification of int or double, setting to undef
+or more will throw compile-time errors.
+
+    my int $j;
+    my const int $i = 0;
+    my int @a;
+    my const int @b = (0..9);
+    my string %h;
+    my const string %h
+       = ('ok' => '1',
+          'bad' => '2');
+
+Array keys are always of type int, so the array type declaration specifies
+the type of all values.  The const qualifier for arrays specifies
+const-ness of the array size, so you are allowed to change existing array
+values, but you may not add or delete array entries.
+
+    my const @a = (0..4);
+    $a[0] = 'ok';
+    push @a, 'bad';
+    => Modification of a read-only value attempted
+
+Hash keys are always of type string, so the hash type declaration specifies
+the type of all values.  The const qualifier for hashes specifies
+const-ness of all keys, so you are allowed to change hash values, but
+you may not add or delete or change hash keys.
+
+    my const %h = ('ok' => 0);
+    $a{ok} = 1;
+    $a{bad} = 1;
+    => Attempt to access disallowed key
+
+const hashes are implemented as perfect hashes, with element access in O(1)
+time. Existing hashes can be converted to such perfect hashes with
+L<perlfunc/study>.
+
+    my %h;
+    $h{$_}=1 for <>;
+    study %h; # %h is now a PH, a perfect hash
+
 =head3 Version Strings
 X<version string> X<vstring> X<v-string>