drama::sds::Id Class Reference

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$ $Date$

Examples

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

#include "sds.hh"

Inheritance diagram for drama::sds::Id:

Public Member Functions
	Id ()
	Default constructor.
	Id (const Id &source)=delete
	Copy constructor - deleted.
	Id (Id &&source) noexcept
	Move copy constructor.
virtual	~Id ()
	sds::Id Destructor.
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.
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.
template<typename T , class ContainerType >
void	ArrayAccess (ArrayAccessHelper< T > *const data, ContainerType *dims) const
	Access the data of an SDS primitive item array.
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.
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.
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.
template<class ContainerType >
void	CheckItem (SdsCodeType code, const ContainerType &dims) const
	Check an item has a required structure.
virtual void	ClearDelete ()
	Indicate the underlying SDS structure should NOT be deleted when the sds::Id object is destroyed.
virtual Id	Copy () const
	Factory constructor method Id Copy constructor.
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.
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 multi-dimensional array.
Id	CreateChildArray (const std::string &name, const SdsCodeType code, const unsigned nElem, const std::string &extra="") const
	Factory constructor method Constructor which creates a new child item which is a one-dimensional array.
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.
virtual void	Delete ()
	Delete the SDS item.
virtual bool	Exists (const std::string &name) const
	Determine if a named item exists in a structure.
virtual bool	Exists (unsigned index) const
	Determine if a item of a given index exists in a structure.
template<class ContainerType >
void	Export (ContainerType *container) const
	Export the SDS structure into a buffer.
template<class ContainerType >
void	ExportDefined (ContainerType *container) const
	Export the SDS structure into a buffer, defining any undefined data.
virtual void	Extract ()
	Extract the SDS structure from its parent.
virtual void	FillArray (const Id &elem)
	Fill out the contents of this object, which is a structured array.
virtual Id	Find (const std::string &name, bool throwOnNotFound=true) const
	Factory constructor method Constructor which returns a reference to a named item.
virtual void	Flush ()
	Flush data modified by pointer.
template<typename T >
void	Get (const std::string &name, T *value) const
	Fetch primitive value from a named component of the structure.
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.
template<typename T >
void	Get (T *value) const
	Fetch primitive value from the component.
virtual SdsCodeType	GetCode () const
	Return the code of the SDS item.
template<class ContainerType >
void	GetDims (ContainerType *dims) const
	Return the dimensions of the SDS item.
virtual double	GetDouble () const
	If the SDS item refers to a scalar value, convert it to a double item.
virtual std::string	GetExtra () const
	Get extra data from an SDS item.
virtual int	GetInt () const
	If the SDS item refers to a scalar value, convert it to an integer.
virtual long	GetLong () const
	If the SDS item refers to a scalar value, convert it to long integer.
virtual std::string	GetName () const
	Return the name of the SDS item.
unsigned	GetNumItems () const
	Return the number of components in an SDS structure.
std::string	GetString () const
	If the SDS item refers to a scalar value or a character string, convert it to a string item.
virtual unsigned int	GetUInt () const
	If the SDS item refers to a scalar value, convert it to an unsigned integer.
virtual unsigned long	GetULong () const
	If the SDS item refers to a scalar value, convert it to an unsigned long integer.
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.
virtual void	Insert (Id &to_insert)
	Insert an SDS object into this object.
template<class ContainerType >
void	Insert (Id &to_insert, const ContainerType &dims)
	Insert an SDS object into this object, which is a structured array.
virtual bool	IsExternal () const
	Determine if the SDS structure is external.
virtual void	List () const
	List the contents of the structure to standard output.
