oscript.data
Class OArray

java.lang.Object
  extended byoscript.data.Value
      extended byoscript.data.OObject
          extended byoscript.data.OArray
All Implemented Interfaces:
java.io.Externalizable, MemberTable, java.io.Serializable

public class OArray
extends OObject
implements java.io.Externalizable, MemberTable

An array instance.

Author:
Rob Clark (rob@ti.com)
See Also:
Serialized Form

Field Summary
 Value concat
          Join this array object with one or more additional arrays.
static java.lang.String[] MEMBER_NAMES
           
static java.lang.String PARENT_TYPE_NAME
           
 Value push
          Add one or more elements to the end of the array, returning the new length.
 Value splice
          Add and remove elements from an array
static Value TYPE
          The type object for an instance of Array.
static java.lang.String TYPE_NAME
           
 Value unshift
          Add one or more elements to the beginning of the array, returning the new length.
 
Fields inherited from class oscript.data.OObject
EMPTY_EXPR_LIST_EVALUATOR
 
Fields inherited from class oscript.data.Value
DEBUG, NULL, UNDEFINED
 
Constructor Summary
OArray()
          Class Constructor.
OArray(int initialLength)
          private constructor, used internally and by compiler...
OArray(MemberTable args)
          Class Constructor.
OArray(Reference[] arr, int size)
          Class Constructor.
OArray(Value[] args)
          Class Constructor.
 
Method Summary
 java.lang.Object castToJavaObject()
          Convert this object to a native java Object value.
 java.lang.String castToString()
          Convert this object to a native java String value.
 Value elementAt(int idx)
           
 Value elementAt(Value idx)
          Get the specified index of this object, if this object is an array.
 Value elementsAt(int idx1, int idx2)
           
 Value elementsAt(Value idx1, Value idx2)
          Get the specified range of this object, if this object is an array.
 void ensureCapacity(int sz)
          Ensure that the member-table has sufficient capacity to accomodate the index sz.
 Value every(Value fxn)
          Executes the provided function fxn once for each element present in the array until it finds one where callback returns false.
 Value filter(Value fxn)
          Create a new array with all elements that pass the test implemented by the provided function.
 void forEach(Value fxn)
          Executes a provided function once per array element.
 void free()
          Indication from creator of member-table that resources allocated from the stack are no longer needed and should be released.
protected  Value getTypeImpl()
          Get the type of this object.
 java.util.Iterator iterator()
          Get an iterator of all the elements of this array.
 Value join()
          Join all elements in the array into a single string, separated by commas
 Value join(Value separator)
          Join all elements in the array into a single string, separated by the specified separator.
 int length()
          For types that implement elementAt, this returns the number of elements.
static OArray makeArray(java.lang.Object arrObject)
           
 Value map(Value fxn)
          Creates a new array with the results of calling a provided function on every element in this array.
 Value pop()
          Remove and return the last element of the array.
 void push1(Value val)
          Push a single parameter into the table.
 void push2(Value val1, Value val2)
          Push two values into the table.
 void push3(Value val1, Value val2, Value val3)
          Push three values into the table.
 void push4(Value val1, Value val2, Value val3, Value val4)
          Push four values into the table.
 void readExternal(java.io.ObjectInput in)
          Derived class that implements Externalizable must call this if it overrides it.
 Reference referenceAt(int idx)
          Return the reference at the specified index.
 Reference referenceAt(int idx, int attr)
           
 void reset()
          An indication from the creator of the member-table that, while the table itself is still required, the references referred to by the table are no longer required and can be freed.
 Value reverse()
          Reverse the order of elements in this array, returning this array.
 MemberTable safeCopy()
          Indication to the member-table that a "safe" copy is required.
 Value shift()
          Remove and return the first element of the array.
 Value slice(Value begin)
          Slice out a section of the array.
 Value slice(Value begin, Value end)
          Slice out a section of the array.
 Value some(Value fxn)
          Tests whether some element in the array passes the test implemented by the provided function.
 Value sort()
          Sort the elements in the array, by converting each element to string, and sorting in ascending order.
 Value sort(Value fxn)
          Sort the elements in the array, by using the specified comparision function.
 void writeExternal(java.io.ObjectOutput out)
          Derived class that implements Externalizable must call this if it overrides it.
 
