vector2d 2.3.0 → 3.0.0

data/lib/vector2d/componentwise.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Operations applied to each coordinate on its own, the way Numeric
+  # applies them to a number.
+  module Componentwise
+    # Returns the absolute value of each axis. This is component-wise,
+    # not the magnitude of the vector, which is #length.
+    #
+    #   Vector2d(-2, 3).abs  # => Vector2d(2,3)
+    #   Vector2d(-2, -3).abs # => Vector2d(2,3)
+    #
+    # @return [self]
+    def abs
+      build(x.abs, y.abs)
+    end
+
+    # Rounds vector up to nearest integer.
+    #
+    #   Vector2d(2.4, 3.6).ceil        # => Vector2d(3,4)
+    #   Vector2d(2.441, 3.666).ceil(2) # => Vector2d(2.45,3.67)
+    #
+    # @param digits [Integer] the number of decimal places to keep
+    # @return [self]
+    def ceil(digits = 0)
+      build(x.ceil(digits), y.ceil(digits))
+    end
+
+    # Rounds vector down to nearest integer.
+    #
+    #   Vector2d(2.4, 3.6).floor        # => Vector2d(2,3)
+    #   Vector2d(2.444, 3.669).floor(2) # => Vector2d(2.44,3.66)
+    #
+    # @param digits [Integer] the number of decimal places to keep
+    # @return [self]
+    def floor(digits = 0)
+      build(x.floor(digits), y.floor(digits))
+    end
+
+    # Rounds vector to nearest integer.
+    #
+    #   Vector2d(2.4, 3.6).round         # => Vector2d(2,4)
+    #   Vector2d(2.4444, 3.666).round(2) # => Vector2d(2.44,3.67)
+    #
+    # @param digits [Integer] the number of decimal places to keep
+    # @return [self]
+    def round(digits = 0)
+      build(x.round(digits), y.round(digits))
+    end
+
+    # @deprecated Use #limit_length instead. The name belongs to the
+    # #ceil/#floor/#round family, which maps Numeric over both
+    # coordinates.
+    #
+    # @param max [Integer, Float, Rational, BigDecimal] the maximum length
+    # @return [self]
+    def truncate(max)
+      warn_deprecated("Vector2d#truncate is deprecated. Use #limit_length instead.")
+      limit_length(max)
+    end
+
+    # Returns the sign of each axis, -1, 0 or 1.
+    #
+    #   Vector2d(-2, 3).sign # => Vector2d(-1,1)
+    #   Vector2d(0, -3).sign # => Vector2d(0,-1)
+    #
+    # The signs are integers, whatever the coordinates were. There are
+    # only three of them, and they are exact.
+    #
+    #   Vector2d(-2.5, 0.0).sign # => Vector2d(-1,0)
+    #
+    # NaN has no sign, so ArgumentError is raised.
+    #
+    #   Vector2d(Float::NAN, 3).sign # => ArgumentError
+    #
+    # @return [self] a vector of -1, 0 and 1
+    def sign
+      build(coordinate_sign(x), coordinate_sign(y))
+    end
+
+    # Snaps each axis to the nearest multiple of a step. The step is
+    # coerced, so scalars work too, and a vector gives each axis its
+    # own step.
+    #
+    #   vector = Vector2d(23, 47)
+    #   vector.snap(10)              # => Vector2d(20,50)
+    #   vector.snap(Vector2d(10, 5)) # => Vector2d(20,45)
+    #
+    # Coordinates take the type of the step, so an integer step snaps
+    # to integers.
+    #
+    #   Vector2d(2.3, 3.7).snap(1)   # => Vector2d(2,4)
+    #   Vector2d(2.3, 3.7).snap(0.5) # => Vector2d(2.5,3.5)
+    #
+    # A step of zero has no multiples to snap to, and leaves the axis
+    # unchanged.
+    #
+    #   vector.snap(0)               # => Vector2d(23,47)
+    #   vector.snap(Vector2d(10, 0)) # => Vector2d(20,47)
+    #
+    # @!macro coercible
+    # @return [self]
+    def snap(step)
+      v = coerce_vector(step)
+      build(snap_coordinate(x, v.x), snap_coordinate(y, v.y))
+    end
+
+    # Returns the larger value of each axis. The other vector is
+    # coerced, so scalars work too.
+    #
+    #   vector = Vector2d(2, 8)
+    #   vector.max(Vector2d(5, 5)) # => Vector2d(5,8)
+    #   vector.max(5)              # => Vector2d(5,8)
+    #
+    # @!macro coercible
+    # @return [self]
+    def max(other)
+      v = coerce_vector(other)
+      build([x, v.x].max, [y, v.y].max)
+    end
+
+    # Returns the smaller value of each axis. The other vector is
+    # coerced, so scalars work too.
+    #
+    #   vector = Vector2d(2, 8)
+    #   vector.min(Vector2d(5, 5)) # => Vector2d(2,5)
+    #   vector.min(5)              # => Vector2d(2,5)
+    #
+    # @!macro coercible
+    # @return [self]
+    def min(other)
+      v = coerce_vector(other)
+      build([x, v.x].min, [y, v.y].min)
+    end
+
+    # Clamps the vector between two others, one axis at a time. The
+    # bounds are coerced, so scalars work too.
+    #
+    #   vector = Vector2d(2, 8)
+    #   vector.clamp(Vector2d(3, 3), Vector2d(6, 6)) # => Vector2d(3,6)
+    #   vector.clamp(3, 6)                           # => Vector2d(3,6)
+    #
+    # The bounds can also be given as a single range, which may be
+    # beginless or endless to clamp only one side.
+    #
+    #   vector.clamp(3..6) # => Vector2d(3,6)
+    #   vector.clamp(..6)  # => Vector2d(2,6)
+    #   vector.clamp(3..)  # => Vector2d(3,8)
+    #
+    # The range must not exclude its end, as with Comparable#clamp.
+    #
+    #   vector.clamp(3...6) # => ArgumentError
+    #
+    # @overload clamp(min, max)
+    #   @param min [Vector2d, Array, String, Hash, Integer, Float, Rational,
+    #     BigDecimal, ::Vector, ::Matrix] the lower bound, anything
+    #     Vector2d.parse accepts
+    #   @param max [Vector2d, Array, String, Hash, Integer, Float, Rational,
+    #     BigDecimal, ::Vector, ::Matrix] the upper bound
+    # @overload clamp(range)
+    #   @param range [Range] both bounds, and may be beginless or endless
+    # @return [self]
+    def clamp(min, max = nil)
+      min_v, max_v = clamp_bounds(min, max)
+      build(
+        x.clamp(Range.new(min_v&.x, max_v&.x)),
+        y.clamp(Range.new(min_v&.y, max_v&.y))
+      )
+    end
+
+    # Returns the vector with x replaced.
+    #
+    #   Vector2d(2, 3).with_x(5) # => Vector2d(5,3)
+    #
+    # Vectors are immutable, so this is how a single axis is changed.
+    # The value is a coordinate, not a vector, and is not coerced.
+    #
+    #   Vector2d(2, 3).with_x("5") # => ArgumentError
+    #
+    # @param value [Integer, Float, Rational, BigDecimal] the new x coordinate
+    # @return [self]
+    def with_x(value)
+      build(value, y)
+    end
+
+    # Returns the vector with y replaced.
+    #
+    #   Vector2d(2, 3).with_y(5) # => Vector2d(2,5)
+    #
+    # The value is a coordinate, not a vector, and is not coerced.
+    #
+    #   Vector2d(2, 3).with_y(nil) # => ArgumentError
+    #
+    # @param value [Integer, Float, Rational, BigDecimal] the new y coordinate
+    # @return [self]
+    def with_y(value)
+      build(x, value)
+    end
+
+    private
+
+    def clamp_bounds(min, max)
+      if min.is_a?(Range)
+        return range_bounds(min, max)
+               .map { |bound| bound && coerce_vector(bound) }
+      end
+
+      raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if max.nil?
+
+      [coerce_vector(min), coerce_vector(max)]
+    end
+
+    # Splits the range form of #clamp and #clamp_length into its two
+    # ends, either of which can be nil.
+    def range_bounds(range, max)
+      raise ArgumentError, "wrong number of arguments (given 2, expected 1)" unless max.nil?
+      raise ArgumentError, "cannot clamp with an exclusive range" if range.exclude_end?
+
+      [range.begin, range.end]
+    end
+
+    # The sign of a coordinate. Comparing to zero gives one of -1, 0
+    # and 1, or nothing at all for NaN.
+    def coordinate_sign(value)
+      sign = value <=> 0
+      raise ArgumentError, "NaN has no sign" if sign.nil?
+
+      sign
+    end
+
+    # Rounds a coordinate to the nearest multiple of a step. A step of
+    # zero has no multiples, and the coordinate is left alone.
+    def snap_coordinate(value, step)
+      return value if step.zero?
+
+      (value / step.to_f).round * step
+    end
+  end
+end

