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.

cpanm Graphics::Grid

perl -MCPAN -e shell
install Graphics::Grid