Class: TPrimitiveRegion

Declaration: PrintPrimitives.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

Items in a grid array can be grouped in various combinations to form collections or sets. These sets can be queried for containment of a specific coordinate and sets can be manipulated to modify their contents. In fact, sets of coordinates act very much like classical sets, because they obey the rules of Union, Intersection, Difference, and ExclusiveOr operations that pertain to primitive sets. The class that represents sets of grid coordinates is called TPrimitiveRegion. A TPrimitiveRegion can cover the entire 2-D unsigned integer space. All the elements of a TSimpleGrid can be represented by a region whose set contents are all the elements surrounded by the grid. Elements are added to or removed from the grid using SetRange, Union, Intersection, Difference, or ExclusiveOr. In addition, all elements inside the set can be placed outside and all elements outside the set can be placed inside by using Not.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is not intended to have derived classes descend from it. This is a fully functional class. Other classes could be derived from this class to change basic functionality such as the set operations.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPrimitiveRegion::TPrimitiveRegion

TPrimitiveRegion ()
TPrimitiveRegion (const TPrimitiveRegion &)
TPrimitiveRegion (const TULongPair & rectRegion)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.
Constructor initially set to be the rectangular region.

Calling Context:

Called by the stream-in operators and directly.
Called to copy an object.
Called to create an object.

Parameters:

Takes no parameters.
const TPrimitiveRegion & -The region to copy during construction.
const TULongPair & rectRegion -An initial rectangular region.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::~TPrimitiveRegion

virtual ~ TPrimitiveRegion ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Contains

virtual bool Contains (const TULongPair &) const

Interface Category:

API.

Purpose:

Determines if the coordinate is contained in the region.

Calling Context:

Called to verify if a coordinate is within the region.

Parameters:

const TULongPair & -The coordinate to be checked for containment.

Return Value:

Returns true if the TULongPair point is within the region.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines if the region is empty.

Calling Context:

Called to test for an empty region.

Parameters:

Takes no parameters.

Return Value:

Returns true if the region is empty.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::IsFull

virtual bool IsFull () const

Interface Category:

API.

Purpose:

Determines if the region is full (contains all elements it is capable of holding).

Calling Context:

Called to test if the region is full.

Parameters:

Takes no parameters.

Return Value:

Returns true if the region can contain no more items.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::GetItemCountInRange

virtual unsigned long GetItemCountInRange () const

Interface Category:

API.

Purpose:

Returns the number of items in the range.

Calling Context:

Called to obtain a count of items in the range.

Parameters:

Takes no parameters.

Return Value:

Returns the number of items within the range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::GetBounds

virtual TULongRect GetBounds () const

Interface Category:

API.

Purpose:

Gets the loose bounds of the region as a TULongRect.

Calling Context:

Called to obtain the loose bounds of the region.

Parameters:

Takes no parameters.

Return Value:

Returns the loose bounds of the region as a rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::SetRange

