STL Containers

From CometWiki

(Difference between revisions)
Jump to: navigation, search
(List)
m (minor)
 
(17 intermediate revisions not shown)
Line 1: Line 1:
===Introduction===
===Introduction===
-
The Standard Template Library (STL) in C++ provides a variety of containers for storing collections of data.  The concept of a container is similar to an array, but the STL containers are more robust in terms of functionality, and some are designed for a more specific purpose than the more general array structure.  All containers grow dynamically, negating the need for a declared length and memory management.  Each of the containers is designed to be accessed in the most efficient way using different functions, but all containers support a standard set of [[iteration]] functions that allow you to access each element in the container.
+
The Standard Template Library (STL) in C++ provides a variety of containers for storing collections of data.  The concept of a container is similar to an array, but the STL containers are more robust in terms of functionality, and some are designed for a more specific purpose than the more general array structure.  All containers grow dynamically, negating the need for a declared length and memory management.  Each of the containers is designed to be accessed in the most efficient way using different functions, but all containers support a standard set of [[#Iteration|iteration]] functions that allow you to access each element in the container.
-
The three major containers are the [[Vector]], the [[List]], and the [[Map]].  A vector is a collection made of contiguous memory, allowing for efficient access with a numeric index.  A list is a collection where each element contains a value plus a pointer to the next value in the list, allowing for extremely efficient insertion into and removal from anywhere in the container.  A map is a collection of key/value pairs, mapping a string index to a value.
+
The three major containers are the [[#Vector|vector]], the [[#List|list]], and the [[#Map|map]].  A vector is a collection made of contiguous memory, allowing for efficient access with a numeric index.  A list is a collection where each element contains a value plus a pointer to the next value in the list, allowing for extremely efficient insertion into and removal from anywhere in the container.  A map is a collection of key/value pairs, mapping a string index to a value.
-
We have also provided a [[Stack]] and a [[Queue]], which are specialized containers with a more specific purpose in mind.
+
We have also provided a [[#Stack|stack]] and a [[#Queue|queue]], which are specialized containers with a more specific purpose in mind.
-
===Container Types===
+
Stl containers can hold both string and numeric values, as well as [[#References|references]] to either typeReferences are similar to pointers in C/C++ type languages, where the container element will actually "point to" the specified variable.  That is, if you add a reference to a variable to a container, if that variable subsequently changes in your program, the value within the container will change as well.
-
The following containers have been implemented in Comet32Containers come in two forms: sequence containers maintain a specific order (generally the order of inserted items), and associative containers which do not maintain an order but instead rely on an associated key to retrieve the value.
+
 +
===Initialization===
 +
STL containers are defined in the declarative section, using a similar syntax to formats with some extra options.  Containers can be declared empty, with an initial size (except maps), or with initial values.  You must provide the name you will use to reference the container, as well as the type of container it will be.
 +
 +
<container-name>: <container-type>[(<size>)] [<value1>; <value2>; ...]
 +
 +
'''<container-name>''' (Required) Name used to reference this container in your program.
 +
 +
'''<container-type>''' (Required) One of the following: vector, list, map, stack, queue.
 +
 +
'''<size>''' (Optional) All containers except maps can be declared with an initial size.  The container will initialize with the specified size, containing empty values for uninitialized values.
 +
 +
'''<values>''' (Optional) All containers can be declared with initial values, separated by semi-colons (';').  These values will be automatically inserted into the container at the beginning of the program, and the container's size will be accurately reflected.  Maps require both a key and value, separated by a comma (','), for initialization.
 +
 +
===General Usage===
====Vector====
====Vector====
A vector is an indexable, sequence container that behaves like an array, but will grow as required.  Like arrays, vectors store their data in contiguous memory, which is why access with a numeric index is so efficient, but unlike arrays you get all of the robust functionality of an STL container.
A vector is an indexable, sequence container that behaves like an array, but will grow as required.  Like arrays, vectors store their data in contiguous memory, which is why access with a numeric index is so efficient, but unlike arrays you get all of the robust functionality of an STL container.
Line 16: Line 29:
====List====
====List====
-
A list is a sequence container in which each value points to the next value.  This way, lists allow for fast insertion and deletion anywhere in the container, but do now allow for random access via an index like arrays/vectors.
+
A list is a sequence container in which each value points to the next value.  This way, lists allow for fast insertion and deletion anywhere in the container, but do not allow for random access via an index like arrays/vectors.
-
Lists are implemented as doubly-linked lists, and since each value points to other values, the data does not need to be in contiguous storage like vectors.  Thus unlike vectors, lists are more efficient for programs that require consistent insertion/removal functionality, as a vector will have to perform dynamic reallocation (described above) as its size changes.
+
Lists are implemented as doubly-linked lists, and since each value points to other values, the data does not need to be in contiguous storage like vectors.  Thus unlike vectors, lists are more efficient for programs that require consistent insertion/removal functionality, as a vector will have to perform dynamic reallocation (described above) as its size changes.  Lists can append elements indefinitely without the need for reallocation.
====Map====
====Map====
-
A map is an associative container consisting of key/value pairs.  A map is basically a vector that uses a string index instead of a numerical index. Maps are designed for efficient access to values using their key, unlike sequence containers which are more efficient at accessing elements by their position (index).  Keys are unique - that is there will never be two values associated with the same key.
+
A map is an associative container consisting of key/value pairs.  A string index is "mapped" to the value specified, making the syntax similar to arrays and vectors.
 +
 
 +
Maps are designed for efficient access to values using their key, unlike sequence containers which are more efficient at accessing elements by their position (index).  Keys are unique - that is there will never be two values associated with the same key.
====Stack====
====Stack====
-
Stacks are deque (double-ended queue) containers designed for LIFO (Last In, First Out) access, which means that you are adding and removing elements at the "back" of the container.  A stack should be used when the last element you added to the container is the first one you want back out again. Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the container.  Insertions/removals from the middle of the container are not as efficient as lists.
+
Internally, stacks utilize deque (double-ended queue) containers to provide LIFO (Last In, First Out) access, which means that you are adding and removing elements at the "back" of the container.  A stack should be used when the last element you added to the container is the first one you want back out again.
 +
 
 +
Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the container.  Insertions/removals from the middle of the container are not as efficient as lists.
====Queue====
====Queue====
-
Queues are deque containers designed for FIFO (First In, First Out) access, which means that you are adding elements at the "back" of the container, and removing them from the "front" of the container.  A queue should be used when the first element you added is the first one you want back out again.  Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the container.  Insertions/removals from the middle of the container are not as efficient as lists.
+
Internally, queues utilize deque (double-ended queue) containers to provide FIFO (First In, First Out) access, which means that you are adding elements at the "back" of the container, and removing them from the "front" of the container.  A queue should be used when the first element you added is the first one you want back out again.
-
===Initialization===
+
Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the containerInsertions/removals from the middle of the container are not as efficient as lists.
-
Containers are defined in the declarative section, using a similar syntax to formats with some extra options.  Containers can be declared empty, with an initial size (except maps), or with initial valuesYou must provide the name you will use to reference the container, as well as the type of container it will be.
+
-
'''Initial Values''' All containers can be declared with initial valuesThese values will be automatically inserted into the container at the beginning of the program, and the container's size will be accurately reflected.
+
===Iteration===
 +
All STL Containers provide a standard iteration interface that allows you to step through each element in the collectionThat is, using the same functions, you can iterate through any STL container.  Think of iterating through a container as reading records from a file.  First the iterator is initialized, then you can move it through the container one element at a time.  At each position, you can read or write the element.
-
'''Initial Size''' All containers except maps can be declared with an initial sizeThe container will initialize with the specified size, but will contain blank values.   
+
Unfortunately, due to the internal implementation of the STL containers, although you will iterate over every element in the collection, an order cannot be guaranteedAlso, if the container is modified during iteration, the iterator cannot be guaranteed to still be validIf you modify the container during iteration, you must start the iteration process over in order to be sure every element is accessed.
-
<container-name>: <container-type>[(<size>)] [<initial-value>; <initial-value>; ...]
+
In general iteration is used to aggregate all of the data within a container (calculate a total, average, etc), or maybe to see if a certain value exists within the collection.
-
<map-name>: map [<initial-key>, <initial-value>; <initial-key>, <initial-value>; ...]
+
-
 
+
-
For example:
+
-
 
+
-
myVector: vector
+
-
myList: list 10; 20; 30; 40
+
-
myStack: stack(10)
+
-
myQueue: queue(5) 10; "twenty"; 30; 40; 50
+
-
myMap: map "key1", "value1"; "key2", 20
+
-
 
+
-
Are all valid declarations for STL containers.
+
-
 
+
-
===General Usage===
+
-
Once initialized, there is a standard set of functions that provide access to the STL containers.  In general, there are functions that store and access data in the containers, and there are also functions to iterate over and read data from the containers.
+
-
===IB Reference===
+
===[[STL Container IB Reference|IB Reference]]===
-
====Core====
+
Internet Basic function reference.
-
=====stlSize=====
+
-
=====stlEmpty=====
+
-
=====stlClear=====
+
-
=====stlReset=====
+
-
=====stlFront=====
+
-
=====stlBack=====
+
-
=====stlPush=====
+
-
=====stlPop=====
+
-
=====operator(index/key)=====
+
-
=====stlSet=====
+
-
=====stlPushFront=====
+
-
=====stlPopFront=====
+
-
====Iteration====
+
-
=====stlFirst=====
+
-
=====stlLast=====
+
-
=====stlNext=====
+
-
=====stlPrev=====
+
-
=====stlReadKey=====
+
-
=====stlRead=====
+
-
=====stlWrite=====
+
-
====Utility====
+
-
=====stlSort=====
+

Latest revision as of 03:47, 23 November 2011

Contents

Introduction

The Standard Template Library (STL) in C++ provides a variety of containers for storing collections of data. The concept of a container is similar to an array, but the STL containers are more robust in terms of functionality, and some are designed for a more specific purpose than the more general array structure. All containers grow dynamically, negating the need for a declared length and memory management. Each of the containers is designed to be accessed in the most efficient way using different functions, but all containers support a standard set of iteration functions that allow you to access each element in the container.

The three major containers are the vector, the list, and the map. A vector is a collection made of contiguous memory, allowing for efficient access with a numeric index. A list is a collection where each element contains a value plus a pointer to the next value in the list, allowing for extremely efficient insertion into and removal from anywhere in the container. A map is a collection of key/value pairs, mapping a string index to a value.

We have also provided a stack and a queue, which are specialized containers with a more specific purpose in mind.

Stl containers can hold both string and numeric values, as well as references to either type. References are similar to pointers in C/C++ type languages, where the container element will actually "point to" the specified variable. That is, if you add a reference to a variable to a container, if that variable subsequently changes in your program, the value within the container will change as well.

Initialization

STL containers are defined in the declarative section, using a similar syntax to formats with some extra options. Containers can be declared empty, with an initial size (except maps), or with initial values. You must provide the name you will use to reference the container, as well as the type of container it will be.

<container-name>: <container-type>[(<size>)] [<value1>; <value2>; ...]

<container-name> (Required) Name used to reference this container in your program.

<container-type> (Required) One of the following: vector, list, map, stack, queue.

<size> (Optional) All containers except maps can be declared with an initial size. The container will initialize with the specified size, containing empty values for uninitialized values.

<values> (Optional) All containers can be declared with initial values, separated by semi-colons (';'). These values will be automatically inserted into the container at the beginning of the program, and the container's size will be accurately reflected. Maps require both a key and value, separated by a comma (','), for initialization.

General Usage

Vector

A vector is an indexable, sequence container that behaves like an array, but will grow as required. Like arrays, vectors store their data in contiguous memory, which is why access with a numeric index is so efficient, but unlike arrays you get all of the robust functionality of an STL container.

When a vector is created, it has an initial size (either declared in the program or a default specified by the library implementation). Reads/Writes in this space are all very efficient, until the vector fills up and a new value is added. When this happens, the vector automatically allocates another contiguous memory block, and copies the current values. This means that most of the time, adding to a vector is very efficient, but every once in a while this reallocation will take place. Note that a performance hit will only be noticeable on very large vectors.

List

A list is a sequence container in which each value points to the next value. This way, lists allow for fast insertion and deletion anywhere in the container, but do not allow for random access via an index like arrays/vectors.

Lists are implemented as doubly-linked lists, and since each value points to other values, the data does not need to be in contiguous storage like vectors. Thus unlike vectors, lists are more efficient for programs that require consistent insertion/removal functionality, as a vector will have to perform dynamic reallocation (described above) as its size changes. Lists can append elements indefinitely without the need for reallocation.

Map

A map is an associative container consisting of key/value pairs. A string index is "mapped" to the value specified, making the syntax similar to arrays and vectors.

Maps are designed for efficient access to values using their key, unlike sequence containers which are more efficient at accessing elements by their position (index). Keys are unique - that is there will never be two values associated with the same key.

Stack

Internally, stacks utilize deque (double-ended queue) containers to provide LIFO (Last In, First Out) access, which means that you are adding and removing elements at the "back" of the container. A stack should be used when the last element you added to the container is the first one you want back out again.

Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the container. Insertions/removals from the middle of the container are not as efficient as lists.

Queue

Internally, queues utilize deque (double-ended queue) containers to provide FIFO (First In, First Out) access, which means that you are adding elements at the "back" of the container, and removing them from the "front" of the container. A queue should be used when the first element you added is the first one you want back out again.

Deques are a sort of vector-list hybrid that allow for random access via an index (like arrays/vectors), and also allow for efficient addition/removal of elements at the beginning or end of the container. Insertions/removals from the middle of the container are not as efficient as lists.

Iteration

All STL Containers provide a standard iteration interface that allows you to step through each element in the collection. That is, using the same functions, you can iterate through any STL container. Think of iterating through a container as reading records from a file. First the iterator is initialized, then you can move it through the container one element at a time. At each position, you can read or write the element.

Unfortunately, due to the internal implementation of the STL containers, although you will iterate over every element in the collection, an order cannot be guaranteed. Also, if the container is modified during iteration, the iterator cannot be guaranteed to still be valid. If you modify the container during iteration, you must start the iteration process over in order to be sure every element is accessed.

In general iteration is used to aggregate all of the data within a container (calculate a total, average, etc), or maybe to see if a certain value exists within the collection.

IB Reference

Internet Basic function reference.

Personal tools