- Qt 5.5
- Qt3D Module
- C++ Classes
- QCircularBuffer
- Qt 5.5.1 Reference Documentation

# QCircularBuffer Class

(Qt3D::QCircularBuffer)

A template class providing a dynamic circular array. More...

Header: | #include <Qt3D>
qmake: | QT += 3dcore

Note: All functions in this class are reentrant.

- List of all members, including inherited members

## Public Types

class | const_iterator
class | iterator
typedef | ArrayRange
typedef | ConstArrayRange
typedef | ConstIterator
typedef | Iterator
typedef | array_range
typedef | const_array_range
typedef | const_pointer
typedef | const_reference
typedef | const_reverse_iterator
typedef | difference_type
typedef | pointer
typedef | reference
typedef | reverse_iterator
typedef | size_type
typedef | value_type

## Public Functions

| QCircularBuffer()
| QCircularBuffer(int capacity)
| QCircularBuffer(int capacity, const T & value)
| QCircularBuffer(int capacity, int size, const T & value)
| QCircularBuffer(std::initializer_list<T> list)
| QCircularBuffer(ForwardIterator f, ForwardIterator l)
| QCircularBuffer(const QCircularBuffer<T> & other)
| ~QCircularBuffer()
void | append(const T & value)
const T & | at(int i) const
T & | back()
const T & | back() const
iterator | begin()
const_iterator | begin() const
int | capacity() const
const_iterator | cbegin() const
const_iterator | cend() const
void | clear()
const_iterator | constBegin() const
const_array_range | constData() const
const_array_range | constDataOne() const
const_array_range | constDataTwo() const
const_iterator | constEnd() const
bool | contains(const T & value) const
int | count(const T & value) const
int | count() const
const_reverse_iterator | crbegin() const
const_reverse_iterator | crend() const
array_range | data()
const_array_range | data() const
array_range | dataOne()
const_array_range | dataOne() const
array_range | dataTwo()
const_array_range | dataTwo() const
bool | empty() const
iterator | end()
const_iterator | end() const
bool | endsWith(const T & value) const
iterator | erase(const_iterator pos)
iterator | erase(const_iterator begin, const_iterator end)
QCircularBuffer<T> & | fill(const T & value, int size = -1)
T & | first()
const T & | first() const
int | freeSize() const
T & | front()
const T & | front() const
int | indexOf(const T & value, int from = 0) const
void | insert(int i, const T & value)
void | insert(int i, int count, const T & value)
iterator | insert(const_iterator before, int count, const T & value)
iterator | insert(const_iterator before, const T & value)
bool | isEmpty() const
bool | isFull() const
bool | isLinearised() const
bool | isSharedWith(const QCircularBuffer & other) const
T & | last()
const T & | last() const
int | lastIndexOf(const T & value, int from = -1) const
void | linearise()
int | max_size() const
void | pop_back()
void | pop_front()
void | prepend(const T & value)
void | push_back(const T & value)
void | push_front(const T & value)
reverse_iterator | rbegin()
const_reverse_iterator | rbegin() const
QAtomicInt | refCount() const
void | remove(int i)
void | remove(int i, int count)
reverse_iterator | rend()
const_reverse_iterator | rend() const
void | replace(int i, const T & value)
void | reserve(int capacity)
void | resize(int size)
void | setCapacity(int capacity)
int | size() const
int | sizeAvailable() const
void | squeeze()
bool | startsWith(const T & value) const
void | swap(QCircularBuffer & other)
QList<T> | toList() const
QVector<T> | toVector() const
T | value(int i) const
T | value(int i, const T & defaultValue) const
QCircularBuffer<T> & | operator+=(const T & other)
QCircularBuffer<T> & | operator+=(const QCircularBuffer<T> & other)
QCircularBuffer<T> & | operator+=(const QVector<T> & other)
QCircularBuffer<T> & | operator+=(const QList<T> & other)
QCircularBuffer<T> & | operator<<(const T & other)
QCircularBuffer<T> & | operator<<(const QCircularBuffer<T> & other)
QCircularBuffer<T> & | operator<<(const QVector<T> & other)
QCircularBuffer<T> & | operator<<(const QList<T> & other)
QCircularBuffer<T> & | operator=(const QCircularBuffer<T> & other)
T & | operator[](int i)
const T & | operator[](int i) const

## Static Public Members

QCircularBuffer<T> | fromList(const QList<T> & list)
QCircularBuffer<T> | fromVector(const QVector<T> & vector)

## Detailed Description

A template class providing a dynamic circular array.

QCircularBuffer<T> is one of Qt's generic container classes. It stores its items in adjacent memory locations and provides fast index-based access.

