A label string in a file format. More...

#include <Label.h>

Inheritance diagram for Util::Label:

Public Member Functions
	Label (bool isRequired=true)
	Constructor. More...

	Label (std::string string, bool isRequired=true)
	Constructor. More...

	Label (const char *string, bool isRequired=true)
	Constructor. More...

	Label (const Label &other)
	Copy constructor. More...

virtual	~Label ()
	Destructor. More...

void	setString (std::string string)
	Set the label string. More...

void	setIsRequired (bool isRequired)
	Set the isRequired boolean flag. More...

bool	match (std::istream &in)
	Read and attempt to match next word in an input stream. More...

std::string	string () const
	Return label string. More...

bool	isRequired () const
	Is this the label for a required component? More...

Static Public Member Functions
static void	read (std::istream &in)
	Read a string without checking its value. More...

static void	clear ()
	Clear the input buffer. More...

static void	setIsMatched (bool isMatched)
	Explicitly set the isMatched flag. More...

static std::string	buffer ()
	Get the string that is currently in the input buffer. More...

static bool	isClear ()
	Is the input buffer clear? More...

static bool	isMatched ()
	Did the most recent attempt to match a Label succeed? More...

Static Public Attributes
static const int	LabelWidth = 20
	Width of label field in file output format. More...

Friends
std::istream &	operator>> (std::istream &in, Label label)
	Extractor for Label. More...

std::ostream &	operator<< (std::ostream &out, Label label)
	Inserter for Label. More...

Detailed Description

A label string in a file format.

The operator >> for a label checks if the expected label was found. The operator << outputs the expected label.

Every Label constructor takes an optional parameter isRequired that determines whether the label must be matched (isRequired == true), or if it is optional (isRequired == false). The isRequired parameter is true by default. If the input value read by the >> operator does not match the expected value and isRequired is true, the >> operator will print an error message to the Log::file() and then throw an Exception. If the input value does not match and isRequired is false, the >> operator stores the input value in a buffer string for later use. If the >> operator is invoked when the buffer is not clear (e.g., after a failed match to an optional label), the operator does not read from file and compares the expected label to the string in the buffer.

The class is designed to allow either of two methods to be used to read and check a label, referred to below as cases A and B:

Case A (the usual case, and concise) : The user constructs a Label object using a constructor that takes an expected label string as as argument, then uses the >> operator to attempt to read a string from file into the Label. For example, to read a required label that must match the expected label string "thing", one might use the line

in >> Label("thing");

Util::Label

A label string in a file format.

Definition: Label.h:73

where "in" is a symbol for an input stream. The overloaded ">>" operator reads a string from input stream into a buffer if and only if the buffer is empty. It then compares the string in the buffer to the label string (e.g., "thing"). If the strings match, the buffer is cleared and isMatch is set true. If the strings do not match and is isRequired is true, an Exception is thrown. If the strings do not match but isRequired is false, the buffer is left unchanged and isMatched is set false.

Case B (less common, and more verbose) : A user can use several static functions to perform a sequence of operations similar to those peformed by the >> operator. In this case, the user must call the static Label::read function to read a string from an input stream iff the buffer is empty, then call Label::buffer to retrieve the buffer string, and explicitly check if that string matches one or more allowed possible labels. If a match is found, call Label::clear to clear the buffer and call Label::setIsMatched to set isMatched false. This more verbose sequence of operations is used in the readObject function of the Factory class template, in which a single input string is * compared to a list of several possible valid labels.

Definition at line 72 of file Label.h.

Constructor & Destructor Documentation

◆ Label() [1/4]

Util::Label::Label ( bool isRequired = true )

explicit

Constructor.

Parameters

isRequired Is this label a required entry? (true by default)

Definition at line 61 of file Label.cpp.

◆ Label() [2/4]

Util::Label::Label	(	std::string	string,
		bool	isRequired = `true`
	)

Constructor.

Parameters

string	label string that precedes value in file format
isRequired	Is this label a required entry? (true by default)

Definition at line 69 of file Label.cpp.

◆ Label() [3/4]

Util::Label::Label	(	const char *	string,
		bool	isRequired = `true`
	)

Constructor.

Parameters

string	label string that precedes value in file format
isRequired	Is this label a required entry? (true by default)

Definition at line 77 of file Label.cpp.

◆ Label() [4/4]

Util::Label::Label ( const Label & other )

Copy constructor.

Parameters

other Label object being copied.

Definition at line 85 of file Label.cpp.

◆ ~Label()

Util::Label::~Label ( )

virtual

Destructor.

