A C++ Interface to the handling SDS structures. More...

#include <sds.h>

Inheritance diagram for SdsId:

Public Member Functions
	SdsId (const SdsIdType item=0, const bool free=false, const bool del=false, const bool readfree=false)
	Construct an SdsId item from an existing C language SDS id. More...

	SdsId (void const data, StatusType const status, const bool import=false)
	Constructor that accesses an exported SDS structure in a byte stream. More...

	SdsId (const void const data, StatusType const status)
	Constructor that imports a previously exported SDS structure from a const byte stream. More...

	SdsId (const char const filename, StatusType const status)
	Constructor which creates an SDS Id after reading a structure from a file. More...

	SdsId (const SdsId &parent_id, const char const name, const SdsCodeType code, StatusType const status, const long nextra=0, const char *const extra=0)
	Constructor which creates a new (non-array) child item. More...

	SdsId (const char const name, const SdsCodeType code, StatusType const status, const long nextra=0, const char *const extra=0)
	Constructor which creates a new (non-array) top-level item. More...

	SdsId (const SdsId &parent_id, const char const name, const SdsCodeType code, const long ndims, const unsigned long dims, StatusType const status, const long nextra=0, const char const extra=0)
	Constructor which creates a new array child item. More...

	SdsId (const char const name, const SdsCodeType code, const long ndims, const unsigned long dims, StatusType const status, const long nextra=0, const char const extra=0)
	Constructor which creates a new array top-level item. More...

	SdsId (const SdsId &array_id, const long nindicies, const unsigned long const indicies, StatusType const status)
	Constructor that returns a cell of an existing array id. More...

	SdsId (const SdsId &source, StatusType *const status)
	SdsId Copy constructor. More...

	SdsId (const SdsId &source, const char const name, StatusType const status)
	Constructor which returns a reference to a named item. More...

	SdsId (const SdsId &source, const long index, StatusType *const status)
	Constructor which returns an id to a structured item indexed by position. More...

virtual	~SdsId ()
	SdsId Destructor. More...

void	SetFree ()
	Indicate the underlying SDS item should be free-ed when the SdsId object is destroyed. More...

void	SetDelete ()
	Indicate the underlying SDS structure should be deleted when the SdsId object is destroyed. More...

void	ClearDelete ()
	Indicate the underlying SDS structure should NOT be deleted when the SdsId object is desroyed. More...

void	Outlive ()
	Force the actual SDS ID to outlive the SdsId variable. More...

virtual void	Delete (StatusType *const status)
	Delete the SDS item. More...

void	Export (const unsigned long length, void const data, StatusType const status)
	Export the SDS structure into a buffer. More...

void	ExportDefined (const unsigned long length, void const data, StatusType const status)
	Export the SDS structure into a buffer, defining any undefined data. More...

void	Extract (StatusType *const status)
	Extract the SDS structure from its parent. More...

void	Flush (StatusType *const status)
	Flush data modified by pointer. More...

virtual void	Get (const unsigned long length, void const data, StatusType const status, unsigned long *actlen=0, const unsigned long offset=0) const
	Get data from an SDS item. More...

void	GetExtra (const unsigned long length, char const extra, StatusType const status, unsigned long *actlen=0) const
	Get extra data from an SDS item. More...

void	Info (char const name, SdsCodeType const code, long const ndims, unsigned long const dims, StatusType *const status) const
	Return information about an SDS item. More...

void	GetName (char const name, StatusType const status) const
	Return the name of the SDS item. More...

void	Code (SdsCodeType const code, StatusType const status) const
	Return the code of the SDS item. More...

void	Dims (long const ndims, unsigned long const dims, StatusType *const status) const
	Return the dimensions of the SDS item. More...

void	Insert (SdsId &to_insert, StatusType *const status)
	Insert an SDS object into this object. More...

void	Insert (SdsId &to_insert, const long ndims, const unsigned long const dims, StatusType const status)
	Insert an SDS object into this object, which is a structured array. More...

void	FillArray (const SdsId &elem, StatusType *const status)
	Fill out the contents of this object, which is a structured array. More...

void	Pointer (void *data, StatusType const status, unsigned long *length=0)
	Object a pointer to the data area of a primitive SDS item. More...

virtual void	Put (const unsigned long length, void const data, StatusType const status, const unsigned long offset=0)
	Put data into an SDS item. More...

void	PutExtra (const long nextra, const char const extra, StatusType const status)
	Put extra data into an SDS item. More...

void	Rename (const char const name, StatusType const status)
	Rename the SDS item. More...

void	Resize (const long ndims, const unsigned long dims, StatusType const status)
	Change the dimensions of an SDS array. More...

void	Size (unsigned long const bytes, StatusType const status) const
	Return the size of an SDS structure, as required for exporting. More...

void	SizeDefined (unsigned long const bytes, StatusType const status) const
	Return the size of an SDS structure, as required for exporting defined. More...