Methods inherited from class oscript.data.OObject
getMember, populateMemberSet
 
Methods inherited from class oscript.data.Value
_getTypeMember, _populateTypeMemberSet, bopBitwiseAnd, bopBitwiseAndR, bopBitwiseOr, bopBitwiseOrR, bopBitwiseXor, bopBitwiseXorR, bopCast, bopCastR, bopDivide, bopDivideR, bopEquals, bopEqualsR, bopGreaterThan, bopGreaterThanOrEquals, bopGreaterThanOrEqualsR, bopGreaterThanR, bopInstanceOf, bopInstanceOfR, bopLeftShift, bopLeftShiftR, bopLessThan, bopLessThanOrEquals, bopLessThanOrEqualsR, bopLessThanR, bopLogicalAnd, bopLogicalAndR, bopLogicalOr, bopLogicalOrR, bopMinus, bopMinusR, bopMultiply, bopMultiplyR, bopNotEquals, bopNotEqualsR, bopPlus, bopPlusR, bopRemainder, bopRemainderR, bopSignedRightShift, bopSignedRightShiftR, bopUnsignedRightShift, bopUnsignedRightShiftR, callAsConstructor, callAsConstructor, callAsConstructor, callAsExtends, callAsExtends, callAsExtends, callAsFunction, callAsFunction, callAsFunction, castToBoolean, castToExactNumber, castToInexactNumber, getMember, getMember, getMember, getMember, getMember, getMonitor, getType, getTypeMember, getTypeMember, isA, memberSet, noSuchMember, opAssign, populateTypeMemberSet, toString, unhand, uopBitwiseNot, uopDecrement, uopIncrement, uopLogicalNot, uopMinus, uopPlus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

TYPE

public static final Value TYPE
The type object for an instance of Array.


PARENT_TYPE_NAME

public static final java.lang.String PARENT_TYPE_NAME
See Also:
Constant Field Values

TYPE_NAME

public static final java.lang.String TYPE_NAME
See Also:
Constant Field Values

MEMBER_NAMES

public static final java.lang.String[] MEMBER_NAMES

concat

public final Value concat
Join this array object with one or more additional arrays. This performs a shallow copy, so the original arrays are unmodified, but for mutable objects there may be side effects.


splice

public final Value splice
Add and remove elements from an array


push

public final Value push
Add one or more elements to the end of the array, returning the new length.


unshift

public final Value unshift
Add one or more elements to the beginning of the array, returning the new length.

Constructor Detail

OArray

public OArray()
Class Constructor.


OArray

public OArray(int initialLength)
private constructor, used internally and by compiler... initialLength == -1 is used to create arrays that wrap native java arrays, rather than having to do a copy when an array is passed from java to script. For java arrays, arr should equal null, so methods that don't work for java arrays know to throw an exception... ugly, but it works


OArray

public OArray(Reference[] arr,
              int size)
Class Constructor. This constructor is not intended for public consumption... it is just used by StackFrame$StackFrameArray for quickly making a safe-copy when already copied out of the stack


OArray

public OArray(MemberTable args)
Class Constructor. This is the constructor that is called via a BuiltinType instance.

Parameters:
args - arguments to this constructor
Throws:
PackagedScriptObjectException(Exception) - if wrong number of args

OArray

public OArray(Value[] args)
Class Constructor. This is the constructor that is called via a BuiltinType instance.

Parameters:
args - arguments to this constructor
Throws:
PackagedScriptObjectException(Exception) - if wrong number of args
Method Detail

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Derived class that implements Externalizable must call this if it overrides it. It should override it to save/restore it's own state.

Specified by:
readExternal in interface java.io.Externalizable
Overrides:
readExternal in class Value
Throws:
java.io.IOException
java.lang.ClassNotFoundException

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.IOException
Derived class that implements Externalizable must call this if it overrides it. It should override it to save/restore it's own state.

Specified by:
writeExternal in interface java.io.Externalizable
Overrides:
writeExternal in class Value
Throws:
java.io.IOException

makeArray

