vector2d 2.3.0 → 3.0.0

data/lib/vector2d/lengths.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The length of a vector, the distance between two, and the
+  # operations that change the length while keeping the direction.
+  module Lengths
+    # Length of vector.
+    #
+    #   Vector2d(2, 3).length # => 3.6055..
+    #
+    # @return [Float]
+    def length
+      Math.sqrt(length_squared)
+    end
+    alias magnitude length
+    alias norm length
+
+    # Squared length of vector. Avoids the square root when lengths are
+    # only being compared to each other.
+    #
+    #   Vector2d(2, 3).length_squared # => 13
+    #
+    # @return [Integer, Float, Rational, BigDecimal]
+    def length_squared
+      (x * x) + (y * y)
+    end
+
+    # @deprecated Use #length_squared instead.
+    #
+    # @return [Integer, Float, Rational, BigDecimal]
+    def squared_length
+      warn_deprecated("Vector2d#squared_length is deprecated. Use #length_squared instead.")
+      length_squared
+    end
+
+    # Is this the zero vector?
+    #
+    #   Vector2d(0, 0).zero? # => true
+    #   Vector2d(2, 3).zero? # => false
+    #
+    # @return [Boolean]
+    def zero?
+      length_squared.zero?
+    end
+
+    # Is this the zero vector, give or take floating point drift? See
+    # #approx_equal? for what the tolerance is.
+    #
+    #   Vector2d(0, 0).approx_zero?     # => true
+    #   Vector2d(1e-17, 0).approx_zero? # => true
+    #   Vector2d(1e-15, 0).approx_zero? # => false
+    #
+    # An explicit tolerance is an absolute length.
+    #
+    #   Vector2d(0.2, 0).approx_zero?(0.5) # => true
+    #
+    # @param tolerance [Integer, Float, Rational, BigDecimal, nil]
+    #   an absolute length, or nil for the default scaled tolerance
+    # @return [Boolean]
+    def approx_zero?(tolerance = nil)
+      return length <= coordinate(tolerance) unless tolerance.nil?
+
+      near_zero?(length)
+    end
+
+    # Is this a normalized vector?
+    #
+    #   Vector2d(0, 1).normalized? # => true
+    #   Vector2d(2, 3).normalized? # => false
+    #
+    # @return [Boolean]
+    def normalized?
+      near_zero?(length - 1.0)
+    end
+
+    # Normalizes the vector.
+    #
+    #   vector = Vector2d(2, 3)
+    #   vector.normalize        # => Vector2d(0.5547.., 0.8320..)
+    #   vector.normalize.length # => 1.0
+    #
+    # The zero vector has no direction, and is returned unchanged.
+    #
+    #   Vector2d(0, 0).normalize # => Vector2d(0,0)
+    #
+    # @return [self]
+    def normalize
+      resize(1.0)
+    end
+
+    # Changes magnitude of vector.
+    #
+    #   Vector2d(2, 3).resize(1.0) # => Vector2d(0.5547.., 0.8320..)
+    #
+    # The zero vector has no direction, and is returned unchanged.
+    #
+    #   Vector2d(0, 0).resize(1.0) # => Vector2d(0,0)
+    #
+    # A negative length reverses the vector.
+    #
+    #   Vector2d(2, 3).resize(-1.0) # => Vector2d(-0.5547..,-0.8320..)
+    #
+    # @param new_length [Integer, Float, Rational, BigDecimal] the new length
+    # @return [self]
+    def resize(new_length)
+      new_length = coordinate(new_length)
+      return self if zero?
+
+      self * (new_length / length)
+    end
+
+    # Limits the length of the vector, scaling it down if it is longer
+    # than max. The direction is kept.
+    #
+    #   vector = Vector2d(2.0, 3.0)
+    #   vector.limit_length(5.0) # => Vector2d(2.0, 3.0)
+    #   vector.limit_length(1.0) # => Vector2d(0.5547.., 0.8320..)
+    #
+    # #clamp_length bounds the length at both ends.
+    #
+    # The zero vector has no direction, and is returned unchanged.
+    #
+    #   Vector2d(0, 0).limit_length(1.0) # => Vector2d(0,0)
+    #
+    # Lengths can't be negative.
+    #
+    #   Vector2d(2, 3).limit_length(-1.0) # => ArgumentError
+    #
+    # @param max [Integer, Float, Rational, BigDecimal] the maximum length
+    # @return [self]
+    def limit_length(max)
+      resize(length.clamp(..length_bound(max, "max")))
+    end
+
+    # Clamps the length of the vector between a minimum and a maximum,
+    # scaling it up if it is shorter than min and down if it is longer
+    # than max. The direction is kept.
+    #
+    #   vector = Vector2d(2.0, 3.0)
+    #   vector.clamp_length(5.0, 10.0) # => Vector2d(2.7735.., 4.1602..)
+    #   vector.clamp_length(1.0, 10.0) # => Vector2d(2.0, 3.0)
+    #
+    # The bounds can also be given as a single range, which may be
+    # beginless or endless to clamp only one side, as in #clamp.
+    #
+    #   vector.clamp_length(5.0..10.0) # => Vector2d(2.7735.., 4.1602..)
+    #   vector.clamp_length(..1.0)     # => Vector2d(0.5547.., 0.8320..)
+    #   vector.clamp_length(5.0..)     # => Vector2d(2.7735.., 4.1602..)
+    #
+    # A maximum on its own is #limit_length.
+    #
+    # The range must not exclude its end, as with Comparable#clamp.
+    #
+    #   vector.clamp_length(5.0...10.0) # => ArgumentError
+    #
+    # The zero vector has no direction, and is returned unchanged. It
+    # can't be scaled up to a minimum length.
+    #
+    #   Vector2d(0, 0).clamp_length(1.0, 2.0) # => Vector2d(0,0)
+    #
+    # Lengths can't be negative, and min can't exceed max.
+    #
+    #   Vector2d(2, 3).clamp_length(-1.0, 1.0) # => ArgumentError
+    #   Vector2d(2, 3).clamp_length(4.0, 2.0)  # => ArgumentError
+    #
+    # @overload clamp_length(min, max)
+    #   @param min [Integer, Float, Rational, BigDecimal] the minimum length
+    #   @param max [Integer, Float, Rational, BigDecimal] the maximum length
+    # @overload clamp_length(range)
+    #   @param range [Range] both bounds, and may be beginless or endless
+    # @return [self]
+    def clamp_length(min, max = nil)
+      min_length, max_length = clamp_length_bounds(min, max)
+      resize(length.clamp(Range.new(min_length, max_length)))
+    end
+
+    # Calculates the distance between two vectors.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(3, 4)
+    #   v1.distance(v2) # => 1.4142..
+    #
+    # @!macro coercible
+    # @return [Float]
+    def distance(other)
+      (self - other).length
+    end
+
+    # Calculate squared distance between vectors. Avoids the square root
+    # when distances are only being compared to each other.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(5, 6)
+    #   v1.distance_squared(v2) # => 18
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal]
+    def distance_squared(other)
+      (self - other).length_squared
+    end
+
+    # @deprecated Use #distance_squared instead.
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal]
+    def squared_distance(other)
+      warn_deprecated("Vector2d#squared_distance is deprecated. Use #distance_squared instead.")
+      distance_squared(other)
+    end
+
+    # Calculates the Manhattan distance between two vectors, the sum of
+    # the absolute differences along each axis.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(5, 7)
+    #   v1.manhattan_distance(v2) # => 7
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal]
+    def manhattan_distance(other)
+      (self - other).abs.to_a.sum
+    end
+
+    # Calculates the Chebyshev distance between two vectors, the largest
+    # absolute difference along any axis.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v2 = Vector2d(5, 7)
+    #   v1.chebyshev_distance(v2) # => 4
+    #
+    # @!macro coercible
+    # @return [Integer, Float, Rational, BigDecimal]
+    def chebyshev_distance(other)
+      (self - other).abs.to_a.max
+    end
+
+    # Unit vector pointing from this vector to another vector, the
+    # direction a step from here to there would take. The other vector
+    # is coerced, so scalars work too.
+    #
+    #   v1 = Vector2d(2, 3)
+    #   v1.direction_to(Vector2d(2, 6)) # => Vector2d(0.0,1.0)
+    #   v1.direction_to(Vector2d(5, 7)) # => Vector2d(0.6000..,0.8)
+    #
+    # This is (other - self).normalize. #distance measures the same
+    # step, and #move_toward takes it.
+    #
+    # There is no direction to where you already are. The zero vector
+    # has no direction, and is returned.
+    #
+    #   v1.direction_to(v1) # => Vector2d(0,0)
+    #
+    # @!macro coercible
+    # @return [self]
+    def direction_to(other)
+      v = coerce_vector(other)
+      build(v.x - x, v.y - y).normalize
+    end
+
+    private
+
+    def clamp_length_bounds(min, max)
+      return range_length_bounds(min, max) if min.is_a?(Range)
+
+      raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if max.nil?
+
+      [length_bound(min, "min"), length_bound(max, "max")]
+    end
+
+    def range_length_bounds(range, max)
+      range_bounds(range, max).zip(%w[min max]).map do |bound, name|
+        bound && length_bound(bound, name)
+      end
+    end
+
+    # Validates one end of a length clamp. Lengths are never negative.
+    def length_bound(value, name)
+      value = coordinate(value)
+      raise ArgumentError, "negative #{name} length: #{value}" if value.negative?
+
+      value
+    end
+  end
+end

