EDoc::StringIdentifiedObject Class Reference

#include <include/EDoc/StringIdentifiedObject.h>

Inheritance diagram for EDoc::StringIdentifiedObject:

---

Detailed Description

Represents a fundamental DictionarySpecific data type that has a unique string identifier.

All fundamental dictionary types derive from this abstract class. This includes the classes:

• File
• Type
• FunctionType
• Function

This class exposes common functionality that makes managing these objects a little simpler. In particular all such types are identified by a unique string, however when saved in .edc files they are identified by unique integer indexes. This class provides mechanisms to help in the process of loading objects that are indexed with integers and fitting them into objects indexed by strings.

These objects all have common properties such as:

• They all have eithre a string identifier OR an integer identifier. Only the string OR the integer can be used for indexing the object at any one point in time.
• They can exist in a non-populated state waiting to be populated
• They can all be written/read to/from a file
• It can be easy to introduce a bug in pointer assignment between dictionaries, so they all support special internal validation and pointer replacement methods.

See also:

See Also Dictionary and DictionarySpecific

Definition at line 71 of file StringIdentifiedObject.h.

Public Member Functions
	StringIdentifiedObject (Dictionary &dict_in, std::string key_name_in, bool populated_in=false)
	Constructor called from a derived class initialising the object with an initial string identifier.
	StringIdentifiedObject (Dictionary &dict_in, int32_t index_in, bool populated_in=false)
	Constructor called from a derived class initialising the object with an initial integer identifier.
virtual	~StringIdentifiedObject ()
	Destructor.
virtual void	Read (PersistenceIFace &file, IndexedDictionary &idict)=0
	See CodeBlock::Read().
virtual void	Write (PersistenceIFace &file) const =0
	See CodeBlock::Write().
virtual void	Merge (const StringIdentifiedObject &right)=0
	Merges two StringIdentifiedObjects.
virtual uint8_t	GetRecordType () const=0
	Returns an integer identifying the type of the derived class.
const std::string &	GetKeyName () const
	Returns the string key that identifies this object.
ssize_t	GetIndex () const
	Returns the integer key that identifies this object.
bool	IsPopulated () const
	Returns true if this object has been completely populated from a file source or manually or false if the object is incomplete.
virtual size_t	ReplaceReferences (PStack &stack, void *remove, void *replace)=0
	Replaces all references of pointers referencing remove with pointers to replace.
virtual std::ostream &	Print (std::ostream &out, std::string prefix="") const =0
	Print the current object to the given stream in a user readable manner.
std::string	ToString (std::string prefix="") const
	Returns a string representing the current object in a user readable manner.
virtual void	Validate (PStack &stack, const Dictionary &dict_in) const =0
	Performs internal valtidation on the current object and will throw a BugException if the validation fails.
Protected Member Functions
void	SetKeyName (std::string key_name_in)
	Used by derived class to set the string key once it is able to determine it.
Protected Attributes
bool	populated
	True if this object has been completely populated.
int32_t	index
	Set to the integer index used to identify this object or -1 if the key_name is used to identify this object.
std::string	key_name
	Set to the string key used to identify this object.
bool	writing
	USED ONLY FROM Dictionary::Write().
Dictionary &	dict
	A reference to the dictionary this object belongs to.
Friends
class	IndexedDictionary
class	IndexedObject
class	Dictionary

---

Constructor & Destructor Documentation

EDoc::StringIdentifiedObject::StringIdentifiedObject	(	EDoc::Dictionary &	dict_in,
		std::string	key_name_in,
		bool	populated_in = false
	)

Constructor called from a derived class initialising the object with an initial string identifier.

Note:

EDoc++ data included.

Definition at line 28 of file StringIdentifiedObject.cpp.

EDoc::StringIdentifiedObject::StringIdentifiedObject	(	EDoc::Dictionary &	dict_in,
		int32_t	index_in,
		bool	populated_in = false
	)

Constructor called from a derived class initialising the object with an initial integer identifier.

Note:

EDoc++ data included.

Definition at line 40 of file StringIdentifiedObject.cpp.

EDoc::StringIdentifiedObject::~StringIdentifiedObject

(

)

[inline, virtual]

Destructor.

Note:

EDoc++ data included.

Definition at line 95 of file StringIdentifiedObject.h.

---

Member Function Documentation

EDoc::StringIdentifiedObject::Read	(	PersistenceIFace &	file,
		IndexedDictionary &	idict
	)			[pure virtual]

See CodeBlock::Read().

After reading objects derived from StringIdentifiedObject will have their key name set and will be considered "populated"