data/lib/vector2d/constructors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The constructors that build a vector from something other than
+  # coordinates: an angle, a random draw, or a direction. They are
+  # class methods rather than constants, so a subclass gets its own.
+  module Constructors
+    # Creates a vector from an angle in radians, with an optional
+    # length. Angles are measured counterclockwise from the positive x
+    # axis, the same convention #angle follows.
+    #
+    #   Vector2d.from_angle(0)                 # => Vector2d(1.0,0.0)
+    #   Vector2d.from_angle(Math::PI / 4)      # => Vector2d(0.7071..,0.7071..)
+    #   Vector2d.from_angle(Math::PI / 4, 2.0) # => Vector2d(1.4142..,1.4142..)
+    #
+    # Coordinates are always floats. This is the inverse of #to_polar.
+    #
+    #   length, angle = Vector2d(2, 3).to_polar
+    #   Vector2d.from_angle(angle, length) # => Vector2d(2.0,3.0)
+    #
+    # Raises ArgumentError unless both arguments are real numbers.
+    # Complex numbers are not coordinates, and are rejected.
+    #
+    #   Vector2d.from_angle(Complex(1, 2)) # => ArgumentError
+    #
+    # @param angle [Integer, Float, Rational, BigDecimal] the angle in radians
+    # @param length [Integer, Float, Rational, BigDecimal]
+    #   the length of the vector
+    # @return [Vector2d] a vector of the receiver's class
+    def from_angle(angle, length = 1.0)
+      angle = coordinate(angle).to_f
+      length = coordinate(length).to_f
+      build(Math.cos(angle) * length, Math.sin(angle) * length)
+    end
+
+    # Creates a random vector, uniformly distributed by angle, with an
+    # optional length. Coordinates are always floats, as with
+    # .from_angle.
+    #
+    #   Vector2d.random.length.round(6)      # => 1.0
+    #   Vector2d.random(2.0).length.round(6) # => 2.0
+    #
+    # Pass a Random to draw from a seeded sequence.
+    #
+    #   a = Vector2d.random(random: Random.new(42))
+    #   b = Vector2d.random(random: Random.new(42))
+    #   a == b # => true
+    #
+    # Raises ArgumentError unless the length is a real number.
+    #
+    #   Vector2d.random(Complex(1, 2)) # => ArgumentError
+    #
+    # @param length [Integer, Float, Rational, BigDecimal]
+    #   the length of the vector
+    # @param random [#rand] the source of randomness
+    # @return [Vector2d] a vector of the receiver's class
+    def random(length = 1.0, random: Random)
+      from_angle(random.rand * 2 * Math::PI, length)
+    end
+
+    # The zero vector.
+    #
+    #   Vector2d.zero # => Vector2d(0,0)
+    #
+    # This and the five constants below have integer coordinates. They
+    # are exact, and integers keep them exact through arithmetic with
+    # integer vectors, widening to floats only when a float is
+    # involved. .from_angle returns floats instead, because a general
+    # angle has no exact coordinates.
+    #
+    #   Vector2d.zero.x       # => 0
+    #   (Vector2d.up * 2).y   # => 2
+    #   (Vector2d.up * 0.5).y # => 0.5
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def zero
+      build(0, 0)
+    end
+
+    # The vector with both coordinates set to one.
+    #
+    #   Vector2d.one # => Vector2d(1,1)
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def one
+      build(1, 1)
+    end
+
+    # The unit vector pointing up.
+    #
+    #   Vector2d.up       # => Vector2d(0,1)
+    #   Vector2d.up.angle # => 1.5707..
+    #
+    # The y axis grows upwards here, and angles turn counterclockwise
+    # from the positive x axis. That is the convention .from_angle,
+    # #angle, #rotate and #perpendicular all follow. Libraries drawing
+    # in screen coordinates grow the y axis downwards and call (0, -1)
+    # up, so flip the y axis at that boundary.
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def up
+      build(0, 1)
+    end
+
+    # The unit vector pointing down. See .up for the direction the y
+    # axis grows in.
+    #
+    #   Vector2d.down       # => Vector2d(0,-1)
+    #   Vector2d.down.angle # => -1.5707..
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def down
+      build(0, -1)
+    end
+
+    # The unit vector pointing left.
+    #
+    #   Vector2d.left       # => Vector2d(-1,0)
+    #   Vector2d.left.angle # => 3.1415..
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def left
+      build(-1, 0)
+    end
+
+    # The unit vector pointing right, along the positive x axis. This
+    # is the direction angles are measured from.
+    #
+    #   Vector2d.right       # => Vector2d(1,0)
+    #   Vector2d.right.angle # => 0.0
+    #
+    # @return [Vector2d] a vector of the receiver's class
+    def right
+      build(1, 0)
+    end
+  end
+end

