Math::PlanePath::Base::Digits(3) helpers for digit based paths

SYNOPSIS


use Math::PlanePath::Base::Digits 'digit_split_lowtohigh';
foreach my $digit (digit_split_lowtohigh ($n, 16)) {
}

DESCRIPTION

This is a few generic helper functions for paths based on digits or powering.

They're designed to work on plain Perl integers and floats and there's some special case support for "Math::BigInt".

EXPORTS

Nothing is exported by default but each function below can be as in the usual Exporter style,

    use Math::PlanePath::Base::Digits 'round_down_pow';

(But not "parameter_info_radix2()", for the reason described below.)

FUNCTIONS

Generic

"($power, $exponent) = round_up_pow ($n, $radix)"
"($power, $exponent) = round_down_pow ($n, $radix)"
Return the power of $radix equal to or either higher or lower than $n. For example

   ($pow, $exp) = round_down_pow (260, 2);
   # $pow==512  # the next higher power
   # $exp==9    # the exponent in that power
   # 2**9=512 is next above 260
   ($pow, $exp) = round_down_pow (260, 2);
   # $pow==256  # the next lower power
   # $exp==8    # the exponent in that power
   # 2**8=256 is next below 260
"@digits = digit_split_lowtohigh ($n, $radix)"
"@bits = bit_split_lowtohigh ($n)"
Return a list of digits from $n in base $radix, or in binary. For example,

   @digits = digit_split_lowtohigh (12345, 10);
   # @digits = (5,4,3,2,1)   # decimal digits low to high

If "$n==0" then the return is an empty list. The current code expects "$n >= 0".

``lowtohigh'' in the name tries to make it clear which way the digits are returned. "reverse()" can be used to get high to low instead (see ``reverse'' in perlfunc).

"bit_split_lowtohigh()" is the same as "digit_split_lowtohigh()" called with radix=2.

"$n = digit_join_lowtohigh ($arrayref, $radix)"
"$n = digit_join_lowtohigh ($arrayref, $radix, $zero)"
Return a value made by joining digits from $arrayref in base $radix. For example,

   @digits = (5,4,3,2,1)   # decimal digits low to high
   $n = digit_split_lowtohigh (\@digits, 10);
   # $n == 12345

Optional $zero can be a 0 of an overloaded number type such as "Math::BigInt" to give a returned $n of that type.

Subclassing

"$aref = parameter_info_array()"
Return an arrayref of a "radix" parameter, default 2. This is designed to be imported into a PlanePath subclass as its "parameter_info_array()" method.

    package Math::PlanePath::MySubclass;
    use Math::PlanePath::Base::Digits 'parameter_info_array';

The arrayref is

    [ { name      => 'radix',
        share_key => 'radix_2',
        display   => 'Radix',
        type      => 'integer',
        minimum   => 2,
        default   => 2,
        width     => 3,
        description => 'Radix (number base).',
      }
    ]
"$href = Math::PlanePath::Base::Digits::parameter_info_radix2()"
Return the single "radix" parameter hashref from the info above. This can be used when a subclass wants the radix parameter and other parameters too,

    package Math::PlanePath::MySubclass;
    use constant parameter_info_array =>
      [
       { name            => 'something_else',
         type            => 'integer',
         default         => '123',
       },
       Math::PlanePath::Base::Digits::parameter_info_radix2(),
      ];

If the ``description'' part should be more specific or more detailed then it could be overridden with for example

   { %{Math::PlanePath::Base::Digits::parameter_info_radix2()},
     description => 'Radix, for both something and something.',
   },

This function is not exportable since it's meant for a one-off call in an initializer and so no need to import it for repeated use.

LICENSE

Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016 Kevin Ryde

This file is part of Math-PlanePath.

Math-PlanePath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Math-PlanePath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Math-PlanePath. If not, see <http://www.gnu.org/licenses/>.