vector2d 2.3.0 → 3.0.0

data/spec/lib/vector2d_immutability_spec.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "bigdecimal"
+require "matrix"
+
+describe Vector2d do
+  subject(:vector) { described_class.new(2, 3) }
+
+  coordinate_types = {
+    "integer coordinates" => [2, 3],
+    "float coordinates" => [2.0, 3.0],
+    "rational coordinates" => [Rational(1, 2), Rational(3, 4)],
+    "big decimal coordinates" => [BigDecimal("2.5"), BigDecimal("3.5")]
+  }
+
+  # Runs the block in a ractor with the argument as its only parameter,
+  # and returns the value it produces.
+  def in_ractor(argument, &)
+    experimental = Warning[:experimental]
+    Warning[:experimental] = false
+    ractor = Ractor.new(argument, &)
+    ractor.respond_to?(:value) ? ractor.value : ractor.take
+  ensure
+    Warning[:experimental] = experimental
+  end
+
+  describe "#frozen?" do
+    subject { vector.frozen? }
+
+    it { is_expected.to be(true) }
+
+    coordinate_types.each do |description, (x, y)|
+      context "with #{description}" do
+        let(:vector) { described_class.new(x, y) }
+
+        it { is_expected.to be(true) }
+      end
+    end
+
+    context "with a vector built by an operation" do
+      let(:vector) { described_class.new(2, 3) * 2 }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a vector built by .parse" do
+      let(:vector) { described_class.parse("2x3") }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a vector built by .from_angle" do
+      let(:vector) { described_class.from_angle(Math::PI / 4) }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a vector built by .from_degrees" do
+      let(:vector) { described_class.from_degrees(45) }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a vector built by the helper method" do
+      let(:vector) { Vector2d(2, 3) }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a clone" do
+      let(:vector) { described_class.new(2, 3).clone }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a clone that asks not to be frozen" do
+      let(:vector) { described_class.new(2, 3).clone(freeze: false) }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a dup" do
+      let(:vector) { described_class.new(2, 3).dup }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a subclass" do
+      let(:vector) { Class.new(described_class).new(2, 3) }
+
+      it { is_expected.to be(true) }
+    end
+  end
+
+  describe "assigning a coordinate" do
+    it "raises FrozenError" do
+      expect { vector.instance_variable_set(:@x, 5) }
+        .to raise_error(FrozenError)
+    end
+
+    it "raises FrozenError on a dup" do
+      expect { vector.dup.instance_variable_set(:@x, 5) }
+        .to raise_error(FrozenError)
+    end
+  end
+
+  describe "#dup" do
+    subject(:duped) { vector.dup }
+
+    it { is_expected.to eq(vector) }
+    it { is_expected.to eql(vector) }
+
+    it "is shareable" do
+      expect(Ractor.shareable?(duped)).to be(true)
+    end
+
+    context "with a subclass carrying extra state" do
+      subject(:duped) { labeled.new(2, 3, "point").dup }
+
+      let(:labeled) do
+        stub_const("DupLabeled", Class.new(described_class) do
+          attr_reader :label
+
+          def initialize(x, y, label = "unlabeled")
+            @label = label
+            super(x, y)
+          end
+        end)
+      end
+
+      it { is_expected.to be_frozen }
+      its(:label) { is_expected.to eq("point") }
+    end
+  end
+
+  describe "Ractor.shareable?" do
+    subject { Ractor.shareable?(vector) }
+
+    it { is_expected.to be(true) }
+
+    coordinate_types.each do |description, (x, y)|
+      context "with #{description}" do
+        let(:vector) { described_class.new(x, y) }
+
+        it { is_expected.to be(true) }
+      end
+    end
+
+    context "with a vector built by an operation" do
+      let(:vector) { described_class.new(2, 3) * 2 }
+
+      it { is_expected.to be(true) }
+    end
+
+    context "with a coordinate that is not shareable" do
+      let(:coordinate) { Class.new(Numeric).new }
+      let(:vector) { described_class.new(2, coordinate) }
+
+      it { is_expected.to be(false) }
+
+      it "is still frozen" do
+        expect(vector).to be_frozen
+      end
+    end
+  end
+
+  describe "sharing a vector with a ractor" do
+    it "arrives frozen and unchanged" do
+      result = in_ractor(vector) { |v| [v.frozen?, v.to_a] }
+
+      expect(result).to eq([true, [2, 3]])
+    end
+
+    it "calculates with a vector argument" do
+      result = in_ractor(vector) { |v| (v * Vector2d(2, 3)).to_a }
+
+      expect(result).to eq([4, 9])
+    end
+
+    it "calculates with a coerced argument" do
+      result = in_ractor(vector) { |v| ((v + 1) / "2x2").to_a }
+
+      expect(result).to eq([1, 2])
+    end
+
+    it "transforms into a new vector" do
+      result = in_ractor(vector) { |v| v.normalize.length }
+
+      expect(result).to be_within(0.0001).of(1.0)
+    end
+
+    it "returns a vector that is still frozen" do
+      result = in_ractor(vector, &:reverse)
+
+      expect(result).to be_frozen
+    end
+
+    it "returns a vector equal to the expected one" do
+      result = in_ractor(vector, &:reverse)
+
+      expect(result).to eq(described_class.new(-2, -3))
+    end
+
+    it "transforms through a matrix" do
+      result = in_ractor(vector) { |v| v.transform(Matrix[[0, -1], [1, 0]]).to_a }
+
+      expect(result).to eq([-3, 2])
+    end
+
+    it "converts to a stdlib vector" do
+      result = in_ractor(vector, &:to_vector)
+
+      expect(result).to eq(Vector[2, 3])
+    end
+  end
+
+  describe "a subclass adding instance variables" do
+    let(:before_super) do
+      stub_const("BeforeSuper", Class.new(described_class) do
+        attr_reader :label
+
+        def initialize(x, y, label = "unlabeled")
+          @label = label
+          super(x, y)
+        end
+      end)
+    end
+
+    let(:after_super) do
+      stub_const("AfterSuper", Class.new(described_class) do
+        def initialize(x, y, label = "unlabeled")
+          super(x, y)
+          @label = label
+        end
+      end)
+    end
+
+    context "when assigning before super" do
+      subject(:vector) { before_super.new(2, 3, "point") }
+
+      it { is_expected.to be_frozen }
+      its(:label) { is_expected.to eq("point") }
+
+      it "is shareable when the extra state is shareable" do
+        expect(Ractor.shareable?(vector)).to be(true)
+      end
+    end
+
+    context "when assigning after super" do
+      it "raises FrozenError" do
+        expect { after_super.new(2, 3) }.to raise_error(FrozenError)
+      end
+    end
+  end
+
+  describe ".parse with a vector argument" do
+    subject(:parsed) { described_class.parse(vector) }
+
+    it { is_expected.to be(vector) }
+    it { is_expected.to be_frozen }
+  end
+end

