NAME

Module::Generic::Number - Number Manipulation Object Class

SYNOPSIS

my $n = Module::Generic::Number->new(10);
# or
my $n = Module::Generic::Number->new( 10, 
{
    thousand => ',',
    decimal => '.',
    precision => 2,
    # Currency symbol
    symbol => '€',
    # Display currency symbol before or after the number
    precede => 1,
});
# Even accepts numbers in Japanese double bytes
# Will be converted automatically to regular digits.
my $n = Moule::Generic::Number->new( "−１２３４５６７" ); # becomes -1234567
# or, to get all the defaults based on language code
my $n = Module::Generic::Number->new( 10, 
{
    lang => 'fr_FR',
    # or
    # locale => 'fr_FR',
});
# this would set the decimal separator to ',', the thousand separator to ' ', and precede to 0 (false).
print( "Number is: $n\n" );
# prints: 10

$n ** 2 # 100
# and all other operators work

my $n_neg = Module::Generic::Number->new(-10);
$n_neg->abs # 10
$n->atan # 1.47112767430373
$n->atan2(2) # 1.37340076694502
$n->cbrt # 2.15443469003188
$n->cbrt->ceil # 3
$n->clone # Cloning the number object
$n->cos # -0.839071529076452
$n->currency # €
$n->decimal # .
$n->exp # 22026.4657948067
$n->cbrt->floor # 2
$n *= 100;
$n->format # 1,000.00
$n->format(0) # 1,000
$n->format(
    precision => 0,
    # Boolean value
    decimal_fill => 0,
    thousand => ',',
    decimal => '.',
);
$n->format_binary # 1111101000
my $n2 = $n->clone;
$n2 += 24
$n2->format_bytes # 1K
$n2->format_hex # 0x400
$n2->format_money # € 1,024.00
$n2->format_money( '$' ) # $1,024.00
$n2->format_negative # -1,024.00
$n2->format_picture( '(x)' ) # (1,024.00)
$n2->formatter( $new_Number_Format_object );
$n->from_binary( "1111101000" ) # 1000
$n->from_hex( "0x400" ) # 1000
my $n3 = $n->clone( 3.14159265358979323846 )->int # 3
$n3->is_even # false
$n3->is_odd # true
# Uses POSIX::signbit
$n3->is_negative # 0
$n3->is_positive # 1
$n->log # 6.90775527898214
$n->log2 # 9.96578428466209
$n->log10 # 3
$n->max( 2000 ) # 2000
$n->min( 2000 ) # 1000
$n->mod(3) # 1
my $perm = Module::Generic::Number->new( '0700' );
$perm->oct # 448
printf( "%o\n", 448 ) # 700
$n->clone( 2 )->pow( 3 ) # 8
# Change position of the currency sign
$n->precede( 1 ) # Set it to precede the number
# Change precision
$n->precision( 0 )
# Based on 1000
$n->rand # For example, returns 77.775465338589
$n->rand->int # For example, would return a random integer 77
$n->clone( 3.14159265358979323846 )->round( 4 ) # 3.1416
$n->sin # 0.826879540532003
$n2->sqrt # 32
$n->symbol # €
$n->tan # 1.47032415570272
$n->thousand # ,
$n->unformat( "€ 1,024.00" ) # 1024

VERSION

v2.1.1

DESCRIPTION

The purpos of this class/package is to provide a lightweight object-oriented approach to number manipulation.

This uses perl core functions and POSIX functions only. This module's methods act as a wrapper to them.

The object is overloaded, so it returns the embedded number when used as a string.

print( "I have $n friends\n" );

Would produce: I have 1000 friends

Because the object is overloaded, you can use the variable with any perl operators, such as:

$n /= 2 # 5
$n + 3 # 8
$n **= 2 # $n is now 64
# etc...

Module::Generic::Number also handles infinity and numbers that are not numbers, a.k.a. NaN. Ot uses 2 special classes: Module::Generic::Infinity and Module::Generic::Nan

While NaN is very straightforward, Inf or -Inf is a bit trickier, because although it is not a number, it is still possible to perform some operations. For example :

