Valset Class Reference

Valset is an STL-compatible container for contiguous Lua stack slots. Its primary use is accepting multiple return values. More...

Inherits noNew.

Public Types
typedef Valref	value_type
	The Valref objects are not actually stored, but rather created dynamically.
typedef size_t	size_type
	Index type.
typedef ptrdiff_t	difference_type
	Index difference.
typedef valset_iterator	iterator
	Normal iterator.
typedef valset_const_iterator	const_iterator
	Const iterator.
typedef std::reverse_iterator< iterator >	reverse_iterator
	Reverse iterator.
typedef std::reverse_iterator< const_iterator >	const_reverse_iterator
	Reverse const iterator.
typedef value_type	reference
	Reference to a value is still a Valref.
typedef const value_type	const_reference
	Const reference doesn't strictly enforce immutability.

Public Member Functions
Life cycle
	Valset (Temporary src)
	Construct from an expression. More...
	Valset (const Valref &src)
	Copy a value into set (works with Value and Table too).
	Valset (Valset &&)
	Valset can be returned from functions but not actually moved.
	Valset (Context &s) noexcept
	Create an empty Valset. More...
	Valset (const Valset &src) noexcept
	Create copies of values stored in src.
	~Valset () noexcept
	Owned stack slots are freed on destruction.
Element access
reference	at (size_t index)
	Checked indexation. More...
const_reference	at (size_t index) const
	Checked indexation. More...
const_reference	operator[] (size_t index) const noexcept
	Unchecked indexation.
reference	operator[] (size_t index) noexcept
	Unchecked indexation.
Iterators
iterator	begin () noexcept
const_iterator	begin () const noexcept
const_iterator	cbegin () const noexcept
iterator	end () noexcept
const_iterator	end () const noexcept
const_iterator	cend () const noexcept
reverse_iterator	rbegin () noexcept
const_reverse_iterator	rbegin () const noexcept
const_reverse_iterator	crbegin () const noexcept
reverse_iterator	rend () noexcept
const_reverse_iterator	rend () const noexcept
const_reverse_iterator	crend () const noexcept
Capacity
size_t	size () const noexcept
	Amount of stored values.
bool	empty () const noexcept
	Check if the container is empty.
Modification
template<typename... Types>
void	push_back (Types &&...values)
	Add values to the end. More...
void	pop_back (size_t amount=1)
	Remove a value from the end. More...
Status query
bool	success () const noexcept
	Protected call status. More...
bool	isBlocked () const noexcept
	Blocked status. More...

Detailed Description

Valset is an STL-compatible container for contiguous Lua stack slots. Its primary use is accepting multiple return values.

This object owns arbitrary number of neighbouring stack slots. It is STL compatible, so it's possible to use standard algorithms with it (also things like back_inserter, range-based for and so on). The values are accessed by indexation with integer indices or through iterators which dereference to Valref.
This class is designed for following uses:

• accept multiple return values from function calls;
• hold function arguments (see Context::args);
• be a temporary storage for processing a number of values;
• collect values to be returned from the function when their number is big or variable.

If no values are placed on the stack after the Valset, it is unblocked, which means that new value can be added to its end with push_back, or the last value be removed with pop_back function. Otherwise the Valset is in "blocked" state and cannot be grown or shrunk.
On object's destruction all owned slots are freed (unless it is used to return values from the function).
When put inside value sequence (like function arguments or array content), Valset automatically expands into contained values. But Valset cannot be used in a place that requires single value (like index).

Note

Contrary to general Lua standards, Valset indexation is 0-based.

Valset's iterators conform to RandomAccessIterator concept.

Valset does not actually store anything, it only remembers the lower and upper indices of owned stack slots.

Lua has no concept of immutability, so even constant Valset could be used to change the referenced or nested values.

Constructor & Destructor Documentation

Valset

(

Temporary

src

)

Construct from an expression.

The created Valset will have 1 element inside.
If the expression was a function call that returned multiple values, the Valset will contain all returned values.
If the expression was a protected function call which ended succesfully, the Valset will contain all returned values.
Unsuccesfull protected call will put into Valset error description and the success status will be "false".

Valset ( Context &  s )

explicitnoexcept

Create an empty Valset.

Note

Empty Valset does not occupy space on the stack, but it still blocks other Valsets.

Member Function Documentation

reference at ( size_t  index )

inline

Checked indexation.

Exceptions

std::range

error

const_reference at ( size_t  index ) const

inline

Checked indexation.

Exceptions

std::range

error

void push_back

(

Types &&...

values

)

Add values to the end.

Precondition

!isBlocked()

Exceptions

std::runtime_error

if Valset is blocked or if push failed.

void pop_back

(

size_t

amount = 1

)

Remove a value from the end.

Precondition

!isBlocked()

Exceptions

std::runtime_error

if Valset is blocked.

Note

Minimum of size() and "amount" is chosen.

bool success ( ) const

inlinenoexcept

Protected call status.

If success() returns false, the protected call failed and Valset contains error message. If Valset wasn't created from protected call, this function always returns true.

bool isBlocked ( ) const

noexcept

Blocked status.

Any value that occupies a slot after Valset makes it blocked. Attempt to add or remove an item from blocked Valset creates an exception.