ArgumentIterator (luna-all-shaded 0.2 API)

java.lang.Object
- org.classdump.luna.lib.ArgumentIterator

All Implemented Interfaces:

Iterator<Object>
```
public class ArgumentIterator
extends Object
implements Iterator<Object>
```
An iterator over arguments passed to a function.
The class implements the Iterator interface, but additionally provides facilities for rewinding the iterator and specialised methods for retrieving and verifying argument types and/or values, named nextX(...), where X the expected next argument. The argument list is immutable: invoking remove() throws an UnsupportedOperationException.

Note: references to instances of this class should not be retained by invoked functions beyond the scope of an invoke or resume, since this class may hold a reference to an ExecutionContext.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Object[]`	`copyAll()` Returns all arguments in the argument list in a freshly-allocated array.
`Object[]`	`copyRemaining()` Returns the arguments from the current position to the end of the argument list in a freshly-allocated array.
`void`	`goTo(int index)` Sets the current position to `index`.
`boolean`	`hasNext()`
`Object`	`next()`
`Object`	`nextAny()` Retrieves the argument `o` at the current position, advances the current position and returns `o`.
`boolean`	`nextBoolean()` Retrieves the boolean value `b` of the argument `o` at the current position, advances the current position and returns `b`.
`org.classdump.luna.runtime.Coroutine`	`nextCoroutine()` Returns the argument `o` at the current position if `o` is a coroutine, in which case it also advances the current position.
`double`	`nextFloat()` Retrieves the float value `f` of the argument `o` at the current position, advances the current position and returns `f`.
`org.classdump.luna.runtime.LuaFunction`	`nextFunction()` Returns the argument `o` at the current position if `o` is a function, in which case it also advances the current position.
`int`	`nextInt()` Retrieves the integer value `i` of the argument `o` at the current position, advances the current position and returns `i` truncated to 32 bits (i.e., the primitive `int` type).
`long`	`nextInteger()` Retrieves the integer value `i` of the argument `o` at the current position, advances the current position and returns `i`.
`int`	`nextIntRange(int min, int max)` Retrieves the integer value `i` of the argument `o` at the current position, advances the current position and returns `i` if `i >= min` and `i <= max`.
`int`	`nextIntRange(int min, int max, String rangeName)` Retrieves the integer value `i` of the argument `o` at the current position, advances the current position and returns `i` if `i >= min` and `i <= max`.
`Number`	`nextNumber()` Retrieves the numerical value `n` of the argument `o` at the current position, advances the current position and returns `n`.
`Object`	`nextOptionalAny(Object defaultValue)` If there is an argument `o` at the current position, returns `o` and advances the current position.
`boolean`	`nextOptionalBoolean(boolean defaultValue)` If there is an argument `o` at the current position, returns the boolean value of `o` and advances the current position.
`org.classdump.luna.runtime.Coroutine`	`nextOptionalCoroutine(org.classdump.luna.runtime.Coroutine defaultValue)` If there is a non-`null` argument `o` and `o` is a coroutine, returns the coroutine and advances the current position.
`double`	`nextOptionalFloat(double defaultValue)` If there is a non-`null` argument `o` at the current position, attempts to determine the `float value` of `o`.
`org.classdump.luna.runtime.LuaFunction`	`nextOptionalFunction(org.classdump.luna.runtime.LuaFunction defaultValue)` If there is a non-`null` argument `o` and `o` is a function, returns the function and advances the current position.
`int`	`nextOptionalInt(int defaultValue)` If there is a non-`null` argument `o` at the current position, attempts to determine the `integer value` of `o`.
`long`	`nextOptionalInteger(long defaultValue)` If there is a non-`null` argument `o` at the current position, attempts to determine the `integer value` of `o`.
`org.classdump.luna.ByteString`	`nextOptionalString(org.classdump.luna.ByteString defaultValue)` If there is a non-`null` argument `o` at the current position, attempts to determine the `string value` of `o`.
`org.classdump.luna.Table`	`nextOptionalTable(org.classdump.luna.Table defaultValue)` If there is a non-`null` argument `o` and `o` is a table, returns the table and advances the current position.
`org.classdump.luna.ByteString`	`nextStrictString()` Returns the argument `o` at the current position if `o` is a string, in which case it also advances the current position.
`org.classdump.luna.ByteString`	`nextString()` Retrieves the string value `s` of the argument `o` at the current position, advances the current position and returns `s`.
`org.classdump.luna.Table`	`nextTable()` Returns the argument `o` at the current position if `o` is a table, in which case it also advances the current position.
`org.classdump.luna.Userdata`	`nextUserdata()` Returns the argument `o` at the current position if `o` is a (full) userdata, in which case it also advances the current position.
`<T extends org.classdump.luna.Userdata> T`	`nextUserdata(String typeName, Class<T> clazz)` Returns the argument `o` at the current position if `o` is a (full) userdata of type `T`, in which case it also advances the current position.
`static ArgumentIterator`	`of(org.classdump.luna.MetatableProvider metatableProvider, String name, Object[] args)` Returns a new argument iterator over the argument array `args` that uses `metatableProvider` to access value names (by looking up their `"__name"` metatable field), and uses `name` as the name of the function for error reporting.
`Object`	`peek()` Returns the argument at current position, without incrementing the current position afterwards.
`int`	`position()` Returns the current position in the argument list.
`int`	`remaining()` Returns the number of times the method `next()` can be called without throwing an exception.
`void`	`remove()` Throws an `UnsupportedOperationException`, since the argument list is immutable.
`void`	`rewind()` Rewinds the iterator, moving the next pointer to the beginning of the argument list.
`int`	`size()` Returns the number of arguments in the argument list.
`void`	`skip()` Skips the next argument.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Iterator
forEachRemaining

- Method Detail
  - of
```
public static ArgumentIterator of(org.classdump.luna.MetatableProvider metatableProvider,
                                  String name,
                                  Object[] args)
