STL Container IB Reference
From CometWiki
(Difference between revisions)
m (→Iteration Functions) |
|||
| (18 intermediate revisions not shown) | |||
| Line 1: | Line 1: | ||
===Core Functions=== | ===Core Functions=== | ||
| + | These are the main functions you will use for each container. | ||
| + | |||
====Vector==== | ====Vector==== | ||
'''stlPushBack( <container-name>, <data> )''' adds an element to the end of the vector | '''stlPushBack( <container-name>, <data> )''' adds an element to the end of the vector | ||
'''stlPopBack( <container-name> )''' removes the element at the end of the vector | '''stlPopBack( <container-name> )''' removes the element at the end of the vector | ||
| - | '''stlFront( <container-name> )''' gets the element at the front of the vector | + | '''stlFront( <container-name> [,EXCP=statement label])''' gets the element at the front of the vector |
| - | '''stlBack( <container-name> )''' gets the element at the end of the vector | + | '''stlBack( <container-name> [,EXCP=statement label])''' gets the element at the end of the vector |
| - | ''' | + | '''stlGet( <container-name>, <index> [,EXCP=statement label])''' gets the element at the index specified |
| - | '''<container-name> | + | '''stlSet( <container-name> <index> <data>)''' sets the element at the index specified |
| - | Similar to arrays, vectors are mostly used to access data based on a numeric index, thus | + | Similar to arrays, vectors are mostly used to access data based on a numeric index, thus stlGet and stlSet are going to be your bread and butter functions for this container. stlPushBack is a great way to programatically build a vector - it will append the specified data to the end of the vector, and increase its size by 1. If you want to remove the last element, you would use stlPopBack. Then the stlFront and stlBack functions have been included as shortcuts for accessing the first and last elements respectively. |
====List==== | ====List==== | ||
| Line 15: | Line 17: | ||
'''stlPushFront( <container-name>, <data> )''' adds an element to the beginning of the list | '''stlPushFront( <container-name>, <data> )''' adds an element to the beginning of the list | ||
'''stlPopFront( <container-name> )''' removes the element at the beginning of the list | '''stlPopFront( <container-name> )''' removes the element at the beginning of the list | ||
| - | '''stlFront( <container-name> )''' gets the element at the beginning of the list | + | '''stlFront( <container-name> [,EXCP=statement label])''' gets the element at the beginning of the list |
| - | '''stlBack( <container-name> )''' gets the element at the end of the list | + | '''stlBack( <container-name> [,EXCP=statement label])''' gets the element at the end of the list |
| + | |||
| + | Lists are designed to be accessed sequentially, that is each element is associated with the preceding and following elements in the container. As such, the core functions provided are used to add, remove, and get the elements at the front and back of the list. The real power of lists is utilized during iteration - they are the most efficient container for inserting and erasing elements in the middle of the container. | ||
====Map==== | ====Map==== | ||
| - | ''' | + | '''stlGet( <container-name>, <key> [,EXCP=statement label])''' gets the element at the key specified |
| - | '''<container-name> | + | '''stlSet( <container-name> <key> <data>)''' sets the element at the key specified |
| + | |||
| + | Maps are used to relate an element to a key (string index). Similar to vectors, to access a value, the key must be specified. | ||
====Stack/Queue==== | ====Stack/Queue==== | ||
'''stlPush( <container-name>, <data> )''' adds an element to the container | '''stlPush( <container-name>, <data> )''' adds an element to the container | ||
'''stlPop( <container-name> )''' removes the next element from the container | '''stlPop( <container-name> )''' removes the next element from the container | ||
| - | '''stlPeek( <container-name> )''' gets the next element from the container | + | '''stlPeek( <container-name> [,EXCP=statement label])''' gets the next element from the container |
| - | ''' | + | '''stlGet( <container-name>, <index> [,EXCP=statement label])''' gets the element at the index specified |
| - | '''<container-name> | + | '''stlSet( <container-name> <index> <data>)''' sets the element at the index specified |
Both stacks and queues utilize the same set of functions, but perform differently depending on which container you have implemented. In general, the stlPush, stlPop, and stlPeek functions are going to be the most important of these functions. They perform the basic operations associated with these containers. For stacks, stlPush and stlPop adds and removes from the end of the container. For queues, stlPush adds to the end of the container, and stlPop removes from the front of the container. For both containers, stlPeek will get the "next" element in the container (i.e. the last element for stacks, the first element for queues). | Both stacks and queues utilize the same set of functions, but perform differently depending on which container you have implemented. In general, the stlPush, stlPop, and stlPeek functions are going to be the most important of these functions. They perform the basic operations associated with these containers. For stacks, stlPush and stlPop adds and removes from the end of the container. For queues, stlPush adds to the end of the container, and stlPop removes from the front of the container. For both containers, stlPeek will get the "next" element in the container (i.e. the last element for stacks, the first element for queues). | ||
| - | Because these containers are implemented with deques internally, we also provide access via numeric indexes with the stlSet and () | + | Because these containers are implemented with deques internally, we also provide access via numeric indexes with the stlSet() and stlGet() operators. These functions behave similarly to the vector functions of the same name, by getting and setting the elements at the specified index. |
===Iteration Functions=== | ===Iteration Functions=== | ||
These functions are used to iterate over the elements of a container. | These functions are used to iterate over the elements of a container. | ||
| - | ''' | + | General: |
| - | ''' | + | '''stlBegin( <container-name> )''' sets the iterator position at the beginning |
| - | '''stlNext( <container-name> )''' moves the iterator position forward one element | + | '''stlEnd( <container-name> )''' sets the iterator position at the end |
| + | '''stlNext( <container-name> ) [, EXCP=statement label]''' moves the iterator position forward one element | ||
'''stlPrev( <container-name> )''' moves the iterator position back one element | '''stlPrev( <container-name> )''' moves the iterator position back one element | ||
| - | '''stlRead( <container-name> )''' gets the element at the current iterator position | + | '''stlRead( <container-name> [,EXCP=statement label])''' gets the element at the current iterator position |
'''stlWrite( <container-name>, <data> )''' - sets the element at the current iterator position | '''stlWrite( <container-name>, <data> )''' - sets the element at the current iterator position | ||
| + | |||
| + | Maps only: | ||
| + | '''stlReadKey( <container-name> [,EXCP=statement label])''' gets the key at the current iterator position | ||
| + | |||
| + | Lists only: | ||
| + | '''stlInsert( <container-name>, <data> )''' inserts the element BEFORE the current iterator position | ||
| + | '''stlErase( <container-name> )''' erases the element at the current iterator position | ||
| + | (stlErase will subsequently move the iterator position to the next element) | ||
===Utility Functions=== | ===Utility Functions=== | ||
These are basic functions that return information about the specified container. | These are basic functions that return information about the specified container. | ||
| - | '''stlSize( <container-name> )''' returns the size of the container | + | '''stlSize( <container-name> [,EXCP=statement label])''' returns the size of the container |
| - | '''stlEmpty( <container-name> )''' returns whether the container is empty | + | '''stlEmpty( <container-name> [,EXCP=statement label])''' returns whether the container is empty |
'''stlClear( <container-name> )''' empties the specified container | '''stlClear( <container-name> )''' empties the specified container | ||
'''stlReset( <container-name> )''' resets the container to its initial values | '''stlReset( <container-name> )''' resets the container to its initial values | ||
Latest revision as of 21:46, 13 October 2023
Contents |
Core Functions
These are the main functions you will use for each container.
Vector
stlPushBack( <container-name>, <data> ) adds an element to the end of the vector stlPopBack( <container-name> ) removes the element at the end of the vector stlFront( <container-name> [,EXCP=statement label]) gets the element at the front of the vector stlBack( <container-name> [,EXCP=statement label]) gets the element at the end of the vector stlGet( <container-name>, <index> [,EXCP=statement label]) gets the element at the index specified stlSet( <container-name> <index> <data>) sets the element at the index specified
Similar to arrays, vectors are mostly used to access data based on a numeric index, thus stlGet and stlSet are going to be your bread and butter functions for this container. stlPushBack is a great way to programatically build a vector - it will append the specified data to the end of the vector, and increase its size by 1. If you want to remove the last element, you would use stlPopBack. Then the stlFront and stlBack functions have been included as shortcuts for accessing the first and last elements respectively.
List
stlPushBack( <container-name>, <data> ) adds an element to the end of the list stlPopBack( <container-name> ) removes the element at the end of the list stlPushFront( <container-name>, <data> ) adds an element to the beginning of the list stlPopFront( <container-name> ) removes the element at the beginning of the list stlFront( <container-name> [,EXCP=statement label]) gets the element at the beginning of the list stlBack( <container-name> [,EXCP=statement label]) gets the element at the end of the list
Lists are designed to be accessed sequentially, that is each element is associated with the preceding and following elements in the container. As such, the core functions provided are used to add, remove, and get the elements at the front and back of the list. The real power of lists is utilized during iteration - they are the most efficient container for inserting and erasing elements in the middle of the container.
Map
stlGet( <container-name>, <key> [,EXCP=statement label]) gets the element at the key specified stlSet( <container-name> <key> <data>) sets the element at the key specified
Maps are used to relate an element to a key (string index). Similar to vectors, to access a value, the key must be specified.
Stack/Queue
stlPush( <container-name>, <data> ) adds an element to the container stlPop( <container-name> ) removes the next element from the container stlPeek( <container-name> [,EXCP=statement label]) gets the next element from the container stlGet( <container-name>, <index> [,EXCP=statement label]) gets the element at the index specified stlSet( <container-name> <index> <data>) sets the element at the index specified
Both stacks and queues utilize the same set of functions, but perform differently depending on which container you have implemented. In general, the stlPush, stlPop, and stlPeek functions are going to be the most important of these functions. They perform the basic operations associated with these containers. For stacks, stlPush and stlPop adds and removes from the end of the container. For queues, stlPush adds to the end of the container, and stlPop removes from the front of the container. For both containers, stlPeek will get the "next" element in the container (i.e. the last element for stacks, the first element for queues).
Because these containers are implemented with deques internally, we also provide access via numeric indexes with the stlSet() and stlGet() operators. These functions behave similarly to the vector functions of the same name, by getting and setting the elements at the specified index.
Iteration Functions
These functions are used to iterate over the elements of a container.
General:
stlBegin( <container-name> ) sets the iterator position at the beginning stlEnd( <container-name> ) sets the iterator position at the end stlNext( <container-name> ) [, EXCP=statement label] moves the iterator position forward one element stlPrev( <container-name> ) moves the iterator position back one element stlRead( <container-name> [,EXCP=statement label]) gets the element at the current iterator position stlWrite( <container-name>, <data> ) - sets the element at the current iterator position
Maps only:
stlReadKey( <container-name> [,EXCP=statement label]) gets the key at the current iterator position
Lists only:
stlInsert( <container-name>, <data> ) inserts the element BEFORE the current iterator position stlErase( <container-name> ) erases the element at the current iterator position (stlErase will subsequently move the iterator position to the next element)
Utility Functions
These are basic functions that return information about the specified container.
stlSize( <container-name> [,EXCP=statement label]) returns the size of the container stlEmpty( <container-name> [,EXCP=statement label]) returns whether the container is empty stlClear( <container-name> ) empties the specified container stlReset( <container-name> ) resets the container to its initial values
Meta Functions
These functions perform some action either on all of the elements in the container, or using all the elements in the container.
