Loading...
Searching...
No Matches
CircularBuffer< T > Class Template Reference

A simple list of objects of type <T> that is intended to be used as a circular buffer (eg, a FIFO) when the alloc/free overhead associated with a linked-list approach is to be avoided. More...

#include <CircularBuffer.H>

Inheritance diagram for CircularBuffer< T >:

Classes

class  const_iterator
 A simple forward const iterator for a circular buffer. More...

Public Types

typedef T value_type
 The value type the list contains.
typedef Tpointer
 The pointer type for non-const access to value_type items.
typedef const Tconst_pointer
 The pointer type for const access to value_type items.
typedef Treference
 The type used for storing into value_type objects.
typedef const Tconst_reference
 The type used for reading from constant value_type objects.
typedef label size_type
 The type to represent the size of a buffer.
typedef label difference_type
 The difference between iterator objects.

Public Member Functions

constexpr CircularBuffer () noexcept
 Default construct, empty buffer without allocation.
 CircularBuffer (const label len)
 Construct an empty buffer with given reserve size.
 CircularBuffer (const CircularBuffer< T > &list)
 Copy construct.
 CircularBuffer (CircularBuffer< T > &&list)
 Move construct.
 CircularBuffer (Istream &is)
 Construct from Istream - uses readList.
label capacity () const noexcept
 Size of the underlying storage.
bool empty () const noexcept
 Empty or exhausted buffer.
label size () const noexcept
 The current number of buffer items.
label space () const noexcept
 The nominal space available to fill. Subtract 1 for the number to append before re-balancing is needed.
labelRange range_one () const noexcept
 The addressing range covered by array_one().
labelRange range_two () const noexcept
 The addressing range covered by array_two().
SubList< Tarray_one ()
 The contents of the first internal array.
SubList< Tarray_two ()
 The contents of the second internal array.
const SubList< Tarray_one () const
 The contents of the first internal array.
const SubList< Tarray_two () const
 The contents of the second internal array.
Tfront ()
 Access the first element (front). Requires !empty().
Tback ()
 Access the last element (back). Requires !empty().
const Tfront () const
 Const access to the first element (front). Requires !empty().
const Tback () const
 Const access to the last element (back). Requires !empty().
void reserve (const label len)
 Reserve allocation space for at least this size, allocating new space if required and retaining old content.
void reserve_nocopy (const label len)
 Reserve allocation space for at least this size, allocating new space if required without retaining old content.
void clear () noexcept
 Clear the addressed buffer, does not change allocation.
void clearStorage ()
 Clear the buffer and delete storage.
void swap (CircularBuffer< T > &other)
 Swap content, independent of sizing parameter.
bool contains (const T &val) const
 True if the value is contained in the list.
bool contains (const T &val, label pos) const
 Is the value contained in the list?
label find (const T &val, label pos=0) const
 Find index of the first occurrence of the value.
void push_front (const T &val)
 Copy prepend an element to the front of the buffer.
void push_front (T &&val)
 Move prepend an element to the front of the buffer.
template<class... Args>
Templace_front (Args &&... args)
 Construct an element at the front of the buffer, return reference to the new element.
void push_back (const T &val)
 Copy append an element to the end of the buffer.
void push_back (T &&val)
 Move append an element to the end of the buffer.
template<class... Args>
Templace_back (Args &&... args)
 Construct an element at the end of the buffer, return reference to the new element.
void pop_front (label n=1)
 Shrink by moving the front of the buffer 1 or more times.
void pop_back (label n=1)
 Shrink by moving the end of the buffer 1 or more times.
void push_back (const UList< T > &list)
 Copy append multiple elements the end of the buffer.
template<class Addr>
void push_back (const IndirectListBase< T, Addr > &list)
 Copy append IndirectList elements the end of the buffer.
label push_uniq (const T &val)
 Append an element if not already in the buffer.
List< Tlist () const
 Return a copy of the buffer flattened into a single List. Use sparingly!
void reverse ()
 Reverse the buffer order, swapping elements.
Toperator[] (const label i)
 Non-const access to an element in the list.