void	List (StatusType *const status) const
	List the contents of the structure to standard output. More...

void	List (FILE to, StatusType const status) const
	List the contents of the structure to a C file. More...

void	Write (const char const filename, StatusType const status) const
	Write the contents of the structure to a file. More...

void	IsExternal (int const external, StatusType const status) const
	Determine if the SDS structure is external. More...

void	GetExternInfo (void *data, StatusType const status) const
	Return the address of an external item. More...

	operator SdsIdType (void) const
	Operator which returns the underlying SDS id. More...

	operator bool (void) const
	Operator which tests if an item is valid. More...

SdsIdType	COut (const bool outlives, bool const free=0, bool const del=0, bool *const readfree=0)
	Return this item as an SdsIdType for return to C code. More...

void	COut (const bool outlives, SdsIdType item, bool const free=0, bool const del=0, bool const readfree=0)
	Return this item as an SdsIdType for return to C code. More...

void	Find (const SdsId &source, const char const name, StatusType const status)
	Find an SDS object and make available in the current SdsId object. More...

void	ShallowCopy (SdsId &source, const bool outlives=true)
	Shallow copy from SdsId. More...

void	DeepCopy (const SdsId &source, StatusType *const status)
	Replace the item refered to by this object by a deep copy of source. More...

void	ShallowCopy (const SdsIdType source, const bool free=false, const bool del=false, const bool readfree=false)
	Shallow copy from SdsIdType. More...

void	DeepCopy (const SdsIdType source, StatusType *status)
	Replace the item refered to by this object by a deep copy of source. More...

template<typename T >
void	ArrayAccess (SdsArrayAccessHelper< T > const data, StatusType const status)
	Access the data of a single dimensional SDS array item. More...

template<typename T >
void	ArrayAccess (const unsigned long expitems, SdsArrayAccessHelper< T > const data, StatusType const status)
	Access the data of a single dimensional SDS array. More...

template<typename T >
void	ArrayAccess (SdsArrayAccessHelper< T > const data, long ndims, unsigned long dims[], StatusType const status)
	Access the data of an SDS array. More...

template<typename T >
void	ArrayAccess (SdsArrayAccessHelper< T > const data, long ndims, unsigned long dims[], StatusType *const status)
	Access the data of an SDS array. More...

Detailed Description

A C++ Interface to the handling SDS structures.

The class SdsId provides a C++ interface to the AAO DRAMA SDS Library. See The SDS Specification for more details on SDS itself.

An assortment of constructors are provided. Some of these access components of structures, some access external items and some create new SDS structures. Each SdsId class object contains an SDS id which refers to an SDS structure, rather then a complete SDS structure and more then on SdsId can refer to the one underlying SDS structure. Additionally, details about what to do when the object goes out of scope are maintained, ensuring the the destructor cleans up correctly.

If any of the contructors fail, then the current implementation will set the inherited status argument bad rather then throwing an exception. The object is still constructed in this case but will refer to an invalid SDS id, causing any other methods to fail (by setting status bad). If the inherited status is not equal to STATUS__OK on entry to any method with an inherited status argument, then the method returns immediately.

The various methods of the class implement those SDS functions which do not return new SDS id's (SDS functions which return new SDS id's are implemented as constructors).

The destructor will normally delete the underlying SDS item and and free the SDS id, when appropiate. These operations are normally dependent on how the item was constructed, but can be changed if required (which might be required if the underlying SDS id is to be passed to a C function).

Assignment and copying of these items is prohibited by making the operators private. This is done since it is not clear what the user will expect from some operations. (for example, in a copy constructor, should the item be copied with the C routine SdsCopy() or just a new id to the same item generated. SDS does not even support the later. Also, management of the inherited status is a problem).

You can pass items to subroutines by reference or pointer to get around the copy problem. A constructor which creates a copy of an existing object can be used in the place of assignment in many cases. You can use the member functions ShallowCopy() (which just copies the Sds id itself) and DeepCopy(), to get a copy in an explicit maner in other cases.

See also: Arg; SDS Specification; DRAMA C++ interface; DRAMA DITS Specification

Constructor & Destructor Documentation

SdsId::SdsId	(	const SdsIdType	item = `0`,
		const bool	free = `false`,
		const bool	del = `false`,
		const bool	readfree = `false`
	)

inline

Construct an SdsId item from an existing C language SDS id.

This SdsId constructor that takes an existing SDS id (C style) and creates an SdsId class object which refers to that SDS id. You must explictly specify if the item is to be free-ed and/or deleted when the object's destructor is invoked, and what you do depends on when what other code may do with item. The del and readfree are mutually exclusive, through this is currently not checked in this implementation.

Parameters