Definition at line 93 of file Label.cpp.

Member Function Documentation

◆ read()

void Util::Label::read ( std::istream & in )

static

Read a string without checking its value.

This function reads a string from input stream in if and only if the buffer is empty. It does not compare the string to an expected value. If matching is desired, use >> operator.

Parameters

in	input stream

Definition at line 35 of file Label.cpp.

References UTIL_THROW.

Referenced by pscfpp.param.Composite::__init__(), pscfpp.field.Field::__init__(), pscfpp.command.Script::__init__(), pscfpp.output.Thermo::__init__(), pscfpp.param.Matrix::__init__(), pscfpp.param.Array::__init__(), and Util::Factory< Data >::readObject().

◆ clear()

void Util::Label::clear ( )

static

Clear the input buffer.

Definition at line 25 of file Label.cpp.

Referenced by Util::Factory< Data >::readObject().

◆ setIsMatched()

void Util::Label::setIsMatched ( bool isMatched )

inlinestatic

Explicitly set the isMatched flag.

Parameters

isMatched boolean value to store in isMatched_.

Definition at line 280 of file Label.h.

References isMatched().

Referenced by Util::Factory< Data >::readObject().

◆ buffer()

std::string Util::Label::buffer ( )

inlinestatic

Get the string that is currently in the input buffer.

Definition at line 286 of file Label.h.

Referenced by Util::Factory< Data >::readObject().

◆ isClear()

bool Util::Label::isClear ( )

inlinestatic

Is the input buffer clear?

Definition at line 267 of file Label.h.

Referenced by Util::Factory< Data >::readObject(), and Util::Begin::readParam().

◆ isMatched()

bool Util::Label::isMatched ( )

inlinestatic

Did the most recent attempt to match a Label succeed?

Returns true after a successful match by operator >> or the match() function. Returns false before any attempt to match any Label, or after a failed attempt to match either a required or optional label.

Definition at line 274 of file Label.h.

Referenced by Util::ArrayParam< Type >::readLabel(), Util::MatrixParam< Type >::readLabel(), Util::Parameter::readParam(), and setIsMatched().

◆ setString()

void Util::Label::setString ( std::string string )

Set the label string.

Parameters

string label string that precedes value in file format

Definition at line 99 of file Label.cpp.

References string().

Referenced by Util::ArrayParam< Type >::ArrayParam(), Util::Begin::Begin(), and Util::MatrixParam< Type >::MatrixParam().

◆ setIsRequired()

void Util::Label::setIsRequired ( bool isRequired )

Set the isRequired boolean flag.

Parameters

isRequired boolean that is true iff the label is required.

Definition at line 105 of file Label.cpp.

References isRequired().

◆ match()

bool Util::Label::match ( std::istream & in )

Read and attempt to match next word in an input stream.

This is a convenience function that invokes operator >> to read a word and then returns the value of Label::isMatched(). For an optional Label, this returns true upon a successful match and false otherwise. For a required label, returns true upon a successful match or throws an Exception.

Definition at line 117 of file Label.cpp.

◆ string()

std::string Util::Label::string ( ) const

Return label string.

Definition at line 111 of file Label.cpp.

Referenced by Util::ArrayParam< Type >::save(), setString(), and Util::Begin::writeParam().

◆ isRequired()

bool Util::Label::isRequired ( ) const

inline

Is this the label for a required component?

Definition at line 261 of file Label.h.

Referenced by Util::Begin::isRequired(), Util::Parameter::isRequired(), and setIsRequired().

Friends And Related Function Documentation

◆ operator>>

std::istream & operator>>	(	std::istream &	in,
		Label	label
	)

friend

Extractor for Label.

Parameters

in	input stream
label	Label to be read from file

Definition at line 126 of file Label.cpp.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	out,
		Label	label
	)

friend

Inserter for Label.

Parameters

out	output stream
label	Label to be written to file

Definition at line 169 of file Label.cpp.

Member Data Documentation

◆ LabelWidth

const int Util::Label::LabelWidth = 20

static

Width of label field in file output format.

Definition at line 80 of file Label.h.

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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Label() [1/4]

◆ Label() [2/4]

◆ Label() [3/4]

◆ Label() [4/4]

◆ ~Label()

Member Function Documentation

◆ read()

◆ clear()

◆ setIsMatched()

◆ buffer()

◆ isClear()

◆ isMatched()

◆ setString()

◆ setIsRequired()

◆ match()

◆ string()

◆ isRequired()

Friends And Related Function Documentation

◆ operator>>

◆ operator<<

Member Data Documentation

◆ LabelWidth