# Here the use of abs is meaningless, and just to test chaining
$inf->abs->max(10)->floor

Would yield Inf object (Module::Generic::Infinity), but

$inf->abs->max(10)->mod(3)

Would yield a NaN object (Module::Generic::Nan) and of course

$inf->abs->min(10)

Would yield 10 as a Module::Generic::Number object, so the results possibly becomes an object of a different class based on the result.

Operators also works on the infinity object:

my $inf = Module::Generic::Infinity->ne(-Inf);
$inf *= -1 # Yields a new infinity object with value Inf

Those are just basic arithmetics wrapped in object to enable object oriented interface and chaining. It does not do anything special and rely on perl and POSIX for computation, depending on the function.

METHODS

new

Provided with a number, some optional parameters and this returns a new object.

Possible optional parameters are:

decimal

Specifies the decimal separator. This can also be changed or retrieved with the method "decimal"

grouping

The sizes of the groups of digits, except for currency values. unpack( "C*", $grouping ) will give the number in question. This is typically 3.

lang

If provided with a language tag as specified in rfc5646, and this will the number format properties based on the locale dictionary. It uses "setlocale" in POSIX to achieve that, but without disturbing your own locale settings.

WIth the number format properties retrieved, it will populate the other parameters here, if not provided already. For example :

my $n = Module::Generic::Number->new( 1000, { lang => 'fr_FR' });
$n->format # 1.000,00 €

Would set the thousand separator to ., the decimal separator to ,, the currency symbol to € and precede to false.

my $n = Module::Generic::Number->new( 1000, {
    lang => 'fr_FR',
    precede => 1,
});

Uses the standard default format properties, except for precede which we set to true

$n->format # € 1.000,00

When no lang is provided, it uses the default language set in the system to retrieve the number formatting properties.

Any of those properties can be overriden by specifying its value when creating an object.

position_neg

Boolea value to define whether the negative sign (typically "-") should be positioned at the begining (true) or at the end (false) of the negative numbers.

position_pos

Boolea value to define whether the positive sign (typically and empty string) should be positioned at the begining (true) or at the end (false) of the positive numbers.

precede

If set to true, this will set the currency symbol before the number and when set to false, it will set it after the number

This can also be changed or retrieved with the method "precede"

precede_neg

If set to true, this will set the currency symbol before the negative number and when set to false, it will set it after the negative number

This can also be changed or retrieved with the method "precede_neg"

precision

Sets the decimal precision of the number. This can also be changed or retrieved with the method "precision"

sign_neg

The character used to denote negative currency values, usually a minus sign.

sign_pos

The separator between groups of digits before the decimal point, except for currency values.

space

Boolean value to define whether there should be a space between the currency sign and the number value.

space_neg

Boolean value to define whether there should be a space between the currency sign and the number value for negative numbers.

symbol

Sets the currency symbol to be used upon formatting of the number as money with the method "format_money"

This can also be changed or retrieved with the method L</"symbol">

thousand

Sets the thousand separator to be used uppon formatting.

This can also be changed or retrieved with the method L</"thousand">

abs

Return the absolute value of the number object. Same as "abs" in perlfunc

as_array

Return the number object as a Module::Generic::Array object.

as_boolean

Return the number object as a Module::Generic::Boolean object.

as_scalar

Return the number object as a Module::Generic::Scalar object.

as_string

Returns the object string as a string.

my $n = Module::Generic::Number->new( 1000 );
print( "I have $n books\n" );
# I have 1000 books
# But better like ths:
printf( "I have %s bools\n", $n->format( 0 ) );
# I have 1,000 books

atan

Returns the arcus tangent for the number object. See "atan" in POSIX

# Assuming $n is an object for 1000
# atan2( Y, X ). Y = 1000 here
$n->atan2( 20 ) # produces 1.55079899282175

atan2

Returns the arctangent of Y/X in the range -PI to PI. See "atan2" in perlfunc

cbrt

Returns the cube root. See "cbrt" in POSIX

ceil

