LString

LString is a PowerPlant class that is used for manipulating text strings.

Methods :

The methods in this class are:

LString()	Append (TypeParameters )
AppendPStr()	Assign(TypeParameters)
BeginsWith(TypeParameters)	CStringLength()
CompareBytes()	CompareIgnoringCase()
CompareTo()	CopyPStr()
EndsWith()	Find()
FindWithin()	FourCharCodeToPStr()
Insert()	Length()
LoadFromPtr()	LoadFromSTRListResource()
LoadFromStringPtr()	PStrToFourCharCode()
Remove()	Replace()
ReverseFind()	SetCompareFunc()
ToolboxCompareText()	operator += (TypeParameter)
operator = (TypeParameter)	operator ()(unsigned char,unsigned char) const
operator [ ](unsigned char) const	operator [ ](unsigned char)
operator const unsigned char*() const	operator long double() const
operator long() const	operator unsigned char*()
operator unsigned long() const

Data Members:

The data members in this class are:

mStringPtr	mCompareFunc
mMaxBytes

Operation:

This class implements string functionality for Pascal-style strings. It serves as a base class for LStr255 and TString.

Source files:

(Support Classes)

LString.h

LString.cp

LString()

Purpose:

This is a constructor to create a string from a max length and a string pointer. Subclasses must call this "protected" constructor to specify the maximum string size (including the length byte) and a pointer to the storage for the string

Access:

Public

Prototype:

LString();

None

Append (TypeParameters )

Purpose:

These overloaded methods append characters to the end of this String.

Access:

Public

Prototype:

LString& Append( const void* inPtr, UInt8 inLength 
);

LString& Append( SInt32 inNumber );

LString& Append( char inChar );

LString& Append( UInt8 inChar );

LString& Append( ConstStringPtr inStringPtr );

LString& Append( const LString& inString );

The parameters for these methods are:

const void*	inPtr	A pointer to the string to append.
SInt32	inNumber	The number to append to the string.
char	inChar	The character to append to the string.
UInt8	inChar	The character to append to the string.
ConstStringPtr	inStringPtr	The string to append to the string.
const LString&	inString	The LString to append to the string.
UInt8	inLength	The length of the string to append.

Return:

A reference to an LString that has the appended string.

AppendPStr()

Purpose:

Append a Pascal string to this String.

Access:

Static, Public

Prototype:

static StringPtr AppendPStr( Str255 ioBaseString,

ConstStringPtr inAppendString,

SInt16 inDestSize );

The parameters for these methods are:

Str255	ioBaseString	A pointer to the string to append to.
ConstStringPtr	inAppendString	The string to append.
SInt16	inDestSize	The size of the buffer.

Return:

A pointer to the finished String.

Assign(TypeParameters)

Purpose:

Assign a value to the string.

Access:

Public

Prototype:

LString& Assign(FourCharCode inCode);

LString& Assign(double_t inNumber,

SInt8 inStyle,SInt16 inDigits);

LString& Assign( SInt32 inNumber);

LString& Assign(ResIDT inResID,SInt16 inIndex);

LString& Assign( Handle inHandle);

LString& Assign(const void* inPtr,UInt8 inLength);

LString& Assign( const char* inCString);

LString& Assign( char inChar);

LString& Assign( UInt8 inChar);

LString& Assign( ConstStringPtr inStringPtr);

LString& Assign(const LString& inString,

UInt8 inStartPos,UInt8 inCount);

The parameters for this method are:

