Detailed Description

A C++ Interface to the handling SDS structures.

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

An assortment of factory constructors are provided. Some of these access components of structures, some access external items and some create new SDS structures. The factory constructors may be static methods (when not accessing an existing item) or non-static when seeking to access or expand an existing SDS item.

Each sds::Id class object contains an SDS id which refers to an SDS structure, rather then a complete SDS structure and more then on sds::Id 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 destructor cleans up correctly.

The destructor will normally delete the underlying SDS item 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).

A "Move Assignment operator" and "Move Constructor" are provided, but non-move assignment and copying of these items is prohibited by deleting the operators. 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 should just a new ID to the same item generated. If the later, when would you expect the ID to be free-ed or the item itself deleted.

You can pass items to subroutines by reference or pointer to help get around the copy problem. You can also use the Copy() method to create a full copy an SDS item, or one of the ShallowCopy() methods to move ID's around. And move assignment/copy help a lot (thanks C++ 11).

In addition to methods implementing the full range of traditional SDS operations, there are also methods implementing the "Arg" style SDS interface layer. These are appropriate for constructing or reading the standard style DRAMA message arguments. There are a series of Put() and Get() methods which take the name of an item and operate in a similar method to the "ArgPut()" and "ArgGet()" series. There are constructors and methods which build these type of structures efficiently.

In most cases, any error returned by the underlying SDS C functions will result in a drama::Exception being thrown. The dramaStatus() method of the exception will contain the original SDS status code triggering the error. The exceptions are some of the methods for looking up parts of structures. Some of these have the option to return a null item if the requested item is not found, rather then throw an exception.

These are the Static Factory Constructors

drama::sds::Id::CreateFromSdsIdType Imports a SdsIdType ID into a sds::Id.
drama::sds::Id::CreateFromSdsIdTypeCopy Creates a sds::Id by coping the structure for which an SdsIdType ID is given.
drama::Sds::Id::CreateNullItem Creates a null SDS item. Normally only used to generate a variable which is will be a target in later operations.
drama::sds::Id::CreateByAccess Accesses an external SDS item.
drama::sds::Id::CreateByImport Imports an external SDS item.
drama::sds::Id::FromFile Reads an SDS item from a file.
drama::sds::Id::CreateTopLevel Creates a new top-level item.
drama::sds::Id::CreateTopLevelArray Creates a new top-level array item.
drama::sds::Id::CreateArgStruct Creates a DRAMA Argument style structure.
drama::sds::Id::CreateArgCmdStruct Creates a DRAMA Argument style structure and fills it with values.
drama::sds::Id::CreateArgCmdStructSingle Creates a DRAMA Argument style structure and insert one value.

These are the Non-Static Factory Constructor Methods

drama::sds::Id::CreateChildItem Creates a new child item.
drama::sds::Id::CreateChildArray Creates a new child array item.
drama::sds::Id::Cell Access a Cell of an array of structures.
drama::sds::Id::Copy Create a copy of the SDS object.
drama::sds::Id::Find Find an item in a structure by name.
drama::sds::Id::Index Find an item in a structure by index.

Warning: The "sds.h" include file also declares a very similar "SdsId" class. That class implements much of the same functionality but does not take advantage of C++ 11 feature, is not in a namespace and uses inherited status rather then exceptions. There are subtle differences in some areas, please read the documentation of the relevant method carefully.

See also: SDS Specification

Author: Tony Farrell, AAO

Revision: 1.45

Date: 22-Feb-2016 14:09:58+11

Examples:: argtest.cpp, dramahello.cpp, gitpathtest.cpp, and threadbasic.cpp.

#include "sds.hh"

Inheritance diagram for drama::sds::Id:

Public Member Functions
	Id (const Id &source)=delete
	Copy constructor - deleted. More...

	Id (Id &&source) noexcept
	Move copy constructor. More...

	Id ()
	Default constructor. More...

virtual	~Id ()
	sds::Id Destructor. More...

template<typename ContainerType >
void	AddToArgCmdStruct (const ContainerType &values, const unsigned firstArg=1)
	Insert a set of values from a container into an SDS structure in in the DRAMA Command style. More...

template<typename T >
void	ArrayAccess (ArrayAccessHelper< T > *const data) const
	Access the data of a single dimensional SDS primitive array item of a specified number of elements. More...

template<typename T >
void	ArrayAccess (const unsigned long nitems, sds::ArrayAccessHelper< T > *const data) const
	Access the data of a single dimensional SDS primitive item array of a specified number of elements. More...

template<typename T , class ContainerType >
void	ArrayAccess (ArrayAccessHelper< T > const data, long ndims, ContainerType dims) const
	Access the data of an SDS primitive item array. More...

template<typename T , class ContainerType >
void	ArrayAccess (ArrayAccessHelper< T > const data, ContainerType dims) const
	Access the data of an SDS primitive item array. More...

template<class ContainerType >
Id	Cell (const ContainerType &indicies, bool throwOnNotFound=true) const
	Factory constructor method Constructor that returns a cell of an existing id which must refer to an SDS array. More...

template<class ContainerType >
void	CheckItem (SdsCodeType code, const ContainerType &dims) const
	Check an item has a required structure. More...

virtual void	ClearDelete ()
	Indicate the underlying SDS structure should NOT be deleted when the sds::Id object is destroyed. More...

virtual Id	Copy () const
	Factory constructor method Id Copy constructor. More...

virtual 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...

template<class ContainerType >
Id	CreateChildArray (const std::string &name, const SdsCodeType code, const ContainerType &dims, const std::string &extra="") const
	Factory constructor method Constructor which creates a new child item which is an array. More...

virtual Id	CreateChildItem (const std::string &name, const SdsCodeType code, const std::string &extra="") const
	Factory constructor method which creates a new (non-array) child item. More...

virtual void	Delete ()
	Delete the SDS item. More...

virtual bool	Exists (const std::string &name) const
	Determine if a named item exists in a structure. More...

