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

QCircularBuffer<QString> circ(200);

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

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

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

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

// 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

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

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().

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().

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().

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().

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).