radix 2.1.1 → 2.2.0

data/.index

@@ -11,11 +11,15 @@ requirements:
 - groups:
   - build
   development: true
-  name: detroit
+  name: ergo
 - groups:
   - test
   development: true
   name: qed
+- groups:
+  - test
+  development: true
+  name: ae
 conflicts: []
 alternatives: []
 resources:
@@ -47,9 +51,9 @@ paths:
 created: '2009-07-01'
 summary: Convert to and from any base.
 title: Radix
-version: 2.1.1
+version: 2.2.0
 name: radix
 description: ! "Radix is a very easy to use Ruby library for converting numbers to
   and from\nany base. It supports both Integer, Float and Rational numbers, as well
   as \nrepresentational string-notations that need not be in ASCII order."
-date: '2013-02-06'
+date: '2013-03-20'

data/.yardopts

@@ -1,5 +1,8 @@
---title Erbside
---readme README.rdoc
+--title Radix
+--readme README.md
+--protected
+--private
 lib
 -
-[A-Z]*.*
+*.md
+*.txt

data/HISTORY.md

@@ -1,12 +1,28 @@
 # RELEASE HISTORY
 
+## 2.2.0 / 2013-03-20
+
+Good documentation is so under-addressed by most developers that we really
+have to roll out the bright lights when someone comes along and takes 
+up the time consuming mantle of documenting an API in complete detail.
+This is exactly what happened with Radix this last month. A coder going
+by the unassuming handle, **douglascodes**, announced his desire to 
+document Radix and proceeded to do so until YARD pronounced 100%
+completeness. Hey, we think that is worth of a whole version bump and 
+a big shout-out for Douglas!
+
+Changes:
+
+* 100% API documentation coverage. (douglascodes)
+
+
 ## 2.1.1 / 2013-02-06
 
-Minor release to fix gemspec. Which, alas, Bunder cannot do without.
+Minor release to fix gemspec. Which, alas, Bundler cannot do without.
 
 Changes:
 
-* Update .gemspec file for lastest indexer.
+* Update .gemspec file for latest indexer.
 
 
 ## 2.1.0 / 2013-01-31
@@ -28,7 +44,7 @@ Changes:
 
 ## 2.0.1 / 2011-10-23
 
-This release is simply an adminstrative release to update the project
+This release is simply an administrative release to update the project
 build configuration. The functionality of the library itself has not
 changed. This release also transitions the project to the BSD-2-Clause
 license.
@@ -59,8 +75,8 @@ Radix now provides an actual Numeric subclass, Radix::Number, that stores
 the base and can be used like any other Numeric object. This makes it very
 easy to convert and manipulate numbers in any base. The implementation is still
 a bit nascent. For the moment, it only supports the most basic math operators
-and only handles integer values, but furture releases will continue to expand
-on it's capabilites.
+and only handles integer values, but future releases will continue to expand
+on it's capabilities.
 
 Changes:
 

data/README.md

@@ -1,10 +1,12 @@
 # Radix
 
