/ 
Graphics-Grid-0.0000_03
River stage zero No dependents
/ Graphics::Grid::Unit

NAME

Graphics::Grid::Unit - A vector of unit values

VERSION

version 0.0000_03

SYNOPSIS

use Graphics::Grid::Unit;

# $u1, $u2, $u3 are same
my $u1 = Graphics::Grid::Unit->new(42);
my $u2 = Graphics::Grid::Unit->new(42, "npc");
my $u3 = Graphics::Grid::Unit->new(value => 42, unit => "npc");

# $u4, $u5, and $u6 are same
my $u3 = Graphics::Grid::Unit->new([1,2,3], "npc");
my $u4 = Graphics::Grid::Unit->new([1,2,3], ["npc", "npc", "npc"]);
my $u4 = Graphics::Grid::Unit->new(value => [1,2,3], unit => "npc");

# or use the function interface
use Graphics::Grid::Functions qw(:all);
my $u = unit(@params);

DESCRIPTION

A Graphics::Grid::Unit object is an array ref of unit values. A unit value is a single numeric value with an associated unit.

ATTRIBUTES

value

Array ref of numbers.

unit

Array ref of units.

Possible units are:

  • npc

    Normalised Parent Coordinates (the default). The origin of the viewport is (0, 0) and the viewport has a width and height of 1 unit. For example, (0.5, 0.5) is the centre of the viewport.

  • cm

    Centimeters.

  • inches

    Inches. 1 in = 2.54 cm.

  • mm

    Millimeters. 10 mm = 1 cm.

  • points

    Points. 72.27 pt = 1 in.

  • picas

    Picas. 1 pc = 12 pt.

  • char

    Multiples of nominal font height of the viewport (as specified by the viewport's fontsize).

  • native

    Locations and dimensions are relative to the viewport's xscale and yscale.

METHODS

at($idx)

This method returns an object of the same Graphics::Grid::Unit class. The returned object represents the value and unit at given index, and has at only one value and one unit.

my $u1 = Graphics::Grid::Unit->new(value => [2,3,4], unit => "npc");

# $u2 is same as Graphics::Grid::GPar->new(value => 3, unit => "npc");
my $u2 = $u1->at(1);

$idx is applied like wrap-indexing. So below are same as above.

my $u3 = $u1->at(4);
my $u4 = $u2->at(42);

elems

Number of effective values in the object.

is_absolute_unit($unit_name)

This is a class method. It tells if the given unit name is absolute or not.

my $is_absolute = Graphics::Grid::Unit->is_absolute_unit('cm');

stringify

Stringify the object.

CONSTRUCTOR

The constructor supports multiple forms of parameters. It can coerce from a single value to array ref. And it allows specifying the values and units without the value and unit keys.

So below are all equivalent,

Graphics::Grid::Unit->new(42);      # unit defaults to npc
Graphics::Grid::Unit->new([42]); 
Graphics::Grid::Unit->new(42, "npc");
Graphics::Grid::Unit->new([42], ["npc"]);
Graphics::Grid::Unit->new(value => 42);
Graphics::Grid::Unit->new(value => [42]);
Graphics::Grid::Unit->new(value => 42, unit => "npc");
Graphics::Grid::Unit->new(value => [42], unit => ["npc"]);

ARITHMETIC

Several arithmetic operations, +, -, and *, are supported on Graphics::Grid::Unit objects.

use Graphics::Grid::Functions qw(:all);

# 1cm+0.5npc, 2cm+0.5npc, 3cm+0.5npc
my $ua1 = unit([1,2,3], "cm") + unit(0.5);

# 1cm*2, 2cm*2, 3cm*2
my $ua2 = unit([1,2,3], "cm") * 2;

A plus or minus operation requires both its binary operands are consumers of Graphics::Grid::UnitLike. The multiply operation requires one of its operands is consumer of Graphics::Grid::UnitLike, the other a number or array ref of numbers.

Return value of an operation is an object of Graphics::Grid::UnitArithmetic.

SEE ALSO

Graphics::Grid

Graphics::Grid::UnitLike

Graphics::Grid::UnitArithmetic

AUTHOR

Stephan Loyd <sloyd@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Stephan Loyd.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.