item	The SdsIdType of the item. If 0 (the default), the SdsId object constructed does not refer to any SDS item. This is normally only used when we want an argument to pass (by pointer) to a function which will use SdsId::ShallowCopy or SdsId::DeepCopy to set the ID.
free	Set true to invoke SdsFreeId() on the ID when the object is destroyed. The default is false.
del	Set true to invoke SdsDelete() on the ID when the object is destroyed. The default is false.
readfree	Set true to invoke SdsReadFree() on the ID when the object is destroyed. The default is false.

SdsId::SdsId	(	void *const	data,
		StatusType *const	status,
		const bool	import = `false`
	)

inline

Constructor that accesses an exported SDS structure in a byte stream.

This constructor uses SdsImport() or SdsAccess() to get access an SDS structure stored in an external byte stream

See also: SdsImport().; SdsAccess().

Parameters

data	A pointer to a byte stream created with SdsExport() or SdsId::Export .
status	Inherited status.
import	If true, then import the structure such that is an internal SDS structure. This allows the structure to be modified in any fashion, but is slower and requires more memory.

SdsId::SdsId	(	const void *const	data,
		StatusType *const	status
	)

inline

Constructor that imports a previously exported SDS structure from a const byte stream.

This constructor uses SdsImport() to get access an SDS structure stored in an const external byte stream. Note that since the data is const, only a SdsImport() is possible.

See also: SdsImport().

Parameters

data	A pointer to a byte stream created with SdsExport() or SdsId::Export .
status	Inherited status.

SdsId::SdsId	(	const char *const	filename,
		StatusType *const	status
	)

inline

Constructor which creates an SDS Id after reading a structure from a file.

The specified file should contain an SDS structure created using SdsWrite() or SdsId::Write .

See also: SdsId::Write; SdsRead()

Parameters

filename	Name of the file.
status	Inherited status.

SdsId::SdsId	(	const SdsId &	parent_id,
		const char *const	name,
		const SdsCodeType	code,
		StatusType *const	status,
		const long	nextra = `0`,
		const char *const	extra = `0`
	)

inline

Constructor which creates a new (non-array) child item.

This contructor creates a new SDS item which is a child of the specified SDS item in the specified SdsId object.

See also: SdsNew()

Parameters

parent_id	The parent SDS item.
name	The name for the new SDS item.
code	The SDS code for the new item.
status	Inherited status.
nextra	The about of extra data, default to 0 (no extra data).
extra	The extra data.

SdsId::SdsId	(	const char *const	name,
		const SdsCodeType	code,
		StatusType *const	status,
		const long	nextra = `0`,
		const char *const	extra = `0`
	)

inline

Constructor which creates a new (non-array) top-level item.

This constructor creates a new SDS top-level SDS item.

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item.
status	Inherited status.
nextra	The about of extra data, default to 0 (no extra data).
extra	The extra data.

SdsId::SdsId	(	const SdsId &	parent_id,
		const char *const	name,
		const SdsCodeType	code,
		const long	ndims,
		const unsigned long *	dims,
		StatusType *const	status,
		const long	nextra = `0`,
		const char *const	extra = `0`
	)

inline

Constructor which creates a new array child item.

This contructor creates a new SDS structure array which is a child of the specified SDS item in the specified SdsId object.

See also: SdsNew()

Parameters

parent_id	The parent SDS item.
name	The name for the new SDS item.
code	The SDS code for the new item.
ndims	The number of dimensions, 1 through 7.
dims	An array giving each dimension.
status	Inherited status.
nextra	The about of extra data, default to 0 (no extra data).
extra	The extra data.

SdsId::SdsId	(	const char *const	name,
		const SdsCodeType	code,
		const long	ndims,
		const unsigned long *	dims,
		StatusType *const	status,
		const long	nextra = `0`,
		const char *const	extra = `0`
	)

inline

Constructor which creates a new array top-level item.

This constructor creates a new SDS top-level SDS structure array.

See also: SdsNew()

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item.
ndims	The number of dimensions, 1 through 7.
dims	An array giving each dimension.
status	Inherited status.
nextra	The about of extra data, default to 0 (no extra data).
extra	The extra data.

SdsId::SdsId	(	const SdsId &	array_id,
		const long	nindicies,
		const unsigned long *const	indicies,
		StatusType *const	status
	)

inline

Constructor that returns a cell of an existing array id.

This constructor is used to access a specified cell of an existing SDS structure array.

See also: SdsCell().

Parameters

array_id	An ID which refers to a structure array.
nindicies	The number of indicies in the array
indicies	An array giving the indicies of the cell in question.
status	Inherited status.

SdsId::SdsId	(	const SdsId &	source,
		StatusType *const	status
	)

inline

SdsId Copy constructor.

This constructor is used to generate a copy of an existing SDS structure. This is a deep copy - a new internal SDS item is created.

See also: SdsCopy().

Parameters

source	The SDS item to be copied.
status	Inherited status.

