NAME
    String::Numeric - Determine whether a string represents a numeric value

SYNOPSIS
        $boolean = is_float($string);
        $boolean = is_decimal($string);
    
        $boolean = is_int($string);
        $boolean = is_int8($string);
        $boolean = is_int16($string);
        $boolean = is_int32($string);
        $boolean = is_int64($string);
        $boolean = is_int128($string);
    
        $boolean = is_uint($string);
        $boolean = is_uint8($string);
        $boolean = is_uint16($string);
        $boolean = is_uint32($string);
        $boolean = is_uint64($string);
        $boolean = is_uint128($string);

DESCRIPTION
    A numeric value contains an integer part that may be prefixed with an
    optional minus sign, which may be followed by a fractional part and/or
    an exponent part.

    See "String::Numeric ABNF" for specification and "COMPARISON" for a
    comparison with "Scalar::Util::looks_like_number()".

FUNCTIONS
  is_float
    Determine whether $string is a floating-point number of arbitrary
    precision.

    *Usage*

        $boolean = is_float($string);
        $boolean = is_float('-1');     # true
        $boolean = is_float('1');      # true
        $boolean = is_float('1.0');    # true
        $boolean = is_float('1.0e6');  # true
        $boolean = is_float('1e6');    # true
        $boolean = is_float(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

    *Note*

    This function is also available as "is_numeric()"

  is_decimal
    Determine whether $string is a decimal number of arbitrary precision.

    *Usage*

        $boolean = is_decimal($string);
        $boolean = is_decimal('-1');     # true
        $boolean = is_decimal('1');      # true
        $boolean = is_decimal('1.0');    # true
        $boolean = is_decimal('1.0e6');  # false
        $boolean = is_decimal('1e6');    # false
        $boolean = is_decimal(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_int
    Determine whether $string is an integer of arbitrary precision.

    *Usage*

        $boolean = is_int($string);
        $boolean = is_int('1');      # true
        $boolean = is_int('-1');     # true
        $boolean = is_int('1.0');    # false
        $boolean = is_int(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

    *Note*

    This function is also available as "is_integer()"

  is_int8
    Determine whether $string is a 8-bit signed integer which can have any
    value in the range -128 to 127.

    *Usage*

        $boolean = is_int8($string);
        $boolean = is_int8('-128');   # true
        $boolean = is_int8('127');    # true
        $boolean = is_int8(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_int16
    Determine whether $string is a 16-bit signed integer which can have any
    value in the range -32,768 to 32,767.

    *Usage*

        $boolean = is_int16($string);
        $boolean = is_int16('-32768');   # true
        $boolean = is_int16('32767');    # true
        $boolean = is_int16(undef);      # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_int32
    Determine whether $string is a 32-bit signed integer which can have any
    value in the range -2,147,483,648 to 2,147,483,647.

    *Usage*

        $boolean = is_int32($string);
        $boolean = is_int32('-2147483648');   # true
        $boolean = is_int32('2147483647');    # true
        $boolean = is_int32(undef);           # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_int64
    Determine whether $string is a 64-bit signed integer which can have any
    value in the range -9,223,372,036,854,775,808 to
    9,223,372,036,854,775,807.

    *Usage*

        $boolean = is_int64($string);
        $boolean = is_int64('-9223372036854775808');   # true
        $boolean = is_int64('9223372036854775807');    # true
        $boolean = is_int64(undef);                    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_int128
    Determine whether $string is a 128-bit signed integer which can have any
    value in the range -170,141,183,460,469,231,731,687,303,715,884,105,728
    to 170,141,183,460,469,231,731,687,303,715,884,105,727.

    *Usage*

        $boolean = is_int128($string);
        $boolean = is_int128('-170141183460469231731687303715884105728');   # true
        $boolean = is_int128('170141183460469231731687303715884105727');    # true
        $boolean = is_int128(undef);                                        # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint
    Determine whether $string is an unsigned integer of arbitrary precision.

    *Usage*

        $boolean = is_uint($string);
        $boolean = is_uint('1');      # true
        $boolean = is_uint('-1');     # false
        $boolean = is_uint('1.0');    # false
        $boolean = is_uint(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint8
    Determine whether $string is a 8-bit unsigned integer which can have any
    value in the range 0 to 255.

    *Usage*

        $boolean = is_uint8($string);
        $boolean = is_uint8('0');      # true
        $boolean = is_uint8('255');    # true
        $boolean = is_uint8(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint16
    Determine whether $string is a 16-bit unsigned integer which can have
    any value in the range 0 to 65,535.

    *Usage*

        $boolean = is_uint16($string);
        $boolean = is_uint16('0');      # true
        $boolean = is_uint16('65535');  # true
        $boolean = is_uint16(undef);    # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint32
    Determine whether $string is a 32-bit unsigned integer which can have
    any value in the range 0 to 4,294,967,295.

    *Usage*

        $boolean = is_uint32($string);
        $boolean = is_uint32('0');           # true
        $boolean = is_uint32('4294967295');  # true
        $boolean = is_uint32(undef);         # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint64
    Determine whether $string is a 64-bit unsigned integer which can have
    any value in the range 0 to 18,446,744,073,709,551,615.

    *Usage*

        $boolean = is_uint64($string);
        $boolean = is_uint64('0');                     # true
        $boolean = is_uint64('18446744073709551615');  # true
        $boolean = is_uint64(undef);                   # false

    *Arguments*

    $string

    *Returns*

    $boolean

  is_uint128
    Determine whether $string is a 128-bit unsigned integer which can have
    any value in the range 0 to
    340,282,366,920,938,463,463,374,607,431,768,211,455.

    *Usage*

        $boolean = is_uint128($string);
        $boolean = is_uint128('0');                                        # true
        $boolean = is_uint128('340282366920938463463374607431768211455');  # true
        $boolean = is_uint128(undef);                                      # false

    *Arguments*

    $string

    *Returns*

    $boolean

LIMITATIONS
    "String::Numeric" supports numbers in decimal notation using Western
    Arabic numerals and decimal fractions seperated with a dot. Other
    notations or numeral systems are not supported.

COMPARISON
  Scalar::Util
    None of the following is considered valid by "String::Numeric".

    * Fractional number without integer part or fractional part
            looks_like_number("1.") # true
            looks_like_number(".1") # true

    * Plus prefix
            looks_like_number("+1") # true

    * Leading zeros
            looks_like_number("01") # true

    * Radix point other than "."
            looks_like_number("1,1") # true assuming locale is in effect and locale radix point is ','

    * Leading and/or trailing whitespace, such as HT, LF, FF, CR, and SP
            looks_like_number("\n1")   # true
            looks_like_number("1\n")   # true
            looks_like_number("\n1\n") # true

    * Numeric values that are not represented as a sequence of digits, such
    as "Inf", "Infinity", "NaN" and "0 but true"
            looks_like_number("Inf")        # true
            looks_like_number("Infinity")   # true
            looks_like_number("NaN")        # true
            looks_like_number("0 but true") # true

GRAMMAR
  String::Numeric ABNF
        ; String::Numeric ABNF Grammar
    
        is-float          = [ "-" ] FloatNumber
        is-decimal        = [ "-" ] DecimalNumber
        is-integer        = [ "-" ] DecimalInteger
        is-uint           = DecimalInteger
    
        FloatNumber       = DecimalNumber [ ExponentPart ]
        DecimalNumber     = DecimalInteger [ FractionalPart ]
        DecimalInteger    = "0" / ( NonZeroDigit *DecimalDigit )
    
        DecimalDigit      = %x30-39; 0-9
        NonZeroDigit      = %x31-39; 1-9
        FractionalPart    = "." 1*DecimalDigit
        ExponentIndicator = "e" / "E"
        ExponentPart      = ExponentIndicator [ "+" / "-" ] 1*DecimalDigit

  looks_like_number ABNF
        ; ABNF Grammar based on 5.10 Perl_grok_number()
    
        looks-like-number = Number / ZeroButTrue
    
        Number            = *WS [ Sign ] ( FloatNumber / ( Infinity / NaN ) ) *WS;
        FloatNumber       = DecimalNumber [ ExponentPart ]
        DecimalNumber     = DecimalInteger [ "." *DecimalDigit ] / "." 1*DecimalDigit
        DecimalInteger    = 1*DecimalDigit
    
        WS                = %x09 ; HT
                          / %x0A ; LF 
                          / %x0C ; FF
                          / %x0D ; CR
                          / %x20 ; SP
        DecimalDigit      = %x30-39; 0-9
        Sign              = "+" / "-"
        ExponentIndicator = "e" / "E"
        ExponentPart      = ExponentIndicator [ Sign ] 1*DecimalDigit
        Infinity          = "Inf" / "Infinity"
        NaN               = "NaN"
        ZeroButTrue       = %x30.20.62.75.74.20.74.72.75.65 ; 0 but true

EXPORTS
    None by default. Functions and constants can either be imported
    individually or in sets grouped by tag names. The tag names are:

    ":all" exports all functions.
    ":is_int" exports all "is_int" functions.
    ":is_uint" exports all "is_uint" functions.

DIAGNOSTICS
    (F) Usage: %s(string)
        Subroutine %s invoked with wrong number of arguments.

ENVIRONMENT
    Set the environment variable "STRING_NUMERIC_PP" to a true value before
    loading this package to disable usage of XS implementation.

PREREQUISITES
  Run-Time
    perl 5.006 or greater.
    Carp, core module.
    Exporter, core module.

  Build-Time
    In addition to Run-Time:

    Test::More 0.47 or greater, core module since 5.6.2.
    Test::Exception.

SEE ALSO
    String::Numeric::XS

    Data::Types

    Regexp::Common::number

    Scalar::Util

    Scalar::Util::Numeric

AUTHOR
    Christian Hansen "chansen@cpan.org"

COPYRIGHT AND LICENSE
    Copyright 2009 Christian Hansen.

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.