const Toperator[] (const label i) const
 Const access to an element in the list.
void operator= (const CircularBuffer< T > &list)
 Copy construct.
void operator= (CircularBuffer< T > &&list)
 Move construct.
void operator= (const T &val)
 Assign all addressed elements to the given value.
void operator= (Foam::zero)
 Assignment of all entries to zero.
void operator= (const UList< T > &rhs)
 Deep copy values from a list of the addressed elements.
template<class AnyAddr>
void operator= (const IndirectListBase< T, AnyAddr > &rhs)
 Deep copy values from a list of the addressed elements.
Ostreaminfo (Ostream &os) const
 Print information.
IstreamreadList (Istream &is)
 Read buffer contents from Istream.
OstreamwriteList (Ostream &os, const label shortLen=0) const
 Write buffer contents with line-breaks in ASCII when length exceeds shortLen.
const_iterator cbegin () const
 Return a const_iterator at begin of buffer.
const_iterator cend () const
 Return a const_iterator at end of buffer.
const_iterator begin () const
 Return a const_iterator at begin of buffer.
const_iterator end () const
 Return a const_iterator at end of buffer.

Static Public Member Functions

static constexpr label min_size () noexcept
 Lower capacity limit.

Friends

Istreamoperator>> (Istream &is, CircularBuffer< T > &list)
 Use the readList() method to read contents from Istream.
Ostreamoperator<< (Ostream &os, const CircularBuffer< T > &list)
 Write to Ostream.

Detailed Description

template<class T>
class Foam::CircularBuffer< T >

A simple list of objects of type <T> that is intended to be used as a circular buffer (eg, a FIFO) when the alloc/free overhead associated with a linked-list approach is to be avoided.

The internal storage is addressed by independent begin/end markers.

  • The begin marker points to the front.
  • The end marker is a one-past the back.

This results in a variety ofr different possible buffer states:

  1. empty (begin == end)
  2. simple/linear (begin < end) has no wrapping:
       |.|.|.|a|b|c|d|.|.|.|
       beg ___^
       end ___________^
    
  3. split (begin > end):
       |f|g|h|i|.|.|.|a|b|c|d|e|
       end _____^
       beg ___________^
    

The methods range_one(), range_two() return the internal indexing and the methods array_one(), array_two() provide direct access to the internal contents.

When filling the buffer, the internal storage will be resized (doubling strategy) as required. When this occurs, the new list will be linearized with begin = 0.

Simultaneously when filling, the storage buffer will be over-allocated to avoid ambiguity when (begin == end), which represents an empty buffer and not a full buffer. Eg,

    |c|d|.|a|b|
    end _^
    beg ___^

after appending one more, it would be incorrect to simply fill the available space:

    |c|d|e|a|b|
    end ___^        WRONG : would represent empty!
    beg ___^

the storage is instead increased (doubled) and rebalanced before the append occurs (old capacity 5, new capacity 10):

    |a|b|c|d|e|.|.|.|.|.|
    _^_ beg
    end _______^
Source files

Definition at line 115 of file CircularBuffer.H.

Member Typedef Documentation

◆ value_type

template<class T>
typedef T value_type

The value type the list contains.

Definition at line 174 of file CircularBuffer.H.

◆ pointer

template<class T>
typedef T* pointer

The pointer type for non-const access to value_type items.

Definition at line 179 of file CircularBuffer.H.

◆ const_pointer

template<class T>
typedef const T* const_pointer

The pointer type for const access to value_type items.

Definition at line 184 of file CircularBuffer.H.

◆ reference

template<class T>
typedef T& reference

The type used for storing into value_type objects.

Definition at line 189 of file CircularBuffer.H.

◆ const_reference

template<class T>
typedef const T& const_reference

The type used for reading from constant value_type objects.

Definition at line 194 of file CircularBuffer.H.

◆ size_type

template<class T>
typedef label size_type

The type to represent the size of a buffer.

Definition at line 199 of file CircularBuffer.H.

◆ difference_type

template<class T>
typedef label difference_type

