Tickit::Rect - a lightweight data structure representing a rectangle

NAME  SYNOPSIS  DESCRIPTION  CONSTRUCTORS  new  intersect  translate  ACCESSORS  top  left  bottom  right  lines  cols  linerange  METHODS  equals  contains  intersects  add  subtract  AUTHOR 

---

NAME

"Tickit::Rect" − a lightweight data structure representing a rectangle

SYNOPSIS

use Tickit::Rect;
my $rect = Tickit::Rect−>new(
top => 0, left => 5, lines => 3, cols => 10
);

DESCRIPTION

Objects in this class represent a rectangle, by storing the top left corner coordinate and the size in lines and columns. This data structure is purely abstract and not tied to a particular window or coordinate system. It exists simply as a convenient data store containing some useful utility methods.

CONSTRUCTORS

new

$rect = Tickit::Rect−>new( %args )

Construct a new rectangle of the given geometry, given by "top", "left" and either "lines" and "cols", or "bottom" and "right".

$rect = Tickit::Rect−>new( $str )

If given a single string, this will be parsed in the form

(left,top)..(right,bottom)

intersect

$rect = $existing_rect−>intersect( $other_rect )

If there is an intersection between the given rectangles, return it. If not, return "undef".

translate

$rect = $existing_rect−>translate( $downward, $rightward )

Returns a new rectangle of the same size as the given one, moved down and to the right by the given argmuents (which may be negative)

ACCESSORS

top

left

bottom

right

$top = $rect−>top
$left = $rect−>left
$bottom = $rect−>bottom
$right = $rect−>right

Return the edge boundaries of the rectangle.

lines

cols

$lines = $rect−>lines
$cols = $rect−>cols

Return the size of the rectangle.

linerange

@lines = $rect−>linerange( $min, $max )

A convenient shortcut to generate the list of lines covered that are within the given bounds (either bound may be given as "undef"). Without bounds, equivalent to:

$rect−>top .. $rect−>bottom − 1

METHODS

equals

$bool = $rect−>equals( $other )
$bool = ( $rect == $other )

Returns true if $other represents the same area as $rect. This method overloads the numerical equality operator ("==").

contains

$bool = $rect−>contains( $other )

Returns true if $other is entirely contained within the bounds of $rect.

intersects

$bool = $rect−>intersects( $other )

Returns true if $other and $rect intersect at all, even if they overlap.

add

@r = $rect−>add( $other )

Returns a list of the non−overlapping regions covered by either $rect or $other.

In the trivial case that the two given rectangles do not touch, the result will simply be a list of the two initial rectangles. Otherwise a list of newly−constructed rectangles will be returned that covers the same area as the original two. This list will contain anywhere between 1 and 3 rectangles.

subtract

@r = $rect−>subtract( $other )

Returns a list of the non−overlapping regions covered by $rect but not by $other.

In the trivial case that $other completely covers $rect then the empty list is returned. In the trivial case that $other and $rect do not intersect then a list containing $rect is returned. Otherwise, a list of newly−constructed rectangles will be returned that covers the required area. This list will contain anywhere between 1 and 4 rectangles.

AUTHOR

Paul Evans <[email protected]>

---