Documentation for: base-convert.r

1. Version/History

• Sunanda
• 1-aug-2004
• Version: 0.0.1
• License: GPL

2. Introduction

REBOL offers enbase and debase for conversions between base 10 and bases 64, 16, and 2.

That omits base-8 -- octal -- which is a useful one. And it omits all other bases.

This set of functions corrects that by offering (out of the box) conversions to any base up to base-36. (See Customisation for handling bases larger than 36).

3. Quick examples

3.1. Loading the function:

    do %base-convert.r
 

3.2. Converting to other bases from base-10

   base-convert/to-base 99 2   ;; 99 in binary
   == "1100011"
   base-convert/to-base 999 8 ;; 999 in octal
   == "1747"
   base-convert/to-base 14600926 16  ;; large number in hex
   == "DECADE"
   base-convert/to-base 1024 29  ;; 1024 in base 29
   == "169"
   base-convert/to-base 177 "#@"  ;; 177 in base-2 using "#" and "@" rather than 0 and 1
   == "@#@@###@"
 

3.3. Converting from other bases to base-10

   base-convert/from-base "4444" 5  ;;"4444" in base 5
   == 624
   base-convert/from-base "1000000000000000000000001" 2
   == 16777217
   base-convert/from-base "AA" 31  ;; "AA" in base 31 (310 + 10)
   == 320
 

4. Functions in detail

There are two functions for general public use:

• base-convert/to-base -- takes a decimal and rebases it
• base-convert/from-base -- takes a number in any base and decimalises it

4.1. base-convert/to-base

Call format is:

    base-convert/to-base decimal base
 

4.1.1. decimal

is the number you want to convert

4.1.2. base

is the base you want it in. You can specify this in two ways:

• as an integer 2-36 -- meaning bases 2 through 36 respectively
• as a string with the digits you want to use:
  • 01234 -- would be the same as 5 for base-5
  • XY -- means base-2, but using X for 0 and Y for 1
  • 0123456789TE -- base-12 using T and E rather than the default A and B

The is more on the base options in the Customisation options.

4.1.3. Returns

You get a string back

4.2. base-convert/from-base

Call format is:

    base-convert/from-base number  base
 

4.2.1. number

is a string containing the number you want to convert

4.2.2. base

is the base it is in. See base-convert/to-base for specifying this.

4.2.3. Returns

You get a decimal back

5. Customisation

5.1. Case sensitivity

If you want upper- and lower-case letters to be different digits, set:

  base-convert/case-sensitive: true
 

5.1.1. example

   do %base-convert.r
   base-convert/to-base 100 "oO"
    User Error: Base contains duplicate characters: OO
   But:
   base-convert/case-sensitive: true
   base-convert/to-base 100 "oO"
   =="OOooOoo"      ;; 100 in base-2 using O and o rather than 0 and 1
 

5.2. Different digit strings

If you want a different default sequence of digits, or you want more than base-36, set:

   base-convert/default-digits: "...your digits..."
 

5.2.1. Examples

   base-convert/default-digits: "QWERTY"
   base-convert/to-base 100 3  ;; base-3 using Q, W and E
   == "WQEQW"
   base-convert/to-base 100 7  ;; sadly, max base is now length? "QWERTY"
    User Error: Maximum base should be 6

   letters: copy "abcdefghijklmnopqrstuvwxyz"
   digits: "0123456789"
   base-convert/default-digits: join digits [letters uppercase copy letters]
   base-convert/case-sensitive: true
   base-convert/to-base 100 62  ;; now use up to base 62
   == "1C"
 

5.3. Maximum decimal

The largest number that can safely be used in convert-base/to-base is the largest decimal that can be divided by the base and give an accurate remainder.

That will vary by base, and I'm happy to admit that I haven't researched it or done any testing. Also, as it will fall at the very end of the range of what is possible, it may vary slightly between platforms and versions of REBOL.

You can adjust the maximum number the to-base function will attempt:

     convert-base/maximum-decimal: ...a big value...
 

But be warned, you'll get no support or sympathy if it goes wrong.

6. Testing

If you want to extend, expand, enhance or just fix this script, please do so.

A test driver is included so you can run some verification tests that your changes haven't broken anything obvious. Example:

   do %base-convert.r
   base-convert/test-drive
   22:22:08  Tests completed:  0
   22:22:10  Tests completed:  1000
   22:22:11  Tests completed:  2000
   22:22:12  Tests completed:  3000
   22:22:13  Tests completed:  4000
   22:22:15  Tests completed:  5000
   22:22:16  Tests completed:  6000
 

That's 24,000 conversions (4 * 6000: decimal --> base-x --> decimal. And then base-y --> decimal --> base-y) without a failure. Could mean the last bug will be hard to find.

end