```
    Returns a new argument iterator over the argument array args that uses metatableProvider to access value names (by looking up their "__name" metatable field), and uses name as the name of the function for error reporting.
    This method makes a copy of the argument array args.
    
    Parameters:
    
    metatableProvider - the metatable provider, must not be null
    
    name - the function name, must not be null
    
    args - the argument list, must not be null
    
    Returns:
    
    an argument iterator over args
    
    Throws:
    
    NullPointerException - if metatableProvider, name or args is null
  - hasNext
```
public boolean hasNext()
```
    Specified by:
    
    hasNext in interface Iterator<Object>
  - next
```
public Object next()
```
    Specified by:
    
    next in interface Iterator<Object>
  - remove
```
public void remove()
```
    Throws an UnsupportedOperationException, since the argument list is immutable.
    
    Specified by:
    
    remove in interface Iterator<Object>
    
    Throws:
    
    UnsupportedOperationException - every time called
  - position
```
public int position()
```
    Returns the current position in the argument list.
    The current position is the index of the next argument as it would be returned by next() or any other nextX(...) method if successful (i.e., if the method does not throw an exception). The index is 0-based, i.e., the first argument in the list is at position 0.
    
    Returns:
    
    the current position in the argument list
  - size
```
public int size()
```
    Returns the number of arguments in the argument list.
    
    Returns:
    
    the number of arguments in the argument list
  - remaining
```
public int remaining()
```
    Returns the number of times the method next() can be called without throwing an exception.
    
    Returns:
    
    the (non-negative) number of arguments remaining in the list
  - skip
```
public void skip()
```
    Skips the next argument.
  - goTo
```
public void goTo(int index)
```
    Sets the current position to index.
    No range checking is performed: it is permissible for index to be a position outside of the argument list bounds.
    
    The index is 0-based, i.e., the first argument in the list is at position 0.
    
    Parameters:
    
    index - the new current position, must be non-negative
    
    Throws:
    
    IllegalArgumentException - if index is negative
  - rewind
```
public void rewind()
```
    Rewinds the iterator, moving the next pointer to the beginning of the argument list.
  - copyAll
```
public Object[] copyAll()
```
    Returns all arguments in the argument list in a freshly-allocated array.
    
    Returns:
    
    an array containing all arguments
  - copyRemaining
```
public Object[] copyRemaining()
```
    Returns the arguments from the current position to the end of the argument list in a freshly-allocated array.
    If the current position is outside of the argument list, returns an empty array.
    
    Returns:
    
    an array containing the remaining arguments
  - peek
```
public Object peek()
```
    Returns the argument at current position, without incrementing the current position afterwards.
    Note that the value returned by this method may be null; if there is no argument at current position, a NoSuchElementException is thrown.
    
    Returns:
    
    the argument at current position, possibly null
    
    Throws:
    
    NoSuchElementException - if there is no argument at the current position
  - nextAny
```
public Object nextAny()
```
    Retrieves the argument o at the current position, advances the current position and returns o. If there is no argument at the current position, throws a BadArgumentException; in such case, the current position is not advanced.
    This method differs from next() in that it signals errors using BadArgumentException rather than NoSuchElementException.
    
    Returns:
    
    the argument the at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position
  - nextBoolean
```
public boolean nextBoolean()
```
    Retrieves the boolean value b of the argument o at the current position, advances the current position and returns b.
    If there is no argument at the current position, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the boolean value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position
  - nextNumber
```
public Number nextNumber()
```
    Retrieves the numerical value n of the argument o at the current position, advances the current position and returns n.
    If there is no argument at the current position or the argument o does not have a numerical value, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the numerical value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no numerical value
  - nextInteger
```
public long nextInteger()
```
    Retrieves the integer value i of the argument o at the current position, advances the current position and returns i.
    If there is no argument at the current position or the argument o does not have an integer value, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the integer value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no integer value
  - nextFloat
```
public double nextFloat()
```
    Retrieves the float value f of the argument o at the current position, advances the current position and returns f.
    If there is no argument at the current position or the argument o does not have a float value, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the float value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no float value
  - nextInt
```
public int nextInt()
```
    Retrieves the integer value i of the argument o at the current position, advances the current position and returns i truncated to 32 bits (i.e., the primitive int type).
    If there is no argument at the current position, or the argument o does not have an integer value, or the integer value does not fit in 32 bits, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the integer value of the argument at current position cast to int
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, the argument at current position has no integer value, or the integer does not fit in 32 bits
  - nextIntRange
```
public int nextIntRange(int min,
                        int max,
                        String rangeName)
