Class: TSimpleGrid

Declaration: PrintPrimitives.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

Consider a geometric plane in the first quadrant whose coordinates are represented by TULongPairs. Such an array is called a simple unsigned long grid. A TSimpleGrid does not contain anything, but it can be used to represent or address things such as pages, that can be arranged in a grid or 2-D array. The third item over in the seventh row would have coordinate, or address (3,7), where the coordinate is a TULongPair and numbering begins at (0,0) rather than (1,1). The 0th item in the 0th row would have coordinate (0,0). The TSimpleGrid is a class that helps facilitate building and addressing grid structures. A TSimpleGrid has the ability to add or subtract rows and columns as necessary, to get and set the size of the grid array, to count the number of items in the array, and to test whether a particular coordinate is within the array.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TSimpleGrid is not intended as a base class for deriving classes. However, it is implemented so that classes could be derived from it to override some of its basic functionality. It is, by itself, a fully usable class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TSimpleGrid::TSimpleGrid

  1. TSimpleGrid ()
  2. TSimpleGrid (const TULongPair &)
  3. TSimpleGrid (const TSimpleGrid &)

Interface Category:

API.

Purpose:

  1. Default constructor. Defaults to 1x1 grid.
  2. Sets the grid to the size specified by TULongPair.
  3. Copy constructor.

Calling Context:

  1. Called by the stream-in operators and clients.
  2. Called by clients to create a grid object.
  3. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Whenever a grid is constructed or modified, its area is bounded by 1 and ULONG_MAX -1. This behavior is enforced by the class.

Member Function: TSimpleGrid::~TSimpleGrid

virtual ~ TSimpleGrid ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::CreateGridIterator

virtual TGridIterator * CreateGridIterator () const

Interface Category:

API.

Purpose:

Creates an iterator that can be used to iterate over items in the grid.

Calling Context:

Called to create a grid iterator.

Parameters:

Return Value:

Returns a newly created iterator for the grid. The client is responsible for its storage.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::SetGridSize

virtual void SetGridSize (const TULongPair &)

Interface Category:

API.

Purpose:

Sets the size of the grid as specified.

Calling Context:

Called to set the size of the grid.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::GetGridSize

virtual TULongPair GetGridSize () const

Interface Category:

API.

Purpose:

Returns the size of the grid.

Calling Context:

Called to get the size of the grid.

Parameters:

Return Value:

Returns the size of the grid as a TULongPair.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::AddRow

virtual void AddRow ()

Interface Category:

API.

Purpose:

Adds a row of items to the grid matrix.

Calling Context:

Called to add a row to the grid. This invalidates any iterators.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Does not add a row if the number of rows is equal to ULONG_MAX. The total area of the grid is restricted to ULONG_MAX -1.

Member Function: TSimpleGrid::SubtractRow

virtual void SubtractRow ()

Interface Category:

API.

Purpose:

Subtracts a row of elements from the grid matrix.

Calling Context:

Called to subtract a row from the grid.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Does not subtract a row if the number of rows is equal to 1. The total area of the grid is restricted to ULONG_MAX -1.

Member Function: TSimpleGrid::AddColumn

virtual void AddColumn ()

Interface Category:

API.

Purpose:

Adds a column of elements to the grid matrix.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Does not add a column if the number of columns is equal to ULONG_MAX. The total area of the grid is restricted to ULONG_MAX -1.

Member Function: TSimpleGrid::SubtractColumn

virtual void SubtractColumn ()

Interface Category:

API.

Purpose:

Subtracts a column of elements from the grid matrix.

Calling Context:

Called to subtract a column.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Does not subtract a column if the number of columns is equal to 1. The total area of the grid is restricted to ULONG_MAX -1.

Member Function: TSimpleGrid::GetItemCount

unsigned long GetItemCount () const

Interface Category:

API.

Purpose:

Returns the number of items in the grid.

Calling Context:

Called to get a count of items in the grid.

Parameters:

Return Value:

Returns the number of items in the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::Contains

  1. bool Contains (unsigned long) const
  2. bool Contains (const TULongPair &) const

Interface Category:

API.

Purpose:

  1. Determines if the item number is within the grid.
  2. Determines if the item coordinate is within the grid.

Calling Context:

  1. Called directly to test whether a given item is within the grid.
  2. Called directly to test whether a given item is within the grid.

Parameters:

Return Value:

Returns true if the given item is within the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::Validate

  1. bool Validate (unsigned long & item) const
  2. bool Validate (TULongPair & coordinate) const

Interface Category:

API.

Purpose:

  1. Determines if the item number is within the grid and forces the item to be in the grid.
  2. Determines if the item coordinate is within the grid and forces the coordinate to be in the grid.

Calling Context:

  1. Called to test whether a given item is within the grid and to force it to be in the grid.
  2. Called to test whether a given item is within the grid and to force it to be in the grid.

Parameters:

Return Value:

Returns true if the given item is within the grid.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Out-of-bounds items are arbitrarily placed back in the grid.

Member Function: TSimpleGrid::operator=

TSimpleGrid & operator =(const TSimpleGrid &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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: TSimpleGrid::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called to obtain a hash value.

Parameters:

Return Value:

Returns the hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSimpleGrid::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: TSimpleGrid::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.