quadratic_number 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 705d8a42df709867ad6b91d3640cef83984ef48b
-  data.tar.gz: 34a4ac05039bdbbc0a79b8b5d3b3f3e9a22a9fd0
+  metadata.gz: 592839e562c20b3ad315b30b1d4b6806b87610fd
+  data.tar.gz: 7f5bc9f6afdd48da7aa698be16a1f9914ad8ce72
 SHA512:
-  metadata.gz: a324310465b08035e341a90d58fe1eefcfa89fce53c2e16384794090a7a1cc8c78f6d628dcaeede2e39d9d0c7b63f545443618c31b597596075344e361de9165
-  data.tar.gz: 29bd1b248cffc3b4fb7678ae609186323fd30851bac9fec0414e116981b40cd7f408f0d26fb9b93216cb66acceaac76fe732f76d952266ada9cbde0f64b5e408
+  metadata.gz: b3a2450f1d646157ea8fb744f9d6327967bbba6c949f7d75d4c0a53cd20d54d49f5d613df04feb590aa4842ccf8ca3fffe34a4bf87acea2d81d82b18fab5354c
+  data.tar.gz: 4daf1c009dd3c709aee9cb14a76f783f3f46778e55f9a28f4d20c75c6195bdba129299ad1a6b1f2338a5cb7b680d42bb8b8d84f7ca8d440b660093563654eb8b

data/lib/quadratic_number/imag.rb

@@ -1,11 +1,20 @@
 require_relative '../quadratic_number'
 
-class Quadratic::Imag # < Quadratic < Numeric
+##
+# Abstract class for <tt>Quadratic[d]</tt> (d < 0).
+#
+# Instances behave like those of <tt>Complex</tt>.
+# See <tt>#to_c</tt> for details of the complex expression.
+#
+class Quadratic::Imag
 	### Classification ###
 
 	# defined by Numeric:
 	# * integer? #=> false
 
+	##
+	# Returns false.
+	#
 	def real?
 		false
 	end
@@ -19,6 +28,11 @@ class Quadratic::Imag # < Quadratic < Numeric
 
 	undef <=>
 	undef_method(*Comparable.public_instance_methods(false))
+
+	##
+	# @param [Object] other
+	# @return [Boolean]
+	#
 	def ==(other)
 		if other.kind_of?(Numeric)
 			self.to_c - other == 0
@@ -35,6 +49,18 @@ class Quadratic::Imag # < Quadratic < Numeric
 
 	### Type conversions ###
 
+	##
+	# Returns an equivalent complex.
+	# Its imaginary part is usually a <tt>Quadratic::Real</tt>.
+	#
+	# @return [Complex]
+	#
+	# @example
+	#   Quadratic[-3].new(1, 2)      #=> (1+2√-3)
+	#   Quadratic[-3].new(1, 2).to_c #=> (1+(0+2√3)*i)
+	#   Quadratic[-1].new(3, 4)      #=> (3+4√-1)
+	#   Quadratic[-1].new(3, 4).to_c #=> (3+4i)
+	#
 	def to_c
 		d = self.class::D
 		if d == -1
@@ -45,6 +71,31 @@ class Quadratic::Imag # < Quadratic < Numeric
 		end
 	end
 
