Document the val() from allomorphs.pm

Covers #418

Author: jonathanstowe

doc/Type/Str.pod

@@ -895,6 +895,26 @@ Form KD / Compatibility Decomposed).
 
 Returns C<True> if the string is L<the same as|eq> C<$other>.
 
+=head2 sub val
+
+=comment
+    seems like the best place to document this
+
+    multi sub val(Str:D $MAYBEVAL, :$val-or-fail)
+
+Given a C<Str> that may be parseable as a numeric value, it will
+attempt to construct the appropriate L<allomorph|/language/glossary#Allomorph>,
+returning one of L<IntStr|/type/IntStr>, L<NumStr|/type/NumStr>, L<RatStr|/type/RatStr>
+or L<ComplexStr|/type/ComplexStr> or a plain C<Str> if a numeric value cannot
+be parsed.  If the C<:val-or-fail> adverb is provided it will return an
+L<X::Str::Numeric|/type/X/Str/Numeric> rather than the original string if it 
+cannot parse the string as a number.
+
+    say val("42").WHAT; # (IntStr)
+    say val("42e0").WHAT; # (NumStr)
+    say val("42.0").WHAT; # (RatStr)
+    say val("42+0i").WHAT; # (ComplexStr)
+
 =end pod
 
 # vim: expandtab shiftwidth=4 ft=perl6