FourCharCode	inCode	A four characters in a FourCharCode to assign.
double_t	inNumber	The number to assign to the string.
SInt8	inStyle	The style to use, must be FLOATDECIMAL or FIXEDDECIMAL.
SInt16	inDigits	For FLOATDECIMAL, inDigits is the number of significant digits (should be > 0). For FIXEDDECIMAL, inDigits is the number of digits to the right of the decimal point.
SInt32	inNumber	The number to assign to the string.
ResIDT	inResID	The LString to append to the string.
SInt16	inIndex	The length of the string to append.
Handle	inHandle	The handle to the string to assign.
const void*	inPtr	The pointer to the string to assign.
UInt8	inLength	The length of the string.
const char*	inCString	The pointer to the "C" string to assign.
char	inChar	The character to assign to the string.
UInt8	inChar	The character to assign to the string.
ConstStringPtr	inStringPtr	The pointer to the string to assign.
const LString&	inString	The pointer to the string to assign.
UInt8	inStartPos	The starting index in the string to assign from.
UInt8	inCount	The character count to put in the string.

Return:

A reference to the finished LString.

BeginsWith(TypeParameters)

Purpose:

Indicate whether this String begins with a specified String.

Access:

Public

Prototype:

Boolean BeginsWith( const void* inPtr, 

UInt8 inLength ) const;

Boolean BeginsWith( UInt8 inChar) const;

Boolean BeginsWith( 

ConstStringPtr inStringPtr) const;

Boolean BeginsWith( const LString& inString) 
const;

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to check for.
UInt8	inChar	The character to check for at the beginning of the string.
ConstStringPtr	inStringPtr	The pointer to the string to check for.
const LString&	inString	The pointer to the string to check for.

Return:

A Boolean value of true if the String starts with the passed String, else false.

CStringLength()

Purpose:

Return the length of a C string, but with an upper limit of 255.

Access:

Static, Public

Prototype:

static UInt8 CStringLength(const char* inCString);

The parameters for this method are:

const char*

inCString

The pointer to the "C" string to assign.

Return:

The length of the string (number of characters in it).

CompareBytes()

Purpose:

Simple byte-by-byte value comparison of two strings.

Access:

Static, Public

Prototype:

static SInt16 CompareBytes(

const void* inLeft,

const void* inRight,

UInt8 inLeftLength,

UInt8 inRightLength );

The parameters for this method are:

const void*	inLeft	The first string.
const void*	inRight	The second string.
UInt8	inLeftLength	The length of the first string.
UInt8	inRightLength	The length of the second string.

Return:

Return 1 of the Left String is greater, else return -1 if the Right String is greater. Equality will cause a return value of 0.

CompareIgnoringCase()

Purpose:

Case-insensitve string comparison.

Access:

Static, Public

Prototype:

static SInt16 CompareIgnoringCase(

const void* inLeft,

const void* inRight,

UInt8 inLeftLength,

UInt8 inRightLength );

The parameters for this method are:

const void*	inLeft	The first string.
const void*	inRight	The second string.
UInt8	inLeftLength	The length of the first string.
UInt8	inRightLength	The length of the second string.

Return:

Return 1 of the Left String is greater, else return -1 if the Right String is greater. Equality will cause a return value of 0.

CompareTo()

Purpose:

Compare two strings using a compare function set in mCompareFunc.

Access:

Protected

Prototype:

SInt16 CompareTo (const void* inPtr, UInt8 
inLength) 

const;

SInt16 CompareTo( UInt8 inChar) const;

SInt16 CompareTo(ConstStringPtr inStringPtr) 
const;

SInt16 CompareTo( const LString& inString) const;

The parameters for this method are:

const void*	inPtr	The string to compare with.
UInt8	inLength	The length of the string.
UInt8	inChar	The character to compare with.
ConstStringPtr	inStringPtr	The pointer to a string to compare with.
const LString&	inString	A reference to a string to compare with.

Return:

The return values are specified by the compare function you supply.

CopyPStr()

Purpose:

Copy a Pascal String into the String.

Access:

Public

Prototype:

static StringPtr CopyPStr(

ConstStringPtr inSourceString,

StringPtr outDestString,

SInt16 inDestSize );

The parameters for this method are:

SInt16	inDestSize	The length of the source buffer.
StringPtr	outDestString	The destination string.
ConstStringPtr	inStringPtr	The pointer to a string to copy.

Return:

A pointer to the String is returned.