The difference between iterator objects.

Definition at line 204 of file CircularBuffer.H.

Constructor & Destructor Documentation

◆ CircularBuffer() [1/5]

template<class T>
CircularBuffer ( )
inlineconstexprnoexcept

Default construct, empty buffer without allocation.

Definition at line 107 of file CircularBufferI.H.

References Foam::noexcept.

Referenced by CircularBuffer(), CircularBuffer(), CircularBuffer< T >::const_iterator::const_iterator(), operator<<, operator=(), operator=(), operator>>, and swap().

Here is the caller graph for this function:

◆ CircularBuffer() [2/5]

template<class T>
CircularBuffer ( const label len)
inlineexplicit

Construct an empty buffer with given reserve size.

Definition at line 116 of file CircularBufferI.H.

References Foam::max(), and min_size().

Here is the call graph for this function:

◆ CircularBuffer() [3/5]

template<class T>
CircularBuffer ( const CircularBuffer< T > & list)
inline

Copy construct.

Definition at line 125 of file CircularBufferI.H.

References CircularBuffer(), and list().

Here is the call graph for this function:

◆ CircularBuffer() [4/5]

template<class T>
CircularBuffer ( CircularBuffer< T > && list)
inline

Move construct.

Definition at line 137 of file CircularBufferI.H.

References CircularBuffer(), and list().

Here is the call graph for this function:

◆ CircularBuffer() [5/5]

template<class T>
CircularBuffer ( Istream & is)
explicit

Construct from Istream - uses readList.

Definition at line 27 of file CircularBufferIO.C.

References readList().

Here is the call graph for this function:

Member Function Documentation

◆ min_size()

template<class T>
constexpr label min_size ( )
inlinestaticconstexprnoexcept

Lower capacity limit.

Definition at line 247 of file CircularBuffer.H.

References min_size(), and Foam::noexcept.

Referenced by CircularBuffer(), min_size(), and readList().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ capacity()

template<class T>
Foam::label capacity ( ) const
inlinenoexcept

Size of the underlying storage.

Definition at line 154 of file CircularBufferI.H.

References Foam::noexcept.

Referenced by Foam::meshTools::bandCompression(), and info().

Here is the caller graph for this function:

◆ empty()

template<class T>
bool empty ( ) const
inlinenoexcept

Empty or exhausted buffer.

Definition at line 162 of file CircularBufferI.H.

References Foam::noexcept.

Referenced by back(), back(), Foam::meshTools::bandCompression(), and front().

Here is the caller graph for this function:

◆ size()

template<class T>
Foam::label size ( ) const
inlinenoexcept

The current number of buffer items.

Definition at line 169 of file CircularBufferI.H.

References Foam::diff(), and Foam::noexcept.

Referenced by cend(), emplace_back(), emplace_front(), info(), Foam::polyMeshZipUpCells(), pop_back(), pop_front(), push_back(), push_front(), push_front(), reverse(), space(), and writeList().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ space()

template<class T>
Foam::label space ( ) const
inlinenoexcept

The nominal space available to fill. Subtract 1 for the number to append before re-balancing is needed.

Definition at line 183 of file CircularBufferI.H.

References Foam::noexcept, and size().

Here is the call graph for this function:

◆ range_one()

template<class T>
Foam::labelRange range_one ( ) const
inlinenoexcept

The addressing range covered by array_one().

Definition at line 190 of file CircularBufferI.H.

References Foam::noexcept.

◆ range_two()

template<class T>
Foam::labelRange range_two ( ) const
inlinenoexcept

The addressing range covered by array_two().

Definition at line 202 of file CircularBufferI.H.

References Foam::noexcept.

◆ array_one() [1/2]

template<class T>
Foam::SubList< T > array_one ( )

The contents of the first internal array.

Definition at line 77 of file CircularBuffer.C.

Referenced by contains(), find(), list(), operator=(), operator=(), and writeList().

Here is the caller graph for this function:

◆ array_two() [1/2]

template<class T>
Foam::SubList< T > array_two ( )

The contents of the second internal array.