Returns the smallest integer value greater than or equal to the number object. See "ceil" in POSIX

# Assuming $n is an object for 3.14159265358979323846
$n->ceil # 4

chr

Returns the character matching our number object. See "chr" in perlfunc

# Assuming $n is 74
$n->chr # J

clone

Returns a clone of the current object, keeping its original formatting properties

It can take an optional number that will be used

my $n = Moduke::Generic::Number->new(1000);
# $n is no 1000 with thousand separator set to "","", etc
my $n2 = $n->clone( 2020 );
# Same properties as $n, but now the number is 2020 instead of 1000 and this is a new object

cos

Returns the cosine of the number object. See "cos" in perlfunc

currency

Sets or gets the currency symbol to be used for formatting the number object with "format_money"

decimal

Sets or gets the decimal separator to be used for formatting the number object

decimal_fill

Boolean. Sets or gets whether to pad the decimal with zeroes. This is used in conjonction with "precision"

decode_lconv

Provided with an hash reference that came from POSIX::localeconv, and this will ensure all its non-utf8 values set are properly decoded.

This is especially true for the property currency_symbol

It returns the hash reference upon success, and upon error, it sets an error object and return undef in scalar context, or an empty list in list context.

default

Sets the dictionary (hash reference) of property-value pairs used for the number object formatting.

encoding

Sets or gets the encoding of the data provided by localeconv

There is no reason for you to set or change this value. It is rather meant to be retrieved and is set automatically once the language has been set for this object.

exp

Returns the natural logarithm base to the power of the number object. See "exp" in perlfunc

# Assuming the number object is 2
$n->exp # 7.38905609893065

floor

Returns the largest integer value less than or equal to the number object. See "floor" in POSIX

# Assuming $n is an object for 3.14159265358979323846
$n->ceil # 3

format

Provided with an optional precision and this format the number in a human readable way using thousand and decimal separators and floating number precision

$n->format # 1,000.00
$n->format(
    precision => 2,
    # Override object value
    thousand => ',',
    decimal => '.',
    # Boolean
    decimal_fill => 1,
);

If the number is too large or great to work with as a regular number, but instead must be shown in scientific notation, returns that number in scientific notation without further formatting.

Module::Generic::Number->new("0.000020000E+00")->format(7); # 2e-05

It returns a scalar object upon success or an error if an error occurred.

format_binary

# Assuming the number object is 1000
$n->format_binary # 1111101000

format_bytes

# Assuming the number object is 1,234,567
$n->format_bytes # 1.18M

Provided with an hash or hash reference of options, and this formats number with suffix K, M or G depending if it exceeds gigabytes, megabytes or kilobytes; or the IEC standard 60027 KiB, MiB, or GiB depending on the option mode

It returns a scalar object upon success or an error if an error occurred.

The following options are supported:

base

Sets the number at which the suffix set with "kilo_suffix" is added. Default is 1024. Set to any value; the only other useful value is probably 1000.

If the mode (see below) is set to iec or iec60027 then setting the base option returns an error.
mode

This can be trad, traditional, iec or iec60027
precision

The decimal precision. Defaults to the value set with "precision"
unit

By default, this is guessed based on the value of the number, but can be explicitly specified here.

In other words, numbers greater than or equal to 1024 (or other number given by the base option) will be divided by 1024 and suffix set with "kilo_suffix" or "kibi_suffix" added; if greater than or equal to 1048576 (1024*1024), it will be divided by 1048576 and suffix set with "mega_suffix" or "mebi_suffix" appended to the end; etc.

Possible values are: auto (default), kilo, mega, giga

If a value other than auto is specified, that value will be used instead no matter the number. For example:
```
Module::Generic::Number->new( 1048576 )->format_bytes( unit => 'k' );
# Produces 1,024K and not 1M
```

format_hex

# Assuming the number object is 1000
$n->format_hex # 0x3E8

format_money

Provided with an optional precision, and an optional currency symbol and this format the number accordingly. It uses the object initial value set with "precision" and "currency" if not explicitly specified. object, using the inital format parameters specified during object instantiation.

