/****************************************************************************
**
** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB).
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/* !\internal
    \class Qt3DCore::QCircularBuffer
    \inmodule Qt3DCore
    \brief A template class providing a dynamic circular array.

    \ingroup tools
    \ingroup shared

    \reentrant

    QCircularBuffer\<T\> is one of Qt's generic \l{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:

    \snippet code/src_core_qcircularbuffer.cpp 0

    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:

    \snippet code/src_core_qcircularbuffer.cpp 1

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

    \snippet code/src_core_qcircularbuffer.cpp 2

    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":

    \snippet code/src_core_qcircularbuffer.cpp 3

    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 \l{operator[]()}{operator[]}. On
    non-const buffers, \l{operator[]()}{operator[]} returns a reference to the item
    that can be used on the left side of an assignment:

    \snippet code/src_core_qcircularbuffer.cpp 4

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

    \snippet code/src_core_qcircularbuffer.cpp 5

    at() can be faster than \l{operator[]()}{operator[]}, because it never causes
    a \l{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 an \l 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:

    \snippet code/src_core_qcircularbuffer.cpp 6

    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:

    \snippet code/src_core_qcircularbuffer.cpp 7

    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 (\l{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 \l {setCapacity()}{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
    \l{implicit sharing}.

    QCircularBuffer's value type must be an \l{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 \c operator==().  These requirements are documented on a
    per-function basis.

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

    QCircularBuffer does \e 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.

    \sa iterator, const_iterator, QVector, QList, QLinkedList
*/

/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer()

    Constructs an empty circular buffer with zero capacity.

    \sa resize(), setCapacity()
*/

/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity)

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

    \sa resize(), setCapacity()
*/

/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity, const T &value)

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

    The elements are initialized to \a value.

    \sa resize(), setCapacity(), fill()
*/

/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity, int size, const T &value)

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

    The first \a size elements are initialized to \a value.

    \sa resize(), setCapacity(), fill()
*/

