Class: TTieredTextBuffer

Declaration: TieredTextBuffer.h

Taxonomy Categories:

Member Functions:

Interface Category:

Developer Tool Programmer Interface.

Inherits From:

MCollectible

Inherited By:

TChunkyTieredTextBuffer

Purpose:

Objects of the class TTieredTextBuffer act like C++ ostream objects. They support operator<< for all built-in types and for some basic Taligent types. Most clients will use objects of this class simply to output textual information to the console.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive TTieredTextBuffer. Use TTieredTextBuffer directly.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTieredTextBuffer::TTieredTextBuffer

TTieredTextBuffer ()
TTieredTextBuffer (const TTieredTextBuffer &)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
const TTieredTextBuffer & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::operator=

TTieredTextBuffer & operator =(const TTieredTextBuffer &)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTieredTextBuffer & -The right-hand side object.

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: TTieredTextBuffer::~TTieredTextBuffer

virtual ~ TTieredTextBuffer ()

Interface Category:

Developer Tool Programmer Interface.

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

virtual long Hash () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the hash value for this instance of TTieredTextBuffer.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value for this instance of TTieredTextBuffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::operator<<=

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

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & source -The stream the object is streamed 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: TTieredTextBuffer::operator>>=

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

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & destination -The stream the object is streamed 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: TTieredTextBuffer::operator<<

virtual TTieredTextBuffer & operator << (const double)
virtual TTieredTextBuffer & operator << (const float)
virtual TTieredTextBuffer & operator << (const long)
virtual TTieredTextBuffer & operator << (const int)
virtual TTieredTextBuffer & operator << (const short)
virtual TTieredTextBuffer & operator << (const signed char)
virtual TTieredTextBuffer & operator << (const unsigned long)
virtual TTieredTextBuffer & operator << (const unsigned short)
virtual TTieredTextBuffer & operator << (const unsigned int)
virtual TTieredTextBuffer & operator << (const unsigned char)
virtual TTieredTextBuffer & operator << (const char)
virtual TTieredTextBuffer & operator << (const char *)
virtual TTieredTextBuffer & operator << (const TText &)
virtual TTieredTextBuffer & operator << (const TToken &)
virtual TTieredTextBuffer & operator << (const TTieredText &)
virtual TTieredTextBuffer & operator << (const void *)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

C++ ostream-style text streaming for double.
C++ ostream-style text streaming for float.
C++ ostream-style text streaming for long.
C++ ostream-style text streaming for int.
C++ ostream-style text streaming for short.
C++ ostream-style text streaming for signed char.
C++ ostream-style text streaming for unsigned long.
C++ ostream-style text streaming for unsigned short.
C++ ostream-style text streaming for unsigned int.
C++ ostream-style text streaming for unsigned char.
C++ ostream-style text streaming for char.
C++ ostream-style text streaming for char *.
C++ ostream-style text streaming for TText&.
C++ ostream-style text streaming for TToken&.
C++ ostream-style text streaming for TTieredText&.
C++ ostream-style text streaming for void *.

Calling Context:

Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

const double -The double value.
const float -The float value.
const long -A long value.
const int -The int value.
const short -The short value.
const signed char -The signed char value.
const unsigned long -The unsigned long value.
const unsigned short -The unsigned short value.
const unsigned int -The unsigned int value.
const unsigned char -The unsigned char value.
const char -The char value.
const char * -The char pointer.
const TText & -A reference to the TText value.
const TToken & -A reference to the TToken value.
const TTieredText & -A reference to the TTieredText value.
const void * -A void pointer.

Return Value:

Returns this instance of TTieredTextBuffer.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetIndent

unsigned short SetIndent (unsigned short)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the indent level for subsequent output via the operator<< function. If the given indent is zero, text is flushed left. Indentation only affects text that is added to this object via one of the << operators.

Calling Context:

Call this function directly.

Parameters:

unsigned short -The indent level.

Return Value:

Returns the original indent level.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetIndent

unsigned short GetIndent () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the indentation level previously set by SetIndent.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the indentation level previously set by SetIndent.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::PushTier

void PushTier (TTieredText :: ETier newTier)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Pushes the new tier onto an internal stack of ETiers and makes it the new tier by calling SetTier.

Calling Context:

Call this function directly.

Parameters:

TTieredText :: ETier newTier -The new tier to push on the stack.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::PopTier

TTieredText::ETier PopTier()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Pops the tier at the top of the stack, as previously pushed on by PushTier, and returns it. The tier is set to the value it had before the last call to PushTier.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the tier popped off from the top of the stack.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetTier

TTieredText :: ETier SetTier (TTieredText :: ETier newTier)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Changes the tier of all subsequently streamed text to newTier. It only affects future calls to operator<<. SetTier pins newTier to the range kTop...kBottom.

Calling Context:

Call this function directly.

Parameters:

TTieredText :: ETier newTier -The tier level.

Return Value:

The new tier level.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetTier

TTieredText::ETier GetTier() const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the tier of this object as previously set by SetTier.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the tier of this object as previously set by SetTier.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetMinFractionDigits

void SetMinFractionDigits (unsigned short digits)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the minimum number of fraction digits displayed when the operator<< function is called for floating-point values.

Calling Context:

Call this function directly.

Parameters:

unsigned short digits -The minimum number of fraction digits.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetMaxFractionDigits

void SetMaxFractionDigits (unsigned short digits)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the maximum number of fraction digits displayed when the operator<< function is called for floating-point values.

Calling Context:

Call this function directly.

Parameters:

unsigned short digits -The maximum number of fraction digits.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetBase

void SetBase (unsigned short)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Alters the radix or base in which numbers are displayed. The default base is 10.

Calling Context:

Call this function directly.

Parameters:

unsigned short -The base value to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetBase

unsigned short GetBase ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the current base.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetSignificantDigits

void SetSignificantDigits (unsigned short digits)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the number of digits that are shown for numeric values.

Calling Context:

Call this function directly.

Parameters:

unsigned short digits -The number of digits that are shown for numeric values.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetSignificantDigits

unsigned short GetSignificantDigits () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Gets the number of digits that are shown for numeric values.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the number of digits that are shown for numeric values.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetTextSaving

void SetTextSaving (bool saveText)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets a flag indicating whether text is saved in the object for later retrieval.

Calling Context:

Call this function directly.

Parameters:

bool saveText -A flag indicating whether text is saved in the object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetTextSaving

bool GetTextSaving () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Gets a flag indicating whether text is saved in the object for later retrieval.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if text is saved in the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetFileNameOfSavedBufferData

void GetFileNameOfSavedBufferData (TText & name) const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the name of a file used to store back-up data.

Calling Context:

Call this member function directly.

Parameters:

TText & name -Contains the file name being returned.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetFileNameOfSavedBufferData

void SetFileNameOfSavedBufferData (TText & name)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the desired name of a file used to store back up data.

Calling Context:

Call this member function directly. However, this member function is normally called in conjunction with SetFileNameOfSavedBufferData() to set the file name of the back up file. If no file name is given, a default will will be used. Default is TextBuffer<number> where number is some long value.

Parameters:

TText & name -Contains the desired name.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::IsSaveBufferedData

bool IsSaveBufferedData () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns true if back-up is turned on; else false.

Calling Context:

Call this member function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if SetSaveBufferedData() had been called with true.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetSaveBufferedData

void SetSaveBufferedData (bool saveData =true)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Turns on saving of data into a back-up file if the parameter is true.

Calling Context:

Parameters:

bool saveData =true -Turn on back-up of stored data.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::SetEchoTier

void SetEchoTier (TTieredText :: ETier)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the tier level at which echoing occurs.

Calling Context:

Called by RunTest and directly.

Parameters:

TTieredText :: ETier -The tier level.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::GetEchoTier

TTieredText::ETier GetEchoTier () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns the tier level at which echoing occurs.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the tier level at which echoing occurs.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::AdoptOutputStream