public static final OArray makeArray(java.lang.Object arrObject)

getTypeImpl

protected Value getTypeImpl()
Get the type of this object. The returned type doesn't have to take into account the possibility of a script type extending a built-in type, since that is handled by Value.getType().

Overrides:
getTypeImpl in class OObject
Returns:
the object's type

castToString

public java.lang.String castToString()
                              throws PackagedScriptObjectException
Convert this object to a native java String value.

Overrides:
castToString in class OObject
Returns:
a String value
Throws:
PackagedScriptObjectException(NoSuchMethodException)
PackagedScriptObjectException

castToJavaObject

public java.lang.Object castToJavaObject()
                                  throws PackagedScriptObjectException
Convert this object to a native java Object value.

Overrides:
castToJavaObject in class Value
Returns:
a java object
Throws:
PackagedScriptObjectException(NoSuchMemberException)
PackagedScriptObjectException

length

public int length()
           throws PackagedScriptObjectException
For types that implement elementAt, this returns the number of elements. This is the same as the length property of an object.

Specified by:
length in interface MemberTable
Overrides:
length in class Value
Returns:
an integer length
Throws:
PackagedScriptObjectException(NoSuchMethodException)
PackagedScriptObjectException
See Also:
elementAt(oscript.data.Value)

elementAt

public Value elementAt(Value idx)
                throws PackagedScriptObjectException
Get the specified index of this object, if this object is an array. If needed, the array is grown to the appropriate size.

Overrides:
elementAt in class Value
Parameters:
idx - the index to get
Returns:
a reference to the member
Throws:
PackagedScriptObjectException(NoSuchMethodException)
PackagedScriptObjectException
See Also:
length()

elementAt

public Value elementAt(int idx)

referenceAt

public final Reference referenceAt(int idx)
Description copied from interface: MemberTable
Return the reference at the specified index. This does not necessarily grow the array, so the user should be sure to use MemberTable.ensureCapacity(int) to ensure the array has sufficient capacity before dereferencing an index into the table which is not known to exist.

Specified by:
referenceAt in interface MemberTable
Parameters:
idx - an index into the member-table
Returns:
a reference

referenceAt

public final Reference referenceAt(int idx,
                                   int attr)

ensureCapacity

public final void ensureCapacity(int sz)
Description copied from interface: MemberTable
Ensure that the member-table has sufficient capacity to accomodate the index sz. Grow the array, if necessary.

Specified by:
ensureCapacity in interface MemberTable
Parameters:
sz - the requested table size

elementsAt

public Value elementsAt(Value idx1,
                        Value idx2)
                 throws PackagedScriptObjectException
Get the specified range of this object, if this object is an array. This returns a copy of a range of the array.

Overrides:
elementsAt in class Value
Parameters:
idx1 - the index index of the beginning of the range, inclusive
idx2 - the index of the end of the range, inclusive
Returns:
a copy of the specified range of this array
Throws:
PackagedScriptObjectException(NoSuchMemberException)
PackagedScriptObjectException
See Also:
length(), elementAt(oscript.data.Value)

elementsAt

public Value elementsAt(int idx1,
                        int idx2)

iterator

public java.util.Iterator iterator()
Get an iterator of all the elements of this array. This makes arrays useful in the "for( var item : set )" syntx.

Returns:
an iterator of elements of the array

join

public Value join()
Join all elements in the array into a single string, separated by commas

Returns:
the resulting string

join

public Value join(Value separator)
Join all elements in the array into a single string, separated by the specified separator.

Parameters:
separator - the separator string
Returns:
the resulting string

slice

public Value slice(Value begin)
Slice out a section of the array. This works like arr[begin.. arr.length()-1]. The index can be negative, in which case it will count from the end of the array.

Parameters:
begin - the begin index, inclusive
Returns:
the resulting array

slice

public Value slice(Value begin,
                   Value end)
Slice out a section of the array. This works like arr[begin.. end-1]. Either index can be negative, in which case it will count from the end of the array.

Parameters:
begin - the begin index, inclusive
end - the end index, exclusive
Returns:
the resulting array

pop

public Value pop()
Remove and return the last element of the array.


shift