template<class ContainerType >
void	Export (ContainerType *container) const
	Export the SDS structure into a buffer. More...

template<class ContainerType >
void	ExportDefined (ContainerType *container) const
	Export the SDS structure into a buffer, defining any undefined data. More...

virtual void	Extract ()
	Extract the SDS structure from its parent. More...

virtual void	FillArray (const Id &elem)
	Fill out the contents of this object, which is a structured array. More...

virtual Id	Find (const std::string &name, bool throwOnNotFound=true) const
	Factory constructor method Constructor which returns a reference to a named item. More...

virtual void	Flush ()
	Flush data modified by pointer. More...

template<typename T >
void	Get (const unsigned long length, T const data, unsigned long actlen=nullptr, const unsigned long offset=0) const
	Get data from an SDS item. More...

template<typename T >
void	Get (const std::string &name, T *value) const
	Fetch primitive value from a named component of the structure. More...

template<typename T >
void	Get (T *value) const
	Fetch primitive value from the component. More...

virtual SdsCodeType	GetCode () const
	Return the code of the SDS item. More...

template<class ContainerType >
void	GetDims (ContainerType *dims) const
	Return the dimensions of the SDS item. More...

virtual double	GetDouble () const
	If the SDS item refers to a scalar value, convert it to a double item. More...

virtual std::string	GetExtra () const
	Get extra data from an SDS item. More...

virtual int	GetInt () const
	If the SDS item refers to a scalar value, convert it to an integer. More...

virtual long	GetLong () const
	If the SDS item refers to a scalar value, convert it to long integer. More...

virtual std::string	GetName () const
	Return the name of the SDS item. More...

unsigned	GetNumItems () const
	Return the number of components in an SDS structure. More...

std::string	GetString () const
	If the SDS item refers to a scalar value or a character string, convert it to a string item. More...

virtual unsigned int	GetUInt () const
	If the SDS item refers to a scalar value, convert it to an unsigned integer. More...

virtual unsigned long	GetULong () const
	If the SDS item refers to a scalar value, convert it to an unsigned long integer. More...

virtual Id	Index (const long index, bool throwOnNotFound=true) const
	Factory constructor method Constructor which returns an id to a structured item indexed by position. More...

virtual void	Insert (Id &to_insert)
	Insert an SDS object into this object. More...

template<class ContainerType >
void	Insert (Id &to_insert, const ContainerType &dims)
	Insert an SDS object into this object, which is a structured array. More...

virtual bool	IsExternal () const
	Determine if the SDS structure is external. More...

virtual void	List () const
	List the contents of the structure to standard output. More...

virtual void	List (FILE *to) const
	List the contents of the structure to a C file. More...

virtual void	List (std::ostream &strm, int lineMaxLen=100) const
	List the contents of the structure to an output stream. More...