data/spec/lib/vector2d_spec.rb

@@ -5,92 +5,90 @@ require "spec_helper"
 describe Vector2d do
   subject(:vector) { described_class.new(2, 3) }
 
-  shared_examples "a parsed vector" do |x, y|
-    it "receives the x property" do
-      expect(subject.x).to eq(x)
-    end
-
-    it "receives the y property" do
-      expect(subject.y).to eq(y)
-    end
-  end
-
   describe "helper method" do
     it "creates a vector" do
       expect(Vector2d(2, 3)).to eq(described_class.new(2, 3))
     end
   end
 
-  describe ".parse" do
-    context "with fixnum argument" do
-      subject(:vector) { described_class.parse(2) }
-
-      it_behaves_like "a parsed vector", [2, 2]
+  describe ".new" do
+    it "creates a vector from two coordinates" do
+      expect(described_class.new(2, 3).to_a).to eq([2, 3])
     end
 
-    context "with two arguments, fixnum" do
-      subject(:vector) { described_class.parse(1, 2) }
-
-      it_behaves_like "a parsed vector", [1, 2]
+    context "with a complex x" do
+      it "raises an error" do
+        expect { described_class.new(Complex(1, 2), 3) }.to(
+          raise_error(ArgumentError, "not a valid coordinate: (1+2i)")
+        )
+      end
     end
 
-    context "with two arguments, float" do
-      subject(:vector) { described_class.parse(1.0, 2.0) }
-
-      it_behaves_like "a parsed vector", [1.0, 2.0]
+    context "with a complex y" do
+      it "raises an error" do
+        expect { described_class.new(2, Complex(1, 2)) }.to(
+          raise_error(ArgumentError, "not a valid coordinate: (1+2i)")
+        )
+      end
     end
 