data/lib/vector2d/matrix_interop.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Interoperability with the Matrix and Vector classes from the
+  # standard library.
+  #
+  # The matrix library is a bundled gem, and is only loaded when a
+  # conversion needs it. Nothing here loads it on its own, so it has to
+  # be in the Gemfile of applications using these methods.
+  module MatrixInterop
+    class << self
+      # Is the object a Matrix?
+      #
+      # @param object [Object] any object
+      # @return [Boolean]
+      def matrix?(object)
+        defined?(::Matrix) && object.is_a?(::Matrix)
+      end
+
+      # Is the object a Vector?
+      #
+      # @param object [Object] any object
+      # @return [Boolean]
+      def vector?(object)
+        defined?(::Vector) && object.is_a?(::Vector)
+      end
+    end
+
+    # Implements Ruby's coercion protocol for matrices, so a vector can
+    # be the right hand operand of a matrix. The result is a Vector, as
+    # the matrix is the receiver of the operation.
+    #
+    #   Matrix[[0, -1], [1, 0]] * Vector2d(3, 4) # => Vector[-4, 3]
+    #
+    # Use #transform to get a Vector2d back.
+    #
+    # Vectors are coerced the other way around, as the two dimensional
+    # vector is the more specific type.
+    #
+    #   Vector[1, 2] + Vector2d(3, 4) # => Vector2d(4,6)
+    #
+    # @!macro coercible
+    # @return [Array(::Matrix, ::Vector), Array(self, self)] the other
+    #   operand and this vector, converted to a Vector when the other
+    #   operand is a Matrix
+    def coerce(other)
+      return [other, to_vector] if MatrixInterop.matrix?(other)
+
+      super
+    end
+
+    # Converts vector to a 2x1 column Matrix from the standard library,
+    # the same shape Vector#to_matrix returns.
+    #
+    #   Vector2d(2, 3).to_matrix # => Matrix[[2], [3]]
+    #
+    # @return [::Matrix] a 2x1 column matrix
+    def to_matrix
+      require "matrix"
+      ::Matrix[[x], [y]]
+    end
+
+    # Converts vector to a Vector from the standard library. This is
+    # the only to_* method that leaves the class behind, #to_f_vector
+    # and #to_i_vector return a vector of this class.
+    #
+    #   Vector2d(2, 3).to_vector # => Vector[2, 3]
+    #
+    # @return [::Vector]
+    def to_vector
+      require "matrix"
+      ::Vector[x, y]
+    end
+
+    # Multiplies a 2x2 Matrix by this vector, treating the vector as a
+    # column. Unlike coercion, this keeps the class of the receiver.
+    #
+    #   Vector2d(3, 4).transform(Matrix[[0, -1], [1, 0]])
+    #   # => Vector2d(-4,3)
+    #
+    # Raises TypeError unless the argument is a Matrix, and
+    # ErrDimensionMismatch unless it has two columns.
+    #
+    # @param matrix [::Matrix] a matrix with two columns
+    # @return [self]
+    def transform(matrix)
+      raise TypeError, "#{matrix.class} is not a Matrix" unless MatrixInterop.matrix?(matrix)
+
+      result = matrix * to_vector
+      build(result[0], result[1])
+    end
+  end
+end