virtual void	List (PrintObjectPnt *printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectPnt object. More...

virtual void	List (const PrintObjectCR &printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectCR. More...

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

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

Id &	operator= (const Id &rhs)=delete
	Assignment operator - deleted. More...

Id &	operator= (Id &&rhs) noexcept
	Move assignment operator. More...

virtual void	Outlive ()
	Force the actual SDS ID to outlive the sds::Id variable. More...

template<typename T >
void	Pointer (T *data, unsigned long length=0) const
	Obtain a pointer to the data area of a primitive SDS item. More...

template<typename T >
void	Put (const unsigned long length, const T *const data, const unsigned long offset=0)
	Put data into an SDS item. More...

template<typename T >
void	Put (const std::string &name, T value)
	Insert a primitive value into a named component of the structure. More...

void	Put (const std::string &name, const std::string &value)
	Insert a string value into a named component of the structure. More...

template<typename T >
void	Put (T value)
	Insert a primitive value into the item. More...

void	Put (const std::string &value)
	Insert a string value into the component. More...

virtual void	PutExtra (const std::string &extra)
	Put extra data into an SDS item. More...

virtual void	Rename (const std::string &name)
	Rename the SDS item. More...

template<class ContainerType >
void	Resize (const ContainerType &dims)
	Change the dimensions of an SDS array. More...

virtual void	SetDelete ()
	Indicate the underlying SDS structure should be deleted when the sds::Id object is destroyed. More...

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

virtual void	ShallowCopy (const Id &source)
	Shallow copy from a const sds::Id which will outlive this object. More...

virtual void	ShallowCopy (Id *source, const bool outlives)
	Shallow copy from sds::Id. More...

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

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

virtual unsigned long	SizeDefined () const
	Return the size of an SDS structure, as required for exporting when fully defined. More...

virtual std::string	toString (int maxlen=200)
	Convert the structure to a string. More...

virtual void	ValidateCode (SdsCodeType requiredCode) const
	Validate the code of the SDS item. More...

virtual void	Write (const std::string &filename) const
	Write the contents of the structure to a file. More...

Static Public Member Functions
template<typename ContainerType >
static Id	CreateArgCmdStruct (const ContainerType &values, const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style. More...

template<typename T >
static Id	CreateArgCmdStructSingle (const T value, const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style. More...

static Id	CreateArgStruct (const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure. More...

template<class ContainerType >
static Id	CreateByAccess (ContainerType *container)
	Factory constructor method that accesses an exported SDS structure found in a byte stream. More...

template<class ContainerType >
static Id	CreateByImport (const ContainerType &container)
	Factory constructor method that imports an exported SDS structure found in a byte stream. More...

static Id	CreateFromSdsIdType (const SdsIdType item, const bool free=false, const bool del=false, const bool readfree=false)
	Factory constructor method that constructs an sds::Id item from an existing C language SDS id. More...

static Id	CreateFromSdsIdTypeCopy (const SdsIdType item)
	Factory constructor method that constructs an sds::Id item by coping an existing C language SDS id. More...

static Id	CreateNullItem ()
	Factory constructor method that constructs an null sds::Id item . More...

static Id	CreateTopLevel (const std::string &name, const SdsCodeType code, const std::string &extra="")
	Constructor which creates a new (non-array) top-level item. More...

template<class ContainerType >
static Id	CreateTopLevelArray (const std::string &name, const SdsCodeType code, const ContainerType &dims, const std::string &extra="")
	Factory constructor method Constructor which creates a new array top-level item. More...

static Id	FromFile (const std::string &filename)
	Factory constructor method that reads an SDS structure from a file. More...

Constructor & Destructor Documentation

drama::sds::Id::Id ( const Id & source )

delete

Copy constructor - deleted.

Not possible to copy sds::Id objects as we then don't know when the underlying SDS object should be cleaned up.

A Move constructor is available and deals with most relevant cases of interest.

See also: drama::sds::ShallowCopy; drama::sds::Copy

drama::sds::Id::Id ( Id && source )

inlinenoexcept

Move copy constructor.

Often optimized out using the "copy elision" rule.

drama::sds::Id::Id ( )

inline

Default constructor.

Creates an empty SDS id object. Only of use as a target for move assignments and ShallowCopy() operations.

virtual drama::sds::Id::~Id ( )

inlinevirtual

sds::Id 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 achieved and all resources are released.

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

Reimplemented in drama::gitarg::Id.

Member Function Documentation

template<typename ContainerType >

void drama::sds::Id::AddToArgCmdStruct	(	const ContainerType &	values,
		const unsigned	firstArg = `1`
	)

inline

Insert a set of values from a container into an SDS structure in in the DRAMA Command style.

This method adds a new set of values to an existing SDS structure. The values are all of the same type and are given the names Argument<n>, Argument<n+1> etc, where <n> is an integer given by the "firstArg" argument.

This method can be used to fill out value in an existing DRAMA Command style ArgStructure item.

See also: drama::sds::CreateArgCmdStruct()

Template Parameters

ContainerType For the container itself, any acceptable to a "for" loop with "auto" range should work (so any STL container and C style arrays). The item within the container must be acceptable to the drama::sds::Id::Put() with name methods, e.g. bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representation std::string.

Parameters

values	The values to be inserted into the structure.
firstArg	The number associated with the first item in the structure. By setting this you can build a structure in various calls

References Put().

template<typename T >

void drama::sds::Id::ArrayAccess ( ArrayAccessHelper< T > *const data ) const

inline

Access the data of a single dimensional SDS primitive array item of a specified number of elements.

Accesses an array using an ArrayWriteHelper or ArrayReadHelper of the appropriate 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 sds::AccessArrayHelper:: class for more information.

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

In this example, we instantiate value to provide access to an array of SDS short items.

   sds::Id structure;
   ...
   sds::ArrayReadHelper<short> value;
   structure.ArrayAccess(&value);
   unsigned long count = value.Size();
   for (unsigned long i = 0; i < count ; ++i)
       printf("Element %ld = %d\\n", i, (int)value[i]);

See also: sds::ArrayAccessHelper; sds::ArrayWriteHelper; sds::ArrayReadHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be an Instantiation of a sub-class of ArrayAccessHelper appropiate for type T.

Template Parameters

T	The array access helper to use.

References drama::sds::ArrayAccessHelper< T >::Code().

Referenced by ArrayAccess().

template<typename T >

void drama::sds::Id::ArrayAccess	(	const unsigned long	nitems,
		sds::ArrayAccessHelper< T > *const	data
	)		const

inline

Access the data of a single dimensional SDS primitive item array of a specified number of elements.

Accesses an array using an ArrayWriteHelper or ArrayReadHelper of the appropriate 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.

In this example, we instantiate value to provide access to an array of 10 SDS short items.

   sds::Id structure;
   ...
   sds::ArrayReadHelper<short> value;
   structure.ArrayAccess(10, &value);
   for (unsigned long i = 0; i < 10 ; ++i)
      printf("Element %ld = %d\\n", i, (int)value[i]);

See also: sds::ArrayAccessHelper; sds::ArrayWriteHelper; sds::ArrayReadHelper

Parameters

nitems	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 an Instantiations of a sub-class of ArrayAccessHelper appropriate for type T.

Template Parameters

T	The array access helper to use.

References drama::sds::ArrayAccessHelper< T >::Code(), and DramaTHROW_S.

template<typename T , class ContainerType >

void drama::sds::Id::ArrayAccess	(	ArrayAccessHelper< T > *const	data,
		long	ndims,
		ContainerType *	dims
	)		const

inline

Access the data of an SDS primitive item array.

Number of dimensions specified, actual size from data.

Accesses an array using an ArrayWriteHelper or ArrayReadHelper of the appropriate 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 sds::ArrayAccessHelper:: 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, we instantiate value to provide access to a 1 dimensional array of SDS short items.

   sds::Id structure;
   ...
   std::vector<unsigned long> dims;
   sds::ArrayAccessHelper<short> value;
   structure.ArrayAccess(&value, 1, &dims);
   for (unsigned long i = 0; i < dims[0] ; ++i)
       printf("Element %ld = %d\\n", i, (int)value[i]);

See also: sds::ArrayWriteHelper; sds::ArrayReadHelper; sds::ArrayAccessHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be an Instantiations of a sub-class of ArrayAccessHelper appropriate for type T.
ndims	The number of dimensions there should be in the structure.
dims	The dimensions are written to this array. This container will be cleared and then push_back() applied up to 7 times.

Template Parameters

T	The array access helper to use.
ContainerType	A container with clear() and push_back() methods. The push_back() method must accept unsigned long items.

References drama::sds::ArrayAccessHelper< T >::Code(), and DramaTHROW_S.

template<typename T , class ContainerType >

void drama::sds::Id::ArrayAccess	(	ArrayAccessHelper< T > *const	data,
		ContainerType *	dims
	)		const

inline

Access the data of an SDS primitive item array.

Any dimensions.

Accesses an array using an ArrayWriteHelper or ArrayReadHelper of the appropriate 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, we instantiate value to provide access to an array of SDS short items, of unknown dimensions.

   sds::Id structure;
   ...
   std::vector<unsigned long> dims;
   sds::ArrayAccessHelper value;
   structure.ArrayAccess(&value, dims);
   unsigned long count = value.Size();
   for (unsigned long i = 0; i < count ; ++i)
        printf("Element %ld = %d\\n", i, (int)value[i]);

See also: sds::ArrayAccessHelper; sds::ArrayWriteHelper; sds::ArrayReadHelper

Parameters

data	A pointer to an object which allows you to access the underlying SDS data. It must be an Instantiations of a sub-class ArrayAccessHelper appropriate for type T.
dims	The dimensions are written to this array. This is the address of a container. The container is cleared before the dimensions are pushed into it.

Template Parameters

T	The array access helper to use.
ContainerType	A container with clear() and push_back() methods. The push_back() method must accept unsigned long items.

References ArrayAccess(), and GetDims().

template<class ContainerType >

Id drama::sds::Id::Cell	(	const ContainerType &	indicies,
		bool	throwOnNotFound = `true`
	)		const

inline

Factory constructor method Constructor that returns a cell of an existing id which must refer to an SDS array.

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

The object on which the method is invoked must reference an SDS Array (rather then an SDS structure or primitive). It must also be an internal item (rather then external).

Note that if working through a one dimensional structure array (incrementing the index), then you might find drama::sds::IdIterator provides a neater solution over a loop calling this method.

See also: SdsCell().; drama::sds::IdIterator

Parameters

indicies An container giving the indicies of the cell in question. A maximum of 7 dimensions are supported.

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of unsigned long.

Parameters

throwOnNotFound If true (default), will throw an exception if the an item of the index does not exist. Otherwise will return a null SDS item. Any other errors will cause an exception to be thrown regardless.

References DramaTHROW, and DramaTHROW_S.

Referenced by drama::sds::IdIterator::operator*().

template<class ContainerType >

void drama::sds::Id::CheckItem	(	SdsCodeType	code,
		const ContainerType &	dims
	)		const

inline

Check an item has a required structure.

A common requirement for the user of the SDS library is to check that a specified SDS item has the right format - type code, number of dimensions and dimensions. This utility function implements such a check.

See also: ArgCheckItem()

Parameters

code	SDS Code we expect. The normal SDS code values, or ARG_STRING, in which case we mean SDS_CHAR but the ndims value is bumped by 1 automatically. If specified as -1, then the code is ignored.
dims	The expected dimensions.

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of long (not unsigned long as used elsewhere.)

References DramaTHROW, and DramaTHROW_S.

virtual void drama::sds::Id::ClearDelete ( )

inlinevirtual

Indicate the underlying SDS structure should NOT be deleted when the sds::Id object is destroyed.

This should be considered if the SDS object refers to must outlive the object.

See also: sds::Id::OutLive()

virtual Id drama::sds::Id::Copy ( ) const

virtual

Factory constructor method Id Copy constructor.

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

Warning: If the current object refers to a null SDS item, then the result is a null id, rather then an error being thrown.

See also: SdsCopy().

Examples:: argtest.cpp.

Referenced by drama::Parameter< drama::sds::Id >::Set(), and drama::thread::TAction::SetReturnArg().

virtual SdsIdType drama::sds::Id::COut	(	const bool	outlives,
		bool *const	free = `0`,
		bool *const	del = `0`,
		bool *const	readfree = `0`
	)

inlinevirtual

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 inquiry 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 drama::MessageHandler::SetReturnArg().

template<typename ContainerType >

static Id drama::sds::Id::CreateArgCmdStruct	(	const ContainerType &	values,
		const std::string &	name = `"ArgStructure"`
	)

inlinestatic

Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style.

This static factory drama::sds::Id constructor creates a new top level SDS item of type SDS_STRUCT. This style of structure is commonly used for action arguments within DRAMA.

It then uses the values supplied in the values argument to create a typical DRAMA command argument structure.

See also: ArgNew(); drama::sds::AddToArgCmdStruct()

Template Parameters

ContainerType For the container itself, any acceptable to a "for" loop with "auto" range should work (so any STL container and C style arrays). The item within the container must be acceptable to the drama::sds::Id::Put() with name methods, e.g. bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representation std::string.

Parameters

values	The values to be inserted into the structure.
name	The name for the structure. The default is what is normally supplied by the ArgNew() function, but any name acceptable to SDS can be specified.

References CreateArgStruct(), and Put().

Referenced by drama::Path::GetParam(), drama::Path::GetParamWaitUntil(), and drama::Path::MonitorCancel().

template<typename T >

static Id drama::sds::Id::CreateArgCmdStructSingle	(	const T	value,
		const std::string &	name = `"ArgStructure"`
	)

inlinestatic

Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style.

This static factory drama::sds::Id constructor creates a new top level SDS item of type SDS_STRUCT. This style of structure is commonly used for action arguments within DRAMA.

It then uses the single value supplied to generate the first item in a typical DRAMA command argument structure.

This method provides a quick way of generating an argument structure with on item.

See also: ArgNew(); drama::sds::AddToArgCmdStruct()

Template Parameters

T	The type must be acceptable to the drama::sds::Id::Put() with name methods, e.g. bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representation std::string.

Parameters

value	The value to be inserted into the structure.
name	The name for the structure. The default is what is normally supplied by the ArgNew() function, but any name acceptable to SDS can be specified.

References CreateArgStruct(), and Put().

static Id drama::sds::Id::CreateArgStruct ( const std::string & name = "ArgStructure" )

static

Factory constructor which creates a new "Arg" style SDS structure.

This static factory drama::sds::Id constructor creates a new top level SDS item of type SDS_STRUCT. This style of structure is commonly used for action arguments within DRAMA.

See also: ArgNew()

Parameters

name	The name for the structure. The default is what is normally supplied by the ArgNew() function, but any name acceptable to SDS can be specified.

Examples:: argtest.cpp, and threadbasic.cpp.

Referenced by CreateArgCmdStruct(), and CreateArgCmdStructSingle().

template<class ContainerType >

static Id drama::sds::Id::CreateByAccess ( ContainerType * container )

inlinestatic

Factory constructor method that accesses an exported SDS structure found in a byte stream.

This static factory sds::Id constructor uses SdsAccess() to get access an SDS structure stored in an external byte stream.

SDS accesses the data in place and may modify it the data values. But the structure layout cannot be modified.

See also: SdsAccess().; sds::Id::Import

Template Parameters

ContainerType A container for which "&container[0]" will return the address of a byte array into which the data can be written. The empty() method is also applied. E.g. std::array<unsigned char> or std::vector<unsigned char>. The container must be a container of POD types, if not, compile will fail with a static assertion.

Parameters

container The buffer to read the data from. Must not be deallocated or reallocated until the SDS object create by this constructor is destroyed. Note, SDS can modify this buffer.

References DramaTHROW.

template<class ContainerType >

static Id drama::sds::Id::CreateByImport ( const ContainerType & container )

inlinestatic

Factory constructor method that imports an exported SDS structure found in a byte stream.

This static factory sds::Id constructor uses SdsImport() to imported an SDS structure stored in a byte stream into SDS. Since the result is an internal SDS item, the structure can be modified (both data values and layout).

See also: SdsImport().; sds::Id::Access

Template Parameters

ContainerType A container for which "&container[0]" will return the address of a byte array into which the data can be written. The empty() method is also applied. E.g. std::array<unsigned char> or std::vector<unsigned char>. The container must be a container of POD types, if not, compile will fail with a static assertion.

Parameters

container The buffer to read the data from.

References DramaTHROW.

template<class ContainerType >

Id drama::sds::Id::CreateChildArray	(	const std::string &	name,
		const SdsCodeType	code,
		const ContainerType &	dims,
		const std::string &	extra = `""`
	)		const

inline

Factory constructor method Constructor which creates a new child item which is an array.

This non-static factory sds::Id constructor creates a new SDS array item which is a child of this SDS item.

The object on which the method is invoked must reference an SDS Structure item (rather then an array or primitive). It must also be an internal item (rather then external).

See also: SdsNew()

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item. A maximum of 7 dimensions are supported.
dims	A container giving each dimension. A maximum of 7 dimensions are supported
extra	The extra data, if any. Defaults to none.

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of unsigned long.

References DramaTHROW_S.

virtual Id drama::sds::Id::CreateChildItem	(	const std::string &	name,
		const SdsCodeType	code,
		const std::string &	extra = `""`
	)		const

virtual

Factory constructor method which creates a new (non-array) child item.

This non-static factory sds::Id constructor creates a new SDS item which is a child of this SDS item.

The object on which the method is invoked must reference an SDS Structure item (rather then an array or primitive). It must also be an internal item (rather then external).

See also: SdsNew()

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item.
extra	The extra data, if any. Defaults to none.

static Id drama::sds::Id::CreateFromSdsIdType	(	const SdsIdType	item,
		const bool	free = `false`,
		const bool	del = `false`,
		const bool	readfree = `false`
	)

static

Factory constructor method that constructs an sds::Id item from an existing C language SDS id.

This static factory sds::Id constructor that takes an existing SDS ID (C style) and creates an sds::Id class object which refers to that SDS id. You must explicitly 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 to be wrapped in an sds::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.

Referenced by drama::EntryInfo::Argument(), and drama::Parameter< INT32 >::Parameter().

static Id drama::sds::Id::CreateFromSdsIdTypeCopy ( const SdsIdType item )

static

Factory constructor method that constructs an sds::Id item by coping an existing C language SDS id.

This static factory sds::Id constructor that takes an existing SDS ID (C style) and creates an sds::Id object referring to a copy of that item.

Parameters

item	The SdsIdType of the item to be copied.

static Id drama::sds::Id::CreateNullItem ( )

static

Factory constructor method that constructs an null sds::Id item .

The sds::Id 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 move assignment or sds::Id::ShallowCopy() to set the underlying SDS ID. It can also be used for variables which to which the result of another constructor will be assigned directly (e.g. the move assignment operated can be invoked on it).

Referenced by drama::Path::GetParam(), and drama::Path::GetParamWaitUntil().

static Id drama::sds::Id::CreateTopLevel	(	const std::string &	name,
		const SdsCodeType	code,
		const std::string &	extra = `""`
	)

static

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

This static factory sds::Id constructor creates a new SDS top-level SDS item.

See also: SdsNew()

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item.
extra	The extra data, if any. Defaults to none.

template<class ContainerType >

static Id drama::sds::Id::CreateTopLevelArray	(	const std::string &	name,
		const SdsCodeType	code,
		const ContainerType &	dims,
		const std::string &	extra = `""`
	)

inlinestatic

Factory constructor method Constructor which creates a new array top-level item.

This static factory sds::Id constructor creates a new SDS array which is a top-level SDS item.

See also: SdsNew()

Parameters

name	The name for the new SDS item.
code	The SDS code for the new item.
dims	A container giving each dimension. A maximum of 7 dimensions are supported
extra	The extra data, if any. Defaults to none.

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of unsigned long.

References DramaTHROW_S.

virtual void drama::sds::Id::Delete ( )

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.

The object on which the method is invoked must reference an internal SDS item (rather then external).

See also: SdsDelete(); SdsFreeId()

References DramaTHROW.

Referenced by drama::Parameter< drama::sds::Id >::Set().

virtual bool drama::sds::Id::Exists ( const std::string & name ) const

virtual

Determine if a named item exists in a structure.

Searches an existing SDS item for a item with a specified name, returned true if it exists.

The object on which the method is invoked must reference an SDS Structure item (rather then an array or primitive).

See also: SdsFind()

Parameters

name	The name of the SDS item to find.

Referenced by drama::Parameter< drama::sds::Id >::Set().

template<class ContainerType >

void drama::sds::Id::Export ( ContainerType * container ) const

inline

Export the SDS structure into a buffer.

The SDS structure refered to by this sds::Id 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 sds::Id::ExportDefined method.

See also: SdsExport(); sds::Id::ExportDefined

Template Parameters

ContainerType A container that has a size() method and for which "&container[0]" will return the address of a byte array into which the data can be written. The size() method is used to retrieve the available memory space. E.g. std::array<unsigned char> or std::vector<unsigned char>. The container must be a container of POD types, if not, compile will fail with a static assertion.

Parameters

container The buffer to write the data into.

References DramaTHROW.

template<class ContainerType >

void drama::sds::Id::ExportDefined ( ContainerType * container ) const

inline

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

The SDS structure refered to by this sds::Id 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(); sds::Id::Export

Template Parameters

ContainerType A container that has a size() method and for which "&container[0]" will return the address of a byte array into which the data can be written. E.g. std::array<unsigned char> or std::vector<unsigned char>. The container must be a container of POD types, if not, compile will fail with a static assertion

Parameters

container The buffer to write the data into.

References DramaTHROW.

virtual void drama::sds::Id::Extract ( )

inlinevirtual

Extract the SDS structure from its parent.

This method is normally applied to an sds::Id object which refers to a child of another SDS structure. This method extracts the child such that this item is now a top-level SDS structure.

The object on which the method is invoked must reference an internal SDS item (rather then external).

The referenced SDS item will now be deleted when the destructor is run on the object (unless sds::Id::ClearDelete is invoked).

See also: SdsExtract(); sds::Id::Pointer; SdsPointer()

References DramaTHROW.

virtual void drama::sds::Id::FillArray ( const Id & elem )

inlinevirtual

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 structure.

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

Parameters

elem	The item to copy into the structure.

References DramaTHROW.

virtual Id drama::sds::Id::Find	(	const std::string &	name,
		bool	throwOnNotFound = `true`
	)		const

virtual

Factory constructor method Constructor which returns a reference to a named item.

This non-static factory constructor searches an existing SDS item for a item with a specified name and creates a reference to it, which is returned.

The object on which the method is invoked must reference an SDS Structure item (rather then an array or primitive).

See also: SdsFind()

Parameters

name	The name of the SDS item to find.
throwOnNotFound	If true (default), will throw an exception if the an item of the name specified does not exist. Otherwise will return a null SDS item. Any other errors will cause an exception to be thrown regardless.

Referenced by drama::Parameter< drama::sds::Id >::Get(), drama::Parameter< drama::sds::Id >::Set(), and drama::Parameter< drama::sds::Id >::UpdateMonitors().

virtual void drama::sds::Id::Flush ( )

inlinevirtual

Flush data modified by pointer.

When the data of an SDS is modified via a pointer obtained by SdsPointer() or sds::Id::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()

References DramaTHROW.

Referenced by drama::sds::DataPointer< T >::~DataPointer(), and drama::sds::DataPointer< T[]>::~DataPointer().

static Id drama::sds::Id::FromFile ( const std::string & filename )

static

Factory constructor method that reads an SDS structure from a file.

This static factory sds::Id constructor reads an SDS structure from the specified file, it should contain an SDS structure created using SdsWrite() or sds::Id::Write.

See also: sds::Id::Write; SdsWrite(); SdsRead()

Parameters

filename Name of the file.

Examples:: argtest.cpp.

template<typename T >

void drama::sds::Id::Get	(	const unsigned long	length,
		T *const	data,
		unsigned long *	actlen = `nullptr`,
		const unsigned long	offset = `0`
	)		const

inline

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(); sds::Id::Pointer; sds::Id::Put; SdsPut()

Template Parameters

T	The type of the data item. This needs to be a POD type, if not, compile will fail with a static assertion.

Parameters

length	The amount of data to fetch.
data	The buffer to put the data info, must of of size length or greater.
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

Examples:: argtest.cpp, dramahello.cpp, and threadbasic.cpp.

References DramaTHROW.

template<typename T >

void drama::sds::Id::Get	(	const std::string &	name,
		T *	value
	)		const

inline

Fetch primitive value from a named component of the structure.

If the named item exists within the SDS structure then fetch its value and convert it to the type of the template argument, if possible.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also std::string.

This is equivalent to the ArgGet series of C level calls, used for building up DRAMA command arguments.

Template Parameters

T	The SDS primitive type you wish to fetch

Parameters

name	The name of the item within the SDS structure.
value	The value retrieved will be written here.

References DramaTHROW_S.

template<typename T >

void drama::sds::Id::Get ( T * value ) const

inline

Fetch primitive value from the component.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also std::string.

Template Parameters

T	The SDS primitive type you wish to fetch

Parameters

value The value retrieved will be written here.

References DramaTHROW.

virtual SdsCodeType drama::sds::Id::GetCode ( ) const

inlinevirtual

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 sds::Id::GetName, sds::Id::Code and sds::Id::Dims, then use sds::Id::Info, it is more efficient.

See also: SdsInfo(); SdsGetCode()

Returns: The SDS item code.

References DramaTHROW.

Referenced by drama::sds::IdIterator::IdIterator().

template<class ContainerType >

void drama::sds::Id::GetDims ( ContainerType * dims ) 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 sds::Id::GetName, sds::Id::Code and sds::Id::Dims, then use sds::Id::Info, it is more efficent.

See also: SdsGetDims(); SdsInfo()

Parameters

dims	The dimensions are retuned here. This is the address of a container. The container is cleared before the dimensions are pushed into it.

Template Parameters

ContainerType A container with "clear()" and "push_back()" methods. The push_back() must accept unsigned long items.

References DramaTHROW.

Referenced by ArrayAccess(), and drama::sds::IdIterator::IdIterator().

virtual double drama::sds::Id::GetDouble ( ) const

virtual

If the SDS item refers to a scalar value, convert it to a double item.

Returns: The converted value is returned here.

virtual std::string drama::sds::Id::GetExtra ( ) const

inlinevirtual

Get extra data from an SDS item.

This method accesses the extra data from an SDS item. If nothing is available, then an empty string is returned.

See also: SdsGetExtra(); sds::Id::PutExtra; SdsPutExtra()

References DramaTHROW.

virtual int drama::sds::Id::GetInt ( ) const

virtual

If the SDS item refers to a scalar value, convert it to an integer.

Returns: The converted value is returned here.

virtual long drama::sds::Id::GetLong ( ) const

virtual

If the SDS item refers to a scalar value, convert it to long integer.

Returns: The converted value is returned here.

virtual std::string drama::sds::Id::GetName ( ) const

inlinevirtual

Return the name of the SDS item.

Just return the name of the underlying SDS item.

See also: SdsInfo(); SdsGetName()

References DramaTHROW.

Referenced by ValidateCode().

unsigned drama::sds::Id::GetNumItems ( ) const

inline

Return the number of components in an SDS structure.

This method returns the maximum value which can be supplied to sds::Index().

See also: SdsIndex()

References DramaTHROW.

std::string drama::sds::Id::GetString ( ) const

If the SDS item refers to a scalar value or a character string, convert it to a string item.

Returns: The converted value is returned here.

virtual unsigned int drama::sds::Id::GetUInt ( ) const

virtual

If the SDS item refers to a scalar value, convert it to an unsigned integer.

Returns: The coverted value is returned here.

virtual unsigned long drama::sds::Id::GetULong ( ) const

virtual

If the SDS item refers to a scalar value, convert it to an unsigned long integer.

Returns: The coverted value is returned here.

virtual Id drama::sds::Id::Index	(	const long	index,
		bool	throwOnNotFound = `true`
	)		const

virtual

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

This non-static factory constructor uses the specified index to find an item within an SDS structure.

The object on which the method is invoked must reference an SDS Structure item (rather then an array or primitive).

Note that if working through a structure (incrementing index), then you might find drama::sds::IdIterator provides a neater solution over a loop calling this method.

See also: SdsIndex(); drama::sds::IdIterator

Parameters

index	The index of the item fo find. Items in a structure are numbered in order of creation starting with one.
throwOnNotFound	If true (default), will throw an exception if the the index does not exist. Otherwise will return a null SDS item. Any other errors will cause an exception to be thrown regardless.

Referenced by drama::sds::IdIterator::operator*().

virtual void drama::sds::Id::Insert ( Id & to_insert )

inlinevirtual

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.

References DramaTHROW.

Referenced by drama::Parameter< drama::sds::Id >::Set().

template<class ContainerType >

void drama::sds::Id::Insert	(	Id &	to_insert,
		const ContainerType &	dims
	)

inline

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

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

See also: SdsInsertCell(); sds::Id::FillArray

Parameters

to_insert	The object to insert.
dims	The cell indicies. A container giving each index. It must be possible to convert the elements to unsigned long int and a maximum of 7 dimensions are supported.

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of unsigned long.

References DramaTHROW, and DramaTHROW_F.

virtual bool drama::sds::Id::IsExternal ( ) const

inlinevirtual

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()

Returns: True if item is external.

References DramaTHROW.

virtual void drama::sds::Id::List ( ) const

inlinevirtual

List the contents of the structure to standard output.

See also: SdsList()

Examples:: argtest.cpp, and dramahello.cpp.

References DramaTHROW.

virtual void drama::sds::Id::List ( FILE * to ) const

inlinevirtual

List the contents of the structure to a C file.

See also: SdsList()

References DramaTHROW.

virtual void drama::sds::Id::List	(	std::ostream &	strm,
		int	lineMaxLen = `100`
	)		const

virtual

List the contents of the structure to an output stream.

See also: SdsList()

Parameters

strm	The stream to output the listing too.
lineMaxLen	A maximum length for each line. Due to the structure of the underlying code, you need so specify this and may want to set it appropriately for your terminal width or similar.

virtual void drama::sds::Id::List	(	PrintObjectPnt *	printer,
		int	lineMaxLen = `100`
	)		const

virtual

List the contents of the structure via a PrintObjectPnt object.

The "Print(const std::string &)" method of the printer is invoked for each line of detail from an SDS Structure listing.

PrintObjectPnt is an abstract class. The user should supply a sub-class to do the job.

This version should be used if your printer object must change its internal state, a pointer to the printer must be supplied.

See also: SdsList()

Parameters

printer	An object sub-classed from PrintObject, the (non-const) Print method of which will be invoked for each line in the listing.
lineMaxLen	A maximum length for each line. Due to the structure of the underlying code, you need so specify this.

virtual void drama::sds::Id::List	(	const PrintObjectCR &	printer,
		int	lineMaxLen = `100`
	)		const

virtual

List the contents of the structure via a PrintObjectCR.

The "Print(const std::string &) const" method of the printer is invoked for each line of detail from an SDS Structure listing.

PrintObjectCR is an abstract class. The user should supply a sub-class to do the job.

This version can be used if your printer object does not change its internal state

See also: SdsList()

Parameters

printer	An object sub-classed from PrintObject, the (const) Print method of which will be invoked for each line in the listing.
lineMaxLen	A maximum length for each line. Due to the structure of the underlying code, you need so specify this.

drama::sds::Id::operator bool ( ) const

inlineexplicit

Operator which tests if an item is valid.

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

drama::sds::Id::operator SdsIdType ( ) const

inlineexplicit

Operator which returns the underlying SDS id.

This operator allows the sds::Id 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 sds::Id::COut() if that might happen.

See also: sds::Id::COut

Returns: The underlying SDS ID value.

Id& drama::sds::Id::operator= ( const Id & rhs )

delete

Assignment operator - deleted.

Not possible to assign sds::Id objects as we then don't know when the underlying SDS object should be cleaned up.

A Move assignment operator is available and deals with most relevant cases of interest.

See also: drama::sds::ShallowCopy; drama::sds::Copy

Id& drama::sds::Id::operator= ( Id && rhs )

inlinenoexcept

Move assignment operator.

Often optimized out using the "copy elision" rule.

virtual void drama::sds::Id::Outlive ( )

inlinevirtual

Force the actual SDS ID to outlive the sds::Id variable.

This method should be invoked if it is determined that the underlying SDS ID/Structure should outlive the sds::Id object.

Typically, this might be done if the underlying ID is passed to some other function.

template<typename T >

void drama::sds::Id::Pointer	(	T **	data,
		unsigned long *	length = `0`
	)		const

inline

Obtain 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()/ sds::Id::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.

Warning: This operation's const-ness depends on your point of view. It does not in itself change the underlying SDS structure or its contents, but one you have a pointer, you could change the data.

See also: SdsPointer(); SdsFlush(); sds::Id::Flush

Template Parameters

T	The type of the data item. This needs to be a POD type, if not, compile will fail with a static assertion.

Parameters

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

References DramaTHROW.

Referenced by drama::sds::DataPointer< T >::DataPointer(), and drama::sds::DataPointer< T[]>::DataPointer().

template<typename T >

void drama::sds::Id::Put	(	const unsigned long	length,
		const T *const	data,
		const unsigned long	offset = `0`
	)

inline

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(); sds::Id::Get; sds::Id::Pointer; SdsGet()

Template Parameters

T	The type of the data item. This needs to be a POD type, if not, compile will fail with a static assertion.

Parameters

length	The length of the data to put.
data	The buffer of the data, must of of size length or greater.
offset	An offset into the SDS structure to start putting the data from. By elements.

Examples:: argtest.cpp.

References DramaTHROW.

Referenced by AddToArgCmdStruct(), CreateArgCmdStruct(), CreateArgCmdStructSingle(), and drama::Parameter< INT32 >::Parameter().

template<typename T >

void drama::sds::Id::Put	(	const std::string &	name,
		T	value
	)

inline

Insert a primitive value into a named component of the structure.

The named item is created in the SDS structure if it does not already exist and the specified value inserted.

If the named item already exists, then the value is converted to that type (if possible) and inserted.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representations char* and std::string.

bool is represented by an SDS type SDS_USHORT. char * and std::string are put in arrays of SDS_CHAR items.

This is equivalent to the ArgPut series of C level calls, used for building up DRAMA command arguments.

Template Parameters

T	The SDS primitive you wish to insert.

Parameters

name	The name of the item within the SDS structure.
value	The value to be inserted.

References DramaTHROW_S.

void drama::sds::Id::Put	(	const std::string &	name,
		const std::string &	value
	)

inline

Insert a string value into a named component of the structure.

Specialization for putting an std::string item into a structure Needed because we can't get this right using the template Put.

Parameters

name	The name of the item within the SDS structure.
value	The value to be inserted.

References DramaTHROW_S.

template<typename T >

void drama::sds::Id::Put ( T value )

inline

Insert a primitive value into the item.

The current item should be a scalar item. The supplied value is converted if required and inserted.

Supports the various primitive types - bool, char, short, unsigned short, INT32, UINT32, INT64, UINT64, float and double. Also the string representations char* and std::string.

bool is represented by an SDS type SDS_USHORT. char * and std::string are put in arrays of SDS_CHAR items.

Template Parameters

T	The SDS primitive you wish to insert.

Parameters

value The value to be inserted.

References DramaTHROW.

void drama::sds::Id::Put ( const std::string & value )

inline

Insert a string value into the component.

Specialization for putting an std::string item into a structure Needed because we can't get this right using the template.

Parameters

value The value to be inserted.

References DramaTHROW.

virtual void drama::sds::Id::PutExtra ( const std::string & extra )

inlinevirtual

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(); sds::Id::GetExtra; SdsGetExtra()

Parameters

extra The extra data, if any.

References DramaTHROW.

virtual void drama::sds::Id::Rename ( const std::string & name )

inlinevirtual

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.

References DramaTHROW.

Referenced by drama::Parameter< drama::sds::Id >::Set().

template<class ContainerType >

void drama::sds::Id::Resize ( const ContainerType & dims )

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

dims	The new dimensions

Template Parameters

ContainerType A container with a size() method and which can be used to initialize a vector of unsigned long.

References DramaTHROW, and DramaTHROW_F.

virtual void drama::sds::Id::SetDelete ( )

inlinevirtual

Indicate the underlying SDS structure should be deleted when the sds::Id object is destroyed.

See also: sds::Id::OutLive()

virtual void drama::sds::Id::SetFree ( )

inlinevirtual

Indicate the underlying SDS item should be free-ed when the sds::Id object is destroyed.

See also: sds::Id::OutLive()

virtual void drama::sds::Id::ShallowCopy ( const Id & source )

inlinevirtual

Shallow copy from a const sds::Id which will outlive this object.

Copy another sds::Id 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.

See also: sds::Id::Copy

Parameters

source The Sds object to copy. Must outlive this object.

Referenced by drama::sds::DataPointer< T >::DataPointer(), drama::sds::DataPointer< T[]>::DataPointer(), and drama::thread::TAction::SetReturnArg().

virtual void drama::sds::Id::ShallowCopy	(	Id *	source,
		const bool	outlives
	)

inlinevirtual

Shallow copy from sds::Id.

Copy another sds::Id 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: sds::Id::Copy

Parameters

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

virtual void drama::sds::Id::ShallowCopy	(	const SdsIdType	source,
		const bool	free = `false`,
		const bool	del = `false`,
		const bool	readfree = `false`
	)

inlinevirtual

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: sds::Id::Copy

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.