Definition at line 85 of file CircularBuffer.C.

Referenced by contains(), find(), list(), operator=(), operator=(), and writeList().

Here is the caller graph for this function:

◆ array_one() [2/2]

template<class T>
const Foam::SubList< T > array_one ( ) const

The contents of the first internal array.

Definition at line 93 of file CircularBuffer.C.

◆ array_two() [2/2]

template<class T>
const Foam::SubList< T > array_two ( ) const

The contents of the second internal array.

Definition at line 101 of file CircularBuffer.C.

◆ front() [1/2]

template<class T>
T & front ( )
inline

Access the first element (front). Requires !empty().

Definition at line 267 of file CircularBufferI.H.

References empty(), and Foam::T().

Referenced by Foam::meshTools::bandCompression(), and Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ back() [1/2]

template<class T>
T & back ( )
inline

Access the last element (back). Requires !empty().

Definition at line 291 of file CircularBufferI.H.

References Foam::abort(), empty(), Foam::FatalError, FatalErrorInFunction, and Foam::T().

Referenced by Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ front() [2/2]

template<class T>
const T & front ( ) const
inline

Const access to the first element (front). Requires !empty().

Definition at line 279 of file CircularBufferI.H.

References Foam::T().

Here is the call graph for this function:

◆ back() [2/2]

template<class T>
const T & back ( ) const
inline

Const access to the last element (back). Requires !empty().

Definition at line 303 of file CircularBufferI.H.

References Foam::abort(), empty(), Foam::FatalError, FatalErrorInFunction, and Foam::T().

Here is the call graph for this function:

◆ reserve()

template<class T>
void reserve ( const label len)
inline

Reserve allocation space for at least this size, allocating new space if required and retaining old content.

Never shrinks.

Definition at line 239 of file CircularBufferI.H.

◆ reserve_nocopy()

template<class T>
void reserve_nocopy ( const label len)
inline

Reserve allocation space for at least this size, allocating new space if required without retaining old content.

Never shrinks.

Definition at line 246 of file CircularBufferI.H.

◆ clear()

template<class T>
void clear ( )
inlinenoexcept

Clear the addressed buffer, does not change allocation.

Definition at line 209 of file CircularBufferI.H.

References Foam::noexcept.

Referenced by Foam::polyMeshZipUpCells().

Here is the caller graph for this function:

◆ clearStorage()

template<class T>
void clearStorage ( )
inline

Clear the buffer and delete storage.

Definition at line 216 of file CircularBufferI.H.

Referenced by operator=().

Here is the caller graph for this function:

◆ swap()

template<class T>
void swap ( CircularBuffer< T > & other)
inline

Swap content, independent of sizing parameter.

Definition at line 224 of file CircularBufferI.H.

References CircularBuffer().

Referenced by operator=().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ contains() [1/2]

template<class T>
bool contains ( const T & val) const
inline

True if the value is contained in the list.

Definition at line 253 of file CircularBufferI.H.

References array_one(), array_two(), contains(), and Foam::T().

Referenced by contains(), and push_uniq().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ contains() [2/2]

template<class T>
bool contains ( const T & val,
label pos ) const
inline

Is the value contained in the list?

Parameters
valThe value to search for
posThe first position to examine (no-op if -ve)
Returns
true if found.

Definition at line 260 of file CircularBufferI.H.

References Foam::pos(), and Foam::T().

Here is the call graph for this function:

◆ find()

template<class T>
Foam::label find ( const T & val,
label pos = 0 ) const

Find index of the first occurrence of the value.

Any occurrences before the start pos are ignored. Linear search.

Returns
position in list or -1 if not found.

Definition at line 109 of file CircularBuffer.C.

References array_one(), array_two(), Foam::pos(), and Foam::T().

Here is the call graph for this function:

◆ push_front() [1/2]

template<class T>
void push_front ( const T & val)
inline

Copy prepend an element to the front of the buffer.

Definition at line 315 of file CircularBufferI.H.

References reserve(), size(), and Foam::T().

Referenced by Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ push_front() [2/2]

