Isis::PvlKeyword Class Reference
[Parsing]

A single keyword-value pair. More...

#include <PvlKeyword.h>

Public Member Functions
	PvlKeyword ()
	Constructs a blank PvlKeyword object.
	PvlKeyword (QString name)
	Constructs a PvlKeyword object with a name.
	PvlKeyword (QString name, QString value, QString unit="")
	Constructs a PvlKeyword object with a name, value and units.
	PvlKeyword (const PvlKeyword &other)
	Copy constructor.
	~PvlKeyword ()
	Destructs a PvlKeyword object.
void	SetName (QString name)
	Sets the keyword name.
QString	Name () const
	Returns the keyword name.
bool	IsNamed (QString name) const
	Determines whether two PvlKeywords have the same name or not.
void	SetValue (QString value, QString unit="")
	Sets new values.
void	SetUnits (QString units)
	Sets the unit of measure for all current values if any exist.
void	SetUnits (QString value, QString units)
	Sets the unit of measure for a given value.
PvlKeyword &	operator= (QString value)
	Sets new values.
void	AddValue (QString value, QString unit="")
	Adds a value with units.
PvlKeyword &	operator+= (QString value)
	Adds a value.
int	Size () const
	Returns the number of values stored in this keyword.
bool	IsNull (const int index=0) const
	Decides whether a value is null or not at a given index.
void	Clear ()
	Clears all values and units for this PvlKeyword object.
	operator double () const
	Returns the first value in this keyword converted to a double.
	operator int () const
	Returns the first value in this keyword converted to an integer.
	operator Isis::BigInt () const
	Returns the first value in this keyword converted to a BigInt.
	operator QString () const
const QString &	operator[] (int index) const
	Gets value for this object at specified index.
QString &	operator[] (int index)
	Gets value for this object at specified index.
QString	Unit (const int index=0) const
	Returns the units of measurement of the element of the array of values for the object at the specified index.
void	AddComment (QString comment)
	Add a comment to the PvlKeyword.
void	AddCommentWrapped (QString comment)
	Automatically wraps and adds long comments to the PvlKeyword.
void	AddComments (const std::vector< QString > &comments)
	This method adds multiple comments at once by calling AddComments on each element in the vector.
int	Comments () const
	Returns the number of lines of comments associated with this keyword.
QString	Comment (const int index) const
	Return a comment at the specified index.
void	ClearComments ()
	Clears the current comments.
bool	operator== (const PvlKeyword &key) const
	Returns true of the keyword names match.
bool	operator!= (const PvlKeyword &key) const
	Returns true of the keyword names do not match.
bool	IsEquivalent (QString string1, int index=0) const
	Checks to see if a value with a specified index is equivalent to another QString.
void	SetWidth (int width)
	The width of the longest keyword name (for formatting).
void	SetIndent (int indent)
	Sets the indent level when outputted(for formatting).
int	Width () const
	Returns the current set longest keyword name.
int	Indent () const
	Returns the current indent level.
PvlKeyword &	operator= (Isis::PvlSequence &seq)
	Add values and units from a PvlSequence.
void	SetFormat (PvlFormat *formatter)
	Set the PvlFormatter used to format the keyword name and value(s).
PvlFormat *	GetFormat ()
	Get the current PvlFormat or create one.
const PvlKeyword &	operator= (const PvlKeyword &other)
	This is an assignment operator.
void	ValidateKeyword (PvlKeyword &pvlKwrd, QString psValueType="", PvlKeyword *pvlKwrdRange=NULL)
	Validate Keyword for type and required values.
Static Public Member Functions
static bool	StringEqual (const QString &string1, const QString &string2)
	Checks to see if two QStrings are equal.
static QString	ReadLine (std::istream &is, bool insideComment)
	This method reads one line of data from the input stream.
static bool	ReadCleanKeyword (QString keyword, std::vector< QString > &keywordComments, QString &keywordName, std::vector< std::pair< QString, QString > > &keywordValues)
	This reads a keyword compressed back to 1 line of data (excluding comments, which are included on separate lines of data before the keyword).
static QString	ReadValue (QString &keyword, bool &quoteProblem)
static QString	ReadValue (QString &keyword, bool &quoteProblem, const std::vector< std::pair< char, char > > &otherDelimiters)
	This method looks for a data element in the QString.
Protected Member Functions
QString	Reform (const QString &value) const
	Checks if the value needs to be converted to PVL or iPVL and returns it in the correct format.
