API reference - Class Box

Notation used in Ruby API documentation

Description: A box class with floating-point coordinates

This object represents a box (a rectangular shape).

The definition of the attributes is: p1 is the lower left point, p2 the upper right one. If a box is constructed from two points (or four coordinates), the coordinates are sorted accordingly.

A box can be empty. An empty box represents no area (not even a point). Empty boxes behave neutral with respect to most operations. Empty boxes return true on empty?.

A box can be a point or a single line. In this case, the area is zero but the box still can overlap other boxes for example and it is not empty.

See The Database API for more details about the database objects.

Public constructors

new BoxnewDefault constructor: creates an empty (invalid) box
new Boxnew(int left,
int bottom,
int right,
int top)
Constructor with four coordinates
new Boxnew(const Point lower_left,
const Point upper_right)
Constructor with two points

Public methods

[const]bool!=(const Box box)Inequality
[const]Box&(const Box box)Intersection of boxes
[const]Box*(const Box box)Convolve boxes
[const]Box*(double scale_factor)Scale box
[const]Box+(const Point point)Join box with a point
[const]Box+(const Box box)Joining of boxes
[const]bool<(const Box box)Less operator
[const]bool==(const Box box)Equality
[const]doubleareaCompute the box area
[const]voidassign(const Box other)Assign the contents of another object to self
[const]intbottomThe bottom coordinate of the box
voidbottom=(int c)Set the bottom coordinate of the box
[const]PointcenterThe center of the box
[const]boolcontains?(int x,
int y)
Returns true if the box contains the given point
[const]boolcontains?(const Point point)Returns true if the box contains the given point
voidcreateEnsures the C++ object is created
voiddestroyExplicitly destroy the object
[const]booldestroyed?Returns a value indicating whether the object was already destroyed
[const]BoxdupCreates a copy of self
[const]boolempty?Empty predicate
Boxenlarge(int dx,
int dy)
Enlarges the box by a certain amount.
Boxenlarge(const Point enlargement)Enlarges the box by a certain amount.
[const]Boxenlarged(int dx,
int dy)
Enlarges the box by a certain amount.
[const]Boxenlarged(const Point enlargement)Enlarges the box by a certain amount.
[const]unsigned intheightThe height of the box
[const]boolinside?(const Box box)Test if this box is inside the argument box
[const]boolis_const_object?Returns a value indicating whether the reference is a const reference
[const]boolis_point?Return true, if the box is a single point
[const]intleftThe left coordinate of the box
voidleft=(int c)Set the left coordinate of the box
Boxmove(int dx,
int dy)
Moves the box by a certain distance
Boxmove(const Point distance)Moves the box by a certain distance
[const]Boxmoved(int dx,
int dy)
Moves the box by a certain distance
[const]Boxmoved(const Point distance)Returns the box moved by a certain distance
[const]booloverlaps?(const Box box)Test if this box overlaps the argument box
[const]Pointp1The lower left point of the box
voidp1=(const Point p)Set the lower left point of the box
[const]Pointp2The upper right point of the box
voidp2=(const Point p)Set the upper right point of the box
[const]intperimeterReturns the perimeter of the box
[const]intrightThe right coordinate of the box
voidright=(int c)Set the right coordinate of the box
[const]stringto_sConvert to a string
[const]inttopThe top coordinate of the box
voidtop=(int c)Set the top coordinate of the box
[const]booltouches?(const Box box)Test if this box touches the argument box
[const]Boxtransformed(const ICplxTrans t)Transform the box with the given complex transformation
[const]Boxtransformed(const Trans t)Transform the box with the given simple transformation
[const]DBoxtransformed(const CplxTrans t)Transform the box with the given complex transformation
[const]unsigned intwidthThe width of the box

Public static methods and constants

Boxfrom_dbox(const DBox double_box)Construct an integer box from a floating-point coordinate box
new Boxfrom_s(string s)Creates an object from a string

Deprecated methods (protected, public, static, non-static and constructors)

[static]new Boxnew_lbrt(int left,
int bottom,
int right,
int top)
Use of this method is deprecated. Use new instead
[static]new Boxnew_pp(const Point lower_left,
const Point upper_right)
Use of this method is deprecated. Use new instead
[const]Boxtransformed_cplx(const ICplxTrans t)Use of this method is deprecated. Use transformed instead
[const]DBoxtransformed_cplx(const CplxTrans t)Use of this method is deprecated. Use transformed instead

