#include <SSMStringHandler.h>

Public Member Functions
	SSMStringHandler (SSMBase *aBase)
	Default constructor initializes last string bucket to -1. More...

	~SSMStringHandler ()

void	setLastStringBucket (Int lastStringBucket)
	Set or get last string bucketnr. More...

Int	lastStringBucket () const

void	put (Int &bucketNr, Int &offset, Int &length, const String &string)
	Put a single string or an array of strings into a bucket. More...

void	put (Int &bucketNr, Int &offset, Int &length, const Array< String > &string, Bool handleShape)

void	putShape (Int &bucketNr, Int &offset, Int &length, const IPosition &aShape)
	Put a single string or an array of strings into a bucket. More...

void	getShape (IPosition &aShape, Int bucket, Int &offset, Int length)
	Get the shape in the given bucket and offset. More...

void	remove (Int bucketNr, Int offset, Int length)
	Remove data with the given length from a bucket. More...

void	get (String &string, Int bucket, Int offset, Int length)
	Get a string or an array of strings. More...

void	get (Array< String > &string, Int bucket, Int offset, Int length, Bool handleShape)

void	flush ()
	Flush the currently used string bucket. More...

void	init ()
	Initialize the StringHandler. More...

void	resync ()
	Resynchronize (after a table lock was acquired). More...

Private Member Functions
	SSMStringHandler (const SSMStringHandler &)
	Forbid copy constructor and assignment. More...

SSMStringHandler &	operator= (const SSMStringHandler &)

void	getBucket (uInt bucketNr, Bool isNew=False)
	Get the given bucket and make it current. More...

void	getNewBucket (Bool doConcat)
	Get a new bucket and make it current. More...

void	putData (Int length, const Char *data)
	Put the data with the given length at the end of the current bucket. More...

void	getData (Int length, Char *data, Int &offset)
	Get the data with the given length from the curent bucket at the given offset. More...

void	replace (Int bucketNr, Int offset, Int length, const String &string)
	Replace the current data with the new data. More...

void	replace (Int bucketNr, Int offset, Int length, Int totalLength, const IPosition &aShape)

void	replace (Int bucketNr, Int offset, Int length, Int totalLength, const Array< String > &string, Bool handleShape)

void	replaceData (Int &offset, Int length, const Char *data)

Private Attributes
SSMBase *	itsSSMPtr

Int	itsCurrentBucket

Int	itsLength

Int	itsNDeleted

Int	itsUsedLength

Int	itsNextBucket

char *	itsData

char *	itsIntBuf

Bool	isChanged

uInt	itsIntSize

Int	itsLastBucket

uInt	itsStart

Detailed Description

Store strings in the Standard Storage Manager.

Intended use:

Internal

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25
Test programs:: tSSMStringHandler

Prerequisite

SSMBase

Etymology

SSMStringHandler handles strings for the Standard Storage Manager.

Synopsis

Variable length strings cannot be stored in the data bucket. Only short (<8 characters) strings can be stored directly. Class SSMStringhandler is used by the SSM to store strings in so-called string buckets. A string bucket has the following layout:

The first Int is reserved to be used for the free bucket list.
itsUsedLength tells how many bytes have been used. Thus it tells the next free byte in the string part. In principle it always increases. Only if data are removed from the last part of the string part, it is decreased, thus the deleted part can be reused again.
itsNDeleted tells how many bytes of the string part are deleted (i.e. not used). Initially it is the length of the string part of the bucket (i.e. bucketsize minus 4 Ints). When a string is stored, its length is subtracted from itsNDeleted. When a string is removed, its length is added again. When the string part is deleted, the bucket is added to the free bucket list.
itsNextBucket tells the next bucket if the last entry in the bucket is continued in another bucket. Normally this field is -1 (meaning not continued), but long strings or string arrays might be continued in another bucket (and continued from there again).
The string part is a sequence of bytes containing the string data. When a value is to be stored, it will replace the current value if the new value is not longer. Otherwise the current value (if any) is deleted and the new value is appended to the end of the string part in the last bucket used.

For a scalar string only its characters are stored. Its length (and bucketnr and offset in string bucket) are stored in the data bucket.
A fixed length array is stored as an array of bytes. That byte array contains length-value pairs for each element of the array. The total length (and bucketnr and offset) are stored in the data bucket.
A variable length array is stored as the shape, a flag, optionally followed by the string array as length-value pairs (as above). The shape consists of the nr of dimensions followed by the length of each dimension. The flag indicates if a string array is actually stored. It is not if only the shape of the array is set, but no data put yet.

