Class: TStandardPageRange

Declaration: HighLevelPrint.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPageRange

Inherited By:

None.

Purpose:

TPageRange, from which this class derives, is an abstract base class whose interface describes general page ranges. Conceptually, a page range is a set or collection of numbers that represent pages of a document. The page range specifies which pages in the document are selected, usually for printing. For a given linear page number (beginning with 0), the page range tells if that page is within the range. It returns a value of true if so, false otherwise. A TStandardPageRange is a specific derived class that is completely general in the sense that it can literally represent almost any page range. Page ranges within a standard page range object do not need to be continuous, that is, they do not need to be in a single group. They act more like traditional sets where any page number can be added to or removed from the set independent of any other page number. The total number of pages in a page range cannot exceed TPageRange::kPageCountLimit and the last numbered page cannot be above TPageRange::kLastPageNumber. (These are usually close to the largest unsigned number that can be represented on any given platform.) The constant TPageRange::kPageCountLimit gives the absolute total number of pages a page range can contain for any implementation and the constant TPageRange::kLastPageNumber gives the ordinal page number of that page. The disjoint complexity of a TStandardPageRange is not without its limits. If the number of discontinuities in a standard page range becomes too excessive, the standard page range implementation is unable to represent the range of pages and will throw an exception (TPrimitiveRegionException::kTooComplex). Depending on the implementation, the number of discontinuities allowed is on the order of about 30,000. As TStandardPageRange is described in terms of set semantics, it also obeys many standard set operations such as Union, Intersection, and ExclusiveOr.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is pretty much a stand-alone class and need not be overridden except to change some specific behavior.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardPageRange::TStandardPageRange

TStandardPageRange ()
TStandardPageRange (unsigned long from, unsigned long to)
TStandardPageRange (const TStandardPageRange &)
TStandardPageRange (const TPageRange &)

Interface Category:

API.

Purpose:

Default constructor. Used for streaming or to construct a valid full page range.
Creates a standard page range that includes all pages between from and to, inclusive.
Copy constructor. Copies peer objects.
Performs a well-defined slicing of any TPageRange object. That is, it creates a TStandardPageRange representation of any other TPageRange object independent of its internal format. Depending on the complexity of the target page range and the number of pages in the range, this constructor could exceed the complexity limitation of TStandardPageRange for some ranges. Beware!

Calling Context:

Called by the stream-in operators and to obtain a full page range.
Called to create a page range initially set to a continuous subrange.
Called to copy an object.
Called to create a page range that, within TStandardPageRange, is polymorphically equivalent to the page range being copied.

Parameters:

Takes no parameters.
unsigned long from -The first page of a sequence of pages to be included in the new range. Subsequence pages are taken in sequence until the end of the sequence specified by the parameter, to.
unsigned long to -The last page in a sequence of pages to be included in the new range. This page ends the sequence begun by the previous parameter, from.
const TStandardPageRange & -The page range to copy.
const TPageRange & -The page range object is polymorphically copied, but only the information relevant to TStandardPageRange is sliced from the object to be used in construction.

Return Value:

None.

Exceptions:

Throws TPrimitiveRegionException::kTooComplex or TPrimitiveRegionException::kNoResources when the region becomes too complex to represent or runs out of memory resources. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Because this is a general class that can represent almost any other page range, constructing it from other page ranges with many thousands of pages could potentially exhaust resources and time. When copying another page range it is best to have the total number of pages as small as possible or to intersect the copied page range with a small number of pages in this object after it is constructed. This is particularly true of constructing from a TOddPageRange or TEvenPageRange.

Member Function: TStandardPageRange::~TStandardPageRange

virtual ~ TStandardPageRange ()

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: TStandardPageRange::SetRange

void SetRange (unsigned long from, unsigned long to)
void SetRange (const TPageRange &)

Interface Category:

API.

Purpose:

Sets the range to include all pages between from and to, inclusive.
Sets the range to include the same pages as in the supplied page range. Beware: this call can be expensive.

Calling Context:

Called directly to set the page range to a specific continuous sub page range.
Called directly to set the page range to be equivalent to another page range.

Parameters:

unsigned long from -The beginning page number of the subsequence to include in the range.
unsigned long to -The ending page number of the subsequence to include in the range.
const TPageRange & -The page range to copy.

Return Value:

None.

Exceptions:

Throws TPrimitiveRegionException::kTooComplex or TPrimitiveRegionException::kNoResources if the region becomes too complex to represent or runs out of memory resources. Passes all other exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Because this is a general class that can represent almost any other page range, setting the range from other page ranges with many thousands of pages could potentially exhaust resources and time. When copying another page range it is best to have its total number of pages as small as possible, or, if it is not possible, to first set this range to some small number of pages and then intersect it with the range to be copied. This is particularly true when setting odd or even pages from a TOddPageRange or TEvenPageRange.

Member Function: TStandardPageRange::Union

void Union (unsigned long from, unsigned long to)
void Union (const TPageRange &)

Interface Category:

API.

Purpose:

Adds all pages between from and to, inclusive, to the range.
Adds all pages in the supplied page range to this page range.

Calling Context:

Called directly to add pages to a page range.
Called directly to combine another page range with this page range.

Parameters:

unsigned long from -The beginning page number of subsequence to add to the present range.
unsigned long to -The ending page number of the subsequence to add to the present range.
const TPageRange & -Another range to add to the current page range.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::Intersection

void Intersection (unsigned long from, unsigned long to)
void Intersection (const TPageRange &)

Interface Category:

API.

Purpose:

Removes any pages that are not between from and to, inclusive.
Removes any pages that are not in both this and the supplied page range.