Implemented in EDoc::File, EDoc::Function, EDoc::FunctionType, and EDoc::Type.

Referenced by EDoc::Dictionary::Read().

EDoc::StringIdentifiedObject::Write

(

EDoc::PersistenceIFace &

file

)

const [pure virtual]

See CodeBlock::Write().

Exceptions:

EDoc::FileIOException

Originating from: EDoc::BinaryPersistence::WriteString(char const*, std::string) P: EDoc::File::Write(EDoc::PersistenceIFace&) const P: EDoc::Type::Write(EDoc::PersistenceIFace&) const P: EDoc::FunctionType::Write(EDoc::PersistenceIFace&) const P: EDoc::Function::Write(EDoc::PersistenceIFace&) const Originating from: EDoc::BinaryPersistence::WriteUInt32(char const*, uint32_t) P: EDoc::File::Write(EDoc::PersistenceIFace&) const P: EDoc::Type::Write(EDoc::PersistenceIFace&) const P: EDoc::FunctionType::Write(EDoc::PersistenceIFace&) const P: EDoc::Function::Write(EDoc::PersistenceIFace&) const Originating from: EDoc::BinaryPersistence::WriteBoolean(char const*, bool) P: EDoc::Type::Write(EDoc::PersistenceIFace&) const P: EDoc::FunctionType::Write(EDoc::PersistenceIFace&) const P: EDoc::Function::Write(EDoc::PersistenceIFace&) const

Implemented in EDoc::File, EDoc::Function, EDoc::FunctionType, and EDoc::Type.

EDoc::StringIdentifiedObject::Merge

(

const StringIdentifiedObject &

right

)

[pure virtual]

Merges two StringIdentifiedObjects.

Warning:

NOTE: The two objects MUST be of the same type. You can NOT merge a File with a Function.

Implemented in EDoc::File, EDoc::Function, EDoc::FunctionType, and EDoc::Type.

EDoc::StringIdentifiedObject::GetRecordType

(

)

const [pure virtual]

Returns an integer identifying the type of the derived class.

Currently the following integers are defined i npersistence_data.h:

• 1 VALUE_RECORD_TYPE_TYPE for Type objects.
• 2 VALUE_RECORD_TYPE_FUNCTION for Function objects.
• 3 VALUE_RECORD_TYPE_FILE for File objects.
• 4 VALUE_RECORD_TYPE_FUNCTION_TYPE for FunctionType objects.

Implemented in EDoc::File, EDoc::Function, EDoc::FunctionType, and EDoc::Type.

EDoc::StringIdentifiedObject::GetKeyName

(

)

const

Returns the string key that identifies this object.

Will assert if the object has not yet been populated OR it currently uses an integer identifier not a string identifier.

Definition at line 51 of file StringIdentifiedObject.cpp.

References EDOC_ASSERT, index, key_name, and writing.

Referenced by EDoc::ManagedObject::CAdd(), EDoc::ManagedObject::CAlwaysGet(), EDoc::ManagedObject::CRemove(), EDoc::Function::ExpandCallGraph(), EDoc::FunctionLoc::FunctionLoc(), EDoc::Type::GetBestName(), EDoc::Type::IsEquivilant(), EDoc::Type::Merge(), EDoc::Location::Merge(), EDoc::FunctionType::Merge(), EDoc::Function::Merge(), EDoc::FunctionLoc::operator<(), EDoc::TypeLoc::Print(), EDoc::PropogatingException::Print(), EDoc::FunctionTypeLoc::Print(), EDoc::FunctionLoc::Print(), EDoc::Function::Print(), EDoc::Exception::Print(), EDoc::CatchBlock::Print(), EDoc::Dictionary::ProcessCodeBlock(), EDoc::Dictionary::ProcessFunction(), EDoc::StdErrFunctionProgress::Progress(), EDoc::Dictionary::Read(), EDoc::Dictionary::UpdateFunctionAddressLists(), EDoc::Type::Validate(), EDoc::FunctionType::Validate(), EDoc::Function::Validate(), EDoc::File::Validate(), EDoc::Dictionary::Validate(), EDoc::CatchBlock::Validate(), and EDoc::Function::Write().

EDoc::StringIdentifiedObject::GetIndex

(

)

const [inline]

Returns the integer key that identifies this object.

Note:

EDoc++ data included.

Definition at line 142 of file StringIdentifiedObject.h.

References index.

Referenced by EDoc::TypeLoc::Write(), EDoc::Type::Write(), EDoc::FunctionTypeLoc::Write(), EDoc::FunctionType::Write(), EDoc::FunctionLoc::Write(), and EDoc::Function::Write().

