magician 0.2.1 → 0.3.0

data/lib/magician/math.rb

@@ -1,121 +1,172 @@
 # Magician's extensions to the Math module.
 module Math
 
-	# If we don't do this, our new methods won't get added onto Math.
-	extend self
-
-	# Solves a quadratic formula of the form "ax^2+bx+c=0" for x, where a is not
-	# 0. It asks for the three coefficients of the function (a, b, and c), and
-	# returns the two possible values for x. Returns nil if a is 0.
-	#
-	# @param [Numeric] a the first coefficient (must not be 0)
-	# @param [Numeric] b the second coefficient
-	# @param [Numeric] c the third coefficient
-	#
-	# @return [Array] a sorted array of two Floats, the two possible values for x
-	def quadratic(a, b, c)
-		return nil if a.zero?
-		left = -b
-		right = Math.sqrt(b**2 - 4*a*c)
-		bottom = 2*a
-		[ (left+right)/bottom, (left-right)/bottom ].sort
-	end
-
-	# The number of size k ordered subsets of a set of size n. Equivalent to
-	# n!/(n-k)!. Returns nil if either is negative, or if n < k.
-	#
-	# @param [Integer] n the size of the set to pick from
-	# @param [Integer] k the size of the ordered subsets
-	#
-	# @return [Integer] the number of permutations
-	def permutations(n, k)
-		return nil if n < 0 or k < 0 or n < k
-		n.factorial / (n-k).factorial
-	end
-
-	# The number of size k unordered subsets of a set of size n. Equivalent to
-	# n!/(k!(n-k)!). Returns nil if either is negative, or if n < k.
-	#
-	# @param [Integer] n the size of the set to pick from
-	# @param [Integer] k the size of the unordered subsets
-	#
-	# @return [Integer] the number of combinations
-	def combinations(n, k)
-		return nil if n < 0 or k < 0 or n < k
-		n.factorial / (k.factorial * (n-k).factorial)
-	end
-
-	# Get the number of steps it takes to get from integer n to 1 using the
-	# Collatz conjecture (set http://en.wikipedia.org/wiki/Collatz_conjecture).
-	# Returns nil if n < 1.
-	#
-	# @param [Integer] n the number to put into the Collatz conjecture initially
-	# @param [Integer] depth the number of steps that have passed so far (should
-	# not be modified unless this is being cached carefully)
-	#
-	# @return [Integer] the number of steps it takes to get from integer n to 1
-	# using the Collatz conjecture (the depth)
-	def collatz(n, depth=0)
-		return nil if n < 1
-		if n == 1
-			depth
-		elsif n % 2 == 0
-			depth += 1
-			collatz(n/2, depth)
-		else
-			depth += 1
-			collatz(3*n + 1, depth)
-		end
-	end
-
-	# Using the Pythagorean theorem, gets c (the length of the hypotenuse) when a
-	# and b (the lengths of the other sides of a triangle) are given. Returns nil
-	# if either a or b is negative.
-	#
-	# @param [Numeric] a the length of the first side of the triangle
-	# @param [Numeric] b the length of the second side of the triangle
-	#
-	# @return [Float] the length of the hypotenuse of the triangle
-	def hypotenuse(a, b)
-		[a,b].each do |n|
-			return nil if n < 0
-		end
-		Math.sqrt(a**2 + b**2)
-	end
-
-	# Returns true if the three given numbers are positive integers that form a
-	# Pythagorean triplet (that is, if a^2+b^2=c^2). C must be the last parameter.
-	#
-	# @param [Integer] a the length of the first side of the triangle
-	# @param [Integer] b the length of the second side of the triangle
-	# @param [Integer] c the length of the hypotenuse of the triangle
-	#
-	# @return [Boolean] true if the three numbers form a Pythagorean triplet
-	def triplet?(a, b, c)
-		inputs_are_valid = true
-		[a,b,c].each do |n|
-			inputs_are_valid = false if n < 1 or not n.class <= Integer
-		end
-		return false unless inputs_are_valid
-		a**2 + b**2 == c**2
-	end
-
-	# Calculates a series of Fibonacci numbers of a specified length. Returns nil
-	# if a negative length is given.
-	#
-	# @param [Integer] length the length of the Fibonacci series that should be
-	# returned
-	#
-	# @return [Array] a Fibonacci series of Integers with the specified length
-	# (ordered)
-	def fibs length
-		return nil if length < 0
-		terms = []
-		until terms.length == length do
-			at_beginning = [0,1].include? terms.length
-			terms << ( at_beginning ? 1 : terms[-2] + terms[-1] )
-		end
-		terms
-	end
+  # If we don't do this, our new methods won't get added onto Math.
+  extend self
+
+  # Solves a quadratic formula of the form "ax^2+bx+c=0" for x, where a is not
+  # 0. It asks for the three coefficients of the function (a, b, and c), and
+  # returns the two possible values for x. Complex number results are not
+  # supported yet.
+  #
+  # @param [Numeric] a the first coefficient (must not be 0)
+  # @param [Numeric] b the second coefficient
+  # @param [Numeric] c the third coefficient
+  #
+  # @return [Array] a sorted array of two Floats, the two possible values for x
+  #
+  # @raise [ArgumentError] if a is 0
+  def quadratic(a, b, c)
+    raise ArgumentError, 'a cannot be zero' if a.zero?
+
+    left = -b
+    right = Math.sqrt(b**2 - 4*a*c)
+    bottom = 2*a
+
+    [ (left+right)/bottom, (left-right)/bottom ].sort
+  end
+
+  # The number of size k ordered subsets of a set of size n. Equivalent to
+  # n!/(n-k)!.
+  #
+  # @param [Integer] n the size of the set to pick from
+  # @param [Integer] k the size of the ordered subsets
+  #
+  # @return [Integer] the number of permutations
+  #
+  # @raise [ArgumentError] if either argument is negative, or if n < k
+  def permutations(n, k)
+    raise ArgumentError, 'n cannot be negative' if n < 0
+    raise ArgumentError, 'k cannot be negative' if k < 0
+    raise ArgumentError, 'n must be at least as large as k' if n < k
+
+    n.factorial / (n-k).factorial
+  end
+
+  # The number of size k unordered subsets of a set of size n. Equivalent to
+  # n!/(k!(n-k)!).
+  #
+  # @param [Integer] n the size of the set to pick from
+  # @param [Integer] k the size of the unordered subsets
+  #
+  # @return [Integer] the number of combinations
+  #
+  # @raise [ArgumentError] if either argument is negative, or if n < k
+  def combinations(n, k)
+    raise ArgumentError, 'n cannot be negative' if n < 0
+    raise ArgumentError, 'k cannot be negative' if k < 0
+    raise ArgumentError, 'n must be at least as large as k' if n < k
+
+    n.factorial / (k.factorial * (n-k).factorial)
+  end
+
+  # Get the number of steps it takes to get from integer n to 1 using the
+  # Collatz conjecture.
+  #
+  # @see http://en.wikipedia.org/wiki/Collatz_conjecture
+  #
+  # @param [Integer] n the number to put into the Collatz conjecture initially
+  # @param [Integer] depth the number of steps that have passed so far (should
+  #   not be modified unless this is being cached carefully)
+  #
+  # @return [Integer] the number of steps it takes to get from integer n to 1
+  #   using the Collatz conjecture (the depth)
+  #
+  # @raise [ArgumentError] if n < 1
+  def collatz(n, depth=0)
+    raise ArgumentError, 'n must be at least 1' if n < 1
+
+    if n == 1
+      depth
+    elsif n % 2 == 0
+      depth += 1
+      collatz(n/2, depth)
+    else
+      depth += 1
+      collatz(3*n + 1, depth)
+    end
+  end
+
+  # Using the Pythagorean theorem, gets c (the length of the hypotenuse) when a
+  # and b (the lengths of the other sides of a triangle) are given.
+  #
+  # @param [Numeric] a the length of the first side of the triangle
+  # @param [Numeric] b the length of the second side of the triangle
+  #
+  # @return [Float] the length of the hypotenuse of the triangle
+  #
+  # @raise [ArgumentError] if either argument is negative
+  def hypotenuse(a, b)
+    raise ArgumentError, 'a cannot be negative' if a < 0
+    raise ArgumentError, 'b cannot be negative' if b < 0
+
+    Math.sqrt(a**2 + b**2)
+  end
+
+  # Returns true if the three given numbers are positive integers that form a
+  # Pythagorean triplet (that is, if a^2+b^2=c^2). C must be the last parameter.
+  #
+  # @param [Integer] a the length of the first side of the triangle
+  # @param [Integer] b the length of the second side of the triangle
+  # @param [Integer] c the length of the hypotenuse of the triangle
+  #
+  # @return [Boolean] true if the three numbers form a Pythagorean triplet
+  def triplet?(a, b, c)
+    return false if [a, b, c].any? { |n| n < 1 or not n.class <= Integer }
+
+    a**2 + b**2 == c**2
+  end
+
+  # Calculates a series of Fibonacci numbers of a specified length. Note that
+  # if terms are not passed to this method, it will start generating numbers
+  # with the terms [1, 1].
+  #
+  # @param [Integer] length the length of the Fibonacci series that should be
+  #   returned
+  #
+  # @return [Array] a Fibonacci series of Integers with the specified length
+  #   (ordered)
+  #
+  # @raise [ArgumentError] if a negative length is given, or if less than two
+  #   terms are given
+  def fibs length, terms = [1, 1]
+    raise ArgumentError, 'Length must be at least 0' if length < 0
+    raise ArgumentError, 'At least two terms must be given' if terms.length < 2
+
+    terms << (terms[-2] + terms[-1]) while terms.length < length
+
+    terms.first length
+  end
+
+  # Finds all prime numbers from 1 to a given number n (inclusive) using the
+  # Sieve of Eratosthenes.
+  #
+  # @see http://www.algorithmist.com/index.php/Prime_Sieve_of_Eratosthenes
+  #
+  # @param [Integer] limit the upper limit of all primes to find (inclusive)
+  #
+  # @return [Array] an array of integers containing all discovered primes (in
+  #   increasing order)
+  def primes limit
+    # Initialize the array of booleans
+    is_prime = [true] * (limit+1)
+    is_prime[0] = false
+    is_prime[1] = false
+
+    # Check for composite numbers and update the array with results
+    2.upto(Math.sqrt limit).each do |i|
+      if is_prime[i]
+        # Mark all multiples of i as composite
+        2.upto(limit).each do |factor|
+          multiple = i * factor
+          break if multiple > limit
+          is_prime[multiple] = false
+        end
+      end
+    end
+
+    # Create an array of prime integers by iterating over the array of booleans
+    1.upto(limit).reduce [] { |primes, i| is_prime[i] ? primes << i : primes }
+  end
 
 end