QCircularBuffer<T> provides similar functionality as QVector<T> and QList<T>, but behaves differently when adding items to a full QCircularBuffer. Whereas QVector<T> and QList<T> will both grow to accommodate the new items, QCircularBuffer<T> will overwrite the oldest items. This provides circular behavior to the container, and also means that it can maintain a flat memory profile.

QCircularBuffer<T> also offers performance gains over the other container classes when doing lots of appending or prepending to the buffer, such as in data logging applications. This is because appending (or prepending) an item does not require any extra memory to be allocated, unlike, for example, QVector<T> or QList<T>. Appending and prepending items to a QCircularBuffer<T> is an O(1) operation.

As with QVector<T>, items in QCircularBuffer<T> occupy adjacent positions in memory. However, the items may not be located in order in a single array. At times, the internal indices used to store the positions of the first and last items may wrap around as the QCircularBuffer<T> is modified. If the index of the last item is greater than the index of the first item, then the buffer is said to be non-linearized.

Here's an example of a QCircularBuffer that stores integers and a QCircularBuffer that stores QString values:

    QCircularBuffer<int> integerBuffer;
    QCircularBuffer<QString> stringBuffer;

The above examples create QCircularBuffer objects with a capacity of 0. The capacity is the number of items that can be stored in a QCircularBuffer. The size of a QCircularBuffer object is the number of items that actually are stored in it. Here's an example of creating a QCircularBuffer with a capacity for 200 elements and a size of 0:

    QCircularBuffer<QString> circ(200);

By default the QCircularBuffer is empty. If you want to create a circular buffer with unused capacity, pass a size argument to the constructor.

    QCircularBuffer<QString> circ(200, "Pass");

If you wish to fill a subset of the QCircularBuffer with a default value, then you should also pass a size argument to the constructor. The following example creates a QCircularBuffer with a capacity for 200 QString items, and initializes the first 50 of them to the value "Qt":

    QCircularBuffer<QString> circ(200, 50, "Qt");

You can also call fill() at any time to fill the QCircularBuffer with a value.

QCircularBuffer uses 0-based indexes, just like C++ arrays. To access the item at a particular index position, you can use operator[]. On non-const buffers, operator[] returns a reference to the item that can be used on the left side of an assignment:

    if (circ[0] == "Izzie")
      circ[0] = "Elizabeth";

For read-only access, an alternative syntax is to use at():

    for (int i = 0; i < circ.size(); ++i) {
      if (circ.at(i) == "Jack")
        cout << "Found Jack at position " << i << endl;
     }

at() can be faster than operator[], because it never causes a deep copy to occur.

Another way to access the data stored in a QCircularBuffer is to call data(), or dataOne() and dataTwo() depending on if the buffer is linearized or not. See the discussion in isLinearised() for more information. The data() function returns a Qt3D::QCircularBuffer::array_range object describing the array of items stored in the QCircularBuffer. You can use the pointer in the array_range to directly access and modify the elements stored in the circular buffer. The pointer is also useful if you need to pass a QCircularBuffer to a function that accepts a plain C++ array.

If the circular buffer is non-linearized, the data() function will linearize it before returning. This can be an expensive operation for large buffers. To avoid this cost, QCircularBuffer also provides alternative methods called dataOne() and dataTwo() that return pointers to the two contiguous arrays used to represent the buffer. dataOne() returns a pointer to the earlier (or oldest) items, and dataTwo() returns a pointer to the later (or newer) items. The dataOne() and dataTwo() functions never cause the circular buffer to be linearized.

If you wish to pass a C++ array to a function and that function is expensive to call, then you may wish to use the data() method so that you only need to call your expensive function once. If your function is cheap and you have a large circular buffer (so that linearizing it is expensive), then you may wish to use dataOne() and dataTwo() and call your function twice.

Here is a simple example that shows the semantics of how QCircularBuffer operates:

    // Create a circular buffer with capacity for 3 integers
    QCircularBuffer<int> circ(3);

    // Insert some items into the buffer
    circ.append( 1 );
    circ.append( 2 );
    circ.append( 3 );

    for (int i = 0; i < circ.size(); ++i) {
      cout << circ.at(i) << endl;
     } // Prints out 1 2 3

    // The circular buffer is now full. Appending subsequent items
    // will overwrite the oldest items:
    circ.append(4); // Overwrite 1 with 4
    circ.append(5); // Overwrite 2 with 5

    // The buffer now contains 3, 4 and 5

    for (int i = 0; i < circ.size(); ++i) {
      cout << circ.at(i) << endl;
     } // Prints out 3 4 5

Notice how appending items to a full buffer overwrites the earliest items.