Detailed description

[const] bool !=(const Box box)

Description: Inequality

Return true, if this box and the given box are not equal

[const] Box &(const Box box)

Description: Intersection of boxes

box:The box to take the intersection with
Returns:The intersection box

The intersection of two boxes is the largest box common to both boxes. The intersection may be empty if both boxes to not touch. If the boxes do not overlap but touch the result may be a single line or point with an area of zero. Overwrites this box with the result.

[const] Box *(const Box box)

Description: Convolve boxes

box:The box to convolve with this box.
Returns:The convolved box

The * operator convolves the firstbox with the one given as the second argument. The box resulting from "convolution" is the outer boundary of the union set formed by placing the second box at every point of the first. In other words, the returned box of (p1,p2)*(q1,q2) is (p1+q1,p2+q2).

[const] Box *(double scale_factor)

Description: Scale box

scale_factor:The scaling factor
Returns:The scaled box

The * operator scales the box with the given factor and returns the result.

This method has been introduced in version 0.22.

[const] Box +(const Point point)

Description: Join box with a point

point:The point to join with this box.
Returns:The box joined with the point

The + operator joins a point with the box. The resulting box will enclose both the original box and the point.

[const] Box +(const Box box)

Description: Joining of boxes

box:The box to join with this box.
Returns:The joined box

The + operator joins the first box with the one given as the second argument. Joining constructs a box that encloses both boxes given. Empty boxes are neutral: they do not change another box when joining. Overwrites this box with the result.

[const] bool <(const Box box)

Description: Less operator

Return true, if this box is 'less' with respect to first and second point (in this order)

[const] bool ==(const Box box)

Description: Equality

Return true, if this box and the given box are equal

[const] double area

Description: Compute the box area

Returns the box area or 0 if the box is empty

[const] void assign(const Box other)

Description: Assign the contents of another object to self

This method assigns the contents of another object to self. This is a deep copy that does not only copy the reference but the actual content.

[const] int bottom

Description: The bottom coordinate of the box

void bottom=(int c)

Description: Set the bottom coordinate of the box

[const] Point center

Description: The center of the box

[const] bool contains?(int x,int y)

Description: Returns true if the box contains the given point

Returns:true if the point is inside the box.

Tests whether a point (x, y) is inside the box. It also returns true if the point is exactly on the box contour.

[const] bool contains?(const Point point)

Description: Returns true if the box contains the given point

p:The point to test against.
Returns:true if the point is inside the box.

Tests whether a point is inside the box. It also returns true if the point is exactly on the box contour.

void create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

void destroy

Description: Explicitly destroy the object

Explicitly destroy the object on C++ side if it was owned by the Ruby interpreter. Subsequent access to this object will throw an exception. If the object is not owned by Ruby, this method will do nothing.