QString	ToPvl (const QString &value) const
	Converts a value to PVL format.
QString	ToIPvl (const QString &value) const
	Converts a value to iPVL format.
std::ostream &	WriteWithWrap (std::ostream &os, const QString &textToWrite, int startColumn, PvlFormat &format) const
	Wraps output so that length doesn't exceed the character limit.
Protected Attributes
PvlFormat *	p_formatter
	Formatter object.
Friends
std::istream &	operator>> (std::istream &is, PvlKeyword &result)
std::ostream &	operator<< (std::ostream &os, const PvlKeyword &keyword)

Detailed Description

A single keyword-value pair.

This class is used to create a single PVL keyword-value pair. PvlContainer can combine PvlKeyword objects and organize them so they look clean on output.

Author:: 2002-10-11 Jeff Anderson

Constructor & Destructor Documentation

Isis::PvlKeyword::PvlKeyword ( )

Constructs a blank PvlKeyword object.

Isis::PvlKeyword::PvlKeyword ( QString name )

Constructs a PvlKeyword object with a name.

Parameters:

name

The keyword name

References SetName().

Isis::PvlKeyword::PvlKeyword	(	QString	name,
		QString	value,
		QString	unit = `""`
	)

Constructs a PvlKeyword object with a name, value and units.

Defaults to unit="".

Parameters:

	name	The keyword name.
	value	The keyword values.
	unit	The units the values are given in.

References AddValue(), and SetName().

Isis::PvlKeyword::PvlKeyword ( const PvlKeyword & other )

Copy constructor.

Isis::PvlKeyword::~PvlKeyword ( )

Destructs a PvlKeyword object.

Member Function Documentation

void Isis::PvlKeyword::AddComment ( QString comment )

Add a comment to the PvlKeyword.

Parameters:

comment

The new comment.

See also:: AddCommentWrapped(); AddComments(); ClearComments()

Referenced by Isis::PvlContainer::AddComment(), AddComments(), AddCommentWrapped(), and Isis::ControlNetFileV0002::ToPvl().

void Isis::PvlKeyword::AddComments ( const std::vector< QString > & comments )

This method adds multiple comments at once by calling AddComments on each element in the vector.

Parameters:

comments

Comments to associate with this keyword

References AddComment().

Referenced by Isis::operator>>().

void Isis::PvlKeyword::AddCommentWrapped ( QString comment )

Automatically wraps and adds long comments to the PvlKeyword.

Parameters:

comment

The new comment to add

See also:: AddComment(); AddComments(); ClearComments()

References AddComment(), and Isis::IString::Token().

void Isis::PvlKeyword::AddValue	(	QString	value,
		QString	unit = `""`
	)

Adds a value with units.

If no current value exists, this method sets the given value. Otherwise, it retains any current values and adds the value given to the array of values for this PvlKeyword object. Defaults to unit = "" (empty QString).

Parameters:

	value	New value to be assigned.
	unit	Units of measurement corresponding to the value.

See also:: SetValue(); operator=; operator+=

Referenced by Isis::DbProfile::add(), Isis::PvlFormat::Add(), Isis::ControlNetDiff::addUniqueMeasure(), Isis::ControlNetDiff::addUniquePoint(), IsisAml::CommandLine(), Isis::ControlNetDiff::makeKeyword(), operator+=(), operator=(), Isis::operator>>(), PvlKeyword(), Isis::Stretch::Save(), SetValue(), and Isis::Spice::storeValue().

void Isis::PvlKeyword::Clear ( )

Clears all values and units for this PvlKeyword object.

Referenced by operator=(), and SetValue().

void Isis::PvlKeyword::ClearComments ( )

Clears the current comments.

QString Isis::PvlKeyword::Comment ( const int index ) const

Return a comment at the specified index.

Parameters:

index

The index of the comment.

Returns:: QString The comment at the index.

Exceptions:

iException

ArraySubscriptNotInRange (index) Index out of bounds.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), and Isis::IException::Programmer.

Referenced by Isis::PvlContainer::Comment(), and Isis::operator<<().

int Isis::PvlKeyword::Comments ( ) const [inline]

Returns the number of lines of comments associated with this keyword.

Referenced by Isis::PvlContainer::Comments(), and Isis::operator<<().

PvlFormat * Isis::PvlKeyword::GetFormat ( )

Get the current PvlFormat or create one.

Returns:: PvlFormat* Pointer to PvlFormat.

References p_formatter.

Referenced by Isis::PvlContainer::GetFormat().