If you want to find all occurrences of a particular value in a circular buffer, use indexOf() or lastIndexOf(). The former searches forward starting from a given index position, the latter searches backward. Both return the index of the matching item if they found one; otherwise, they return -1. For example:

    int i = circ.indexOf("Tom");
    if (i != -1)
      cout << "First occurrence of Tom is at position " << i << endl;

If you simply want to check whether a circular buffer contains a particular value, use contains(). If you want to find out how many times a particular value occurs in the circular buffer, use count().

QCircularBuffer provides these basic functions to add, move, and remove items: insert(), replace(), remove(), prepend(), append(). The insert() and remove() functions can be slow (linear time) for large circular buffers, because they require moving many items in the circular buffer by one or more positions in memory. The implementation does however take care to minimize the number of items that need to be moved. In the extreme worst case for insert() and remove(), half of the items will be moved in memory. QCircularBuffer also takes care to move items around using the best method available for the type being stored. If your type is movable, then it is best to tell Qt about this by using the Q_DECLARE_TYPEINFO() macro. In such cases memory moves are performed using memmove() rather than calling the copy constructor for each item. If you want a container class that always provides fast insertion/removal in the middle, use QList or QLinkedList instead.

Unlike plain C++ arrays, QCircularBuffers can be resized at any time by calling resize() or setCapacity(). The resize() function can only allocate items up to the number specified by capacity(). If you wish to alter the capacity of the CircularBuffer, then use setCapacity(). This can be slow as new memory needs to be allocated. It is most common to specify the capacity of the circular buffer in the constructor or immediately after construction, and then simply keep appending to the buffer. If you wish to reclaim any unused memory from the circular buffer, then call squeeze(). This is equivalent to calling setCapacity( size() ).

Note that using non-const operators and functions can cause QCircularBuffer to do a deep copy of the data. This is due to implicit sharing.

QCircularBuffer's value type must be an assignable data type. This covers most data types that are commonly used, but the compiler won't let you, for example, store a QWidget as a value; instead, store a QWidget *. Some functions have additional requirements; for example, indexOf() and lastIndexOf() expect the value type to support `operator==()`. These requirements are documented on a per-function basis.

QCircularBuffer provides STL-Style Iterators (const_iterator) and iterator). In practice, these are rarely used, because you can use indexes into the QCircularBuffer.

QCircularBuffer does not support inserting, prepending, appending, or replacing with references to its own values. Doing so will cause your application to abort with an error message.

See also Qt3D::QCircularBuffer::iterator, Qt3D::QCircularBuffer::const_iterator, QVector, QList, and QLinkedList.

## Member Type Documentation

### typedef QCircularBuffer::ArrayRange

Qt-style synonym for Qt3D::QCircularBuffer::array_range.

### typedef QCircularBuffer::ConstArrayRange

Qt-style synonym for Qt3D::QCircularBuffer::const_array_range.

### typedef QCircularBuffer::ConstIterator

Qt-style synonym for Qt3D::QCircularBuffer::const_iterator.

### typedef QCircularBuffer::Iterator

Qt-style synonym for Qt3D::QCircularBuffer::iterator.

### typedef QCircularBuffer::array_range

Typedef for QPair<T*,int>. The first element is a pointer to the first element of an array of T. The second element is the number of elements in the array.

See also data(), dataOne(), and dataTwo().

### typedef QCircularBuffer::const_array_range

Typedef for QPair<const T*,int>. The first element is a pointer to the first element of an array of const T. The second element is the number of elements in the array.

### typedef QCircularBuffer::const_pointer

Typedef for const T *. Provided for STL compatibility.

### typedef QCircularBuffer::const_reference

Typedef for T &. Provided for STL compatibility.

### typedef QCircularBuffer::const_reverse_iterator

### typedef QCircularBuffer::difference_type

Typedef for ptrdiff_t. Provided for STL compatibility.

### typedef QCircularBuffer::pointer

Typedef for T *. Provided for STL compatibility.

### typedef QCircularBuffer::reference

Typedef for T &. Provided for STL compatibility.

### typedef QCircularBuffer::reverse_iterator

### typedef QCircularBuffer::size_type

Typedef for int. Provided for STL compatibility.

### typedef QCircularBuffer::value_type

Typedef for T. Provided for STL compatibility.

## Member Function Documentation

### QCircularBuffer::QCircularBuffer()

Constructs an empty circular buffer with zero capacity.

See also resize() and setCapacity().

### QCircularBuffer::QCircularBuffer(int capacity)

Constructs an empty circular buffer with an initial capacity of capacity elements.

See also resize() and setCapacity().

### QCircularBuffer::QCircularBuffer(int capacity, const T & value)