[const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

[const] Box dup

Description: Creates a copy of self

[const] bool empty?

Description: Empty predicate

An empty box may be created with the default constructor for example. Such a box is neutral when combining it with other boxes and renders empty boxes if used in box intersections and false in geometrical relationship tests.

Box enlarge(int dx,int dy)

Description: Enlarges the box by a certain amount.

Returns:A reference to this box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Box enlarge(const Point enlargement)

Description: Enlarges the box by a certain amount.

enlargement:The grow or shrink amount in x and y direction
Returns:A reference to this box.

Enlarges the box by x and y value specified in the vector passed. Positive values with grow the box, negative ones will shrink the box. The result may be an empty box if the box disappears. The amount specifies the grow or shrink per edge. The width and height will change by twice the amount. Does not check for coordinate overflows.

[const] Box enlarged(int dx,int dy)

Description: Enlarges the box by a certain amount.

Returns:The enlarged box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

[const] Box enlarged(const Point enlargement)

Description: Enlarges the box by a certain amount.

enlargement:The grow or shrink amount in x and y direction
Returns:The enlarged box.

Enlarges the box by x and y value specified in the vector passed. Positive values with grow the box, negative ones will shrink the box. The result may be an empty box if the box disappears. The amount specifies the grow or shrink per edge. The width and height will change by twice the amount. Does not modify this box. Does not check for coordinate overflows.

[static] Box from_dbox(const DBox double_box)

Description: Construct an integer box from a floating-point coordinate box

Create a integer coordinate box from a floating-point coordinate box

[static] new Box from_s(string s)

Description: Creates an object from a string

Creates the object from a string representation (as returned by to_s)

This method has been added in version 0.23.

[const] unsigned int height

Description: The height of the box

[const] bool inside?(const Box box)

Description: Test if this box is inside the argument box

Returns true, if this box is inside the given box, i.e. the box intersection renders this box

[const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

[const] bool is_point?

Description: Return true, if the box is a single point

[const] int left

Description: The left coordinate of the box

void left=(int c)

Description: Set the left coordinate of the box

Box move(int dx,int dy)

Description: Moves the box by a certain distance

Returns:A reference to this box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

Box move(const Point distance)

Description: Moves the box by a certain distance

distance:The offset to move the box.
Returns:A reference to this box.

Moves the box by a given offset and returns the moved box. Does not check for coordinate overflows.

[const] Box moved(int dx,int dy)

Description: Moves the box by a certain distance

Returns:The enlarged box.

This is a convenience method which takes two values instead of a Point object. This method has been introduced in version 0.23.

[const] Box moved(const Point distance)

Description: Returns the box moved by a certain distance

distance:The offset to move the box.
Returns:The moved box.

Moves the box by a given offset and returns the moved box. Does not modify this box. Does not check for coordinate overflows.

[static] new Box new

Description: Default constructor: creates an empty (invalid) box

[static] new Box new(int left,int bottom,int right,int top)

Description: Constructor with four coordinates

Four coordinates are given to create a new box. If the coordinates are not provided in the correct order (i.e. right < left), these are swapped.

[static] new Box new(const Point lower_left,const Point upper_right)

Description: Constructor with two points

Two points are given to create a new box. If the coordinates are not provided in the correct order (i.e. right < left), these are swapped.

[static] new Box new_lbrt(int left,int bottom,int right,int top)

Description: Constructor with four coordinates

This method is deprecated. Use method 'new' instead

[static] new Box new_pp(const Point lower_left,const Point upper_right)

Description: Constructor with two points

This method is deprecated. Use method 'new' instead

[const] bool overlaps?(const Box box)

Description: Test if this box overlaps the argument box

Returns true, if the intersection box of this box with the argument box exists and has a non-vanishing area

[const] Point p1

Description: The lower left point of the box

void p1=(const Point p)

Description: Set the lower left point of the box

[const] Point p2

Description: The upper right point of the box

void p2=(const Point p)

Description: Set the upper right point of the box

[const] int perimeter

Description: Returns the perimeter of the box

This method is equivalent to 2*(width+height). For empty boxes, this method returns 0.

This method has been introduced in version 0.23.

[const] int right

Description: The right coordinate of the box

void right=(int c)

Description: Set the right coordinate of the box

[const] string to_s

Description: Convert to a string

[const] int top

Description: The top coordinate of the box

void top=(int c)

Description: Set the top coordinate of the box

[const] bool touches?(const Box box)

Description: Test if this box touches the argument box

Returns true, if this box has at least one point common with the argument box

[const] Box transformed(const ICplxTrans t)

Description: Transform the box with the given complex transformation

t:The magnifying transformation to apply
Returns:The transformed box (in this case an integer coordinate box)

This method has been introduced in version 0.18.

[const] Box transformed(const Trans t)

Description: Transform the box with the given simple transformation

t:The transformation to apply
Returns:The transformed box

[const] DBox transformed(const CplxTrans t)

Description: Transform the box with the given complex transformation

t:The magnifying transformation to apply
Returns:The transformed box (a DBox now)

[const] Box transformed_cplx(const ICplxTrans t)

Description: Transform the box with the given complex transformation

t:The magnifying transformation to apply
Returns:The transformed box (in this case an integer coordinate box)

This method is deprecated. Use method 'transformed' instead

[const] DBox transformed_cplx(const CplxTrans t)

Description: Transform the box with the given complex transformation

t:The magnifying transformation to apply
Returns:The transformed box (a DBox now)

This method is deprecated. Use method 'transformed' instead

[const] unsigned int width

Description: The width of the box