int Isis::PvlKeyword::Indent ( ) const [inline]

Returns the current indent level.

Referenced by Isis::PvlContainer::Indent(), and Isis::operator<<().

bool Isis::PvlKeyword::IsEquivalent	(	QString	QString1,
		int	index = `0`
	)			const

Checks to see if a value with a specified index is equivalent to another QString.

Parameters:

	QString1	The QString to compare the value to.
	index	The index of the existing value.

Returns:: bool True if the two QStrings are equivalent, false if they're not.

Exceptions:

iException

ArraySubscriptNotInRange (index) Index out of bounds.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), Isis::IException::Programmer, and StringEqual().

bool Isis::PvlKeyword::IsNamed ( QString name ) const [inline]

Determines whether two PvlKeywords have the same name or not.

Parameters:

name

The name of the keyword to compare with this one.

Returns:: True if the names are equal, false if not.

References Name(), and StringEqual().

Referenced by Isis::KernelDb::findAll(), and Isis::KernelDb::matches().

bool Isis::PvlKeyword::IsNull ( const int index = 0 ) const

Decides whether a value is null or not at a given index.

Defaults to index = 0.

Parameters:

index

The value index

Returns:: bool True if the value is null, false if it's not.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), Isis::IException::Programmer, Size(), and StringEqual().

QString Isis::PvlKeyword::Name ( ) const [inline]

Returns the keyword name.

Returns:: The name of the keyword.

Referenced by Isis::PvlFormat::Accuracy(), Isis::PvlFormat::Add(), Isis::PvlContainer::AddKeyword(), Isis::PvlTranslationTable::AddTable(), Isis::ControlNetDiff::compare(), Isis::ControlMeasureLogData::ControlMeasureLogData(), Isis::PvlFormatPds::FormatName(), Isis::PvlFormat::FormatName(), Isis::PvlFormatPds::FormatValue(), Isis::PvlTranslationManager::InputKeyword(), IsNamed(), Isis::Preference::Load(), Isis::PvlContainer::operator-=(), Isis::operator>>(), Isis::PvlFormat::Type(), Isis::PvlContainer::Type(), Isis::PvlContainer::ValidateAllKeywords(), ValidateKeyword(), and Isis::PvlContainer::ValidateRepeatOption().

Isis::PvlKeyword::operator double ( ) const [inline]

Returns the first value in this keyword converted to a double.

References Isis::toDouble().

Isis::PvlKeyword::operator int ( ) const [inline]

Returns the first value in this keyword converted to an integer.

References Isis::toInt().

Isis::PvlKeyword::operator Isis::BigInt ( ) const [inline]

Returns the first value in this keyword converted to a BigInt.

References Isis::toBigInt().

Isis::PvlKeyword::operator QString ( ) const

References operator[]().

bool Isis::PvlKeyword::operator!= ( const PvlKeyword & key ) const [inline]

Returns true of the keyword names do not match.

Parameters:

key

The keyword to compare names with

PvlKeyword & Isis::PvlKeyword::operator+= ( QString value )

Adds a value.

Overwrites the '+=' operators to add a new value. Like AddValue(), this method keeps any previously existing values and adds the new value with unit = "" (empty QString) to the array of values for this PvlKeyword object.

Parameters:

value

The new value.

Returns:: PvlKeyword& Reference to PvlKeyword object.

See also:: AddValue(); SetValue(); operator=

References AddValue().

Referenced by operator=().

const PvlKeyword & Isis::PvlKeyword::operator= ( const PvlKeyword & other )

This is an assignment operator.

References p_formatter, and SetName().

PvlKeyword & Isis::PvlKeyword::operator= ( Isis::PvlSequence & seq )

Add values and units from a PvlSequence.

(Clears current values and units)

Parameters:

seq

The PvlSequence to add from.

Returns:: PvlKeyword& Reference to PvlKeyword object.

References Clear(), operator+=(), size, and Isis::PvlSequence::Size().

PvlKeyword & Isis::PvlKeyword::operator= ( QString value )

Sets new values.

Overwrites the '=' operator to add a new value using AddValue(). Like SetValue(), this method clears any previously existing values and resets to the given value with unit = "" (empty QString).

Parameters:

value

The value to be added.

Returns:: PvlKeyword& Reference to PvlKeyword object.

See also:: AddValue(); SetValue(); operator+=

References AddValue(), and Clear().

bool Isis::PvlKeyword::operator== ( const PvlKeyword & key ) const [inline]

Returns true of the keyword names match.