EndsWith()

Purpose:

Return whether this String ends with a specified String.

Access:

Public

Prototype:

Boolean EndsWith( const void* inPtr,

UInt8 inLength) const;

Boolean EndsWith( UInt8 inChar) const;

Boolean EndsWith( ConstStringPtr inStringPtr) 
const;

Boolean EndsWith( const LString& inString) const;

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to check for.
UInt8	inChar	The character to check for at the beginning of the string.
ConstStringPtr	inStringPtr	The pointer to the string to check for.
const LString&	inString	The pointer to the string to check for.

Return:

A Boolean value of true if the String starts with the passed String, else false.

Find()

Purpose:

Find a substring within a String.

Access:

Public

Prototype:

UInt8 Find( const void* inPtr,

UInt8 inLength, UInt8 inStartPos ) const;

UInt8 Find( UInt8 inChar,

UInt8 inStartPos = 1 ) const;

UInt8 Find( ConstStringPtr inStringPtr, 

UInt8 inStartPos = 1 ) const;

UInt8 Find( const LString& inString, UInt8

inStartPos = 1 ) const;

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to check for.
UInt8	inStartPos	The starting position in the string to search from.
ConstStringPtr	inStringPtr	The pointer to the string to check for.

Return:

Return the index of where the substring starts within this String.

FindWithin()

Purpose:

Return the index of where this String starts within another String.

Access:

Public

Prototype:

UInt32 FindWithin( const void* inPtr,

UInt32 inLength, UInt32 inStartPos ) const;

UInt8 FindWithin(UInt8 inChar, 

UInt8 inStartPos = 1 ) const;

UInt8 FindWithin( ConstStringPtr inStringPtr, 
UInt8 

inStartPos = 1 ) const;

UInt8 FindWithin( const LString& inString, UInt8 

inStartPos = 1 ) const;

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to check for.
UInt8	inStartPos	The starting position in the string to search from.
ConstStringPtr	inStringPtr	The pointer to the string to check for.

Return:

Returns 0 if the substring is not in the String. inStartPos is the index within inPtr at which to begin searching. The default value is 1. Value 0 is not valid.

Remarks:

To find the next occurrence, set inStartPos to one plus the index returned by the last FindWithin call.

FourCharCodeToPStr()

Purpose:

Convert a four character code to a Pascal string and return a pointer to the string.

Access:

Static, Public

Prototype:

static StringPtr FourCharCodeToPStr(

FourCharCode inCode,

StringPtr outString );

The parameters for this method are:

FourCharCode	inCode	The four-character value to put in the string.
StringPtr	outString	The pointer to the string.

Return:

Returns a pointer to the string.

Remarks:

outString must point to a buffer (usually a string) that can hold the resulting string, including the length byte. Therefore, the buffer must be at least 5-bytes large. Usually, you will allocate an array of 5 unsigned char.

Insert()

Purpose:

Access:

Public

Prototype:

LString& Insert( const void* inPtr,

UInt8 inLength, UInt8 inAtIndex);

LString& Insert( UInt8 inChar, UInt8 inAtIndex);

LString& Insert( ConstStringPtr inStringPtr, UInt8 

inAtIndex);

LString& Insert( const LString& inString, UInt8 

inAtIndex);

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to insert.
UInt8	inAtIndex	The starting position in the string to insert from.
UInt8	inChar	The character to insert in the string.
ConstStringPtr	inStringPtr	The pointer to the string to insert.
const LString&	inString	A reference to the string to insert.

Return:

A reference to the finished string.

Length()

Purpose:

Indicate the String length.

Access:

Public

Prototype:

UInt8 Length() const;

None

Return:

Returns the number of characters in the String.

LoadFromPtr()

Purpose:

Fill in the String given a pointer and a byte count.

Access:

Protected

Prototype:

void LoadFromPtr( const void* inPtr,

UInt8 inLength );

The parameters for this method are:

