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

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.

See Also:
  `Parameter`, `Parser`, Serialized Form

### Field Summary

Fields
`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

Constructors
Constructor and Description
`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

Methods
`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 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.
See Also:
  `toString()`, `Long.toString(long, int)`, `Double.toString()`

#### 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.
See Also:
  `Type(int)`, `Remove(Value)`, `Vector.insertElementAt(Object, int)`

#### 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 `Insert`ed 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.
See Also:
  `Type(Object)`, `adopt(Vector)`, `orphan(Vector)`

#### 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 ``clone``d, the current Value is set to the (empty) `default Array Type`, and the copy of the original Value is ``Insert``ed 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 ``graft``ed 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.
See Also:
  `NUMERIC`, `STRING`, `ARRAY`, `set_type(int)`, `Long.doubleValue()`, `Double.longValue()`, `clone()`, `graft(Value)`, `Long_Data()`, `Double_Data()`, `String_Data()`

#### 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.
See Also:
  `Character.MIN_RADIX`, `Character.MAX_RADIX`

#### 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 `Write`n 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 `Write`n 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)`

#### Find

    public Value Find(byte value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(byte)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(short value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(short)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(int value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(int)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(long value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(long)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(float value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(float)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(double value)

Finds a Value having the datum equal to the primitive value.

A test_value is constructed from the primitive value and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The primitive value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Value(double)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(Object value)
               throws PVL_Exception

Finds a Value having the datum equal to the value of the Object.

A test_value is constructed from the object and a selection criteria requiring a data match is provided.

Parameters:
  `value` - The object having the value for the datum being sought.
Returns:
  The Value object that was found, or null if not found.
Throws:
  `PVL_Exception` - If a Value could not be constructed from the Object.
See Also:
  `Value(Object)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(int type,
             Value last_value)

Finds the Value of the specified Type, beginning after the specified Value object is found.

The Type matching is specific. For a general Type match - i.e. where any two `NUMERIC`, `STRING` or `ARRAY` Values will match - use:

    Find (new Value ().Type (type),
          new Selection ().Type (true).Specific (false),
          last_value);

Parameters:
  `type` - The Type code to search for.
  `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.
See Also:
  `Find(int)`, `Find(Value, Selector, Value)`, `Selection.Type(boolean)`, `Selection.Specific(boolean)`

#### Find

    public Value Find(Value test_value)

Finds the Value that completely matches a test Value.

A complete match requires an exact match of the Value data and its Type (as well as the numeric base for integers), and any units String. Note: Value contents, not Value object references, are compared.

Parameters:
  `test_value` - The Value to use when testing for a match.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Find(Value, Selector, Value)`

#### Find

    public 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.

Parameters:
  `test_value` - A Value object to use for testing Values in this Array for a 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.
See Also:
  `Find(Value)`, `Find(Value, Selector, Value)`

#### Find

    public Value Find(Value test_value,
             Selector criteria)

Finds the Value that matches a test Value according the Selector criteria.

Parameters:
  `test_value` - A Value to use for testing Values in this Array for a match.
  `criteria` - A Selector object providing the methods to determine if Values match.
Returns:
  The Value object that was found, or null if not found.
See Also:
  `Find(Value, Selector, Value)`

#### setUserObject

    public void setUserObject(Object object)

Overrides the base class method to ensure Value integrity.

Specified by:
  `setUserObject` in interface `MutableTreeNode`
Overrides:
  `setUserObject` in class `DefaultMutableTreeNode`
Parameters:
  `object` - Since the `userObject` of a Value is a reference to itself, it is illegal to use this method. A `PVL_Exception.BAD_ARGUMENT` warning status is set.
See Also:
  `DefaultMutableTreeNode.setUserObject(Object)`

#### setAllowsChildren

    public void setAllowsChildren(boolean allows)

Overrides the base class method to ensure Value integrity.

Overrides:
  `setAllowsChildren` in class `DefaultMutableTreeNode`
Parameters:
  `allows` - Since the ability of a Value to have children is totally determined by its Type (only Arrays may have a children data Vector), this argument is ignored and a `PVL_Exception.ILLEGAL_SYNTAX` warning status is set.
See Also:
  `DefaultMutableTreeNode.setAllowsChildren(boolean)`

#### add

    public void add(MutableTreeNode value)
             throws IllegalArgumentException

Invokes the Value's `Add` method.

Overrides:
  `add` in class `DefaultMutableTreeNode`
Parameters:
  `value` - A MutableTreeNode that must be a Value object.
Throws:
  `IllegalArgumentException` - If the value argument is not a Value object, or the `Add` method threw a PVL_Exception (in which case it's message is used for the exception message).
See Also:
  `Add(Value)`, `DefaultMutableTreeNode.add(MutableTreeNode)`

#### insert

    public void insert(MutableTreeNode value,
              int index)
                throws IllegalArgumentException

Invokes the Value's `Insert` method.

Specified by:
  `insert` in interface `MutableTreeNode`
Overrides:
  `insert` in class `DefaultMutableTreeNode`
Parameters:
  `value` - A MutableTreeNode that must be a Value object.
  `index` - The index in the Array where the Value is to be inserted.
Throws:
  `IllegalArgumentException` - If the value argument is not a Value object, or the `Insert` method threw a PVL_Exception (in which case it's message is used for the exception message).
See Also:
  `Insert(Value, int)`, `DefaultMutableTreeNode.insert(MutableTreeNode, int)`

#### remove

    public void remove(int index)

Invokes the Value's `Remove` method.

Specified by:
  `remove` in interface `MutableTreeNode`
Overrides:
  `remove` in class `DefaultMutableTreeNode`
Parameters:
  `index` - The index of the element in the Array to remove.
See Also:
  `Remove(int)`, `DefaultMutableTreeNode.remove(int)`

#### remove

    public void remove(MutableTreeNode value)
                throws IllegalArgumentException

Invokes the Value's `Remove` method.

Specified by:
  `remove` in interface `MutableTreeNode`
Overrides:
  `remove` in class `DefaultMutableTreeNode`
Parameters:
  `value` - A MutableTreeNode that must be a Value object.
Throws:
  `IllegalArgumentException` - If the value argument is not a Value object.
See Also:
  `Remove(Value)`, `DefaultMutableTreeNode.remove(MutableTreeNode)`