-    context "with string argument, first omitted" do
-      subject(:vector) { described_class.parse("x200") }
-
-      it_behaves_like "a parsed vector", [0, 200]
+    context "with a non-numeric coordinate" do
+      it "raises an error" do
+        expect { described_class.new(2, nil) }.to(
+          raise_error(ArgumentError, "not a valid coordinate: nil")
+        )
+      end
     end
+  end
+
+  describe "#==" do
+    subject { vector == comp }
 
-    context "with string argument, second omitted" do
-      subject(:vector) { described_class.parse("200x") }
+    context "with both arguments equal" do
+      let(:comp) { described_class.new(2, 3) }
 
-      it_behaves_like "a parsed vector", [200, 0]
+      it { is_expected.to be(true) }
     end
 
-    context "with string argument, fixnum" do
-      subject(:vector) { described_class.parse("1x2") }
+    context "with x differing" do
+      let(:comp) { described_class.new(3, 3) }
 
-      it_behaves_like "a parsed vector", [1, 2]
+      it { is_expected.to be(false) }
     end
 
-    context "with string argument, float" do
-      subject(:vector) { described_class.parse("1.0x2.0") }
+    context "with y differing" do
+      let(:comp) { described_class.new(2, 4) }
 
-      it_behaves_like "a parsed vector", [1.0, 2.0]
+      it { is_expected.to be(false) }
     end
 
-    context "with array argument" do
-      subject(:vector) { described_class.parse([1, 2]) }
+    context "with a number argument" do
+      let(:comp) { 5 }
 
-      it_behaves_like "a parsed vector", [1, 2]
+      it { is_expected.to be(false) }
     end
 
-    context "with hash argument, symbol keys" do
-      subject(:vector) { described_class.parse(x: 1, y: 2) }
+    context "with an array argument" do
+      let(:comp) { [2, 3] }
 
-      it_behaves_like "a parsed vector", [1, 2]
+      it { is_expected.to be(false) }
     end
 
-    context "with hash argument, string keys" do
-      subject(:vector) { described_class.parse("x" => 1, "y" => 2) }
+    context "with a string argument" do
+      let(:comp) { "2x3" }
 
-      it_behaves_like "a parsed vector", [1, 2]
+      it { is_expected.to be(false) }
     end
 
-    context "with vector argument" do
-      subject(:vector) { described_class.parse(described_class.new(1, 2)) }
+    context "with a nil argument" do
+      let(:comp) { nil }
 
-      it_behaves_like "a parsed vector", [1, 2]
+      it { is_expected.to be(false) }
     end
   end
 
-  describe "#==" do
-    subject { vector == comp }
+  describe "#eql?" do
+    subject { vector.eql?(comp) }
 
     context "with both arguments equal" do
       let(:comp) { described_class.new(2, 3) }
@@ -109,5 +107,47 @@ describe Vector2d do
 
       it { is_expected.to be(false) }
     end
+
+    context "with coordinates of a different type" do
+      let(:comp) { described_class.new(2.0, 3.0) }
+
+      it { is_expected.to be(false) }
+    end
+
+    context "with a subclass" do
+      let(:comp) { Class.new(described_class).new(2, 3) }
+
+      it { is_expected.to be(false) }
+    end
+
+    context "with a non-vector" do
+      let(:comp) { [2, 3] }
+
+      it { is_expected.to be(false) }
+    end
+  end
+
+  describe "#hash" do
+    subject { vector.hash }
+
+    context "with an equal vector" do
+      it { is_expected.to eq(described_class.new(2, 3).hash) }
+    end
+
+    context "with a differing vector" do
+      it { is_expected.not_to eq(described_class.new(3, 2).hash) }
+    end
+
+    context "with coordinates of a different type" do
+      it { is_expected.not_to eq(described_class.new(2.0, 3.0).hash) }
+    end
+
+    it "makes vectors usable as hash keys" do
+      expect({ vector => :value }[described_class.new(2, 3)]).to be(:value)
+    end
+
+    it "deduplicates equal vectors in arrays" do
+      expect([vector] | [described_class.new(2, 3)]).to eq([vector])
+    end
   end
 end

