| Chapter 15. The Language Utilities (UTIL) Component | ||
|---|---|---|
 | Part II. C-Language Components |  |
Chapter 15. The Language Utilities (UTIL) Component
This component provides a common location for utility types and functions that are important but not worth including in the core language component.
dlist
Description
The dlist type consists of a doubly-linked list of
dnode objects. Instead of being a ring, this provides a
first and a last property (with
the obvious meanings). It also provides a method of retrieving the count
of nodes, and the nodes at the beginning and the end of a list refer to
.nul in their properties for the appropriate direction
(either next or prev).
Type Tags
None
Object Value
Objects of type dlist have no value, and it is an error to try to get or set this value.
dlist.new()
Description
Creates a new empty dlist object.
Prototype
dlist.new ()
Parameters
None
Properties
| Property | Type | Description |
|---|---|---|
| _ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. |
| __ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property. |
| first | dnode |
This is the first node in the list. If there are no elements in the list, then
this will be .nul.
|
| last | dnode |
This is the last node in the list. If there are no elements in the list, then
this will be .nul.
|
| type | type | Specifies the dlist type object. |
Methods
clear()
Description
This clears the nodes from a list and makes any nodes that are still referred to anywhere into a complete ring. This means that the nodes still exist, they simply aren't part of the list any more, unless none of the nodes are referred to by any other variable, in which case they will no longer exist.
Prototype
dlistvar.clear ()
Parameters
None
count()
Description
Returns the number of nodes in the list.
Prototype
dlistvar.count ()
Parameters
None
getnode()
Description
Returns the node from the list corresponding to the index value passed as the
parameter. The first node has the index value 1
and the last node will have an index value equal to that returned by
the count() method.
Prototype
dlistvar.getnode (
integer index
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| index | None | integer | Specifies the index value of the node to retrieve. |
insertfirst()
Description
Inserts the node passed as the first node in the list. If the node is part of
a ring consisting of more than one node, then the ring will be broken
following the node passed and all entries will be inserted prior to
that node which will then have the former first node of the list (if
any) as its next node and it will become the
prev node of the former first node. If, for
example, there is a rings of nodes: a, b, c (, a, b,
…) and a list x containing:
d, e, f, and then the call:
x.insertfirst(b) is made, then the result in
x will be: c, a, b, d, e, f. It
is an error to pass a node to this method if that node is already in
a list.
Prototype
dlistvar.insertfirst (
dnode node
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| node | None | dnode | Specifies the node that should be inserted into the beginning of the list. |
insertlast()
Description
Inserts the node passed as the last node in the list. If the node is part of a
ring consisting of more than one node, then the ring will be broken
following the node passed and all entries will be inserted prior to
that node, the first of which will then have the former last node of
the list (if any) as its prev node and it will
become the next node of the former last node.
If, for example, there is a rings of nodes: a, b, c (, a, b,
…) and a list x containing:
d, e, f, and then the call:
x.insertlast(b) is made, then the result in
x will be: d, e, f, c, a, b. It
is an error to pass a node to this method if that node is already in
a list.
Prototype
dlistvar.insertlast (
dnode node
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| node | None | dnode | Specifies the node that should be inserted at the end of the list. |