EDoc::StringIdentifiedObject::IsPopulated

(

)

const [inline]

Returns true if this object has been completely populated from a file source or manually or false if the object is incomplete.

Note:

EDoc++ data included.

Definition at line 151 of file StringIdentifiedObject.h.

References populated.

Referenced by EDoc::Dictionary::GeneratePredefined(), EDoc::Type::GetBestName(), EDoc::FunctionType::GetSpecString(), EDoc::Function::GetSpecString(), and EDoc::Dictionary::Read().

EDoc::StringIdentifiedObject::SetKeyName

(

std::string

key_name_in

)

[protected]

Used by derived class to set the string key once it is able to determine it.

Usually an instance is created with an integer index and then data is loaded into the object and once it has loaded it is able to determine what its string index should be. Then it will call this function which sets the integer index to -1 and sets the string key to the given value.

Definition at line 57 of file StringIdentifiedObject.cpp.

References EDOC_ASSERT, index, and key_name.

Referenced by EDoc::Type::Read(), EDoc::FunctionType::Read(), EDoc::Function::Read(), and EDoc::File::Read().

EDoc::DictionarySpecific::ReplaceReferences	(	PStack &	stack,
		void *	remove,
		void *	replace
	)			[pure virtual, inherited]

Replaces all references of pointers referencing remove with pointers to replace.

The replacement is used because when after Read()'ing it is possible to have two instances of an object indexed by the same key. The contents of them must be merged and all references to one object be changed to reference the other. Then the now unreferenced object would be deleted. This is a part of the loading phase and is a result of the fact that GCC can generate multiple tree nodes for a single type. Thus when loading we often get the same type multiple times.

Todo:

As an option in the future we may choose to allow replace to be a NULL pointer. In which case it will completely erase references to a particular object instead of having to replace them with something else. This works for containers, but for non-optional fixed pointers it may cause some problems. Maybe in these cases, we should throw an exception that indicates to the user that they cant just erase that reference, they must at least replace it in some places with something or first erase other nodes that reference it first. This exception would need to include as its data a reference to the object that cant release its reference to "remove".

Implemented in EDoc::CatchBlock, EDoc::CodeBlock, EDoc::Exception, EDoc::File, EDoc::Function, EDoc::FunctionLoc, EDoc::FunctionType, EDoc::FunctionTypeLoc, EDoc::Location, EDoc::ManagedObject, EDoc::PropogatingException, EDoc::TryBlock, EDoc::Type, and EDoc::TypeLoc.

EDoc::DictionarySpecific::Print	(	std::ostream &	out,
		std::string	prefix = ""
	)			const [pure virtual, inherited]

Print the current object to the given stream in a user readable manner.

Parameters:

	out	The stream to print to.
	prefix	A string prefix to display at the start of every line. As an example this can be used in order to indent the print by passing "\t" as the string.

Implemented in EDoc::CatchBlock, EDoc::CodeBlock, EDoc::Exception, EDoc::File, EDoc::Function, EDoc::FunctionLoc, EDoc::FunctionType, EDoc::FunctionTypeLoc, EDoc::Location, EDoc::ManagedObject, EDoc::PropogatingException, EDoc::TryBlock, EDoc::Type, and EDoc::TypeLoc.

Referenced by std::operator<<(), and EDoc::DictionarySpecific::ToString().

EDoc::DictionarySpecific::ToString

(

std::string

prefix = ""

)

const [inherited]

Returns a string representing the current object in a user readable manner.

This will return as a string exactly what Print() would display. This is primarily here for use from within python and for debugging.

Definition at line 34 of file DictionarySpecific.cpp.

References EDoc::DictionarySpecific::Print().

Referenced by EDoc::Dictionary::Read().

EDoc::DictionarySpecific::Validate	(	PStack &	stack,
		const Dictionary &	dict_in
	)			const [pure virtual, inherited]

Performs internal valtidation on the current object and will throw a BugException if the validation fails.

This is primarily used to ensure that all DictionarySpecific objects are internally consistent, not referencing dictionaries that they actually do not belong to. It is also used for a few other validations too that if they fail would indicate a bug in the code somewhere.

Implemented in EDoc::CatchBlock, EDoc::CodeBlock, EDoc::Exception, EDoc::File, EDoc::Function, EDoc::FunctionLoc, EDoc::FunctionType, EDoc::FunctionTypeLoc, EDoc::Location, EDoc::ManagedObject, EDoc::PropogatingException, EDoc::TryBlock, EDoc::Type, and EDoc::TypeLoc.

---

Friends And Related Function Documentation