data/spec/lib/vector2d_subclassing_spec.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "matrix"
+
+describe Vector2d do
+  subject(:vector) { subclass.new(2.5, 3.5) }
+
+  let(:subclass) { stub_const("SubVector", Class.new(described_class)) }
+
+  it_behaves_like "a class preserving method", :*, 2
+  it_behaves_like "a class preserving method", :/, 2
+  it_behaves_like "a class preserving method", :+, 2
+  it_behaves_like "a class preserving method", :-, 2
+  it_behaves_like "a class preserving method", :-@
+  it_behaves_like "a class preserving method", :+@
+  it_behaves_like "a class preserving method", :direction_to, 2
+  it_behaves_like "a class preserving method", :move_toward, 2, 0.5
+  it_behaves_like "a class preserving method", :move_toward, 2, 10
+  it_behaves_like "a class preserving method", :project, 2
+  it_behaves_like "a class preserving method", :reflect, 2
+  it_behaves_like "a class preserving method", :reject, 2
+  it_behaves_like "a class preserving method", :refract, 2, 0.5
+
+  it_behaves_like "a class preserving method", :transform,
+                  Matrix[[0, -1], [1, 0]]
+
+  it_behaves_like "a class preserving method", :to_i_vector
+  it_behaves_like "a class preserving method", :to_f_vector
+
+  it_behaves_like "a class preserving method", :fit, 10
+  it_behaves_like "a class preserving method", :cover, 10
+
+  it_behaves_like "a class preserving method", :abs
+  it_behaves_like "a class preserving method", :ceil
+  it_behaves_like "a class preserving method", :clamp, 0, 10
+  it_behaves_like "a class preserving method", :clamp, 0..10
+  it_behaves_like "a class preserving method", :clamp_length, 1.0, 10.0
+  it_behaves_like "a class preserving method", :clamp_length, 1.0..10.0
+  it_behaves_like "a class preserving method", :floor
+  it_behaves_like "a class preserving method", :lerp, 2, 0.5
+  it_behaves_like "a class preserving method", :slerp, 2, 0.5
+  it_behaves_like "a class preserving method", :limit_length, 1.0
+  it_behaves_like "a class preserving method", :max, 2
+  it_behaves_like "a class preserving method", :midpoint, 2
+  it_behaves_like "a class preserving method", :min, 2
+  it_behaves_like "a class preserving method", :normalize
+  it_behaves_like "a class preserving method", :perpendicular
+  it_behaves_like "a class preserving method", :perpendicular_cw
+  it_behaves_like "a class preserving method", :resize, 2.0
+  it_behaves_like "a class preserving method", :reverse
+  it_behaves_like "a class preserving method", :rotate, Math::PI
+  it_behaves_like "a class preserving method", :rotate_degrees, 180
+  it_behaves_like "a class preserving method", :rotate_around, 0, Math::PI
+  it_behaves_like "a class preserving method", :round
+  it_behaves_like "a class preserving method", :sign
+  it_behaves_like "a class preserving method", :snap, 1
+  it_behaves_like "a class preserving method", :with_x, 5
+  it_behaves_like "a class preserving method", :with_y, 5
+
+  describe ".parse" do
+    it "rebuilds a vector of another class" do
+      expect(subclass.parse(described_class.new(2, 3)))
+        .to be_an_instance_of(subclass)
+    end
+
+    it "returns a vector of the receiver's class as it is" do
+      expect(subclass.parse(vector)).to be(vector)
+    end
+
+    it "returns a subclass as it is when parsed by the parent" do
+      expect(described_class.parse(vector)).to be(vector)
+    end
+  end
+
+  describe "#coerce" do
+    it "builds the other operand as the receiver's class" do
+      expect(vector.coerce(2).first).to be_an_instance_of(subclass)
+    end
+
+    it "keeps the class when the vector is the right hand operand" do
+      expect(2 * vector).to be_an_instance_of(subclass)
+    end
+  end
+
+  describe ".from_angle" do
+    it "returns an instance of the receiver's class" do
+      expect(subclass.from_angle(Math::PI / 2))
+        .to be_an_instance_of(subclass)
+    end
+  end
+
+  describe ".from_degrees" do
+    it "returns an instance of the receiver's class" do
+      expect(subclass.from_degrees(90))
+        .to be_an_instance_of(subclass)
+    end
+  end
+
+  describe ".random" do
+    it "returns an instance of the receiver's class" do
+      expect(subclass.random).to be_an_instance_of(subclass)
+    end
+  end
+
+  describe "the direction constants" do
+    %i[zero one up down left right].each do |name|
+      describe ".#{name}" do
+        it "returns an instance of the receiver's class" do
+          expect(subclass.public_send(name)).to be_an_instance_of(subclass)
+        end
+      end
+    end
+  end
+
+  describe "#contain" do
+    it "returns an instance of the argument's class" do
+      expect(described_class.new(2, 3).contain(subclass.new(4, 5)))
+        .to be_an_instance_of(subclass)
+    end
+  end
+
+  context "when the subclass takes extra constructor arguments" do
+    subject(:vector) { labeled.new(2.5, 3.5, "point") }
+
+    let(:labeled) do
+      stub_const("LabeledVector", Class.new(described_class) do
+        attr_reader :label
+
+        def self.build(x, y)
+          new(x, y, "unlabeled")
+        end
+
+        def initialize(x, y, label)
+          @label = label
+          super(x, y)
+        end
+
+        def build(x, y)
+          self.class.new(x, y, label)
+        end
+      end)
+    end
+
+    it { is_expected.to be_frozen }
+
+    describe "#abs" do
+      subject { vector.abs }
+
+      it { is_expected.to be_an_instance_of(labeled) }
+      it { is_expected.to be_frozen }
+      its(:label) { is_expected.to eq("point") }
+    end
+
+    describe "#*" do
+      subject { vector * 2 }
+
+      its(:label) { is_expected.to eq("point") }
+    end
+
+    describe "#transform" do
+      subject { vector.transform(Matrix[[0, -1], [1, 0]]) }
+
+      its(:label) { is_expected.to eq("point") }
+    end
+
+    describe "#coerce" do
+      subject { 2 * vector }
+
+      its(:label) { is_expected.to eq("point") }
+    end
+
+    describe ".parse" do
+      subject { labeled.parse("2x3") }
+
+      it { is_expected.to be_an_instance_of(labeled) }
+      its(:label) { is_expected.to eq("unlabeled") }
+    end
+
+    describe ".parse with a Vector" do
+      subject { labeled.parse(Vector[2, 3]) }
+
+      its(:label) { is_expected.to eq("unlabeled") }
+    end
+
+    describe ".from_angle" do
+      subject { labeled.from_angle(0) }
+
+      its(:label) { is_expected.to eq("unlabeled") }
+    end
+
+    describe ".random" do
+      subject { labeled.random }
+
+      its(:label) { is_expected.to eq("unlabeled") }
+    end
+
+    describe ".up" do
+      subject { labeled.up }
+
+      its(:label) { is_expected.to eq("unlabeled") }
+    end
+
+    describe "#refract" do
+      subject { vector.refract(Vector2d(0, 1), 0.5) }
+
+      its(:label) { is_expected.to eq("point") }
+    end
+  end
+end

