radix 2.1.1 → 2.2.0

data/lib/radix/numeric.rb

@@ -2,57 +2,90 @@ require 'radix/base'
 
 module Radix
 
-  # Redix separator used in string and array representations.
+  # Radix separator used in string and array representations.
   DOT = '.'
 
-  #
+  # Division character for rational numbers
   DIV = '/'
 
-  #
+  # Default seperator character.
   DIVIDER = " "
 
-  # Radix Numeric base class is subclassed by Radix::Integer and Radix::Float,
-  # and is a subclass of Ruby's built-in Numeric class.
+  ##
+  # Radix::Numeric class inherits from Ruby's Numeric class. It is then
+  # subclassed by Radix::Integer and Radix::Float.
+  #
+  # @todo Make immutable, but best way to do it?
+  # @example First suggestion
+  #   class << self
+  #     alias_method :_new, :new
+  #     private :_new
+  #   end
+  # @example Second suggestion
+  #   def self.new(value, base=10)
+  #     @cache ||= {}
+  #     @cache[[value, base]] ||= _new(value, base)
+  #   end
   class Numeric < ::Numeric
 
-    # TODO: Make immutable, but best way to do it?
-
-    #class << self
-    #  alias_method :_new, :new
-    #  private :_new
-    #end
+    ##
+    # Addition, binary operation.
     #
-    #def self.new(value, base=10)
-    #  @cache ||= {}
-    #  @cache[[value, base]] ||= _new(value, base)
-    #end
-
-    # Addition
+    # @param [Radix::Numeric] other
+    #
+    # @return [Radix::Numeric] Result of arithmetic operation.
     def +(other)
       operation(:+, other)
     end
 
-    # Subtraction
+    ##
+    # Subtraction, binary operation.
+    #
+    # @param [Radix::Numeric] other
+    #
+    # @return [Radix::Numeric] Result of arithmetic operation.
     def -(other)
       operation(:-, other)
     end
 
-    # Multiplication
+    ##
+    # Multiplication, binary operation.
+    #
+    # @param [Radix::Numeric] other
+    #
+    # @return [Radix::Numeric] Result of arithmetic operation.
     def *(other)
       operation(:*, other)
     end
 
-    # Division
+    ##
+    # Division, binary operation.
+    #
+    # @param [Radix::Numeric] other
+    #
+    # @return [Radix::Numeric] Result of arithmetic operation.
     def /(other)
       operation(:/, other)
     end
 
     private
 
+    ##
+    # Parses the value of the base and character set to use.
     #
+    # @param [Fixnum, Array<String>] base
+    #   The value of the base, or a set of characters to use as
+    #   representation of the base.
+    #
+    # @note If an array of String characters is passed, its length is the
+    #   value of the base level.
+    #
+    # @return [Array<(Fixnum, [Array<String>, nil])>] Two part array:
+    #   0 - Fixnum value of the base.
+    #   1 - Nil, or Array of characters representing the base values.
     def parse_base(base)
       case base
-      when Array
+       when Array
         code = base
         base = base.size
       else
@@ -62,20 +95,42 @@ module Radix
       return base, code
     end
 
+    ##
+    # Simply returns the passed value. Used for simplifying creation of 
+    # Radix::Numeric instances.
+    # 
+    # @param [Radix::Float, Radix::Integer] value Given value.
+    # @param [Fixnum, Array<String>] base Desired base.
     #
+    # @return [Radix::Float, Radix::Integer] The passed value.
     def parse_numeric(value, base)
       value
     end
 
+    ##
     # If a float style string is passed in for +value+, e.g. "9.5", the
     # decimal will simply be truncated. So "9.x" would become "9".