Constructs a circular buffer with an initial capacity and size of capacity elements.

The elements are initialized to value.

See also resize(), setCapacity(), and fill().

### QCircularBuffer::QCircularBuffer(int capacity, int size, const T & value)

Constructs a circular buffer with an initial capacity of capacity elements and initial size of size elements.

The first size elements are initialized to value.

See also resize(), setCapacity(), and fill().

### QCircularBuffer::QCircularBuffer(std::initializer_list<T> list)

### QCircularBuffer::QCircularBuffer(ForwardIterator f, ForwardIterator l)

### QCircularBuffer::QCircularBuffer(const QCircularBuffer<T> & other)

Constructs a copy of other.

This operation takes constant time, because QCircularBuffer is implicitly shared. This makes returning a QCircularBuffer from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takes linear time.

See also operator=().

### QCircularBuffer::~QCircularBuffer()

Destroys the circular buffer.

### void QCircularBuffer::append(const T & value)

Inserts value at the end of the circular buffer. If the circular buffer is full, then the oldest element is overwritten.

Example:

    QCircularBuffer<QString> circ(3);
    circ.append("one");
    circ.append("two");
    circ.append("three");
    // circ: ["one", "two", "three"]

    circ.append("four");
    // circ: ["two", "three", "four"]

    circ.append("five");
    // circ: ["three", "four", "five"]

    circ.append("six");
    // circ: ["four", "five", "six"]

This operation is very fast, because QCircularBuffer never allocates memory in this function.

See also operator<<(), operator+=(), prepend(), and insert().

### const T & QCircularBuffer::at(int i) const

Returns the item at index position i in the circular buffer.

i must be a valid index position in the circular buffer (i.e., 0 <= i < size()).

See also value() and operator[]().

### T & QCircularBuffer::back()

This function is provided for STL compatibility. It is equivalent to last().

### const T & QCircularBuffer::back() const

This is an overloaded function.

### iterator QCircularBuffer::begin()

Returns an STL-style iterator pointing to the first item in the circular buffer.

See also constBegin() and end().

### const_iterator QCircularBuffer::begin() const

This is an overloaded function.

### int QCircularBuffer::capacity() const

Returns the maximum number of elements that can be stored in the circular buffer.

See also setCapacity() and size().

### const_iterator QCircularBuffer::cbegin() const

### const_iterator QCircularBuffer::cend() const

### void QCircularBuffer::clear()

Removes all elements from the circular buffer so that the size is zero. The capacity is unchanged.

See also isEmpty().

### const_iterator QCircularBuffer::constBegin() const

Returns a const STL-style iterator pointing to the first item in the circular buffer.

See also begin() and constEnd().

### const_array_range QCircularBuffer::constData() const

Returns a Qt3D::QCircularBuffer::const_array_range describing the internal array of data.

If the circular buffer is non-linearized then the pointer and array size returned will both be 0 since linearising the circular buffer would break constness.

If the circular buffer is empty then the pointer and array size returned will both be 0.

See also data(), constDataOne(), constDataTwo(), and isLinearised().

### const_array_range QCircularBuffer::constDataOne() const

Returns a Qt3D::QCircularBuffer::const_array_range describing the first internal array of contiguous data. If the circular buffer is linearized, then this function is equivalent to calling constData(). If the circular buffer is non-linearized, then the returned array range will describe a subset of the data contained in the circular buffer. This subset will consist of the earliest (lowest index) items in the buffer. To obtain a Qt3D::QCircularBuffer::const_array_range for the remainder of the data, use the constDataTwo() function.

If the circular buffer is empty, then the pointer and array size returned will both be 0.

See also dataOne(), constDataTwo(), constData(), and isLinearised().

### const_array_range QCircularBuffer::constDataTwo() const

Returns a Qt3D::QCircularBuffer::const_array_range describing the first internal array of contiguous data. If the circular buffer is linearized, then the pointer and array size returned will both be 0 since all the data will be contained in the array described by calling the dataOne() function.

See also constDataOne(), dataTwo(), constData(), and isLinearised().

### const_iterator QCircularBuffer::constEnd() const

Returns a const STL-style iterator pointing to the imaginary item after the last item in the circular buffer.

See also constBegin() and end().

### bool QCircularBuffer::contains(const T & value) const

Returns true if the circular buffer contains an occurrence of value; otherwise returns false.

This function requires the value type to have an implementation of `operator==()`.

See also indexOf() and count().

### int QCircularBuffer::count(const T & value) const

Returns the number of occurrences of value in the circular buffer.

This function requires the value type to have an implementation of `operator==()`.

See also contains() and indexOf().

### int QCircularBuffer::count() const

This is an overloaded function.

