Isis Developer Reference
Isis::PvlKeyword Class Reference

A single keyword-value pair. More...

#include <PvlKeyword.h>

Collaboration diagram for Isis::PvlKeyword:
Collaboration graph

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 setJsonValue (nlohmann::json jsonobj, QString unit="")
 Sets new value from Json.
 
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.
 
PvlKeywordoperator= (QString value)
 Sets new values.
 
void addValue (QString value, QString unit="")
 Adds a value with units.
 
void addJsonValue (nlohmann::json jsonobj, QString unit="")
 Adds a value with units.
 
PvlKeywordoperator+= (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 clearComment ()
 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.
 
PvlKeywordoperator= (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)
 
PvlFormatformat ()
 Get the current PvlFormat or create one.
 
const PvlKeywordoperator= (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

PvlFormatm_formatter
 Formatter object.
 

Friends

std::istream & operator>> (std::istream &is, PvlKeyword &result)
 Read in a keyword.
 
std::ostream & operator<< (std::ostream &os, const PvlKeyword &keyword)
 Write out the 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

◆ PvlKeyword() [1/4]

Isis::PvlKeyword::PvlKeyword ( )

Constructs a blank PvlKeyword object.

◆ PvlKeyword() [2/4]

Isis::PvlKeyword::PvlKeyword ( QString name)

Constructs a PvlKeyword object with a name.

Parameters
nameThe keyword name

References name(), and setName().

◆ PvlKeyword() [3/4]

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

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

Defaults to unit="".

Parameters
nameThe keyword name.
valueThe keyword values.
unitThe units the values are given in.

References addValue(), name(), setName(), and unit().

◆ PvlKeyword() [4/4]

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

Copy constructor.

◆ ~PvlKeyword()

Isis::PvlKeyword::~PvlKeyword ( )

Destructs a PvlKeyword object.

Member Function Documentation

◆ addComment()

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

◆ addComments()

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
commentsComments to associate with this keyword

References addComment(), and comments().

◆ addCommentWrapped()

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

Automatically wraps and adds long comments to the PvlKeyword.

Parameters
commentThe new comment to add
See also
addComment()
addComments()
clearComment()

References addComment(), comment(), and Isis::IString::Token().

◆ addJsonValue()

void Isis::PvlKeyword::addJsonValue ( nlohmann::json jsonobj,
QString unit = "" )

Adds a value with units.

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

Parameters
jsonobjNew jsonobj to be parsed and assigned.
unitUnits of measurement corresponding to the value.
See also
setJsonValue()
addValue()
Exceptions
Isis::iException::Unknown- jsonobj cannot be an array of values

References _FILEINFO_, addValue(), name(), unit(), and Isis::IException::Unknown.

Referenced by Isis::PvlObject::PvlObject(), and setJsonValue().

◆ addValue()

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
valueNew value to be assigned.
unitUnits of measurement corresponding to the value.
See also
setValue()
operator=
operator+=

References unit().

Referenced by Isis::DbProfile::add(), addJsonValue(), Isis::ControlNetDiff::addUniqueMeasure(), Isis::ControlNetDiff::addUniquePoint(), Isis::PvlToPvlTranslationManager::DoTranslation(), Isis::HiHistory::makekey(), Isis::ControlNetDiff::makeKeyword(), Isis::ControlNetDiff::makeKeyword(), operator+=(), operator=(), PvlKeyword(), setValue(), and Isis::Spice::storeValue().

◆ clear()

void Isis::PvlKeyword::clear ( )

◆ clearComment()

void Isis::PvlKeyword::clearComment ( )

Clears the current comments.

◆ comment()

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

Return a comment at the specified index.

Parameters
indexThe index of the comment.
Returns
QString The comment at the index.
Exceptions
iExceptionArraySubscriptNotInRange (index) Index out of bounds.

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

Referenced by addComment(), addCommentWrapped(), Isis::PvlContainer::comment(), Isis::pvlKeywordToJSON(), and readCleanKeyword().

◆ comments()

int Isis::PvlKeyword::comments ( ) const
inline

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

Referenced by addComments(), Isis::PvlContainer::comments(), Isis::pvlKeywordToJSON(), and readCleanKeyword().

◆ format()

PvlFormat * Isis::PvlKeyword::format ( )

Get the current PvlFormat or create one.

Returns
PvlFormat* Pointer to PvlFormat.

References m_formatter.

Referenced by Isis::PvlContainer::format(), and writeWithWrap().

◆ indent()

int Isis::PvlKeyword::indent ( ) const
inline

Returns the current indent level.

Referenced by Isis::PvlContainer::indent(), and setIndent().

◆ isEquivalent()

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
QString1The QString to compare the value to.
indexThe index of the existing value.
Returns
bool True if the two QStrings are equivalent, false if they're not.
Exceptions
iExceptionArraySubscriptNotInRange (index) Index out of bounds.

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

◆ isNamed()

bool Isis::PvlKeyword::isNamed ( QString name) const
inline

Determines whether two PvlKeywords have the same name or not.

Parameters
nameThe 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().

◆ isNull()

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

◆ name()

◆ operator double()

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

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

References Isis::toDouble().

◆ operator int()

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

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

References Isis::toInt().

◆ operator Isis::BigInt()

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

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

References Isis::toBigInt().

◆ operator QString()

Isis::PvlKeyword::operator QString ( ) const

◆ operator!=()

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

Returns true of the keyword names do not match.

Parameters
keyThe keyword to compare names with

◆ operator+=()

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
valueThe new value.
Returns
PvlKeyword& Reference to PvlKeyword object.
See also
addValue()
setValue()
operator=

References addValue().

Referenced by operator=().

◆ operator=() [1/3]

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

This is an assignment operator.

References m_formatter, and setName().

◆ operator=() [2/3]

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

Add values and units from a PvlSequence.

(Clears current values and units)

Parameters
seqThe PvlSequence to add from.
Returns
PvlKeyword& Reference to PvlKeyword object.

References clear(), operator+=(), and size().

◆ operator=() [3/3]

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
valueThe value to be added.
Returns
PvlKeyword& Reference to PvlKeyword object.
See also
addValue()
setValue()
operator+=

References addValue(), and clear().

◆ operator==()

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

Returns true of the keyword names match.

Parameters
keyThe keyword to compare names with

References stringEqual().

◆ operator[]() [1/2]

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
indexThe index of the value.
Returns
IString The value at the index.
Exceptions
iExceptionArraySubscriptNotInRange (index) Index out of bounds.
See also
const operator[]

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

◆ operator[]() [2/2]

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
indexThe index of the value.
Returns
IString The value at the index.
Exceptions
iExceptionArraySubscriptNotInRange (index) Index out of bounds.
See also
operator[]

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

◆ readCleanKeyword()

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
keywordPvl "#COMMENT\n//COMMENT\nKeyword = (Value1,Value2,...)" QString
keywordCommentsOutput: Lines of data that are comments
keywordNameOutput: Name of keyword
keywordValuesOutput: 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_, comment(), comments(), readValue(), and Isis::IException::Unknown.

◆ readLine()

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
isThe stream to read from
Returns
QString The first encountered line of data

◆ readValue() [1/2]

QString Isis::PvlKeyword::readValue ( QString & keyword,
bool & quoteProblem )
static

References readValue().

Referenced by readCleanKeyword(), and readValue().

◆ readValue() [2/2]

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
keywordInput/Output: The keyword to get the next value from (DESTRUCTIVE)
quoteProblemOutput: The QString has an unclosed quote character
Returns
QString The stripped out token.

◆ reform()

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
valueThe value to be converted.
Returns
QString The value in its proper format (iPVL or PVL).

References Isis::Preference::Preferences(), toIPvl(), toPvl(), Isis::PvlObject::Traverse, and Isis::IString::UpCase().

◆ setFormat()

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

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

Parameters
formatterA pointer to the formatter to be used

References m_formatter.

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

◆ setIndent()

void Isis::PvlKeyword::setIndent ( int indent)
inline

Sets the indent level when outputted(for formatting)

Parameters
indentThe new indent

References indent().

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

◆ setJsonValue()

void Isis::PvlKeyword::setJsonValue ( nlohmann::json jsonobj,
QString unit = "" )

Sets new value from Json.

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

Parameters
jsonobjNew jsobobj to be parsed and assigned.
unitUnits of measurement corresponding to the value.
See also
addJsonValue()

References addJsonValue(), clear(), and unit().

Referenced by Isis::PvlObject::PvlObject().

◆ setName()

◆ setUnits() [1/2]

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

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

Parameters
unitsNew units to be assigned.

Referenced by Isis::fitsToJson().

◆ setUnits() [2/2]

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

Sets the unit of measure for a given value.

Parameters
valueThe value to match
unitsNew units to be assigned.
Exceptions
Isis::iException::Programmer- Given value must exist

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

◆ setValue()

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
valueNew value to be assigned.
unitUnits of measurement corresponding to the value.
See also
addValue()
operator=
operator+=

References addValue(), clear(), and unit().

Referenced by Isis::PvlContainer::setName(), and Isis::ProcessExportPds::StandardAllMapping().

◆ setWidth()

void Isis::PvlKeyword::setWidth ( int width)
inline

The width of the longest keyword name (for formatting)

Parameters
widththe new width

References width().

◆ size()

◆ stringEqual()

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
QString1The first QString
QString2The second QString
Returns
bool True or false, depending on whether the QString values are equal.

Referenced by Isis::PvlToPvlTranslationManager::GetContainer(), Isis::PvlToXmlTranslationManager::GetContainer(), isEquivalent(), Isis::PvlContainer::isNamed(), isNamed(), isNull(), Isis::PvlFormat::isSingleUnit(), Isis::PvlGroup::operator==(), operator==(), and Isis::PvlObject::operator==().

◆ toIPvl()

QString Isis::PvlKeyword::toIPvl ( const QString & value) const
protected

Converts a value to iPVL format.

Parameters
valueThe value to be converted.
Returns
QString The value in iPVL format.

Referenced by reform().

◆ toPvl()

QString Isis::PvlKeyword::toPvl ( const QString & value) const
protected

Converts a value to PVL format.

Parameters
valueThe value to be converted.
Returns
QString The value in PVL format.

Referenced by reform().

◆ unit()

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

◆ validateKeyword()

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(), Isis::toDouble(), Isis::toInt(), and Isis::IException::User.

◆ width()

int Isis::PvlKeyword::width ( ) const
inline

Returns the current set longest keyword name.

Referenced by setWidth().

◆ writeWithWrap()

ostream & Isis::PvlKeyword::writeWithWrap ( std::ostream & os,
const QString & textToWrite,
int startColumn,
PvlFormat & format ) const
protected

Wraps output so that length doesn't exceed the character limit.

By default, the character limit is set to 80, and can be changed with the method SetCharLimit. Used as a helper method for output of PvlKeyword.

Parameters
osDesignated output stream
textToWriteThe text to be written
startColumnThe starting column after the "=" sign.
endOfLineThe EOL character
Returns
ostream& Reference to ostream.
See also
operator<<

References Isis::PvlFormat::charLimit(), format(), and Isis::PvlFormat::formatEOL().

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<< ( std::ostream & os,
const PvlKeyword & keyword )
friend

Write out the keyword.

Parameters
osThe output stream.
keywordThe PvlKeyword object to output.
Returns
ostream& Reference to ostream.
See also
writeWithWrap()

◆ operator>>

std::istream & operator>> ( std::istream & is,
PvlKeyword & result )
friend

Read in a keyword.

http://pds.jpl.nasa.gov/tools/standards-reference.shtml

Parameters
isThe input stream
resultThe keyword to read into (OUTPUT)

Member Data Documentation

◆ m_formatter

PvlFormat* Isis::PvlKeyword::m_formatter
protected

Formatter object.

Referenced by format(), operator=(), and setFormat().


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