michael@0: # This Source Code Form is subject to the terms of the Mozilla Public
michael@0: # License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0: # file, You can obtain one at http://mozilla.org/MPL/2.0/.
michael@0: 
michael@0: =head1 NAME
michael@0: 
michael@0:  basecvt - radix conversion for arbitrary precision integers
michael@0: 
michael@0: =head1 SYNOPSIS
michael@0: 
michael@0:  basecvt <ibase> <obase> [values]
michael@0: 
michael@0: =head1 DESCRIPTION
michael@0: 
michael@0: The B<basecvt> program is a command-line tool for converting integers
michael@0: of arbitrary precision from one radix to another.  The current version
michael@0: supports radix values from 2 (binary) to 64, inclusive.  The first two
michael@0: command line arguments specify the input and output radix, in base 10.
michael@0: Any further arguments are taken to be integers notated in the input
michael@0: radix, and these are converted to the output radix.  The output is
michael@0: written, one integer per line, to standard output.
michael@0: 
michael@0: When reading integers, only digits considered "valid" for the input
michael@0: radix are considered.  Processing of an integer terminates when an
michael@0: invalid input digit is encountered.  So, for example, if you set the
michael@0: input radix to 10 and enter '10ACF', B<basecvt> would assume that you
michael@0: had entered '10' and ignore the rest of the string.
michael@0: 
michael@0: If no values are provided, no output is written, but the program
michael@0: simply terminates with a zero exit status.  Error diagnostics are
michael@0: written to standard error in the event of out-of-range radix
michael@0: specifications.  Regardless of the actual values of the input and
michael@0: output radix, the radix arguments are taken to be in base 10 (decimal)
michael@0: notation.
michael@0: 
michael@0: =head1 DIGITS
michael@0: 
michael@0: For radices from 2-10, standard ASCII decimal digits 0-9 are used for
michael@0: both input and output.  For radices from 11-36, the ASCII letters A-Z
michael@0: are also included, following the convention used in hexadecimal.  In
michael@0: this range, input is accepted in either upper or lower case, although
michael@0: on output only lower-case letters are used.
michael@0: 
michael@0: For radices from 37-62, the output includes both upper- and lower-case
michael@0: ASCII letters, and case matters.  In this range, case is distinguished
michael@0: both for input and for output values.
michael@0: 
michael@0: For radices 63 and 64, the characters '+' (plus) and '/' (forward
michael@0: solidus) are also used.  These are derived from the MIME base64
michael@0: encoding scheme.  The overall encoding is not the same as base64,
michael@0: because the ASCII digits are used for the bottom of the range, and the
michael@0: letters are shifted upward; however, the output will consist of the
michael@0: same character set.
michael@0: 
michael@0: This input and output behaviour is inherited from the MPI library used
michael@0: by B<basecvt>, and so is not configurable at runtime.
michael@0: 
michael@0: =head1 SEE ALSO
michael@0: 
michael@0:  dec2hex(1), hex2dec(1)
michael@0: 
michael@0: =head1 AUTHOR
michael@0: 
michael@0:  Michael J. Fromberger <sting@linguist.dartmouth.edu>
michael@0:  Thayer School of Engineering, Hanover, New Hampshire, USA