POD AN::Tools::Math: Difference between revisions

From Alteeve Wiki
Jump to navigation Jump to search
(Created page with '{{mod_header}} {{footer}}')
 
No edit summary
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
{{mod_header}}
{{mod_header}}
==NAME==
AN::Tools::Math
This is the mathmatical (and general number-based methods) module in the AN::Tools suite. Please do not directly access it, but instead access it's methods via the parent AN::Tools module. The methods provided by this method are described below.
==SYNOPSIS==
<source lang="perl">
  use AN::Tools;
  # Get a common object handle on all AN::Tools::* modules.
  my $an=AN::Tools->new();
 
  # Access this module's methods using '$an->Math->method()' syntax.
  my $rounded=$an->Math->round({
          number        =>      10.245,
          places        =>      2
  });
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.25]"
</source>
==DESCRIPTION==
This module provides access to the mathmatical and other number-type methods in the AN::Tools suite. Please see each method's sections below.
==NOTES==
All AN::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.
==METHODS==
Below are the detailed usage instructions for the methods provided by this module.
===round===
====Example====
<source lang="perl">
  # Round a number to two places after the decimal.
  my $real_number=10.63295;
  my $places=2;
  my $rounded=$an->Math->round({
          number        =>      $real_number,
          places        =>      $places
  });
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.63]"
 
  # Alternatively, to save space, you can pass the number and places directly
  # in the following order:
  my $rounded=$an->Math->round($real_number, $places);
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.63]"
</source>
====Details====
Takes a number (signed float) with an arbitrary number of digits after the decimal place and a number of places after the decimal to round it to (default is '0') and return a properly rounded value. This methods works by looking at each digit, from least significant and working back, and deciding whether the preceding value needs to be incremented or not. As such, it's probably quite slow compared to 'ceil' or 'floor', or other types of rounding/truncating functions, but it is financially accurate and it has no limit on the number of places after the decimal you give it.
====Parameters====
=====<tt>number</tt>=====
This can be any signed real number. It may have commas, however, the returned rounded number will have it's commas removed. It may contain one period denoting the decimal place and may contain a sign at the beginning of the number; (-) to denote negative number and (+) or no prefix to denote a positive number. Any other character found in this paramete will trigger a fatal error.
=====<tt>places</tt>=====
Default: 0
This can be a simple unsigned integer to define how many places after the decimal place to round the <tt>number</tt> paramter value to. If this is longer than the number of places after the decimal passed in then the returned number will have up to this number of '0' padded onto the fractional portion of the number.
==SEE ALSO==
Other modules in the AN::Tools suite:
AN&#58;&#58;Tools
AN&#58;&#58;Tools&#58;&#58;Alert
AN&#58;&#58;Tools&#58;&#58;Readable
AN&#58;&#58;Tools&#58;&#58;String
==LICENSE==
<code>
Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
</code>


{{footer}}
{{footer}}

Latest revision as of 03:45, 20 September 2009

 AN!Tools :: AN::Tools :: POD AN::Tools::Math

NAME

AN::Tools::Math

This is the mathmatical (and general number-based methods) module in the AN::Tools suite. Please do not directly access it, but instead access it's methods via the parent AN::Tools module. The methods provided by this method are described below.

SYNOPSIS

  use AN::Tools;
 
  # Get a common object handle on all AN::Tools::* modules.
  my $an=AN::Tools->new();
  
  # Access this module's methods using '$an->Math->method()' syntax.
  my $rounded=$an->Math->round({
          number        =>      10.245,
          places        =>      2
  });
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.25]"

DESCRIPTION

This module provides access to the mathmatical and other number-type methods in the AN::Tools suite. Please see each method's sections below.

NOTES

All AN::Tools::* modules expects the data they receive to be in UTF-8 encoded format. Likewise, they return UTF-8 encoded strings. If you are getting weird output or are seeing a "wide character in print" error, check that you are not getting double-encoded UTF-8 strings by casting your data as UTF-8 in the first place.

METHODS

Below are the detailed usage instructions for the methods provided by this module.

round

Example

  # Round a number to two places after the decimal.
  my $real_number=10.63295;
  my $places=2;
  my $rounded=$an->Math->round({
          number        =>      $real_number,
          places        =>      $places
  });
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.63]"
  
  # Alternatively, to save space, you can pass the number and places directly
  # in the following order:
  my $rounded=$an->Math->round($real_number, $places);
  print "Rounded: [$rounded]\n";        # Prints "Rounded: [10.63]"

Details

Takes a number (signed float) with an arbitrary number of digits after the decimal place and a number of places after the decimal to round it to (default is '0') and return a properly rounded value. This methods works by looking at each digit, from least significant and working back, and deciding whether the preceding value needs to be incremented or not. As such, it's probably quite slow compared to 'ceil' or 'floor', or other types of rounding/truncating functions, but it is financially accurate and it has no limit on the number of places after the decimal you give it.

Parameters

number

This can be any signed real number. It may have commas, however, the returned rounded number will have it's commas removed. It may contain one period denoting the decimal place and may contain a sign at the beginning of the number; (-) to denote negative number and (+) or no prefix to denote a positive number. Any other character found in this paramete will trigger a fatal error.

places

Default: 0

This can be a simple unsigned integer to define how many places after the decimal place to round the number paramter value to. If this is longer than the number of places after the decimal passed in then the returned number will have up to this number of '0' padded onto the fractional portion of the number.

SEE ALSO

Other modules in the AN::Tools suite:

AN::Tools
AN::Tools::Alert
AN::Tools::Readable
AN::Tools::String

LICENSE

Copyright (c) 2009 Alteeve's Niche!. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support
Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.