8.2.3 Group Functions

Groups have many functions for operating on the elements of the group.

These functions return an element of the group. The element is an instance of the group's element type.

El (int i)
Returns the element of the group at index i. If the index is out of range, an out of rangeerror is reported, and NULL is returned.
DefaultEl()
Returns the element indexed by the default_el variable of the group.
Leaf (int n)
Performs a depth first search to find the nth leaf of the group tree.
FirstEl()
Utilizes sets the internal leaf index to zero and return the first leaf.
NextEl();
Increments the internal leaf index and returns the leaf of that index.
Pop()
Returns the last element of the group, and removes it from the group as well.
Peek()
This function is similar to the Pop() function, but it does not remove the element.

These functions return an integer indicating the index of the element in the group. In all these functions if no match is found, a value of "-1" is returned.

FindEl (inst el)
Returns the index of the element of the group which matches el.
FindName (char* name)
Returns the index of the element which has a name field which matches name.
Find (TypeDef t)
Returns the index of the first element of type T.
FindLeaf (char* name)
Returns the leaf index of the leaf element which has a name field which matches name.
FindLeafEl (inst el)
Returns the leaf index of the leaf element which matches el.

These functions are used to add elements to the group.

AddEl (inst el)
Adds element el to the group
AddUniqueName (inst el)
Adds an element el to the group and adds an instance index to its name if another element in the group has the same name.
Push (inst el)
Adds element el to the end of the group.
PushUnique (inst el)
Adds element el to the end of group only if it is not in the group already.
PushUniqueName (inst el)
Adds element el to the end of the group only if there are no other elements of the group with the same name.
Insert (inst el, int i)
Inserts element el at position i in the group. If the position i is out of range, it is added to the beginning or end of the group accordingly.
Replace (int i ,inst el)
Replaces the element at location i with the element el.
ReplaceEl (inst rel, inst el)
Replaces the element rel of the group with element el. If no match is found, the element el is not inserted.
ReplaceName (char* name, inst el)
Replaces the element with the name name with the element el. If no match is found, the element el is not inserted.
Transfer (inst el)
Removes el from the group or owner it is currently in and adds it to this group.
Link (inst el)
Adds a link to the object el to this group. There are also corresponding functions (InsertLink, ReplaceLink, etc) which perform as the do the Add functions except they link instead of add (see section 8.2 Groups).
New (int i, typedef t)
Creates i new objects of type t in the group.

These functions are used for removing elements from the group.

Remove (int i)
Removes the element at position i. If the element is owned by the group it deletes the element. If the element is a linked element, it deletes the link.
Move (int from, int to)
Removes an element from position from and inserts at position to.
RemoveName (char* name)
Removes the element with a name matching name.
RemoveLeafName (char* name)
Removes the leaf with a name matching name.
RemoveAll()
Removes all the elements of the group.

These functions return a subgroup of the group.

Gp (int i)
Returns the subgroup at index(i)
LeafGp (int n)
Returns the nth subgroup which contains leaves.
FirstGp()
Sets the group index to zero and returns the first subgroup with leaf elements.
NextGp()
Increments the group index and return the corresponding subgroup with leaf elements.