radix 1.1.0 → 2.0.0

data/README.rdoc

@@ -1,7 +1,7 @@
 = Radix
 
-* http://rubyworks.github.com/radix
-* http://github.com/rubyworks/radix
+* home: http://rubyworks.github.com/radix
+* code: http://github.com/rubyworks/radix
 
 
 == DESCRIPTION
@@ -16,14 +16,14 @@ base 62.
 == FEATURES/ISSUES
 
 * Convert to and from any base.
-* User-definable character set upto base 62.
-* Defaults to standard base 62.
-* Can be used to encode strings.
+* Define custom character sets.
+* Can be used to encode/decode strings.
+* Very intuitive API.
 
 
 == RELEASE NOTES
 
-Please see HISTORY file.
+Please see the HISTORY.rdoc file.
 
 
 == SYNOPSIS
@@ -37,44 +37,45 @@ But Ruby reaches it's limit at base 36.
 
   255.to_s(37)   #=> Error
 
-Radix provides the means of converting to and from any base. For example,
-a number in base 256, represented by the array [100, 10] (ie. 100 * 256 + 10 * 1),
-can be converted to base 10 as follows:
+Radix provides the means of converting to and from any base.
 
-  Radix.convert_base([100, 10], 256, 10)
-  #=> [2,5,6,1,0]
+For example, a number in base 256 can be represented by the array [100, 10]
+(ie. 100**256 + 10**1) and can be convert to base 10.
 
-And it can handle any string notation up to base 62.
+  [100,10].b(256).to_a(10)  #=> [2,5,6,1,0]
 
-  Radix.convert("10", 62, 10)  #=> "62"
+Or, to get a string representation for any base upto 62.
 
-The string notation need not be in ASCII order --odd notations
-can be used.
+  [100,10].b(256).to_s(10)  #=> "25610"
 
-  b10 = Radix.new([:Q, :W, :E, :R, :T, :Y, :U, :I, :O, :U])
-  b10.convert("FF", 16) #=> "EYY"
+A string representation of anumber can be converted too, again,
+upto base 62.
 
+  "10".b(62).to_s(10)  #=> "62"
 
-== HOW TO INSTALL
+To use a custom character set, use an array of characters as the base
+rather than an integer. For example we can convert a base 10 number
+to another base 10 number using a different encoding.
 
-To install with RubyGems simply open a console and type:
+  base = [:Q, :W, :E, :R, :T, :Y, :U, :I, :O, :U]
+
+  "10".b(10).to_a(base)  #=> [:W, :Q]
 
