The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Arithmetic-PaperAndPencil-0.01
River stage zero No dependents
/ Arithmetic::PaperAndPencil::Number

NAME

Arithmetic::PaperAndPencil::Number - integer, with elementary operations

VERSION

Version 0.01

SYNOPSIS

    use Arithmetic::PaperAndPencil::Number;

    my $x = Arithmetic::PaperAndPencil::Number->new(radix => 10, value => '9');
    my $y = Arithmetic::PaperAndPencil::Number->new(radix => 10, value => '6');
    my $sum = $x + $y;
    my $pdt = $x * $y;

DESCRIPTION

This class should not be used directly. It is meant to be a utility module for Arithmetic::PaperAndPencil.

Arithmetic::PaperAndPencil::Number is a class storing integer numbers and simulating elementary operations that a pupil learns at school. The simulated operations are the operations an average human being can do in his head, without outside help such as a paper and a pencil.

So, operations are implemented with only very simple numbers. For example, when adding two numbers, at least one of them must have only one digit. And when multiplying numbers, both numbers must have a single digit. Attempting to multiply, or add, two numbers with multiple digits triggers an exception.

An important difference with the average human being: most humans can compute in radix 10 only. Some gifted humans may add or subtract in radix 8 and in radix 16, but they are very few. This module can compute in any radix from 2 to 36.

Another difference with normal human beings: a human can add a single-digit number with a multi-digit number, provided the multi-digit number is not too long. E.g. a human can compute 15678 + 6 and get 15684, but when asked to compute 18456957562365416378 + 6, this human will fail to remember all necessary digits. The module has no such limitations. Or rather, the module's limitations are those of the Perl interpreter and of the host machine.

METHODS

new

An instance of Arithmetic::PaperAndPencil::Number is built by calling method new with two parameters, value and radix. If omitted, radix defaults to 10.

radix

The numerical base, or radix, in which the number is defined.

value

The digits of the number.

chars

The number of chars in the value attribute.

unit

Builds a number (instance of Arithmetic::PaperAndPencil::Number), using the last digit of the input number. For example, when applied to number 1234, the unit method gives 4.

Extended usage: given a $len parameter (positional, optional, default 1), builds a number using the last $len digits of the input number. For example, when applied to number 1234 with parameter 2, the unit method gives 34. When applied to number 1234 with parameter 3, the unit method gives 234.

carry

Builds a number (instance of Arithmetic::PaperAndPencil::Number), using the input number without its last digit. For example, when applied to number 1234, the carry method gives 123.

Extended usage: given a $len parameter (positional, optional, default 1), builds a number, using the input number without its last $len digits. For example, when applied to number 1234 with parameter 2, the carry method gives 12 by removing 2 digits, 34. When applied to number 1234 with parameter 3, the carry method gives 1.

complement

Returns the 10-complement, 2-complement, 16-complement, whatever, of the number. Which complement is returned is determined by the number's radix. The method requires another parameter, to choose the number of digits in the computed complement. This length parameter is a positional parameter.

Example

  radix  = 16     |
  number = BABE   | → complement = FFFF5652
  length = 8      |

square_root

Returns the square root of the objet, rounded down to an integer.

The object must be a single-digit or a double-digit instance of Arithmetic::PaperAndPencil::Number.

is_odd

Returns an integer used as a boolean, 1 if the number is odd, 0 if the number is even.

FUNCTIONS

max_unit

The input parameter is the radix (positional). The function returns the highest single-digit number for this radix. For example, max-unit(10) returns 9 and max-unit(16) returns F.

The returned value is an instance of Arithmetic::PaperAndPencil::Number).

Addition add

Adding two numbers with the same radix. At least one argument must be a single-digit number. This function is used to overload +.

Subtraction minus

Subtracting two numbers with the same radix. Both arguments must be single-digit numbers. This function is used to overload -.

Subtraction adjust_sub

Actually, this is not the plain subtraction. This function receives a 1-digit high number and a 1- or 2-digit low number. It sends back an adjusted high-number and a subtraction result. The adjusted high-number is the first number greater than the low number and in which the unit is the parameter high number.

For example (radix 10):

  high = 1, low = 54 → adjusted-high = 61, result = 7
  high = 8, low = 54 → adjusted-high = 58, result = 4

The parameters are positional.

Multiplication times

Multiplying two numbers with the same radix. Both arguments must be single-digit numbers. This function is used to overload *.

Division divide

Dividing two numbers with the same radix. The first argument must be a single-digit or double-digit number and the second argument must be a single-digit number (and greater than zero, of course).

Numeric Comparison num_cmp

This function interprets the arguments as numbers and returns the 3-way comparison of these numbers. This function overloads <=>, which means that all other numeric comparisons (==, <, <=, etc) are overloaded too.

Alphabetic Comparison alpha_cmp

This function interprets the arguments as strings and returns the 3-way comparison of these strings. This function overloads cmp, which means that all other numeric comparisons (eq, lt, le, etc) are overloaded too.

EXPORT

Functions max_unit and adjust_sub are exported.

AUTHOR

Jean Forget, <J2N-FORGET at orange.fr>

BUGS

Please report any bugs or feature requests to bug-arithmetic-paperandpencil at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Arithmetic-PaperAndPencil. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Arithmetic::PaperAndPencil

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2024 by jforget.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)