NAME

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

SYNOPSIS

use Arithmetic::PaperAndPencil::Number;
my $x = Arithmetic::PaperAndPencil::Number.new(value => '9', radix => 13);
my $y = Arithmetic::PaperAndPencil::Number.new(value => '6', radix => 13);
my $sum = $x ☈+ $y;
say $sum;
my $pdt = $x ☈× $y;
say $pdt;

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 Raku 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.

gist

Just display the value. The radix is not displayed.

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 a boolean, True if the number is odd, False 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

Infix function ☈+. At least one argument must be a single-digit number.

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.

Subtraction, ☈-

Infix function ☈-. Both arguments must be single-digit numbers. This is the plain subtraction.

Multiplication

Infix function ☈×. Both arguments must be single-digit numbers.

Division

Infix function ☈÷. 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).

Comparisons

Infix function < ☈<=> > 3-way numerical comparison or right-aligned comparison.

Infix function ☈leg 3-way alphabetical comparison or left-aligned comparison.

Infix functions C<< ☈< >> and < ☈≤ > numerical comparisons or right-aligned comparisons.

Infix function ☈lt alphabetical comparison or left-aligned comparison.

The arguments can have any length.

REMARKS

Why the thunderstorm symbol? First I cannot use plain + and plain × both for Arithmetic::PaperAndPencil::Number and for core Int. So I had to adopt a different syntax. And I chose the thunderstorm symbol to represent the cerebral activity in a human brain when computing the results. Do you have a better idea? Dingbats accepted, emojis rejected.

AUTHOR

Jean Forget <[email protected]>

COPYRIGHT AND LICENSE

Copyright 2023, 2024 Jean Forget

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.