data/lib/magician/numeric.rb

@@ -1,31 +1,43 @@
 # Magician's extensions to the Numeric class (affects Integers and Floats).
 class Numeric
 
-	# Returns true if the number is evenly divisible by n. If n is equal to 0, it
-	# returns false, since numbers cannot be divided by 0 in real number
-	# arithmetic.
-	#
-	# @param [Numeric] n the number that this number (self) should be divided by
-	#
-	# @return [Boolean] true if the number is evenly divisible by n
-	def divisible? n
-		return false if n.zero?
-		(self % n).zero?
-	end
+  # Returns true if the number is evenly divisible by n. If n is equal to 0, it
+  # returns false, since numbers cannot be divided by 0 in real number
+  # arithmetic.
+  #
+  # @param [Numeric] n the number that this number (self) should be divided by
+  #
+  # @return [Boolean] true if the number is evenly divisible by n
+  def divisible? n
+    n.zero? ? false : modulo(n).zero?
+  end
 
-	# Performs to_s[selection].to_i on the number. Note that for floats, the
-	# decimal counts as a digit within the string.
-	# TODO: Let this intelligently convert back to an Integer or Float.
-	#
-	# @param [Range] selection the selection/range to get from the number (you can
-	# use anything that works with the [] syntax)
-	#
-	# @return [Integer] substring of the number (using []), converted to an
-	# Integer
-	# 
-	# @deprecated because it's useless and wrong
-	def digits selection
-		to_s[selection].to_i
-	end
+  # Performs to_s[selection].to_i on the number. Note that for floats, the
+  # decimal counts as a digit within the string.
+  #
+  # @param [Range] selection the selection/range to get from the number (you can
+  #   use anything that works with the [] syntax)
+  #
+  # @return [Integer] substring of the number (using []), converted to an
+  #   Integer
+  #
+  # @deprecated Avoid using this any more. It's inaccurate and not very useful.
+  def digits selection
+    to_s[selection].to_i
+  end
 