Same as size().

### const_reverse_iterator QCircularBuffer::crbegin() const

### const_reverse_iterator QCircularBuffer::crend() const

### array_range QCircularBuffer::data()

Returns a Qt3D::QCircularBuffer::array_range describing the internal array of data. If the circular buffer is non-linearized, then this function causes it to be linearized. If the cost of linearisation is too high for your use case, then you should consider using the dataOne() and dataTwo() functions instead.

If the circular buffer is empty then the pointer and array size returned will both be 0.

See also constData(), dataOne(), dataTwo(), and isLinearised().

### const_array_range QCircularBuffer::data() const

This is an overloaded function.

If the circular buffer is non-linearized then the pointer and array size returned will both be 0 since linearising the circular buffer would break constness.

### array_range QCircularBuffer::dataOne()

Returns a Qt3D::QCircularBuffer::array_range describing the first internal array of contiguous data. If the circular buffer is linearized, then this function is equivalent to calling data(). If the circular buffer is non-linearized then the returned array range will describe a subset of the data contained in the circular buffer. This subset will consist of the earliest (lowest index) items in the buffer. To obtain a Qt3D::QCircularBuffer::array_range for the remainder of the data, use the dataTwo() function.

If the circular buffer is empty, then the pointer and array size returned will both be 0.

See also constDataOne(), dataTwo(), data(), and isLinearised().

### const_array_range QCircularBuffer::dataOne() const

This is an overloaded function.

Unlike data() this function always returns a valid Qt3D::QCircularBuffer::const_array_range (unless the circular buffer is empty).

### array_range QCircularBuffer::dataTwo()

Returns a Qt3D::QCircularBuffer::array_range describing the first internal array of contiguous data. If the circular buffer is linearized, then the pointer and array size returned will both be 0 since all the data will be contained in the array described by calling the dataOne() function.

See also dataOne(), constDataTwo(), data(), and isLinearised().

### const_array_range QCircularBuffer::dataTwo() const

This is an overloaded function.

### bool QCircularBuffer::empty() const

This function is provided for STL compatibility. It is equivalent to isEmpty(), returning true if the circular buffer is empty; otherwise returns false.

### iterator QCircularBuffer::end()

Returns an STL-style iterator pointing to the imaginary item after the last item in the circular buffer.

See also begin() and constEnd().

### const_iterator QCircularBuffer::end() const

This is an overloaded function.

### bool QCircularBuffer::endsWith(const T & value) const

Returns true if this circular buffer is not empty and its last item is equal to value; otherwise returns false.

See also isEmpty(), last(), and startsWith().

### iterator QCircularBuffer::erase(const_iterator pos)

Removes the item pointed to by the iterator pos from the circular buffer, and returns an iterator to the next item in the circular buffer (which may be end()).

See also insert() and remove().

### iterator QCircularBuffer::erase(const_iterator begin, const_iterator end)

This is an overloaded function.

Removes all the items from begin up to (but not including) end. Returns an iterator to the same item that end referred to before the call.

### QCircularBuffer<T> & QCircularBuffer::fill(const T & value, int size = -1)

Assigns value to all items in the circular buffer. If size is different from -1 (the default), the circular buffer is resized to size size beforehand (size must be less than or equal to the capacity).

This function also linearizes the circular buffer.

Example:

    QCircularBuffer<QString> circ(3, 3, "No");
    circ.fill("Yes");
    // circ: ["Yes", "Yes", "Yes"]

    circ.fill("oh", 5);
    // circ: ["oh", "oh", "oh", "oh", "oh"]

See also resize().

### T & QCircularBuffer::first()

Returns a reference to the first item in the circular buffer. This function assumes that the circular buffer isn't empty.

See also last() and isEmpty().

### const T & QCircularBuffer::first() const

This is an overloaded function.

### int QCircularBuffer::freeSize() const

Returns the number of items that can be added to the circular buffer without causing the earliest item to be overwritten. It is equivalent to (capacity() - size()).

See also sizeAvailable(), capacity(), isEmpty(), isFull(), and size().

### `[static]` QCircularBuffer<T> QCircularBuffer::fromList(const QList<T> & list)

Returns a QCircularBuffer object with the data contained in list. The capacity and size of the circular buffer will be equal to the size of list.

Example:

    QStringList list;
    list << "Sven" << "Kim" << "Ola";

    QCircularBuffer<QString> circ = QCircularBuffer<QString>::fromList(list);
    // circ: ["Sven", "Kim", "Ola"]

See also fromVector(), toList(), and toVector().

### `[static]` QCircularBuffer<T> QCircularBuffer::fromVector(const QVector<T> & vector)