# Assuming the number object is 1000
$n->format_money # € 1,000.00
$n->format_money(3) # € 1,000.000

It returns a scalar object upon success or an error if an error occurred.

format_negative

Provided with an optional format, or by default uses the value set with "neg_format" which must include the character x and this format the number object, assuming it is negative.

For example, suitable for accounting:

$n->format_negative( '(x)' ); # (1,000)

It returns a scalar object upon success or an error if an error occurred.

format_picture

Format the string based on the pattern provided, which will have the # characters replaced by the digits from the number.

$n->format_picture( '##,###.##' ); # 1,000.00

If the length of the integer part of $number is too large to fit, the # characters are replaced with asterisks (*) instead. For examples:

# Assuming 100023
$n->format_picture( 'EUR ##,###.##' ); # EUR **,***.**
# Assuming 1.00023
$n->format_picture( 'EUR #.###,###' ); # EUR 1.002,300

The comma , and period . used in the example above are taken from the value set with "thousand" and "decimal" respectively. However, the thousand characters in the picture provided, does not need to occur every three digits; the only use of that variable by this function is to remove leading commas (see the first example above).

There may not be more than one instance of decimal in the picture provided though, or an error will be returned.

It returns a scalar object upon success or an error if an error occurred.

from_binary

Returns a number object based on a binary number.

my $n2 = $n->from_binary( "1111101000" ); # 1000

from_hex

Returns a number object based on an hex number.

my $n2 = $n->from_hex( "0x400" ); # 1024

gibi_suffix

Sets or gets the gibi suffix.

giga_suffix

Sets or gets the gigabytes suffix.

grouping

The sizes of the groups of digits, except for currency values. unpack( "C*", $grouping ) will reveal the number in question.

int

Returns the integer portion of the number object. See "int" in perlfunc for more details.

# Assuming $n is an object for 3.14159265358979323846
$n->int # 3

is_decimal

Returns true if the number is a decimal number.

is_empty

Returns true if the length of the underlying number is zero. This always returns true, because an instance of this class can never be undef. This is here for consistency with other classes of Module::Generic

is_even

Returns true if the number is even, i.e. if the modulus of the number divided by 2 is 0.

See "is_odd"

is_finite

Rturns true if the number is finite, i.e. not infinity. See "isfinite" in POSIX

is_float

Returns true if the number is a floating decimal number. It uses "modf" in POSIX to find out.

is_infinite

Rturns true if the number is infinite. See "isinf" in POSIX

is_int

Returns true if the number is an integer. It uses "modf" in POSIX to find out.

is_nan

Returns true if the number is not a number, i.e. NaN. See "isnan" in POSIX

is_neg

Alias for /is_negative

is_negative

Returns true if the number object is negative, false otherwise. See "signbit" in POSIX

is_normal

Returns true if the argument is normal (that is, not a subnormal/denormal, and not an infinity, or a not-a-number). See "isnormal" in POSIX

is_odd

Returns true if the number is odd, i.e. if the modulus of the number divided by 2 is 1.

See "is_even"

is_pos

Alias for "is_positive"

is_positive

Returns true if the number object is positive, false otherwise. See "signbit" in POSIX

kibi_suffix

Sets or gets the kibi suffix.

kilo_suffix

Sets or gets the kilobytes suffix.

lang

Returns the current language used for the number formatting properties.

length

Returns the number of digits this number object contains. The value returned is a Module::Generic::Number object

locale

Same as "lang"

log

Returns the natural logarithm of the number object. See "log" in perlfunc for more details.

$n->log # 6.90775527898214

log2

Logarithm base two of the number object. See "log2" in POSIX for more details.

$n->log2 # 9.96578428466209

log10

Returns the 10-base logarithm of the number object. See "log10" in POSIX for more details.

$n->log10 # 3

max

Returns the highest number of either the number object, or the additional number provided as arguement. If the latter is undef, the number object is returned. See "fmax" in POSIX

$n->max( 2000 ) # 2000

Returns the lowest number of either the number object, or the additional number provided as arguement. If the latter is undef, the number object is returned. See "fmin" in POSIX