/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(const QCircularBuffer<T> &other)

    Constructs a copy of \a other.

    This operation takes \l{constant time}, because QCircularBuffer is
    \l{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 \l{linear time}.

    \sa operator=()
*/

/* \fn Qt3DCore::QCircularBuffer::~QCircularBuffer()

    Destroys the circular buffer.
*/

/* \fn QCircularBuffer &Qt3DCore::QCircularBuffer::operator=(const QCircularBuffer<T> &other)

    Assigns \a other to this circular buffer and returns a reference to this
    circular buffer.
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::begin()

    Returns an \l{STL-Style iterators}{STL-style iterator} pointing to the first item in
    the circular buffer.

    \sa constBegin(), end()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::begin() const

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::constBegin() const

    Returns a const \l{STL-Style Iterators}{STL-style iterator} pointing to the first item in
    the circular buffer.

    \sa begin(), constEnd()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::end()

    Returns an \l {STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
    after the last item in the circular buffer.

    \sa begin(), constEnd()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::end() const

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::constEnd() const

    Returns a const \l{STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
    after the last item in the circular buffer.

    \sa constBegin(), end()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::erase(const_iterator pos)

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

    \sa insert(), remove()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::erase(const_iterator begin, const_iterator end)

    \overload

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

/* \fn void Qt3DCore::QCircularBuffer::push_back(const T &value)

    This function is provided for STL compatibility. It is equivalent
    to append(\a value).
*/

/* \fn void Qt3DCore::QCircularBuffer::push_front(const T &value)

    This function is provided for STL compatibility. It is equivalent
    to prepend(\a value).
*/

/* \fn void Qt3DCore::QCircularBuffer::pop_back()

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

/* \fn void Qt3DCore::QCircularBuffer::pop_front()

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

/* \fn bool Qt3DCore::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.
*/

/* \fn Qt3DCore::QCircularBuffer::reference Qt3DCore::QCircularBuffer::front()

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

/* \fn Qt3DCore::QCircularBuffer::const_reference Qt3DCore::QCircularBuffer::front() const

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer::reference Qt3DCore::QCircularBuffer::back()

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

/* \fn Qt3DCore::QCircularBuffer::const_reference Qt3DCore::QCircularBuffer::back() const

    \overload
*/

/* \fn int Qt3DCore::QCircularBuffer::refCount() const

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

/* \fn Qt3DCore::QCircularBuffer::append(const T &value)

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 8

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

    \sa operator<<(), operator+=(), prepend(), insert()
*/

/* \fn const T &Qt3DCore::QCircularBuffer::at(int i) const

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

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

    \sa value(), operator[]()
*/

/* \fn T &Qt3DCore::QCircularBuffer::operator[](int i)

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

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

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

    \sa at(), value()
*/

/* \fn const T &Qt3DCore::QCircularBuffer::operator[](int i) const

    \overload

    Same as at(\a i).
*/

/* \fn int Qt3DCore::QCircularBuffer::capacity() const

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

    \sa setCapacity(), size()
*/

/* \fn void Qt3DCore::QCircularBuffer::clear()

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

    \sa isEmpty()
*/

/* \fn bool Qt3DCore::QCircularBuffer::contains(const T &value) const

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

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

    \sa indexOf(), count()
*/

/* \fn int Qt3DCore::QCircularBuffer::count(const T &value) const

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

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

    \sa contains(), indexOf()
*/

/* \fn int Qt3DCore::QCircularBuffer::count() const

    \overload

    Same as size().
*/

/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::data()

    Returns an \l 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.

    \sa constData(), dataOne(), dataTwo(), isLinearised()
*/

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::data() const

    \overload

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

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constData() const

    Returns a \l 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.

    \sa data(), constDataOne(), constDataTwo(), isLinearised()
*/

/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::dataOne()

    Returns an \l 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 an \l 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.

    \sa constDataOne(), dataTwo(), data(), isLinearised()
*/

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::dataOne() const

    \overload

    Unlike data(), this function always returns a valid \l const_array_range
    (unless the circular buffer is empty).
*/

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constDataOne() const

    Returns a \l 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 \l 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.

    \sa dataOne(), constDataTwo(), constData(), isLinearised()
*/

/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::dataTwo()

    Returns an \l 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.

    \sa dataOne(), constDataTwo(), data(), isLinearised()
*/

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::dataTwo() const

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constDataTwo() const

    Returns a \l 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.

    \sa constDataOne(), dataTwo(), constData(), isLinearised()
*/

/* \fn bool Qt3DCore::QCircularBuffer::endsWith(const T &value) const

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

    \sa isEmpty(), last(), startsWith()
*/

/* \fn QCircularBuffer<T>& Qt3DCore::QCircularBuffer::fill(const T &value, int size = -1)

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

    This function also linearizes the circular buffer.

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 14

    \sa resize()
*/

/* \fn T &Qt3DCore::QCircularBuffer::first()

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

    \sa last(), isEmpty()
*/

/* \fn const T &Qt3DCore::QCircularBuffer::first() const

    \overload
*/

/* \fn int Qt3DCore::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()).

    \sa sizeAvailable(), capacity(), isEmpty(), isFull(), size()
*/

/* \fn static QCircularBuffer<T> Qt3DCore::QCircularBuffer::fromList(const QList<T>& list)

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 18

    \sa fromVector(), toList(), toVector()
*/

/* \fn static QCircularBuffer<T> Qt3DCore::QCircularBuffer::fromVector(const QVector<T>& vector)

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

    \sa fromList(), toVector(), toList()
*/

/* \fn int Qt3DCore::QCircularBuffer::indexOf(const T &value, int from = 0) const

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 15

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

    \sa lastIndexOf(), contains()
*/

/* \fn void Qt3DCore::QCircularBuffer::insert(int i, const T &value)

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 11

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

    Items at indexes \a 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 \c {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 (\l{linear time}),
    because it requires moving all the items at indexes \a 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.

    \sa append(), prepend(), remove()
*/

/* \fn void Qt3DCore::QCircularBuffer::insert(int i, int count, const T &value)

    \overload

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

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

    The actual number of items that get inserted may not always be equal to
    \a 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(\a count, \a i + freeSize()).

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 12

    For large circular buffers, this operation can be slow (\l{linear time}),
    because it requires moving all the items at indexes \a 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.

    \sa append(), prepend(), remove()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::insert(const_iterator before, int count, const T &value)

    \overload

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

    \sa append(), prepend(), remove()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::insert(const_iterator before, const T &value)

    \overload

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

    \sa append(), prepend(), remove()
*/

/* \fn bool Qt3DCore::QCircularBuffer::isEmpty() const

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

    \sa capacity(), resize(), setCapacity(), size()
*/

/* \fn bool Qt3DCore::QCircularBuffer::isFull() const

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

    \sa capacity(), resize(), setCapacity(), size()
*/

/* \fn bool Qt3DCore::QCircularBuffer::isLinearised() const

    Returns \c true if the circular buffer is linearized; otherwise returns
    \c 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:

    \snippet code/src_core_qcircularbuffer.cpp 19

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

    \img circularbuffer-1.png

    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:

    \snippet code/src_core_qcircularbuffer.cpp 20

    the internal representation then becomes:

    \img circularbuffer-2.png

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

    \snippet code/src_core_qcircularbuffer.cpp 21

    causes the internal representation to become:

    \img circularbuffer-3.png

    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 (\l{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 an \l 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
    \l array_range object describing the values 2-6, and the dataTwo() function
    would return an \l 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.

    \sa linearise(), data(), dataOne(), dataTwo()
*/

/* \fn T &Qt3DCore::QCircularBuffer::last()

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

    \sa first(), isEmpty()
*/

/* \fn const T &Qt3DCore::QCircularBuffer::last() const

    \overload
*/

/* \fn int Qt3DCore::QCircularBuffer::lastIndexOf(const T &value, int from = -1) const

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 16

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

    \sa indexOf()
*/

/* \fn void Qt3DCore::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 (\l{linear time}).

    \sa isLinearised()
*/

/* \fn void Qt3DCore::QCircularBuffer::prepend(const T &value)

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

    Example:
    \snippet code/src_core_qcircularbuffer.cpp 10

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

    \sa operator<<(), operator+=(), append(), insert()
*/

/* \fn void Qt3DCore::QCircularBuffer::remove(int i)

    Removes the element at index position \a i.

    \sa insert(), replace(), fill()
*/

/* \fn void Qt3DCore::QCircularBuffer::remove(int i, int count)

    \overload

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

    \sa insert(), replace(), fill()
*/

/* \fn void Qt3DCore::QCircularBuffer::replace(int i, const T &value)

    Replaces the item at index position \a i with \a value.

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

    \sa operator[](), remove()
*/

/* \fn void Qt3DCore::QCircularBuffer::reserve(int capacity)

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

    \sa setCapacity()
*/

/* \fn void Qt3DCore::QCircularBuffer::resize(int size)

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

    \sa size(), insert(), remove(), capacity(), setCapacity()
*/

/* \fn void Qt3DCore::QCircularBuffer::setCapacity(int capacity)

    Sets the capacity of the circular buffer to \a capacity.

    \sa reserve(), capacity()
*/

/* \fn int Qt3DCore::QCircularBuffer::size() const

    Returns the number of items in the circular buffer.

    \sa sizeAvailable(), capacity(), resize()
*/

/* \fn int Qt3DCore::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()).

    \sa capacity(), isEmpty(), isFull(), size(), freeSize()
*/

/* \fn void Qt3DCore::QCircularBuffer::squeeze()

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

    \sa setCapacity(), size(), resize(), sizeAvailable()
*/

/* \fn bool Qt3DCore::QCircularBuffer::startsWith(const T &value) const

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

    \sa isEmpty(), first(), endsWith()
*/

/* \fn QList<T> Qt3DCore::QCircularBuffer::toList() const

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

    Example:

    \snippet code/src_core_qcircularbuffer.cpp 17

    \sa fromList(), toVector()
*/

/* \fn QVector<T> Qt3DCore::QCircularBuffer::toVector() const

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

    \sa fromVector(), toList()
*/

/* \fn T Qt3DCore::QCircularBuffer::value(int i) const

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

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

    \sa at(), operator[]()
*/

/* \fn T Qt3DCore::QCircularBuffer::value(int i, const T &defaultValue) const

    \overload

    If the index \a i is out of bounds, the function returns
    \a defaultValue.
*/

/* \fn bool Qt3DCore::operator==(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if the circular buffer \a lhs is equal to \a rhs; otherwise
    returns \c false.

    Two circular buffers are considered equal if they contain the same values
    in the same order and have the same capacity.

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

    \sa operator!=()
*/

/* \fn bool Qt3DCore::operator!=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if the circular buffer \a lhs is not equal to \a rhs; otherwise
    returns \c false.

    Two circular buffers are considered equal if they contain the same values
    in the same order and have the same capacity.

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

    \sa operator==()
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const T &other)

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

    \sa operator+(), operator<<(), append()
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QCircularBuffer<T>& other)

    \overload

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

    \sa operator+(), operator<<(), append()
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QVector<T>& other)

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QList<T>& other)

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const T &other)

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

    \sa operator+(), operator+=(), append()
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QCircularBuffer<T>& other)

    \overload

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

    \sa operator+(), operator+=(), append()
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QVector<T>& other)

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QList<T>& other)

    \overload
*/

/* \fn Qt3DCore::QCircularBuffer<T> Qt3DCore::operator+(const QCircularBuffer<T>& lhs, const QCircularBuffer<T>& rhs)
    \relates Qt3DCore::QCircularBuffer

    Returns a circular buffer object with capacity of lhs.size() + rhs.size() containing
    the items from \a lhs followed by the items from \a rhs.

    \sa {QCircularBuffer::}{operator+=()}
*/

/* \fn void Qt3DCore::swap(QCircularBuffer<T> &lhs, QCircularBuffer<T> &rhs)

    Swaps the contents of the circular buffer \a lhs with the contents of \a rhs.
*/

/* \fn bool Qt3DCore::operator<(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if \a lhs is lexographically less than \a rhs. This is equivalent to calling
    \c{return std::lexicographical_compare(lhs.begin(), lhs.end(), rhs.begin(), rhs.end())}.
*/

/* \fn bool Qt3DCore::operator>(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if \a rhs is lexographically less than \a lhs.
*/

/* \fn bool Qt3DCore::operator>=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if \a lhs is lexographically less than or equal to \a rhs.
*/

/* \fn bool Qt3DCore::operator<=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)

    Returns \c true if \a lhs is lexographically less than or equal to \a rhs.
*/

/* \typedef Qt3DCore::QCircularBuffer::Iterator

    Qt-style synonym for \l iterator.
*/

/* \typedef Qt3DCore::QCircularBuffer::ConstIterator

    Qt-style synonym for \l const_iterator.
*/

/* \typedef Qt3DCore::QCircularBuffer::const_pointer

    Typedef for const T *. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::const_reference

    Typedef for T &. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::difference_type

    Typedef for ptrdiff_t. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::pointer

    Typedef for T *. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::reference

    Typedef for T &. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::size_type

    Typedef for int. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::QCircularBuffer::value_type

    Typedef for T. Provided for STL compatibility.
*/

/* \typedef Qt3DCore::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.

    \sa data(), dataOne(), dataTwo()
*/

/* \typedef Qt3DCore::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 Qt3DCore::QCircularBuffer::ArrayRange

    Qt-style synonym for \l array_range.
*/

/* \typedef Qt3DCore::QCircularBuffer::ConstArrayRange

    Qt-style synonym for \l const_array_range.
*/


/* \class Qt3DCore::QCircularBuffer::iterator
    \inmodule Qt3DCore
    \brief The Qt3DCore::QCircularBuffer::iterator class provides an STL-style non-const iterator for QCircularBuffer.

    QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
    Iterators}.

    \sa begin(), end(), const_iterator
*/

/* \typedef Qt3DCore::QCircularBuffer::iterator::iterator_category

    A synonym for \e {std::random_access_iterator_tag} indicating
    this iterator is a random access iterator.
*/

/* \typedef Qt3DCore::QCircularBuffer::iterator::difference_type

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::iterator::value_type

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::iterator::pointer

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::iterator::reference

    \internal
*/

/* \fn Qt3DCore::QCircularBuffer::iterator::iterator()

    Constructs an uninitialized iterator.

    Functions like operator*() and operator++() should not be called
    on an uninitialized iterator. Use operator=() to assign a value
    to it before using it.

    \sa begin(), end()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator::iterator(QCircularBuffer<T> *buffer, int index)

    \internal
*/

/* \fn T &Qt3DCore::QCircularBuffer::iterator::operator*() const

    Returns a modifiable reference to the current item.

    You can change the value of an item by using operator*() on the
    left side of an assignment.

    \sa operator->()
*/

/* \fn T *Qt3DCore::QCircularBuffer::iterator::operator->() const

    Returns a pointer to the current item.

    \sa operator*()
*/

/* \fn T &Qt3DCore::QCircularBuffer::iterator::operator[](int j) const

    Returns a modifiable reference to the item at position *this +
    \a{j}.

    This function is provided to make QCircularBuffer iterators behave like C++
    pointers.

    \sa operator+()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator==(const iterator &other) const

    Returns \c true if \a other points to the same item as this
    iterator; otherwise returns \c false.

    \sa operator!=()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator!=(const iterator &other) const

    Returns \c true if \a other points to a different item than this
    iterator; otherwise returns \c false.

    \sa operator==()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator<(const iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs before
    the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator<=(const iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs before
    or at the same position as the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator>(const iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs after
    the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::iterator::operator>=(const iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs after
    or at the same position as the item pointed to by the \a other iterator.
*/

/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator++()

    The prefix ++ operator (\c{++it}) advances the iterator to the
    next item in the circular buffer and returns an iterator to the new current
    item.

    Calling this function on end() leads to undefined results.

    \sa operator--()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator++(int)

    \overload

    The postfix ++ operator (\c{it++}) advances the iterator to the
    next item in the circular buffer and returns an iterator to the previously
    current item.
*/

/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator--()

    The prefix -- operator (\c{--it}) makes the preceding item
    the current item, and returns an iterator to the new current item.

    Calling this function on begin() leads to undefined results.

    \sa operator++()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator--(int)

    \overload

    The postfix -- operator (\c{it--}) makes the preceding item
    the current item, and returns an iterator to the previously current item.
*/

/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator+=(int j)

    Advances the iterator by \a j items. (If \a j is negative, the
    iterator goes backward.)

    \sa operator-=(), operator+()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator-=(int j)

    Makes the iterator go back by \a j items. (If \a j is negative,
    the iterator goes forward.)

    \sa operator+=(), operator-()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator+(int j) const

    Returns an iterator to the item at \a j positions forward from
    this iterator. (If \a j is negative, the iterator goes backward.)

    \sa operator-(), operator+=()
*/

/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator-(int j) const

    Returns an iterator to the item at \a j positions backward from
    this iterator. (If \a j is negative, the iterator goes forward.)

    \sa operator+(), operator-=()
*/

/* \fn int Qt3DCore::QCircularBuffer::iterator::operator-(iterator other) const

    Returns the number of items between the item pointed to by \a
    other and the item pointed to by this iterator.
*/


/* \class Qt3DCore::QCircularBuffer::const_iterator
    \inmodule Qt3DCore
    \brief The Qt3DCore::QCircularBuffer::const_iterator class provides an STL-style const iterator for QCircularBuffer.

    QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
    Iterators}.

    \sa constBegin(), constEnd(), iterator
*/

/* \typedef Qt3DCore::QCircularBuffer::const_iterator::iterator_category

    A synonym for \e {std::random_access_iterator_tag} indicating
    this iterator is a random access iterator.
*/

/* \typedef Qt3DCore::QCircularBuffer::const_iterator::difference_type

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::const_iterator::value_type

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::const_iterator::pointer

    \internal
*/

/* \typedef Qt3DCore::QCircularBuffer::const_iterator::reference

    \internal
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator::const_iterator()

    Constructs an uninitialized const iterator.

    Functions like operator*() and operator++() should not be called
    on an uninitialized iterator. Use operator=() to assign a value
    to it before using it.

    \sa begin(), end()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator::const_iterator(const iterator &other)

    \internal
*/

/* \fn const T &Qt3DCore::QCircularBuffer::const_iterator::operator*() const

    Returns a const reference to the current item.

    \sa operator->()
*/

/* \fn const T *Qt3DCore::QCircularBuffer::const_iterator::operator->() const

    Returns a pointer to the current item.

    \sa operator*()
*/

/* \fn const T &Qt3DCore::QCircularBuffer::const_iterator::operator[](int j) const

    Returns a const reference to the item at position *this +
    \a{j}.

    This function is provided to make QCircularBuffer iterators behave like C++
    pointers.

    \sa operator+()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator==(const const_iterator &other) const

    Returns \c true if \a other points to the same item as this
    iterator; otherwise returns \c false.

    \sa operator!=()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator!=(const const_iterator &other) const

    Returns \c true if \a other points to a different item than this
    iterator; otherwise returns \c false.

    \sa operator==()
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator<(const const_iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs before
    the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator<=(const const_iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs before,
    or at the same position as the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator>(const const_iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs after
    the item pointed to by the \a other iterator.
*/

/*
    \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator>=(const const_iterator& other) const

    Returns \c true if the item pointed to by this iterator occurs after,
    or at the same position as the item pointed to by the \a other iterator.
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator++()

    The prefix ++ operator (\c{++it}) advances the iterator to the
    next item in the circular buffer and returns an iterator to the new current
    item.

    Calling this function on constEnd() leads to undefined results.

    \sa operator--()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator++(int)

    \overload

    The postfix ++ operator (\c{it++}) advances the iterator to the
    next item in the circular buffer and returns an iterator to the previously
    current item.
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator--()

    The prefix -- operator (\c{--it}) makes the preceding item the
    current and returns an iterator to the new current item.

    Calling this function on constBegin() leads to undefined results.

    \sa operator++()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator--(int)

    \overload

    The postfix -- operator (\c{it--}) makes the preceding item the
    current and returns an iterator to the previously current item.
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator+=(int j)

    Advances the iterator by \a j items. (If \a j is negative, the
    iterator goes backward.)

    \sa operator-=(), operator+()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator-=(int j)

    Makes the iterator go back by \a j items. (If \a j is negative,
    the iterator goes forward.)

    \sa operator+=(), operator-()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator+(int j) const

    Returns an iterator to the item at \a j positions forward from
    this iterator. (If \a j is negative, the iterator goes backward.)

    \sa operator-(), operator+=()
*/

/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator-(int j) const

    Returns an iterator to the item at \a j positions backward from
    this iterator. (If \a j is negative, the iterator goes forward.)

    \sa operator+(), operator-=()
*/

/* \fn int Qt3DCore::QCircularBuffer::const_iterator::operator-(const_iterator other) const

    Returns the number of items between the item pointed to by \a
    other and the item pointed to by this iterator.
*/