Returns a QCircularBuffer object with the data contained in vector. The capacity and size of the circular buffer will be equal to the size of vector.

See also fromList(), toVector(), and toList().

### T & QCircularBuffer::front()

This function is provided for STL compatibility. It is equivalent to first().

### const T & QCircularBuffer::front() const

This is an overloaded function.

### int QCircularBuffer::indexOf(const T & value, int from = 0) const

Returns the index position of the first occurrence of value in the circular buffer, searching forward from index position from. Returns -1 if no item matched.

Example:

    QCircularBuffer<QString> circ(5);
    circ << "A" << "B" << "C" << "B" << "A";
    circ.indexOf("B");            // returns 1
    circ.indexOf("B", 1);         // returns 1
    circ.indexOf("B", 2);         // returns 3
    circ.indexOf("X");            // returns -1

This function requires the value type to have an implementation of `operator==()`.

See also lastIndexOf() and contains().

### void QCircularBuffer::insert(int i, const T & value)

Inserts value at index position i in the circular buffer. If i is 0, the value is prepended to the circular buffer. If i is size(), the value is appended to the circular buffer. The capacity of the circular buffer is not changed.

Example:

    QCircularBuffer<QString> circ(5);
    circ << "alpha" << "beta" << "delta";
    circ.insert(2, "gamma");
    // circ: ["alpha", "beta", "gamma", "delta"]

Using this function is equivalent to calling insert(i, 1, value). See the discussion there for more information.

Items at indexes i and higher are shifted along by one. If the circular buffer is full then the earliest item will be overwritten. Note that this has the non-obvious behavior that calling insert(0,value) on a circular buffer that is already full will effectively do nothing since the newly prepended item will immediately be overwritten by the highest item as it is shifted along one position.

For large circular buffers, this operation can be slow (linear time), because it requires moving all the items at indexes i and above (or all items below index i depending upon where in the circular buffer the new item is inserted) by one position in memory. If you want a container class that provides a fast insert() function, use QLinkedList instead.

If the capacity() is zero, then nothing will be inserted.

See also append(), prepend(), and remove().

### void QCircularBuffer::insert(int i, int count, const T & value)

This is an overloaded function.

Inserts value at index position i in the circular buffer. If i is 0, the value is prepended to the circular buffer. If i is size(), the value is appended to the circular buffer. The capacity of the circular buffer is not changed.

Items at indexes i and higher are shifted along by one. If the circular buffer has freeSize() < count, then the earliest items will be overwritten.

The actual number of items that get inserted may not always be equal to count since this function preserves the capacity of the circular buffer, and since items at indexes i and higher are shifted along by one. The actual number of items inserted is min(count, i + freeSize()).

For the same reasons, the number of items that get overwritten at the start of the circular buffer is min(i, max(0, count - freeSize())).

Example:

    QCircularBuffer<int> circ(6);
    circ << 1 << 2 << 3 << 4; // circ: [1, 2, 3, 4]
    circ.insert(2, 5, 0);
    // circ: [0, 0, 0, 0, 3, 4]

For large circular buffers, this operation can be slow (linear time), because it requires moving all the items at indexes i and above (or all items below index i depending upon where in the circular buffer the new item is inserted) in memory. If you want a container class that provides a fast insert() function, use QLinkedList instead.

If the capacity() is zero, then nothing will be inserted.

See also append(), prepend(), and remove().

### iterator QCircularBuffer::insert(const_iterator before, int count, const T & value)

This is an overloaded function.

Inserts up to count items with value value in front of the item pointed to by the iterator before in the circular buffer. Returns an iterator pointing at the first of the inserted items.

See also append(), prepend(), and remove().

### iterator QCircularBuffer::insert(const_iterator before, const T & value)

This is an overloaded function.

Inserts value in front of the item pointed to by the iterator before. Returns an iterator pointing at the inserted item.

See also append(), prepend(), and remove().

### bool QCircularBuffer::isEmpty() const

Returns true if the circular buffer has size 0; otherwise returns false.

See also capacity(), resize(), setCapacity(), and size().

### bool QCircularBuffer::isFull() const

Returns true if the circular buffer is full ie if size() == capacity(); otherwise returns false.

See also capacity(), resize(), setCapacity(), and size().

### bool QCircularBuffer::isLinearised() const

Returns true if the circular buffer is linearized; otherwise returns false.

A circular buffer is said to be linearized if the position of the first item in the internal array occurs before the position of the last item. A little more explanation is provided for clarification.

Internally, QCircularBuffer stores the items in a plain C++ array. Additionally, the positions in the array of the first and last items of the circular buffer are also stored (along with the capacity and size).

