PVL: Parameter Value Language
|
|
PVL: Parameter Value Language
|
#include <Value.hh>
Public Types | |
| enum | { MIN_BASE = 2, MAX_BASE = 36 } |
| The range of allowable radix base values. More... | |
Public Member Functions | |
| virtual Value & | base (const int base) |
| Sets the numeric base. | |
| virtual int | base () const |
| Gets the numeric base. | |
| virtual Value * | clone () const =0 |
| Creates a Value clone of the Value. | |
| virtual int | compare (const Value &value) const =0 |
| Logically compares another Value to this Value. | |
| Value & | digits (const int digits) |
| Sets the number of digits for the Value representation. | |
| int | digits () const |
| Gets the number of digits for the Value representation. | |
| virtual bool | is_Array () const |
| Tests if the Value is an Array. | |
| virtual bool | is_Date_Time () const |
| Tests if the Value is a DATE_TIME String. | |
| virtual bool | is_Identifier () const |
| Tests if the Value is an IDENTIFIER String. | |
| virtual bool | is_Integer () const |
| Tests if the Value is an Integer type. | |
| virtual bool | is_Numeric () const |
| Tests if the Value is an Integer or Real. | |
| virtual bool | is_Real () const |
| Tests if the Value is a Real type. | |
| virtual bool | is_Sequence () const |
| Tests if the Value is a SEQUENCE Array. | |
| virtual bool | is_Set () const |
| Tests if the Value is a SET Array. | |
| virtual Value & | is_signed (const bool signedness) |
| Sets the signed-ness of the Value. | |
| virtual bool | is_signed () const |
| Tests if the Value is signed. | |
| virtual bool | is_String () const |
| Tests if the Value is a String type. | |
| virtual bool | is_Symbol () const |
| Tests if the Value is a SYMBOL String. | |
| virtual bool | is_Text () const |
| Tests if the Value is a TEXT String. | |
| std::string | nearest_units () const |
| Gets the "nearest" units description for the Value. | |
| virtual | operator int () const =0 |
| Casts the Value to an int. | |
| virtual | operator Integer_type () const =0 |
| Casts the Value to an Integer_type. | |
| virtual | operator Real_type () const =0 |
| Casts the Value to a Real_type. | |
| virtual | operator String_type () const =0 |
| Casts the Value to a String_type. | |
| operator unsigned int () const | |
| Casts the Value to an unsigned int. | |
| operator Unsigned_Integer_type () const | |
| Casts the Value to an Unsigned_Integer_type. | |
| bool | operator!= (const Value &value) const |
| Test if a Value is logically not equivalent to another Value. | |
| virtual Value & | operator+= (const Value &value)=0 |
| Adds another Value to this Value. | |
| bool | operator< (const Value &value) const |
| Test if this Value is logically less than another Value. | |
| bool | operator<= (const Value &value) const |
| Test if a Value is logically less than or equal to another Value. | |
| virtual Value & | operator= (const char *value)=0 |
| Assigns a C-string (char*) value to this Value. | |
| virtual Value & | operator= (const String_type &value)=0 |
| Assigns a String_type value to this Value. | |
| virtual Value & | operator= (const Real_type value)=0 |
| Assigns a Real_type value to this Value. | |
| virtual Value & | operator= (const unsigned int value)=0 |
| Assigns an unsigned int value to this Value. | |
| virtual Value & | operator= (const Integer_type value)=0 |
| Assigns an Integer_type value to this Value. | |
| virtual Value & | operator= (const int value)=0 |
| Assigns an int value to this Value. | |
| virtual Value & | operator= (const Value &value)=0 |
| Assigns another Value to this Value. | |
| bool | operator== (const Value &value) const |
| Test if this Value is logically equivalent to another Value. | |
| bool | operator> (const Value &value) const |
| Test if a Value is logically greater than another Value. | |
| bool | operator>= (const Value &value) const |
| Test if a Value is logically greater than or equal to another Value. | |
| virtual const Value & | operator[] (unsigned int index) const |
| Array notation accessor. | |
| virtual Value & | operator[] (unsigned int index) |
| Array notation accessor. | |
| Array * | parent () const |
| Gets the Value's parent. | |
| std::ostream & | print (std::ostream &out) const |
| Prints the Value ot an ostream. | |
| void | read (Parser &parser) |
| Assigns the next Value from a Parser to this Value. | |
| void | read (std::istream &in=std::cin) |
| Reads an input stream parsed as PVL syntax into this Value. | |
| Array * | root () const |
| Gets the root Array enclosing this Value. | |
| virtual Type | type () const =0 |
| Gets the Type of the Value. | |
| virtual Value & | type (const Type type_code) |
| Sets the Type of the Value. | |
| virtual std::string | type_name () const =0 |
| Gets the name for the Type of the Value. | |
| Value & | units (const std::string &units) |
| Sets the units description for the Value. | |
| std::string | units () const |
| Gets the units description for the Value. | |
| Value (const Value &value) | |
| Constructs a Value as a copy of another Value. | |
| Value (const int digits, const int base=10) | |
| Constructs a Value with specified representation digits. | |
| Value (const std::string &units="", const int digits=0, const int base=10) | |
| Constructs a Value with optional units and digits specifications. | |
| unsigned int | write (std::ostream &out=std::cout, int depth=-1) const |
| Writes the Value to an ostream. | |
| virtual | ~Value () |
| Virtual destructor. | |
Static Public Member Functions | |
| static std::string | integer_to_string (const Integer_type value, const bool is_signed=SIGNED, const int base=10, const int digits=0) |
| Converts an integer value to its string representation. | |
| static std::string | real_to_string (const Real_type value, std::ios::fmtflags format=std::ios::showpoint, unsigned int precision=0) |
| Converts a floating point Real_type value to its string representation using optional format controls. | |
| static unsigned int | string_numeric_base (const std::string &value) |
| Attemps to intuit the numeric base of string. | |
| static Integer_type | string_to_integer (const std::string &value, const int base=0) |
| Converts a string to the integer value it represents. | |
| static Real_type | string_to_real (const std::string &value) |
| Converts a string to the floating point value it represents. | |
| static std::string | type_name (const Type type_code) |
| Gets the name for a Type. | |
Static Public Attributes | |
| static const char *const | ID |
| Class identification name with source code version and date. | |
| static const bool | SIGNED = idaeim::Strings::String::SIGNED |
| static const bool | UNSIGNED = idaeim::Strings::String::UNSIGNED |
| Convience constants for setting/testing is_signed. | |
Protected Attributes | |
| int | Base |
| The numeric base of the Value. | |
| int | Digits |
| The number of digits in the Value representation. | |
| Array * | Parent |
| The Array of which this Value is a member, or NULL if not a member of an Array. | |
| std::string | Units |
| The units description string. | |
Friends | |
| class | Array |
There are two Value categories: a primitive Value - Integer, Real or String - has a corresponding type of datum; an Array is a list of Values. A digits member is provided for use in creating a text representation of a primitive Value: the precision of a Numeric Value or the field width of a String. A base member is also provided for specifying the radix in creating a text representation of a numeric Value. A pointer to a parent value is provided for navigating Array hierachies; a Value with no parent is not a member of an Array. Arrays list may have Values of mixed types and contain Arrays of mixed sizes.
Numeric Values can be directly converted to/from their primitive datum types. This enables them to be used in mathematical expressions. A String, when it represents a numerical value, can also be converted to an integer or real data type. And, of course, a String can be directly converted to/from a std::string. A set of logical operators is also provided for all Values so they can be meaningfully compared.
N.B.: The storage precision of Integer and Real values is determined at the time the PVL library is compiled by the High_Precision_Integer_type (and High_Precision_Unsigned_Integer_type) and High_Precision_Floating_Point_type typedefs defined in the Utility/Types.hh file. These are expected to be either long or long long and double or long double, respectively. To ensure complete type conversion coverage is provided the idaeim_LONG_LONG_INTEGER is defined if long long is used and idaeim_LONG_DOUBLE is defined if long double is used. The storage precision of an Integer Value is independent of the storage precision of a Real Value.
Any Value, including an Array, may have a units string that provides an arbitrary description for the Value. Provision is made for a Value to inherit the units of its parent.
A Parser is used for interpreting the Parameter Value Language syntax from text into Value objects. A Lister is used for generating Parameter Value Language syntax from Value objects.
1.39
| typedef std::string String_type |
| enum Type |
Subtype identifiers.
There are four specific implementations of Value: Integer, Real, String and Array. However, a String and Array can also be distinguished in the way they are represented with the PVL syntax. Since this distinction is not functional - in fact is a characteristic that can be readily changed within the specific type
The STRING Type codes are:
The ARRAY Type codes are:
INTEGER and REAL Type codes are also provided for the Integer and Real classes for consistency. These latter two classes are both categorized as NUMERIC as an aid to the application in identifying how it will use a Value.
Type specification codes are bit flags. These are organized such that the general Type bit is present for all specific members: Both INTEGER and REAL contain the NUMERIC bit; IDENTIFIER, SYMBOL, TEXT and DATE_TIME contain the STRING bit; and both SET and SEQUENCE contain the ARRAY bit.
Note: Value Type codes are guaranteed to be distinct from Parameter Type codes: they occupy completely separate bit fields and can not be accidently confused.
| Value | ( | const std::string & | units = "", |
|
| const int | digits = 0, |
|||
| const int | base = 10 | |||
| ) | [inline] |
Constructs a Value with optional units and digits specifications.
| units | The units string. | |
| digits | The precision of the value text representation. Zero means unpadded (6 digit floatingpoint). | |
| base | The numeric base of value text representation. If the base is not in the range MIN_BASE (2) to MAX_BASE (36), inclusive, base 0 (no base) will be used. |
| Value | ( | const int | digits, | |
| const int | base = 10 | |||
| ) | [inline, explicit] |
Constructs a Value with specified representation digits.
| digits | The precision of the value text representation. Zero means unpadded (6 digit floatingpoint). | |
| base | The numeric base of value text representation. If the base is not in the range MIN_BASE (2) to MAX_BASE (36), inclusive, base 0 (no base) will be used. |
| virtual ~Value | ( | ) | [inline, virtual] |
Virtual destructor.
| virtual Value* clone | ( | ) | const [pure virtual] |
| Array* parent | ( | ) | const [inline] |
Gets the Value's parent.
Note: The parent of a Value should only be set by entering the Value into an Array Value; it should only be cleared by removing the Value from its Array.
References Value::Parent.
Referenced by Value::root(), and idaeim::PVL::sort().
| Array * root | ( | ) | const |
Gets the root Array enclosing this Value.
References Value::Parent, and Value::parent().
| virtual operator int | ( | ) | const [pure virtual] |
| operator unsigned int | ( | ) | const [inline] |
| virtual operator Integer_type | ( | ) | const [pure virtual] |
Casts the Value to an Integer_type.
Real::operator Integer_type
String::operator Integer_type
Array::operator Integer_type
Implemented in Integer, Real, String, and Array.
Referenced by String::operator int(), and Value::operator Unsigned_Integer_type().
| operator Unsigned_Integer_type | ( | ) | const [inline] |
Casts the Value to an Unsigned_Integer_type.
References Value::operator Integer_type().
| virtual operator Real_type | ( | ) | const [pure virtual] |
| virtual operator String_type | ( | ) | const [pure virtual] |
Casts the Value to a String_type.
Real::operator String_type
String::operator String_type
Array::operator String_type
| virtual bool is_Numeric | ( | ) | const [inline, virtual] |
| virtual bool is_Integer | ( | ) | const [inline, virtual] |
Tests if the Value is an Integer type.
Reimplemented in Integer.
Referenced by Lister::write().
| virtual bool is_Real | ( | ) | const [inline, virtual] |
Tests if the Value is a Real type.
Reimplemented in Real.
Referenced by Real::Real(), and Lister::write().
| virtual bool is_String | ( | ) | const [inline, virtual] |
Tests if the Value is a String type.
Reimplemented in String.
Referenced by Parser::get_parameter(), String::operator=(), Integer::operator=(), String::String(), and Lister::write().
| virtual bool is_Identifier | ( | ) | const [inline, virtual] |
| virtual bool is_Symbol | ( | ) | const [inline, virtual] |
| virtual bool is_Text | ( | ) | const [inline, virtual] |
| virtual bool is_Date_Time | ( | ) | const [inline, virtual] |
| virtual bool is_Array | ( | ) | const [inline, virtual] |
Tests if the Value is an Array.
Reimplemented in Array.
Referenced by Array::Array(), Array::compare(), String::compare(), Real::compare(), Integer::compare(), Array::operator+=(), String::operator+=(), Real::operator+=(), Integer::operator+=(), Array::operator=(), and Lister::write().
| virtual bool is_Set | ( | ) | const [inline, virtual] |
| virtual bool is_Sequence | ( | ) | const [inline, virtual] |
Sets the Type of the Value.
| type_code | The Type to be set. |
Reimplemented in String, and Array.
Referenced by Array::Array(), Parser::get_datum(), Array::operator=(), String::operator=(), and String::String().
| virtual std::string type_name | ( | ) | const [pure virtual] |
Gets the name for the Type of the Value.
Implemented in Integer, Real, String, and Array.
Referenced by Array::default_type(), Parser::get_parameter(), Integer::Integer(), Real::Real(), String::String(), Array::type(), String::type(), Array::type_name(), String::type_name(), Real::type_name(), and Integer::type_name().
| string type_name | ( | const Type | type_code | ) | [static] |
Gets the name for a Type.
The name of Type is identical to its enum symbol except only the first character is uppercase. If the argument is not a recognized Type, then the name returned will be "Invalid".
| type_code | A Type code value. |
| virtual int base | ( | ) | const [inline, virtual] |
Gets the numeric base.
References Value::Base.
Referenced by String::operator=(), Integer::operator=(), String::String(), and Lister::write().
| Value & base | ( | const int | base | ) | [virtual] |
Sets the numeric base.
As a special case, a base of 0 is accepted for a String. This is interpreted to mean that the base should be intuited from the string representation.
| base | The numeric base value. |
| Out_of_Range | If the base argument is not within the allowable range of MIN_BASE (2) to MAX_BASE (36). |
| virtual bool is_signed | ( | ) | const [inline, virtual] |
| virtual Value& is_signed | ( | const bool | signedness | ) | [inline, virtual] |
| std::string units | ( | ) | const [inline] |
Gets the units description for the Value.
References Value::Units.
Referenced by Parser::get_value(), Array::operator=(), String::operator=(), Real::operator=(), Integer::operator=(), and Lister::write().
| std::string nearest_units | ( | ) | const |
Gets the "nearest" units description for the Value.
The units string of the Value is returned. However, if the units string is empty and the Value is a member of an Array, then the units of the parent Array will be recursively sought. The effect is to return the "nearest" non-empty units string, if there is one.
References Value::nearest_units(), Value::Parent, and Value::Units.
Referenced by Value::nearest_units(), and Lister::value_units().
| Value& units | ( | const std::string & | units | ) | [inline] |
Sets the units description for the Value.
| units | The units string to be associated with the Value. The string is copied into the Value. |
References Value::Units.
| int digits | ( | ) | const [inline] |
Gets the number of digits for the Value representation.
References Value::Digits.
Referenced by String::operator=(), Real::operator=(), Integer::operator=(), and Lister::write().
| Value& digits | ( | const int | digits | ) | [inline] |
Sets the number of digits for the Value representation.
How the number of digits is used is the responsibility of the specific type of Value.
| digits | The number of Value digits. |
References Value::Digits.
| Value & operator[] | ( | unsigned int | index | ) | [virtual] |
Array notation accessor.
| index | The Array element to reference. |
| Invalid_Argument | If the Value is not an Array. |
Reimplemented in Array.
Referenced by Array::operator[]().
| const Value & operator[] | ( | unsigned int | index | ) | const [virtual] |
Array notation accessor.
| index | The Array element to reference. |
| Invalid_Argument | If the Value is not an Array. |
Reimplemented in Array.
Assigns another Value to this Value.
| value | The Value to be assigned. |
Implemented in Integer, Real, String, and Array.
Referenced by Array::operator=(), and String::operator=().
| virtual Value& operator= | ( | const int | value | ) | [pure virtual] |
Assigns an int value to this Value.
| value | The int value to be assigned. |
| virtual Value& operator= | ( | const Integer_type | value | ) | [pure virtual] |
Assigns an Integer_type value to this Value.
| value | The Integer_type value to be assigned. |
| virtual Value& operator= | ( | const unsigned int | value | ) | [pure virtual] |
Assigns an unsigned int value to this Value.
| value | The unsigned int value to be assigned. |
Assigns a Real_type value to this Value.
| value | The Real_type value to be assigned. |
| virtual Value& operator= | ( | const String_type & | value | ) | [pure virtual] |
Assigns a String_type value to this Value.
| value | The String_type value to be assigned. |
Real::operator=(const String_type)
String::operator=(const String_type)
Array::operator=(const String_type)
| virtual Value& operator= | ( | const char * | value | ) | [pure virtual] |
Assigns a C-string (char*) value to this Value.
| value | The C-string value to be assigned. |
Adds another Value to this Value.
The meaning of addition is the responsibility of the specific type of Value.
| value | The Value to be added. |
| virtual int compare | ( | const Value & | value | ) | const [pure virtual] |
Logically compares another Value to this Value.
The meaning of the comparison is the responsibility of the specific type of Value.
| value | The Value to be compared against. |
Real::compare(const Value&) const
Implemented in Integer, Real, String, and Array.
Referenced by Value::operator!=(), Value::operator<(), Value::operator<=(), Value::operator==(), Value::operator>(), and Value::operator>=().
| bool operator== | ( | const Value & | value | ) | const [inline] |
Test if this Value is logically equivalent to another Value.
| value | The Value to compare against. |
References Value::compare().
| bool operator< | ( | const Value & | value | ) | const [inline] |
Test if this Value is logically less than another Value.
| value | The Value to compare against. |
References Value::compare().
| bool operator!= | ( | const Value & | value | ) | const [inline] |
Test if a Value is logically not equivalent to another Value.
| value | The Value to compare against. |
References Value::compare().
| bool operator> | ( | const Value & | value | ) | const [inline] |
Test if a Value is logically greater than another Value.
| value | The Value to compare against. |
References Value::compare().
| bool operator<= | ( | const Value & | value | ) | const [inline] |
Test if a Value is logically less than or equal to another Value.
| value | The Value to compare against. |
References Value::compare().
| bool operator>= | ( | const Value & | value | ) | const [inline] |
Test if a Value is logically greater than or equal to another Value.
| value | The Value to compare against. |
References Value::compare().
| unsigned int write | ( | std::ostream & | out = std::cout, |
|
| int | depth = -1 | |||
| ) | const |
Writes the Value to an ostream.
N.B.: The output is not terminated with an end-of-line. It is, however, flushed to the ostream.
| out | The ostream to which the PVL syntax will be written. | |
| depth | The indent depth to be applied to Array Values. A negative depth disables indenting. |
References Lister::flush(), and Lister::write().
Referenced by Value::print().
| std::ostream& print | ( | std::ostream & | out | ) | const [inline] |
Prints the Value ot an ostream.
The Value is written to the stream with no indenting.
| out | The ostream to which the PVL syntax will be written. |
References Value::write().
| void read | ( | std::istream & | in = std::cin |
) |
Reads an input stream parsed as PVL syntax into this Value.
A Parser is constructuced from the input stream and used to obtain the next Value interpreted from PVL syntax in the stream.
| in | The istream to be parsed for PVL syntax. |
Referenced by idaeim::PVL::operator>>().
| void read | ( | Parser & | parser | ) |
Assigns the next Value from a Parser to this Value.
The next Value interpreted from PVL syntax is obtained from the Parser. The Value obtained is assigned to this Value.
Warning: Unless the next PVL item available to the Parser is a Value, this method will fail. Also, the type of Value obtained by the must be assignable to this Value or the method will fail. Any type of Value may be assigned to an Array.
References Parser::get_value().
| string integer_to_string | ( | const Integer_type | value, | |
| const bool | is_signed = SIGNED, |
|||
| const int | base = 10, |
|||
| const int | digits = 0 | |||
| ) | [static] |
Converts an integer value to its string representation.
| value | The Integer_type value to be converted. | |
| is_signed | Either SIGNED or UNSIGNED. | |
| base | The numeric base interpretation of the string representation. A base of 0 is the same as base 10. | |
| digits | The number of digits in the representation. The string will be padded with leading 0's as needed. |
idaeim::Strings::String(long, bool, int, int)
Referenced by Integer::operator String_type(), and Lister::write().
| Value::Integer_type string_to_integer | ( | const std::string & | value, | |
| const int | base = 0 | |||
| ) | [static] |
Converts a string to the integer value it represents.
If the numeric base is 0, it will be intuited from the string: a leading sign is ignored; a leading "0x" or "0X" indicates hexadecimal (base 16) notation, a leading '0' alone indicates octal (base 8) notation, while anything else is taken to be decimal notation. To prevent padding with leading '0' characters to be interpreted as octal specify the base.
A conversion that succeeds up to a decimal point character ('.') is accepted as a real number representation truncated to an integer. Thus the conversion can be fooled by an otherwise invalid string.
Leading and trailing whitespace in the string is ignored.
| value | The string representation of the value to be converted. | |
| base | The numeric base interpretation of the string representation. |
| Out_of_Range | If the value represented is out of the range of what can be represented by an Integer_type. | |
| Invalid_Value | If the value does not represent a numeric value. |
References Value::ID, and STRTOL.
Referenced by String::operator Integer_type().
| unsigned int string_numeric_base | ( | const std::string & | value | ) | [static] |
Attemps to intuit the numeric base of string.
Leading whitespace is ignored and, after any whitespace, a leading sign character ('+' or '-') is also ignored; a leading "0x" or "0X" indicates hexadecimal (base 16) notation, a leading '0' alone indicates octal (base 8) notation, while anything else is taken to be decimal notation.
An internal test conversion based on the tentative surmise of the base representation is attempted. If the conversion fails a value of 0 is returned indicating that the string does not represent a numeric value. An empty string is defined as base 10.
| value | The string to interpret. |
References Parser::WHITESPACE.
| string real_to_string | ( | const Real_type | value, | |
| std::ios::fmtflags | format = std::ios::showpoint, |
|||
| unsigned int | precision = 0 | |||
| ) | [static] |
Converts a floating point Real_type value to its string representation using optional format controls.
The real value representation is generated by an ostringstream. If format flags and/or a precision value is specified they are applied to the ostringstream. N.B.: The showpoint format flag is always applied. If a non-zero precision is specified, it is also applied; otherwise, if neither the fixed nor scientific format flags are specified, at least one digit after the decimal point will be used.
| value | The Real_type value to be converted. | |
| format | The fmtflags to be applied to the conversion. | |
| precision | An unsigned int precision value to be applied to the conversion (0 implies default precision). |
Referenced by Real::operator String_type(), and Lister::write().
| Value::Real_type string_to_real | ( | const std::string & | value | ) | [static] |
Converts a string to the floating point value it represents.
Leading and trailing whitespace in the string is ignored.
| value | The string value to be converted. |
| Out_of_Range | If the value represented is out of the range of what can be represented by an Real_type. | |
| Invalid_Value | If the value does not represent a numeric value. |
References Value::ID, and STRTOD.
Referenced by String::operator Real_type().
friend class Array [friend] |
Referenced by Array::clone().
const char *const ID [static] |
Initial value:
"idaeim::PVL::Value (1.33 2009/07/12 04:45:07)"
Referenced by Array::default_type(), Array::Depth_Iterator::end_depth(), Array::entering(), Array::operator int(), Array::operator Integer_type(), Array::operator Real_type(), Array::operator String_type(), Array::Depth_Iterator::operator++(), Array::Depth_Iterator::operator--(), Array::Depth_Iterator::operator=(), idaeim::PVL::sort(), Value::string_to_integer(), Value::string_to_real(), and Array::type().
const bool UNSIGNED = idaeim::Strings::String::UNSIGNED [static] |
Convience constants for setting/testing is_signed.
Referenced by Integer::operator=(), and Lister::write().
const bool SIGNED = idaeim::Strings::String::SIGNED [static] |
The Array of which this Value is a member, or NULL if not a member of an Array.
Referenced by Array::entering(), Value::nearest_units(), Value::parent(), Array::removing(), and Value::root().
std::string Units [protected] |
The units description string.
Referenced by Value::nearest_units(), and Value::units().
int Digits [protected] |
The number of digits in the Value representation.
Referenced by Value::digits(), Real::operator String_type(), and Integer::operator String_type().
int Base [protected] |
The numeric base of the Value.
Referenced by Value::base(), String::operator Integer_type(), and Integer::operator String_type().
1.5.8