blib/lib/Math/Vectors2.pm

filter: Statementstmt 96.0% 147 / 153 Branchbran 72.2% 13 / 18 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 94.5% 52 / 55 Podpod 84.8% 28 / 33 totaltotal 92.6% 240 / 259 CC 12 SCAR 4.5
CC
12
Cov
94%
test
5.1
n
2.0
zero
2.0
CRAP 1.6
« Build ↑ Summary
1 #!/usr/bin/perl -I/home/phil/perl/cpan/DataTableText/lib/
2 #-------------------------------------------------------------------------------
3 # Vectors in two dimensions
4 # Philip R Brenan at gmail dot com, Appa Apps Ltd Inc., 2017-2020
5 #-------------------------------------------------------------------------------
6 # podDocumentation
7 package Math::Vectors2;
8 1 require v5.16;
9 1 our $VERSION = 20230930;
10 1 ▶use warnings FATAL => qw(all);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use Data::Table::Text qw(genHash);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use Math::Trig;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 1 my $nearness = 1e-6; # Definition of near
17  
18 sub near($$) # Check two scalars are near each other.
19 393 ▶ {my ($o, $p) = @_;
Subroutine near: called CC=1 SCAR=0.0
Pod undocumented
20 393 abs($p-$o) < $nearness
21 }
22  
23 sub near2($$) # Check two vectors are near each other.
24 19 ▶ {my ($o, $p) = @_;
Subroutine near2: called CC=1 SCAR=0.0
Pod undocumented
25 19 $o->d($p) < $nearness
26 }
27  
28 #D1 Methods # Vector methods.
29  
30 sub new($$) #S Create new vector from components.
31 545 ▶ {my ($x, $y) = @_; # X component, Y component
Subroutine new: called CC=1 SCAR=0.0
Pod documented
32 545 genHash(__PACKAGE__, # Attributes of a vector
33 x => $x, # X coordinate
34 y => $y, # Y coordinate
35 );
36 }
37  
38 sub zeroAndUnits() #S Create the useful vectors: zero=(0,0), x=(1,0), y=(0,1).
39 12 ▶ {map {&new(@$_)} ([0, 0], [1, 0], [0, 1])
Subroutine zeroAndUnits: called CC=1 SCAR=0.0
Pod documented
40 }
41  
42 sub eq($$) # Whether two vectors are equal to within the accuracy of floating point arithmetic.
43 13 ▶ {my ($o, $p) = @_; # First vector, second vector
Subroutine eq: called CC=1 SCAR=0.0
Pod documented
44 13 near2($o, $p)
45 }
46  
47 sub zero($) # Whether a vector is equal to zero within the accuracy of floating point arithmetic.
48 3 ▶ {my ($o) = @_; # Vector
Subroutine zero: called CC=2 SCAR=6.9
Pod documented
49 3 ▶ near($o->x, 0) && near($o->y, 0)
Branch: 1 branch
BranchTrueFalseTotal
&near(scalar $o->x, 0) and &near(scalar $o->y, 0) 2 1 3
50 }
51  
52 sub print($@) # Print one or more vectors.
53 13 ▶ {my ($p, @p) = @_; # Vector to print, more vectors to print
Subroutine print: called CC=1 SCAR=0.0
Pod documented
54 13 join ', ', map {'('.$_->x.','.$_->y.')'} @_
55 }
56  
57 sub clone($) # Clone a vector.
58 83 ▶ {my ($o) = @_; # Vector to clone
Subroutine clone: called CC=1 SCAR=0.0
Pod documented
59 83 new($o->x, $o->y)
60 }
61  
62 sub Plus($@) # Add zero or more other vectors to the first vector and return the result.
63 33 ▶ {my ($o, @p) = @_; # First vector, other vectors
Subroutine Plus: called CC=2 SCAR=6.9
Pod documented
64 33 for(@p)
65 33 {$o->x += $_->x;
66 33 $o->y += $_->y;
67 }
68 $o
69 33 }
70  
71 sub plus($@) # Add zero or more other vectors to a copy of the first vector and return the result.
72 31 ▶ {my ($o, @p) = @_; # First vector, other vectors
Subroutine plus: called CC=1 SCAR=0.0
Pod documented
73 31 $o->clone->Plus(@p)
74 }
75  
76 sub Minus($@) # Subtract zero or more vectors from the first vector and return the result.
77 13 ▶ {my ($o, @p) = @_; # First vector, other vectors
Subroutine Minus: called CC=2 SCAR=6.9
Pod documented
78 13 for(@p)
79 13 {$o->x -= $_->x;
80 13 $o->y -= $_->y;
81 }
82 $o
83 13 }
84  
85 sub minus($@) # Subtract zero or more vectors from a copy of the first vector and return the result.
86 11 ▶ {my ($o, @p) = @_; # First vector, other vectors
Subroutine minus: called CC=1 SCAR=0.0
Pod documented
87 11 $o->clone->Minus(@p)
88 }
89  
90 sub Multiply($$) # Multiply a vector by a scalar and return the result.
91 37 ▶ {my ($o, $m) = @_; # Vector, scalar to multiply by
Subroutine Multiply: called CC=1 SCAR=0.0
Pod documented
92 37 $o->x *= $m; $o->y *= $m;
93 37 $o
94 }
95  
96 sub multiply($$) # Multiply a copy of a vector by a scalar and return the result.
97 35 ▶ {my ($o, $m) = @_; # Vector, scalar to multiply by
Subroutine multiply: called CC=1 SCAR=0.0
Pod documented
98 35 $o->clone->Multiply($m)
99 }
100  
101 sub Divide($$) # Divide a vector by a scalar and return the result.
102 7 ▶ {my ($o, $d) = @_; # Vector, scalar to multiply by
Subroutine Divide: called CC=1 SCAR=0.0
Pod documented
103 7 $o->x /= $d; $o->y /= $d;
104 7 $o
105 }
106  
107 sub divide($$) # Divide a copy of a vector by a scalar and return the result.
108 5 ▶ {my ($o, $d) = @_; # Vector, scalar to divide by
Subroutine divide: called CC=1 SCAR=0.0
Pod documented
109 5 $o->clone->Divide($d)
110 }
111  
112 sub l($) # Length of a vector.
113 1563 ▶ {my ($o) = @_; # Vector
Subroutine l: called CC=1 SCAR=0.0
Pod documented
114 1563 sqrt($o->x**2 + $o->y**2)
115 }
116  
117 sub l2($) # Length squared of a vector.
118 2 ▶ {my ($o) = @_; # Vector
Subroutine l2: called CC=1 SCAR=0.0
Pod documented
119 2 $o->x**2 + $o->y**2
120 }
121  
122 sub d($$) # Distance between the points identified by two vectors when placed on the same point.
123 20 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine d: called CC=1 SCAR=0.0
Pod documented
124 20 sqrt(($o->x-$p->x)**2 + ($o->y-$p->y)**2)
125 }
126  
127 sub d2($$) # Distance squared between the points identified by two vectors when placed on the same point.
128 1 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine d2: called CC=1 SCAR=0.0
Pod documented
129 1 ($o->x-$p->x)**2 + ($o->y-$p->y)**2
130 }
131  
132 sub n($) # Return a normalized a copy of a vector.
133 1 ▶ {my ($o) = @_; # Vector
Subroutine n: called CC=2 SCAR=7.0
Pod documented
134 1 my $l = $o->l;
135 1 ▶ $l == 0 and confess;
Branch: 1 branch
BranchTrueFalseTotal
$l == 0 and confess() 0 1 1
136 1 new($o->x / $l, $o->y / $l)
137 }
138  
139 sub dot($$) # Dot product of two vectors.
140 393 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine dot: called CC=1 SCAR=0.0
Pod documented
141 393 $o->x * $p->x + $o->y * $p->y
142 }
143  
144 sub area($$) # Signed area of the parallelogram defined by the two vectors. The area is negative if the second vector appears to the right of the first if they are both placed at the origin and the observer stands against the z-axis in a left handed coordinate system.
145 393 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine area: called CC=1 SCAR=0.0
Pod documented
146 393 $o->x * $p->y - $o->y * $p->x
147 }
148  
149 sub cosine($$) # Cos(angle between two vectors).
150 389 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine cosine: called CC=1 SCAR=0.0
Pod documented
151 389 $o->dot($p) / $o->l / $p->l
152 }
153  
154 sub sine($$) # Sin(angle between two vectors).
155 391 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine sine: called CC=1 SCAR=0.0
Pod documented
156 391 $o->area($p) / $o->l / $p->l
157 }
158  
159 sub angle($$) # Angle in radians anticlockwise that the first vector must be rotated to point along the second vector normalized to the range: -pi to +pi.
160 384 ▶ {my ($o, $p) = @_; # Vector 1, vector 2
Subroutine angle: called CC=2 SCAR=6.9
Pod documented
161 384 my $c = $o->cosine($p);
162 384 my $s = $o->sine($p);
163 384 my $a = Math::Trig::acos($c);
164 384 ▶ $s > 0 ? $a : -$a
Branch: 1 branch
BranchTrueFalseTotal
$s > 0 ? : 190 194 384
165 }
166  
167 sub smallestAngleToNormalPlane($$) # The smallest angle between the second vector and a plane normal to the first vector.
168 9 ▶ {my ($a, $b) = @_; # Vector 1, vector 2
Subroutine smallestAngleToNormalPlane: called CC=2 SCAR=6.9
Pod undocumented
169 9 my $r = abs $a->angle($b);
170 9 my $p = Math::Trig::pi / 2;
171 9 ▶ $r < $p ? $p - $r : $r - $p
Branch: 1 branch
BranchTrueFalseTotal
$r < $p ? : 2 7 9
172 }
173  
174 sub r90($) # Rotate a vector by 90 degrees anticlockwise.
175 12 ▶ {my ($o) = @_; # Vector to rotate
Subroutine r90: called CC=1 SCAR=0.0
Pod documented
176 12 new(-$o->y, $o->x)
177 }
178  
179 sub r180($) # Rotate a vector by 180 degrees.
180 0 ▶ {my ($o) = @_; # Vector to rotate
Subroutine r180: not called CC=1 SCAR=6.9
Pod documented
181 0 new(-$o->x, -$o->y)
182 }
183  
184 sub r270($) # Rotate a vector by 270 degrees anticlockwise.
185 0 ▶ {my ($o) = @_; # Vector to rotate
Subroutine r270: not called CC=1 SCAR=6.9
Pod documented
186 0 new($o->y, -$o->x)
187 }
188  
189 sub rotate($$$$) # Rotate a vector about another vector through an angle specified by its values as sin, and cos.
190 6 ▶ {my ($p, $o, $sin, $cos) = @_; # Vector to rotate, center of rotation, sin of the angle of rotation, cosine of the angle of rotation
Subroutine rotate: called CC=1 SCAR=0.0
Pod undocumented
191 6 my $q = $p - $o;
192 6 $o + new($cos*$q->x-$sin*$q->y, $sin*$q->x+$cos*$q->y)
193 }
194  
195 sub swap($) # Swap the components of a vector.
196 1 ▶ {my ($o) = @_; # Vector
Subroutine swap: called CC=1 SCAR=0.0
Pod documented
197 1 new($o->y, $o->x)
198 }
199  
200 use overload
201 13 ▶ '==' => sub {my ($o, $p) = @_; $o->eq ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
202 30 ▶ '+' => sub {my ($o, $p) = @_; $o->plus ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
203 1 ▶ '+=' => sub {my ($o, $p) = @_; $o->Plus ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
204 24 ▶ '-' => sub {my ($o, $p) = @_; ref($p) ? $o->minus($p) : $o->multiply(-1)},
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
ref $p ? : 10 14 24
205 1 ▶ '-=' => sub {my ($o, $p) = @_; $o->Minus ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
206 20 ▶ '*' => sub {my ($o, $p) = @_; $o->multiply($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
207 1 ▶ '*=' => sub {my ($o, $p) = @_; $o->Multiply($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
208 4 ▶ '/' => sub {my ($o, $p) = @_; $o->divide ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
209 1 ▶ '/=' => sub {my ($o, $p) = @_; $o->Divide ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
210 4 ▶ '.' => sub {my ($o, $p) = @_; $o->dot ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
211 0 ▶ 'x' => sub {my ($o, $p) = @_; $o->area ($p)},
Subroutine __ANON__: not called CC=1 SCAR=6.9
212 367 ▶ '<' => sub {my ($o, $p) = @_; $o->angle ($p)},
Subroutine __ANON__: called CC=1 SCAR=0.0
213 12 ▶ '""' => sub {my ($o) = @_; $o->print },
Subroutine __ANON__: called CC=1 SCAR=0.0
214 1 ▶ "fallback" => 1;
Subroutine BEGIN: called CC=1 SCAR=0.0
215  
216 #D0
217 #-------------------------------------------------------------------------------
218 # Export - eeee
219 #-------------------------------------------------------------------------------
220  
221 1 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
222  
223 1 ▶use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
Subroutine BEGIN: called CC=1 SCAR=0.0
224  
225 # containingFolder
226  
227 1 @ISA = qw(Exporter);
228 1 @EXPORT = qw();
229 1 @EXPORT_OK = qw();
230 1 %EXPORT_TAGS = (all=>[@EXPORT, @EXPORT_OK]);
231  
232 # podDocumentation
233  
234 =encoding utf-8
235  
236 =head1 Name
237  
238 Math::Vectors2 - Vectors in two dimensions
239  
240 =head1 Synopsis
241  
242 use Math::Vectors2;
243  
244 my ($zero, $x, $y) = Math::Vectors2::zeroAndUnits;
245  
246 ok near deg2rad(-60), $x + $y * sqrt(3) < $x;
247 ok near deg2rad(+30), ($x + $y * sqrt(3))->angle($y);
248  
249 =head1 Description
250  
251 Vectors in two dimensions
252  
253  
254 Version 20200402.
255  
256  
257 The following sections describe the methods in each functional area of this
258 module. For an alphabetic listing of all methods by name see L<Index|/Index>.
259  
260  
261  
262 =head1 Methods
263  
264 Vector methods.
265  
266 =head2 new($x, $y)
267  
268 Create new vector from components.
269  
270 Parameter Description
271 1 $x X component
272 2 $y Y component
273  
274 B<Example:>
275  
276  
277 my ($zero, $x, $y) = zeroAndUnits;
278 ok near $y->angle(𝗻𝗲𝘄(+1, -1)), deg2rad(-135);
279 ok near $y->angle(𝗻𝗲𝘄(+1, 0)), deg2rad(-90);
280 ok near $y->angle(𝗻𝗲𝘄(+1, +1)), deg2rad(-45);
281 ok near $y->angle(𝗻𝗲𝘄( 0, +1)), deg2rad(+0);
282 ok near $y->angle(𝗻𝗲𝘄(-1, +1)), deg2rad(+45);
283 ok near $y->angle(𝗻𝗲𝘄(-1, 0)), deg2rad(+90);
284 ok near $y->angle(𝗻𝗲𝘄(-1, -1)), deg2rad(+135);
285  
286 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄( 0, -1), deg2rad(-135);
287 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄( 1, -1), deg2rad(-90);
288 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄( 1, 0), deg2rad(-45);
289 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄( 1, 1), deg2rad(0);
290 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄( 0, 1), deg2rad(+45);
291 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄(-1, 1), deg2rad(+90);
292 ok near 𝗻𝗲𝘄(1,1) < 𝗻𝗲𝘄(-1, 0), deg2rad(+135);
293  
294 ok near $x + $y * sqrt(3) < $x, deg2rad(-60);
295 ok near $x + $y * sqrt(3) < $y, deg2rad(+30);
296  
297 for my $i(-179..179)
298 {ok near $x < 𝗻𝗲𝘄(cos(deg2rad($i)), sin(deg2rad($i))), deg2rad($i);
299 }
300  
301  
302 This is a static method and so should either be imported or invoked as:
303  
304 Math::Vectors2::new
305  
306  
307 =head2 zeroAndUnits()
308  
309 Create the useful vectors: o=(0,0), x=(1,0), y=(0,1)
310  
311  
312 B<Example:>
313  
314  
315 my ($z, $x, $y) = 𝘇𝗲𝗿𝗼𝗔𝗻𝗱𝗨𝗻𝗶𝘁𝘀;
316 ok $x + $y + $z == $x->plus($y);
317 ok $x - $y == $x->minus($y);
318 ok $x * 3 == $x->multiply(3);
319 ok $y / 2 == $y->divide(2);
320 ok $x + $y eq '(1,1)';
321 ok $x - $y eq '(1,-1)';
322 ok $x * 3 eq '(3,0)';
323 ok $y / 2 eq '(0,0.5)';
324 ok (($x * 2 + $y * 3)-> print eq '(2,3)');
325  
326  
327 This is a static method and so should either be imported or invoked as:
328  
329 Math::Vectors2::zeroAndUnits
330  
331  
332 =head2 eq($o, $p)
333  
334 Whether two vectors are equal to within the accuracy of floating point arithmetic
335  
336 Parameter Description
337 1 $o First vector
338 2 $p Second vector
339  
340 B<Example:>
341  
342  
343 my ($z, $x, $y) = zeroAndUnits;
344 ok $x + $y + $z == $x->plus($y);
345 ok $x - $y == $x->minus($y);
346 ok $x * 3 == $x->multiply(3);
347 ok $y / 2 == $y->divide(2);
348 ok $x + $y 𝗲𝗾 '(1,1)';
349 ok $x - $y 𝗲𝗾 '(1,-1)';
350 ok $x * 3 𝗲𝗾 '(3,0)';
351 ok $y / 2 𝗲𝗾 '(0,0.5)';
352 ok (($x * 2 + $y * 3)-> print 𝗲𝗾 '(2,3)');
353  
354  
355 =head2 zero($o)
356  
357 Whether a vector is equal to zero within the accuracy of floating point arithmetic
358  
359 Parameter Description
360 1 $o Vector
361  
362 B<Example:>
363  
364  
365 my ($𝘇𝗲𝗿𝗼, $x, $y) = zeroAndUnits;
366 ok $𝘇𝗲𝗿𝗼->𝘇𝗲𝗿𝗼;
367 ok !$x->𝘇𝗲𝗿𝗼;
368 ok !$y->𝘇𝗲𝗿𝗼;
369  
370  
371 =head2 print($p, @p)
372  
373 Print one or more vectors.
374  
375 Parameter Description
376 1 $p Vector to print
377 2 @p More vectors to print
378  
379 B<Example:>
380  
381  
382 my ($z, $x, $y) = zeroAndUnits;
383 ok $x + $y + $z == $x->plus($y);
384 ok $x - $y == $x->minus($y);
385 ok $x * 3 == $x->multiply(3);
386 ok $y / 2 == $y->divide(2);
387 ok $x + $y eq '(1,1)';
388 ok $x - $y eq '(1,-1)';
389 ok $x * 3 eq '(3,0)';
390 ok $y / 2 eq '(0,0.5)';
391 ok (($x * 2 + $y * 3)-> 𝗽𝗿𝗶𝗻𝘁 eq '(2,3)');
392  
393  
394 =head2 clone($o)
395  
396 Clone a vector.
397  
398 Parameter Description
399 1 $o Vector to clone
400  
401 B<Example:>
402  
403  
404 my ($z, $x, $y) = zeroAndUnits;
405 ok $x->swap == $y;
406 ok $x->𝗰𝗹𝗼𝗻𝗲 == $x;
407  
408  
409 =head2 Plus($o, @p)
410  
411 Add zero or more other vectors to the first vector and return the result.
412  
413 Parameter Description
414 1 $o First vector
415 2 @p Other vectors
416  
417 B<Example:>
418  
419  
420 my ($zero, $x, $y) = zeroAndUnits;
421 $x->𝗣𝗹𝘂𝘀(new(1,1));
422 ok $x eq '(2,1)';
423 $y += new(1,1);
424 ok $y eq '(1,2)';
425  
426  
427  
428 =head2 plus($o, @p)
429  
430 Add zero or more other vectors to a copy of the first vector and return the result.
431  
432 Parameter Description
433 1 $o First vector
434 2 @p Other vectors
435  
436 B<Example:>
437  
438  
439 my ($z, $x, $y) = zeroAndUnits;
440 ok $x + $y + $z == $x->𝗽𝗹𝘂𝘀($y);
441 ok $x - $y == $x->minus($y);
442 ok $x * 3 == $x->multiply(3);
443 ok $y / 2 == $y->divide(2);
444 ok $x + $y eq '(1,1)';
445 ok $x - $y eq '(1,-1)';
446 ok $x * 3 eq '(3,0)';
447 ok $y / 2 eq '(0,0.5)';
448 ok (($x * 2 + $y * 3)-> print eq '(2,3)');
449  
450  
451 =head2 Minus($o, @p)
452  
453 Subtract zero or more vectors from the first vector and return the result.
454  
455 Parameter Description
456 1 $o First vector
457 2 @p Other vectors
458  
459 B<Example:>
460  
461  
462 my ($zero, $x, $y) = zeroAndUnits;
463 $x->𝗠𝗶𝗻𝘂𝘀(new(0, 1));
464 ok $x eq '(1,-1)';
465 $y -= new(1,1);
466 ok $y eq '(-1,0)';
467  
468  
469 =head2 minus($o, @p)
470  
471 Subtract zero or more vectors from a copy of the first vector and return the result.
472  
473 Parameter Description
474 1 $o First vector
475 2 @p Other vectors
476  
477 B<Example:>
478  
479  
480 my ($z, $x, $y) = zeroAndUnits;
481 ok $x + $y + $z == $x->plus($y);
482 ok $x - $y == $x->𝗺𝗶𝗻𝘂𝘀($y);
483 ok $x * 3 == $x->multiply(3);
484 ok $y / 2 == $y->divide(2);
485 ok $x + $y eq '(1,1)';
486 ok $x - $y eq '(1,-1)';
487 ok $x * 3 eq '(3,0)';
488 ok $y / 2 eq '(0,0.5)';
489 ok (($x * 2 + $y * 3)-> print eq '(2,3)');
490  
491  
492 =head2 Multiply($o, $m)
493  
494 Multiply a vector by a scalar and return the result.
495  
496 Parameter Description
497 1 $o Vector
498 2 $m Scalar to multiply by
499  
500 B<Example:>
501  
502  
503 my ($zero, $x, $y) = zeroAndUnits;
504 $x->𝗠𝘂𝗹𝘁𝗶𝗽𝗹𝘆(2);
505 ok $x eq '(2,0)';
506 $y *= 2;
507 ok $y eq '(0,2)';
508  
509  
510  
511 =head2 multiply($o, $m)
512  
513 Multiply a copy of a vector by a scalar and return the result.
514  
515 Parameter Description
516 1 $o Vector
517 2 $m Scalar to multiply by
518  
519 B<Example:>
520  
521  
522 my ($z, $x, $y) = zeroAndUnits;
523 ok $x + $y + $z == $x->plus($y);
524 ok $x - $y == $x->minus($y);
525 ok $x * 3 == $x->𝗺𝘂𝗹𝘁𝗶𝗽𝗹𝘆(3);
526 ok $y / 2 == $y->divide(2);
527 ok $x + $y eq '(1,1)';
528 ok $x - $y eq '(1,-1)';
529 ok $x * 3 eq '(3,0)';
530 ok $y / 2 eq '(0,0.5)';
531 ok (($x * 2 + $y * 3)-> print eq '(2,3)');
532  
533  
534 =head2 Divide($o, $d)
535  
536 Divide a vector by a scalar and return the result.
537  
538 Parameter Description
539 1 $o Vector
540 2 $d Scalar to multiply by
541  
542 B<Example:>
543  
544  
545 my ($zero, $x, $y) = zeroAndUnits;
546 $x->𝗗𝗶𝘃𝗶𝗱𝗲(1/2);
547 ok $x eq '(2,0)';
548 $y /= 1/2;
549 ok $y eq '(0,2)';
550  
551  
552  
553 =head2 divide($o, $d)
554  
555 Divide a copy of a vector by a scalar and return the result.
556  
557 Parameter Description
558 1 $o Vector
559 2 $d Scalar to divide by
560  
561 B<Example:>
562  
563  
564 my ($z, $x, $y) = zeroAndUnits;
565 ok $x + $y + $z == $x->plus($y);
566 ok $x - $y == $x->minus($y);
567 ok $x * 3 == $x->multiply(3);
568 ok $y / 2 == $y->𝗱𝗶𝘃𝗶𝗱𝗲(2);
569 ok $x + $y eq '(1,1)';
570 ok $x - $y eq '(1,-1)';
571 ok $x * 3 eq '(3,0)';
572 ok $y / 2 eq '(0,0.5)';
573 ok (($x * 2 + $y * 3)-> print eq '(2,3)');
574  
575  
576 =head2 l($o)
577  
578 Length of a vector.
579  
580 Parameter Description
581 1 $o Vector
582  
583 B<Example:>
584  
585  
586 my ($z, $x, $y) = zeroAndUnits;
587  
588 ok 5 == ($x * 3 + $y * 4)->𝗹;
589 ok 25 == ($x * 3 + $y * 4)->l2;
590  
591 ok 2 * ($x + $y)->𝗹 == ($x + $y)->d (-$x - $y);
592 ok 4 * ($x + $y)->l2 == ($x + $y)->d2(-$x - $y);
593  
594  
595 =head2 l2($o)
596  
597 Length squared of a vector.
598  
599 Parameter Description
600 1 $o Vector
601  
602 B<Example:>
603  
604  
605 my ($z, $x, $y) = zeroAndUnits;
606  
607 ok 5 == ($x * 3 + $y * 4)->l;
608 ok 25 == ($x * 3 + $y * 4)->𝗹𝟮;
609  
610 ok 2 * ($x + $y)->l == ($x + $y)->d (-$x - $y);
611 ok 4 * ($x + $y)->𝗹𝟮 == ($x + $y)->d2(-$x - $y);
612  
613  
614 =head2 d($o, $p)
615  
616 Distance between the points identified by two vectors when placed on the same point.
617  
618 Parameter Description
619 1 $o Vector 1
620 2 $p Vector 2
621  
622 B<Example:>
623  
624  
625 my ($z, $x, $y) = zeroAndUnits;
626  
627 ok 5 == ($x * 3 + $y * 4)->l;
628 ok 25 == ($x * 3 + $y * 4)->l2;
629  
630 ok 2 * ($x + $y)->l == ($x + $y)->𝗱 (-$x - $y);
631 ok 4 * ($x + $y)->l2 == ($x + $y)->d2(-$x - $y);
632  
633  
634 =head2 d2($o, $p)
635  
636 Distance squared between the points identified by two vectors when placed on the same point.
637  
638 Parameter Description
639 1 $o Vector 1
640 2 $p Vector 2
641  
642 B<Example:>
643  
644  
645 my ($z, $x, $y) = zeroAndUnits;
646  
647 ok 5 == ($x * 3 + $y * 4)->l;
648 ok 25 == ($x * 3 + $y * 4)->l2;
649  
650 ok 2 * ($x + $y)->l == ($x + $y)->d (-$x - $y);
651 ok 4 * ($x + $y)->l2 == ($x + $y)->𝗱𝟮(-$x - $y);
652  
653  
654 =head2 n($o)
655  
656 Return a normalized a copy of a vector.
657  
658 Parameter Description
659 1 $o Vector
660  
661 B<Example:>
662  
663  
664 my ($z, $x, $y) = zeroAndUnits;
665 ok (($x * 3 + $y * 4)->𝗻 == $x * 3/5 + $y * 4/5);
666  
667 ok 0 == $x . $y;
668 ok 1 == $x . $x;
669 ok 1 == $y . $y;
670 ok 8 == ($x * 1 + $y * 2) .($x * 2 + $y * 3);
671  
672  
673 =head2 dot($o, $p)
674  
675 Dot product of two vectors.
676  
677 Parameter Description
678 1 $o Vector 1
679 2 $p Vector 2
680  
681 B<Example:>
682  
683  
684 my ($z, $x, $y) = zeroAndUnits;
685 ok (($x * 3 + $y * 4)->n == $x * 3/5 + $y * 4/5);
686  
687 ok 0 == $x . $y;
688 ok 1 == $x . $x;
689 ok 1 == $y . $y;
690 ok 8 == ($x * 1 + $y * 2) .($x * 2 + $y * 3);
691  
692  
693 =head2 area($o, $p)
694  
695 Signed area of the parallelogram defined by the two vectors. The area is negative if the second vector appears to the right of the first if they are both placed at the origin and the observer stands against the z-axis in a left handed coordinate system.
696  
697 Parameter Description
698 1 $o Vector 1
699 2 $p Vector 2
700  
701 B<Example:>
702  
703  
704 my ($z, $x, $y) = zeroAndUnits;
705 ok +1 == $x->cosine($x);
706 ok +1 == $y->cosine($y);
707 ok 0 == $x->cosine($y);
708 ok 0 == $y->cosine($x);
709  
710 ok 0 == $x->sine($x);
711 ok 0 == $y->sine($y);
712 ok +1 == $x->sine($y);
713 ok -1 == $y->sine($x);
714  
715 ok near -sqrt(1/2), ($x + $y)->sine($x);
716 ok near +sqrt(1/2), ($x + $y)->sine($y);
717 ok near -2, ($x + $y)->𝗮𝗿𝗲𝗮($x * 2);
718 ok near +2, ($x + $y)->𝗮𝗿𝗲𝗮($y * 2);
719  
720  
721 =head2 cosine($o, $p)
722  
723 cos(angle between two vectors)
724  
725 Parameter Description
726 1 $o Vector 1
727 2 $p Vector 2
728  
729 B<Example:>
730  
731  
732 my ($z, $x, $y) = zeroAndUnits;
733 ok +1 == $x->𝗰𝗼𝘀𝗶𝗻𝗲($x);
734 ok +1 == $y->𝗰𝗼𝘀𝗶𝗻𝗲($y);
735 ok 0 == $x->𝗰𝗼𝘀𝗶𝗻𝗲($y);
736 ok 0 == $y->𝗰𝗼𝘀𝗶𝗻𝗲($x);
737  
738 ok 0 == $x->sine($x);
739 ok 0 == $y->sine($y);
740 ok +1 == $x->sine($y);
741 ok -1 == $y->sine($x);
742  
743 ok near -sqrt(1/2), ($x + $y)->sine($x);
744 ok near +sqrt(1/2), ($x + $y)->sine($y);
745 ok near -2, ($x + $y)->area($x * 2);
746 ok near +2, ($x + $y)->area($y * 2);
747  
748  
749 =head2 sine($o, $p)
750  
751 sin(angle between two vectors)
752  
753 Parameter Description
754 1 $o Vector 1
755 2 $p Vector 2
756  
757 B<Example:>
758  
759  
760 my ($z, $x, $y) = zeroAndUnits;
761 ok +1 == $x->cosine($x);
762 ok +1 == $y->cosine($y);
763 ok 0 == $x->cosine($y);
764 ok 0 == $y->cosine($x);
765  
766 ok 0 == $x->𝘀𝗶𝗻𝗲($x);
767 ok 0 == $y->𝘀𝗶𝗻𝗲($y);
768 ok +1 == $x->𝘀𝗶𝗻𝗲($y);
769 ok -1 == $y->𝘀𝗶𝗻𝗲($x);
770  
771 ok near -sqrt(1/2), ($x + $y)->𝘀𝗶𝗻𝗲($x);
772 ok near +sqrt(1/2), ($x + $y)->𝘀𝗶𝗻𝗲($y);
773 ok near -2, ($x + $y)->area($x * 2);
774 ok near +2, ($x + $y)->area($y * 2);
775  
776  
777 =head2 angle($o, $p)
778  
779 Angle in radians anticlockwise that the first vector must be rotated to point along the second vector normalized to the range: -pi to +pi.
780  
781 Parameter Description
782 1 $o Vector 1
783 2 $p Vector 2
784  
785 B<Example:>
786  
787  
788 my ($zero, $x, $y) = zeroAndUnits;
789 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(+1, -1)), deg2rad(-135);
790 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(+1, 0)), deg2rad(-90);
791 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(+1, +1)), deg2rad(-45);
792 ok near $y->𝗮𝗻𝗴𝗹𝗲(new( 0, +1)), deg2rad(+0);
793 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(-1, +1)), deg2rad(+45);
794 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(-1, 0)), deg2rad(+90);
795 ok near $y->𝗮𝗻𝗴𝗹𝗲(new(-1, -1)), deg2rad(+135);
796  
797 ok near new(1,1) < new( 0, -1), deg2rad(-135);
798 ok near new(1,1) < new( 1, -1), deg2rad(-90);
799 ok near new(1,1) < new( 1, 0), deg2rad(-45);
800 ok near new(1,1) < new( 1, 1), deg2rad(0);
801 ok near new(1,1) < new( 0, 1), deg2rad(+45);
802 ok near new(1,1) < new(-1, 1), deg2rad(+90);
803 ok near new(1,1) < new(-1, 0), deg2rad(+135);
804  
805 ok near $x + $y * sqrt(3) < $x, deg2rad(-60);
806 ok near $x + $y * sqrt(3) < $y, deg2rad(+30);
807  
808 for my $i(-179..179)
809 {ok near $x < new(cos(deg2rad($i)), sin(deg2rad($i))), deg2rad($i);
810 }
811  
812  
813 =head2 r90($o)
814  
815 Rotate a vector by 90 degrees anticlockwise.
816  
817 Parameter Description
818 1 $o Vector to rotate
819  
820 B<Example:>
821  
822  
823 my ($z, $x, $y) = zeroAndUnits;
824 ok $x->𝗿𝟵𝟬 == $y;
825 ok $y->𝗿𝟵𝟬 == -$x;
826 ok $x->𝗿𝟵𝟬->𝗿𝟵𝟬 == -$x;
827 ok $y->𝗿𝟵𝟬->𝗿𝟵𝟬 == -$y;
828 ok $x->𝗿𝟵𝟬->𝗿𝟵𝟬->𝗿𝟵𝟬 == -$y;
829 ok $y->𝗿𝟵𝟬->𝗿𝟵𝟬->𝗿𝟵𝟬 == $x;
830  
831  
832 =head2 r180($o)
833  
834 Rotate a vector by 180 degrees.
835  
836 Parameter Description
837 1 $o Vector to rotate
838  
839 B<Example:>
840  
841  
842 my ($z, $x, $y) = zeroAndUnits;
843 ok $x->r90 == $y;
844 ok $y->r90 == -$x;
845 ok $x->r90->r90 == -$x;
846 ok $y->r90->r90 == -$y;
847 ok $x->r90->r90->r90 == -$y;
848 ok $y->r90->r90->r90 == $x;
849  
850  
851 =head2 r270($o)
852  
853 Rotate a vector by 270 degrees anticlockwise.
854  
855 Parameter Description
856 1 $o Vector to rotate
857  
858 B<Example:>
859  
860  
861 my ($z, $x, $y) = zeroAndUnits;
862 ok $x->r90 == $y;
863 ok $y->r90 == -$x;
864 ok $x->r90->r90 == -$x;
865 ok $y->r90->r90 == -$y;
866 ok $x->r90->r90->r90 == -$y;
867 ok $y->r90->r90->r90 == $x;
868  
869  
870 =head2 swap($o)
871  
872 Swap the components of a vector
873  
874 Parameter Description
875 1 $o Vector
876  
877 B<Example:>
878  
879  
880 my ($z, $x, $y) = zeroAndUnits;
881 ok $x->𝘀𝘄𝗮𝗽 == $y;
882 ok $x->clone == $x;
883  
884  
885  
886 =head2 Math::Vectors2 Definition
887  
888  
889 Attributes of a vector
890  
891  
892  
893  
894 =head3 Output fields
895  
896  
897 B<x> - X coordinate
898  
899 B<y> - Y coordinate
900  
901  
902  
903 =head1 Index
904  
905  
906 1 L<angle|/angle> - Angle in radians anticlockwise that the first vector must be rotated to point along the second vector normalized to the range: -pi to +pi.
907  
908 2 L<area|/area> - Signed area of the parallelogram defined by the two vectors.
909  
910 3 L<clone|/clone> - Clone a vector.
911  
912 4 L<cosine|/cosine> - cos(angle between two vectors)
913  
914 5 L<d|/d> - Distance between the points identified by two vectors when placed on the same point.
915  
916 6 L<d2|/d2> - Distance squared between the points identified by two vectors when placed on the same point.
917  
918 7 L<divide|/divide> - Divide a copy of a vector by a scalar and return the result.
919  
920 8 L<Divide|/Divide> - Divide a vector by a scalar and return the result.
921  
922 9 L<dot|/dot> - Dot product of two vectors.
923  
924 10 L<eq|/eq> - Whether two vectors are equal to within the accuracy of floating point arithmetic
925  
926 11 L<l|/l> - Length of a vector.
927  
928 12 L<l2|/l2> - Length squared of a vector.
929  
930 13 L<Minus|/Minus> - Subtract zero or more vectors from the first vector and return the result.
931  
932 14 L<minus|/minus> - Subtract zero or more vectors from a copy of the first vector and return the result.
933  
934 15 L<Multiply|/Multiply> - Multiply a vector by a scalar and return the result.
935  
936 16 L<multiply|/multiply> - Multiply a copy of a vector by a scalar and return the result.
937  
938 17 L<n|/n> - Return a normalized a copy of a vector.
939  
940 18 L<new|/new> - Create new vector from components.
941  
942 19 L<Plus|/Plus> - Add zero or more other vectors to the first vector and return the result.
943  
944 20 L<plus|/plus> - Add zero or more other vectors to a copy of the first vector and return the result.
945  
946 21 L<print|/print> - Print one or more vectors.
947  
948 22 L<r180|/r180> - Rotate a vector by 180 degrees.
949  
950 23 L<r270|/r270> - Rotate a vector by 270 degrees anticlockwise.
951  
952 24 L<r90|/r90> - Rotate a vector by 90 degrees anticlockwise.
953  
954 25 L<sine|/sine> - sin(angle between two vectors)
955  
956 26 L<swap|/swap> - Swap the components of a vector
957  
958 27 L<zero|/zero> - Whether a vector is equal to zero within the accuracy of floating point arithmetic
959  
960 28 L<zeroAndUnits|/zeroAndUnits> - Create the useful vectors: o=(0,0), x=(1,0), y=(0,1)
961  
962 =head1 Installation
963  
964 This module is written in 100% Pure Perl and, thus, it is easy to read,
965 comprehend, use, modify and install via B<cpan>:
966  
967 sudo cpan install Math::Vectors2
968  
969 =head1 Author
970  
971 L<philiprbrenan@gmail.com|mailto:philiprbrenan@gmail.com>
972  
973 L<http://www.appaapps.com|http://www.appaapps.com>
974  
975 =head1 Copyright
976  
977 Copyright (c) 2016-2019 Philip R Brenan.
978  
979 This module is free software. It may be used, redistributed and/or modified
980 under the same terms as Perl itself.
981  
982 =cut
983  
984  
985  
986 # Tests and documentation
987  
988 sub test
989 1 ▶ {my $p = __PACKAGE__;
Subroutine test: called CC=5 SCAR=16.4
Pod undocumented
990 1 binmode($_, ":utf8") for *STDOUT, *STDERR;
991 1 ▶ return if eval "eof(${p}::DATA)";
Branch: 1 branch
BranchTrueFalseTotal
if eval "eof(${p}::DATA)" 0 1 1
992 1 my $s = eval "join('', <${p}::DATA>)";
993 1 ▶ $@ and die $@;
Branch: 1 branch
BranchTrueFalseTotal
$@ and die $@ 0 1 1
994 1 ▶ eval $s;
Subroutine BEGIN: called CC=1 SCAR=0.0
995 1 ▶ $@ and die $@;
Branch: 1 branch
BranchTrueFalseTotal
$@ and die $@ 0 1 1
996 1 1
997 }
998  
999 1 ▶test unless caller;
Branch: 1 branch
BranchTrueFalseTotal
unless caller 0 1 1
1000  
1001 1 1;
1002 # podDocumentation
1003 __DATA__
« Build ↑ Summary