---

G.5 Stacks ¶

The library libmbfl-containers.bash implements the traditional stack container with basic operations. Stacks are wrappers for Bash indexed arrays, See Arrays.

Class: mbfl_stack ¶

Superclass: mbfl_default_object ¶

Metaclass: mbfl_default_class ¶

Class of objects representing stacks.

In this documentation: whenever a parameter to function is the data variable of an object of this class, the parameter is named STK.

Constructor on mbfl_stack_t: mbfl_stack_make STK ¶

Build a new object of class mbfl_stack and store it in the already declared variable STK. Some resources are allocated, so when we do not need STK anymore: we must apply a destructor to it.

Destructor on mbfl_stack_t: mbfl_stack_unmake STK ¶

Destroy an object of class mbfl_stack, releasing its resources. The variable STK itself is not unset.

mbfl_location_enter
{
    mbfl_default_object_declare(STK)
    mbfl_location_handler "mbfl_undeclare_varref(_(STK))"

    mbfl_stack_make _(STK)
    mbfl_location_handler "mbfl_stack_unmake _(STK)"

    mbfl_stack_push _(STK) 123
}
mbfl_location_leave

Predicate on mbfl_stack_t: mbfl_stack_is_a OBJ ¶

Return true if OBJ is an object of class mbfl_stack; otherwise return false.

Function: mbfl_stack_size_var SIZE_RV STK ¶

Retrieve the current number of elements on the stack STK and store it in the variable SIZE_RV.

mbfl_default_object_declare(STK)
mbfl_declare_varref(SIZE)

mbfl_stack_make _(STK)
mbfl_stack_push _(STK) 1
mbfl_stack_push _(STK) 2

mbfl_stack_size_var _(SIZE) _(STK)
$SIZE   ⇒ 2

Function: mbfl_stack_push STK ITEM … ¶

Push all the optional parameters ITEM on the stack STK.

mbfl_default_object_declare(STK)

mbfl_stack_make _(STK)
mbfl_stack_push _(STK) 1 2
mbfl_stack_push _(STK) 3

Function: mbfl_stack_top_var OBJ_RV STK ¶

Retrieve the top element from the stack STK and store it in the variable OBJ_RV.

mbfl_default_object_declare(STK)
mbfl_declare_varref(OBJ)

mbfl_stack_make _(STK)
mbfl_stack_push _(STK) 1
mbfl_stack_push _(STK) 2

mbfl_stack_top_var _(OBJ) _(STK)
"$OBJ"  ⇒ 2

Function: mbfl_stack_pop_var OBJ_RV STK ¶

Retrieve and remove the top element from the stack STK and store it in the variable OBJ_RV.

mbfl_default_object_declare(STK)
mbfl_declare_varref(OBJ)

mbfl_stack_make _(STK)
mbfl_stack_push _(STK) 1
mbfl_stack_push _(STK) 2

mbfl_stack_pop_var _(OBJ) _(STK)
"$OBJ"  ⇒ 2

mbfl_stack_pop_var _(OBJ) _(STK)
"$OBJ"  ⇒ 1

Function: mbfl_stack_copy DST_STK SRC_STK ¶

Copy the elements from SRC_STK to DST_STK by directly copying them from the underlying arrays. The old contents of DST_STK are overwritten.

mbfl_default_object_declare(STK1)
mbfl_default_object_declare(STK2)

mbfl_stack_make _(STK1)
mbfl_stack_make _(STK2)

mbfl_stack_push  _(STK1) 'uno' 'due' 'tre'
mbfl_stack_copy  _(STK2) _(STK1)
mbfl_stack_equal _(STK2) _(STK1)
⇒ 0

Function: mbfl_stack_equal STK1 STK2 ¶

Function: mbfl_stack_equal STK1 STK2 ISEQUAL ¶

Compare the elements from STK1 and STK2 using the function ISEQUAL: return true if the elements are equal; return false otherwise.

The optional argument ISEQUAL must be an identifier, bound to a shell function or command, accepting the parameters:

ISEQUAL ELEMENT1 ELEMENT2

when not given, it defaults to mbfl_string_equal().

Function: mbfl_stack_dump STK ¶

Function: mbfl_stack_dump STK LABEL ¶

Print to stderr the elements of the array underlying STK, using the function mbfl_array_dump().