-end
+  # Converts the number from degrees to radians and returns the result.
+  #
+  # @return [Numeric] the number in radians
+  def to_radians
+    self * Math::PI / 180
+  end
+
+  # Converts the number from radians to degrees and returns the result.
+  #
+  # @return [Numeric] the number in degrees
+  def to_degrees
+    self * 180 / Math::PI
+  end
+
+end

data/lib/magician/random.rb

@@ -0,0 +1,31 @@
+# Magician's extensions to the Random class.
+class Random
+
+  # For all the instance methods defined below, add a class method which invokes
+  # the instance method on DEFAULT.
+  [:boolean, :coin, :die].each do |name|
+    define_singleton_method(name) { DEFAULT.send name }
+  end
+
+  # Returns a random boolean (true or false).
+  #
+  # @return [Boolean] true or false
+  def boolean
+    [true, false].sample random: self
+  end
+
+  # Returns a random coin toss (heads or tails).
+  #
+  # @return [String] 'heads' or 'tails'
+  def coin
+    ['heads', 'tails'].sample random: self
+  end
+
+  # Returns a random die roll (from 1-6).
+  #
+  # @return [Fixnum] a Fixnum from 1-6
+  def die
+    rand 1..6
+  end
+
+end

data/lib/magician/shortcuts.rb