+    # 
+    # @param [String] value
+    #   Given value.
+    #
+    # @param [Fixnum, Array<String>] base
+    #   Desired base.
+    #
+    # @return [Radix::Float, Radix::Integer] The passed value.
     def parse_string(value, base)
       digits = value.split(//)
       parse_array(digits, base)
     end
 
+    ##
     # Take an Array in the form of [d1, d2, ..., DOT, d-1, d-2, ...]
     # and convert it to base ten, and store in @value.
+    #
+    # @param [Array<String, Numeric>] value Given value.
+    # @param [Fixnum, Array<String>] base Desired base.
+    #
+    # @return [Fixnum] Decimal version of passed array in base context.
     def parse_array(value, base)
       value = value.dup
 
@@ -93,12 +148,20 @@ module Radix
 
       v = decimal(value, base)
 
-      neg ? -v : v
+      neg ? -v : v # Returns negated v if value array.first == "-"
     end
 
-    # Convert array of values of a different base to decimal.
-    # This handles integer values. The method for Radix::Float
-    # is slighly different.
+    ##
+    # Convert array of values of a different base to decimal. This handles
+    # integer values. The method for Radix::Float is slighly different.
+    #
+    # @param [Array<Numeric, String>] digits
+    #   Representation of base values.
+    #
+    # @param [Fixnum, Array<String>] base
+    #   The base to convert from.
+    #
+    # @return [Integer] The digits of base converted to decimal.
     def decimal(digits, base)
       e = digits.size - 1
       v = 0
@@ -109,8 +172,13 @@ module Radix
       v
     end
 
+    ##
     # Map array of values to base encoding. If no encoding is defined
     # this simply returns the +digits+ unchanged.
+    # 
+    # @param [Array<String, Numeric>] digits
+    #
+    # @return [Array<String, Fixnum>] Encoded digits, or digits if @code is nil
     def base_encode(digits)
       return digits unless @code
       digits.map do |i|
@@ -123,7 +191,12 @@ module Radix
       end
     end
 
-    # Decode an encoded array.
+    ##
+    # Decode an encoded array. Defaults to BASE::B62 if self.code is not set.
+    # 
+    # @param [Array<String, Numeric>] digits The encoded characters. 
+    #
+    # @return [Array<String, Numeric>] Decoded array. 
     def base_decode(digits)
       #return digits unless code
       code = self.code || BASE::B62

data/lib/radix/operator.rb

@@ -0,0 +1,82 @@
+# This script defines the `#b` core extension method for Ruby's built-in
+# Numeric classes to make it easy to convert to Radix base classes.
+
+##
+# Adds the b(base) method to this ruby class for quickly creating Radix
+# instances.
+class ::Float
+
+  ##
+  # Takes a Ruby Float and makes it into a Radix::Float as given base.
+  # 
+  # @param [Fixnum, Array<String>] base
+  #   The desired base.
+  #
+  # @return [Radix::Float]
+  def b(base)
+    Radix::Float.new(self, base)
+  end
+end
+
+##
+# Adds the b(base) method to this ruby class for quickly creating Radix
+# instances.
+class ::Integer
+
+  ##
+  # Takes a Ruby Integer and makes it into a Radix::Integer as given base.
+  # 
+  # @param [Fixnum, Array<String>] base
+  #   The desired base.
+  #
+  # @return [Radix::Integer]
+  def b(base)
+    Radix::Integer.new(self, base)
+  end
+end
+
+##
+# Adds the b(base) method to this ruby class for quickly creating Radix
+# instances.
+class ::String
+
+  ##
+  # Takes a String and makes it into a Radix::Integer or Radix::Float as given
+  # base. Float is determined by a "." character in string instance
+  # 
+  # @param [Fixnum, Array<String>] base
+  #   The desired base.
+  #
+  # @return [Radix::Integer, Radix::Float]
+  def b(base)
+    if index('.')
+      Radix::Float.new(self, base)
+    else
+      Radix::Integer.new(self, base)
+    end
+  end
+end
+
+##
+# Adds the b(base) method to this ruby class for quickly creating Radix
+# instances.
+class ::Array
+
+  ##
+  # Takes array and makes it into a Radix::Integer or Radix::Float as given
+  # base. Float is determined by a "." character in array instance.
+  # 
+  # @param [Fixnum, Array<String>] base
+  #   The desired base.
+  #
+  # @return [Radix::Integer, Radix::Float]
+  def b(base)
+    if index('.')
+      Radix::Float.new(self, base)
+    else
+      Radix::Integer.new(self, base)
+    end
+  end
+
+end
+

data/lib/radix/rational.rb

@@ -3,31 +3,55 @@ require 'radix/numeric'
 
 module Radix
 
+  ##
   # Represents rational numbers.
   #
+  # @!attribute [r] value
+  #   @return [Rational] Ruby Rational representation of self in Base-10.
+  # @!attribute [r] base
+  #   @return [Fixnum] The base level of Rational instance.
+  # @!attribute [r] code 
+  #   @return [Array<String>, nil] Substitution chars or nil if default.
   class Rational < Numeric
 
+    ##
     # Alternative to #new.
+    #
+    # @return [Radix::Rational]
     def self.[](n,d=nil,b=10)
       new(n,d,b)
     end
 
-    # Stores the Rational value.
+    ##
+    # Stores the Rational value in Base-10.
+    #
+    # @return [Rational] 
     attr :value
 
+    ##
     # Base of the number.
+    #
+    # @return [Fixnum] The base level of Rational instance.
     attr :base
 
+    ##
     # Base encoding table.
+    #
+    # @return [Array<String>, nil] Substitution chars or nil if default.
     attr :code
 
     private
 
+    ##
     # Create a new Radix::Rational instance.
-    #
+    # @example
     #   Rational.new(<Integer>, <Integer>, <Integer>)
     #   Rational.new(<Rational>, <Integer>)
-    #
+    # @param [Radix::Rational, ::Rational, Fixnum] numerator A rational number
+    #   or a fixnum for the numerator of a new Rational.
+    # @param [Fixnum] denominator Denominator for new Rational.
+    # @param [Fixnum] base Base level for new Rational.
+    # @return [void]
     def initialize(numerator, denominator=nil, base=10)
       case numerator
       when ::Rational, Rational
@@ -42,7 +66,11 @@ module Radix
       @base, @code = parse_base(base)
     end
 
-    #
+    ##
+    # Parses String, Array, Radix::Float, Radix::Integer or Ruby numerics and
+    # returns the decimal value from base context for storage in @value.
+    # 
+    # @param [Fixnum] base 
     def parse_value(value, base)
       case value
       when Float, Integer # Radix
@@ -58,38 +86,48 @@ module Radix
 
     public
 
+    ##
     # The numerator.
     #
+    # @return [Fixnum] The numerator of Radix::Rational
     def numerator
       @value.numerator
     end
 
+    ##
     # The denominator.
     #
+    # @return [Fixnum] The denominator of Radix::Rational
     def denominator
       @value.denominator
     end
 
+    ##
     # Is the value negative?
     #
+    # @return [Boolean] Returns true if value < 0.
     def negative?
       value < 0
     end
 
+    ##
     # Convert rational to new base.
     #
-    # Returns new rational. [Radix::Rational]
+    # @param [Fixnum] base Desired base.
+    # @return [Radix::Rational] Returns new Radix::Rational in passed base.
     def convert(base)
       self.class.new(numerator, denominator, base)
     end
 
+    ##
     # Convert to rational.
     #
-    # Returns the internal value. [Rational]
+    # @return [Rational] Returns the value.
     def to_r
       value
     end
 
+    ##
     # Convert to Float by dividing the numerator by the denominator.
     #
     # Returns the converted value. [Float]
@@ -97,6 +135,7 @@ module Radix
       numerator.to_f / denominator.to_f
     end
 
+    ##
     # Convert to Integer by converting to Float first then
     # appling #to_i to the float.
     #
@@ -105,9 +144,12 @@ module Radix
       to_f.to_i
     end
 
-    # Translate value into an array of places.
-    #
-    # Returns array of places. [Array]
+    ##
+    # Translate value into an array of places. Uses current base unless
+    # specified.
+    # 
+    # @param [Fixnum] base Desired base.
+    # @return [Array<Fixnum, String>] Array of place values.
     def to_a(base=nil)
       if base
         convert(base).digits_encoded
@@ -116,12 +158,12 @@ module Radix
       end     
     end
 
+    ##
     # Convert the value into a string representation of the given base.
     #
-    # base    - the base to convert
-    # divider - symbol to used ot divide numbers
-    #
-    # Returns translated value. [String]
+    # @param [Fixnum] base The base to convert.
+    # @param [String] divider The string char(s) to divided with.
+    # @return [String] Translated value.
     def to_s(base=nil, divider=nil)
       divider = divider.to_s if divider
       if base
@@ -139,22 +181,33 @@ module Radix
       end
     end
 
-    # Are two rationals equal?
-    #
-    # TODO: this may need improvement to be more percise.
+    ##
+    # Simple equality requires equal values only.
     #
-    # Returns true if equal, otherwise false. [Boolean]
+    # @todo This may need improvement to be more percise.
+    # @param [#to_f] other The value to compare to.
+    # @return [Boolean] True if equal values.
     def ==(other)
       a, b = self.to_f, other.to_f
       a == b
     end
 
-    #
+    ##
+    # Returns an irreducible version of self in current base.
+    # 
+    # @todo Is this method neccesary since @value is a Ruby Rational and
+    #   therefore already irreducible?
+    # @return [Radix::Rational]
     def reduce
       self.class.new(Rational(numerator, denominator), base)
     end
 
+    ##
+    # Returns an array representation of the numerator and denominator with
+    # each column's value.
     #
+    # @return [Array<String, Fixnum>] Values per column of @base as array. 
+    #   Prepended with "-" if negative. 
     def digits
       n = base_conversion(numerator, base)
       d = base_conversion(denominator, base)
@@ -163,34 +216,49 @@ module Radix
       i
     end
 
+    ##
+    # Returns digits, or coded version of digits if @code.
     #
+    # @return [Array<String, Fixnum>] Values per column of @base as array. 
+    #   Prepended with "-" if negative. Or encoded version if @code is
+    #   defined.
     def digits_encoded
       base_encode(digits)
     end
 
-    # Returns [String]
+    ##
+    # Creates a string representation of self.
+    #
+    # @return [String] String rep of self.digits and @base.
     def inspect
       "#{digits.join(' ')} (#{base})"
     end
 
-    #
+    ##
+    # Returns new Radix::Rational of passed value in base-10 and self as an
+    # Array.
+    # 
+    # @return [Array<(Radix::Rational, Radix::Rational)>]
     def coerce(value)
       [Radix::Rational.new(value), self]  
     end
 
     private
 
-    # Perform operation.
+    ##
+    # Perform passed arithmetic operation.
     #
-    # Returns new rational. [Radix::Rational]
+    # @param [#to_r] other  
+    # @return [Radix::Rational] Returns the result of the operation in @base.
     def operation(op, other)
       x = value.__send__(op, other.to_r)
       self.class.new(x, base)
     end
 
+    ##
     # Perform base conversion.
     #
-    # Returns array of places. [Array]
+    # @return [Array<Fixnum, String>] Array of places.
     def base_conversion(value, base)
       #if value < 0
       #  @negative, value = true, value.abs
@@ -213,11 +281,11 @@ module Radix
 end
 
 class ::Array
-  # Convenience method for creating a Radix::Rational.
-  #
-  # TODO: Keep #br? Or find another way?
+  ##
+  # Adds convenience method for creating a Radix::Rational.
   #
-  # Returns [Radix::Rational]
+  # @todo Keep #br? Or find another way?
+  # @return [Radix::Rational]
   def br(base=nil)
     args = dup
     args << base if base
@@ -227,6 +295,11 @@ end
 
 if RUBY_VERSION < '1.9'
   class ::Float
+
+    ##
+    # Adds a #to_r method to pre-1.9 ruby Rationals.
+    # 
+    # @return [Rational] 
     def to_r
       n, f = to_s.split('.')
       d = (10 ** f.size).to_i