data/lib/vector2d/parsing.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The permissive constructor. Everything Vector2d.parse accepts is
+  # recognized here, and turned into two coordinates the class builds a
+  # vector from. It is a module rather than a plain class method, so a
+  # subclass parses into its own kind.
+  module Parsing
+    # Matches a single coordinate in a string, with an optional sign and
+    # an optional fractional part.
+    COORDINATE_EXPRESSION = /[+-]?(?:\d+(?:\.\d+)?|\.\d+)/
+
+    # Matches the string form of a vector, "150x100" or "150,100".
+    # Whitespace is insignificant, the separator is case insensitive, and
+    # either coordinate can be left out to mean zero.
+    STRING_EXPRESSION = /
+      \A\s*(#{COORDINATE_EXPRESSION})?\s*[x,]\s*(#{COORDINATE_EXPRESSION})?\s*\z
+    /xi
+
+    # Stands in for an omitted second argument to .parse, so an explicit
+    # nil can be rejected as a coordinate.
+    NO_ARGUMENT = Object.new.freeze
+
+    private_constant :COORDINATE_EXPRESSION, :STRING_EXPRESSION, :NO_ARGUMENT
+
+    # Parses a vector out of any of the forms below, and is the
+    # permissive counterpart to .new, which takes exactly two
+    # coordinates. Vector2d() is shorthand for this method.
+    #
+    #   Vector2d.parse(150, 100)
+    #   Vector2d.parse(150.0, 100.0)
+    #   Vector2d.parse("150x100")
+    #   Vector2d.parse("150.0x100.0")
+    #   Vector2d.parse([150,100])
+    #   Vector2d.parse({x: 150, y: 100})
+    #   Vector2d.parse({"x" => 150.0, "y" => 100.0})
+    #   Vector2d.parse(Vector2d(150, 100))
+    #   Vector2d.parse(Vector[150, 100])
+    #   Vector2d.parse(Matrix[[150], [100]])
+    #
+    # Strings are either "150x100" or "150,100", optionally signed and
+    # case insensitive. Coordinates keep their type, so "150x100" gives
+    # integers and "150.0x100" gives a float and an integer. An omitted
+    # coordinate is zero, as in "x100".
+    #
+    #   Vector2d.parse("-150X100") # => Vector2d(-150,100)
+    #   Vector2d.parse("150, 100") # => Vector2d(150,100)
+    #   Vector2d.parse("x100")     # => Vector2d(0,100)
+    #
+    # A vector is returned as it is, as long as it is an instance of
+    # the class parsing it. A vector of any other class is rebuilt, so
+    # a subclass is always handed back its own kind.
+    #
+    #   v = Vector2d(150, 100)
+    #   Vector2d.parse(v).equal?(v) # => true
+    #
+    # Raises ArgumentError unless both coordinates resolve to real
+    # numbers. Complex numbers are not coordinates, and are rejected.
+    #
+    #   Vector2d.parse(150, nil)         # => ArgumentError
+    #   Vector2d.parse(Complex(1, 2), 3) # => ArgumentError
+    #
+    # @param arg [Vector2d, Array, String, Hash, Integer, Float,
+    #   Rational, BigDecimal, ::Vector, ::Matrix] the vector, in any of
+    #   the forms above, or its x coordinate
+    # @param second_arg [Integer, Float, Rational, BigDecimal]
+    #   the y coordinate, when the first argument is the x coordinate
+    # @return [Vector2d] a vector of this class, or the argument itself
+    #   when it already is one
+    def parse(arg, second_arg = NO_ARGUMENT)
+      return parse_single_arg(arg) if NO_ARGUMENT.equal?(second_arg)
+
+      build(coordinate(arg), coordinate(second_arg))
+    end
+
+    private
+
+    def parse_single_arg(arg)
+      return parse_vector2d(arg) if arg.is_a?(Vector2d)
+      return parse_array(arg) if arg.is_a?(Array)
+      return parse_str(arg) if arg.is_a?(String)
+      return parse_hash(arg) if arg.is_a?(Hash)
+      return parse_vector(arg) if MatrixInterop.vector?(arg)
+      return parse_matrix(arg) if MatrixInterop.matrix?(arg)
+
+      value = coordinate(arg)
+      build(value, value)
+    end
+
+    def parse_array(array)
+      case array.length
+      when 1 then parse_single_arg(array.first)
+      when 2 then build(coordinate(array[0]), coordinate(array[1]))
+      else
+        raise ArgumentError, "expected 1 or 2 coordinates, got #{array.length}"
+      end
+    end
+
+    def parse_hash(hash)
+      build(coordinate(hash[:x] || hash["x"]),
+            coordinate(hash[:y] || hash["y"]))
+    end
+
+    def parse_matrix(matrix)
+      shape = [matrix.row_count, matrix.column_count]
+      unless [[2, 1], [1, 2]].include?(shape)
+        raise ArgumentError,
+              "expected a 2x1 or 1x2 matrix, got #{shape.join('x')}"
+      end
+
+      values = matrix.to_a.flatten
+      build(coordinate(values[0]), coordinate(values[1]))
+    end
+
+    def parse_vector(vector)
+      raise ArgumentError, "expected 2 coordinates, got #{vector.size}" unless vector.size == 2
+
+      build(coordinate(vector[0]), coordinate(vector[1]))
+    end
+
+    # Returns a vector of this class as it is, and rebuilds one of any
+    # other class.
+    def parse_vector2d(vector)
+      return vector if vector.is_a?(self)
+
+      build(vector.x, vector.y)
+    end
+
+    def parse_str(str)
+      match = STRING_EXPRESSION.match(str)
+      raise ArgumentError, "not a valid string input: #{str.inspect}" unless match
+
+      build(string_coordinate(match[1]), string_coordinate(match[2]))
+    end
+
+    def string_coordinate(value)
+      return 0 if value.nil?
+
+      value.include?(".") ? value.to_f : value.to_i
+    end
+  end
+end