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 <leonerd@leonerd.org.uk>