public Value shift()
Remove and return the first element of the array.


reverse

public Value reverse()
Reverse the order of elements in this array, returning this array. The array is reversed in order.

Returns:
this array object itself

every

public Value every(Value fxn)
Executes the provided function fxn once for each element present in the array until it finds one where callback returns false. If such an element is found, the test aborts and false is returned, otherwise (callback returned true for each of the elements) every will return true. This array is not mutated.

Parameters:
fxn - invoked with three arguments: the value of the element, the index of the element, and the array object containing the element; should return true or false
Returns:
true if every element passes the test, otherwise false

some

public Value some(Value fxn)
Tests whether some element in the array passes the test implemented by the provided function. Executes the provided function once for each element present in the array until it finds one where callback returns true. If such an element is found, the test aborts and true is returned, otherwise (callback returned false for each of the elements) return false.

Parameters:
fxn - invoked with three arguments: the value of the element, the index of the element, and the array object containing the element; should return true or false
Returns:
true if some element passes the test, otherwise false

filter

public Value filter(Value fxn)
Create a new array with all elements that pass the test implemented by the provided function. The provided callback is invoked for each element in the array, and a new array is constructed containing (in the same order) the elements for which the callback returned true. Elements for which the callback returns false are skipped. This array is not mutated.

Parameters:
fxn - invoked with three arguments: the value of the element, the index of the element, and the array object containing the element; should return true or false
Returns:
the filtered array.

map

public Value map(Value fxn)
Creates a new array with the results of calling a provided function on every element in this array. This array is not mutated.

Parameters:
fxn - invoked with three arguments: the value of the element, the index of the element, and the array object containing the element
Returns:
the new array

forEach

public void forEach(Value fxn)
Executes a provided function once per array element. This array is not mutated.

Parameters:
fxn - invoked with three arguments: the value of the element, the index of the element, and the array object containing the element

sort

public Value sort()
Sort the elements in the array, by converting each element to string, and sorting in ascending order. The array is sorted in place.

Returns:
this array object itself

sort

public Value sort(Value fxn)
Sort the elements in the array, by using the specified comparision function. The comparision function(a,b) should return less than zero if a is less than b, zero if they are equal, and greater than zero if a is greater than b. The array is sorted in place.

Parameters:
fxn - the comparasion function
Returns:
this array object itself

safeCopy

public MemberTable safeCopy()
Description copied from interface: MemberTable
Indication to the member-table that a "safe" copy is required. This means that the table may need to outlive the stack-frame that it was (possibly) allocated from. What it means to convert this table into a "safe" copy depends on the implementation of the table. A safe copy is still valid after MemberTable.free() is called.

Specified by:
safeCopy in interface MemberTable
Returns:
a safe copy of this table

push1

public void push1(Value val)
Description copied from interface: MemberTable
Push a single parameter into the table.

Specified by:
push1 in interface MemberTable
Parameters:
val - the value to push

push2

public void push2(Value val1,
                  Value val2)
Description copied from interface: MemberTable
Push two values into the table.

Specified by:
push2 in interface MemberTable
Parameters:
val1 - the value to push
val2 - the value to push

push3

public void push3(Value val1,
                  Value val2,
                  Value val3)
Description copied from interface: MemberTable
Push three values into the table.

Specified by:
push3 in interface MemberTable
Parameters:
val1 - the value to push
val2 - the value to push
val3 - the value to push

push4

public void push4(Value val1,
                  Value val2,
                  Value val3,
                  Value val4)
Description copied from interface: MemberTable
Push four values into the table.

Specified by:
push4 in interface MemberTable
Parameters:
val1 - the value to push
val2 - the value to push
val3 - the value to push
val4 - the value to push

reset

public void reset()
Description copied from interface: MemberTable
An indication from the creator of the member-table that, while the table itself is still required, the references referred to by the table are no longer required and can be freed.

Specified by:
reset in interface MemberTable

free

public void free()
Description copied from interface: MemberTable
Indication from creator of member-table that resources allocated from the stack are no longer needed and should be released. (If the member table is needed after this point, a safe copy should have already been obtained by calling MemberTable.safeCopy().)

Specified by:
free in interface MemberTable