ReturnBuffer (Rembulan Runtime 0.1-SNAPSHOT API)

```
public interface ReturnBuffer
```
A buffer used to store and retrieve the results of function calls and Lua operations initiated via the Dispatch methods.
In Lua, a function may return either a sequence of values, or a tail call of another Lua function. A return buffer represents both possibilities as an optional call target (for tail calls), and mandatory sequence of values (for tail calls, these are the call arguments; for plain returns, these are the actual values).

To query the length of the sequence, use size(). To access the values, use getAsArray() to get the entire sequence packed into an array, get(int) to get a single value in the sequence (or null when the index is not between 0 (inclusive) and size() (exclusive), or get0(), get1(), ... for possibly more optimised versions of get(int).

To determine whether the return buffer contains a tail call, the method isCall() may be used; when it returns true, then the call target (i.e. the object to be tail-called) is accessible using getCallTarget().

New return buffer instances may be created using the methods provided by the static factory class ReturnBuffers.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Object`	`get(int idx)` Returns the `idx`-th value stored in this buffer, or `null` if there is no value with the given index `idx`.
`Object`	`get0()` Returns the first value stored in this buffer.
`Object`	`get1()` Returns the second value stored in this buffer.
`Object`	`get2()` Returns the third value stored in this buffer.
`Object`	`get3()` Returns the fourth value stored in this buffer.
`Object`	`get4()` Returns the fifth value stored in this buffer.
`Object[]`	`getAsArray()` Returns the values stored in this buffer as an array.
`Object`	`getCallTarget()` If this buffer contains a tail call, returns the target of the call, i.e, the object `f` to be called with the arguments args as `f(`args`)`.
`boolean`	`isCall()` Returns `true` iff this buffer contains a tail call.
`void`	`setTo()` Sets the result value in this buffer to the empty sequence.
`void`	`setTo(Object a)` Sets the result value in this buffer to a single value.
`void`	`setTo(Object a, Object b)` Sets the result value in this buffer to two values.
`void`	`setTo(Object a, Object b, Object c)` Sets the result value in this buffer to three values.
`void`	`setTo(Object a, Object b, Object c, Object d)` Sets the result value in this buffer to four values.
`void`	`setTo(Object a, Object b, Object c, Object d, Object e)` Sets the result value in this buffer to five values.
`void`	`setToCall(Object target)` Sets the result in this buffer to a tail call of `target` without arguments.
`void`	`setToCall(Object target, Object arg1)` Sets the result in this buffer to a tail call of `target` with a single argument `arg1`.
`void`	`setToCall(Object target, Object arg1, Object arg2)` Sets the result in this buffer to a tail call of `target` with the arguments `arg1` and `arg2`.
`void`	`setToCall(Object target, Object arg1, Object arg2, Object arg3)` Sets the result in this buffer to a tail call of `target` with the arguments `arg1`, `arg2` and `arg3`.
`void`	`setToCall(Object target, Object arg1, Object arg2, Object arg3, Object arg4)` Sets the result in this buffer to a tail call of `target` with the arguments `arg1`, `arg2`, `arg3` and `arg4`.
`void`	`setToCall(Object target, Object arg1, Object arg2, Object arg3, Object arg4, Object arg5)` Sets the result in this buffer to a tail call of `target` with the arguments `arg1`, `arg2`, `arg3`, `arg4` and `arg5`.
`void`	`setToCallWithContentsOf(Object target, Collection<?> args)` Sets the result in this buffer to a tail call of `target` with the contents of the collection `args` used as call arguments.
`void`	`setToCallWithContentsOf(Object target, Object[] args)` Sets the result in this buffer to a tail call of `target` with the contents of the array `args` used as call arguments.
`void`	`setToContentsOf(Collection<?> collection)` Sets the result value in this buffer to the contents of `collection`, in the order given by `collection`'s `iterator()`.
`void`	`setToContentsOf(Object[] array)` Sets the result value in this buffer to the contents of `array`.
`int`	`size()` Returns the number of values stored in this buffer.

- Method Detail
  - size
```
int size()
```
    Returns the number of values stored in this buffer.
    When the buffer contains a tail call, this is the number of arguments to the call (i.e., the call target is not counted); otherwise, it is the number of return values.
    
    Returns:
    
    the number of values stored in this buffer
  - isCall
```
boolean isCall()
```
    Returns true iff this buffer contains a tail call.
    If this method returns true, the call target may be retrieved using getCallTarget().
    
    Returns:
    
    true iff this buffer contains a tail call
  - getCallTarget
```
Object getCallTarget()
```
    If this buffer contains a tail call, returns the target of the call, i.e, the object f to be called with the arguments args as f(args).
    If this buffer does not contain a tail call, an IllegalStateException is thrown; use isCall() to find out whether the buffer contains a tail call.
    
    In order to retrieve the call arguments, use any of the value getter methods (e.g., getAsArray()).
    
    Note that the target of the tail call may be any object, including null.
    
    Returns:
    
    the target of the tail call
    
    Throws:
    
    IllegalStateException - when this buffer does not contain a tail call
  - setTo
```
void setTo()
```
    Sets the result value in this buffer to the empty sequence.
    This equivalent to the assignment of return values by the Lua statement
```
     return
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
  - setTo
```
void setTo(Object a)
```
    Sets the result value in this buffer to a single value.
    This equivalent to the assignment of return values by the Lua statement
```
     return a
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {a})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
    
    Note: the argument a is taken as-is, even if a is an array or a collection. To set the result value of this buffer to the contents of a, use setToContentsOf(Object[]) or setToContentsOf(Collection).
    Parameters:
    
    a - the result value, may be null
  - setTo
```
void setTo(Object a,
           Object b)
```
    Sets the result value in this buffer to two values.
    This equivalent to the assignment of return values by the Lua statement
```
     return a, b
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {a, b})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
    Parameters:
    
    a - the first value, may be null
    
    b - the second value, may be null
  - setTo