virtual void	List (const PrintObjectCR &printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectCR.
virtual void	List (FILE *to) const
	List the contents of the structure to a C file.
virtual void	List (PrintObjectPnt *printer, int lineMaxLen=100) const
	List the contents of the structure via a PrintObjectPnt object.
virtual void	List (std::ostream &strm, int lineMaxLen=100) const
	List the contents of the structure to an output stream.
	operator bool () const
	Operator which tests if an item is valid.
	operator SdsIdType () const
	Operator which returns the underlying SDS id.
Id &	operator= (const Id &rhs)=delete
	Assignment operator - deleted.
Id &	operator= (Id &&rhs) noexcept
	Move assignment operator.
virtual void	Outlive ()
	Force the actual SDS ID to outlive the sds::Id variable.
template<typename T >
void	Pointer (T **data, unsigned long *length=0) const
	Obtain a pointer to the data area of a primitive SDS item.
void	Put (const std::string &name, const std::string &value, const std::string &extraData="")
	Insert a string value into a named component of the structure.
template<typename T >
void	Put (const std::string &name, T value, const std::string &extraData="")
	Insert a primitive value into a named component of the structure.
void	Put (const std::string &value)
	Insert a string value into the component.
template<typename T >
void	Put (const unsigned long length, const T *const data, const unsigned long offset=0)
	Put data into an SDS item.
template<typename T >
void	Put (T value)
	Insert a primitive value into the item.
virtual void	PutExtra (const std::string &extra)
	Put extra data into an SDS item.
virtual void	Rename (const std::string &name)
	Rename the SDS item.
template<class ContainerType >
void	Resize (const ContainerType &dims)
	Change the dimensions of an SDS array.
virtual void	SetDelete ()
	Indicate the underlying SDS structure should be deleted when the sds::Id object is destroyed.
virtual void	SetFree ()
	Indicate the underlying SDS item should be free-ed when the sds::Id object is destroyed.
virtual void	ShallowCopy (const Id &source)
	Shallow copy from a const sds::Id which will outlive this object.
virtual void	ShallowCopy (const SdsIdType source, const bool free=false, const bool del=false, const bool readfree=false)
	Shallow copy from SdsIdType.
virtual void	ShallowCopy (Id *source, const bool outlives)
	Shallow copy from sds::Id.
virtual unsigned long	Size () const
	Return the size of an SDS structure, as required for exporting.
virtual unsigned long	SizeDefined () const
	Return the size of an SDS structure, as required for exporting when fully defined.
virtual void	ToSdsId (::SdsId *target, const bool outlives=false)
	Shallow copy to an SdsId type.
virtual std::string	toString (int maxlen=200)
	Convert the structure to a string.
virtual void	ValidateCode (SdsCodeType requiredCode) const
	Validate the code of the SDS item.
virtual void	Write (const std::string &filename) const
	Write the contents of the structure to a file.

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.
template<typename T >
static Id	CreateArgCmdStruct (const std::initializer_list< T > &values, const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure in the DRAMA Command style.
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.
static Id	CreateArgStruct (const std::string &name="ArgStructure")
	Factory constructor which creates a new "Arg" style SDS structure.
template<class ContainerType >
static Id	CreateByAccess (ContainerType *container)
	Factory constructor method that accesses an exported SDS structure found in a byte stream.
template<class ContainerType >
static Id	CreateByImport (const ContainerType &container)
	Factory constructor method that imports an exported SDS structure found in a byte stream.
static Id	CreateFromSdsId (const SdsId &item)
	Factory constructor method that constructs an sds::Id item from an existing old C++ interface SdsId item.
static Id	CreateFromSdsId (SdsId *item)
	Factory constructor method that constructs an sds::Id item from an existing old C++ interface SdsId item.
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.
static Id	CreateFromSdsIdTypeCopy (const SdsIdType item)
	Factory constructor method that constructs an sds::Id item by coping an existing C language SDS id.
static Id	CreateNullItem ()
	Factory constructor method that constructs an null sds::Id item .
static Id	CreateTopLevel (const std::string &name, const SdsCodeType code, const std::string &extra="")
	Constructor which creates a new (non-array) top-level item.
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.
static Id	CreateTopLevelArray (const std::string &name, const SdsCodeType code, const unsigned nElem, const std::string &extra="")
	Factory constructor method Constructor which creates a new one-dimensional array top-level item.
static Id	FromFile (const std::string &filename)
	Factory constructor method that reads an SDS structure from a file.

---

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

• sds.hh