Scanf(3)

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>s
The 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'.

COMPATIBILITY
Versions prior to 1.3 scanned "0123" with [efg] formats as an octal number. `C' sscanf would, however, understand this as a decimal number. Versions starting from 1.3 will use the decimal interpretation. If you have old code that depends on the old interpretation, you can say

        String::Scanf::set_compat('efg_oct' => 1);

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 status

CREATED
v1.1, -Id: Scanf.pm,v 1.8 1995/12/27 08:32:28 jhi Exp -

AUTHOR
Jarkko Hietaniemi, `Jarkko.Hietaniemi@iki.fi'