$n->min( 2000 ) # 2000

mebi_suffix

Sets or gets the mebi suffix.

mega_suffix

Sets or gets the megabytes suffix.

min

Provided with another number and this returns the smallest of the two as an Module::Generic::Number object.

neg_format

Sets or gets the format for formatting negative numbers.

Returns a scalar object

mod

Returns the remainder for the number bject divided by another number provided as additional argument. See "fmod" in POSIX for more details.

# Assuming 1000
$n->mod(3) # 1

oct

Provided an octal value, this returns the corresponding number as an object. See "oct" in perlfunc for more details.

position_neg

Set to true or false if the negative sign (typically "-") should be positioned at the begining (true) or at the end (false) of the number.

position_pos

Set to true or false if the positive sign (typically "", i.e. empty, but could be set to "+") should be positioned at the begining (true) or at the end (false) of the number.

pow

Returns the number object to the power of the number provided as arguments. See "pow" in POSIX for more details.

# Assuming $n is an object representing 2
$n->pow( 3 ) # 8

precede

Sets or gets the precede property of this object. This is used by Number::Format to determine if the currency symbol should be set before or after the number

precede_neg

Sets or gets the precede_neg property of this object. This is used by Number::Format to determine if the currency symbol should be set before or after the number when it is a negative number.

precede_pos

Sets or gets the property value for precede.

1 if the currency symbol precedes the currency value for nonnegative values, 0 if it follows.

precision

Sets or gets the floating precision of the number.

# Assuming $n is an object for 3.14159265358979323846
$n->precision( 4 );
$n->format # 3.1416

rand

Returns a random fractional number greater than or equal to 0 and less than the value of the number object. See "rand" in perlfunc for more information.

round

Provided with an optional precision, this will round the number object. Internally it uses "sprintf" in perldoc to achieve that.

This returns an error if more than 1 argument was provided. To use two arguments, use "round2"

round_zero

This will round the number using "round" in POSIX, which will return "the integer (but still as floating point) nearest to the argument"

round2

Provided with a number and an optional precision, or by default the one set with "precision", and this will round the number using an alternative approach based on "round" in Number::Format.

scalar

Same as "as_string". This forces the return of the object as a raw number.

sign_neg

Sets or gets the sign_neg property of this object. The character used to denote negative currency values, usually a minus sign.

sign_pos

Sets or gets the sign_pos property of this object. The character used to denote nonnegative currency values, usually the empty string.

sin

Returns the sine of the number object. See "sine" in perlfunc for more details.

space

Sets or gets the space property of this object. 1 if a space is inserted between the currency symbol and the currency value for non-negative values, 0 otherwise.

space_neg

Sets or gets the space_neg property of this object. 1 if a space is inserted between the currency symbol and the currency value for negative values, 0 otherwise.

space_pos

Sets or gets the space property. 1 if a space is inserted between the currency symbol and the currency value for nonnegative values, 0 otherwise.

sqrt

Return the positive square root of the number object. See "sqrt" in perlfunc for more details.

symbol

Set or gets the currency symbol to be used in "format_money"

tan

Returns the tangent of the number object. See "tan" in POSIX for more details.

thousand

Set or gets the thousand separator used in formatting the number.

TO_JSON

Special method called by JSON to transform this object into a string suitable to be added in a json data.

unformat

Provided with a string containing a number, and an optional hash or hash reference of options, and this returns a number as a Module::Generic::Number object.

It returns an error if the string provided does not contain any number.

my $n = Module::Generic::Number->unformat('USD 12.95'); # 12.95
# Same
my $n = $n1->unformat('USD 12.95'); # 12.95
my $n = Module::Generic::Number->unformat('USD 12.00'); # 12
my $n = Module::Generic::Number->unformat('foobar'); # return error (undef)
my $n = Module::Generic::Number->unformat('1234-567@.8'); # 1234567.8

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.

To install Module::Generic, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Module::Generic

CPAN shell

perl -MCPAN -e shell
install Module::Generic

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)