data/lib/vector2d/conversions.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Conversions to and from other Ruby objects, including the coercion
+  # protocol and pattern matching. Conversions to the standard library
+  # Matrix and Vector are in Vector2d::MatrixInterop.
+  module Conversions
+    # Implements Ruby's coercion protocol, so a vector can be the right
+    # hand operand of a scalar.
+    #
+    #   2 * Vector2d(3, 4) # => Vector2d(6,8)
+    #
+    # The operand is built through #build, so a subclass is the result
+    # on either side of the operator.
+    #
+    # Matrices are coerced the other way around, see
+    # Vector2d::MatrixInterop#coerce.
+    #
+    # @!macro coercible
+    # @return [Array(self, self)] the coerced operand and this vector
+    def coerce(other)
+      v = coerce_vector(other)
+      [build(v.x, v.y), self]
+    end
+
+    # Returns the components as an array, so a vector can be matched
+    # against an array pattern.
+    #
+    #   Vector2d(3, 4).deconstruct # => [3,4]
+    #
+    #   case Vector2d(3, 4)
+    #   in [0, 0] then :origin
+    #   in [Integer => a, Integer => b] then a + b
+    #   end # => 7
+    #
+    # @return [Array<Integer, Float, Rational, BigDecimal>] the [x, y] pair
+    def deconstruct
+      to_a
+    end
+
+    # Returns the components as a hash, so a vector can be matched
+    # against a hash pattern. Both components are always returned,
+    # whichever keys the pattern asks for.
+    #
+    #   Vector2d(3, 4).deconstruct_keys([:x]) # => {x: 3, y: 4}
+    #
+    #   case Vector2d(0, 4)
+    #   in {x: 0} then :on_y_axis
+    #   in {y: 0} then :on_x_axis
+    #   end # => :on_y_axis
+    #
+    # @param _keys [Array<Symbol>, nil] ignored, both components are
+    #   always returned
+    # @return [Hash{Symbol => Integer, Float, Rational, BigDecimal}]
+    #   the x and y coordinates
+    def deconstruct_keys(_keys)
+      to_hash
+    end
+
+    # Renders vector as a pretty string.
+    #
+    #   Vector2d(2, 3).inspect # => "Vector2d(2,3)"
+    #
+    # @return [String]
+    def inspect
+      "#{self.class}(#{x},#{y})"
+    end
+
+    # Converts vector to array.
+    #
+    #   Vector2d(2, 3).to_a # => [2,3]
+    #
+    # @return [Array<Integer, Float, Rational, BigDecimal>] the [x, y] pair
+    def to_a
+      [x, y]
+    end
+
+    # Converts vector to hash.
+    #
+    #   Vector2d(2, 3).to_hash # => {x: 2, y: 3}
+    #
+    # @return [Hash{Symbol => Integer, Float, Rational, BigDecimal}]
+    #   the x and y coordinates
+    def to_hash
+      { x: x, y: y }
+    end
+
+    # Converts the coordinates to integers. The result is still a
+    # vector of this class, unlike #to_vector, which converts to the
+    # standard library Vector.
+    #
+    #   Vector2d(2.0, 3.0).to_i_vector # => Vector2d(2,3)
+    #
+    # @return [self]
+    def to_i_vector
+      build(x.to_i, y.to_i)
+    end
+
+    # Converts the coordinates to floats. As with #to_i_vector, the
+    # result is a vector of this class.
+    #
+    #   Vector2d(2, 3).to_f_vector # => Vector2d(2.0,3.0)
+    #
+    # @return [self]
+    def to_f_vector
+      build(x.to_f, y.to_f)
+    end
+
+    # Converts vector to string.
+    #
+    #   Vector2d.new(150, 100).to_s # => "150x100"
+    #
+    # @return [String]
+    def to_s
+      "#{x}x#{y}"
+    end
+
+    private
+
+    # Parses anything Vector2d.parse accepts into a vector. A vector is
+    # returned as it is.
+    def coerce_vector(other)
+      return other if other.is_a?(Vector2d)
+      return Vector2d.parse(other) if parseable?(other)
+
+      raise TypeError, "#{other.class} can't be coerced into #{self.class}"
+    end
+
+    # Can the object be parsed into a vector? Complex numbers are
+    # Numeric, but they are not coordinates.
+    def parseable?(other)
+      case other
+      when Vector2d, Array, String, Hash then true
+      when Numeric then other.real?
+      else MatrixInterop.vector?(other) || MatrixInterop.matrix?(other)
+      end
+    end
+  end
+end

data/lib/vector2d/coordinates.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # Coordinate validation, shared by the class methods that parse input
+  # and by the constructor.
+  module Coordinates
+    module_function
+
+    # Returns the value if it is a valid coordinate, raises
+    # ArgumentError otherwise. Coordinates are real numbers, so Complex
+    # is rejected along with everything outside Numeric.
+    #
+    # @param value [Object] the value to validate
+    # @return [Integer, Float, Rational, BigDecimal] the value
+    def coordinate(value)
+      return value if value.is_a?(Float) || value.is_a?(Integer)
+      raise ArgumentError, "not a valid coordinate: #{value.inspect}" unless value.is_a?(Numeric) && value.real?
+
+      value
+    end
+  end
+end

data/lib/vector2d/deprecation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Vector2d
+  # The warning issued by the methods deprecated for 3.0. Each of them
+  # names its replacement, and forwards to it.
+  module Deprecation
+    private
+
+    # Warns that a method is deprecated. Silent unless deprecation
+    # warnings are enabled, either with <tt>Warning[:deprecated] = true</tt>
+    # or by running Ruby with <tt>-w</tt>.
+    def warn_deprecated(message)
+      warn(message, uplevel: 2, category: :deprecated)
+    end
+  end
+end