```
void setTo(Object a,
           Object b,
           Object c)
```
    Sets the result value in this buffer to three values.
    This equivalent to the assignment of return values by the Lua statement
```
     return a, b, c
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {a, b, c})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
    Parameters:
    
    a - the first value, may be null
    
    b - the second value, may be null
    
    c - the third value, may be null
  - setTo
```
void setTo(Object a,
           Object b,
           Object c,
           Object d)
```
    Sets the result value in this buffer to four values.
    This equivalent to the assignment of return values by the Lua statement
```
     return a, b, c, d
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {a, b, c, d})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
    Parameters:
    
    a - the first value, may be null
    
    b - the second value, may be null
    
    c - the third value, may be null
    
    d - the fourth value, may be null
  - setTo
```
void setTo(Object a,
           Object b,
           Object c,
           Object d,
           Object e)
```
    Sets the result value in this buffer to five values.
    This equivalent to the assignment of return values by the Lua statement
```
     return a, b, c, d, e
 
```
    (Note, however, that this method has no influence on the control flow of its caller.)
    
    The effect of this method is equivalent to
```
     setToContentsOf(new Object[] {a, b, c, d, e})
 
```
    However, implementations of this method may be optimised due to the fact that the number of values in this case is known at compile time.
    Parameters:
    
    a - the first value, may be null
    
    b - the second value, may be null
    
    c - the third value, may be null
    
    d - the fourth value, may be null
    
    e - the fifth value, may be null
  - setToContentsOf
```
void setToContentsOf(Object[] array)
```
    Sets the result value in this buffer to the contents of array.
    This equivalent to the assignment of return values by the Lua statement