Parameters:

key

The keyword to compare names with

QString & Isis::PvlKeyword::operator[] ( int index )

Gets value for this object at specified index.

Overrides the '[]' operator to return the element in the array of values at the specified index.

Parameters:

index

The index of the value.

Returns:: IString The value at the index.

Exceptions:

iException

ArraySubscriptNotInRange (index) Index out of bounds.

See also:: const operator[]

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), Isis::IException::Programmer, and Isis::toString().

const QString & Isis::PvlKeyword::operator[] ( int index ) const

Gets value for this object at specified index.

Overrides the '[]' operator to return the element in the array of values at the specified index.

Parameters:

index

The index of the value.

Returns:: IString The value at the index.

Exceptions:

iException

ArraySubscriptNotInRange (index) Index out of bounds.

See also:: operator[]

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), and Isis::IException::Programmer.

Referenced by operator QString().

bool Isis::PvlKeyword::ReadCleanKeyword	(	QString	keyword,
		std::vector< QString > &	keywordComments,
		QString &	keywordName,
		std::vector< std::pair< QString, QString > > &	keywordValues
	)			`[static]`

This reads a keyword compressed back to 1 line of data (excluding comments, which are included on separate lines of data before the keyword).

Line concatenations must have already been handled. This returns the data of the keyword (if valid) and its status.

Parameters:

	keyword	Pvl "#COMMENT\n//COMMENT\nKeyword = (Value1,Value2,...)" QString
	keywordComments	Output: Lines of data that are comments
	keywordName	Output: Name of keyword
	keywordValues	Output: vector< pair<Value, Units> >

Returns:: bool false if it is invalid but could become valid given more data, true if it is a valid keyword and successful

References _FILEINFO_, ReadValue(), trimmed, and Isis::IException::Unknown.

Referenced by Isis::operator>>().

QString Isis::PvlKeyword::ReadLine	(	std::istream &	is,
		bool	insideComment
	)			`[static]`

This method reads one line of data from the input stream.

All spaces, newlines, returns and tabs are trimmed from the result. Once a newline is encountered, if the line we read is blank, we keep reading. Once a line with data is encountered, that is the result. All newlines, spaces, returns and tabs are consumed past this line of data until the next different character (seeks to next valid data).

Parameters:

is

The stream to read from

Returns:: QString The first encountered line of data

Referenced by Isis::operator>>().

QString Isis::PvlKeyword::ReadValue	(	QString &	keyword,
		bool &	quoteProblem,
		const std::vector< std::pair< char, char > > &	otherDelimiters
	)			`[static]`

This method looks for a data element in the QString.

A data element is a quoted QString, a units value, or one value of an array (not including units). As an example, each value in the following QString is quoted:

