Math::PlanePath::Base::Digits -- helpers for digit based paths

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

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

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.

       <http://user42.tuxfamily.org/math-planepath/index.html>

       Copyright 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 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/>.

perl v5.32.0                                       2021-01-23                 Math::PlanePath::Base::Digits(3pm)

       Math::PlanePath::Base::Digits -- helpers for digit based paths

       Math::PlanePath, Math::PlanePath::Base::Generic

       Math::BigInt

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