/ 
Graphics-Grid-0.001
River stage zero No dependents
/ Graphics::Grid::Unit

NAME

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

VERSION

version 0.001

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.

  • lines

    Lines of text. Locations and dimensions are in terms of multiples of the default text size of the viewport (as specified by the viewport's fontsize and lineheight).

  • 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.

  • null

    Only meaningful for layouts. It indicates what relative fraction of the available width/height the column/row occupies.

  • grobwidth

    Multiples of the width of the grob specified in the data attr.

  • grobheight

    Multiples of the height of the grob specified in the data argument.

data

Needed if unit is "grobwidth" or "grobheight".

METHODS

elems

Number of effective values in the object.

length

This is an alias of elems().

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);

slice($indices)

Slice by indices.

string()

Returns a string representing the object.

sum()

Sum the effective unit vector in a unit object.

append($other)

Append two UnitLike objects. If both are Graphics::Grid::Unit objects, this method would return a Graphics::Grid::Unit object. Otherwise, it would return a Graphics::Grid::UnitList object.

insert($other, $after=$self->elems-1)

Insert another UnitLike object after index $after. Insert before first element if after is a negative value.

as_hashref()

is_absolute()

Returns true if all units in this object are absolute.

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-2023 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.