Package com.blackrook.rookscript

Class ScriptValue

java.lang.Object
com.blackrook.rookscript.ScriptValue
All Implemented Interfaces:
Comparable<ScriptValue>, Iterable<ScriptIteratorType.IteratorPair>
public class ScriptValue extends Object implements Comparable<ScriptValue>, Iterable<ScriptIteratorType.IteratorPair>
Script value encapsulation.
Author:
Matthew Tropiano

  • Method Details

    • create

      public static ScriptValue create(Object value)
      Creates a script value.
      Parameters:
      value - the source value.
      Returns:
      a new script value.

    • create

      public static ScriptValue create(ScriptValue.Type type, Object value)
      Creates a script value.
      Parameters:
      type - the target script value type.
      value - the source value.
      Returns:
      a new script value.

    • createEmptyBuffer

      public static ScriptValue createEmptyBuffer(int size)
      Creates a script value that is an empty buffer.
      Parameters:
      size - the size of the buffer in bytes.
      Returns:
      a new script value.

    • createEmptyList

      public static ScriptValue createEmptyList()
      Creates a script value that is an empty list.
      Returns:
      a new script value.

    • createEmptyMap

      public static ScriptValue createEmptyMap()
      Creates a script value that is an empty map.
      Returns:
      a new script value.

    • createError

      public static ScriptValue createError(Throwable t)
      Creates an error value from a Throwable. Copies the simple class name, the message, and the localized message.
      Parameters:
      t - the Throwable to use.
      Returns:
      a new script value.
      See Also:

    • createError

      public static ScriptValue createError(String type, String message)
      Creates an error value.
      Parameters:
      type - the error type.
      message - the error message (will be same as localized).
      Returns:
      a new script value.

    • createError

      public static ScriptValue createError(String type, String message, String localizedMessage)
      Creates an error value.
      Parameters:
      type - the error type.
      message - the error message.
      localizedMessage - a localized version of the error message.
      Returns:
      a new script value.

    • setNull

      public void setNull()
      Sets this value to the null value.

    • setEmptyBuffer

      public void setEmptyBuffer(int size)
      Sets this value to a new buffer (new reference), native byte order.
      Parameters:
      size - the size of the new buffer in bytes.

    • setEmptyBuffer

      public void setEmptyBuffer(int size, ByteOrder order)
      Sets this value to a new buffer (new reference).
      Parameters:
      size - the size of the new buffer in bytes.
      order - the byte ordering.

    • setEmptyList

      public void setEmptyList(int size, int capacity)
      Sets this value to a new empty list (new reference) initialized by nulls.
      Parameters:
      size - the initial of the new empty list.
      capacity - the inner capacity of the new empty list.

    • setEmptyList

      public void setEmptyList(int capacity)
      Sets this value to a new empty list (new reference).
      Parameters:
      capacity - the inner capacity of the new empty list.

    • setEmptyList

      public void setEmptyList()
      Sets this value to a new empty list (new reference).

    • setEmptyMap

      public void setEmptyMap(int capacity)
      Sets this value to a new empty map (new reference).
      Parameters:
      capacity - the inner capacity of the new empty map.

    • setEmptyMap

      public void setEmptyMap()
      Sets this value to a new empty map (new reference).

    • setError

      public void setError(String type, String message)
      Sets this value as an error.
      Parameters:
      type - the error type.
      message - the error message.

    • setError

      public void setError(String type, String message, String localizedMessage)
      Sets this value as an error.
      Parameters:
      type - the error type.
      message - the error message.
      localizedMessage - a localized version of the error message.

    • setError

      public void setError(Throwable value)
      Sets this value as an error. If null, this is set to the null value.
      Parameters:
      value - the source error to use.

    • set

      public void set(ScriptValue.Type type, Object value)
      Sets this value using another object, and converts it if possible to the target underlying type.
      Parameters:
      type - the target script value type.
      value - the source value to use.

    • set

      public void set(Object value)
      Sets this value using another value. If null, this is set to the null value.
      Parameters:
      value - the source value to use.

    • set

      public void set(ScriptValue value)
      Sets this value using another value. If null, this is set to the null value.
      Parameters:
      value - the source value to use.

    • set

      public void set(boolean value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(byte value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(short value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(char value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(int value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(long value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(float value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(double value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • set

      public void set(CharSequence value)
      Sets this value using another value.
      Parameters:
      value - the source value to use.

    • length

      public int length()
      Gets the length of this value, if this is a map, list, or the underlying object is an array or Collection type.
      Returns:
      the length in values, or 1 if not a collection of some kind.

    • empty

      public boolean empty()
      Gets if this value is considered "empty".

      Null is empty.
      If boolean, false is empty.
      If integer, 0 is empty.
      If float, 0.0 or NaN.
      If string, trimmed and zero length.
      If list or map, 0 keys or 0 items is empty.

      Returns:
      true if so, false if not.

    • listExtract

      public boolean listExtract(Collection<?> list)
      Sets the contents of this list to the provided collection.
      Parameters:
      list - the list to set.
      Returns:
      true if set, false if not.

    • listExtract

      public <T> boolean listExtract(T[] list)
      Sets the contents of this list to the provided collection.
      Type Parameters:
      T - the array type.
      Parameters:
      list - the list to set.
      Returns:
      true if set, false if not.

    • listSetByIndex

      public boolean listSetByIndex(int index, Object value)
      Sets a value in this list. If the index is outside of the range of the list's indices, it is not added.
      Parameters:
      index - the list index to set.
      value - the value to add (converted to internal value).
      Returns:
      true if set, false if not.
      See Also:

    • listAdd

      public boolean listAdd(Object value)
      Adds a value to this value, if it is a list.
      Parameters:
      value - the value to add (converted to internal value).
      Returns:
      true if added, false if not.
      See Also:

    • listAddAt

      public boolean listAddAt(int index, Object value)
      Adds a value to this value, only if it is a list.
      Parameters:
      index - the index to add the value to.
      value - the value to add (converted to internal value).
      Returns:
      true if added, false if not.
      See Also:

    • listRemove

      public boolean listRemove(Object value)
      Removes a value from this value, if it is a list.
      Parameters:
      value - the value to remove (converted to internal value).
      Returns:
      true if removed, false if not.
      See Also:

    • listRemoveAt

      public boolean listRemoveAt(int index, ScriptValue out)
      Removes a value from this value at an index, if it is a list.
      Parameters:
      index - the index to remove.
      out - the output value - the value that was removed, or set to null if not a list nor a valid index.
      Returns:
      true if this is a list and the index is valid and a value was removed, false otherwise.
      See Also:

    • listGetByIndex

      public boolean listGetByIndex(int index, ScriptValue out)
      Gets a value at an index, if it is a list. NOTE: This returns a reference, not a new instance!
      Parameters:
      index - the list index to return.
      out - the output value - the value at the index, or set to null if not a list nor a valid index.
      Returns:
      the value at the index, or null if not a list nor a valid index.
      See Also:

    • listGetIndexOf

      public int listGetIndexOf(Object value)
      Gets the index that a value is found at, if it is a list.
      Parameters:
      value - the value to look for.
      Returns:
      the index found, or -1 if not found or not a list.
      See Also:

    • listGetLastIndexOf

      public int listGetLastIndexOf(Object value)
      Gets the last index that a value is found at, if it is a list.
      Parameters:
      value - the value to look for.
      Returns:
      the index found, or -1 if not found or not a list.
      See Also:

    • listContains

      public boolean listContains(Object value)
      Gets if this list contains an object, if it is a list.
      Parameters:
      value - the value to look for.
      Returns:
      true if found, false if not or not a list.
      See Also:

    • listApply

      public <T> boolean listApply(T target)
      Applies this list to an array.
      Type Parameters:
      T - the array type.
      Parameters:
      target - the target array.
      Returns:
      true if this is a list and it has been applied, false if not.
      Since:
      1.10.0

    • listApply

      public <T> boolean listApply(Class<T> targetType, List<T> target)
      Applies this list to another list by setting the contents on a (expected new, empty) target list. Best of used on a list of contiguous elements.
      Type Parameters:
      T - the array type.
      Parameters:
      targetType - the underlying generic target type.
      target - the target array.
      Returns:
      true if this is a list and it has been applied, false if not.
      Since:
      1.10.0
      See Also:

    • sort

      public void sort()
      Sorts the contents of this list. Does nothing if this is not a list.

    • setAdd

      public boolean setAdd(Object value)
      Adds a value to this value, if it is a list, treating the structure like a set of discrete items. This assumes that the list is sorted - if not, this will have undefined behavior.
      Parameters:
      value - the value to add (converted to internal value).
      Returns:
      true if added, false if not.
      See Also:

    • setRemove

      public boolean setRemove(Object value)
      Removes a value from this value, if it is a list, treating the structure like a set of discrete items. This assumes that the list is sorted - if not, this will have undefined behavior.
      Parameters:
      value - the value to remove (converted to internal value).
      Returns:
      true if removed, false if not.
      See Also:

    • setContains

      public boolean setContains(Object value)
      Gets if this list contains an object, if it is a list, treating the structure like a set of discrete items. This assumes that the list is sorted - if not, this will have undefined behavior. This has better performance than listContains(Object), but only if this is a sorted set.
      Parameters:
      value - the value to look for.
      Returns:
      true if found, false if not or not a list.
      See Also:

    • setSearch

      public int setSearch(Object value)
      Gets a value's index, if it is a list, treating the structure like a set of discrete items. This assumes that the list is sorted - if not, this will have undefined behavior. This has better performance than listGetIndexOf(Object), but only if this is a sorted set.
      Parameters:
      value - the value to look for.
      Returns:
      true if found, false if not or not a list.
      See Also:

    • mapSet

      public boolean mapSet(String key, Object value)
      If this is a map, sets a key on it to a value. Keys are case-insensitive.
      Parameters:
      key - the key.
      value - the associated value.
      Returns:
      true if this is a map and the value was assigned, false otherwise.
      See Also:

    • mapGet

      public boolean mapGet(String key, ScriptValue out)
      If this is a map, gets the value that corresponds to a provided key. Changing the returned value does not change the value, unless it is a reference type like a map or list. Keys are case-insensitive.
      Parameters:
      key - the key.
      out - the destination variable for the value.
      Returns:
      true if a corresponding value was replaced, false if not or this is not a map. If false, out is set to the null value.
      See Also:

    • mapContains

      public boolean mapContains(String key)
      If this is a map, checks if it contains the provided key. Keys are case-insensitive.
      Parameters:
      key - the key.
      Returns:
      true if the key is present, false if not.
      Since:
      1.4.0
      See Also:

    • mapRemove

      public boolean mapRemove(String key)
      If this is a map, removes the value that corresponds to a provided key. Keys are case-insensitive.
      Parameters:
      key - the key.
      Returns:
      true if the value existed and was removed, false otherwise.
      See Also:

    • mapExtract

      public boolean mapExtract(Map<?,?> map)
      Extracts a map's key-value pairs and sets those values to this map. This can be expensive, depending on what needs converting.

      If you are passing an object to a script repeatedly, it may be better to just pass it as an object reference, if there are associated host functions that manipulate it.

      Parameters:
      map - the source map.
      Returns:
      true if this is a map and extraction was successful.

    • mapExtract

      public <T> boolean mapExtract(T object)
      Extracts an object's fields/getters and sets those values to this map. This can be expensive, depending on what needs converting.

      If you are passing an object to a script repeatedly, it may be better to just pass it as an object reference, if there are associated host functions that manipulate it.

      Type Parameters:
      T - the object type.
      Parameters:
      object - the source object.
      Returns:
      true if this is a map and extraction was successful.

    • mapApply

      public <T> boolean mapApply(T object)
      Applies this map to an object's fields/setters. This can be expensive, depending on what needs converting.
      Type Parameters:
      T - the object type.
      Parameters:
      object - the source object.
      Returns:
      true if this is a map and application was successful.
      Throws:
      ClassCastException - if any incoming type cannot be converted.

    • isNull

      public boolean isNull()
      Returns:
      true if this value is null.

    • isNaN

      public boolean isNaN()
      Returns:
      true if this value is strictly NaN.

    • isInfinite

      public boolean isInfinite()
      Returns:
      true if this value is positive or negative infinity.

    • isBoolean

      public boolean isBoolean()
      Returns:
      true if this value is a boolean type.

    • isInteger

      public boolean isInteger()
      Returns:
      true if this value is an integer type.
      Since:
      1.3.1

    • isFloat

      public boolean isFloat()
      Returns:
      true if this value is a floating-point type.
      Since:
      1.3.1

    • isNumeric

      public boolean isNumeric()
      Returns:
      true if this value is a numeric type (float or integer).

    • isString

      public boolean isString()
      Returns:
      true if this value is a string type.

    • isBuffer

      public boolean isBuffer()
      Returns:
      true if this value is a buffer type.

    • isList

      public boolean isList()
      Returns:
      true if this value is a list type.

    • isMap

      public boolean isMap()
      Returns:
      true if this value is a map type.

    • isError

      public boolean isError()
      Returns:
      true if this value is an error type.

    • isObjectRef

      public boolean isObjectRef()
      Returns:
      true if this value is an object reference type.

    • isObjectRef

      public boolean isObjectRef(Class<?> targetType)
      Parameters:
      targetType - the target type.
      Returns:
      true if this value is an object reference type and it can be cast to the provided type.

    • isObjectType

      public boolean isObjectType(Class<?> targetType)
      Checks if this script value can be cast to the target type. If this is null (see isNull()), this returns false.
      Parameters:
      targetType - the type to test.
      Returns:
      if the underlying object can be cast to the target type.

    • isObjectArrayType

      public boolean isObjectArrayType(Class<?> targetType)
      Checks if this script value is both an array and a particular type.
      Parameters:
      targetType - the type to test.
      Returns:
      if the underlying object can be cast to an array of the target type.

    • asBoolean

      public boolean asBoolean()
      Gets this value as a boolean.
      Returns:
      true if the value is nonzero and not NaN, false otherwise.

    • asByte

      public byte asByte()
      Gets this value as a byte. Depending on the internal value, this may end up truncating data. 
      (byte)asLong()
      Returns:
      the byte value of this value.

    • asShort

      public short asShort()
      Gets this value as a short. Depending on the internal value, this may end up truncating data. 
      (short)asLong()
      Returns:
      the byte value of this value.

    • asChar

      public char asChar()
      Gets this value as a char. Depending on the internal value, this may end up truncating data. 
      (short)asLong()
      Returns:
      the byte value of this value.

    • asInt

      public int asInt()
      Gets this value as an integer. Depending on the internal value, this may end up truncating data. 
      (int)asLong()
      Returns:
      the byte value of this value.

    • asFloat

      public float asFloat()
      Gets this value as a float. Depending on the internal value, this may end up truncating data. 
      isNaN() ? Float.NaN : (float)asDouble()
      Returns:
      the byte value of this value.

    • asLong

      public long asLong()
      Gets this value as a long integer. If this is a boolean type, this returns -1L. If this is a double type, this is cast to a long. If this is null (see isNull()), this returns 0.
      Returns:
      the long value of this value.

    • asDouble

      public double asDouble()
      Gets this value as a double-precision float. If this is a boolean type, this returns 1.0. If this is a long type, this is cast to a double. If this is null (see isNull()), this returns 0.0. If anything else, this returns Double.NaN.
      Returns:
      the double value of this value.

    • asString

      public String asString()
      Gets this value as a string. If this is null (see isNull()), this returns "null".
      Returns:
      the string value of this value.

    • asObject

      public Object asObject()
      Gets this value as an object.
      Returns:
      the object representation of this value.

    • asObjectType

      public <T> T asObjectType(Class<T> targetType)
      Gets this value cast as a different object type. Does no conversion nor coersion.
      Type Parameters:
      T - the returned type.
      Parameters:
      targetType - the class type to cast to.
      Returns:
      the object representation of this value.

    • getTypeName

      public String getTypeName()
      Gets the type name of this value.
      Returns:
      the type name.

    • createForType

      public <T> T createForType(Class<T> targetType)
      Gets this object coerced or converted to another class type. Not to be confused with asObjectType(Class), which just recasts. If this is a map, this applies its fields to the new object's setter methods and fields.
      Type Parameters:
      T - the returned type.
      Parameters:
      targetType - the target class type to convert to.
      Returns:
      a suitable object of type targetType, or null .
      Throws:
      ClassCastException - if the incoming type cannot be converted.

    • iterator

      public ScriptIteratorType iterator()
      Specified by:
      iterator in interface Iterable<ScriptIteratorType.IteratorPair>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • equals

      public boolean equals(ScriptValue value)
      Parameters:
      value - the other value.
      Returns:
      true if this value is STRICTLY EQUAL to another.

    • compareTo

      public int compareTo(ScriptValue o)
      Specified by:
      compareTo in interface Comparable<ScriptValue>

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toDebugString

      public String toDebugString()
      Returns:
      string representation of this value suitable for debugging.

    • not

      public static void not(ScriptValue operand, ScriptValue out)
      Bitwise not calculation.
      Parameters:
      operand - the input value.
      out - the output value.

    • negate

      public static void negate(ScriptValue operand, ScriptValue out)
      Negate calculation.
      Parameters:
      operand - the input value.
      out - the output value.

    • absolute

      public static void absolute(ScriptValue operand, ScriptValue out)
      Absolute calculation.
      Parameters:
      operand - the input value.
      out - the output value.

    • logicalNot

      public static void logicalNot(ScriptValue operand, ScriptValue out)
      Logical not calculation.
      Parameters:
      operand - the input value.
      out - the output value.

    • add

      public static void add(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Add calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • subtract

      public static void subtract(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Subtract calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • multiply

      public static void multiply(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Multiply calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • divide

      public static void divide(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Divide calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • modulo

      public static void modulo(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Modulo calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • and

      public static void and(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Bitwise And calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • or

      public static void or(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Bitwise Or calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • xor

      public static void xor(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Bitwise XOr calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • logicalAnd

      public static void logicalAnd(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Logical And calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • logicalOr

      public static void logicalOr(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Logical Or calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • leftShift

      public static void leftShift(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Left shift calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • rightShift

      public static void rightShift(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Right shift calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • rightShiftPadded

      public static void rightShiftPadded(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Right shift padded calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • less

      public static void less(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Less-than calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • lessOrEqual

      public static void lessOrEqual(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Less-than-or-equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • greater

      public static void greater(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Greater-than calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • greaterOrEqual

      public static void greaterOrEqual(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Greater-than-or-equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • equal

      public static void equal(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Logical Equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • notEqual

      public static void notEqual(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Logical Not Equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • strictEqual

      public static void strictEqual(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Strict Equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.

    • strictNotEqual

      public static void strictNotEqual(ScriptValue operand, ScriptValue operand2, ScriptValue out)
      Strict Not Equal calculation.
      Parameters:
      operand - the source operand.
      operand2 - the second operand.
      out - the output value.