SdsId::SdsId	(	const SdsId &	source,
		const char *const	name,
		StatusType *const	status
	)

inline

Constructor which returns a reference to a named item.

This constructor searches an existing SDS item for a item with a specified name and creates a reference to it.

See also: SdsFind()

Parameters

source	The SDS item to find name within.
name	The name of the SDS item to find.
status	Inherited status.

SdsId::SdsId	(	const SdsId &	source,
		const long	index,
		StatusType *const	status
	)

inline

Constructor which returns an id to a structured item indexed by position.

This constructor uses the specified index to find an item within an SDS structure.

See also: SdsIndex()

Parameters

source	The SDS item to index within.
index	The index of the item fo find. Items in a structure are numbered in order of creation starting with one.
status	Inherited status.

virtual SdsId::~SdsId ( )

inlinevirtual

SdsId Destructor.

The SdsDelete()/ SdsReadFree() may be invoked on the underlying SDS id as may SdsFreeId(). What is to happen depends on how the item was constructed or how the flags were changed. In general, the required result is achived.

See also: SdsId::SetFree(); SdsId::SetDelete(); SdsId::ClearDelete(); SdsId::Outlive(); SdsFreeId(); SdsDelete(); SdsReadFree()

Member Function Documentation

template<typename T >

void SdsId::ArrayAccess	(	SdsArrayAccessHelper< T > *const	data,
		StatusType *const	status
	)

inline

Access the data of a single dimensional SDS array item.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to a one dimensional array of any size. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsAccess ArrayHelper:: class for more information.

This version uses the number of elements in the SDS array.

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper.

   SdsId structure;
   ...
   SdsArrayShort value;
   structure.ArrayAccess(&value, status);
   unsigned long count = value.Size();
   if (*status == STATUS__OK)
   {
      for (unsigned long i = 0; i < count ; ++i)
        printf("Element %ld = %d\\n", i, (int)value[i]);
   }

Remarks: Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.

See also: SdsArrayAccessHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
status	Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

References SdsArrayAccessHelper< T >::Code().

template<typename T >

void SdsId::ArrayAccess	(	const unsigned long	expitems,
		SdsArrayAccessHelper< T > *const	data,
		StatusType *const	status
	)

inline

Access the data of a single dimensional SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to a one dimensional array of any size. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index.

In this version uses the number of elements in the SDS array must match the specified number of elements, otherwise status is set to SDS__INVDIMS.

Remarks: Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper.

   SdsId structure;
   ...
   SdsArrayShort value;
   structure.ArrayAccess(10, &value, status);
   if (*status == STATUS__OK)
   {
      for (unsigned long i = 0; i < 10 ; ++i)
        printf("Element %ld = %d\\n", i, (int)value[i]);
   }

See also: SdsArrayAccessHelper

Parameters

expitems	The number of items expected in the array.
data	A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
status	Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

References SdsArrayAccessHelper< T >::Code().

template<typename T >

void SdsId::ArrayAccess	(	SdsArrayAccessHelper< T > *const	data,
		long	ndims,
		unsigned long	dims[],
		StatusType *const	status
	)

inline

Access the data of an SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to an array of a specified number of dimensions. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsArrayAccessHelper:: class for more information. Note that Multidimensional arrays must be indexed by calculating the equivalent single dimensional index (otherwise the type definitions are too hard).

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper.

   SdsId structure;
   ...
   unsigned long dims[SDS_C_MAXARRAYDIMS];
   SdsArrayShort value;
   structure.ArrayAccess(&value, 1, dims, status);
   if (*status == STATUS__OK)
   {
      for (unsigned long i = 0; i < dims[0] ; ++i)
        printf("Element %ld = %d\\n", i, (int)value[i]);
   }

Remarks: Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.

See also: SdsArrayAccessHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
ndims	The number of dimensions there should be in the structure.
dims	The dimensions are written to this array. Must have space for 7 dimensions.
status	Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

References SdsArrayAccessHelper< T >::Code().

template<typename T >

void SdsId::ArrayAccess	(	SdsArrayAccessHelper< T > *const	data,
		long *	ndims,
		unsigned long	dims[],
		StatusType *const	status
	)

inline

Access the data of an SDS array.

Accesses an array using an SdsArrayAccessHelper of the appropiate type. This version allows access to an array of any dimensions and number of dimensions. Various other versions also exist.

On return, "data[index]" can be used to access the array element at the specified index. See the SdsArrayAccessHelper class for more information. Note that mult-idimensional arrays must be indexed by calculating the single dimensional index (otherwise the type definitions are too hard).

In this example, SdsArrayShort is a sub-class of SdsArrayAccessHelper.

   SdsId structure;
   ...
   long ndims;
   unsigned long dims[SDS_C_MAXARRAYDIMS];
   SdsArrayShort value;
   structure.ArrayAccess(&value, &ndims, dims, status);
   unsigned long count = value.Size();
   if (*status == STATUS__OK)
   {
      for (unsigned long i = 0; i < count ; ++i)
        printf("Element %ld = %d\\n", i, (int)value[i]);
   }

