Provided by: libscalar-number-perl_0.006-1build2_amd64 bug

NAME

       Scalar::Number - numeric aspects of scalars

SYNOPSIS

               use Scalar::Number qw(scalar_num_part);

               $num = scalar_num_part($scalar);

               use Scalar::Number qw(sclnum_is_natint sclnum_is_float);

               if(sclnum_is_natint($value)) { ...
               if(sclnum_is_float($value)) { ...

               use Scalar::Number qw(sclnum_val_cmp sclnum_id_cmp);

               @sorted_nums = sort { sclnum_val_cmp($a, $b) } @floats;
               @sorted_nums = sort { sclnum_id_cmp($a, $b) } @floats;

DESCRIPTION

       This module is about the numeric part of plain (string) Perl scalars.  A scalar has a
       numeric value, which may be expressed in either the native integer type or the native
       floating point type.  Many values are expressible both ways, in which case the exact
       representation is insignificant.  To fully understand Perl arithmetic it is necessary to
       know about both of these representations, and the differing behaviours of numbers
       according to which way they are expressible.

       This module provides functions to extract the numeric part of a scalar, classify a number
       by expressibility, and compare numbers across representations.

       This module is implemented in XS, with a pure Perl backup version for systems that can't
       handle XS.

FUNCTIONS

       Each "sclnum_" function takes one or more scalar numeric arguments to operate on.  These
       arguments must be numeric; giving non-numeric arguments will cause mayhem.  See
       "is_number" in Params::Classify for a way to check for numericness.  Only the numeric
       value of the scalar is used; the string value is completely ignored, so dualvars are not a
       problem.

   Decomposition
       scalar_num_part(SCALAR)
           Extracts the numeric value of SCALAR, and returns it as a pure numeric scalar.  The
           argument is permitted to be any scalar.

           Every scalar has both a string value and a numeric value.  In pure string scalars,
           those resulting from string literals or string operations, the numeric value is
           determined from the string value.  In pure numeric scalars, those resulting from
           numeric literals or numeric operations, the string value is determined from the
           numeric value.  In the general case, however, a plain scalar's string and numeric
           values may be set independently, which is known as a dualvar.  Non-plain scalars,
           principally references, determine their string and numeric values in other ways, and
           in particular a reference to a blessed object can stringify and numerify however the
           class wishes.

           This function does not warn if given an ostensibly non-numeric argument, because the
           whole point of it is to extract the numeric value of scalars that are not pure
           numeric.

   Classification
       sclnum_is_natint(VALUE)
           Returns a truth value indicating whether the provided VALUE can be represented in the
           native integer data type.  If the floating point type includes signed zeroes then they
           do not qualify; the only zero representable in the integer type is unsigned.

       sclnum_is_float(VALUE)
           Returns a truth value indicating whether the provided VALUE can be represented in the
           native floating point data type.  If the floating point type includes signed zeroes
           then an unsigned zero (from the native integer type) does not qualify.

   Comparison
       sclnum_val_cmp(A, B)
           Numerically compares the values A and B.  Integer and floating point values are
           compared correctly with each other, even if there is no available format in which both
           values can be accurately represented.  Returns -1, 0, +1, or undef, indicating whether
           A is less than, equal to, greater than, or not comparable with B.  The "not
           comparable" situation arises if either value is a floating point NaN (not-a-number).
           All flavours of zero compare equal.

           This is very similar to Perl's built-in <=> operator.  The only difference is the
           capability to compare integer against floating point (where neither can be represented
           exactly in the other's format).  <=> performs such comparisons in floating point,
           losing accuracy of the integer value.

       sclnum_id_cmp(A, B)
           This is a comparison function supplying a total ordering of scalar numeric values.
           Returns -1, 0, or +1, indicating whether A is to be sorted before, the same as, or
           after B.

           The ordering is of the identities of numeric values, not their numerical values.  If
           floating point zeroes are signed, then the three types (positive, negative, and
           unsigned) are considered to be distinct.  NaNs compare equal to each other, but
           different from all numeric values.  The exact ordering provided is mostly numerical
           order: NaNs come first, followed by negative infinity, then negative finite values,
           then negative zero, then unsigned zero, then positive zero, then positive finite
           values, then positive infinity.

           In addition to sorting, this function can be useful to check for a zero of a
           particular sign.

BUGS

       In Perl 5.6, if configured with a wider-than-usual native integer type such that there are
       native integers that can't be represented exactly in the native floating point type, it is
       not always possible to distinguish between integer and floating point values in pure Perl
       code.  In order to get the full benefit of either type, one is expected (by the numeric
       semantics) to know in advance which of them one is using.  The pure Perl version of this
       module can't operate on such a system, but the XS version works fine.  This problem is
       resolved by Perl 5.8's new numeric semantics.

SEE ALSO

       Data::Float, Data::Integer, perlnumber(1)

AUTHOR

       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

       Copyright (C) 2007, 2009, 2010 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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