```
     return a_0, ..., a_n
 
```
    where a_i denotes the value of args[i] and n is equal to (args.length - 1). (Note, however, that this method has no influence on the control flow of its caller.)
    
    The contents of array are not modified by the buffer, and the reference to array is not retained by the buffer. (In other words, implementations of the ReturnBuffer interface are required to make a copy of array's contents.)
    
    For result values of known length, it is recommended to use the appropriate setTo(...) method.
    Parameters:
    
    array - the array to set values from, must not be null
    
    Throws:
    
    NullPointerException - if array is null
  - setToContentsOf
```
void setToContentsOf(Collection<?> collection)
```
    Sets the result value in this buffer to the contents of collection, in the order given by collection's iterator().
    This equivalent to the assignment of return values by the Lua statement
```
     return a_0, ..., a_n
 
```
    where a_i denotes the value returned by the (i+1)-th invocation of an iterator on args, and n is equal to args.size() - 1. (Note, however, that this method has no influence on the control flow of its caller.)
    
    The contents of collection are not modified by the buffer, and the reference to collection is not retained by the buffer. (In other words, implementations of the ReturnBuffer interface are required to make a copy collection's contents.
    
    When the contents of collection are modified concurrently with the execution of this method, the behaviour of this method is undefined.
    
    The effect of this method is equivalent to
```
     setToContentsOf(collection.toArray())
 
```
    However, implementations of this method may be expected to iterate over the elements of collection directly (i.e, avoiding the conversion to array).
    
    For result values of known length, it is recommended to use the appropriate setTo(...) method.
    Parameters:
    
    collection - the collection to set values from, must not be null
    
    Throws:
    
    NullPointerException - if collection is null
  - setToCall
```
void setToCall(Object target)
```
    Sets the result in this buffer to a tail call of target without arguments.
    This equivalent to the assignment of return values by the Lua statement
```
     return target()
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    Parameters:
    
    target - tail call target, may be null
  - setToCall
```
void setToCall(Object target,
               Object arg1)
```
    Sets the result in this buffer to a tail call of target with a single argument arg1.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(arg1)
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {arg1})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    
    Note: the argument arg1 is taken as-is, even if arg1 is an array or a collection. To set the call arguments to the contents of arg1, use setToCallWithContentsOf(Object, Object[])} or setToCallWithContentsOf(Object, Collection)}.
    Parameters:
    
    target - tail call target, may be null
    
    arg1 - the first call argument, may be null
  - setToCall
```
void setToCall(Object target,
               Object arg1,
               Object arg2)
```
    Sets the result in this buffer to a tail call of target with the arguments arg1 and arg2.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(arg1, arg2)
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {arg1, arg2})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    Parameters:
    
    target - tail call target, may be null
    
    arg1 - the first call argument, may be null
    
    arg2 - the second call argument, may be null
  - setToCall
```
void setToCall(Object target,
               Object arg1,
               Object arg2,
               Object arg3)
```
    Sets the result in this buffer to a tail call of target with the arguments arg1, arg2 and arg3.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(arg1, arg2, arg3)
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object, Object, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {arg1, arg2, arg3})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    Parameters:
    
    target - tail call target, may be null
    
    arg1 - the first call argument, may be null
    
    arg2 - the second call argument, may be null
    
    arg3 - the third call argument, may be null
  - setToCall
```
void setToCall(Object target,
               Object arg1,
               Object arg2,
               Object arg3,
               Object arg4)
```
    Sets the result in this buffer to a tail call of target with the arguments arg1, arg2, arg3 and arg4.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(arg1, arg2, arg3, arg4)
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object, Object, Object, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {arg1, arg2, arg3, arg4})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    Parameters:
    
    target - tail call target, may be null
    
    arg1 - the first call argument, may be null
    
    arg2 - the second call argument, may be null
    
    arg3 - the third call argument, may be null
    
    arg4 - the fourth call argument, may be null
  - setToCall
```
void setToCall(Object target,
               Object arg1,
               Object arg2,
               Object arg3,
               Object arg4,
               Object arg5)
```
    Sets the result in this buffer to a tail call of target with the arguments arg1, arg2, arg3, arg4 and arg5.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(arg1, arg2, arg3, arg4, arg5)
 
```
    Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object, Object, Object, Object).)
    
    The effect of this method is equivalent to
```
     setToCallWithContentsOf(target, new Object[] {arg1, arg2, arg3, arg4, arg5})
 
```
    However, implementations of this method may optimise this method since the number of arguments is known at compile time.
    Parameters:
    
    target - tail call target, may be null
    
    arg1 - the first call argument, may be null
    
    arg2 - the second call argument, may be null
    
    arg3 - the third call argument, may be null
    
    arg4 - the fourth call argument, may be null
    
    arg5 - the fifth call argument, may be null
  - setToCallWithContentsOf
```
void setToCallWithContentsOf(Object target,
                             Object[] args)
```
    Sets the result in this buffer to a tail call of target with the contents of the array args used as call arguments.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(a_0, ..., a_n)
 
```
    where a_i denotes the value of args[i] and n is equal to (args.length - 1). Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object[]).)
    
    The contents of args are not modified by the buffer, and the reference to args is not retained by the buffer. (In other words, implementations of the ReturnBuffer interface are required to make copy of args's contents.)
    
    For tail calls with a fixed number of arguments known at compile time, it is recommended to use the appropriate setToCall(...) method.
    Parameters:
    
    target - tail call target, may be null
    
    args - the array to set values from, must not be null
    
    Throws:
    
    NullPointerException - if args is null
  - setToCallWithContentsOf
```
void setToCallWithContentsOf(Object target,
                             Collection<?> args)
```
    Sets the result in this buffer to a tail call of target with the contents of the collection args used as call arguments.
    This equivalent to the assignment of return values by the Lua statement
```
     return target(a_0, ..., a_n)
 