Remarks: Only available if the marcro DRAMA_ALLOW_CPP_STDLIB is defined.

See also: SdsArrayAccessHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be a sub-class of SdsArrayAccessHelper appropiate for type T.
ndims	The number of dimensions is written here.
dims	The dimensions are written to this array. Must have space for 7 dimensions.
status	Inherited status. In addition to the values returned by SdsInfo() and SdsPointer(), the values SDS__TYPE, SDS__NOTARR and SDS__INVDIMS may be returned.

void SdsId::ClearDelete ( )

inline

Indicate the underlying SDS structure should NOT be deleted when the SdsId object is desroyed.

This should be considered if the SDS object refered to was created when the SdsId object is created and must outlive the object.

See also: SdsId::OutLive()

void SdsId::Code	(	SdsCodeType *const	code,
		StatusType *const	status
	)		const

inline

Return the code of the SDS item.

Just return the code of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also: SdsId::Info; SdsInfo()

Parameters

code	The SDS item code is returned here..
status	Inherited status.

SdsIdType SdsId::COut	(	const bool	outlives,
		bool *const	free = `0`,
		bool *const	del = `0`,
		bool *const	readfree = `0`
	)

inline

Return this item as an SdsIdType for return to C code.

This method will setup for and obtain details of this item for return of this item using an SdsIdType. Of particular note - if outlives is true, the SdsIdType item returned by this is considered to outlive this object and we leave the freeing of the id etc up to the caller, who can use the other variables to work out what to do. If outlives is false, can method be used as an enquiry for what is to happen when the destructor is invoked.

Parameters

outlives	If true, then the returned value will outlive this object and this object is modified to reflect this.
free	If specified, set true to indicate that the destructor for this object would have invoked SdsFreeId() on the underlying SDS ID. If outlives is true, this won't now happen.
del	If specified, set true to indicate that the destructor for this object would have invoked SdsDelete() on the underlying SDS ID. If outlives is true, this won't now happen.
readfree	If specified, set true to indicate that the destructor for this object would have invoked SdsReadFree() on the underlying SDS ID. If outlives is true, this won't now happen.

Returns: The underlying SDS ID value.

Referenced by Sdp::PutStruct().

void SdsId::COut	(	const bool	outlives,
		SdsIdType *	item,
		bool *const	free = `0`,
		bool *const	del = `0`,
		bool *const	readfree = `0`
	)

inline

Return this item as an SdsIdType for return to C code.

Deprecated:: Please use the version which returns the value.

This method will setup for and obtain details of this item for return of this item using an SdsIdType. Of particular note - if outlives is true, the SdsIdType item returned by this is considered to outlive this object and we leave the freeing of the id etc up to the caller, who can use the other variables to work out what to do.

Parameters

outlives	If true, then the returned value will outlive this object and this object is modified to reflect this.
item	the SDS item is returned here.
free	If specified, set true to indicate that the destructor for this object would have invoked SdsFreeId() on the underlying SDS ID. If outlives is true, this won't now happen.
del	If specified, set true to indicate that the destructor for this object would have invoked SdsDelete() on the underlying SDS ID. If outlives is true, this won't now happen.
readfree	If specified, set true to indicate that the destructor for this object would have invoked SdsReadFree() on the underlying SDS ID. If outlives is true, this won't now happen.

Returns: The underlying SDS ID value.

void SdsId::DeepCopy	(	const SdsId &	source,
		StatusType *const	status
	)

inline

Replace the item refered to by this object by a deep copy of source.

The SdsCopy() function is used to create a copy.

Remarks: If source is this item, then SdsCopy() is only invoked if this is an external SDS item. The result of such an operation is that "this" will always refer to something you can modify the structure of, after a call to DeepCopy().

Parameters

source	The item to create a copy of.
status	Inherited status.

void SdsId::DeepCopy	(	const SdsIdType	source,
		StatusType *	status
	)

inline

Replace the item refered to by this object by a deep copy of source.

The SdsCopy() function is used to create a copy.

Parameters

source	The item to create a copy of.
status	Inherited status.

virtual void SdsId::Delete ( StatusType *const status )

inlinevirtual

Delete the SDS item.

SdsDelete() is invoked on the SDS ID refered to by the Object. This is generally used to delete items which are a component of other objects. The ID is also free-ed if the approiate flag is set

After this method is invoked, this object is invalid and many methods will now fail. But you can use the copy methods to insert a new item.

See also: SdsDelete(); SdsFreeId()

Parameters

status Inherited status.

void SdsId::Dims	(	long *const	ndims,
		unsigned long *const	dims,
		StatusType *const	status
	)		const

inline

Return the dimensions of the SDS item.