data/spec/lib/vector2d_tags_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe Vector2d do
+  DocTags.methods.each do |method|
+    describe method.path do
+      it "documents every parameter" do
+        expect(DocTags.undocumented_parameters(method)).to be_empty
+      end
+
+      it "documents what it returns" do
+        expect(method.tags(:return)).not_to be_empty
+      end
+
+      it "avoids type names that are too vague", :aggregate_failures do
+        DocTags.tags(method).each do |tag|
+          expect(tag.types & DocTags::FORBIDDEN).to be_empty, tag.to_s
+        end
+      end
+
+      it "names every coordinate type", :aggregate_failures do
+        DocTags.coordinate_tags(method).each do |tag|
+          expect(tag.missing(DocTags::COORDINATE)).to be_empty, tag.to_s
+        end
+      end
+
+      it "names the parse union in full", :aggregate_failures do
+        DocTags.parse_union_tags(method).each do |tag|
+          expect(tag.missing(DocTags::COERCIBLE)).to be_empty, tag.to_s
+        end
+      end
+    end
+  end
+
+  it "tags every method that warns as deprecated" do
+    expect(DocTags.untagged_deprecations).to be_empty
+  end
+
+  it "closes every doc comment with its tag block" do
+    expect(DocTags.prose_after_tags).to be_empty
+  end
+end