SSMStringHandler keeps a copy of the current bucket in use to reduce the number of accesses to the bucket cache.

It also keeps the bucket number of the last bucket where data were added to. It tells which bucket to use when new data has to be stored.

Definition at line 120 of file SSMStringHandler.h.

Constructor & Destructor Documentation

◆ SSMStringHandler() [1/2]

casacore::SSMStringHandler::SSMStringHandler ( SSMBase * aBase )

Default constructor initializes last string bucket to -1.

◆ ~SSMStringHandler()

casacore::SSMStringHandler::~SSMStringHandler ( )

◆ SSMStringHandler() [2/2]

casacore::SSMStringHandler::SSMStringHandler ( const SSMStringHandler & )

private

Forbid copy constructor and assignment.

Member Function Documentation

◆ flush()

void casacore::SSMStringHandler::flush ( )

Flush the currently used string bucket.

◆ get() [1/2]

void casacore::SSMStringHandler::get	(	Array< String > &	string,
		Int	bucket,
		Int	offset,
		Int	length,
		Bool	handleShape
	)

◆ get() [2/2]

void casacore::SSMStringHandler::get	(	String &	string,
		Int	bucket,
		Int	offset,
		Int	length
	)

Get a string or an array of strings.

The array must have the correct shape. handleShape will be True for variable shaped arrays indicating that the data are preceeded by the shape.

◆ getBucket()

void casacore::SSMStringHandler::getBucket	(	uInt	bucketNr,
		Bool	isNew = `False`
	)

private

Get the given bucket and make it current.

It first writes the current bucket if it has changed.
If isNew is True the bucket is new, so the Ints at its beginning do not have to be interpreted.

◆ getData()

void casacore::SSMStringHandler::getData	(	Int	length,
		Char *	data,
		Int &	offset
	)

private

Get the data with the given length from the curent bucket at the given offset.

If sets the offset to the byte after the data read. Continuation buckets are followed (and made current).

◆ getNewBucket()

void casacore::SSMStringHandler::getNewBucket ( Bool doConcat )

private

Get a new bucket and make it current.

If doConcat is True, the new bucket is a continuation, so itsNextBucket in the currently used bucket is filled with the new bucket number.

◆ getShape()

void casacore::SSMStringHandler::getShape	(	IPosition &	aShape,
		Int	bucket,
		Int &	offset,
		Int	length
	)

Get the shape in the given bucket and offset.

It sets the offset to the data right after the shape. The IPosition object is resized as needed.

◆ init()

void casacore::SSMStringHandler::init ( )

Initialize the StringHandler.

◆ lastStringBucket()

Int casacore::SSMStringHandler::lastStringBucket ( ) const

inline

Definition at line 256 of file SSMStringHandler.h.

References itsLastBucket.

Referenced by setLastStringBucket().

◆ operator=()

SSMStringHandler& casacore::SSMStringHandler::operator= ( const SSMStringHandler & )

private

◆ put() [1/2]

void casacore::SSMStringHandler::put	(	Int &	bucketNr,
		Int &	offset,
		Int &	length,
		const Array< String > &	string,
		Bool	handleShape
	)

◆ put() [2/2]

void casacore::SSMStringHandler::put	(	Int &	bucketNr,
		Int &	offset,
		Int &	length,
		const String &	string
	)

Put a single string or an array of strings into a bucket.

If its length does not exceed the given length, it reuses the currently used space (given by bucketnr and offset). Otherwise it adds the data to the last string bucket. It fills the offset and bucketnr where the data are stored and the length occupied in the buckets. An array of strings is flattened first (a la SSMColumn::writeString).
If handleShape is True (for variable shaped arrays), the shape will be put first.

◆ putData()

void casacore::SSMStringHandler::putData	(	Int	length,
		const Char *	data
	)

private

Put the data with the given length at the end of the current bucket.

If they do not fit, they are continued in a new bucket.

◆ putShape()

void casacore::SSMStringHandler::putShape	(	Int &	bucketNr,
		Int &	offset,
		Int &	length,
		const IPosition &	aShape
	)

Put a single string or an array of strings into a bucket.

If its length does not exceed the given length, it reuses the currently used space (given by bucketnr and offset). Otherwise it adds the data to the last string bucket. It fills the offset and bucketnr where stored and the length occupied in the buckets.

◆ remove()

void casacore::SSMStringHandler::remove	(	Int	bucketNr,
		Int	offset,
		Int	length
	)

