Note: This module will be deprecated when new module 'Number' is released as version 1.0.0.
use Number::More :ALL;
my $bin = '11001011'; # do not enter any prefix
my $hex = bin2hex $bin;
say $hex; # OUTPUT: 'CB'
This module provides some convenience functions to convert unsigned integers between different, commonly used number bases: decimal, hexadecimal, octal, and binary. There is also a function to convert between bases 2 through 62.
Note that bases greater than 36 will use a set of digits consisting of a case-sensitive set of ASCII characters in an array indexed from 0..base-1, and the reverse mapping is in a hash. Both exported variables are shown in NUMBERS. Also included in that document is more information on other exported variables, number systems (and references), and their use in this module.
The current subroutines are described in detail in SUBS which shows a short description of each exported routine along along with its complete signature.
The functions in this module are recommended for users who don't want to have to deal with the messy code involved with such transformations and who want an easy interface to get the various results they may need.
As an example of the detail involved, any transformation from a non-decimal base to another non-decimal base requires an intermediate step to convert the first non-decimal number to decimal and then convert the decimal number to the final desired base. In addition, adding prefixes, changing to lower-case where appropriate, and increasing lengths will involve more processing.
The following illustrates the process using Raku routines for the example above:
my $bin = '11001011';
# use a sub:
my $dec = parse-base $bin, 2;
# or use a method on $bin:
$dec = $bin.parse-base: 2;
# finally, get the hex value:
my $hex = $dec.base: 16;
say $hex; # OUTPUT 'CB'
The default for each provided function is to take a string (valid decimals may be entered as numbers) representing a valid number in one base and transform it into the desired base with no leading zeroes or descriptive prefix (such as '0x', '0o', and '0b') to indicate the type of number. The default is also to use upper-case characters for the non-decimal characters for all bases greater than 10 and less than 37. Bases greater than 36 use a mixture of upper-case and lower-case characters, so those non-decimal characters are case-sensitive and retain their results..
There is an optional parameter to define desired lengths of results
(which will result in adding leading zeroes if needed). There are
named parameters to have results in lower-case (:$LC) for bases
between 11 and 36 and add appropriate prefixes to transformed numbers
(:$prefix) in bases 2 (binary), 8 (octal), and 16 (hecadecimal).
Note that requested prefixes will take two characters in a
requested length. There is also an option (:$suffix) to add the
appropriate base suffix to any number, the result of which will look
like this (the number itself with the base shown as a trailing subscript in
smaller characters):
'2Zz3' ~ '62'
Attempting to use both a length and a prefix or suffix provides any padding to the left side of the number as leading zeroes. Note use of both :prefix and :suffix will throw an exception. The use of :prefix only affects numbers of bases 2, 8, 10, and 16.
Any length requested that is too short for the number of characters plus any prefix will be silently handled properly by default. However, the user can set an environment variable ('LENGTH_HANDLING') to the desired reponse to situations where the transformed length is greater than the requested length: (1) 'ignore' and provide the required length (the default), (2) 'warn' of the increased length but provide it, or (3) 'fail' to throw an exception and report the offending data.
Interested users are encouraged to contribute improvements and corrections to this module, and pull requests, bug reports, and suggestions are always welcome.
Thanks to 'timotimo' on IRC #perl6 (now #raku) for the suggestion of the name 'rebase' for the general base transformation subroutine.
Artistic 2.0. See LICENSE.
Copyright (C) 2017-2025 Thomas M. Browder, Jr. <tbrowder@acm.org>