.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Scalar::Number 3pm" .TH Scalar::Number 3pm "2011-11-15" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Scalar::Number \- numeric aspects of scalars .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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; .Ve .SH "DESCRIPTION" .IX Header "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. .PP This module provides functions to extract the numeric part of a scalar, classify a number by expressibility, and compare numbers across representations. .PP This module is implemented in \s-1XS\s0, with a pure Perl backup version for systems that can't handle \s-1XS\s0. .SH "FUNCTIONS" .IX Header "FUNCTIONS" Each \*(L"sclnum_\*(R" function takes one or more scalar numeric arguments to operate on. These arguments must be numeric; giving non-numeric arguments will cause mayhem. See \*(L"is_number\*(R" 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. .SS "Decomposition" .IX Subsection "Decomposition" .IP "scalar_num_part(\s-1SCALAR\s0)" 4 .IX Item "scalar_num_part(SCALAR)" Extracts the numeric value of \s-1SCALAR\s0, and returns it as a pure numeric scalar. The argument is permitted to be any scalar. .Sp 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. .Sp 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. .SS "Classification" .IX Subsection "Classification" .IP "sclnum_is_natint(\s-1VALUE\s0)" 4 .IX Item "sclnum_is_natint(VALUE)" Returns a truth value indicating whether the provided \s-1VALUE\s0 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. .IP "sclnum_is_float(\s-1VALUE\s0)" 4 .IX Item "sclnum_is_float(VALUE)" Returns a truth value indicating whether the provided \s-1VALUE\s0 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. .SS "Comparison" .IX Subsection "Comparison" .IP "sclnum_val_cmp(A, B)" 4 .IX Item "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 \*(L"not comparable\*(R" situation arises if either value is a floating point NaN (not-a-number). All flavours of zero compare equal. .Sp 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. .IP "sclnum_id_cmp(A, B)" 4 .IX Item "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. .Sp 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. .Sp In addition to sorting, this function can be useful to check for a zero of a particular sign. .SH "BUGS" .IX Header "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 \s-1XS\s0 version works fine. This problem is resolved by Perl 5.8's new numeric semantics. .SH "SEE ALSO" .IX Header "SEE ALSO" Data::Float, Data::Integer, \&\fIperlnumber\fR\|(1) .SH "AUTHOR" .IX Header "AUTHOR" Andrew Main (Zefram) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (C) 2007, 2009, 2010 Andrew Main (Zefram) .SH "LICENSE" .IX Header "LICENSE" This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.