-  gem install radix
+To learn more have a look at the {QED}[http://rubyworks.github.com/radix/docs/qed].
 
-Site installation requires Setup.rb (gem install setup),
-then download the tarball package and type:
+== HOW TO INSTALL
+
+To install with RubyGems simply open a console and type:
 
-  tar -xvzf radix-1.0.0.tgz
-  cd radix-1.0.0
-  sudo setup.rb all
+  $ gem install radix
 
-Windows users use 'ruby setup.rb all'.
+Radix follows {Ruby Setup}[http://rubyworks.github.com/setup] package standard.
 
 
-== LINCENSE/COPYRIGHT
+== LICENSE/COPYRIGHT
 
 Copyright (c) 2009 Thomas Sawyer
 
-This program is ditributed unser the terms of the LGPLv3 license.
+This program is ditributed unser the terms of the Apache 2.0 license.
 
 See LICENSE file for details.

data/doc/01_synopsis.rdoc

@@ -0,0 +1,60 @@
+= Synopsis
+
+Base conversions with ASCII ordered notations are easy in Ruby.
+
+  255.to_s(16)   #=> "ff"
+  "ff".to_i(16)  #=> 255
+
+But Ruby reaches it's limit at base 36.
+
+  expect ArgumentError do
+    255.to_s(37)
+  end
+
+Radix provides the means of converting to and from any base.
+
+  require 'radix'
+
+For example, a number in base 256 can be represented by the array [100, 10]
+(ie. 100**256 + 10**1) and easily converted to base 10.
+
+  [100,10].b(256).to_i  #=> 25610
+
+We can get an Array representation as well.
+
+  [100,10].b(256).to_a(10)  #=> [2,5,6,1,0]
+  [100,10].b(256).to_a(62)  #=> [6,41,4]
+  [100,10].b(256).to_a(64)  #=> [6,16,10]
+
+To get a String representation for any base use #to_s.
+
+  [100,10].b(256).to_s(10)  #=> "25610"
+  [100,10].b(256).to_s(62)  #=> "6 41 4"
+  [100,10].b(256).to_s(64)  #=> "6 16 10"
+
+Notice that anything above base 10 is seperated by a space divider. The divider
+can be changed by providing a second argument.
+
+  [100,10].b(256).to_s(64, ':')  #=> "6:16:10"
+
+A string representation of a number can be converted upto base 62 (B62).
+
+  "10".b(62).to_s(10)  #=> "62"
+  "zz".b(62).to_s(10)  #=> "3843"
+
+To encode a number with a base greater than 10, use an Array base. Radix
+provides a built-in set of these, such as `BASE::B62`.
+
+  [100,10].b(256).to_s(Radix::BASE::B62)  #=> "6f4"
+
+To use a custom character set, use an array of characters as the base
+rather than an integer. For example we can convert a base 10 number
+to another base 10 number but useing a different encoding.
+
+  base = %w[Q W E R T Y U I O U]
+
+  "10".b(10).to_a(base)  #=> ["W", "Q"]
+
+  "10".b(10).to_s(base)  #=> "WQ"
+
+All of the above holds equally for floating point numbers.

data/doc/02_integer.rdoc

@@ -0,0 +1,48 @@
+= Radix Integer
+
+Radix provides an Integer class for working with integers in various bases.
+
+  require 'radix'
+
+Radix extend the Integer, String and Array classes with the #b method
+which simplifies the creation of Radix::Integer instances. The following
+return the equivalent instance of Radix::Integer.
+
+  a = 8.b(2)
+
+  b = "1000".b(2)
+
+  c = [1, 0, 0, 0].b(2)
+
+  a.assert == b
+  b.assert == c
+  c.assert == a
+
+  a.assert == 8
+  b.assert == 8
+  c.assert == 8
+
+Radix integers can ve converted to other bases with the #convert method.
+
+  b = "1000".b(2)
+  d = b.convert(10)
+  d.digits.assert == [8]
+
+Radix::Integer supports all the usual mathematical operators.
+
+  r = "1000".b(2) + "2".b(8)
+  r.assert == "1010".b(2)
+  r.assert == "12".b(8)
+  r.assert == "10".b(10)
+
+A more complex example with a much higher base.
+
+  r = "AZ42".b(62) + "54".b(10)
+  r.assert == "2518124".b(10)
+  r.assert == 2518124
+
+Work with arrays for bases greater than 62.
+
+  r = [100,10].b(256) + "54".b(10)
+  r.assert == "25664".b(10)
+

data/doc/03_float.rdoc

@@ -0,0 +1,36 @@
+= Radix Float
+
+Radix provides a Float class for working with floating point numbers in
+any base.
+
+  require 'radix'
+
+With it, the #b method extends String and Array classes to
+simplify all mulit-base operations.
+
+  b = "100.01".b(2)
+  b.to_a.assert == [1,0,0,'.',0,1]
+
+Convert to base 10.
+
+  t = b.convert(10)
+  t.to_a.assert == [4,'.',2,5]
+
+Like a Numeric class, Radix::Float's can be added, subtracted, multipled, etc.
+
+  r = "1000.01".b(2) + "2".b(8)
+  r.assert == "1010.01".b(2)
+  r.assert == "12.2".b(8)
+  r.assert == "10.25".b(10)
+
+Even complex conversions are supported.
+
+  r = "AZ42".b(62) + "54".b(10)
+  r.assert == "2518124".b(10)
+
+To work with bases greater than 62, use arrays. A '.' entry in the array
+can be used to separate the whole from the fractional part of the number.
+
+  r = [100,10,'.',64].b(256) + "54".b(10)
+  r.assert == "25664.25".b(10)
+

data/doc/04_rational.rdoc

@@ -0,0 +1,27 @@
+= Radix Rational
+
+Radix also provides a Rational class. Like the Integer and Float classes
+Radix::Rational delegates to an underlying instance of Ruby standard
+Rational class.
+
+  require 'radix'
+
+  b = ["100","10"].br(2)
+  b.assert = [2,1].br(10)
+
+When convert to Array or String Radix::Rational uses `/` to separate
+the numerator from the denominator.
+
+  b.to_a  #=> [1,0,0,'/',1,0]
+  b.to_s  #=> "100/10"
+
+To use a custom character set, use an array of characters as the base
+rather than an integer. For example we can convert a base 10 number
+to another base 10 number but useing a different encoding.
+
+  base = %w[Q W E R T Y U I O U]
+
+  ["10","1"].br(10).to_a(base)  #=> ["W", "Q", '/', 'W']
+
+  ["10","1"].br(10).to_s(base)  #=> "WQ/W"
+

data/{qed/radix_base.rdoc → doc/05_base.rdoc}

@@ -1,14 +1,20 @@
-= Overview of Radix::::Base
+= Radix Base
 
-First require the library.
+Radix::Base encapsulates a base which can then be used to perform conversions
+to and form that base.
+
+NOTE: Radix::Base is the original Radix API. But with the advent of v2.0
+and the new Integer and Float classes, it is outmoded. For now it is here
+for backward compatibility. In a future version it may be deprecated, or
+reworked to serve as the backbone of the other classes.
 
   require 'radix/base'
 
 First let's try something we all know, hexideciaml.
 First we setup the radix for each.
 
-  b10 = Radix::Base.new(Radix::Base::BASE10)
-  b16 = Radix::Base.new(Radix::Base::BASE16)
+  b10 = Radix::Base.new(Radix::BASE::B10)
+  b16 = Radix::Base.new(Radix::BASE::B16)
 
 Now we can covert from one base to the other.
 
@@ -30,42 +36,47 @@ a Radix object.
   b10.convert("A0", 16).should == "160"
   b10.convert("FF", 16).should == "255"
 
-We can also use the module function to convert to and from standard
-notations upto 62 without creating an instance of Radix::Base.
+Now let's try a more down to earth base, my favorite,
+senary, or base six.
 
-  Radix::Base.convert("10", 16, 10).should == "16"
-  Radix::Base.convert("A0", 16, 10).should == "160"
-  Radix::Base.convert("FF", 16, 10).should == "255"
+  b6  = Radix::Base.new(0..5)
+  b6.convert("39", 10).should == "103"
 
-Let's try that again with the maximum base supported.
+And the notations need not be in ASCII order. Odd alternate notations
+can be used as well.
 
-  Radix::Base.convert(     "62", 10, 62).should == "10"
-  Radix::Base.convert("8814542", 10, 62).should == "AZ42"
+  b10 = Radix::Base.new([:Q, :W, :E, :R, :T, :Y, :U, :I, :O, :U])
+  b10.convert("FF", 16) #=> "EYY"
 
-  Radix::Base.convert(     "10", 62, 10).should == "62"
-  Radix::Base.convert(   "AZ42", 62, 10).should == "8814542"
+== Encoding and Decoding
 
 Radix can also be used to encode and decode strings.
 
   b16.encode("CHARLIE").should == "434841524C4945"
   b16.decode("434841524C4945").should == "CHARLIE"
 
-Now let's try a more down to earth base, my favorite,
-senary, or base six.
+== Module Methods
 
-  b6  = Radix::Base.new(0..5)
-  b6.convert("39", 10).should == "103"
+We can also use the module function to convert to and from standard
+notations upto 62 without creating an instance of Radix::Base.
 
-And the notations need not be in ASCII order. Odd alternate notations
-can be used as well.
+  Radix.convert("10", 16, 10).should == "16"
+  Radix.convert("A0", 16, 10).should == "160"
+  Radix.convert("FF", 16, 10).should == "255"
 
-  b10 = Radix::Base.new([:Q, :W, :E, :R, :T, :Y, :U, :I, :O, :U])
-  b10.convert("FF", 16) #=> "EYY"
+Let's try that again with the maximum base supported.
+
+  Radix.convert(     "62", 10, 62).should == "10"
+  Radix.convert("8814542", 10, 62).should == "az42"
+
+  Radix.convert(     "10", 62, 10).should == "62"
+  Radix.convert(   "az42", 62, 10).should == "8814542"
 
 Finally, we will demonstrate how to convert bases larger than 62.
 These can only be represented as arrays since there are not enough
 latin characters to represent them.
 
-  Radix::Base.convert_base([100, 10], 256, 10).should == [2, 5, 6, 1, 0]
-  Radix::Base.convert_base([2, 5, 6, 1, 0], 10, 256).should == [100, 10]
+  Radix.convert_base([100, 10], 256, 10).should == [2, 5, 6, 1, 0]
+  Radix.convert_base([2, 5, 6, 1, 0], 10, 256).should == [100, 10]
+  Radix.convert_base([1, 0, 1, 0, 1], 2, 10).should == [2, 1]
 

data/doc/applique/qed.rb

@@ -0,0 +1 @@
+require 'qed/extensions/check'

data/lib/radix.rb

@@ -1 +1,42 @@
-require 'radix/operator'
+require 'radix/meta/data'
+require 'radix/base'
+require 'radix/integer'
+require 'radix/float'
+require 'radix/rational'  # load ?
+
+class ::Float
+  #
+  def b(base)
+    Radix::Float.new(self, base)
+  end
+end
+
+class ::Integer
+  #
+  def b(base)
+    Radix::Integer.new(self, base)
+  end
+end
+
+class ::String
+  #
+  def b(base)
+    if index('.')
+      Radix::Float.new(self, base)
+    else
+      Radix::Integer.new(self, base)
+    end
+  end
+end
+
+class ::Array
+  #
+  def b(base)
+    if index('.')
+      Radix::Float.new(self, base)
+    else
+      Radix::Integer.new(self, base)
+    end
+  end
+end
+

data/lib/radix/base.rb

@@ -1,96 +1,81 @@
-# Radix coverts to and from any base.
-#
-# Base conversions with ASCII ordered notations are easy in Ruby.
-#
-#   255.to_s(16)   #=> "FF"
-#   "FF".to_i(16)  #=> 255
-#
-# But Ruby reaches it's limit at base 36.
-#
-#   255.to_s(37)   #=> Error
-#
-# Radix provides the means of converting to and from any base.
-#
-#   Radix::Base.convert_base([100, 10], 256, 10)
-#   #=> [2,5,6,1,0]
-#
-# And it can handle any notation upto base 62.
-#
-#   Radix::Base.convert("10", 62, 10)  #=> "62"
-#
-# And the notations need not be in ASCII order --odd notations
-# can be used.
-#
-#   b10 = Radix::Base.new([:Q, :W, :E, :R, :T, :Y, :U, :I, :O, :U])
-#   b10.convert("FF", 16) #=> "EYY"
-#
 module Radix
 
-  class Base
+  # Collection of base encodings.
+  module BASE
+    B10 = ('0'..'9').to_a
+    B12 = B10 + ['X', 'E']
+    B16 = B10 + ('A'..'F').to_a
+    B36 = B10 + ('A'..'Z').to_a
+    B60 = B36 + ('a'..'x').to_a
+    B62 = B36 + ('a'..'z').to_a
+
+    # Like BASE16 but encodes with lowercase letters.
+    HEX = B10 + ('a'..'f').to_a
+  end
 
-    BASE10 = ["0".."9"].map { |r| r.to_a }.flatten
-    BASE12 = ["0".."9", ["X", "E"]].map { |r| r.to_a }.flatten
-    BASE16 = ["0".."9", "A".."F"].map { |r| r.to_a }.flatten
-    BASE36 = ["0".."9", "A".."Z"].map { |r| r.to_a }.flatten
-    BASE60 = ["0".."9", "a".."z", "A".."X"].map { |r| r.to_a }.flatten
-    BASE62 = ["0".."9", "a".."z", "A".."Z"].map { |r| r.to_a }.flatten
+  # Radix::Base provides the means of converting to and from any base.
+  #
+  #   b10 = Radix::Base.new(10)
+  #   b10.convert_base([100, 10], 256)
+  #   #=> [2,5,6,1,0]
+  #
+  # And it can handle any notation upto base 62.
+  #
+  #   b10.convert("10", 62)  #=> "62"
+  #
+  # And the notations need not be in ASCII order --odd notations
+  # can be used.
+  #
+  #   b10 = Radix::Base.new(%w{Q W E R T Y U I O U})
+  #   b10.convert("FF", 16) #=> "EYY"
+  #
+  # NOTE: Radix::Base is the original Radix API. But with the advent of v2.0
+  # and the new Integer and Float classes, it is outmoded. For now it is here
+  # for backward compatibility. In a future version it may be deprecated, or
+  # reworked to serve as the backbone of the other classes.
+  #
+  class Base
 
     attr :chars
+
     attr :base
+
     attr :values
 
     # New Radix using +chars+ representation.
-    def initialize(chars=BASE62)
+    def initialize(chars=BASE::B62)
+      if ::Numeric === chars
+        chars = BASE::B62[0...chars]
+      end
       @chars  = chars.map{ |c| c.to_s }
       @base   = @chars.size
       @values = Hash[*(0...@base).map { |i| [ @chars[i], i ] }.flatten]
     end
 
-    # Encode a string in the radix.
-    def encode(byte_string)
-      digits = byte_string.unpack("C*")
-      digits = convert_base(digits, 256, base)
-      digits.map{ |d| @chars[d] }.join
-    end
+    # Convert an *encoded* +number+ of given +base+ to the Base's radix.
+    def convert(number, radix_base)
+      radix_base = Radix::Base.new(radix_base) unless Radix::Base === radix_base
 
-    # Decode a string that was previously encoded in the radix.
-    def decode(encoded)
-      digits = encoded.split(//).map{ |c| @values[c] }
-      convert_base(digits, base, 256).pack("C*")
-    end
+      case number
+      when ::String, ::Numeric
+        digits = number.to_s.split(//)
+      else
+        digits = number
+      end
+
+      # decode the digits
+      digits = digits.map{ |digit| radix_base.values[digit] }
+
+      # THINK: Is best way to check for base out of bounds?
+      raise TypeError if digits.any?{ |digit| digit.nil? }
 
-    # Convert a representational +number+ of +from_radix+ to the radix.
-    def convert(number, from_radix)
-      from_radix = standard_radix(from_radix) if Integer === from_radix
-      digits = number.to_s.split(//)
-      digits = digits.map{ |digit| from_radix.values[digit] }
-      digits = convert_base(digits, from_radix.base, base)
+      digits = Radix.convert_base(digits, radix_base.base, base)
       digits = digits.map{ |digit| chars[digit] }
       digits.join
     end
 
     # Convert any base to any other base, using array of +digits+.
     def convert_base(digits, from_base, to_base)
-      self.class.convert_base(digits, from_base, to_base)
-    end
-
-    private
-
-    def standard_radix(integer_base)
-      self.class.standard_radix(integer_base)
-    end
-
-    public
-
-    # Do a standard conversion upto base 62.
-    def self.convert(number, from_base, to_base)
-      r1 = standard_radix(from_base)
-      r2 = standard_radix(to_base)
-      r2.convert(number, r1)
-    end
-
-    # Convert any base to any other base, using array of +digits+.
-    def self.convert_base(digits, from_base, to_base)
       bignum = 0
       digits.each { |digit| bignum = bignum * from_base + digit }
       converted = []
@@ -98,33 +83,44 @@ module Radix
         bignum, digit = bignum.divmod(to_base)
         converted.push(digit)
       end
+      converted << 0 if converted.empty?  # THINK: correct?
       converted.reverse
     end
 
-    # Provide a standard representation of a base upto 62.
-    def self.standard_radix(integer_base)
-      if integer_base > 36
-        new(BASE62[0..integer_base-1])
-      else
-        new(BASE36[0..integer_base-1])
-      end
+    # Encode a string in the radix.
+    def encode(byte_string)
+      digits = byte_string.unpack("C*")
+      digits = Radix.convert_base(digits, 256, base)
+      digits.map{ |d| @chars[d] }.join
+    end
+
+    # Decode a string that was previously encoded in the radix.
+    def decode(encoded)
+      digits = encoded.split(//).map{ |c| @values[c] }
+      Radix.convert_base(digits, base, 256).pack("C*")
     end
 
   end
 
+  # Convert number from it's given base to antoher base.
   # Do a standard conversion upto base 62.
   def self.convert(number, from_base, to_base)
-    Radix::Base.convert(number, from_base, to_base)
+    from_base = Radix::Base.new(from_base) unless Radix::Base === from_base
+    to_base   = Radix::Base.new(to_base)   unless Radix::Base === to_base
+    to_base.convert(number, from_base)
   end
 
   # Convert any base to any other base, using array of +digits+.
   def self.convert_base(digits, from_base, to_base)
-    Radix::Base.convert_base(digits, from_base, to_base)
-  end
-
-  # Provide a standard representation of a base upto 62.
-  def self.standard_radix(integer_base)
-    Radix::Base.standard_radix(integer_base)
+    bignum = 0
+    digits.each { |digit| bignum = bignum * from_base + digit }
+    converted = []
+    until bignum.zero?
+      bignum, digit = bignum.divmod(to_base)
+      converted.push(digit)
+    end
+    converted << 0 if converted.empty?  # THINK: correct?
+    converted.reverse
   end
 
 end