@@ -6,5 +6,8 @@ PI = Math::PI
 # Alias Math::E to E
 E = Math::E
 
-# the Golden ratio
-GOLDEN_RATIO = (1 + Math.sqrt(5))/2
+# Alias Complex::I to I
+I = Complex::I
+
+# The golden ratio
+GOLDEN_RATIO = (1 + Math.sqrt(5))/2

data/lib/magician/string.rb

@@ -1,12 +1,12 @@
 # Magician's extensions to the String class.
 class String
 
-	# Returns true if the string is a palindrome (meaning it is the same forward
-	# and backward).
-	#
-	# @return [Boolean] true if the string is a palindrome
-	def palindrome?
-		self == reverse
-	end
+  # Returns true if the string is a palindrome (meaning it is the same forward
+  # and backward).
+  #
+  # @return [Boolean] true if the string is a palindrome
+  def palindrome?
+    eql? reverse
+  end
 
 end

data/magician.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "magician"
-  s.version = "0.2.1"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Nicolas McCurdy"]
-  s.date = "2012-12-10"
+  s.date = "2013-03-18"
   s.description = "A suite of handy methods for doing calculations in irb."
   s.email = "thenickperson@gmail.com"
   s.extra_rdoc_files = [
@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
     "lib/magician/integer.rb",
     "lib/magician/math.rb",
     "lib/magician/numeric.rb",
+    "lib/magician/random.rb",
     "lib/magician/shortcuts.rb",
     "lib/magician/string.rb",
     "magician.gemspec",
@@ -38,6 +39,7 @@ Gem::Specification.new do |s|
     "spec/integer_spec.rb",
     "spec/math_spec.rb",
     "spec/numeric_spec.rb",
+    "spec/random_spec.rb",
     "spec/shortcuts_spec.rb",
     "spec/spec_helper.rb",
     "spec/string_spec.rb"
@@ -45,34 +47,34 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/thenickperson/magician"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.24"
+  s.rubygems_version = "1.8.23"
   s.summary = "A suite of handy methods for doing calculations in irb."
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, ["~> 2.12.0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.13"])
       s.add_development_dependency(%q<yard>, ["~> 0.7"])
-      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_development_dependency(%q<bundler>, [">= 0"])
-      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 4.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.2"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8"])
+      s.add_development_dependency(%q<simplecov>, ["~> 0.7"])
     else
-      s.add_dependency(%q<rspec>, ["~> 2.12.0"])
+      s.add_dependency(%q<rspec>, ["~> 2.13"])
       s.add_dependency(%q<yard>, ["~> 0.7"])
-      s.add_dependency(%q<rdoc>, ["~> 3.12"])
-      s.add_dependency(%q<bundler>, [">= 0"])
-      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<rdoc>, ["~> 4.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.2"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8"])
+      s.add_dependency(%q<simplecov>, ["~> 0.7"])
     end
   else
-    s.add_dependency(%q<rspec>, ["~> 2.12.0"])
+    s.add_dependency(%q<rspec>, ["~> 2.13"])
     s.add_dependency(%q<yard>, ["~> 0.7"])
-    s.add_dependency(%q<rdoc>, ["~> 3.12"])
-    s.add_dependency(%q<bundler>, [">= 0"])
-    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
-    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<rdoc>, ["~> 4.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.2"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8"])
+    s.add_dependency(%q<simplecov>, ["~> 0.7"])
   end
 end