---
name: "Math::PlanePath::Base::Digits"
section: "3pm"
platform: "linux"
package: "libmath-planepath-perl"
version: "129-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Math::PlanePath::Base::Digits"
---

# Math::PlanePath::Base::Digits(3pm)

## NAME

Math::PlanePath::Base::Digits -- 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.

## SEE ALSO

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

Math::BigInt

## HOME PAGE

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

## LICENSE

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/\>.