<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-5127C80E-EACE-5524-9A75-A0EFB41C2226" xml:lang="en"><title>Circular
Buffer structure</title><shortdesc>This document describes the structure of circular buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>"Circular Buffers" is a sub-API of the "Buffers and strings" API.</p>
<p>A circular buffer provides a simple way of implementing a fixed length
queue of fixed size objects where objects are added to the head of the queue
while items are removed from the tail of the queue.</p>
<p>Logically, the buffer is circular with no defined start or end. Objects
are always added to the buffer head and are always removed from the buffer
tail. The buffer head is always the next vacant slot into which an object
is added. The buffer tail is always the slot from which the next object is
removed. The tail always logically follows the head and the implementation
ensures that the tail never overtakes the head.</p>
<fig id="GUID-18737BF9-5382-5431-8B3E-68C7CCD3DF86">
<image href="GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e224902_href.png" placement="inline"/>
</fig>
<p>Physically, the buffer is a contiguous block of memory. The implementation
provides the appearance of circularity.</p>
<p>A circular buffer has a maximum capacity which must be set before the circular
buffer can be used. The maximum capacity can be changed at any time but any
existing data within the buffer is lost.</p>
<p>The sub-API consists of three classes, two of which can be instantiated:</p>
<ul>
<li id="GUID-42FC2894-0995-578C-AE0D-0670CC63B242"><p>the templated class <codeph>CCirBuf&lt;class
T&gt;</codeph> builds a circular buffer of general objects.</p> </li>
<li id="GUID-C98B7B84-67D4-5616-A042-CFF16B26422F"><p>the <codeph>CCirBuffer</codeph> class
builds a circular buffer of unsigned integers with values ranging from -128
to +128.</p> </li>
</ul>
</conbody></concept>