friend class IndexedDictionary [friend]

Definition at line 73 of file StringIdentifiedObject.h.

friend class IndexedObject [friend]

Definition at line 74 of file StringIdentifiedObject.h.

friend class Dictionary [friend]

Definition at line 75 of file StringIdentifiedObject.h.

---

Field Documentation

bool EDoc::StringIdentifiedObject::populated [protected]

True if this object has been completely populated.

Definition at line 176 of file StringIdentifiedObject.h.

Referenced by EDoc::Dictionary::GeneratePredefined(), IsPopulated(), EDoc::Type::Merge(), EDoc::FunctionType::Merge(), EDoc::Function::Merge(), EDoc::File::Merge(), EDoc::Type::operator=(), EDoc::FunctionType::operator=(), EDoc::Function::operator=(), EDoc::Type::Read(), EDoc::FunctionType::Read(), EDoc::Function::Read(), EDoc::File::Read(), EDoc::Type::Validate(), EDoc::FunctionType::Validate(), and EDoc::Function::Validate().

int32_t EDoc::StringIdentifiedObject::index [mutable, protected]

Set to the integer index used to identify this object or -1 if the key_name is used to identify this object.

Definition at line 182 of file StringIdentifiedObject.h.

Referenced by EDoc::IndexedObject::CAdd(), EDoc::Dictionary::GeneratePredefined(), GetIndex(), GetKeyName(), SetKeyName(), EDoc::Type::Validate(), EDoc::FunctionType::Validate(), EDoc::Function::Validate(), and EDoc::File::Validate().

std::string EDoc::StringIdentifiedObject::key_name [protected]

Set to the string key used to identify this object.

Definition at line 187 of file StringIdentifiedObject.h.

Referenced by EDoc::Dictionary::GeneratePredefined(), GetKeyName(), SetKeyName(), EDoc::Type::Validate(), EDoc::FunctionType::Validate(), EDoc::Function::Validate(), and EDoc::File::Validate().

bool EDoc::StringIdentifiedObject::writing [mutable, protected]

USED ONLY FROM Dictionary::Write().

While writing an object to file it is possible to use both the objects integer and string keys. This is the only time that is allowable and this flag is used to determine that.

Definition at line 204 of file StringIdentifiedObject.h.

Referenced by GetKeyName().

Dictionary& EDoc::DictionarySpecific::dict [protected, inherited]

A reference to the dictionary this object belongs to.

Definition at line 150 of file DictionarySpecific.h.

Referenced by EDoc::ManagedObject::CAlwaysGet(), EDoc::CatchBlock::CatchBlock(), EDoc::Exception::Exception(), EDoc::Function::ExpandCallGraph(), EDoc::CodeBlock::ExpandCallGraph(), EDoc::FunctionLoc::FunctionLoc(), EDoc::FunctionTypeLoc::FunctionTypeLoc(), EDoc::Function::GetSubstException(), EDoc::Location::Location(), EDoc::ManagedObject::ManagedObject(), EDoc::Type::Merge(), EDoc::Location::Merge(), EDoc::Function::Merge(), EDoc::SpecificManagedObject< EDoc::Type >::New(), EDoc::TypeLoc::operator=(), EDoc::Type::operator=(), EDoc::TryBlock::operator=(), EDoc::PropogatingException::operator=(), EDoc::Location::operator=(), EDoc::FunctionTypeLoc::operator=(), EDoc::FunctionType::operator=(), EDoc::FunctionLoc::operator=(), EDoc::Function::operator=(), EDoc::Exception::operator=(), EDoc::CodeBlock::operator=(), EDoc::PropogatingException::PropogatingException(), EDoc::TryBlock::Read(), EDoc::Function::Read(), EDoc::CodeBlock::Read(), EDoc::TryBlock::TryBlock(), EDoc::TypeLoc::TypeLoc(), EDoc::TypeLoc::Validate(), EDoc::Type::Validate(), EDoc::TryBlock::Validate(), EDoc::PropogatingException::Validate(), EDoc::ManagedObject::Validate(), EDoc::Location::Validate(), EDoc::FunctionTypeLoc::Validate(), EDoc::FunctionType::Validate(), EDoc::FunctionLoc::Validate(), EDoc::Function::Validate(), EDoc::File::Validate(), EDoc::Exception::Validate(), EDoc::CodeBlock::Validate(), EDoc::CatchBlock::Validate(), EDoc::Type::Write(), and EDoc::Function::Write().

---

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

• include/EDoc/StringIdentifiedObject.h
• libs/EDoc/StringIdentifiedObject.cpp
• libs.dox

---