UInt8	inLength	The length of the string.
const void*	inPtr	The pointer to the string to insert.

Return:

None

LoadFromSTRListResource()

Purpose:

Fill in the String from a STR resource.

Access:

Protected

Prototype:

void LoadFromSTRListResource( ResIDT inResID,

SInt16 inIndex);

void LoadFromSTRResource( ResIDT inResID );

The parameters for this method are:

UInt8	inLength	The index of the string within the resource.
ResIDT	inResID	The resource ID containing the string.

Return:

None

LoadFromStringPtr()

Purpose:

This method calls LoadFromPtr().

Access:

Public

Prototype:

void LoadFromStringPtr( ConstStringPtr 

inStringPtr);

The parameter for this method is:

ConstStringPtr

inStringPtr

The pointer to the string to use.

Return:

None

PStrToFourCharCode()

Purpose:

Convert a Pascal string to a four character code.

Access:

Static, Public

Prototype:

static void PStrToFourCharCode(

ConstStringPtr inString,

FourCharCode &outCode );

The parameters for this method are:

ConstStringPtr	inString	The pointer to the string to use.
FourCharCode&	outCode	The four-character code extracted from the string.

Return:

None

Remove()

Purpose:

Remove a given number of bytes from this String starting at the specified index.

Access:

Public

Prototype:

LString& Remove(

UInt8 inStartPos,

UInt8 inCount );

The parameters for this method are:

UInt8	inStartPos	The starting index in the string.
UInt8	inCount	The character count to remove.

Return:

A reference to the String.

Replace()

Purpose:

Replace a portion of this String with a new value.

Access:

Public

Prototype:

LString& Replace( UInt8 inStartPos, UInt8 inCount, 

const void* inPtr, UInt8 inLength );

LString& Replace( UInt8 inStartPos, UInt8 inCount, 

UInt8 inChar );

LString& Replace( UInt8 inStartPos, UInt8 inCount, 

ConstStringPtr inStringPtr );

LString& Replace( UInt8 inStartPos, UInt8 inCount, 

const LString& inString );

The parameters for this method are:

UInt8	inStartPos	The starting index in the string.
UInt8	inCount	The character count to remove.
const void*	inPtr	The pointer to the string.
UInt8	inLength	The length of the string.
const LString&	inString	The reference to the string.
ConstStringPtr	inStringPtr	The pointer to the string.
UInt8	inChar	The character to replace.

Return:

A reference to the String.

ReverseFind()

Purpose:

Find where a substring starts within this String, searching from the end of the String towards the beginning of the String.

Access:

Public

Prototype:

UInt8 ReverseFind( const void* inPtr, UInt8 

inLength, UInt8 inStartPos ) const;

UInt8 ReverseFind( UInt8 inChar, UInt8 inStartPos 

= 255 ) const;

UInt8 ReverseFind( ConstStringPtr inStringPtr, 

UInt8 inStartPos = 255 ) const;

UInt8 ReverseFind( const LString& inString, UInt8 

inStartPos = 255 ) const;

UInt32 ReverseFindWithin( const void* inPtr, 

UInt32 inLength, UInt32 inStartPos ) const;

UInt8 ReverseFindWithin( UInt8 inChar, UInt8 

inStartPos = 1 ) const;

UInt8 ReverseFindWithin( ConstStringPtr 

inStringPtr, UInt8 inStartPos = 255 ) const;

UInt8 ReverseFindWithin( const LString& inString, 

UInt8 inStartPos = 255 ) const;

The parameters for this method are:

UInt8	inStartPos	The starting index in the string.
const void*	inPtr	The pointer to the string.
UInt8	inLength	The length of the string.
const LString&	inString	The reference to the string.
ConstStringPtr	inStringPtr	The pointer to the string.
UInt8	inChar	The character to find.

Return:

The index where the item was found.

SetCompareFunc()

Purpose:

Sets the value of mCompareFunc to point to a function used for comparing strings.

Access:

Public

Prototype:

void SetCompareFunc( CompareFunc inCompareFunc );

The parameters for this method are:

CompareFunc

inCompareFunc

The pointer to the compare function.

Return:

None

ToolboxCompareText()

Purpose:

This method is a String comparison function that uses the Toolbox CompareText() routine.

Access:

Static, Public

Prototype:

static SInt16 ToolboxCompareText(

const void* inLeft,

const void* inRight,

UInt8 inLeftLength,

UInt8 inRightLength );

The parameters for this method are:

const void*	inLeft	The first string.
const void*	inRight	The second string.
UInt8	inLeftLength	The length of the first string.
UInt8	inRightLength	The length of the second string.

Return:

This is the same as the return value for CompareText() in the Mac OS Toolbox.

operator += (TypeParameter)

Purpose:

This is an operator overload for the += operator. It calls the Append (TypeParameters ) method to append a String to another String.

TypeParameter:

long, char, unsigned char, const unsigned char*, const LString&

Access:

Public

Prototype:

LString& operator+=(TypeParameter );

The specified TypeParameters may be input to this operator.

Return:

A reference to the String.

operator = (TypeParameter)

Type Parameter:

unsigned long, long, const char*, char, unsigned char, const unsigned char*, const LString&

Purpose:

This is an operator overload for the = (assignment) operator. It calls the Assign(TypeParameters) method to assign a String to another String.

TypeParameter:

unsigned long, long, const char*, char, unsigned char, const unsigned char*, const LString&

Access:

Public

Prototype:

LString& operator=(TypeParameter );

The specified TypeParameters may be input to this operator.

Return:

A reference to the String.

operator ()(unsigned char,unsigned char) const

Purpose:

Return a LStr255 String object containing the specified substring of this String.

Access:

Public

Prototype:

LStr255 operator()(

UInt8 inStartPos,

UInt8 inCount ) const;

The parameters for this operator are:

UInt8	inStartPos	The start position within the string.
UInt8	inCount	The length of the string to return.

Return:

An LStr255

operator [ ](unsigned char) const

Purpose:

Return a character at a specified position in the String.

Access:

Public

Prototype:

const UInt8& operator[]( UInt8 inPosition ) const;

The parameter for this operator is:

UInt8

inPosition

The start position within the string.

Return:

A reference to the unsigned character.

operator [ ](unsigned char)

Purpose:

Access individual characters in a String, in an array-like fashion.

Access:

Inline, Public

Prototype:

UInt8& operator[]( UInt8 inPosition );

The parameter for this operator is:

UInt8

inPosition

The start position within the string.

Return:

A reference to the unsigned character.

operator const unsigned char*() const

Purpose:

Retrieve the value of mStringPtr.

Access:

Inline, Public

Prototype:

operator ConstStringPtr() const;

None

Return:

A pointer to the String held in mStringPtr.

operator long double() const

Purpose:

This operator provides a conversion to a floating point number.

Access:

Public

Prototype:

operator double_t() const;

None

Return:

A double_t that represents the String.

operator long() const

Purpose:

This operator provides a conversion to a long integer.

Access:

Public

Prototype:

operator SInt32() const;

None

Return:

A SInt32 that represents the String.

operator unsigned char*()

Purpose:

This operator provides a conversion to a char* pointer.

Access:

Public

Prototype:

operator StringPtr();

None

Return:

A StringPtr that represents the String.

operator unsigned long() const

Purpose:

This operator provides a conversion to a four character code.

Access:

Public

Prototype:

operator FourCharCode() const;

None

Return:

A FourCharCode that represents the String.

mStringPtr

Purpose:

The String pointer.

Access:

Protected

Prototype:

StringPtr mStringPtr;

mCompareFunc

Purpose:

The compare function pointer for the String.

Access:

Protected

Prototype:

CompareFunc mCompareFunc;

mMaxBytes

Purpose:

The maximum number of bytes for the String.

Access:

Protected

Prototype:

UInt16 mMaxBytes;