virtual void SetRange (const TULongPair &)
virtual void SetRange (const TULongPair & from, const TULongPair & to)
virtual void SetRange (const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

Sets the range to be the single coordinate.
Sets the range to be the rectangular area circumscribed by from and to.
Sets the range to be the same as the input range.

Calling Context:

Called to set the range to a single coordinate.
Called to set the range to a rectangular region.
Called to copy another region.

Parameters:

const TULongPair & -A coordinate that makes up the whole range.
const TULongPair & from -The top-left corner of a rectangular area.
const TULongPair & to -The bottom-right corner of the rectangular area to be included in the region.
const TPrimitiveRegion & -A region to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::SetRangeEmpty

virtual void SetRangeEmpty ()

Interface Category:

API.

Purpose:

Sets the range to be empty (containing no elements).

Calling Context:

Called to set a range to be empty.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::SetRangeFull

virtual void SetRangeFull ()

Interface Category:

API.

Purpose:

Sets the region to be completely full, containing all the elements it can hold.

Calling Context:

Called to set a range to be full.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Union

virtual void Union (const TULongPair &)
virtual void Union (const TULongPair & from, const TULongPair & to)
virtual void Union (const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

Adds the coordinate to the set of elements in the region.
Adds the area circumscribed by from and to.
Adds the area designated by the region argument.

Calling Context:

Called to add coordinates to the region.
Called to add rectangles to the region.
Called to add other regions to the region.

Parameters:

const TULongPair & -The coordinate to add to the region.
const TULongPair & from -The top-left corner of the region to add.
const TULongPair & to -The bottom-right corner of the region to add.
const TPrimitiveRegion & -The region to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Intersection

virtual void Intersection (const TULongPair &)
virtual void Intersection (const TULongPair & from, const TULongPair & to)
virtual void Intersection (const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

Only the coordinate given remains in the set, if it is already in the set. Otherwise, it is set to empty.
Intersects the rectangular area circumscribed by from and to with the region.
Intersects the provided region with the region.

Calling Context:

Called to intersect with a coordinate.
Called to intersect with a rectangle.
Called to intersect with another region.

Parameters:

const TULongPair & -The coordinate of the region to intersect.
const TULongPair & from -The top-left corner of the region to intersect.
const TULongPair & to -The bottom-right corner of the region to intersect.
const TPrimitiveRegion & -The region to intersect with.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Difference

virtual void Difference (const TULongPair &)
virtual void Difference (const TULongPair & from, const TULongPair & to)
virtual void Difference (const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

Removes the coordinate from the region.
Removes the area circumscribed by from and to from the region.
Removes the provided region from the region.

Calling Context:

Called to subtract a coordinate.
Called to subtract a rectangle.
Called to subtract another region.

Parameters:

const TULongPair & -The coordinate to subtract from the region.
const TULongPair & from -The top-left corner of the rectangle to subtract.
const TULongPair & to -The bottom-right corner of the rectangle to subtract.
const TPrimitiveRegion & -The region to subtract.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::ExclusiveOr

virtual void ExclusiveOr (const TULongPair &)
virtual void ExclusiveOr (const TULongPair & from, const TULongPair & to)
virtual void ExclusiveOr (const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

If the given coordinate is in the region, it is removed, otherwise it is added.
Those elements between from and to that are not in the range are added to the range, otherwise they are removed.
Those elements of the input range that are not already in the range are added to the range, otherwise they are removed.

Calling Context:

Called to exclusive OR a coordinate.
Called to exclusive OR a rectangle.
Called to exclusive OR another region.

Parameters:

const TULongPair & -The coordinate to exclusive OR.
const TULongPair & from -The top-left corner of the rectangle to exclusive OR.
const TULongPair & to -The bottom-right corner of the rectangle to exclusive OR.
const TPrimitiveRegion & -Another region to exclusive OR with.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Not

virtual void Not ()

Interface Category:

API.

Purpose:

Takes items within the region and places them outside. Places items outside the region inside.

Calling Context:

Called to invert a region.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::operator=

TPrimitiveRegion & operator =(const TPrimitiveRegion &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPrimitiveRegion & -The region to assign from.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to obtain a hash value.

Parameters:

Takes no parameters.

Return Value:

Returns a hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::IsEqual

virtual bool IsEqual (const MCollectible *) const

Interface Category:

API.

Purpose:

Compares two objects for equality.

Calling Context:

Called to compare compatible objects.

Parameters:

const MCollectible * -The object to compare with this object.

Return Value:

Returns true if the object is equal to this object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::MapCount

virtual unsigned long MapCount (const TULongPair & pt, EMap map =kLeftToRight) const

Interface Category:

API.

Purpose:

A special purpose function that counts the number of points or locations in a region along a line from a specified edge to a specified point. This function counts the number of region intersections that occur while going along a line from the specified edge to the point in question and returns that count. The net effect of this function is to map a point in an arbitrary region into a fully populated region, that is, from region space into a grid space. This is an onto mapping but not always one to one. The utility of this function is to count objects in a region along various paths or sections, which has special uses when items in a region represent discrete objects such as items in a set.

Calling Context:

Called to obtain the count of items along a path inside the region.

Parameters:

const TULongPair & pt -The point in the region to count toward.
EMap map =kLeftToRight -The path direction from the necessary edge to read the point.

Return Value:

Returns the count of items in the region that are intersected along the path specified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPrimitiveRegion::MapPoint

virtual bool MapPoint (TULongPair &, EMap map =kLeftToRight) const

Interface Category:

API.

Purpose:

A special purpose function that maps a point from grid space into region space. Because the mapping might not exist at all points for all regions, the function returns true if it was able to find a suitable mapping or false if not. The mapping produced by this function is not one-to-one and not onto. The result of the mapping, if it exists, is returned in the input specified when the MapPoint function is called. This function is utilized for ignoring open spaces in a sparse region, when the region represents discrete items such as objects in a set.

Calling Context:

Called to find a point that traverses the specified number of region items along the path indicated.

Parameters:

TULongPair & -The specified number of region items required to satisfy the mapping and also the resultant point that satisfies these requirements (if they can be satisfied).
EMap map =kLeftToRight -The path direction from the necessary edge to reach the point specified.

Return Value:

Returns true if the mapping exists, in which case, the TULongPair passed in is changed to reflect where the mapping maps to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.