template<class T>
void push_front ( T && val)
inline

Move prepend an element to the front of the buffer.

Definition at line 327 of file CircularBufferI.H.

References reserve(), size(), and Foam::T().

Here is the call graph for this function:

◆ emplace_front()

template<class T>
template<class... Args>
T & emplace_front ( Args &&... args)
inline

Construct an element at the front of the buffer, return reference to the new element.

Definition at line 340 of file CircularBufferI.H.

References args, reserve(), size(), and Foam::T().

Here is the call graph for this function:

◆ push_back() [1/4]

template<class T>
void push_back ( const T & val)
inline

Copy append an element to the end of the buffer.

Definition at line 354 of file CircularBufferI.H.

References reserve(), size(), and Foam::T().

Referenced by Foam::meshTools::bandCompression(), and Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ push_back() [2/4]

template<class T>
void push_back ( T && val)
inline

Move append an element to the end of the buffer.

Definition at line 366 of file CircularBufferI.H.

◆ emplace_back()

template<class T>
template<class... Args>
T & emplace_back ( Args &&... args)
inline

Construct an element at the end of the buffer, return reference to the new element.

Definition at line 379 of file CircularBufferI.H.

References args, reserve(), size(), Foam::T(), and T.

Here is the call graph for this function:

◆ pop_front()

template<class T>
void pop_front ( label n = 1)
inline

Shrink by moving the front of the buffer 1 or more times.

Definition at line 394 of file CircularBufferI.H.

References n, and size().

Referenced by Foam::meshTools::bandCompression(), and Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ pop_back()

template<class T>
void pop_back ( label n = 1)
inline

Shrink by moving the end of the buffer 1 or more times.

Definition at line 411 of file CircularBufferI.H.

References n, and size().

Here is the call graph for this function:

◆ push_back() [3/4]

template<class T>
void push_back ( const UList< T > & list)
inline

Copy append multiple elements the end of the buffer.

Definition at line 443 of file CircularBufferI.H.

References Foam::rhs().

Here is the call graph for this function:

◆ push_back() [4/4]

template<class T>
template<class Addr>
void push_back ( const IndirectListBase< T, Addr > & list)
inline

Copy append IndirectList elements the end of the buffer.

Definition at line 464 of file CircularBufferI.H.

References Foam::rhs().

Here is the call graph for this function:

◆ push_uniq()

template<class T>
Foam::label push_uniq ( const T & val)
inline

Append an element if not already in the buffer.

Returns
the change in the buffer length

Definition at line 428 of file CircularBufferI.H.

References contains(), and Foam::T().

Here is the call graph for this function:

◆ list()

template<class T>
Foam::List< T > list ( ) const

Return a copy of the buffer flattened into a single List. Use sparingly!

Definition at line 163 of file CircularBuffer.C.

References array_one(), array_two(), and UList< T >::slice().

Referenced by CircularBuffer(), CircularBuffer(), and Foam::polyMeshZipUpCells().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ reverse()

template<class T>
void reverse ( )

Reverse the buffer order, swapping elements.

Definition at line 150 of file CircularBuffer.C.

References n, size(), and Foam::Swap().

Here is the call graph for this function:

◆ operator[]() [1/2]

template<class T>
T & operator[] ( const label i)
inline

Non-const access to an element in the list.

The index is allowed to wrap in both directions

Definition at line 489 of file CircularBufferI.H.

References Foam::T().

Here is the call graph for this function:

◆ operator[]() [2/2]

template<class T>
const T & operator[] ( const label i) const
inline

Const access to an element in the list.

The index is allowed to wrap in both directions

Definition at line 497 of file CircularBufferI.H.

References Foam::T().

Here is the call graph for this function:

◆ operator=() [1/6]

template<class T>
void operator= ( const CircularBuffer< T > & list)
inline

Copy construct.

Definition at line 505 of file CircularBufferI.H.

References CircularBuffer(), clear(), reserve(), Foam::rhs(), and Foam::T().

Here is the call graph for this function:

◆ operator=() [2/6]