Just return the dimensions of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also: SdsId::Info; SdsInfo()

Parameters

ndims	The number of dimensions is returned here, 0 if the item is not an array, otherwise, 1 through 7.
dims	The dimensions are retuned here. This should be an array of 7 items.
status	Inherited status.

void SdsId::Export	(	const unsigned long	length,
		void *const	data,
		StatusType *const	status
	)

inline

Export the SDS structure into a buffer.

The SDS structure refered to by this SdsId object is exported into the specified buffer.

Note that if any of the underlying data is not defined (say because you created a new item but have not yet put any data into it) then the size will not include space for the data itself. This is acceptable to SDS but may not be what you expect. To create the required space in the exported object, use the SdsId::ExportDefined method.

See also: SdsExport(); SdsId::ExportDefined

Parameters

length	The length of the buffer. Should be the value returned by SdsSize() or SdsId::Size
data	The buffer to write the data into. Should be of at least the size specified by length.
status	Inherited status.

void SdsId::ExportDefined	(	const unsigned long	length,
		void *const	data,
		StatusType *const	status
	)

inline

Export the SDS structure into a buffer, defining any undefined data.

The SDS structure refered to by this SdsId object is exported into the specified buffer, with any undefined data defined.

Data may be undefined if you created a new item but have not yet put any data into it. The standard Export() method does not allow space for this data, but this method does.

See also: SdsExportDefined(); SdsId::Export

Parameters

length	The length of the buffer. Should be the value returned by SdsSizeDefined() or SdsId::SizeDefined
data	The buffer to write the data into. Should be of at least the size specified by length.
status	Inherited status.

void SdsId::Extract ( StatusType *const status )

inline

Extract the SDS structure from its parent.

This method is normally applied to an SdsId object which refers to a child of another SDS structure. This method extracts the child to create a new top-level SDS structure

See also: SdsExtract(); SdsId::Pointer; SdsPointer()

Parameters

status Inherited status.

void SdsId::FillArray	(	const SdsId &	elem,
		StatusType *const	status
	)

inline

Fill out the contents of this object, which is a structured array.

This routine will fill out an array of structures item with the copies of a specified struture.

See also: SdsFillArray(); SdsId::Insert(SdsId &to_insert, const long ndims, const unsigned long *const dims, StatusType *const status)

Parameters

elem	The item to copy into the structure.
status	Inherited status.

void SdsId::Find	(	const SdsId &	source,
		const char *const	name,
		StatusType *const	status
	)

inline

Find an SDS object and make available in the current SdsId object.

This method will first clean up the SdsId object, as if the destructor were run. It then finds a new SDS object within the object represented by "source" and makes that available in the object.

The purpose of this method is for cases where an SdsId object must be set up in a different spot from where the variable is declared.

This method is meant to replace sequences where previously one would have needed to create a new object, and then use ShallowCopy() to copy its contents to another object.

If the find fails or if status is non-zero on entry, then the object will have been cleaned up and will refer to a null SDS object.

See also: SdsId::ShallowCopy SdsFind()

Parameters

source	The object containing the object of interest
name	The name of the SDS object of interest
status	Inherited status.

void SdsId::Flush ( StatusType *const status )

inline

Flush data modified by pointer.

When the data of an SDS is modified via a pointer obtained by SdsPointer() or SdsId::Pointer, then this method should be used to ensure the data is updated correctly.

This is currently a null method for all machines on which SDS is currently implemented, but may be required in the future.

See also: SdsFlush()

Parameters

status Inherited status.

virtual void SdsId::Get	(	const unsigned long	length,
		void *const	data,
		StatusType *const	status,
		unsigned long *	actlen = `0`,
		const unsigned long	offset = `0`
	)		const

inlinevirtual

Get data from an SDS item.

This method accesses the data from an SDS item. The data is copied into the specified buffer.

Note that data from nested structures is also copied. Please see the SDS manual for more details on Get operations.

See also: SdsGet(); SdsId::Pointer; SdsId::Put; SdsPut()

Parameters

length	The amount of data to fetch.
data	The buffer to put the data info, must of of size length or greater.
status	Inherited status.
actlen	The actual amount of data retrived is written here. If not supplied, this information is not returned.
offset	An offset into the SDS structure to start fetch from, in bytes

Reimplemented in Arg.

Referenced by Arg::Get().

void SdsId::GetExternInfo	(	void **	data,
		StatusType *const	status
	)		const

inline

Return the address of an external item.

This method is used to determine the address of the buffer containing an external item, if this item refers to an external item. This is the value given the contructor which accessed this item.

See also: SdsId::SdsId(void *const data, StatusType *const status, const bool import)

Parameters

data	The address is written here.
status	Inherited status.

void SdsId::GetExtra	(	const unsigned long	length,
		char *const	extra,
		StatusType *const	status,
		unsigned long *	actlen = `0`
	)		const