```
    Retrieves the integer value i of the argument o at the current position, advances the current position and returns i if i >= min and i <= max.
    If there is no argument at the current position, or the argument o does not have an integer value, or the integer i is not within the specified range, throws a BadArgumentException. In that case, the current position is not advanced.
    
    The range is considered empty if min > max.
    
    Parameters:
    
    min - the minimum permitted value
    
    max - the maximum permitted value
    
    rangeName - the name of the range for error reporting, may be null
    
    Returns:
    
    the integer value of the argument at current position cast to int within the specified range
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no integer value, or the integer value is not within the specified range
  - nextIntRange
```
public int nextIntRange(int min,
                        int max)
```
    Retrieves the integer value i of the argument o at the current position, advances the current position and returns i if i >= min and i <= max.
    This method is equivalent to nextIntRange(min, max, null).
    
    Parameters:
    
    min - the minimum permitted value
    
    max - the maximum permitted value
    
    Returns:
    
    the integer value of the argument at current position cast to int within the specified range
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no integer value, or the integer value is not within the specified range
  - nextString
```
public org.classdump.luna.ByteString nextString()
```
    Retrieves the string value s of the argument o at the current position, advances the current position and returns s.
    If there is no argument at the current position or the argument s does not have a string value, throws a BadArgumentException. In that case, the current position is not advanced.
    
    Returns:
    
    the string value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position has no string value
  - nextStrictString
```
public org.classdump.luna.ByteString nextStrictString()
```
    Returns the argument o at the current position if o is a string, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not a string, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    This method differs from nextString() in that this method requires o to be a string, wherease nextString() requires o to have a string value.
    
    Returns:
    
    the string value of the argument at current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a string
  - nextFunction
```
public org.classdump.luna.runtime.LuaFunction nextFunction()
```
    Returns the argument o at the current position if o is a function, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not a function, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    Returns:
    
    the function at the current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a function
  - nextTable
```
public org.classdump.luna.Table nextTable()
```
    Returns the argument o at the current position if o is a table, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not a table, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    Returns:
    
    the table at the current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a table
  - nextCoroutine
```
public org.classdump.luna.runtime.Coroutine nextCoroutine()
```
    Returns the argument o at the current position if o is a coroutine, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not a coroutine, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    Returns:
    
    the coroutine at the current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a coroutine
  - nextUserdata
```
public <T extends org.classdump.luna.Userdata> T nextUserdata(String typeName,
                                                              Class<T> clazz)
