Module::Generic::Number - Number Manipulation Object Class
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, }); # or, to get all the defaults based on language code my $n = Module::Generic::Number->new( 10, { lang => '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_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 $fmt = $n->new_formatter({ thousand => '.', decimal => ',', symbol => '€', precision => 2, precede => 0, }); 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
v1.0.1
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
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 :
Inf
-Inf
# 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.
10
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.
Provided with a number, some optional parameters and this returns a new object.
Possible optional parameters are:
Specifies the decimal separator. This can also be changed or retrieved with the method "decimal"
The sizes of the groups of digits, except for currency values. unpack( "C*", $grouping ) will give the number in question. This is typically 3.
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.
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.
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.
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"
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"
Sets the decimal precision of the number. This can also be changed or retrieved with the method "precision"
The character used to denote negative currency values, usually a minus sign.
The separator between groups of digits before the decimal point, except for currency values.
Boolean value to define whether there should be a space between the currency sign and the number value.
Boolean value to define whether there should be a space between the currency sign and the number value for negative numbers.
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">
Sets the thousand separator to be used uppon formatting.
This can also be changed or retrieved with the method L</"thousand">
Return the absolute value of the number object. Same as "abs" in perlfunc
Return the number object as a Module::Generic::Array object.
Return the number object as a Module::Generic::Boolean object.
Return the number object as a Module::Generic::Scalar object.
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
Returns the arctangent of Y/X in the range -PI to PI. See "atan2" in perlfunc
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
Returns the cube root. See "cbrt" in POSIX
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
Returns the character matching our number object. See "chr" in perlfunc
# Assuming $n is 74 $n->chr # J
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
Returns the cosine of the number object. See "cos" in perlfunc
Sets or gets the currency symbol to be used for formatting the number object with "format_money"
Sets or gets the decimal separator to be used for formatting the number object
Sets the dictionary (hash reference) of property-value pairs used for the number object formatting.
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
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
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
# Assuming the number object is 1000 $n->format_binary # 1111101000
# Assuming the number object is 1,234,567 $n->format_bytes # 1.18M
# Assuming the number object is 1000 $n->format_hex # 0x3E8
Provided with an optional precision, this format the number object, using the inital format parameters specified during object instantiation.
# Assuming the number object is 1000 $n->format_money # € 1,000.00
Provided with a format which must includes the character x and this format the number object, assuming it is negative.
x
For example, suitable for accounting:
$n->format_negative( '(x)' ); # (1,000)
Format the string based on the patter provided
$n->format_picture( '##,###.##' ); # 1,000.00
Sets or gets the Number::Format object used for formatting.
Returns a number object based on a binary number.
my $n2 = $n->from_binary( "1111101000" ); # 1000
Returns a number object based on an hex number.
my $n2 = $n->from_hex( "0x400" ); # 1024
The sizes of the groups of digits, except for currency values. unpack( "C*", $grouping ) will reveal the number in question.
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
Returns true if the number is a decimal number.
Returns true if the number is even, i.e. if the modulus of the number divided by 2 is 0.
See "is_odd"
Rturns true if the number is finite, i.e. not infinity. See "isfinite" in POSIX
Returns true if the number is a floating decimal number. It uses "modf" in POSIX to find out.
Rturns true if the number is infinite. See "isinf" in POSIX
Returns true if the number is an integer. It uses "modf" in POSIX to find out.
Returns true if the number is not a number, i.e. NaN. See "isnan" in POSIX
Alias for /is_negative
Returns true if the number object is negative, false otherwise. See "signbit" in POSIX
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
Returns true if the number is odd, i.e. if the modulus of the number divided by 2 is 1.
See "is_even"
Alias for "is_positive"
Returns true if the number object is positive, false otherwise. See "signbit" in POSIX
Returns the current language used for the number formatting properties.
Returns the number of digits this number object contains. The value returned is a Module::Generic::Number object
Same as "lang"
Returns the natural logarithm of the number object. See "log" in perlfunc for more details.
$n->log # 6.90775527898214
Logarithm base two of the number object. See "log2" in POSIX for more details.
$n->log2 # 9.96578428466209
Returns the 10-base logarithm of the number object. See "log10" in POSIX for more details.
$n->log10 # 3
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
Provided with another number and this returns the smallest of the two as an Module::Generic::Number object.
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
Given an optional hash of parameters similar to the oens provided to "new" and this return a new Number::Format object or undef with an "error" in Module::Generic set upon error
Provided an octal value, this returns the corresponding number as an object. See "oct" in perlfunc for more details.
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.
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.
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
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
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.
Sets or gets the property value for precede.
1 if the currency symbol precedes the currency value for nonnegative values, 0 if it follows.
Sets or gets the floating precision of the number.
# Assuming $n is an object for 3.14159265358979323846 $n->precision( 4 ); $n->format # 3.1416
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.
Provided with an optional precision, this will round the number object. Internally it uses "sprintf" in perldoc to achieve that.
This will round the number using "round" in POSIX, which will return "the integer (but still as floating point) nearest to the argument"
Round the number using "round" in Number::Format. It will pass through whatever argument that is provided.
Same as "as_string". This forces the return of the object as a raw number.
Sets or gets the sign_neg property of this object. The character used to denote negative currency values, usually a minus sign.
Sets or gets the sign_pos property of this object. The character used to denote nonnegative currency values, usually the empty string.
Returns the sine of the number object. See "sine" in perlfunc for more details.
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.
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.
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.
Return the positive square root of the number object. See "sqrt" in perlfunc for more details.
Set or gets the currency symbol to be used in "format_money"
Returns the tangent of the number object. See "tan" in POSIX for more details.
Set or gets the thousand separator used in formatting the number.
Special method called by JSON to transform this object into a string suitable to be added in a json data.
Provided with a string containing a number, and this returns a number as a Module::Generic::Number object.
Module::Generic::Scalar, Module::Generic::Array, Module::Generic::Boolean, Module::Generic::Hash, Module::Generic::Dynamic
Math::BigInt
Jacques Deguest <jack@deguest.jp>
Copyright (c) 2000-2020 DEGUEST Pte. Ltd.
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.