inline

Get extra data from an SDS item.

This method accesses the extra data from an SDS item. The data is copied into the specified buffer.

See also: SdsGetExtra(); SdsId::PutExtra; SdsPutExtra()

Parameters

length	The amount of data to fetch.
extra	The buffer to fetch the data into, must of of size length or greater.
status	Inherited status.
actlen	The actual amount of data retrived is written here. If not supplied, this information is not returned.

void SdsId::GetName	(	char *const	name,
		StatusType *const	status
	)		const

inline

Return the name of the SDS item.

Just return the name of the underlying SDS item.

Note that if you want more then one of the items returned by SdsId::GetName, SdsId::Code and SdsId::Dims, then use SdsId::Info, it is more efficent.

See also: SdsId::Info; SdsInfo()

Parameters

name	The name of the SDS item is returned here. There should be space for SDS_C_NAMELEN (16) 16 bytes.
status	Inherited status.

void SdsId::Info	(	char *const	name,
		SdsCodeType *const	code,
		long *const	ndims,
		unsigned long *const	dims,
		StatusType *const	status
	)		const

inline

Return information about an SDS item.

This method returns all the standard information about an SDS item.

See also: SdsInfo(); SdsId::Code; SdsId::Dims; SdsId::Dims

Parameters

name	The name of the SDS item is returned here. There should be space for SDS_C_NAMELEN (16) 16 bytes.
code	The SDS item code is returned here..
ndims	The number of dimensions is returned here, 0 if the item is not an array, otherwise, 1 through 7.
dims	The dimensions are retuned here. This should be an array of 7 items.
status	Inherited status.

Referenced by Sdp::Get(), and Arg::Get().

void SdsId::Insert	(	SdsId &	to_insert,
		StatusType *const	status
	)

inline

Insert an SDS object into this object.

This method inserts an existing SDS structure into the SDS structure refered to by this object.

See also: SdsInsert()

Parameters

to_insert	The object to insert.
status	Inherited status.

void SdsId::Insert	(	SdsId &	to_insert,
		const long	ndims,
		const unsigned long *const	dims,
		StatusType *const	status
	)

inline

Insert an SDS object into this object, which is a structured array.

This object inserts a top level object into a structure array at a position specified by its indices. It deletes any object that is currently at that position.

See also: SdsInsertCell(); SdsId::FillArray

Parameters

to_insert	The object to insert.
ndims	The number of dimensions to the array. 1 through 7.
dims	The cell indicies.
status	Inherited status.

void SdsId::IsExternal	(	int *const	external,
		StatusType *const	status
	)		const

inline

Determine if the SDS structure is external.

This method is used to determine if the SDS object refered to by this object is an external object. Note that external objects cannot have their structure modified.

See also: SdsIsExternal()

Parameters

external	A non-zero value is written here if the object is external
status	Inherited status.

void SdsId::List ( StatusType *const status ) const

inline

List the contents of the structure to standard output.

See also: SdsList()

Parameters

status Inherited status.

void SdsId::List	(	FILE *	to,
		StatusType *const	status
	)		const

inline

List the contents of the structure to a C file.

See also: SdsList()

Parameters

status Inherited status.

SdsId::operator bool ( void ) const

inline

Operator which tests if an item is valid.

Returns: True if an item appears to be valid (the underlying SDS ID is non-zero).

SdsId::operator SdsIdType ( void ) const

inline

Operator which returns the underlying SDS id.

This operator allows the SdsId object to be used in calls to functions which expect an SdsIdType argument. Note that you must ensure that object is nether deleted or free-ed by whatever uses it. See SdsId::COut if that might happen.

See also: SdsId::COut

Returns: The underlying SDS ID value.

void SdsId::Outlive ( )

inline

Force the actual SDS ID to outlive the SdsId variable.

This method should be invoked if it is determined that the underlying SDS ID/Structure should outlive the SdsId object. Typically, this might be done if the underlying ID is passed to some other function

void SdsId::Pointer	(	void **	data,
		StatusType *const	status,
		unsigned long *	length = `0`
	)

inline

Object a pointer to the data area of a primitive SDS item.

Return a pointer to the data of a primitive item. If the data item is undefined and the object is internal, storage for the data will be created. This can only be used with primitive items, not with structures.

If necessary (e.g. if the data originated on a machine with different architecture) the data for the object is converted (in place) from the format stored in the data item to that required for the local machine

If the data pointed to by the pointer is updated by a calling program, the program should then call the function SdsFlush()/ SdsId::Flush to ensure that the data is updated in the original structure. This is necessary because implementations on some machine architectures may have to use a copy of the data rather than the actual data when returning a pointer.

See also: SdsPointer()

Parameters

data	The address of a item to return the pointer to.
status	Inherited status.
length	If specified, the length of the data is returned here.