Imagine a circular buffer of capacity 6 created and populated with the following code:

    QCircularBuffer<int> circ(6);
    circ << 1 << 2 << 3 << 4 << 5;
    // circ: [1, 2, 3, 4, 5]

After executing the above code, the internal state of the circular buffer would look like this:

As you can see, the internal array has been populated from the beginning. The first item is located as position 0 in the array and the last item is located at position 4 in the array. The circular buffer is linearized because the last item occurs later in the array than the first item.

If we now append another item to the circular buffer with:

    circ.append(6);
    // circ: [1, 2, 3, 4, 5, 6]

the internal representation then becomes:

The circular buffer is still linearized, but it is now full. Appending further items will cause the oldest item to be overwritten. For example,

    circ.append(7);
    // circ: [2, 3, 4, 5, 6, 7]

causes the internal representation to become:

We see that the oldest item (1) has been overwritten by the newest item (7), and that the first and last indexes have been adjusted accordingly. The circular buffer is now said to be non-linearized because the position of the last item is before the position of the first item.

The circular buffer can always be linearized by calling the linearise() function. This can be an expensive operation (linear time) for large circular buffers since new memory has to be allocated, the items copied across, and the original memory deallocated.

If you need to directly access the items stored in a circular buffer, (perhaps for a plain C++ function call) then you can use the data() function. If the circular buffer is non-linearized, then the data() function will linearize it for you before returning a Qt3D::QCircularBuffer::array_range describing the array.

To prevent the cost of the linearisation process, you can instead call the dataOne() and dataTwo() functions to obtain the two arrays used to represent a non-linearized circular buffer. After running the above sample code, calling the dataOne() function would return an array_range object describing the values 2-6, and the dataTwo() function would return an array_range object describing the value 7. Sometimes, accessing the items via the two arrays described by dataOne() and dataTwo(), can be quicker than calling data() and having the circular buffer linearized. The dataOne() and dataTwo() functions do not trigger a linearization.

See also linearise(), data(), dataOne(), and dataTwo().

### bool QCircularBuffer::isSharedWith(const QCircularBuffer & other) const

### T & QCircularBuffer::last()

Returns a reference to the last item in the circular buffer. This function assumes that the circular buffer isn't empty.

See also first() and isEmpty().

### const T & QCircularBuffer::last() const

This is an overloaded function.

### int QCircularBuffer::lastIndexOf(const T & value, int from = -1) const

Returns the index position of the last occurrence of the value value in the circular buffer, searching backward from index position from. If from is -1 (the default), the search starts at the last item. Returns -1 if no item is matched.

Example:

    QCircularBuffer<QString> circ;
    circ << "A" << "B" << "C" << "B" << "A";
    circ.lastIndexOf("B");        // returns 3
    circ.lastIndexOf("B", 3);     // returns 3
    circ.lastIndexOf("B", 2);     // returns 1
    circ.lastIndexOf("X");        // returns -1

This function requires the value type to have an implementation of `operator==()`.

See also indexOf().

### void QCircularBuffer::linearise()

Linearizes the internal representation of the circular buffer such that all items are stored in a single contiguous array.

This function can be expensive for large circular buffers (linear time).

See also isLinearised().

### int QCircularBuffer::max_size() const

### void QCircularBuffer::pop_back()

This function is provided for STL compatibility. It is equivalent to erase(end() - 1).

### void QCircularBuffer::pop_front()

This function is provided for STL compatibility. It is equivalent to erase(begin()).

### void QCircularBuffer::prepend(const T & value)

Inserts value at the beginning of the circular buffer. If the circular buffer is full, then the highest index item is overwritten.

Example:

    QCircularBuffer<QString> circ(3);
    circ.prepend("one");
    circ.prepend("two");
    circ.prepend("three");
    // circ: ["three", "two", "one"]

    circ.prepend("four");
    // circ: ["four", "three", "two"]

This operation is very fast, because QCircularBuffer never allocates memory in this function.

See also operator<<(), operator+=(), append(), and insert().

### void QCircularBuffer::push_back(const T & value)

This function is provided for STL compatibility. It is equivalent to append(value).

### void QCircularBuffer::push_front(const T & value)

This function is provided for STL compatibility. It is equivalent to prepend(value).

### reverse_iterator QCircularBuffer::rbegin()

### const_reverse_iterator QCircularBuffer::rbegin() const

### QAtomicInt QCircularBuffer::refCount() const

Returns the number of shallow copies that exist of this circular buffer.

### void QCircularBuffer::remove(int i)

Removes the element at index position i.

See also insert(), replace(), and fill().

### void QCircularBuffer::remove(int i, int count)

This is an overloaded function.

Removes count elements from the middle of the circular buffer, starting at index position i.

