• NAME
• SUPPORTED PLATFORMS
• SYNOPSIS
• DESCRIPTION
• FEATURES
• LIMITATIONS
• EXAMPLES
• INTERNALS
• VERSION
• AUTHOR

NAME

sscanf - emulate the sscanf() of the C stdio library

SUPPORTED PLATFORMS

• Linux
• Solaris
• Windows

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.

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

VERSION

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

AUTHOR

Jarkko Hietaniemi, Jarkko.Hietaniemi@iki.fi