virtual void SdsId::Put	(	const unsigned long	length,
		void *const	data,
		StatusType *const	status,
		const unsigned long	offset = `0`
	)

inlinevirtual

Put data into an SDS item.

This method put the data into an SDS item. The data is copied into the specified buffer.

Note that data from nested structures is also copied. Please see the SDS manual for more details on Put operations.

See also: SdsPut(); SdsId::Get; SdsId::Pointer; SdsGet()

Parameters

length	The amount of data to put.
data	The buffer of the data, must of of size length or greater.
status	Inherited status.
offset	An offset into the SDS structure to start fetch from, in bytes

Reimplemented in Arg.

Referenced by Arg::Put().

void SdsId::PutExtra	(	const long	nextra,
		const char *const	extra,
		StatusType *const	status
	)

inline

Put extra data into an SDS item.

This method puts the extra data from an SDS item. The data is copied into the specified buffer.

See also: SdsPutExtra(); SdsId::GetExtra; SdsGetExtra()

Parameters

nextra	The amount of data to put
extra	The buffer of the data, must of of size length or greater.
status	Inherited status.

void SdsId::Rename	(	const char *const	name,
		StatusType *const	status
	)

inline

Rename the SDS item.

See also: SdsRename()

Parameters

name	The new name, must be less then SDS_C_NAMELEN (16) bytes including the null terminator.
status	Inherited status.

void SdsId::Resize	(	const long	ndims,
		const unsigned long *	dims,
		StatusType *const	status
	)

inline

Change the dimensions of an SDS array.

This object must be an SDS array (either primitive or structured). This method resizes the arrary. Note that it does not move the data elements in the storage representing the array, so there is no guarantee that after resizing the array the same data will be found at the same array index positions as before resizing, though this will be the case for simple changes such as a change in the last dimension only.

If the size of a primitive array is increased the contents of the extra locations is undefined. Decreasing the size causes the data beyond the new limit to be lost.

If a structure array is extended the new elements created will be empty structures. If a structure array is decreased in size, the lost elements and all their components will be deleted.

See also: SdsResize()

Parameters

ndims	The number of dimensions
dims	The new dimensions
status	Inherited status.

void SdsId::SetDelete ( )

inline

Indicate the underlying SDS structure should be deleted when the SdsId object is destroyed.

See also: SdsId::OutLive()

void SdsId::SetFree ( )

inline

Indicate the underlying SDS item should be free-ed when the SdsId object is destroyed.

See also: SdsId::OutLive()

void SdsId::ShallowCopy	(	SdsId &	source,
		const bool	outlives = `true`
	)

inline

Shallow copy from SdsId.

Copy another SdsId item into this object. The existing SDS ID refered to by this object is first tidied up correctly. After the copy, both the source and this object refer to the same SDS structure. The outlives parameter must be set correctly to determine which one destroys the underlying SDS structure.

Note that if outlives is true, then write access is required to source - hence it cannot be const.

See also: SdsId::DeepCopy

Parameters

source	The Sds object to copy.
outlives	If true (default) this object is to outlive the source object.

Referenced by Arg::Arg(), DcppShared::DcppShared(), Sdp::Get(), and Arg::New().

void SdsId::ShallowCopy	(	const SdsIdType	source,
		const bool	free = `false`,
		const bool	del = `false`,
		const bool	readfree = `false`
	)

inline

Shallow copy from SdsIdType.

Copy an SdsIdType item into this object. The existing SDS ID refered to by this object is first tidied up correctly. After the copy, both the source and this object refer to the same SDS structure. The caller must indicate who has responsibility for cleaning up by setting appropiate flags.

See also: SdsId::DeepCopy

Parameters

source	The Sds object to copy.
free	If set true, this object will free the SDS id when it is destroyed.
del	If set true, this object will delete the underlying SDS object when it is destroyed.
readfree	If set true, this object will call SdsReadFree() when the object is destroyed.

void SdsId::Size	(	unsigned long *const	bytes,
		StatusType *const	status
	)		const

inline

Return the size of an SDS structure, as required for exporting.

See also: SdsId::Export; SdsSize()

Parameters

bytes	The number of bytes to allow for exporting this structure.
status	Inherited status.

void SdsId::SizeDefined	(	unsigned long *const	bytes,
		StatusType *const	status
	)		const

inline

Return the size of an SDS structure, as required for exporting defined.

See also: SdsId::ExportDefined; SdsSizeDefined()

Parameters

bytes	The number of bytes to allow for exporting this structure when all elements are defined.
status	Inherited status.

void SdsId::Write	(	const char *const	filename,
		StatusType *const	status
	)		const

inline

Write the contents of the structure to a file.

This method exports the SDS structure into a malloced buffer, before writing that buffer to a the specified file.

See also: SdsWrite()

Parameters

filename	The name of the file. Will be overwritten if it already exists.
status	Inherited status.

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

sds.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation