Here's the very rough draft of the String <=> Num document I said I'd
do.
Some of the behavior in here was just what made sense to me, since I
had no definitive answer. If anyone has ideas for more useful
or sensible behavior, please say so.
Oh, and I'm not sure what POD-like conventions we're using, so please
correct me on that too.
--------
=section ## Converting between numbers and strings
Numbers can be displayed in many different ways. This section covers
how you can represent a number as a string, or vice versa, precisely
how you want.
=section ### Converting numbers to strings
The most straightforward way to convert a number to a string is simply
to use it as one.
my $num = 3.14;
$num ~= 'foo'; # $num contains '3.14foo'
The number is converted to string form in the shortest, correctly
rounded way that results in the same number if converted back. This
means that integers will print all their digits, and floating point
numbers won't resort to scientific notation until there are enough
zeroes to make scientific notation shorter.
To get finer-grained control over how your numbers are represented as
strings or printed, use the C<printf> or C<sprintf> functions.
=for comment
Should I document printf and sprintf here?
=for comment
Is there an C<is formatted> property or something like that, which
would be like an Awk OFMT on a per-variable basis?
=section ### Converting strings to numbers
Just as numbers can be used as strings, strings will automatically
convert themselves to numbers. By default, this is done by taking all
the numbers starting at the beginning of the string, discarding
leading whitespace, up until the first non-numeric character (treating
the decimal point and exponential notation as numeric characters). If
the string is not entirely numeric and C<warnings> are enabled, a
warning is issued.
my ($x, $y, $z) = ≪12.6pi 0x3f 6.022e22≫
$x += 1; # 13.6 with warning ("pi" not numeric)
my $w = $y - 1; # $w = -1 with warning ("x3f" not numeric)
$z /= 2; # 3.011e22 and no warning
To extract a number specified in any notation that Perl allows, and
check whether it is a well-formed Perl number, use the C<.numeric>
method.
The C<.numeric> method on strings returns the number contained in the
string, even if it's in arbitrary base notation, dotted notation, or
anything else Perl understands. It C<fail>s if the string is not a
well-formed number. Leading and trailing whitespace is ignored.
'6124872'.numeric; # 6124872
'3.2e6'.numeric; # 3200000
'0c27'.numeric; # 23
'34foo'.numeric; # fail (undef/exception)
'16:3D'.numeric; # 61
'8:3D'.numeric; # fail