void AdoptOutputStream (TStream *)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the output destination to the given output stream.

Calling Context:

Call this function directly.

Parameters:

TStream * -The output stream.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

After the call to AdoptOutputStream, this object owns the output stream and deletes it.

Member Function: TTieredTextBuffer::GetOutputStream

TStream * GetOutputStream () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Gets the output stream previously set by AdoptOutputStream, or zero if no output stream has been set.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the output stream if set. Otherwise, zero is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller must not delete the copy that is returned.

Member Function: TTieredTextBuffer::OrphanOutputStream

TStream * OrphanOutputStream ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns a pointer to the output stream previously set by AdoptOutputStream, or zero if no output stream has been set.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the output stream if set. Otherwise, zero is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The caller owns the object that is returned and is responsible for deleting it.

Member Function: TTieredTextBuffer::AdoptEchoStream

void AdoptEchoStream (TStream *)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Sets the echo stream to the given stream.

Calling Context:

Call this function directly.

Parameters:

TStream * -The echo stream.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

After the call to AdoptEchoStream, this object owns the echo stream and deletes it.

Member Function: TTieredTextBuffer::GetEchoStream

TStream * GetEchoStream () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns a pointer to the echo stream previously set by AdoptEchoStream.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the echo stream previously set by AdoptEchoStream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Caller must not delete the copy that is returned.

Member Function: TTieredTextBuffer::OrphanEchoStream

TStream * OrphanEchoStream ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns a pointer to the echo stream previously set by AdoptEchoStream.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the echo stream previously set by AdoptEchoStream.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Caller owns the object that is returned and is responsible for deleting it.

Member Function: TTieredTextBuffer::Append

void Append (const TTieredText &)
void Append (const TTieredTextBuffer &)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Adds a copy of the text to the end of the collection of output generated so far.
Adds a copy of the text in the tiered text buffer to the end of the collection of output generated so far.

Calling Context:

Called by Test Framework and directly.
Called by Test Framework and directly.

Parameters:

const TTieredText & -The tiered text.
const TTieredTextBuffer & -The buffer of the tiered text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If the tier of the text is higher than the current echo tier, the text is also streamed to the echo destination stream, or if none is set, to QPrintText. The text is also streamed to the output destination stream if one has been set.

Member Function: TTieredTextBuffer::Flush

void Flush (TTieredText :: ETier keepOnly =TTieredText :: kNormal)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Deletes all text from this object's collection that falls below the given tier.

Calling Context:

Called by Test Framework and directly.

Parameters:

TTieredText :: ETier keepOnly =TTieredText :: kNormal -The tier.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::Clear

void Clear ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Deletes all text from this object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTieredTextBuffer::CreateNewIterator

TIteratorOver < TTieredText > * CreateNewIterator () const

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Returns an iterator that clients can use to access the TTieredText objects which have been appended to this object so far.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an iterator that clients can use to access the TTieredText objects that have been appended to this object so far.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Do not delete the objects returned by the iterator.

Member Function: TTieredTextBuffer::Backup

virtual void Backup (TTieredText * data)

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Used by class to back up data internally when back-up is turned on by user.

Calling Context:

Protected interface. Used by class to back up data. Derived classes can override this member function if desired to write data into different medium.

Parameters:

TTieredText * data -The data to write to the back up file.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Data is stored into a disk file and file is not deleted automatically.

Member Function: TTieredTextBuffer::CreateBackupLog

virtual void CreateBackupLog ()

Interface Category:

Developer Tool Programmer Interface.

Purpose:

Used by class to create a back up log for storing buffered data whenever clients of class turn on back-up.

Calling Context:

Protected interface used only by this class. Derived classes can override this member function to create log file of other types. Note that if this member function changes the log file type, derived class will also have to change the Backup(TTieredText*) member function to accept and use the appropriate data type.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Back-up file is not deleted automatically. If an existing file is used, data will simply be added to existing file instead of overwriting its content.

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