'VALUE' '=' ('VALUE','VALUE', 'VALUE' '

')

The returned values of each of these elements is VALUE. Explicitly defined quotes (', , <>) are stripped from the return value.

Parameters:

	keyword	Input/Output: The keyword to get the next value from (DESTRUCTIVE)
	quoteProblem	Output: The QString has an unclosed quote character

Returns:: QString The stripped out token.

QString Isis::PvlKeyword::ReadValue	(	QString &	keyword,
		bool &	quoteProblem
	)			`[static]`

Referenced by ReadCleanKeyword().

QString Isis::PvlKeyword::Reform ( const QString & value ) const [protected]

Checks if the value needs to be converted to PVL or iPVL and returns it in the correct format.

Parameters:

value

The value to be converted.

Returns:: QString The value in its proper format (iPVL or PVL).

References Isis::PvlObject::FindGroup(), g, Isis::Preference::Preferences(), ToIPvl(), ToPvl(), Isis::PvlObject::Traverse, and Isis::IString::UpCase().

void Isis::PvlKeyword::SetFormat ( PvlFormat * formatter )

Set the PvlFormatter used to format the keyword name and value(s).

Parameters:

formatter

A pointer to the formatter to be used

References p_formatter.

Referenced by Isis::PvlContainer::SetFormat().

void Isis::PvlKeyword::SetIndent ( int indent ) [inline]

Sets the indent level when outputted(for formatting).

Parameters:

indent

The new indent

Referenced by Isis::PvlContainer::SetIndent().

void Isis::PvlKeyword::SetName ( QString name )

Sets the keyword name.

Parameters:

name

The new keyword name.

References _FILEINFO_, and Isis::IException::User.

Referenced by operator=(), Isis::operator>>(), Isis::PvlContainer::PvlContainer(), and PvlKeyword().

void Isis::PvlKeyword::SetUnits	(	QString	value,
		QString	units
	)

Sets the unit of measure for a given value.

Parameters:

	value	The value to match
	units	New units to be assigned.

Exceptions:

Isis::iException::Programmer

- Given value must exist

References _FILEINFO_, ASSERT, and Isis::IException::Programmer.

void Isis::PvlKeyword::SetUnits ( QString units )

Sets the unit of measure for all current values if any exist.

Parameters:

units

New units to be assigned.

void Isis::PvlKeyword::SetValue	(	QString	value,
		QString	unit = `""`
	)

Sets new values.

If no current value exists, this method sets the given value to the PvlKeyword. Otherwise, it clears any existing values and resets to the value given using AddValue(). Defaults to unit = "" (empty QString).

Parameters:

	value	New value to be assigned.
	unit	Units of measurement corresponding to the value.

See also:: AddValue(); operator=; operator+=

References AddValue(), and Clear().

Referenced by Isis::PvlContainer::SetName().

void Isis::PvlKeyword::SetWidth ( int width ) [inline]

The width of the longest keyword name (for formatting).

Parameters:

width

the new width

int Isis::PvlKeyword::Size ( ) const [inline]

Returns the number of values stored in this keyword.

bool Isis::PvlKeyword::StringEqual	(	const QString &	QString1,
		const QString &	QString2
	)			`[static]`

Checks to see if two QStrings are equal.

Each is converted to uppercase and removed of underscores and whitespaces.

Parameters:

	QString1	The first QString
	QString2	The second QString

Returns:: bool True or false, depending on whether the QString values are equal.

References Isis::IString::ConvertWhiteSpace(), Isis::IString::Remove(), s1, s2, and Isis::IString::UpCase().

Referenced by IsEquivalent(), IsNamed(), Isis::PvlContainer::IsNamed(), IsNull(), Isis::PvlFormat::IsSingleUnit(), Isis::PvlObject::operator==(), and Isis::PvlGroup::operator==().

QString Isis::PvlKeyword::ToIPvl ( const QString & value ) const [protected]

Converts a value to iPVL format.

Parameters:

value

The value to be converted.

Returns:: QString The value in iPVL format.

References out.

Referenced by Reform().

QString Isis::PvlKeyword::ToPvl ( const QString & value ) const [protected]

Converts a value to PVL format.

Parameters:

value

The value to be converted.

Returns:: QString The value in PVL format.

References out.

Referenced by Reform().

QString Isis::PvlKeyword::Unit ( const int index = 0 ) const

Returns the units of measurement of the element of the array of values for the object at the specified index.

Defaults to index = 0.

Parameters:

index

The index of the unit.

Returns:: QString The unit at the index.

Exceptions:

iException

ArraySubscriptNotInRange (index) Index out of bounds.

References _FILEINFO_, Isis::Message::ArraySubscriptNotInRange(), and Isis::IException::Programmer.

Referenced by Isis::PvlFormatPds::FormatBinary(), Isis::PvlFormatPds::FormatEnum(), Isis::PvlFormatPds::FormatHex(), Isis::PvlFormatPds::FormatInteger(), Isis::PvlFormatPds::FormatReal(), Isis::PvlFormatPds::FormatString(), Isis::PvlFormatPds::FormatUnknown(), Isis::PvlFormat::FormatValue(), and Isis::PvlFormat::IsSingleUnit().

void Isis::PvlKeyword::ValidateKeyword	(	PvlKeyword &	pvlKwrd,
		QString	psValueType = `""`,
		PvlKeyword *	pvlKwrdValue = `NULL`
	)

Validate Keyword for type and required values.

Validate a Keyword, comparing against corresponding Template Keyword.

Template Keyword has the format: keyName = (valueType, optional/required, Values allowed separated by comma)

Author:: Sharmila Prasad (9/22/2010)

Parameters:

	pvlKwrd	- Keyword to be validated
	psValueType	- Value Type (positive / negative) for numbers
	pvlKwrdValue	- Template Keyword __Value or __Range to validate keyword's value

References _FILEINFO_, Name(), Size(), Isis::toDouble(), Isis::toInt(), and Isis::IException::User.

Referenced by Isis::PvlContainer::ValidateAllKeywords(), and Isis::PvlContainer::ValidateRepeatOption().

int Isis::PvlKeyword::Width ( ) const [inline]

Returns the current set longest keyword name.

Referenced by Isis::operator<<().