-[Website](http://rubyworks.github.com/radix) /
-[Report Issue](http://github.com/rubyworks/radix/issues) /
-[Source Code](http://github.com/rubyworks/radix) /
-[![Build Status](https://secure.travis-ci.org/rubyworks/radix.png)](http://travis-ci.org/rubyworks/radix) /
-[![Gem Version](https://badge.fury.io/rb/radix.png)](http://badge.fury.io/rb/radix)
+[Website](http://rubyworks.github.com/radix) ·
+[Report Issue](http://github.com/rubyworks/radix/issues) ·
+[Source Code](http://github.com/rubyworks/radix)     
+[![Build Status](https://secure.travis-ci.org/rubyworks/radix.png)](http://travis-ci.org/rubyworks/radix)
+[![Gem Version](https://badge.fury.io/rb/radix.png)](http://badge.fury.io/rb/radix)    
+[![Flattr Me](http://api.flattr.com/button/flattr-badge-large.png)](http://flattr.com/thing/324911/Rubyworks-Ruby-Development-Fund)
+
 
 Radix is a very easy to use Ruby library for converting numbers to and from
 any base. It supports both Integer, Float and Rational numbers, as well as 
@@ -34,8 +36,8 @@ But Ruby reaches it's limit at base 36.
 
 Radix provides the means of converting to and from any base.
 
-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.
+For example, a number in base 256 can be represented by the array `[100, 10]`
+(`100**256 + 10**1`) and can be convert to base 10.
 
     [100,10].b(256).to_a(10)  #=> [2,5,6,1,0]
 
@@ -69,6 +71,13 @@ Radix follows [Ruby Setup](http://rubyworks.github.com/setup) package standard
 so it can also be installed in an FHS compliant manner using setup.rb.
 
 
+## Special Thanks
+
+Special thanks to **douglascodes** for taking the time to fully document
+Radix's API. Documentation is an under-addressed and time-consuming affair,
+so your contribution is greatly appreciated. Thank you, Douglas!
+
+
 ## Copyrights
 
 Copyright (c) 2009 Rubyworks

data/demo/issues/004_zero_empty_string.md

@@ -0,0 +1,18 @@
+# Zero becomes empty string (#4)
+
+Example of the issue:
+
+    0.b(10).to_s  #=> ""
+
+I would expect "0" as a result.
+
+    0.b(10).to_s  #=> "0"
+
+Okay, lets make sure this works for Floats.
+
+    0.0.b(10).to_s  #=> "0.0"
+
+And Rationals too.
+
+    [0,1].br(10).to_s  #=> "0/1"
+

data/lib/radix.rb

@@ -1,59 +1,32 @@
 require 'radix/base'
 require 'radix/integer'
 require 'radix/float'
-require 'radix/rational'  # load ?
+require 'radix/rational'
+require 'radix/operator'
 
 module Radix
+
+  ##
+  # Returns the metadata contained in Radix.yml
   #
+  # @return [Hash{String=>String}]
   def self.metadata
     @metadata ||= (
       require 'yaml'
       YAML.load(File.new(File.dirname(__FILE__) + '/radix.yml'))
     )
   end
-  #
-  def self.const_missing(name)
-    key = name.to_s.downcase
-    metadata[key] || super(name)
-  end
 
-  # TODO: Here only for buggy RUby 1.8.x.
-  VERSION = metadata['version']
-end
-
-class ::Float
+  ##
+  # Gets value of name in metadata or goes up ancestry.
   #
-  def b(base)
-    Radix::Float.new(self, base)
-  end
-end
-
-class ::Integer
+  # @param [Symbol] name
   #
-  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
+  # @return [String]
+  def self.const_missing(name)
+    key = name.to_s.downcase
+    metadata.key?(key) ? metadata[key] : super(name)
   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.yml

@@ -11,11 +11,15 @@ requirements:
 - groups:
   - build
   development: true
-  name: detroit
+  name: ergo
 - groups:
   - test
   development: true
   name: qed
+- groups:
+  - test
+  development: true
+  name: ae
 conflicts: []
 alternatives: []
 resources:
@@ -47,9 +51,9 @@ paths:
 created: '2009-07-01'
 summary: Convert to and from any base.
 title: Radix
-version: 2.1.1
+version: 2.2.0
 name: radix
 description: ! "Radix is a very easy to use Ruby library for converting numbers to
   and from\nany base. It supports both Integer, Float and Rational numbers, as well
   as \nrepresentational string-notations that need not be in ASCII order."
-date: '2013-02-06'
+date: '2013-03-20'

data/lib/radix/base.rb

@@ -1,48 +1,90 @@
 module Radix
 
-  # Collection of base encodings.
+  ##
+  # Namespace for common bases defined as reusable constants.
+  #
   module BASE
+    # Array of chars 0 - 9
     B10 = ('0'..'9').to_a
+    # Array of chars 0 - 9 + X + E
     B12 = B10 + ['X', 'E']
+    # Array of chars 0 - 9 + A - F
     B16 = B10 + ('A'..'F').to_a
+    # Array of chars 0 - 9 + A - Z
     B36 = B10 + ('A'..'Z').to_a
+    # Array of chars 0 - 9 + A - Z + a - x
     B60 = B36 + ('a'..'x').to_a
+    # Array of chars 0 - 9 + A - Z + a - z
     B62 = B36 + ('a'..'z').to_a
-
-    # Like BASE16 but encodes with lowercase letters.
+    # Array of chars 0 - 9 + a - f
     HEX = B10 + ('a'..'f').to_a
   end
 
-  # Radix::Base provides the means of converting to and from any base.
+  ##
+  # Radix::Base is a functional model of a base system that can be used for
+  # number conversions.
   #
+  # Radix::Base is the original Radix API. But with the advent of v2.0
+  # and the new Integer and Float classes, it is essentially deprecated.
+  #
+  # @example Convert 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.
-  #
+  # @example Convert to string notation upto base 62
   #   b10.convert("10", 62)  #=> "62"
   #
-  # And the notations need not be in ASCII order --odd notations
-  # can be used.
-  #
+  # @example Odd notations
   #   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.
-  #
+  # @!attribute [r] chars
+  #   @return [Array<String>] The ASCII character set in use.
+  # @!attribute [r] base
+  #   @return [Fixnum] The base level in use.
+  # @!attribute [r] values
+  #   @example Testing base hash default values.
+  #     > test = Radix::Base.new(36)
+  #     > test.values["F"]
+  #     15 
+  #     > test.values["5"]
+  #     5
+  #     > test.values["Y"]
+  #     34
+  #     > test.values["YY"] 
+  #     nil       # Fails because "YY" is not a key in the +values+ hash.
+  #   @return [Hash{String=>Fixnum}]
+  #     A hash of characters and their respective value.
   class Base
 
+    ##
+    # The characters for this base level.
+    #
+    # @return [Array<String>] The ASCII character set in use.
     attr :chars
 
+    ##
+    # The base of this instance.
+    #
+    # @return [Fixnum] The base level in use.
     attr :base
 
+    ##
+    # Hash of characters and values.
+    #
+    # @return [Hash{String=>Fixnum}]
+    #   A hash of characters and their respective value.
     attr :values
 
+    ##
     # New Radix using +chars+ representation.
+    #
+    # @param [Array<String>, Numeric] chars
+    #   Array of string representation of number values of the base
+    #   or a Numeric of the Base level.
+    #
+    # @return [void]
     def initialize(chars=BASE::B62)
       if ::Numeric === chars
         chars = BASE::B62[0...chars]
@@ -52,10 +94,35 @@ module Radix
       @values = Hash[*(0...@base).map { |i| [ @chars[i], i ] }.flatten]
     end
 
-    # Convert an *encoded* +number+ of given +base+ to the Base's radix.
+    ##
+    # Convert a value of given radix_base to that of the base instance.
+    #
+    # @param [String, Numeric, Array<String>] number
+    #   The value in "radix_base" context.
+    #
+    # @param [Radix::Base, Numeric] radix_base
+    #   Numeric for the radix or instance of Radix::Base.
+    #
+    # @example Convert Testing (Binary, Decimal, Hex)
+    #   > b = Radix::Base.new(2)
+    #   > d = Radix::Base.new(10)
+    #   > h = Radix::Base.new(16)
+    #   > d.convert("A", h)
+    #   "10"
+    #   > h.convert("A", d)
+    #   TypeError
+    #   > h.convert(10, d)
+    #   "A"
+    #   > h.convert(10, 10)
+    #   "A"
+    #   > b.convert(10, d)
+    #   "1010"
+    #   > b.convert(10, h)
+    #   "10000"
+    #
+    # @return [String] representation of "number" in self.base level.
     def convert(number, radix_base)
       radix_base = Radix::Base.new(radix_base) unless Radix::Base === radix_base
-
       case number
       when ::String, ::Numeric
         digits = number.to_s.split(//)
@@ -74,7 +141,20 @@ module Radix
       digits.join
     end
 
-    # Convert any base to any other base, using array of +digits+.
+    ##
+    # Convert any base to any other base, using array of Fixnum's. Indexes of
+    # the array correspond to values for each column of the number in from_base
+    #
+    # @param [Array<Fixnum>] digits
+    #   Array of values for each digit of source base.
+    #
+    # @param [Fixnum] from_base
+    #   Source Base
+    #
+    # @param [Fixnum] to_base
+    #   Destination Base
+    #
+    # @return [String] The value of digits in from_base converted as to_base.
     def convert_base(digits, from_base, to_base)
       bignum = 0
       digits.each { |digit| bignum = bignum * from_base + digit }
@@ -87,14 +167,26 @@ module Radix
       converted.reverse
     end
 
+    ##
     # Encode a string in the radix.
+    #
+    # @param [String] byte_string
+    #   String value in this base. 
+    #
+    # @return [String] Encoded string from this Base.
     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.
+    #
+    # @param [String] encoded
+    #   Encoded string from this Base.
+    #
+    # @return [String] Decoded string of value from this base. 
     def decode(encoded)
       digits = encoded.split(//).map{ |c| @values[c] }
       Radix.convert_base(digits, base, 256).pack("C*")
@@ -102,15 +194,40 @@ module Radix
 
   end
 
-  # Convert number from it's given base to antoher base.
-  # Do a standard conversion upto base 62.
+  ##
+  # Convert a number of from_base as to_base.
+  #
+  # @param [String, Numeric, Array<String>] number
+  #   The value in context of "radix_base".
+  #
+  # @param [Fixnum, Radix::Base] from_base
+  #   Source Base
+  #
+  # @param [Fixnum, Radix::Base] to_base
+  #   Destination Base
+  #
+  # @return [String]
+  #   The value of `digits` in `from_base` converted into `to_base`.
   def self.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+.
+  ##
+  # Convert any base to any other base, using array of Fixnum's. Indexes of
+  # the array correspond to values for each column of the number in from_base
+  #
+  # @param [Array<Fixnum>] digits
+  #   Array of values for each digit of source base.
+  #
+  # @param [Fixnum] from_base
+  #   Source Base
+  #
+  # @param [Fixnum] to_base
+  #   Destination Base
+  #
+  # @return [String] The value of digits in from_base converted as to_base.
   def self.convert_base(digits, from_base, to_base)
     bignum = 0
     digits.each { |digit| bignum = bignum * from_base + digit }