Value (PIRL Java Packages)

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

PIRL.PVL
Class Value

java.lang.Object
  javax.swing.tree.DefaultMutableTreeNode
      PIRL.PVL.Value

All Implemented Interfaces:: Serializable, Cloneable, MutableTreeNode, TreeNode

public class Value
extends DefaultMutableTreeNode
implements Cloneable
extends DefaultMutableTreeNode
implements Cloneable

A Value is a general-purpose value entity containing arbitrary data.

A Value provides the data value for Parameter objects. It is based on the Parameter Value Language syntax:

[ ( | { ] Datum [ < Units > ] [ , Datum [...] ] [ ) | } [ < Units > ] ]

The type of Datum that a Value contains is indicated by its Type code. There are three basic types:

NUMERIC: A number with two specific types:
INTEGER (Long) with a variable radix Base
REAL (Double)
STRING: A String of characters with four specific types:
IDENTIFIER - Unquoted
SYMBOL - Single-quoted (')
TEXT - Double-quoted (")
DATE_TIME - Contains dash (-) or colon (:)
ARRAY: A Vector of zero or more Datum, with two specific types:
SET - Enclosed by curly braces ('{' and '}') or no enclosing characters
SEQUENCE - Enclosed by parentheses ('(' and ')')

There is also an UNKNOWN Type for a Value with no Datum. Note that any Datum may be an ARRAY Type, so Arrays of Arrays are supported. Arrays may be of mixed Types and non-rectangular sizes.

Any Datum, including an Array, may have an optional Units String that provides an arbitrary description for the Datum.

Version:: 1.30
Author:: Bradford Castalia, UA/PIRL
See Also:: Parameter, Parser, Serialized Form

Field Summary
`static int`	`ARRAY` Non-specific Type for a Value with a Vector datum.
`static int`	`DATE_TIME` Type for a Value with a String datum.
`static int`	`HIGHEST_BIT` The highest bit used by the Type code bit field.
`static String`	`ID` Class name and version identification.
`static int`	`IDENTIFIER` Type for a Value with a String datum.
`static int`	`INTEGER` Type for a Value with a Long datum.
`static int`	`LOWEST_BIT` The lowest bit used by the Type code bit field.
`static int`	`MASK` Selects only the Type code bit fields recognized by the Value class.
`static int`	`NUMERIC` Non-specific Type for a Value with a numeric datum.
`static int`	`REAL` Type for a Value with a Double datum.
`static int`	`SEQUENCE` Type for a Value with a datum that is a Vector of Values.
`static int`	`SET` Type for a Value with a datum that is a Vector of Values.
`static int`	`STRING` Non-specific Type for a Value with a String datum.
`static int`	`SYMBOL` Type for a Value with a String datum.
`static int`	`TEXT` Type for a Value with a String datum.
`static int`	`UNKNOWN` The classification of an empty Value.

Fields inherited from class javax.swing.tree.DefaultMutableTreeNode
`allowsChildren, children, EMPTY_ENUMERATION, parent, userObject`

Constructor Summary
`Value()` Creates an empty Value, with Type `UNKNOWN`.
`Value(byte value)` Creates an `INTEGER` Value from the primitive byte value.
`Value(char value)` Creates an `IDENTIFIER` Value from the primitive char value.
`Value(double value)` Creates a `REAL` Value from the primitive double value.
`Value(float value)` Creates a `REAL` Value from the primitive float value.
`Value(int value)` Creates an `INTEGER` Value from the primitive int value.
`Value(long value)` Creates an `INTEGER` Value from the primitive long value.
`Value(Object value)` Creates a Value whose Type depends on the class of the value object.
`Value(Parser parser)` A Parser is used to get a new Value.
`Value(short value)` Creates an `INTEGER` Value from the primitive short value.
`Value(Value value)` A Value is constructed from a copy of another Value.

Method Summary
`Value`	`Add(List list)` Adds a List of Objects to the end of the Array.
`void`	`add(MutableTreeNode value)` Invokes the Value's `Add` method.
`Value`	`Add(Object object)` Adds an Object constructed as a new Value to the end of this Array.
`Value`	`Add(Value value)` Adds a Value to the end of this Array.
`protected void`	`adopt(Vector vector)` Sets the parents of a Vector of Values to this Value.
`int`	`Array_Size()` Gets the number of elements in an Array Value.
`int`	`Base()` Gets the radix base that will be applied if this Value is an `INTEGER` Type.
`Value`	`Base(int base)` Sets the radix base to be applied if this Value is an `INTEGER` Type during a conversion between (to or from) a Long and String representation.
`Object`	`clone()` Makes a deep copy of the Value.
`Object`	`Data()` Gets the datum object from the Value.
`Value`	`Data(byte value)` Sets the datum of the Value to the primitive byte value, and sets its Type to `INTEGER`.
`Value`	`Data(char value)` The primitive char value is used to constructs a single character String which is then set to the datum of the Value.
`Value`	`Data(double value)` Sets the datum of the Value to the primitive double value, and sets its Type to `REAL`.
`Value`	`Data(Double value)` Sets the datum of the Value to the Double object, and sets its Type to `REAL`.
`Value`	`Data(float value)` Sets the datum of the Value to the primitive float value, and sets its Type to `REAL`.
`Value`	`Data(int value)` Sets the datum of the Value to the primitive int value, and sets its Type to `INTEGER`.
`Value`	`Data(List list)` Sets the Value data as an Array of Values constructed from the List.
`Value`	`Data(long value)` Sets the datum of the Value to the primitive long value, and sets its Type to `INTEGER`.
`Value`	`Data(Long value)` Sets the datum of the Value to the Long object, and sets its Type to `INTEGER`.
`Value`	`Data(Object object)` Sets the datum for the Value based on the class of the specified Object.
`Value`	`Data(short value)` Sets the datum of the Value to the primitive short value, and sets its Type to `INTEGER`.
`Value`	`Data(String value)` Sets the datum of the Value to the String object.
`Value`	`Data(Value value)` Copies the contents of a Value into this Value.
`static int`	`Default_Array_Type()` Gets the default Array Value Type to use when an Array is automatically constructed.
`static int`	`Default_Array_Type(int type)` Sets the default Array Value Type to use when an Array is automatically constructed.
`String`	`Description()` Gets a PVL description of the Value.
`String`	`Description(Lister lister)` Gets a PVL description of the Value using a specified Lister.
`double`	`double_Data()` Gets a primitive double value from the Value.
`Double`	`Double_Data()` Gets a Double object from the Value.
`boolean`	`equals(Object object)` Tests if an Object is equal to this Value.
`boolean`	`equalsIgnoreCase(Value value)` Tests if a Value is equivalent to this Value, ignoring certain cases where field values are not equal.
`Value`	`Find(byte value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(double value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(float value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(int value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(int type, Value last_value)` Finds the Value of the specified Type, beginning after the specified Value object is found.
`Value`	`Find(long value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(Object value)` Finds a Value having the datum equal to the value of the Object.
`Value`	`Find(short value)` Finds a Value having the datum equal to the primitive value.
`Value`	`Find(Value test_value)` Finds the Value that completely matches a test Value.
`Value`	`Find(Value test_value, Selector criteria)` Finds the Value that matches a test Value according the Selector criteria.
`Value`	`Find(Value test_value, Selector criteria, Value last_value)` Searches for a Value that matches a test Value according the Selector criteria, optionally after some specific Value object has been located first.
`Value`	`Find(Value test_value, Value last_value)` Finds the Value that completely matches a test Value, beginning after the specified Value within the Array.
`PVL_Exception`	`First_Warning()` Returns the first warning since the last `Reset_Warning`.
`Value`	`First_Warning(boolean first)` Enables or disables returning the first warning that occurs as the current warning status.
`Value`	`Get(int index)` Gets the Value at the specified index of the Array.
`protected void`	`graft(Value value)` Grafts the contents of a Value into this Value.
`Value`	`Insert(List list, int index)` Inserts a List of Objects into the Value's Array starting at the specified index.
`void`	`insert(MutableTreeNode value, int index)` Invokes the Value's `Insert` method.
`Value`	`Insert(Object object, int index)` Insert an Object constructed as a new Value at the specified index of the Array.
`Value`	`Insert(Value value, int index)` Inserts a Value into the Array at the specified index.
`boolean`	`Is_Array()` Tests if the Value is one of the `ARRAY` Types.
`static boolean`	`Is_Array(int type)` Tests for an `ARRAY` Type.
`boolean`	`Is_Date_Time()` Tests if the Value is the `DATE_TIME` Type.
`static boolean`	`Is_Date_Time(int type)` Tests for the `DATE_TIME` Type.
`boolean`	`Is_Identifier()` Tests if the Value is the `IDENTIFIER` Type.
`static boolean`	`Is_Identifier(int type)` Tests for the `IDENTIFIER` Type.
`boolean`	`Is_Integer()` Tests if the Value is the `INTEGER` Type.
`static boolean`	`Is_Integer(int type)` Tests for the `INTEGER` Type.
`boolean`	`Is_Numeric()` Tests if the Value is one of the `NUMERIC` Types.
`static boolean`	`Is_Numeric(int type)` Tests for a `NUMERIC` Type.
`boolean`	`Is_Real()` Tests if the Value is the `REAL` Type.
`static boolean`	`Is_Real(int type)` Tests for the `REAL` Type.
`boolean`	`Is_Sequence()` Tests if the Value is the `SEQUENCE` Type.
`static boolean`	`Is_Sequence(int type)` Tests for the `SEQUENCE` Type.
`boolean`	`Is_Set()` Tests if the Value is the `SET` Type.
`static boolean`	`Is_Set(int type)` Tests for the `SET` Type.
`boolean`	`Is_String()` Tests if the Value is one of the `STRING` Types.
`static boolean`	`Is_String(int type)` Tests for a `STRING` Type.
`boolean`	`Is_Symbol()` Tests if the Value is the `SYMBOL` Type.
`static boolean`	`Is_Symbol(int type)` Tests for the `SYMBOL` Type.
`boolean`	`Is_Text()` Tests if the Value is the `TEXT` Type.
`static boolean`	`Is_Text(int type)` Tests for the `TEXT` Type.
`boolean`	`Is_Unknown()` Tests if the Value Type is `UNKNOWN` (an empty Value).
`static boolean`	`Is_Unknown(int type)` Tests for the `UNKNOWN` Type.
`static boolean`	`Is_Value_Array(Object object)` Tests if an Object is a List suitable for an Array Value.
`static boolean`	`Is_Value(Object object)` Tests if an Object is a Value.
`Iterator`	`iterator()` Provides an Iterator starting at the first element of the list.
`Iterator`	`iterator(int index)` Provides an Iterator for Values contained in an Array positioned so that the next element returned will be from the specified index of the Array.
`PVL_Exception`	`Last_Warning()` Returns the last warning since a `Reset_Warning`.
`Value`	`Last_Warning(boolean last)` Enables or disables returning the last warning that occurs as the current warning status.
`ListIterator`	`listIterator()` Provides a ListIterator starting at the first element of the list.
`ListIterator`	`listIterator(int index)` Provides a ListIterator for Values contained in an Array positioned so that the next element returned will be from the specified index of the list.
`long`	`long_Data()` Gets a primitive long value from the Value.
`Long`	`Long_Data()` Gets a Long object from the Value.
`boolean`	`Match_Depth(Value value, Selector criteria)` Tests if a Value matches this Value using the specified criteria.
`boolean`	`Match(Value value, Selector criteria)` Tests if a Value matches this Value using the specified criteria.
`protected static void`	`orphan(Vector vector)` Sets a Vector of Values to have no parent.
`Value`	`Parent()` Gets the Value that contains this Value as an Array element.
`Value`	`Remove_All()` Empties the Value's Array.
`void`	`remove(int index)` Invokes the Value's `Remove` method.
`Value`	`Remove(int index)` Removes the Value at the specified index from the Array.
`void`	`remove(MutableTreeNode value)` Invokes the Value's `Remove` method.
`Value`	`Remove(Value value)` Removes the specified Value from the Array.
`Value`	`Reset_Warning()` Clears any warning status so that the `Warning` method will return null until the next warning condition occurs.
`protected void`	`set_data(Object data)` Set the appropriate Data variables.
`protected void`	`set_type(int type)` Sets the appropriate Type variables.
`void`	`setAllowsChildren(boolean allows)` Overrides the base class method to ensure Value integrity.
`void`	`setUserObject(Object object)` Overrides the base class method to ensure Value integrity.
`String`	`String_Data()` Gets a String object representing the Value datum.
`String`	`toString()` Gets a String representation of the Value.
`String`	`Type_Name()` Gets the name String associated with the Value's Type.
`static String`	`Type_Name(int type)` Gets the name String associated with the Type code.
`int`	`Type()` Gets the Value's Type code.
`Value`	`Type(int type)` Sets the Type of the Value.
`static int`	`Type(Object object)` Determine the Value Type of an Object.
`String`	`Units()` Get the units description String.
`Value`	`Units(String units)` Set the units description String.
`Vector`	`Vector_Data()` Gets the data Vector of an Array Value.
`PVL_Exception`	`Warning()` Gets the current warning status.
`int`	`Write()` Writes the Value in PVL syntax to `System.out` starting at level 0, not strict.
`int`	`Write(boolean indent)` Writes the Value in PVL syntax to `System.out` with or without indenting, not strict.
`int`	`Write(boolean indent, boolean strict)` Writes the Value in PVL syntax to output `System.out` with indenting and strict PVL enabled or disabled.
`int`	`Write(OutputStream output)` Writes the Value in PVL syntax to the output starting at level 0, not strict.
`int`	`Write(OutputStream output, boolean indent)` Writes the Value in PVL syntax to the output with or without indenting, not strict.
`int`	`Write(OutputStream output, int level, boolean strict)` Writes the Value in PVL syntax using a PVL Lister.

Methods inherited from class javax.swing.tree.DefaultMutableTreeNode
breadthFirstEnumeration, children, depthFirstEnumeration, getAllowsChildren, getChildAfter, getChildAt, getChildBefore, getChildCount, getDepth, getFirstChild, getFirstLeaf, getIndex, getLastChild, getLastLeaf, getLeafCount, getLevel, getNextLeaf, getNextNode, getNextSibling, getParent, getPath, getPathToRoot, getPreviousLeaf, getPreviousNode, getPreviousSibling, getRoot, getSharedAncestor, getSiblingCount, getUserObject, getUserObjectPath, isLeaf, isNodeAncestor, isNodeChild, isNodeDescendant, isNodeRelated, isNodeSibling, isRoot, pathFromAncestorEnumeration, postorderEnumeration, preorderEnumeration, removeAllChildren, removeFromParent, setParent

Methods inherited from class javax.swing.tree.DefaultMutableTreeNode

breadthFirstEnumeration, children, depthFirstEnumeration, getAllowsChildren, getChildAfter, getChildAt, getChildBefore, getChildCount, getDepth, getFirstChild, getFirstLeaf, getIndex, getLastChild, getLastLeaf, getLeafCount, getLevel, getNextLeaf, getNextNode, getNextSibling, getParent, getPath, getPathToRoot, getPreviousLeaf, getPreviousNode, getPreviousSibling, getRoot, getSharedAncestor, getSiblingCount, getUserObject, getUserObjectPath, isLeaf, isNodeAncestor, isNodeChild, isNodeDescendant, isNodeRelated, isNodeSibling, isRoot, pathFromAncestorEnumeration, postorderEnumeration, preorderEnumeration, removeAllChildren, removeFromParent, setParent

Methods inherited from class java.lang.Object
`finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

ID

public static final String ID

Class name and version identification.

See Also:: Constant Field Values

LOWEST_BIT

public static final int LOWEST_BIT

The lowest bit used by the Type code bit field.

See Also:: Constant Field Values

HIGHEST_BIT

public static final int HIGHEST_BIT

The highest bit used by the Type code bit field.

See Also:: Constant Field Values

UNKNOWN

public static final int UNKNOWN

The classification of an empty Value.

See Also:: Constant Field Values

NUMERIC

public static final int NUMERIC

Non-specific Type for a Value with a numeric datum.

The specific Type will be either INTEGER or REAL.

See Also:: INTEGER, REAL, Constant Field Values

INTEGER

public static final int INTEGER

Type for a Value with a Long datum.

See Also:: Constant Field Values

REAL

public static final int REAL

Type for a Value with a Double datum.

See Also:: Constant Field Values

STRING

public static final int STRING

Non-specific Type for a Value with a String datum.

The specific Type will be either IDENTIFIER, SYMBOL, TEXT, or DATE_TIME.

See Also:: IDENTIFIER, SYMBOL, TEXT, DATE_TIME, Constant Field Values

IDENTIFIER

public static final int IDENTIFIER

Type for a Value with a String datum.

It will be written unadorned (no quoting).

See Also:: Constant Field Values

SYMBOL

public static final int SYMBOL

Type for a Value with a String datum.

It will be written enclosed within Parser.SYMBOL_DELIMITER characters.

See Also:: Constant Field Values

TEXT

public static final int TEXT

Type for a Value with a String datum.

It will be written enclosed within Parser.TEXT_DELIMITER characters.

See Also:: Constant Field Values

DATE_TIME

public static final int DATE_TIME

Type for a Value with a String datum.

It may represent a date or time (it contains one or more Parser.DATE_TIME_DELIMITERS).

See Also:: Constant Field Values

ARRAY

public static final int ARRAY

Non-specific Type for a Value with a Vector datum.

The specific Type will be either SET or SEQUENCE.

See Also:: SET, SEQUENCE, Constant Field Values

SET

public static final int SET

Type for a Value with a datum that is a Vector of Values.

It will be written preceeded by a Parser.SET_START_DELIMITER character and ending with a Parser.SET_END_DELIMITER character.

See Also:: Constant Field Values

SEQUENCE

public static final int SEQUENCE

Type for a Value with a datum that is a Vector of Values.

It will be written preceeded by a Parser.SEQUENCE_START_DELIMITER character and ending with a Parser.SEQUENCE_END_DELIMITER character.

See Also:: Constant Field Values

MASK

public static final int MASK

Selects only the Type code bit fields recognized by the Value class.

Logical AND with another int variable will ensure that only Value Type bits remain.

See Also:: Constant Field Values

Constructor Detail

Value

public Value()

Creates an empty Value, with Type UNKNOWN.

Value

public Value(char value)

Creates an IDENTIFIER Value from the primitive char value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(char)

Value

public Value(byte value)

Creates an INTEGER Value from the primitive byte value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(byte)

Value

public Value(short value)

Creates an INTEGER Value from the primitive short value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(short)

Value

public Value(int value)

Creates an INTEGER Value from the primitive int value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(int)

Value

public Value(long value)

Creates an INTEGER Value from the primitive long value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(long)

Value

public Value(float value)

Creates a REAL Value from the primitive float value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(float)

Value

public Value(double value)

Creates a REAL Value from the primitive double value.

Parameters:: value - The data used to construct the Value.
See Also:: Data(double)

Value

public Value(Object value)
      throws PVL_Exception

Creates a Value whose Type depends on the class of the value object.

Parameters:: value - The object used to construct the Value.
Throws:: PVL_Exception - From the Data method.
See Also:: Data(Object)

Value

public Value(Parser parser)
      throws PVL_Exception

A Parser is used to get a new Value.

Parameters:: parser - The Parser source for PVL syntax.
Throws:: PVL_Exception - When the Parser encounters an unrecoverable error. The Parser may also generate a Warning which will associated with the new Parameter.
See Also:: Parser

Value

public Value(Value value)
      throws PVL_Exception

A Value is constructed from a copy of another Value.

The contents of the original Value are copied into the new Value. This includes its datum, radix base and units String. When the original Value is an Array, each datum is recursively copied and added to the new Value in the same order. The warning status from the original is not copied.

Parameters:

value - The original Value to be copied.

Throws:

PVL_Exception -

BAD_ARGUMENT: An inappropriate object was found as the element of an Array.

See Also:

set_type(int), Add(Value)

Method Detail

Long_Data

public Long Long_Data()
               throws PVL_Exception

Gets a Long object from the Value.

If the Value is Type INTEGER this is the unmodified datum, unless the datum is null in which case a Long with a 0 value is created. If the Value is Type REAL then a Long will be created from the Double datum by casting (which may result in loss of accuracy). If the Value is a STRING Type, then a Long will be constructed from the Value's long_Data method value. Note: The current radix base for the Value will be used when converting a String to a Long.

Returns:

A Long object from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is not a NUMERIC Type, or a STRING Type could not be converted to a long.

See Also:

long_Data()

long_Data

public long long_Data()
               throws PVL_Exception

Gets a primitive long value from the Value.

If the Value is Type INTEGER this is the long value contained in the Long datum, unless the datum is null in which case a value of 0L is returned. If the Value is Type REAL then a long value will be created from the Double datum by casting (which may result in loss of accuracy). If the Value is a STRING Type, then an attempt will be made to interpret the String as a long value. Note: The current radix base for the Value will be used when converting a String to a long.

Returns:

A long value from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is not a NUMERIC Type, or a STRING Type could not be converted to a long.

See Also:

Long.parseLong(String, int)

Double_Data

public Double Double_Data()
                   throws PVL_Exception

Gets a Double object from the Value.

If the Value is Type REAL this is the unmodified datum, unless the datum is null in which case a Double with a 0.0 value is created. If the Value is Type INTEGER then a Double will be created from the Long datum by casting. If the Value is a STRING Type, then an attempt will be made to interpret the String as a Double value.

Returns:

A Double object from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is not a NUMERIC Type, or a STRING Type could not be converted to a Double.

See Also:

Double.valueOf(String)

double_Data

public double double_Data()
                   throws PVL_Exception

Gets a primitive double value from the Value.

If the Value is Type REAL this is the double value contained in the Double datum, unless the datum is null in which case a value of 0.0 is returned. If the Value is Type INTEGER then a double will be created from the Long datum by casting. If the Value is a STRING Type, then an attempt will be made to interpret the String as a double value.

Returns:

A double value from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is not a NUMERIC Type, or a STRING Type could not be converted to a double.

See Also:

Double.parseDouble(String)

String_Data

public String String_Data()
                   throws PVL_Exception

Gets a String object representing the Value datum.

If the Value is a STRING Type then the unmodified datum is returned, unless the datum is null in which case an empty String is returned. No special enclosing characters associated with the PVL syntax for specific STRING Types are added (use the toString method for this format).

If the Value is a NUMERIC Type it is converted to its String representation. Note: For an INTEGER Type Value it's current radix base is used in the conversion (the representation is preceeded by a negative sign if the datum value is negative, which avoids machine precision and byte ordering issues). The radix base value and PVL syntax characters are not included (use the toString method for this format).

Returns:

A String object from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is an ARRAY Type.

Get

public Value Get(int index)

Gets the Value at the specified index of the Array.

Parameters:: index - The Array index of the Value to get.
Returns:: A Value. If this Value is not an Array, or has no data Vector, null is returned. If this Value is not an Array a PVL_Exception.ILLEGAL_SYNTAX Warning status is set.
See Also:: Vector.remove(int)

Vector_Data

public Vector Vector_Data()
                   throws PVL_Exception

Gets the data Vector of an Array Value.

Returns:

The data Vector from the Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: If the Value is not ARRAY Type.

Array_Size

public int Array_Size()

Gets the number of elements in an Array Value.

Returns:: The number of Values in the Array. If the Value is not an Array or has no elements, zero will be returned; i.e. returning zero is not determinate that the Value is an Array with an empty list. N.B.: This value does not include the number of Values in any Arrays Values this Array may contain.

Data

public Object Data()

Gets the datum object from the Value.

If the Value is an ARRAY Type, the object will be a Vector. The object will be a Long for an INTEGER Type, a Double for a REAL, or a String for a STRING.

Returns:: An object of the appropriate class for the Value.

Data

public Value Data(Long value)

Sets the datum of the Value to the Long object, and sets its Type to INTEGER. Note: A null datum is acceptable.

Parameters:: value - The new datum for the Value.
Returns:: This Value.
See Also:: set_type(int), set_data(Object)

Data

public Value Data(byte value)

Sets the datum of the Value to the primitive byte value, and sets its Type to INTEGER.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Long)

Data

public Value Data(short value)

Sets the datum of the Value to the primitive short value, and sets its Type to INTEGER.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Long)

Data

public Value Data(int value)

Sets the datum of the Value to the primitive int value, and sets its Type to INTEGER.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Long)

Data

public Value Data(long value)

Sets the datum of the Value to the primitive long value, and sets its Type to INTEGER.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Long)

Data

public Value Data(Double value)

Sets the datum of the Value to the Double object, and sets its Type to REAL. Note: A null datum is acceptable.

Parameters:: value - The new datum for the Value.
Returns:: This Value.
See Also:: set_type(int), set_data(Object)

Data

public Value Data(float value)

Sets the datum of the Value to the primitive float value, and sets its Type to REAL.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Double)

Data

public Value Data(double value)

Sets the datum of the Value to the primitive double value, and sets its Type to REAL.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(Double)

Data

public Value Data(String value)

Sets the datum of the Value to the String object.

If the String begins with the Parser.TEXT_DELIMITER character then the Value Type is set to TEXT. If the String begins with the Parser.SYMBOL_DELIMITER character then the Value Type is set to SYMBOL. In either of these cases the leading and trailing (if present) delimiter characters are removed from the String before it is assigned to the datum. Otherwise, if the String contains any Parser.DATE_TIME_DELIMITERS the Value Type is set to DATE_TIME. By default the Value Type is set to IDENTIFIER. Note: A null datum is acceptable.

If the String (after removing any enclosing delimiters) contains any of the Parser.RESERVED_CHARACTERS then a warning status is set. These characters have special meaning in the PVL syntax so writing values containing them could confuse a PVL parser that reads them.

Parameters:: value - The new datum for the Value.
Returns:: This Value.
See Also:: set_type(int), set_data(Object)

Data

public Value Data(char value)

The primitive char value is used to constructs a single character String which is then set to the datum of the Value.

The Type of the Value is set according to the rules of the Data (String) method.

Parameters:: value - The new value for the Value.
Returns:: This Value.
See Also:: Data(String)

Data

public Value Data(List list)
           throws PVL_Exception

Sets the Value data as an Array of Values constructed from the List.

The Value is classified as the default Array Type. A new data Vector is assembled containing Values constructed from the Objects in the list. If any of these Objects are Values they are copied. An Object that is a List results in a new Array Value being recursivley constructed and added to the new data Vector.

If this Value previously had data, it is replaced with the new Vector of Values. In the case where the previous data was a Vector of Values, all Values of the old Vector are orphaned (they are marked as having no parent).

Parameters:: list - The List of values to be adopted.
Returns:: This Parameter.
Throws:: PVL_Exception - From set_data.
See Also:: set_type(int), set_data(Object)

Data

public Value Data(Value value)
           throws PVL_Exception

Copies the contents of a Value into this Value.

Parameters:: value - The Value to be copied into this Value.
Returns:: This Value.
Throws:: PVL_Exception - From making a copy of the value.
See Also:: Value(Value), graft(Value)

Data

public Value Data(Object object)
           throws PVL_Exception

Sets the datum for the Value based on the class of the specified Object.

There are numerous possibilities:

Value

The Value object is copied into this Value using the Data (Value) method.

ARRAY

The Value is assigned a Vector of Values using the Data (List) method. The object classes for this case are:

List - The List object is used.
Value[] - A new Vector is constructed from the array of Values.

INTEGER

The Value is assigned a Long using the Data (Long) method. The object classes for this case are:

Long - The Long object itself is used.
Byte - A new Long is constructed from the object's longValue method.
Short - A new Long is constructed from the object's longValue method.
Integer - A new Long is constructed from the object's longValue method.

REAL

The Value is assigned a Double using the Data (Double) method. The object classes for this case are:

Double - The Double object itself is used.
Float - A new Double is constructed from the object's doubleValue method.

STRING

The Value is assigned a String using the Data (String) method. The object classes for this case are:

String - The String object itself is used.
Character - A String is obtained from the object's toString method.
char[ ] - A new String is constructed from the object.
byte[ ] - A new String is constructed from the object.

UNKNOWN

The object is null so the Value datum will be null.

Parameters:

object - The Object to be considered a the Value datum.

Returns:

This Value.

Throws:

PVL_Exception -

BAD_ARGUMENT: The Object is not suitable for a Value datum.

Insert

public Value Insert(Value value,
                    int index)
             throws PVL_Exception

Inserts a Value into the Array at the specified index.

If the Value is not already an Array Type, and does not have a datum, it is given the default Array Type. The specified Value is inserted at the specified index in this Value's Array. Any Values in the Array at, or beyond the index are moved to the next index. After the specified Value is inserted its parent is set to this Value. Note: The inserted Value is not removed from any other Array it may be in.

Parameters:

value - The Value object to be inserted.

index - The location in the Array for the insertion.

Returns:

This Value.

Throws:

PVL_Exception -

ILLEGAL_SYNTAX: The Value has a non-Array datum.

Insert

public Value Insert(Object object,
                    int index)
             throws PVL_Exception

Insert an Object constructed as a new Value at the specified index of the Array.

If the Object is a Value it is not copied.

Parameters:: object - The Object whose Value is to be inserted.; index - The location in the Array for the insertion.
Returns:: This Value.
Throws:: PVL_Exception - From Insert(Value, int).
See Also:: Value(Object), Insert(Value, int)

Insert

public Value Insert(List list,
                    int index)
             throws PVL_Exception

Inserts a List of Objects into the Value's Array starting at the specified index.

The elements of the List are Inserted in the order they occur from the List's listIterator at sequential locations starting with the specified index.

Parameters:: list - The List of Objects to Insert.; index - The first of sequential Insert locations.
Returns:: This Value.
Throws:: PVL_Exception - From the construction of a new Value from an Object.
See Also:: Insert(Object, int), List.listIterator()

Add

public Value Add(Value value)
          throws PVL_Exception

Adds a Value to the end of this Array.

If this Value is not currently an Array an attempt will be made to convert it to the default Array Type. The Insert method is used with the index at the end of the Array.

N.B.: The Array size will only be increased by one even if the Value being added is an Array; in this case the Array Value being added becomes a sub-Array whose parent is this Value. To append the entries of a Value Array to this Value's list of entries add the Value Array's list to this Value.

Parameters:: value - The Value to be added.
Returns:: This Value.
Throws:: PVL_Exception - If Type could not convert the Value to an Array, or there was a problem with the Insert of the value at the end of the Array.
See Also:: Type(int), Insert(Value, int)

Add

public Value Add(Object object)
          throws PVL_Exception

Adds an Object constructed as a new Value to the end of this Array.

If the Object is a Value it is not copied.

Parameters:: object - The Object whose Value is to be inserted.
Returns:: This Value.
Throws:: PVL_Exception - From Add(Value).
See Also:: Value(Object), Add(Value)

Add

public Value Add(List list)
          throws PVL_Exception

Adds a List of Objects to the end of the Array.

If this Value is not currently an Array an attempt will be made to convert it to the default Array Type. The Insert method is used with the index at the end of the Array.

Parameters:: list - The List of Objects to Insert.
Returns:: This Value.
Throws:: PVL_Exception - If Type could not convert the Value to an Array, or there was a problem with the Insert of the list at the end of the Array.
See Also:: Type(int), Insert(List, int)

Remove

public Value Remove(int index)

Removes the Value at the specified index from the Array.

After being removed from the Array the Value is marked as having no parent.

Parameters:: index - The Array index of the Value to be removed.
Returns:: The Value removed. If this Value is not an Array, or has no Array, null is returned. If this Value is not an Array a PVL_Exception.ILLEGAL_SYNTAX Warning status is set.
See Also:: Vector.remove(int)

Remove

public Value Remove(Value value)

Removes the specified Value from the Array.

The first occurance of the Value in the Array is removed. The Array, if there is one, is searched regardless of the Type of this Value. The search is not recursive: Only this Value's Array data Vector is searched, not the Array Vectors of any Array Values in the Array. The Value is found in the Array by equality of Value object reference, not by the equals method. To remove a Value that equals another Value, use Find and then remove the found Value from its Parent.

Parameters:: value - The Value object to be removed.
Returns:: The Value removed. If this Value is not an Array, or has no Array, null is returned. If this Value is not an Array a PVL_Exception.ILLEGAL_SYNTAX Warning status is set.
See Also:: Remove(int)

Remove_All

public Value Remove_All()

Empties the Value's Array.

The Array data Vector, if it exists, is removed regardless of the Type of this Value. All Values in the Array (but not sub-Arrays) are marked as not having a parent.

Returns:: This Value.

set_data

protected void set_data(Object data)
                 throws PVL_Exception

Set the appropriate Data variables.

The Type of the data object determines how the internal data variables are set. Consistency of the Value's data is ensured by always setting it with this method.

For Vector data, the data becomes the base class children data Vector. Its contents are adopted which confirms that each element is a Value and its parent is set to this Value. The local datum is set to null.

For non-ARRAY data, the data becomes the datum of the Value. The children data Vector is orphaned which sets all of its Value elements to have no parent, and then set to null.

>>> WARNING <<< The Type of the Value is not updated. Accordingly, this method should only be used by methods associated with this package that will also set the Type appropriately.

Parameters:

data - The Object to become Value's data.

Throws:

PVL_Exception -

BAD_ARGUMENT: If the data object is not a valid class for a Value (null is acceptable), or the data object is a Vector and one of its elements is not a Value.

graft

protected void graft(Value value)
              throws PVL_Exception

Grafts the contents of a Value into this Value.

In effect, this Value becomes the specified Value.

The datum reference is set (not copied) to the specified Value's datum reference along with the base, units, and warning status. The Array (children) data Vector reference is set to the specified Value's Vector and if it has contents they are adopted by this Value (the specified Value's children data Vector is set to null to avoid any possible confusion). The Type is set to be the same as the specified Value.

Parameters:: value - The Value object to graft into this Value.
Throws:: PVL_Exception - From adopt.
See Also:: adopt(Vector), set_type(int)

adopt

protected void adopt(Vector vector)
              throws PVL_Exception

Sets the parents of a Vector of Values to this Value.

>>> WARNING <<<

Only the parent references for the Values in the Vector are set to this Value. The Vector itself may still be referenced by some other Value. In this case the adoption of the Vector will not be complete until the reference in the former parent is changed (e.g. to null).

Parameters:

vector - The Vector of Parameters to adopt.

Throws:

PVL_Exception -

BAD_ARGUMENT: If an entry in the list is not a Value.

orphan

protected static void orphan(Vector vector)

Sets a Vector of Values to have no parent.

>>> WARNING <<<

Only the parent references for the Values in the Vector are set to null. The Vector itself may still be referenced by some other Value. In this case the orphaning of the Vector will not be complete until the reference in the former parent is changed (e.g. to null).

Parameters:: vector - The Vector of Values to orphan.

Type

public int Type()

Gets the Value's Type code.

Returns:: The Type code.

Type

public static int Type(Object object)

Determine the Value Type of an Object.

The Object is considered to be potentially the datum for a Value and is tested to see if it is an instance of an acceptable Java Class. The object must be an instance of a class suitable for being assigned directly as the datum or data Vector of a Value. Only a basic Type can be determined by examining an object, except for the specific NUMERIC Types. Note: If this method does not provide a valid Type that does not necessarily mean that the object can not be used by the Data (Object) method.

Parameters:: object - The Object to be examined.
Returns:: The int basic Type code associated with a Value in which the object is its datum. Long objects return the INTEGER code, Double objects the REAL code, String objects the STRING code, and List objects return the ARRAY code. When the object is null, the UNKNOWN code is returned. If an invalid object is specified, then the return value is -1.
See Also:: Data(Object)

Type

public Value Type(int type)
           throws PVL_Exception

Sets the Type of the Value.

When the Value does not have any data (neither a datum nor a data Vector), or the current Type is UNKNOWN, then the Value is simply set to the specifed Type. When the new Type is UNKNOWN then any existing data is removed with the set_data (null) method and then the Type is set.

When the current Value Type is the same basic Type as the new Type - i.e. they are both NUMERIC, STRING or ARRAY Types - then the Value is set to the new Type. In the case of a Type change from INTEGER to DOUBLE, or vice versa, the datum is cast to the new Type.

When the Value is a STRING Type and the new Type is NUMERIC an attempt is made to parse the String using the Value's Double_Data method to produce a REAL Type datum, or the Long_Data method to produce an INTEGER Type datum. In the latter case the current radix base of the Value will be used in the conversion. If the String datum is not a valid representation of the appropriate Type of number then a PVL_Exception.ILLEGAL_SYNTAX will be thrown.

When the Value is a NUMERIC Type and the new Type is STRING the datum is converted to its String representation using the Value's String_Data method. For an INTEGER Type the current radix base of the Value will be used in the conversion.

When the Value is to be converted to an ARRAY Type the current Value is cloned, the current Value is set to the (empty) default Array Type, and the copy of the original Value is Inserted as the first element of the Array. In effect the original Value is "pushed down" as the first and only element of what has become an Array Value; i.e. the new Array contains a copy of the original Value.

When the Value is an ARRAY Type and the new Type is not, this conversion can only be accomplished if the current Array contains less than two Values. If the Array contains no Values then the new Type is simply set. If the Array contains two or more Values then a PVL_Exception.INCOMPATIBLE_TYPES will be thrown. For an Array with just one Value an attempt is made to convert that Value to the new Type by recursively calling this Type method. If this succeeds then the converted value is grafted into this Value to become the new Type. In effect a single Value contained in an Array is "pulled up" into this Value; i.e. the Array's Value becomes this Value with the new Type.

Parameters:

type - The new Type for the Value.

Returns:

This Value.

Throws:

PVL_Exception -

INCOMPATIBLE_TYPES: An Array Value could not be converted to a non-Array value because the Array containes more than one Value, or the Array data Vector unexpectedly contains a non-Value entry.
ILLEGAL_SYNTAX: A String datum could not be converted to a number because the String is not a valid represenation of the specified numerical Type.
BAD_ARGUMENT: Conversion to or from an unsupported Value Type.

set_type

protected void set_type(int type)

Sets the appropriate Type variables.

Consistency of the Value's Type is ensured by always setting it with this method. If the Type code is for an ARRAY, then the allowsChildren variable of the DefaultMutableTreeNode base class will be set to true; otherwise it will be set to false.

>>> WARNING <<< The data of the Value is not checked for consistency with the Type. Accordingly, this method should only be used by methods associated with this package that will also set the data appropriately.

Parameters:: type - The int Type code for the Value.

Type_Name

public static String Type_Name(int type)

Gets the name String associated with the Type code.

Type names are identical to the names of the Type code constants.

Parameters:: type - The Type code int.
Returns:: The appropriate Type name String. An invalid type code will return a null.

Type_Name

public String Type_Name()

Gets the name String associated with the Value's Type.

Returns:: The appropriate Type name String.

Default_Array_Type

public static int Default_Array_Type(int type)

Sets the default Array Value Type to use when an Array is automatically constructed.

Parameters:: type - The Array Type to use by default. If this is not an Array Type nothing is done.
Returns:: The previous value.

Default_Array_Type

public static int Default_Array_Type()

Gets the default Array Value Type to use when an Array is automatically constructed.

Returns:: The Array Type to use by default.
See Also:: Default_Array_Type(int)

Is_Value

public static boolean Is_Value(Object object)

Tests if an Object is a Value.

Parameters:: object - The Object to be tested.
Returns:: true if the object is an instance of the Value class; otherwise false (also false if the object is null).

Is_Value_Array

public static boolean Is_Value_Array(Object object)

Tests if an Object is a List suitable for an Array Value.

Note: The contents of the List are recursively checked to all be Values. null data Vectors are acceptable Values.

Parameters:: object - The Object to be tested.
Returns:: true if the object is an instance of List and all its elements are Values, or the object is null; otherwise false.
See Also:: Is_Value(Object), Is_Array()

Is_Numeric

public boolean Is_Numeric()

Tests if the Value is one of the NUMERIC Types.

NUMERIC Types include INTEGER and REAL Types.

Returns:: true if the Value has a NUMERIC Type.
See Also:: NUMERIC

Is_Integer

public boolean Is_Integer()

Tests if the Value is the INTEGER Type.

Returns:: true if the Value is the INTEGER Type.
See Also:: INTEGER

Is_Real

public boolean Is_Real()

Tests if the Value is the REAL Type.

Returns:: true if the Value is the REAL Type.
See Also:: REAL

Is_String

public boolean Is_String()

Tests if the Value is one of the STRING Types.

STRING Types include IDENTIFIER, SYMBOL, TEXT and DATE_TIME Types.

Returns:: true if the Value has a STRING Type.
See Also:: STRING

Is_Identifier

public boolean Is_Identifier()

Tests if the Value is the IDENTIFIER Type.

Returns:: true if the Value is the IDENTIFIER Type.
See Also:: IDENTIFIER

Is_Symbol

public boolean Is_Symbol()

Tests if the Value is the SYMBOL Type.

Returns:: true if the Value is the SYMBOL Type.
See Also:: SYMBOL

Is_Text

public boolean Is_Text()

Tests if the Value is the TEXT Type.

Returns:: true if the Value is the TEXT Type.
See Also:: TEXT

Is_Date_Time

public boolean Is_Date_Time()

Tests if the Value is the DATE_TIME Type.

Returns:: true if the Value is the DATE_TIME Type.
See Also:: DATE_TIME

Is_Array

public boolean Is_Array()

Tests if the Value is one of the ARRAY Types.

ARRAY Types include SET and SEQUENCE Types.

Returns:: true if the Value has an ARRAY Type.
See Also:: ARRAY

Is_Set

public boolean Is_Set()

Tests if the Value is the SET Type.

Returns:: true if the Value is the SET Type.
See Also:: SET

Is_Sequence

public boolean Is_Sequence()

Tests if the Value is the SEQUENCE Type.

Returns:: true if the Value is the SEQUENCE Type.
See Also:: SEQUENCE

Is_Unknown

public boolean Is_Unknown()

Tests if the Value Type is UNKNOWN (an empty Value).

Returns:: true if the Value Type is UNKNOWN.
See Also:: UNKNOWN

Is_Numeric

public static boolean Is_Numeric(int type)

Tests for a NUMERIC Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is for a NUMERIC.
See Also:: Is_Numeric()

Is_Integer

public static boolean Is_Integer(int type)

Tests for the INTEGER Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is INTEGER.
See Also:: INTEGER

Is_Real

public static boolean Is_Real(int type)

Tests for the REAL Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is REAL.
See Also:: REAL

Is_String

public static boolean Is_String(int type)

Tests for a STRING Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is for a STRING.
See Also:: Is_String()

Is_Identifier

public static boolean Is_Identifier(int type)

Tests for the IDENTIFIER Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is IDENTIFIER.
See Also:: IDENTIFIER

Is_Symbol

public static boolean Is_Symbol(int type)

Tests for the SYMBOL Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is SYMBOL.
See Also:: SYMBOL

Is_Text

public static boolean Is_Text(int type)

Tests for the TEXT Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is TEXT.
See Also:: TEXT

Is_Date_Time

public static boolean Is_Date_Time(int type)

Tests for the DATE_TIME Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is DATE_TIME.
See Also:: DATE_TIME

Is_Array

public static boolean Is_Array(int type)

Tests for an ARRAY Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is for an ARRAY.
See Also:: Is_Array()

Is_Set

public static boolean Is_Set(int type)

Tests for the SET Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is SET.
See Also:: SET

Is_Sequence

public static boolean Is_Sequence(int type)

Tests for the SEQUENCE Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is SEQUENCE.
See Also:: SEQUENCE

Is_Unknown

public static boolean Is_Unknown(int type)

Tests for the UNKNOWN Type.

Parameters:: type - The Type code int.
Returns:: true if the Type is UNKNOWN.
See Also:: UNKNOWN

Base

public int Base()

Gets the radix base that will be applied if this Value is an INTEGER Type.

Returns:: The current radix base int associated with this Value.
See Also:: Base(int)

Base

public Value Base(int base)
           throws PVL_Exception

Sets the radix base to be applied if this Value is an INTEGER Type during a conversion between (to or from) a Long and String representation.

The radix base is associated with the Value regardless of whether it is currently an INTEGER Type and remains associated with the Value regarless of Type changes. Valid radix base values are in the range Character.MIN_RADIX <= |base| <= Character.MAX_RADIX. The sign of the radix base value will be applied to the Value datum when the radix base is used, but is otherwise ignored. For example, if a negative radix base is applied to positive INTEGER Value, then long_Data will return a positive long value but String_Data will return the represenation of the negative of the long value since a conversion has been applied. Using negative radix base numbers can be a source of confusion and probably should be avoided.

Parameters:

base - The radix base int to be used.

Returns:

This Value.

Throws:

PVL_Exception -

VALUE_OVERFLOW: The value of the radix base out of range.

Units

public String Units()

Get the units description String.

Returns:: The units description String, which may be null.

Units

public Value Units(String units)

Set the units description String.

This is an arbitrary String that is expected to provide some form of real world units description for the Value. It may be null to remove any units description.

Parameters:: units - The units description String.
Returns:: This Value.

Parent

public Value Parent()

Gets the Value that contains this Value as an Array element.

Returns:: The Array that contains this Value in its data Vector, or null if this Value is not contained in an Array.

Warning

public PVL_Exception Warning()

Gets the current warning status.

When conditions are encountered that are unusual enough to warrant attention, but not an error condition that would prevent successful processing which would cause an exception to be thrown, a warning condition is registered. The warning is in the form of a PVL_Exception that was not thrown. The current warning status is either the First_Warning or the Last_Warning since a Reset_Warning.

Returns:: The current warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:: PVL_Exception, First_Warning(boolean), Last_Warning(boolean), Reset_Warning()

Reset_Warning

public Value Reset_Warning()

Clears any warning status so that the Warning method will return null until the next warning condition occurs.

Returns:: This Value.
See Also:: Warning()

First_Warning

public Value First_Warning(boolean first)

Enables or disables returning the first warning that occurs as the current warning status.

The first warning is one that occurs when the current warning status is null.

Parameters:: first - true to enable returning the first warning status; false to return the last warning that occurred as the current warning status.
Returns:: This Value.
See Also:: Warning(), First_Warning(), Reset_Warning()

First_Warning

public PVL_Exception First_Warning()

Returns the first warning since the last Reset_Warning.

Returns:: The first warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:: PVL_Exception, Warning(), First_Warning(boolean), Reset_Warning()

Last_Warning

public Value Last_Warning(boolean last)

Enables or disables returning the last warning that occurs as the current warning status.

The last warning is the most recent one regarless of any previous warning conditions that may have occured without an intervening Reset_Warning.

Parameters:: last - true to enable returning the last warning status; false to return the first warning condition that occurred as the current warning status.
Returns:: This Value.
See Also:: Warning(), Last_Warning(), Reset_Warning()

Last_Warning

public PVL_Exception Last_Warning()

Returns the last warning since a Reset_Warning.

Returns:: The last warning status as a PVL_Exception object, or null if no warning condition is registered.
See Also:: PVL_Exception, Warning(), Last_Warning(boolean), Reset_Warning()

clone

public Object clone()

Makes a deep copy of the Value.

Overrides:: clone in class DefaultMutableTreeNode

Returns:: An Object of class Value that is a copy of this Value.
See Also:: Value(Value), Object.clone(), Cloneable

toString

public String toString()

Gets a String representation of the Value.

For an INTEGER Type Value with a decimal radix base the Long datum's toString representation is returned. If the datum is null a 0L value is provided. When the radix base is not decimal then the radix base is incuded in the representation using PVL syntax:

[ sign ] base#value#

Where the negative sign is used if either the radix base or the datum value (but not both) are negative, the radix base is represented in decimal notation, and the datum value is represented in the character set corresponding to the radix base. The crosshatch characters are the Parser.NUMBER_BASE_DELIMITER character.

For a REAL Type Value the Double datum's toString representation is returned. If the datum is null a "0.0" representation is returned.

For STRING Types the String datum is returned (the empy string is used for a null datum) enclosed in any PVL syntax characters appropriate for its specific Type. For the TEXT Type the Parser.TEXT_DELIMITER character starts and ends the String, while for the SYMBOL Type the Parser.SYMBOL_DELIMITER is used.

For Values with an ARRAY Type, the Type_Name is used as a place holder (use the Write method to get all of the individual Array entries). For the SET Type this is enclosed in Parser.SET_START_DELIMITER and Parser.SET_END_DELIMITER characters. For the SEQUENCE Type the Parser.SEQUENCE_START_DELIMITER and Parser.SEQUENCE_END_DELIMITER characters enclose the name.

For Values with the UNKNOWN Type just the Type_Name is provided.

Overrides:: toString in class DefaultMutableTreeNode

Returns:: A String description of the Value datum plus any units.
See Also:: Write(OutputStream, int, boolean), Type_Name(), Long.toString(), Double.toString()

Description

public String Description(Lister lister)

Gets a PVL description of the Value using a specified Lister.

The Value is Writen to a StringWriter on the specified Lister and the resultant String is returned. If the Write method produces an exception, the exception message is returned. The Lister will have its Writer set to the StringWriter used to write the PVL syntax. If no Lister is specified (the argument is null) then a default Lister will be provided.

Parameters:: lister - The Lister to use when writing the PVL syntax.
Returns:: The String describing the Value in PVL syntax.

Description

public String Description()

Gets a PVL description of the Value.

The Value is Writen to a StringWriter on a default Lister and the resultant String is returned. If the Write method produces an exception, the exception message is returned.

Returns:: The String describing the Value in PVL syntax.
See Also:: Description(Lister)

Match

public boolean Match(Value value,
                     Selector criteria)

Tests if a Value matches this Value using the specified criteria.

Parameters:: value - The Value to be compared to this Value.; criteria - The Selector providing the comparison criteria.
Returns:: true if there is a criteria match; false otherwise.
See Also:: Selector

Match_Depth

public boolean Match_Depth(Value value,
                           Selector criteria)

Tests if a Value matches this Value using the specified criteria.

If the Value is an Array matching is done recursively on all Values of the Array. The match succeeds if all Values match.

N.B.: To avoid unnecessary redundant recursive comparisons of Array data values if the Data criteria is included in the criteria the data comparison is only done for non-Array Values.

Parameters:: value - The Value to be compared to this Value.; criteria - The Selector providing the comparison criteria.
Returns:: true if there is a criteria match; false otherwise.
See Also:: Selector, Selection

equals

public boolean equals(Object object)

Tests if an Object is equal to this Value.

An Object is equal to this Value when it is also a Value object and all of its fields are equal to this Value's fields. A Selection object with VALUE_MATCH criteria is used with the Match_Depth method.

Overrides:: equals in class Object

Parameters:: object - The Object to be compared to this Value.
Returns:: true if the object equals this Value, false otherwise.
See Also:: Match_Depth(Value, Selector), Selection, Selector.VALUE_MATCH

equalsIgnoreCase

public boolean equalsIgnoreCase(Value value)

Tests if a Value is equivalent to this Value, ignoring certain cases where field values are not equal.

Unlike equals, for a Value to be equivalent to this Value the fields need only be logically equivalent, rather than containing the same value. A Selection object with VALUE_MATCH but Specific (false) criteria is used with the Match_Depth method.

Parameters:: value - The Value to be compared to this Value.
Returns:: true if the Value is logically equivalent to this Value, false otherwise.
See Also:: Match_Depth(Value, Selector), Selection, Selector.VALUE_MATCH, Selection.Specific(boolean)

Write

public int Write(OutputStream output,
                 int level,
                 boolean strict)
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax using a PVL Lister.

The Lister is created with the output stream as its list destination using the specified indent level and syntax strictness.

Parameters:

output - The OutputStream to receive what is written. If output is null System.out is used.

level - The indent level at which to start the listing. If the level is negative, indenting is disabled.

strict - Use strict PVL syntax if true; otherwise use an easier to read format.

Returns:

The total number of bytes written.

Throws:

PVL_Exception -

BAD_ARGUMENT: If an element in an Array is not a Value.
ILLEGAL_SYNTAX: If a PVL reserved character was found in an unenclosed STRING datum during strict writing.

IOException - From the OutputStream write method.

See Also:

Lister.Write(Value)

Write

public int Write()
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax to System.out starting at level 0, not strict.

Returns:: The total number of bytes written.
Throws:: PVL_Exception - From the foundation Write method.; IOException - From the OutputStream write method.
See Also:: Write(OutputStream, int, boolean)

Write

public int Write(boolean indent)
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax to System.out with or without indenting, not strict.

Parameters:: indent - Enable indenting starting at level 0 if true; disable indenting otherwise.
Returns:: The total number of bytes written.
Throws:: PVL_Exception - From the foundation Write method.; IOException - From the OutputStream write method.
See Also:: Write(OutputStream, int, boolean)

Write

public int Write(boolean indent,
                 boolean strict)
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax to output System.out with indenting and strict PVL enabled or disabled.

Parameters:: indent - Enable indenting starting at level 0 if true; disable indenting otherwise.; strict - Use strict PVL syntax if true; otherwise use an easier to read format.
Returns:: The total number of bytes written.
Throws:: PVL_Exception - From the foundation Write method.; IOException - From the OutputStream write method.
See Also:: Write(OutputStream, int, boolean)

Write

public int Write(OutputStream output)
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax to the output starting at level 0, not strict.

Parameters:: output - The OutputStream to receive what is written.
Returns:: The total number of bytes written.
Throws:: PVL_Exception - From the foundation Write method.; IOException - From the OutputStream write method.
See Also:: Write(OutputStream, int, boolean)

Write

public int Write(OutputStream output,
                 boolean indent)
          throws PVL_Exception,
                 IOException

Writes the Value in PVL syntax to the output with or without indenting, not strict.

Parameters:: output - The OutputStream to receive what is written.; indent - Enable indenting starting at level 0 if true; disable indenting otherwise.
Returns:: The total number of bytes written.
Throws:: PVL_Exception - From the foundation Write method.; IOException - From the OutputStream write method.
See Also:: Write(OutputStream, int, boolean)

iterator

public Iterator iterator(int index)

Provides an Iterator for Values contained in an Array positioned so that the next element returned will be from the specified index of the Array.

This Iterator does not descend into nested Array Values. The DefaultMutableTreeNode base class provdes various Enumeration objects that will traverse the hierarchy in different orders.

For non-Array Values an "empty" Iterator will be provided. This will act the same as an Iterator on an empty data Vector.

Parameters:: index - The starting list element.
Returns:: An Iterator object.
See Also:: Iterator, DefaultMutableTreeNode

iterator

public Iterator iterator()

Provides an Iterator starting at the first element of the list.

Returns:: An Iterator object.
See Also:: iterator(int)

listIterator

public ListIterator listIterator(int index)

Provides a ListIterator for Values contained in an Array positioned so that the next element returned will be from the specified index of the list.

The functionality of the Value Iterator is provided (which it extends) with the ListIterator interface implemented.

Note: When the Value is an ARRAY Type, but has no data Vector, an empty one is provided so the add method will be able to insert new Values into the Array.

Parameters:: index - The starting list element.
Returns:: A ListIterator object.
See Also:: iterator(), ListIterator

listIterator

public ListIterator listIterator()

Provides a ListIterator starting at the first element of the list.

Returns:: A ListIterator object.
See Also:: listIterator(int)

Find

public Value Find(Value test_value,
                  Selector criteria,
                  Value last_value)

Searches for a Value that matches a test Value according the Selector criteria, optionally after some specific Value object has been located first.

A search is made of the Values contained in this Array, and, recursively, any Arrays it contains. The search is depth-wise: each Array Value is searched when it is encountered.

The search must first find the last_value (having the same object reference) before proceeding with the search for the test_value beginning with the Value following the last_value. If the last_value is null, then the search for the test_value begins with the first Value contained in this Array.

The search compares each value encountered against the test_value using the Selector criteria's Values_Match method. The first Value that matches the test_value is returned. If the last_value or the test_value is not found, null is returned. If the last_value could not be found a PVL_Exception.NO_LAST_LOCATION warning status is registered with this Value. If the Value in which to Find is not an ARRAY Type, null will be returned and a PVL_Exception.ILLEGAL_SYNTAX warning status will be set.

The test_value may be any parameter, pre-existing or created ad hoc as a template for the Selector criteria. A Selector offers numerous criteria that may be conditionally applied when comparing the test_value with Array members. Note: The PIRL.PVL package provides a Selection class that implements the Selector interface.

Parameters:: test_value - A Value object to use for testing Values in this Array for a match.; criteria - A Selector object providing the methods to determine if Values match.; last_value - A Value object to be found within the Array before search comparisons begin. If null, begin the search at the first element of the Array.
Returns:: The Value object that was found, or null if not found. If the Value in which to Find is not an ARRAY Type, null will be returned and a PVL_Exception.ILLEGAL_SYNTAX warning status will be set. If the last_value could not be found a PVL_Exception.NO_LAST_LOCATION warning status is registered with this Value.
See Also:: Selector, Selection.Values_Match(Value, Value)