See also insert(), replace(), and fill().

### reverse_iterator QCircularBuffer::rend()

### const_reverse_iterator QCircularBuffer::rend() const

### void QCircularBuffer::replace(int i, const T & value)

Replaces the item at index position i with value.

i must be a valid index position in the circular buffer (i.e., 0 <= i < size()).

See also operator[]() and remove().

### void QCircularBuffer::reserve(int capacity)

Sets the capacity of the circular buffer to capacity. It is a synonym for setCapacity().

See also setCapacity().

### void QCircularBuffer::resize(int size)

Changes the size of the circular buffer to size which must be > 0 and <= capacity(). If size is less than the old size, then the highest indexed items are removed. If size is greater than the old size, then new items with a default-constructed value are appended to the end of the circular buffer.

See also size(), insert(), remove(), capacity(), and setCapacity().

### void QCircularBuffer::setCapacity(int capacity)

Sets the capacity of the circular buffer to capacity.

See also reserve() and capacity().

### int QCircularBuffer::size() const

Returns the number of items in the circular buffer.

See also sizeAvailable(), capacity(), and resize().

### int QCircularBuffer::sizeAvailable() const

Returns the number of items that can be added to the circular buffer without causing the earliest item to be overwritten. It is equivalent to (capacity() - size()).

See also capacity(), isEmpty(), isFull(), size(), and freeSize().

### void QCircularBuffer::squeeze()

Releases any unused memory from the circular buffer. It is equivalent to calling setCapacity(size()).

See also setCapacity(), size(), resize(), and sizeAvailable().

### bool QCircularBuffer::startsWith(const T & value) const

Returns true if the circular buffer is not empty and its first item is equal to value; otherwise returns false.

See also isEmpty(), first(), and endsWith().

### void QCircularBuffer::swap(QCircularBuffer & other)

### QList<T> QCircularBuffer::toList() const

Returns a QList object with the data contained in this QCircularBuffer.

Example:

    QCircularBuffer<QString> circ;
    circ << "red" << "green" << "blue" << "black";

    QList<QString> list = circ.toList();
    // list: ["red", "green", "blue", "black"]

See also fromList() and toVector().

### QVector<T> QCircularBuffer::toVector() const

Returns a QVector object with the data contained in this QCircularBuffer.

See also fromVector() and toList().

### T QCircularBuffer::value(int i) const

Returns the value at index position i in the circular buffer.

If the index i is out of bounds, the function returns a default-constructed value. If you are certain that i is within bounds, you can use at() instead, which is slightly faster.

See also at() and operator[]().

### T QCircularBuffer::value(int i, const T & defaultValue) const

This is an overloaded function.

If the index i is out of bounds, the function returns defaultValue.

### QCircularBuffer<T> & QCircularBuffer::operator+=(const T & other)

Appends the item other to this circular buffer and returns a reference to this circular buffer.

See also operator+(), operator<<(), and append().

### QCircularBuffer<T> & QCircularBuffer::operator+=(const QCircularBuffer<T> & other)

This is an overloaded function.

Appends the items of the other circular buffer to this circular buffer and returns a reference to this circular buffer.

See also operator+(), operator<<(), and append().

### QCircularBuffer<T> & QCircularBuffer::operator+=(const QVector<T> & other)

This is an overloaded function.

### QCircularBuffer<T> & QCircularBuffer::operator+=(const QList<T> & other)

This is an overloaded function.

### QCircularBuffer<T> & QCircularBuffer::operator<<(const T & other)

Appends the item other to this circular buffer and returns a reference to this circular buffer.

See also operator+(), operator+=(), and append().

### QCircularBuffer<T> & QCircularBuffer::operator<<(const QCircularBuffer<T> & other)

This is an overloaded function.

Appends the items of the other circular buffer to this circular buffer and returns a reference to this circular buffer.

See also operator+(), operator+=(), and append().

### QCircularBuffer<T> & QCircularBuffer::operator<<(const QVector<T> & other)

This is an overloaded function.

### QCircularBuffer<T> & QCircularBuffer::operator<<(const QList<T> & other)

This is an overloaded function.

### QCircularBuffer<T> & QCircularBuffer::operator=(const QCircularBuffer<T> & other)

Assigns other to this circular buffer and returns a reference to this circular buffer.

### T & QCircularBuffer::operator[](int i)

Returns the item at index position i as a modifiable reference.

i must be a valid index position in the circular buffer (i.e., 0 <= i < size()).

Note that using non-const operators can cause QCircularBuffer to do a deep copy.

See also at() and value().

### const T & QCircularBuffer::operator[](int i) const

This is an overloaded function.

Same as at(i).