NAME
sscanf - emulate the sscanf() of the C stdio library
SYNOPSIS
use String::Scanf; # this will import sscanf() into the
# current namespace
@values = sscanf($scanf_format_string, $scalar_to_scan);
# the default scan target is the $_
@values = sscanf($scanf_format_string);
# converting scanf formats to regexps (::format_to_re
# is never exported to the current namespace)
$regexp_string = String::Scanf::format_to_re($scanf_format_string);DESCRIPTION
Perl sscanf() can be used very much like the C stdio sscanf(), for detailed sscanf() documentation please refer to your usual documentation resources. The supported formats are: [diuoxefgsc] and the character class [].
All of the format must match. If not, an empty list is returned and all the values end up empty.
The c format returns an anonymous list (see perlref) containing the numeric values of the characters it matched.
The ::format_to_re() function may be helpful if one wants to develop her own parsing routines.
FEATURES
Embedded underscores are accepted in numbers just like in Perl, even in octal/hexadecimal numbers (Perl does not currently support this). Please note the word embedded, not leading or trailing.
If the oh formats are used, the octal/hexadecimal interpretation is forced even without the leading 0 or 0x.
LIMITATIONS
Certain features of the C sscanf() are unsupported:
* the formats C<[npSC]>
* in the C<[efg]> formats the C<INF> and various C<NaN>sThe numeric formats are scanned in as strings, this meaning that numeric overflows may occur. For example: 1.2345e67890 will match the %g format but in most machines Perl cannot handle that large floating point numbers and bizarre values may end up in the Perl variable. Similar caveats apply for integer-type numbers. Results of such huge numbers (or very tiny numbers, say, 1.24345e-67890) are implementation-defined, which translates quite often as garbage. NOTE: if you really want Big numbers please consider using the Math::BigInt and Math::BigFloat, these packages come standard with Perl 5, or the Math::Pari package, available from CPAN.
For Perl <integers> and floating point numbers are the same thing. Also, the possible hl modifiers for the integers mean nothing: they are accepted but still they do nothing because Perl does not care about short/long integer differences.
The character class format is not so rigorously checked for correctness that an illegal character class definition could not be sneaked in. For example [z-a,X] is a bad example: perfectly illegal as a character class but String::Scanf will happily accept it. Beware.
The ::format_to_re() only does the scanf format -> regular expression conversion. It ignores tricky things like the c format (see above) and the %n$ argument reordering. If you want these, you may as well use the full ::sscanf().
EXAMPLES
# business as usual
($i, $s, $x) = sscanf('%d %3s %g', ' -5_678 abc 3.14e-99 9');
# 'skip leading whitespace': $x becomes 42 despite the leading space
# 'the illegal character': $y becomes 'ab' despite the '3'
# 'c' format: $z becomes [120 100], the numeric values of 'x'
# and 'd' (assuming ASCII or ISO Latin 1)
($x, $y, $z) = sscanf('%i%3[a-e]%2c', ' 42acxde');
# reordering the arguments: $a becomes 34, $b becomes 12
($a, $b) = sscanf('%2$d %1$d', '12 34');
# converting scanf formats to regexps
$re = String::Scanf::format_to_re('%x');More examples in the test set t/scanf.t.
INTERNALS
The Perl sscanf() turns the C-stdio style sscanf() format string into a Perl regexp (see perlre) which captures the wanted values into submatches and returns the submatches as a list.
Originally written for purposes of debugging but also useful for educational purposes:
String::Scanf::debug(1); # turn on debugging: shows the regexps
# used and the possible reordering list
# and the character (%c) conversion targets
String::Scanf::debug(0); # turn off debugging
print String::Scanf::debug(), "\n"; # the current debug statusVERSION
v1.1, $Id: Scanf.pm,v 1.8 1995/12/27 08:32:28 jhi Exp $
AUTHOR
Jarkko Hietaniemi, Jarkko.Hietaniemi@iki.fi