/ 
String-Numeric-0.9
River stage one • 4 direct dependents • 8 total dependents
/ String::Numeric

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.