```
    Returns the argument o at the current position if o is a (full) userdata of type T, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not of type T, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    Parameters:
    
    typeName - type name of the userdata for error reporting, must not be null
    
    clazz - the class of the userdata, must not be null
    
    Returns:
    
    the userdata of type T at the current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a full userdata of type T
    
    NullPointerException - if typeName or clazz is null
  - nextUserdata
```
public org.classdump.luna.Userdata nextUserdata()
```
    Returns the argument o at the current position if o is a (full) userdata, in which case it also advances the current position.
    If there is no argument at the current position or the argument s is not a userdata, throws a BadArgumentException. (In that case, the current position is not advanced.)
    
    Returns:
    
    the userdata at the current position
    
    Throws:
    
    BadArgumentException - if there is no argument at current position, or the argument at current position is not a userdata
  - nextOptionalAny
```
public Object nextOptionalAny(Object defaultValue)
```
    If there is an argument o at the current position, returns o and advances the current position. Otherwise, returns defaultValue (without advancing the current position).
    
    Parameters:
    
    defaultValue - the default value, may be null
    
    Returns:
    
    the argument at the current position, or defaultValue if there is no argument at the current position
  - nextOptionalBoolean
```
public boolean nextOptionalBoolean(boolean defaultValue)
```
    If there is an argument o at the current position, returns the boolean value of o and advances the current position. Otherwise, returns defaultValue (without advancing the current position).
    
    Parameters:
    
    defaultValue - the default value
    
    Returns:
    
    the boolean value of the argument at the current position, or defaultValue if there is no argument at the current position
  - nextOptionalInteger
```
public long nextOptionalInteger(long defaultValue)
```
    If there is a non-null argument o at the current position, attempts to determine the integer value of o. If o has an integer value, returns the integer value and advances the current position. If o has no integer value, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value
    
    Returns:
    
    the integer value of the argument at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it has no integer value
  - nextOptionalFloat
```
public double nextOptionalFloat(double defaultValue)
```
    If there is a non-null argument o at the current position, attempts to determine the float value of o. If o has a float value, returns the float value and advances the current position. If o has no float value, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value
    
    Returns:
    
    the float value of the argument at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it has no float value
  - nextOptionalInt
```
public int nextOptionalInt(int defaultValue)
```
    If there is a non-null argument o at the current position, attempts to determine the integer value of o. If o has an integer value that fits into a Java int type, returns this integer value as an int and advances the current position. If o has no integer value or the integer value does not fit in 32 bits, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value
    
    Returns:
    
    the integer value of the argument at the current position truncated to a Java int, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it has no integer value, or it has an integer value that does not fit into a Java int
  - nextOptionalString
```
public org.classdump.luna.ByteString nextOptionalString(org.classdump.luna.ByteString defaultValue)
```
    If there is a non-null argument o at the current position, attempts to determine the string value of o. If o has a string value, returns the string value and advances the current position. If o has no string value, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value, may be null
    
    Returns:
    
    the string value of the argument at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it has no string value
  - nextOptionalFunction
```
public org.classdump.luna.runtime.LuaFunction nextOptionalFunction(org.classdump.luna.runtime.LuaFunction defaultValue)
```
    If there is a non-null argument o and o is a function, returns the function and advances the current position. If o is not a function, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value, may be null
    
    Returns:
    
    the function at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it is not a function
  - nextOptionalTable
```
public org.classdump.luna.Table nextOptionalTable(org.classdump.luna.Table defaultValue)
```
    If there is a non-null argument o and o is a table, returns the table and advances the current position. If o is not a table, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value, may be null
    
    Returns:
    
    the table at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it is not a table
  - nextOptionalCoroutine
```
public org.classdump.luna.runtime.Coroutine nextOptionalCoroutine(org.classdump.luna.runtime.Coroutine defaultValue)
```
    If there is a non-null argument o and o is a coroutine, returns the coroutine and advances the current position. If o is not a coroutine, throws a BadArgumentException. Otherwise (i.e., if there is no argument at the current position or if o is null), returns defaultValue without advancing the current position.
    
    Parameters:
    
    defaultValue - the default value, may be null
    
    Returns:
    
    the coroutine at the current position, or defaultValue if there is no argument at the current position or the argument at the current position is null
    
    Throws:
    
    BadArgumentException - if there is a non-null argument at the current position and it is not a coroutine

Class ArgumentIterator

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Method Detail

of

hasNext

next

remove

position

size

remaining

skip

goTo

rewind

copyAll

copyRemaining

peek

nextAny

nextBoolean

nextNumber

nextInteger

nextFloat

nextInt

nextIntRange

nextIntRange

nextString

nextStrictString

nextFunction

nextTable

nextCoroutine

nextUserdata

nextUserdata

nextOptionalAny

nextOptionalBoolean

nextOptionalInteger

nextOptionalFloat

nextOptionalInt

nextOptionalString

nextOptionalFunction

nextOptionalTable

nextOptionalCoroutine