template<class T>
void operator= ( CircularBuffer< T > && list)
inline

Move construct.

Definition at line 542 of file CircularBufferI.H.

References CircularBuffer(), clearStorage(), Foam::rhs(), and swap().

Here is the call graph for this function:

◆ operator=() [3/6]

template<class T>
void operator= ( const T & val)
inline

Assign all addressed elements to the given value.

Definition at line 555 of file CircularBufferI.H.

References array_one(), array_two(), and Foam::T().

Here is the call graph for this function:

◆ operator=() [4/6]

template<class T>
void operator= ( Foam::zero )
inline

Assignment of all entries to zero.

Definition at line 563 of file CircularBufferI.H.

References array_one(), and array_two().

Here is the call graph for this function:

◆ operator=() [5/6]

template<class T>
void operator= ( const UList< T > & rhs)
inline

Deep copy values from a list of the addressed elements.

Definition at line 571 of file CircularBufferI.H.

References Foam::rhs().

Here is the call graph for this function:

◆ operator=() [6/6]

template<class T>
template<class AnyAddr>
void operator= ( const IndirectListBase< T, AnyAddr > & rhs)
inline

Deep copy values from a list of the addressed elements.

Definition at line 579 of file CircularBufferI.H.

References Foam::rhs().

Here is the call graph for this function:

◆ info()

template<class T>
Foam::Ostream & info ( Ostream & os) const

Print information.

Definition at line 36 of file CircularBufferIO.C.

References capacity(), Foam::nl, os(), and size().

Here is the call graph for this function:

◆ readList()

template<class T>
Foam::Istream & readList ( Istream & is)

Read buffer contents from Istream.

Definition at line 50 of file CircularBufferIO.C.

References DynamicList< T, SizeMin >::capacity(), UList< T >::empty(), min_size(), DynamicList< T, SizeMin >::readList(), DynamicList< T, SizeMin >::resize(), DynamicList< T, SizeMin >::setCapacity(), and UList< T >::size().

Referenced by CircularBuffer().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ writeList()

template<class T>
Foam::Ostream & writeList ( Ostream & os,
const label shortLen = 0 ) const

Write buffer contents with line-breaks in ASCII when length exceeds shortLen.

Using '0' suppresses line-breaks entirely.

Definition at line 79 of file CircularBufferIO.C.

References Foam::abort(), array_one(), array_two(), token::BEGIN_LIST, IOstreamOption::BINARY, token::END_LIST, Foam::FatalError, FatalErrorInFunction, FUNCTION_NAME, Foam::is_contiguous_v, Foam::nl, os(), size(), token::SPACE, and Foam::T().

Here is the call graph for this function:

◆ cbegin()

template<class T>
const_iterator cbegin ( ) const
inline

Return a const_iterator at begin of buffer.

Definition at line 619 of file CircularBuffer.H.

Referenced by begin().

Here is the caller graph for this function:

◆ cend()

template<class T>
const_iterator cend ( ) const
inline

Return a const_iterator at end of buffer.

Definition at line 627 of file CircularBuffer.H.

References size().

Referenced by end().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ begin()

template<class T>
const_iterator begin ( ) const
inline

Return a const_iterator at begin of buffer.

Definition at line 635 of file CircularBuffer.H.

References cbegin().

Here is the call graph for this function:

◆ end()

template<class T>
const_iterator end ( ) const
inline

Return a const_iterator at end of buffer.

Definition at line 640 of file CircularBuffer.H.

References cend().

Here is the call graph for this function:

◆ operator>>

template<class T>
Istream & operator>> ( Istream & is,
CircularBuffer< T > & list )
friend

Use the readList() method to read contents from Istream.

Definition at line 650 of file CircularBuffer.H.

References CircularBuffer(), and Foam::rhs().

◆ operator<<

template<class T>
Ostream & operator<< ( Ostream & os,
const CircularBuffer< T > & list )
friend

Write to Ostream.

Definition at line 661 of file CircularBuffer.H.

References CircularBuffer(), os(), and Foam::rhs().


The documentation for this class was generated from the following files: