DataValue

Method Summary
`DataValue`	`abs()` Returns absolute data value of current value.
`DataValue`	`add(DataValue value)` Adds this and given data values.
`DataValue`	`ceil(DataValue precision)` Quantizes the current value up to an even value within given precision.
`double`	`deinterpolate(DataValue min, DataValue max)` De-interpolates the current data value to a scalar value in respect with the given data value range.
`DataValue`	`div(DataValue value)` Divides the current value with given value.
`DataValue`	`floor(DataValue precision)` Quantizes the current value down to an even value within given precision.
`java.lang.String`	`getFormat()` Gets the type specification optimal for this particular value.
`DataValue`	`interpolate(double value, DataValue max)` Interpolates the given scalar value to data value in respect with the range defined by this value and the given maximum value.
`DataValue`	`max(DataValue value)` Finds the larger of this and the given data value.
`DataValue`	`min(DataValue value)` Finds the smaller of this and the given data value.
`DataValue`	`mul(DataValue value)` Multiplies the current value with given value.
`DataValue`	`negate()` Returns the negation of current value.
`void`	`setValue(java.lang.String stringValue, java.text.ParsePosition status)` Sets the data value from a string value.
`DataValue`	`sub(DataValue value)` Substracts given data value from this data value.
`void`	`toStatement(java.sql.PreparedStatement statement, int parameter)` Converts the data to a prepared statement input parameter.
`java.lang.String`	`toString()` Gets the string representation of this data value.
`java.lang.String`	`toXML()` Gets the XML string representation of this data value.
`DataValue`	`unit(DataValue targetValue, double maxSteps)` Gets the largest suitable unit step to represent a value change between this value and the given target value.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.davisor.data.SerializableData

isNull

Methods inherited from interface com.davisor.data.Data

getType

Methods inherited from interface com.davisor.core.Dupable

dup

Method Detail

abs

public DataValue abs()
              throws InvalidDataException

Returns absolute data value of current value.

Absolute values must satisfy a requirement that when added to any other value, the result must be greater than or equal to the original value.

Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if absolute value can not be computed

add

public DataValue add(DataValue value)
              throws InvalidDataException

Adds this and given data values.

Parameters:: value - a data value to be added to this data value
Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if data values cannot be added

ceil

public DataValue ceil(DataValue precision)
               throws InvalidDataException

Quantizes the current value up to an even value within given precision. The returned value is more than or equal with the current value, but not more than the current value added by given precision.

Parameters:: precision - the precision within quantization occurs
Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if precision was of unacceptable type
See Also:: floor(DataValue), Type.ceil(com.davisor.data.DataValue, com.davisor.data.DataValue, com.davisor.data.DataValue)

deinterpolate

public double deinterpolate(DataValue min,
                            DataValue max)
                     throws InvalidDataException

De-interpolates the current data value to a scalar value in respect with the given data value range. This gives scalar values between [0,1], when the current data value in within the range, negative scalar values when the data value falls below the range and scalar values greater than 1.0 otherwise.

It has been a definite design decision to restrict de-interpolation values to single double values instead of more elaborate data structures that would allow the representation of multi-dimensional de-interpolation results. For a multidimensional object, linear interpolation rarely makes any sense, and if it does, multi-dimensional objects must define their own interpolation schemes anyway. The only multi-dimensional data that would have benefited from multi-dimensional de-interpolation results would have been data structures that carry several unrelated data values. The benefits gained from their convenient one-operation de-interpolation would not, however, be enough to justify the inconvenience caused by the increased de-interpolation value access complexity. Instead, multi-dimensional data structures with unrelated elements should be de-interpolated element by element under explicit guidance.

It is also recommended that generic multi-dimensional de-interpolation operations de-interpolate their members separately, and return a result only if member de-interpolation results are mutually equal. In any other case, the de-interpolation should fail. Such implementations are, however, urged to make a difference between ordinary de-interpolation failures and failures due to member de-interpolation value conflicts.

Deinterpolation failures may be reported through appropriate exceptions, or by returning Double.NaN. Double.NaN indicates a mathematically invalid result like division by zero when values of compatible types are applied to each other. Exceptions report incompatible values and types, like when trying for example to deinterpolate text against dates.

Parameters:: min - a data value representing a range's lower limit; max - a data value representing a range's higher limit
Returns:: the de-interpolated scalar value (may be NaN)
Throws:: DeinterpolationException - if the de-interpolation fails due to a de-interpolation value conflict; InvalidDataException - if the de-interpolation fails for some other reason
See Also:: interpolate(double, com.davisor.data.DataValue), DeinterpolationException, TupleData.deinterpolate(com.davisor.data.DataValue, com.davisor.data.DataValue)

div

public DataValue div(DataValue value)
              throws InvalidDataException

Divides the current value with given value.

Parameters:: value - the divider
Returns:: a new data object, sharing the current type of this object.
Throws:: InvalidDataException - if current value cannot be divided with given divider.

floor

public DataValue floor(DataValue precision)
                throws InvalidDataException

Quantizes the current value down to an even value within given precision. The returned value is less than or equal with the current value, but not less than the current value substracted by given precision.

Parameters:: precision - the precision within the quantization occurs
Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if precision was of unacceptable type
See Also:: ceil(DataValue), Type.floor(com.davisor.data.DataValue, com.davisor.data.DataValue, com.davisor.data.DataValue)

getFormat

public java.lang.String getFormat()

Gets the type specification optimal for this particular value. The specification returned may differ from the current type specification. If so, setting the current type specification equal with the value returned by this method will ensure optimal value formatting and parsing for values of the same magnitude as this value.

See Also:: Data.getType(), Type.getFormat(), Type.setFormat(java.lang.String)

interpolate

public DataValue interpolate(double value,
                             DataValue max)
                      throws InvalidDataException

Interpolates the given scalar value to data value in respect with the range defined by this value and the given maximum value. Scalar values between [0,1] result data values between the current value and the given maximum value. Negative scalar values result values smaller than this value and scalar values higher than 1.0 return data values above the given maximum.

Parameters:: value - the scalar value to be interpolated; max - a data value representing a range's higher limit
Returns:: a new data object containing the result
Throws:: InvalidDataException - if the interpolation fails
See Also:: deinterpolate(com.davisor.data.DataValue, com.davisor.data.DataValue)

max

public DataValue max(DataValue value)
              throws InvalidDataException

Finds the larger of this and the given data value.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Parameters:: value - a data value to be compared with this data value (may be null)
Returns:: the larger of the compared data values, or a new data value that is larger than or the same as the largest of the compared data values.
Throws:: InvalidDataException - if the values cannot be compared

min

public DataValue min(DataValue value)
              throws InvalidDataException

Finds the smaller of this and the given data value.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Parameters:: value - a data value to be compared with this data value (may be null)
Returns:: the smaller of the compared data values, or a new data value that is smaller than or the same as the smallest of the compared data values.
Throws:: InvalidDataException - if the values cannot be compared

mul

public DataValue mul(DataValue value)
              throws InvalidDataException

Multiplies the current value with given value.

Parameters:: value - the multiplier
Returns:: a new data object, sharing the current type of this object.
Throws:: InvalidDataException - if current value cannot be multiplied with given multiplier.

negate

public DataValue negate()
                 throws InvalidDataException

Returns the negation of current value.

Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if absolute value can not be computed

setValue

public void setValue(java.lang.String stringValue,
                     java.text.ParsePosition status)
              throws InvalidDataException

Sets the data value from a string value.

Parameters:: stringValue - string value to be parsed (may be null); status - parse status (may be null)
Throws:: InvalidDataException - if string value could not be parser
See Also:: CountType.countValue(String,ParsePosition)

sub

public DataValue sub(DataValue value)
              throws InvalidDataException

Substracts given data value from this data value.

Parameters:: value - a data value to be substracted from this data value
Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if value can not be substracted

toStatement

public void toStatement(java.sql.PreparedStatement statement,
                        int parameter)
                 throws java.sql.SQLException

Converts the data to a prepared statement input parameter.

Throws:: java.sql.SQLException - if a SQL error occurs

toString

public java.lang.String toString()

Gets the string representation of this data value. The string representation should be complete enough, so that new data objects equal with this one can be created from the string using a Type equal with the current Type.

Note that this method overlaps the standard Java Object class interface. The semantics for the string returned by this method are, however, more strict than those of the standard method.

Returns:: complete string representing the data.
See Also:: toXML(), Type.toData(String,ParsePosition)

toXML

public java.lang.String toXML()

Gets the XML string representation of this data value. The XML string representation should be complete enough, so that new data objects equal with this one can be created with appropriate XML parsing.

Note that this method resembles the toString() method, and indeed, many implementations are expected to use one of these methods to generate output for the other.

Returns:: complete string representing the data.
See Also:: toString(), Type.toData(String,ParsePosition)

unit

public DataValue unit(DataValue targetValue,
                      double maxSteps)
               throws InvalidDataException

Gets the largest suitable unit step to represent a value change between this value and the given target value. If the values are equal, then the type specific default unit step is returned. If the values are not equal, then the given target value must be reached from this value by adding the returned unit step to this value once or more.

Parameters:: targetValue - target value to be reached (may be null); maxSteps - maximum number of steps (zero leaves the choise open)
Returns:: a new data object, sharing the current type of this object
Throws:: InvalidDataException - if target value is unsuitable

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.davisor.data Interface DataValue

abs

add