﻿/**
\page doc Dokumentace projektu CBNode

##Základní popis

\c CBNode představuje prvek, ze kterého je možné vytvářet obousměrně vázaný cyklický seznam. Obousměrně vázaný seznam se od lineárního seznamu liší tím, že jednotlivé prvky \c CBNode obsahují
nejen odkazy na svoje následníky \p iRight, ale také odkazy na své předchůdce \p iLeft. Cyklický seznam představuje variantu kdy poslední prvek odkazuje pomocí ukazatele \p iRight zpět na prvek
na počátku a první prvek odkazuje pomocí ukazatele \p iLeft na prvek poslední.

\dotfile CBNodeList.gv "Příklad cyklického oboustranného seznamu se čtyřmi prvky \c CBNode"
\n

Specifickým případem obousměrně vázaného cyklického seznamu je seznam s pouze jedním prvkem (tzv. elementární seznam). Kde oba ukazatele odkazují na tentýž prvek.

\dotfile CBNodeListPrimitive.gv "Příklad elementárního cyklického oboustranného seznamu s jedním prvkem \c CBNode"
\n

Výhodou obousměrného seznamu je možnost výpočetně efektivního procházení (tzv. traverzovaní) seznamem a to oběma směry. Mezi nevýhody lze uvést vyšší paměťové nároky spojené s existencí dalšího ukazatele (tj. \p iLeft).
Výhodou cyklického seznamu je skutečnost, že všechny ukazatele vždy odkazují svojí hodnotou na platnou paměť, což je výhodné například při vkládání resp. odstraňování prvků.


\n
##Popis implementace
V tomto školním C++ projektu je prvek obousměrně vázaného cyklického seznamu realizován jako instance třídy \c CBNode mající předka CBNodeBase.


###Třída CBNodeBase
Třída CBNodeBase implementuje všechny vlastnosti, které jsou společné pro jakékoliv prvky obousměrně vázaného cyklického seznamu, tj. obsahuje odkaz na předchozí prvek \p iLeft, odkaz na následující prvek \p iRight.
Dále implementuje mechanismy konstrukce, modifikace hodnot ukazatelů a základní kontrolní mechanismy. Tato třída neobsahuje v definici žádná užitečná data, které by měl každý prvek seznamu obsahovat. Definuje, tak pouze základní
rozhraní, které bude společné všem prvkům bez ohledu na typ a množství užitečných dat.


###Třída CBNode
Třída \c CBNode je potomkem třídy CBNodeBase a obsahuje tedy všechny vlastnosti, které budou společné všem prvkům obousměrně vázaného cyklického seznamu. Úlohou třídy \c CBNode je doplnit definici prvku seznamu o atribut \p iValue,
jenž představuje užitečná data a která bude každý prvek seznamu obsahovat. Dále je třeba vhodně upravit a doplnit metody určené pro konstrukci a likvidaci prvku tak, aby bylo možné nový prvek efektivně konstruovat a využívat.
Třída \c CBNode je navíc správcem své vlastní hodnoty \p iValue a proto definuje základní metody pro zjištění, nastavení této hodnoty a zároveň zajišťuje pro nadřazené vyšší části programu metody pro porovnání prvků dle této hodnoty,
čímž izoluje nadřazené části od nutnosti znát konkrétní datový typ atributu \p iValue.


###Jmenné prostory CBNode_xxxx
Návrh programu i Vaše zadání požaduje nezávislost na vnitřní implementaci třídy \c CBNode (konkrétním datovém typu atributu \p iValue). Návrh navíc umožňuje, aby uživatel mohl odkomentováním řádku přepínat
mezi vnitřními implementacemi \c CBNode. Tento mechanismus je zajištěn pomocí definice každé z variant \c CBNode ve vlastním jmenném prostoru \c CBNode_NAZEV_TYPU, díky této skutečnosti může existovat v programu
několik stejně pojmenovaných tříd \c CBNode, neboť názvy existují ve svém vlastním oboru viditelnosti (jmenném prostoru).

Volba dané varianty \c CBNode je potom prováděna v souboru CBNode.h, odkomentovaním toho řádku, který exportuje daný jmenný prostor do globálního prostoru jmen.
\code{.cpp}
using namespace CBNode_bool;
//using namespace CBNode_TWeekDay;
//using namespace CBNode_char;
//using namespace CBNode_int;
//using namespace CBNode_float;
//using namespace CBNode_longdouble;
\endcode


\n
##Realizace dalších variant tříd CBNode
V současnosti projekt obsahuje tyto varianty tříd \c CBNode, z nichž je každá definována ve svém jmenném prostoru:
\li CBNode_bool::CBNode
\li CBNode_TWeekDay::CBNode

Pro každou další variantu \c CBNode nadefinujte nový jmenný prostor \c CBNode_NAZEV_TYPU a v něm implementujte novou variantu třídy \c CBNode.
\note Mechanismus by samozřejmě bylo možné realizovat i zcela automaticky (překladač sám dle potřeby programátora vygeneruje novou variantu třídy \c CBNode pomocí definované šablony, případně bude umožnovat dynamickou identifikaci typu a 
tím umožní mít při běhu programu v jednom seznamu různé varianty prvků \c CBNode.
Obě tyto techniky ovšem svým rozsahem vybočují nad rámec výuky v tomto kurzu a proto jsme se rozhodli se jim v tomto projektu vyhnout.


\n
##Testovací hlavní program
Hlavní program v souboru main.cpp představuje základní sadu testů, které ověřují správnou funkci libovolné varianty třídy \c CBNode. Seznamte se s obsahem hlavního programu a protrasujte si jednotlivá volání.

###Testovací hodnoty
Každá s implementací třídy \c CBNode navíc obsahuje čtyři základní metody vracející hodnotu datového typu vhodného pro vložení do atributu \p iValue. Projděte si uvedené mechanismy a snažte se
pochopit jejich vliv na nezávislost kódu hlavního programu.

Jedná se o tyto metody:
\li \c TestValue0() (např. CBNode_bool::CBNode::TestValue0())
\li \c TestStringValue0() (např. CBNode_bool::CBNode::TestStringValue0)
\li \c TestValue1() (např. CBNode_bool::CBNode::TestValue1)
\li \c TestStringValue1() (např. CBNode_bool::CBNode::TestStringValue1)

###Další kontrolní vlastnosti prvku
Již základní společná třída CBNodeBase (a tedy i každý potomek \c CBNode) obsahuje několik kontrolních a ladících mechanismů, které budete jistě chtít využívat.

\li Prvek při své destrukci kontroluje, zda není součástí seznamu dalších prvků a pokud ano, generuje chybové hlášení případně i výjimku.
\li Prvek vždy ověřuje, že oba jeho ukazatele \p iLeft, \p iRight obsahují odkaz na platnou adresu jiného prvku, každý pokus o nastavení neplatné adresy (\c NULL resp. \c nullptr) generuje výjimku.

Mezi ladicí nástroje patří:
\li CBNodeBase::Total()  - počítadlo vzniklých instancí třídy
\li CBNodeBase::Living() - počítadlo v daném okamžiku existujících instancí třídy
\li CBNodeBase::Index()  - unikátní číselné označení instance třídy

\attention Projděte si všechny uvedené kontrolní i ladicí mechanismy, snažte se pochopit jejich smysl a využití při trasování programu. Získané vědomosti se Vám budou rozhodně hodit.


\note 
Hodně štěstí při realizaci Vašeho projektu. _A nepropadejte panice! ;-)_

Pety.

$Id: Documentation.txt 1 2012-10-15 13:25:08Z petyovsky $
*/