Calling Context:

Called directly to intersect another set of pages with this page range.
Called directly to intersect another page range with this page range.

Parameters:

unsigned long from -The beginning page number of the page sequence to intersect with the current range.
unsigned long to -The ending page number of the page sequence to intersect with the current page range.
const TPageRange & -The page range whose contents will intersected with the current page range.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::Difference

void Difference (unsigned long from, unsigned long to)
void Difference (const TPageRange &)

Interface Category:

API.

Purpose:

Removes all pages between from and to, inclusive.
Removes all pages from this object that are in the supplied page range.

Calling Context:

Called directly to remove pages from a page range.
Called directly to remove pages of another page range from this page range.

Parameters:

unsigned long from -The beginning page number of the page sequence to remove from the current range.
unsigned long to -The ending page number of the page sequence to remove from the current page range.
const TPageRange & -The page range whose contents will be removed from the page range if they exist.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::ExclusiveOr

void ExclusiveOr (unsigned long from, unsigned long to)
void ExclusiveOr (const TPageRange &)

Interface Category:

API.

Purpose:

Adds pages between from and to, inclusive, unless they are already in the range, in which case they are removed.
Adds any pages that are in the supplied page range but not in this page range. Removes pages that are in both.

Calling Context:

Called directly to select pages in either the page range or the supplied range, but not both.
Called directly to select pages that are in one or the other page range, but not both.

Parameters:

unsigned long from -The beginning page number of the page sequence to ExclusiveOr with the current page range.
unsigned long to -The ending page number of the page sequence to ExclusiveOr with the current page range.
const TPageRange & -A page range to be ExclusiveOred with the current page range.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::Not

void Not ()

Interface Category:

API.

Purpose:

Adds any pages that are not currently in the range and removes any that are currently in it.

Calling Context:

Called directly to invert the selection of pages.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::SetRangeEmpty

void SetRangeEmpty ()

Interface Category:

API.

Purpose:

Removes all pages from the range.

Calling Context:

Called directly to empty the page range.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::SetRangeFull

void SetRangeFull ()

Interface Category:

API.

Purpose:

Adds all pages to the range. The total number of pages in the range after this operation is implementation dependent, that is, platform dependent. The total number of pages a page range can contain can be determined by setting the range to full and then calling GetPageCountInRange. This value should be the same as TPageRange::kPageCountLimit.

Calling Context:

Called directly to fill a page range to its limit or to select all possible pages.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Returns true if there are no pages in the range.

Calling Context:

Called directly to quickly determine if a page range is empty.

Parameters:

Takes no parameters.

Return Value:

Returns true if the range contains no selected pages, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::IsFull

virtual bool IsFull () const

Interface Category:

API.

Purpose:

Returns true if no more pages can be added to the range. The number of pages in the range is equal to TPageRange::kPageCountLimit.

Calling Context:

Called directly to quickly determine if a page range is full.

Parameters:

Takes no parameters.

Return Value:

Returns true if no more pages can be added to the selection that aren't already part of the range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::IsPageInRange

virtual bool IsPageInRange (unsigned long pageNumber) const

Interface Category:

API.

Purpose:

Determines if the page specified by pageNumber is in the range.

Calling Context:

Called directly to determine if a specific page number is within the range.

Parameters:

unsigned long pageNumber -The page number to check if it is in the range.

Return Value:

Returns true if the page number is in the page range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::IsNthPageInRange

virtual bool IsNthPageInRange (unsigned long & pageNumber) const

Interface Category:

API.

Purpose:

Counting only pages that are in the range, this function returns true if there are at least pageNumber -1 pages in the range and it gives back the actual page number that it represents. It returns false if there are no pages or less than pageNumber -1 pages in the range. If false is returned, the value of pageNumber is not valid.

Calling Context:

Called directly to determine if there are a specified number of pages in the range, and, if there are, to return the actual page number of that page.

Parameters:

unsigned long & pageNumber -This is the Nth page number expected to be in the range. If this number, counting only pages in the range, is in the range, the parameter is changed to be the actual page number.

Return Value:

Returns true if the Nth page in the range exists.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::GetPageCountInRange

virtual unsigned long GetPageCountInRange () const

Interface Category:

API.

Purpose:

Calculates the total number of pages in the range.

Calling Context:

Called directly to acquire the total number of pages in a range.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of pages within the range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::GetFirstPageInRange

virtual unsigned long GetFirstPageInRange () const

Interface Category:

API.

Purpose:

Returns the first page in the range. If there are no pages in the range (the range is empty), then the result is undefined.

Calling Context:

Called directly to get the page number of the first page within the range.

Parameters:

Takes no parameters.

Return Value:

Returns the page number of the first page within the range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If IsEmpty is true, GetFirstPageInRange still returns a value.

Member Function: TStandardPageRange::GetLastPageInRange

virtual unsigned long GetLastPageInRange () const

Interface Category:

API.

Purpose:

Returns the last page in the range. If there are no pages in the range (the range is empty), then the result is undefined.

Calling Context:

Called directly to acquire the page number of the last page within the range.

Parameters:

Takes no parameters.

Return Value:

Returns the page number of the last page within the range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If there are no pages in the range (the range is empty), then the result is undefined. IsEmpty tells whether or not there are pages in the range.

Member Function: TStandardPageRange::operator=

TStandardPageRange & operator =(const TStandardPageRange &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object. May be called directly.

Parameters:

const TStandardPageRange & -The page range from which to assign.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called directly and by the collection framework when placed in a collection.

Parameters:

Takes no parameters.

Return Value:

A hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageRange::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly 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: TStandardPageRange::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly 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.

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