NAME

Pop::Point

SYNOPSIS

use Pop::Point :operators;

my $a = Pop::Point.new: 3, 4;
    my $b = $a.add: 4;

say $a.length;  # OUTPUT: 5
    say ~$a.normal; # OUTPUT: (0.6, 0.8)

say $a == $a * -1; # True: they have the same length
    say $a ~~ $a * -1; # False: they are different points
    say $a === $a * 1; # True: point are immutable value objects

DESCRIPTION

Pop::Point is a basic, immutable 2D vector class in common use throughout Pop.

Methods in this class aim to cover the common use cases in Pop, and will in some cases (eg. angle) adjust their results so they are more convenient to use in that context. It does not aim to be a generic point class.

For performance reasons, Pop::Point objects store their component values as floating point numbers.

Pop::Point objects are value objects.

Coercions

Single Real values, or lists of two of them, can be coerced into Pop::Point objects. When coercing a single numeric value, it will be used for both components.

When using a Pop::Point object in a numeric context , it will be converted to a number by calling lenght. Calling list (either directly or indirectly via eg. |) will return the values of the components as a list.

When coercing a Pop::Point to Bool, it will be True if any of its components has a non-zero value.

Operators

The following operators will be exported if Pop::Point is imported with the :operators tag:

multi infix:<cmp> ( Pop::Point, Pop::Point )

Compares the length of both points

multi infix:<+> ( Pop::Point, Pop::Point )
    multi infix:<-> ( Pop::Point, Pop::Point )
    multi infix:<*> ( Pop::Point, Pop::Point )
    multi infix:</> ( Pop::Point, Pop::Point )

Call add, sub, mul, and div with the second point on the first.

multi infix:<+> ( Pop::Point, Real )
    multi infix:<-> ( Pop::Point, Real )
    multi infix:<*> ( Pop::Point, Real )
    multi infix:</> ( Pop::Point, Real )

Call add, sub, mul, and div with the numeric on the point.

multi infix:<⨯> ( Pop::Point,   Pop::Point )
    multi infix:<⋅> ( Pop::Point,   Pop::Point )

Call cross and dot with the second point on the first.

multi infix:<+> ( Pop::Point, ( Real, Real ) )
    multi infix:<-> ( Pop::Point, ( Real, Real ) )
    multi infix:<*> ( Pop::Point, ( Real, Real ) )
    multi infix:</> ( Pop::Point, ( Real, Real ) )

Call add, sub, mul, and div with the numeric list on the point.

METHODS

new

method new (
        Real $x,
        Real $y = $x,
    ) returns Pop::Point

Takes two positional Real arguments and constructs a new Pop::Point object with them set as the X and Y components respectively. If called with a single value instead, this value will be used for both components.

zero

method zero () returns Pop::Point

Constructs a Pop::Point object with both components set to 0. This point will evaluate to false if coerced to a Bool.

x

method x () returns Num

Returns the X component for this point.

y

method y () returns Num

Returns the Y component for this point.

length

method length () returns Num

Returns the length of this Pop::Point object, when treated as 2D vector.

normal

method normal () returns Pop::Point

Returns a Pop::Point object with the same direction as the original, but with a length of 1.

floor

method floor () returns Pop::Point

Returns a Pop::Point object with both components rounded down.

round

method round () returns Pop::Point

Returns a Pop::Point object with both components rounded to their nearest integer.

ceiling

method ceiling () returns Pop::Point

Returns a Pop::Point object with both components rounded up.

angle

multi method angle () returns Num

multi method angle (
        Pop::Point:D $reference,
    ) returns Num

Gives the angle in radians relative to the zero point, or to the point that is passed as argument. The angle will be returned in such a way that it is directly usable with the SDL coordinate system, where the Y-axis increases down.

This means that 0 will point right, π will point left, π/2 will point down, and -π/2 will point up.

add

multi method add (
        Num(Real) $x,
        Num(Real) $y = $x,
    ) returns Pop::Point

multi method add (
        Pop::Point:D $other,
    ) returns Pop::Point

If called with a Pop::Point object, add the components of the argument to those of the invocant and return them in a new Pop::Point object.

If called with two numeric values, they will be added to the X and Y components respectively. If only one value is provided, it will be used for both components.

mul

multi method mul (
        Num(Real) $x,
        Num(Real) $y = $x,
    ) returns Pop::Point

multi method mul (
        Pop::Point:D $other,
    ) returns Pop::Point

If called with a Pop::Point object, multiply the components of the argument with those of the invocant and return them in a new Pop::Point object.

If called with two numeric values, they will be added to the X and Y components respectively. If only one value is provided, it will be used for both components.

sub

multi method sub (
        Num(Real) $x,
        Num(Real) $y = $x,
    ) returns Pop::Point

multi method sub (
        Pop::Point:D $other,
    ) returns Pop::Point

If called with a Pop::Point object, subtract the components of the argument from those of the invocant and return them in a new Pop::Point object.

If called with two numeric values, they will be added to the X and Y components respectively. If only one value is provided, it will be used for both components.

div

multi method div (
        Num(Real) $x,
        Num(Real) $y = $x,
    ) returns Pop::Point

multi method div (
        Pop::Point:D $other,
    ) returns Pop::Point

If called with a Pop::Point object, divide the components of the invocant by those of the argument and return them in a new Pop::Point object.

If called with two numeric values, they will be added to the X and Y components respectively. If only one value is provided, it will be used for both components.

cross

method cross (
        Pop::Point:D $other,
    ) returns Num

Called with a Pop::Point object, return the cross product of both vectors.

dot

method dot (
        Pop::Point:D $other,
    ) returns Num

Called with a Pop::Point object, return the dot product of both vectors.

ACKNOWLEDGEMENTS

This class takes a lot of the basic infrastructure code from the Point class by Joshua Yeshouroun.

COPYRIGHT AND LICENSE

Copyright 2021 José Joaquín Atria

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.