Remove data with the given length from a bucket.

If the data are continued in next bucket(s), they will be removed there as well.

◆ replace() [1/3]

void casacore::SSMStringHandler::replace	(	Int	bucketNr,
		Int	offset,
		Int	length,
		const String &	string
	)

private

Replace the current data with the new data.

It is used by put after having assured that the new length does not exceed the current one. It follows continuation buckets as needed.

◆ replace() [2/3]

void casacore::SSMStringHandler::replace	(	Int	bucketNr,
		Int	offset,
		Int	length,
		Int	totalLength,
		const Array< String > &	string,
		Bool	handleShape
	)

private

◆ replace() [3/3]

void casacore::SSMStringHandler::replace	(	Int	bucketNr,
		Int	offset,
		Int	length,
		Int	totalLength,
		const IPosition &	aShape
	)

private

◆ replaceData()

void casacore::SSMStringHandler::replaceData	(	Int &	offset,
		Int	length,
		const Char *	data
	)

private

◆ resync()

void casacore::SSMStringHandler::resync ( )

Resynchronize (after a table lock was acquired).

It clears the itsCurrentBucket variable to assure that buckets are reread.

◆ setLastStringBucket()

void casacore::SSMStringHandler::setLastStringBucket ( Int lastStringBucket )

inline

Set or get last string bucketnr.

Setting is needed when an existing table is opened.

Definition at line 251 of file SSMStringHandler.h.

References itsLastBucket, and lastStringBucket().

Member Data Documentation

◆ isChanged

Bool casacore::SSMStringHandler::isChanged

private

Definition at line 244 of file SSMStringHandler.h.

◆ itsCurrentBucket

Int casacore::SSMStringHandler::itsCurrentBucket

private

Definition at line 237 of file SSMStringHandler.h.

◆ itsData

char* casacore::SSMStringHandler::itsData

private

Definition at line 242 of file SSMStringHandler.h.

◆ itsIntBuf

char* casacore::SSMStringHandler::itsIntBuf

private

Definition at line 243 of file SSMStringHandler.h.

◆ itsIntSize

uInt casacore::SSMStringHandler::itsIntSize

private

Definition at line 245 of file SSMStringHandler.h.

◆ itsLastBucket

Int casacore::SSMStringHandler::itsLastBucket

private

Definition at line 246 of file SSMStringHandler.h.

Referenced by lastStringBucket(), and setLastStringBucket().

◆ itsLength

Int casacore::SSMStringHandler::itsLength

private

Definition at line 238 of file SSMStringHandler.h.

◆ itsNDeleted

Int casacore::SSMStringHandler::itsNDeleted

private

Definition at line 239 of file SSMStringHandler.h.

◆ itsNextBucket

Int casacore::SSMStringHandler::itsNextBucket

private

Definition at line 241 of file SSMStringHandler.h.

◆ itsSSMPtr

SSMBase* casacore::SSMStringHandler::itsSSMPtr

private

Definition at line 236 of file SSMStringHandler.h.

◆ itsStart

uInt casacore::SSMStringHandler::itsStart

private

Definition at line 247 of file SSMStringHandler.h.

◆ itsUsedLength

Int casacore::SSMStringHandler::itsUsedLength

private

Definition at line 240 of file SSMStringHandler.h.

The documentation for this class was generated from the following file:

tables/DataMan/SSMStringHandler.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Intended use:

Review Status

Prerequisite

Etymology

Synopsis

Constructor & Destructor Documentation

◆ SSMStringHandler() [1/2]

◆ ~SSMStringHandler()

◆ SSMStringHandler() [2/2]

Member Function Documentation

◆ flush()

◆ get() [1/2]

◆ get() [2/2]

◆ getBucket()

◆ getData()

◆ getNewBucket()

◆ getShape()

◆ init()

◆ lastStringBucket()

◆ operator=()

◆ put() [1/2]

◆ put() [2/2]

◆ putData()

◆ putShape()

◆ remove()

◆ replace() [1/3]

◆ replace() [2/3]

◆ replace() [3/3]

◆ replaceData()

◆ resync()

◆ setLastStringBucket()

Member Data Documentation

◆ isChanged

◆ itsCurrentBucket

◆ itsData

◆ itsIntBuf

◆ itsIntSize

◆ itsLastBucket

◆ itsLength

◆ itsNDeleted

◆ itsNextBucket

◆ itsSSMPtr

◆ itsStart

◆ itsUsedLength