+	##
+	# @!method to_f
+	# @return [Float]
+	# @raise [RangeError] if its imaginary part is not zero.
+	#
+
+	##
+	# @!method to_r
+	# @return [Rational]
+	# @raise [RangeError] if its imaginary part is not zero.
+	#
+
+	##
+	# @!method rationalize(eps)
+	# @param [Numeric] eps
+	# @return [Rational]
+	# @raise [RangeError] if its imaginary part is not zero.
+	#
+
+	##
+	# @!method to_i
+	# @return [Integer]
+	# @raise [RangeError] if its imaginary part is not zero.
+	#
+
 	{
 		:to_f => Float,
 		:to_r => Rational,
@@ -66,6 +117,36 @@ class Quadratic::Imag # < Quadratic < Numeric
 	alias conjugate conj
 	alias abs2 norm
 
+	##
+	# @!method rect
+	# @return [[Integer/Rational, Quadratic[-d]]]
+	#
+
+	##
+	# @!method real
+	# @return [Integer/Rational]
+	#
+
+	##
+	# @!method imag
+	# @return [Quadratic[-d]]
+	#
+
+	##
+	# @!method abs
+	# @return [Real]
+	#
+
+	##
+	# @!method arg
+	# @return [Real]
+	#
+
+	##
+	# @!method polar
+	# @return [[Real, Real]]
+	#
+
 	[:rect, :real, :imag, :abs, :arg, :polar].each do |sym|
 		define_method(sym) do
 			to_c.send(sym)

data/lib/quadratic_number/real.rb

@@ -1,6 +1,9 @@
 require_relative '../quadratic_number'
 
-class Quadratic::Real # < Quadratic < Numeric
+##
+# Abstract class for <tt>Quadratic[d]</tt> (d > 0).
+#
+class Quadratic::Real
 	### Classification ###
 
 	# defined by Numeric:
@@ -21,6 +24,10 @@ class Quadratic::Real # < Quadratic < Numeric
 
 	### Comparisons ###
 
+	##
+	# @param [Object] other
+	# @return [+1/0/-1/nil]
+	#
 	def <=>(other)
 		if other.kind_of?(Numeric)
 			if other.real?
@@ -34,6 +41,10 @@ class Quadratic::Real # < Quadratic < Numeric
 		end
 	end
 
+	##
+	# @param [Object] other
+	# @return [Boolean]
+	#
 	def ==(other)
 		if other.kind_of?(Numeric) && other.real?
 			(self - other).to_f == 0
@@ -47,6 +58,16 @@ class Quadratic::Real # < Quadratic < Numeric
 	# defined by Numeric:
 	# * to_c #=> Complex.rect(self, 0)
 
+	##
+	# Returns a float.
+	# Prevents cancellations of significant digits.
+	#
+	# @return [Float]
+	#
+	# @example
+	#   -665857 + 470832 * Math.sqrt(2)        #=> -7.508788257837296e-07
+	#   Quadratic[2].new(-665857, 470832).to_f #=> -7.509119826032946e-07
+	#
 	def to_f
 		d = self.class::D
 		if @a * @b < 0
@@ -58,6 +79,22 @@ class Quadratic::Real # < Quadratic < Numeric
 		end
 	end
 
+	##
+	# @!method to_r
+	# @return [Rational]
+	#
+
+	##
+	# @!method rationalize(eps)
+	# @param [Numeric] eps
+	# @return [Rational]
+	#
+
+	##
+	# @!method to_i
+	# @return [Integer]
+	#
+
 	[:to_r, :rationalize, :to_i].each do |sym|
 		define_method(sym) do |*args|
 			(@b == 0 ? @a : to_f).send(sym, *args)

data/lib/quadratic_number.rb

@@ -1,8 +1,31 @@
 require 'prime' # Prime.prime_division
 
+##
+# Base class.
+#
+# Users must specify a square-free integer to get a concrete class (see class method +.[]+).
+#
 class Quadratic < Numeric
 	@@classes = {}
 
+	# @!parse class Real < self; end
+
+	# @!parse class Imag < self; end
+
+	##
+	# Provides a concrete class.
+	#
+	# @param [Integer] d
+	# @return [Class]
+	# @raise [TypeError] if +d+ is not an integer.
+	# @raise [RangeError] if +d+ is not square-free.
+	#
+	# @example
+	#   Quadratic[2].ancestors.take(4)
+	#   #=> [Quadratic[2], Quadratic::Real, Quadratic, Numeric]
+	#   Quadratic[-1].ancestors.take(4)
+	#   #=> [Quadratic[-1], Quadratic::Imag, Quadratic, Numeric]
+	#
 	def self.[](d)
 		# return a memoized subclass if exists
 		return @@classes[d] if @@classes[d]
@@ -40,6 +63,13 @@ class Quadratic < Numeric
 	attr_reader :a, :b
 	protected   :a, :b
 
+	##
+	# Returns <tt>(a+b√d)</tt>.
+	#
+	# @example
+	#   phi   = Quadratic[5].new(1, 1) / 2     #=> ((1/2)+(1/2)*√5)
+	#   omega = Quadratic[-3].new(-1, 1) / 2   #=> ((-1/2)+(1/2)*√-3)
+	#
 	def initialize(a, b = 0)
 		unless [a, b].all? { |x| __rational__(x) }
 			raise TypeError, "not a rational"
@@ -51,6 +81,13 @@ class Quadratic < Numeric
 
 	### Basic arithmetic operations ###
 
+	##
+	# Performs type conversion.
+	#
+	# @param [Numeric] other
+	# @return [[Numeric, Numeric]] +other+ and +self+
+	# @raise [TypeError]
+	#
 	def coerce(other)
 		my_class = self.class
 		if other.kind_of?(my_class)
@@ -79,6 +116,12 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Performs addition.
+	#
+	# @param [Numeric] other
+	# @return [Quadratic[d]]
+	#
 	def +(other)
 		my_class = self.class
 		if other.kind_of?(my_class)
@@ -90,6 +133,12 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Performs subtraction.
+	#
+	# @param [Numeric] other
+	# @return [Quadratic[d]]
+	#
 	def -(other)
 		my_class = self.class
 		if other.kind_of?(my_class)
@@ -101,6 +150,12 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Performs multiplication.
+	#
+	# @param [Numeric] other
+	# @return [Quadratic[d]]
+	#
 	def *(other)
 		my_class = self.class
 		if other.kind_of?(my_class)
@@ -114,6 +169,12 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Performs division.
+	#
+	# @param [Numeric] other
+	# @return [Quadratic[d]]
+	#
 	def quo(other)
 		my_class = self.class
 		if other.kind_of?(my_class)
@@ -129,6 +190,12 @@ class Quadratic < Numeric
 	end
 	alias / quo
 
+	##
+	# Performs division.
+	#
+	# @param [Numeric] other
+	# @return [Float/Complex]
+	#
 	def fdiv(other)
 		if other.kind_of?(Quadratic)
 			self.to_builtin.fdiv(other.to_builtin)
@@ -140,9 +207,15 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Performs exponentiation.
+	#
+	# @param [Numeric] index
+	# @return [Quadratic[d]/Float/Complex]
+	#
 	def **(index)
 		unless index.kind_of?(Numeric)
-			num1, num2 = other.coerce(self)
+			num1, num2 = index.coerce(self)
 			return num1 ** num2
 		end
 
@@ -162,7 +235,7 @@ class Quadratic < Numeric
 		end
 
 		# quadratic -> rational or integer / float or complex
-		if index.kind_of?(Quadratic) && index.b == 0
+		if index.kind_of?(Quadratic)
 			if index.b == 0
 				index = index.a
 			else
@@ -194,6 +267,12 @@ class Quadratic < Numeric
 
 	### Comparisons ###
 
+	##
+	# Returns true if the two numbers are equal including their types.
+	#
+	# @param [Object] other
+	# @return [Boolean]
+	#
 	def eql?(other)
 		if other.kind_of?(self.class)
 			@a.eql?(other.a) && @b.eql?(other.b)
@@ -202,6 +281,11 @@ class Quadratic < Numeric
 		end
 	end
 
+	##
+	# Returns a hash value.
+	#
+	# @return [Integer]
+	#
 	def hash
 		[@a, @b, self.class::D].hash
 	end
@@ -216,11 +300,21 @@ class Quadratic < Numeric
 
 	### Type conversions ###
 
+	##
+	# Convert to a bilt-in class' object.
+	#
+	# @return [Float/Complex]
+	#
 	def to_builtin
 		real? ? to_f : to_c
 	end
 	protected :to_builtin
 
+	##
+	# Returns a string.
+	#
+	# @return [String]
+	#
 	def inspect
 		'(' << __format__(:inspect) << ')'
 	end
@@ -228,12 +322,22 @@ class Quadratic < Numeric
 
 	### Utilities ###
 
+	##
+	# Returns its denominator.
+	#
+	# @return [Integer]
+	#
 	def denominator
 		ad = @a.denominator
 		bd = @b.denominator
 		ad.lcm(bd)
 	end
 
+	##
+	# Returns its numerator.
+	#
+	# @return [Quadratic[d]]
+	#
 	def numerator
 		an = @a.numerator
 		ad = @a.denominator
@@ -245,16 +349,31 @@ class Quadratic < Numeric
 
 	### Extensions for Quadratic ###
 
+	##
+	# Returns its quadratic conjugate.
+	#
+	# @return [Quadratic[d]]
+	#
 	def qconj
 		self.class.new(@a, -@b)
 	end
 	alias quadratic_conjugate qconj
 
+	##
+	# Returns its trace.
+	#
+	# @return [Integer/Rational]
+	#
 	def trace
 		# self + self.qconj
 		@a * 2
 	end
 
+	##
+	# Returns its norm.
+	#
+	# @return [Integer/Rational]
+	#
 	def norm
 		# self * self.qconj
 		@a * @a - @b * @b * self.class::D
@@ -262,6 +381,11 @@ class Quadratic < Numeric
 	alias qabs2 norm
 	alias quadratic_abs2 qabs2
 
+	##
+	# Returns its discriminant.
+	#
+	# @return [Integer/Rational]
+	#
 	def discriminant
 		# trace ** 2 - 4 * norm
 		@b * @b * (self.class::D * 4)

data/quadratic_number.gemspec

@@ -3,12 +3,12 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "quadratic_number"
-  spec.version       = "0.0.1"
+  spec.version       = "0.0.2"
   spec.authors       = ["Masahiro Nomoto"]
   spec.email         = ["hmmnrst@users.noreply.github.com"]
 
   spec.summary       = %q{Quadratic class}
-  spec.description   = %q{Provides a numeric class Quadratic to represent a+b\u221ad exactly}
+  spec.description   = %q{Provides a numeric class Quadratic to represent a+b√d exactly}
   spec.homepage      = "https://github.com/hmmnrst/quadratic_number"
   spec.license       = "MIT"
 

metadata

@@ -1,67 +1,67 @@
 --- !ruby/object:Gem::Specification
 name: quadratic_number
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Masahiro Nomoto
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-01 00:00:00.000000000 Z
+date: 2017-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Provides a numeric class Quadratic to represent a+b\u221ad exactly
+description: Provides a numeric class Quadratic to represent a+b√d exactly
 email:
 - hmmnrst@users.noreply.github.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -82,17 +82,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Quadratic class