<?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-D0BD34C9-7793-5FA0-8864-FD7444D62F90" xml:lang="en"><title>How to

form links</title><shortdesc>This document describes how to use links within a doubly linked

list.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>To form a doubly linked list of <codeph>CMyClass</codeph> objects, include

the link object <codeph>TDblQueLink</codeph> as a component of <codeph>CMyClass</codeph>:</p>

<codeblock id="GUID-E595B603-FC0D-5AF3-9228-7D40C3A08271" xml:space="preserve">class CMyClass : public CBase

    {

    ...

    TDblQueLink iDlink;

    ...

    };</codeblock>

<fig id="GUID-30C9DE23-1805-594C-9F7F-BD4A161DE59A">

<image href="GUID-F342B002-0667-5D51-AE2D-3CF534D70B62_d0e213719_href.png" placement="inline"/>

</fig>

<p>Although any kind of object can be an element of a linked list, most lists

consist of elements which are all of the same type.</p>

<p>An object can participate in more than one list. For example, to allow <codeph>CMyClass</codeph> objects

to participate in two doubly linked lists, include two separate <codeph>TDblQueLink</codeph> objects

as components of <codeph>CMyClass</codeph>:</p>

<codeblock id="GUID-2027BF61-9834-5915-9911-3420CAC7061A" xml:space="preserve">class CMyClass : public CBase

    {

    ...

    TDblQueLink iDlink1;

    ...

    TDblQueLink iDlink2;

    };</codeblock>

<fig id="GUID-DC3DDF09-2F30-5704-ACB0-378622DDDD88">

<image href="GUID-B131AE10-B9B1-53D2-8CAA-A9045957D6F9_d0e213742_href.png" placement="inline"/>

</fig>

<p>Elements can also be objects constructed from a variety of classes, all

ultimately derived from the same base class, where that base class includes

the link object as a component. For example, if <codeph>CBc</codeph> is a

base class for <codeph>CD1</codeph> which, in turn, is a base class for <codeph>CD2</codeph>,

then the elements of the list can consist of a mix of <codeph>CBc</codeph> or <codeph>CDc1</codeph> or <codeph>CDc2</codeph> objects.</p>

<codeblock id="GUID-C274DD90-E21A-5BAD-8094-79CE23CDA1B9" xml:space="preserve">class CBc : public CBase

    {

    ...

    TDblQueLink iDlink;

    ...

    };</codeblock>

<codeblock id="GUID-6BAAB6AA-421F-51CE-8650-2FEDA3EB0A83" xml:space="preserve">class CDc1 : public CBclass

    {

    ...

    }

</codeblock>

<codeblock id="GUID-1C1A9078-0F8A-5E24-82CF-BD0C199B4050" xml:space="preserve">class CDc2 : public CDc1

    {

    ...

    }

</codeblock>

<fig id="GUID-F8769477-6B6C-5531-9675-AC66FE6B6E3D">

<image href="GUID-38FF81FD-0C23-586D-AFAE-9F0761A36BAD_d0e213777_href.png" placement="inline"/>

</fig>

<p>New link elements are inserted into an existing list using either <codeph>TDblQueLink::Enque()</codeph> or <codeph>TDblQueLink::AddBefore()</codeph> function. Note that <codeph>AddBefore()</codeph> is not available in v5.

These are prototyped as:</p>

<codeblock id="GUID-DDD3FDA3-4635-5AFE-9C17-994E5E4D1C59" xml:space="preserve">void Enque(TDblQueLinkBase* aLink);

</codeblock>

<codeblock id="GUID-F3E72D69-0180-5BAD-A2C6-E31704820AAF" xml:space="preserve">void AddBefore(TDblQueLinkBase* aLink);</codeblock>

<p>Calling <codeph>Enque()</codeph> on an element means that this element

is added to the list so that its position follows the element <i>aLink</i>,

as the following figure shows.</p>

<fig id="GUID-F46E770B-8BDC-5E61-9E28-043FDAA3B193">

<image href="GUID-3E1199E4-4F19-58BB-B1EC-8975A04B68FF_d0e213809_href.png" placement="inline"/>

</fig>

<p>Calling <codeph>AddBefore()</codeph> on an element means that this element

is added to the list so that its position precedes the element <i>aLink</i>,

as the following figure shows.</p>

<fig id="GUID-0E6C9ADF-0182-52CC-A3D1-AE83F540E42B">

<image href="GUID-2AB5AA00-71B2-58F4-AE17-9A38D1E5AA99_d0e213823_href.png" placement="inline"/>

</fig>

<p>Note that new elements cannot be inserted at the beginning or end of a

list using these functions. The <codeph>AddFirst()</codeph> and <codeph>AddLast()</codeph> members

of the header class <codeph>TDblQue&lt;class         T&gt;</codeph> must be used

instead.</p>