ast::Object Class Reference

Abstract base class for all AST objects. More...

#include <Object.h>

Inheritance diagram for ast::Object:

Public Types
using	ObjectPtr = std::unique_ptr< AstObject, Deleter >
	unique pointer holding an AST raw pointer More...

Public Member Functions
virtual	~Object ()
	Object (Object const &object)
	Copy constructor: make a deep copy. More...
	Object (Object &&)=default
Object &	operator= (Object const &)=delete
Object &	operator= (Object &&)=default
bool	operator== (Object const &rhs) const
	Return True if this and rhs are the equal. More...
bool	operator!= (Object const &rhs) const
	Return True if this and rhs are not equal. More...
std::shared_ptr< Object >	copy () const
	Return a deep copy of this object. More...
void	clear (std::string const &attrib)
	Clear the values of a specified set of attributes for an Object. More...
bool	hasAttribute (std::string const &attrib) const
	Does this object have an attribute with the specified name? More...
std::string	getClassName () const
	Get Class: the name of the class (e.g. More...
std::string	getID () const
	Get ID: object identification string that is not copied. More...
std::string	getIdent () const
	Get Ident: object identification string that is copied. More...
int	getNObject () const
	Get NObject: number of AST objects in existence of the same type as the underlying AST class. More...
int	getObjSize () const
	Get ObjSize: the in-memory size of the AST object in bytes. More...
int	getRefCount () const
	Get RefCount: number of active pointers to the underlying AST object. More...
bool	getUseDefs () const
	Get UseDefs: allow use of default values for Object attributes? More...
void	lock (bool wait)
	Lock this object for exclusive use by the calling thread. More...
bool	same (Object const &other) const
	Does this contain the same AST object as another? More...
void	setID (std::string const &id)
	Set ID: object identification string that is not copied. More...
void	setIdent (std::string const &ident)
	Set Ident: object identification string that is copied. More...
void	setUseDefs (bool usedefs)
	Set UseDefs: allow use of default values for Object attributes? More...
void	show (std::ostream &os, bool showComments=true) const
	Print a textual description the object to an ostream. More...
std::string	show (bool showComments=true) const
	Return a textual description the object as a string. More...
bool	test (std::string const &attrib) const
	Has this attribute been explicitly set (and not subsequently cleared)? More...
void	unlock (bool report=false)
	Unlock this object previously locked using lock, so that other threads can use this object. More...
AstObject const *	getRawPtr () const
	Get the raw AST pointer. More...
AstObject *	getRawPtr ()
	Get the raw AST pointer. More...

Static Public Member Functions
static std::shared_ptr< Object >	fromString (std::string const &str)
	Construct an Object from a string, using astFromString. More...
template<typename Class >
static std::shared_ptr< Class >	fromAstObject (AstObject *rawObj, bool copy)
	Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type. More...

Protected Member Functions
	Object (AstObject *object)
	Construct an Object from a pointer to a raw AstObject. More...
template<typename T , typename AstT >
std::shared_ptr< T >	copyImpl () const
	Implementation of deep copy. More...
virtual std::shared_ptr< Object >	copyPolymorphic () const =0
	Return a deep copy of this object. More...
bool	getB (std::string const &attrib) const
	Get the value of an attribute as a bool. More...
std::string const	getC (std::string const &attrib) const
	Get the value of an attribute as a string. More...
double	getD (std::string const &attrib) const
	Get the value of an attribute as a double. More...
float	getF (std::string const &attrib) const
	Get the value of an attribute as a float. More...
int	getI (std::string const &attrib) const
	Get the value of an attribute as an int. More...
long int	getL (std::string const &attrib) const
	Get the value of an attribute as a long int. More...
void	set (std::string const &setting)
	Assign a set of attribute values, over-riding any previous values. More...
void	setB (std::string const &attrib, bool value)
	Set the value of an attribute as a bool. More...
void	setC (std::string const &attrib, std::string const &value)
	Set the value of an attribute as a string. More...
void	setD (std::string const &attrib, double value)
	Set the value of an attribute as a double. More...
void	setF (std::string const &attrib, float value)
	Set the value of an attribute as a float. More...
void	setI (std::string const &attrib, int value)
	Set the value of an attribute as an int. More...
void	setL (std::string const &attrib, long int value)
	Set the value of an attribute as a long int. More...

Static Protected Member Functions
template<typename ShimT , typename AstT >
static std::shared_ptr< ShimT >	makeShim (AstObject *p)
	Functor to make an astshim instance from a raw AST pointer of the corresponding type. More...

Friends
class	MapSplit
class	FrameDict

Detailed Description

Abstract base class for all AST objects.

Attributes

Object provides the following attributes:

• Class: object class name (use getClassName)
• ID: object identification string that is not copied.
• Ident: object identification string that is copied.
• NObject: number of Objects in class
• ObjSize: the in-memory size of the Object in bytes
• RefCount: count of active Object pointers
• UseDefs: allow use of default values for Object attributes?

Definition at line 51 of file Object.h.

Member Typedef Documentation

ObjectPtr

using ast::Object::ObjectPtr = std::unique_ptr<AstObject, Deleter>

unique pointer holding an AST raw pointer

Definition at line 59 of file Object.h.

Constructor & Destructor Documentation

~Object()

virtual ast::Object::~Object ( )

inlinevirtual

Definition at line 61 of file Object.h.

{}

Object() [1/3]

ast::Object::Object ( Object const &  object )

inline

Copy constructor: make a deep copy.

Definition at line 64 of file Object.h.

: _objPtr(object.getRawPtrCopy(), &detail::annulAstObject) {}

Object() [2/3]

ast::Object::Object ( Object &&  )

default

Object() [3/3]

ast::Object::Object ( AstObject *  object )

explicitprotected

Construct an Object from a pointer to a raw AstObject.

Definition at line 171 of file Object.cc.

                                : _objPtr(object, &detail::annulAstObject) {
    assertOK();
    if (!object) {
        throw std::runtime_error("Null pointer");
    }
}

Member Function Documentation

clear()

void ast::Object::clear ( std::string const &  attrib )

inline

Clear the values of a specified set of attributes for an Object.

Clearing an attribute cancels any value that has previously been explicitly set for it, so that the standard default attribute value will subsequently be used instead. This also causes the astTest function to return the value zero for the attribute, indicating that no value has been set.

Definition at line 119 of file Object.h.

                                        {
        astClear(getRawPtr(), attrib.c_str());
        assertOK();
    }

copy()

std::shared_ptr<Object> ast::Object::copy ( ) const

inline

Return a deep copy of this object.

Definition at line 109 of file Object.h.

{ return std::static_pointer_cast<Object>(copyPolymorphic()); }

copyImpl()

template<typename T , typename AstT >

std::shared_ptr<T> ast::Object::copyImpl ( ) const

inlineprotected

Implementation of deep copy.

Should be called to implement copyPolymorphic by all derived classes.

Definition at line 320 of file Object.h.

                                      {
        auto *rawptr = reinterpret_cast<AstT *>(astCopy(getRawPtr()));
        auto retptr = std::shared_ptr<T>(new T(rawptr));
        assertOK();
        return retptr;
    }

copyPolymorphic()

virtual std::shared_ptr<Object> ast::Object::copyPolymorphic ( ) const

protectedpure virtual

Return a deep copy of this object.

This is called by copy.

Each subclass must override this method. The standard implementation is:

return copyImpl<astshim_class, ast_class>();

for example Frame implements this as:

return copyImpl<Frame, AstFrame>();

Implemented in ast::ZoomMap, ast::WinMap, ast::WcsMap, ast::UnitNormMap, ast::UnitMap, ast::TranMap, ast::TimeMap, ast::TimeFrame, ast::SphMap, ast::SpecFrame, ast::SlaMap, ast::SkyFrame, ast::ShiftMap, ast::SeriesMap, ast::RateMap, ast::PolyMap, ast::PermMap, ast::PcdMap, ast::ParallelMap, ast::NormMap, ast::MatrixMap, ast::MathMap, ast::Mapping, ast::LutMap, ast::KeyMap, ast::FrameSet, ast::FrameDict, ast::Frame, ast::CmpMap, ast::CmpFrame, ast::ChebyMap, and ast::Channel.

fromAstObject()

template<typename Class >

template std::shared_ptr< Object > ast::Object::fromAstObject< Object > ( AstObject *  rawObj, bool  copy  )

static

Given a bare AST object pointer return a shared pointer to an ast::Object of the correct type.

The returned object takes ownership of the pointer. This is almost always what you want, for instance astDecompose returns shallow copies of the internal pointers.

Template Parameters

Class

The class of the returned shared pointer. (The actual class will be the correct class of rawPtr.)

Parameters

[in]	rawObj	A bare AST object pointer
[in]	copy	If True then make a deep copy of the pointer (and free the original)

Definition at line 138 of file Object.cc.

                                                                       {
    AstObject *rawObjCopy = rawObj;
    if (copy) {
        rawObjCopy = reinterpret_cast<AstObject *>(astCopy(rawObj));
        astAnnul(rawObj);
    }
    assertOK(rawObjCopy);
 
    // Make the appropriate ast shim object and dynamically cast to the desired output type
    auto retObjectBeforeCast = Object::_basicFromAstObject(rawObjCopy);
    auto retObject = std::dynamic_pointer_cast<Class>(retObjectBeforeCast);
    if (!retObject) {
        std::ostringstream os;
        os << "The component is of type " << retObject->getClassName()
           << ", which could not be cast to the desired type " << typeid(Class).name();
        throw std::runtime_error(os.str());
    }
    return retObject;
}

fromString()

static std::shared_ptr<Object> ast::Object::fromString ( std::string const &  str )

inlinestatic

Construct an Object from a string, using astFromString.

Definition at line 88 of file Object.h.

                                                                  {
        auto *rawPtr = reinterpret_cast<AstObject *>(astFromString(str.c_str()));
        assertOK(rawPtr);
        return Object::_basicFromAstObject(rawPtr);
    }

getB()

bool ast::Object::getB ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as a bool.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 348 of file Object.h.

                                             {
        bool val = astGetI(getRawPtr(), attrib.c_str());
        assertOK();
        return val;
    }

getC()

std::string const ast::Object::getC ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as a string.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 361 of file Object.h.

                                                        {
        char const *rawval = astGetC(getRawPtr(), attrib.c_str());
        assertOK();
        return std::string(rawval);
    }

getClassName()

std::string ast::Object::getClassName ( ) const

inline

Get Class: the name of the class (e.g.

ZoomMap)

Note: if AST returns "CmpMap" then the name will be changed to "SeriesMap" or "ParallelMap", as appropriate.

Definition at line 139 of file Object.h.

{ return detail::getClassName(getRawPtr()); }

getD()

double ast::Object::getD ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as a double.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 374 of file Object.h.

                                               {
        double val = astGetD(getRawPtr(), attrib.c_str());
        assertOK();
        return val;
    }

getF()

float ast::Object::getF ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as a float.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 387 of file Object.h.

                                              {
        float val = astGetF(getRawPtr(), attrib.c_str());
        assertOK();
        return val;
    }

getI()

int ast::Object::getI ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as an int.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 400 of file Object.h.

                                            {
        int val = astGetI(getRawPtr(), attrib.c_str());
        assertOK();
        return val;
    }

getID()

std::string ast::Object::getID ( ) const

inline

Get ID: object identification string that is not copied.

Definition at line 142 of file Object.h.

{ return getC("ID"); }

getIdent()

std::string ast::Object::getIdent ( ) const

inline

Get Ident: object identification string that is copied.

Definition at line 145 of file Object.h.

{ return getC("Ident"); }

getL()

long int ast::Object::getL ( std::string const &  attrib ) const

inlineprotected

Get the value of an attribute as a long int.

If possible, the attribute value is converted to the type you request.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 413 of file Object.h.

                                                 {
        long int val = astGetL(getRawPtr(), attrib.c_str());
        assertOK();
        return val;
    }

getNObject()

int ast::Object::getNObject ( ) const

inline

Get NObject: number of AST objects in existence of the same type as the underlying AST class.

Warning

Intended only for debugging astshim.

Definition at line 153 of file Object.h.

{ return getI("NObject"); }

getObjSize()

int ast::Object::getObjSize ( ) const

inline

Get ObjSize: the in-memory size of the AST object in bytes.

Definition at line 156 of file Object.h.

{ return getI("ObjSize"); }

getRawPtr() [1/2]

AstObject* ast::Object::getRawPtr ( )

inline

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 294 of file Object.h.

{ return &*_objPtr; };

getRawPtr() [2/2]

AstObject const* ast::Object::getRawPtr ( ) const

inline

Get the raw AST pointer.

Intended for internal use only, but cannot be made protected without endless "friend class" declarations.

Definition at line 292 of file Object.h.

{ return &*_objPtr; };

getRefCount()

int ast::Object::getRefCount ( ) const

inline

Get RefCount: number of active pointers to the underlying AST object.

Warning

Intended only for debugging astshim.

Definition at line 163 of file Object.h.

{ return getI("RefCount"); }

getUseDefs()

bool ast::Object::getUseDefs ( ) const

inline

Get UseDefs: allow use of default values for Object attributes?

Definition at line 166 of file Object.h.

{ return getB("UseDefs"); }

hasAttribute()

bool ast::Object::hasAttribute ( std::string const &  attrib ) const

inline

Does this object have an attribute with the specified name?

Definition at line 127 of file Object.h.

                                                     {
        bool ret = astHasAttribute(getRawPtr(), attrib.c_str());
        assertOK();
        return ret;
    }

lock()

void ast::Object::lock ( bool  wait )

inline

Lock this object for exclusive use by the calling thread.

The thread-safe public interface to AST is designed so that an error is reported if any thread attempts to use an Object that it has not previously locked for its own exclusive use using this function. When an Object is created, it is initially locked by the thread that creates it, so newly created objects do not need to be explicitly locked. However, if an Object pointer is passed to another thread, the original thread must first unlock it (using astUnlock) and the new thread must then lock it (using astLock) before the new thread can use the Object.

Parameters

[in]

wait

If the Object is curently locked by another thread then this function will either report an error or block. If a non-zero value is supplied for "wait", the calling thread waits until the object is available for it to use. Otherwise, an error is reported and the function returns immediately without locking the Object.

Notes

• The Locked object will belong to the current AST context.
• This function returns without action if the Object is already locked by the calling thread.
• If simultaneous use of the same object is required by two or more threads, Object::copy should be used to to produce a deep copy of the Object for each thread. Each copy should then be unlocked by the parent thread (i.e. the thread that created the copy), and then locked by the child thread (i.e. the thread that wants to use the copy).
• This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 202 of file Object.h.

                         {
        astLock(getRawPtr(), static_cast<int>(wait));
        assertOK();
    }

makeShim()

template<typename ShimT , typename AstT >

static std::shared_ptr<ShimT> ast::Object::makeShim ( AstObject *  p )

inlinestaticprotected

Functor to make an astshim instance from a raw AST pointer of the corresponding type.

Template Parameters

ShimT	Output astshim class
AstT	Output AST class

Definition at line 310 of file Object.h.

                                                       {
        return std::shared_ptr<ShimT>(new ShimT(reinterpret_cast<AstT *>(p)));
    }

operator!=()

bool ast::Object::operator!= ( Object const &  rhs ) const

inline

Return True if this and rhs are not equal.

See operator== for details

Definition at line 82 of file Object.h.

                                             {
        return !(*this == rhs); };

operator=() [1/2]

Object& ast::Object::operator= ( Object &&  )

default

operator=() [2/2]

Object& ast::Object::operator= ( Object const &  )

delete

operator==()

bool ast::Object::operator==

(

Object const &

rhs

)

const

Return True if this and rhs are the equal.

For two objects be equal, they both must have the same attributes and all contained objects must be equal.

Definition at line 85 of file Object.cc.

                                               {
    auto thisStr = this->show(false);
    auto rhsStr = rhs.show(false);
    return rhsStr == thisStr;
}

same()

bool ast::Object::same ( Object const &  other ) const

inline

Does this contain the same AST object as another?

This is a test of identity, not of equality.

Definition at line 212 of file Object.h.

{ return astSame(getRawPtr(), other.getRawPtr()); }

set()

void ast::Object::set ( std::string const &  setting )

inlineprotected

Assign a set of attribute values, over-riding any previous values.

The attributes and their new values are specified via a character string, which should contain a comma-separated list of the form: "attribute_1 = value_1, attribute_2 = value_2, ... " where "attribute_n" specifies an attribute name, and the value to the right of each " =" sign should be a suitable textual representation of the value to be assigned. This value will be interpreted according to the attribute's data type.

Notes

• Attribute names are not case sensitive and may be surrounded by white space
• Attribute names are not case sensitive and may be surrounded by white space.
• White space may also surround attribute values, where it will generally be ignored (except for string-valued attributes where it is significant and forms part of the value to be assigned).
• To include a literal comma or percent sign in the value assigned to an attribute, the whole attribute value should be enclosed in quotation markes.

Exceptions

std::runtime_error

if the attribute is read-only

Definition at line 440 of file Object.h.

                                       {
        astSet(getRawPtr(), "%s", setting.c_str());
        assertOK();
    }

setB()

void ast::Object::setB ( std::string const &  attrib, bool  value  )

inlineprotected

Set the value of an attribute as a bool.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 452 of file Object.h.

                                                   {
        astSetI(getRawPtr(), attrib.c_str(), value);
        assertOK();
    }

setC()

void ast::Object::setC ( std::string const &  attrib, std::string const &  value  )

inlineprotected

Set the value of an attribute as a string.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 464 of file Object.h.

                                                               {
        astSetC(getRawPtr(), attrib.c_str(), value.c_str());
        assertOK();
    }

setD()

void ast::Object::setD ( std::string const &  attrib, double  value  )

inlineprotected

Set the value of an attribute as a double.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 476 of file Object.h.

                                                     {
        astSetD(getRawPtr(), attrib.c_str(), value);
        assertOK();
    }

setF()

void ast::Object::setF ( std::string const &  attrib, float  value  )

inlineprotected

Set the value of an attribute as a float.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 488 of file Object.h.

                                                    {
        astSetF(getRawPtr(), attrib.c_str(), value);
        assertOK();
    }

setI()

void ast::Object::setI ( std::string const &  attrib, int  value  )

inlineprotected

Set the value of an attribute as an int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 500 of file Object.h.

                                                  {
        astSetI(getRawPtr(), attrib.c_str(), value);
        assertOK();
    }

setID()

void ast::Object::setID ( std::string const &  id )

inline

Set ID: object identification string that is not copied.

Definition at line 215 of file Object.h.

{ setC("ID", id); }

setIdent()

void ast::Object::setIdent ( std::string const &  ident )

inline

Set Ident: object identification string that is copied.

Definition at line 218 of file Object.h.

{ setC("Ident", ident); }

setL()

void ast::Object::setL ( std::string const &  attrib, long int  value  )

inlineprotected

Set the value of an attribute as a long int.

If possible, the type you provide is converted to the actual type of the attribute.

Exceptions

std::runtime_error

if the attribute does not exist or the value cannot be converted

Definition at line 512 of file Object.h.

                                                       {
        astSetL(getRawPtr(), attrib.c_str(), value);
        assertOK();
    }

setUseDefs()

void ast::Object::setUseDefs ( bool  usedefs )

inline

Set UseDefs: allow use of default values for Object attributes?

Definition at line 221 of file Object.h.

{ setB("UseDefs", usedefs); }

show() [1/2]

std::string ast::Object::show

(

bool

showComments = true

)

const

Return a textual description the object as a string.

Parameters

[in]

showComments

Show comments?

Definition at line 165 of file Object.cc.

                                              {
    std::ostringstream os;
    show(os, showComments);
    return os.str();
}

show() [2/2]

void ast::Object::show	(	std::ostream &	os,
		bool	showComments = true
	)		const

Print a textual description the object to an ostream.

Parameters

[in,out]	os	The stream to which to write the string representation.
[in]	showComments	Show comments?

Definition at line 158 of file Object.cc.

                                                         {
    Stream stream(nullptr, &os);
    Channel ch(stream, showComments ? "" : "Comment=0");
    ch.write(*this);
    assertOK();
}

test()

bool ast::Object::test ( std::string const &  attrib ) const

inline

Has this attribute been explicitly set (and not subsequently cleared)?

Warning

Unlike the underlying astTest function, throws an exception if an error results

Notes

• Attribute names are not case sensitive and may be surrounded by white space.
• As you might expect, the returned value for a read-only attribute is always false.

Exceptions

std::runtime_error

if an error results.

Definition at line 250 of file Object.h.

                                             {
        bool res = astTest(getRawPtr(), attrib.c_str());
        assertOK();
        return res;
    }

unlock()

void ast::Object::unlock ( bool  report = false )

inline

Unlock this object previously locked using lock, so that other threads can use this object.

See lock for further details.

Parameters

[in]

report

If true, an error will be reported if the supplied Object, or any Object contained within the supplied Object, is not currently locked by the running thread. If false, such Objects will be left unchanged, and no error will be reported.

Notes

• This function attempts to execute even if AST's global error status is set, but no further error report will be made if it subsequently fails under these circumstances.
• All unlocked Objects are excluded from AST context handling until they are re-locked using astLock.
• This function returns without action if the Object is not currently locked by any thread. If it is locked by the running thread, it is unlocked. If it is locked by another thread, an error will be reported if "error" is non-zero.
• This function returns without action if the AST library has been built without POSIX thread support (i.e. the "-with-pthreads" option was not specified when running the "configure" script).

Definition at line 280 of file Object.h.

                                     {
        astUnlock(getRawPtr(), static_cast<int>(report));
        assertOK();
    }

Friends And Related Function Documentation

FrameDict

friend class FrameDict

friend

Definition at line 53 of file Object.h.

MapSplit

friend class MapSplit

friend

Definition at line 52 of file Object.h.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/astshim/22.0.1-1-geca5380+7fa3b7d9b6/include/astshim/Object.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-0.7.0/Linux64/astshim/22.0.1-1-geca5380+7fa3b7d9b6/src/Object.cc