```
    where a_i denotes the value returned by the (i+1)-th invocation of an iterator on args, and n is equal to args.size() - 1. Note, however, that this method is not a control statement that it does not evaluate the call, but rather stores into the buffer a description of how the call should be made. (In order to execute such a call in a non-tail-call setting, use Dispatch.call(ExecutionContext, Object, Object[]).)
    
    The contents of args are not modified by the buffer, and the reference to args is not retained by the buffer. (In other words, implementations of the ReturnBuffer interface are required to make copy of args's contents.)
    
    The effect of this method is equivalent to
```
     setToTailCallWithContentsOf(target, args.toArray())
 
```
    However, implementations of this method may be expected to iterate over the elements of collection directly (i.e, avoiding the conversion to array).
    
    For tail calls with a fixed number of arguments known at compile time, it is recommended to use the appropriate setToCall(...) method.
    Parameters:
    
    target - tail call target, may be null
    
    args - the array to set values from, must not be null
    
    Throws:
    
    NullPointerException - if args is null
  - getAsArray
```
Object[] getAsArray()
```
    Returns the values stored in this buffer as an array.
    When this buffer is a tail call, the result will be the arguments of the call; otherwise, the result are the return values.
    
    The resulting array is freshly allocated, and the reference to it is not retained by the buffer. It may therefore be used freely (no defensive copying is required).
    
    This method's functionality is equivalent to the following:
```
     public Object[] getAsArray() {
         Object[] result = new Object[size()];
         for (int i = 0; i < size(); i++) {
             result[i] = get(i);
         }
         return result;
     }
 
```
    (Implementations of this interface may of course provide a more optimised implementation of this method.)
    Returns:
    
    values stored in this buffer as an array, guaranteed to be non-null
  - get
```
Object get(int idx)
```
    Returns the idx-th value stored in this buffer, or null if there is no value with the given index idx.
    Indices start at 0 like in Java, i.e. 0 is the index of the first value.
    
    When this buffer is a tail call, the result is the idx-th argument of the call; otherwise, it is the idx-th return value.
    
    A null result may be an indication of an index out of bounds, or that the value at the idx-th position is null. In order to distinguish these two cases, an explicit query of the size() must be used.
    
    Note that when the index is known at compile time, it is recommended to use the appropriate optimised getter method (e.g., get0() for accessing the first value).
    
    Parameters:
    
    idx - the index of the value to be retrieved
    
    Returns:
    
    the idx-th value stored in the buffer (may be null), or null if there is no value with index idx
  - get0
```
Object get0()
```
    Returns the first value stored in this buffer.
    The effect of this method is equivalent to get(0); however, implementations of this interface may optimise this method since the index is known at compile time.
    
    When this buffer is a tail call, the result is the first argument of the call; otherwise, it is the first return value.
    
    Returns:
    
    the value of the first value stored in this buffer (may be null), or null if this buffer is empty
  - get1
```
Object get1()
```
    Returns the second value stored in this buffer.
    The effect of this method is equivalent to get(1); however, implementations of this interface may optimise this method since the index is known at compile time.
    
    When this buffer is a tail call, the result is the second argument of the call; otherwise, it is the second return value.
    
    Returns:
    
    the value of the second value stored in this buffer (may be null), or null if this buffer's size is empty
  - get2
```
Object get2()
```
    Returns the third value stored in this buffer.
    The effect of this method is equivalent to get(2); however, implementations of this interface may optimise this method since the index is known at compile time.
    
    When this buffer is a tail call, the result is the third argument of the call; otherwise, it is the third return value.
    
    Returns:
    
    the value of the third value stored in this buffer (may be null), or null if this buffer's size is empty
  - get3
```
Object get3()
```
    Returns the fourth value stored in this buffer.
    The effect of this method is equivalent to get(3); however, implementations of this interface may optimise this method since the index is known at compile time.
    
    When this buffer is a tail call, the result is the fourth argument of the call; otherwise, it is the fourth return value.
    
    Returns:
    
    the value of the fourth value stored in this buffer (may be null), or null if this buffer's size is empty
  - get4
```
Object get4()
```
    Returns the fifth value stored in this buffer.
    The effect of this method is equivalent to get(4); however, implementations of this interface may optimise this method since the index is known at compile time.
    
    When this buffer is a tail call, the result is the fifth argument of the call; otherwise, it is the fifth return value.
    
    Returns:
    
    the value of the fifth value stored in this buffer (may be null), or null if this buffer's size is empty

Interface ReturnBuffer

Method Summary

Method Detail

size

isCall

getCallTarget

setTo

setTo

setTo

setTo

setTo

setTo

setToContentsOf

setToContentsOf

setToCall

setToCall

setToCall

setToCall

setToCall

setToCall

setToCallWithContentsOf

setToCallWithContentsOf

getAsArray

get

get0

get1

get2

get3

get4