StringStorage Class Reference

#include <StringStorage.h>

Public Types
enum	{ kDefaultLength = 16 }
typedef int32	size_type

Public Member Functions
	operator const UTF16TextChar * (void) const
UTF16TextChar	operator[] (int pos) const
StringStorage *	MakeSize (size_type requestedSize)
size_type	capacity () const
UTF16TextChar *	GetBuffer ()
const UTF16TextChar *	ConstBuffer () const
StringStorage *	Copy ()
void	Dispose ()
bool	IsUnique () const

Static Public Member Functions
static StringStorage *	CreateStringStorage (int32 initialLength=kDefaultLength, StringStorage *sourceStr=nil)

Protected Member Functions
	StringStorage (int32 initialLength, size_type adjustedLength)
	StringStorage (const StringStorage &srcStorage, size_type initialLength, size_type adjustedLength)

Protected Attributes
int32	fMemorySize
int32	fRequestedSize
size_type	fReferenceCount
UTF16TextChar	fFirstCharOfBuffer [1]

Detailed Description

StringStorage encapsulates management of the buffer of a string. A StringStorage may be used by

multiple strings, and the shared storage makes copying strings cheaper (you can just copy the reference to the StringStorage instead of allocating a block and doing a memcpy). The owning string must acquire a unique reference inorder to update the StringStorage.

A StringStorage and the buffer it holds are allocated as a single block of memory. The StringStorage is in the start of the block, and the buffer follows immediately after (the last field of the StringStorage is the first character of the buffer).

StringStorage holds 16-bit characters and is null terminated. The buffer must be big enough for the string and for the null character.

This class just maintains an array of textchars; all handling of Unicode surrogates, etc., must be done in the client code.

Constructor & Destructor Documentation

StringStorage::StringStorage ( int32  initialLength, size_type  adjustedLength  )

protected

Constructor

Parameters

initialLength	- The initial expected size of the string, as the number of textchars required for storing characters.
adjustedLength	- The actual size in textchars of the buffer that was allocated.

StringStorage::StringStorage ( const StringStorage &  srcStorage, size_type  initialLength, size_type  adjustedLength  )

protected

Constructor - create a new StringStorage based on an existing one

Parameters

srcStorage	- The storage we're copying from
initialLength	- The initial expected size of the string, as the number of textchars required for storing characters.
adjustedLength	- The actual size in textchars of the buffer that was allocated.

Member Function Documentation

StringStorage::size_type StringStorage::capacity ( ) const

inline

Returns the size in textchars that has been allocated for the string buffer.

const UTF16TextChar * StringStorage::ConstBuffer ( ) const

inline

ConstBuffer returns a const pointer to the start of the character storage (it's a const safe

version of GetBuffer().

StringStorage * StringStorage::Copy ( )

inline

"Copies" the string storage. Really it justs increments the ref-count. Returns a pointer

to the storage that the copy can use (always the same as this). If you wanted to turn off copy-on-write, you could override this function, and make it allocate a new StringStorage instead. Call this when you are copying from one string to another, and want to have the two strings use the same StringStorage.

static StringStorage* StringStorage::CreateStringStorage ( int32  initialLength = kDefaultLength, StringStorage *  sourceStr = nil  )

static

Factory function for creating StringStorage objects. Allocates a single block for the StringStorage and for the buffer, based on the initial requested size, and calls the placement new operator on StringStorage. The actual size of the buffer that is allocated is adjusted upward to make room for expected edits (this is an optimization).

Parameters

initialLength	- The initial expected size of the string, as the number of textchars required for storing characters.
sourceStr	- The new string will be a copy of the source string. The StringStorage may be copied because the string the references needs a copy it owns so it can update it, or because the buffer needs to be enlarged.

Returns

the new StringStorage that was created. The caller is responsible for calling Dispose() when it's done with the Storage.

void StringStorage::Dispose

(

)

Releases the StringStorage. Decrements the ref-count, and if the ref-count goes to zero, also

deletes the StringStorage (since no one is using it). Call this when you are all done with the string storage.

UTF16TextChar * StringStorage::GetBuffer ( )

inline

GetBuffer returns a pointer to the start of the character storage. The caller MUST make sure

that it holds the only reference on the storage first, and that it has requested enough storage space for what it needs to do (e.g., by calling MakeSize()).

bool StringStorage::IsUnique ( ) const

inline

Checks if this storage is shared (ref count is greater than one).

Returns

true if the string storage is not shared.

StringStorage* StringStorage::MakeSize

(

size_type

requestedSize

)

Call this before making changes to the buffer data. It will create a new StringStorage of the

requested size if either this StringStorage has multiple references on it, or if it is too small.

Parameters

requestedSize

- size in textchars of the buffer