<?xml version="1.0"?> 

<!--
	description:
	
		"General Abstractions"

	library: "Gobo Eiffel Structure Library"
	copyright: "Copyright (c) 1997-2005, Eric Bezault and others"
	license: "Eiffel Forum License v2 (see forum.txt)"
	date: "$Date: 2005/02/12 22:39:06 $"
	revision: "$Revision: 1.5 $"
-->

<chapter id="structure/container">
<chapterinfo>
	<copyright>
		<year>1999-2005</year>
		<holder>Eric Bezault</holder>
	</copyright>
	<author>
		<firstname>Eric</firstname><surname>Bezault</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>12 February 2005</date>
</chapterinfo>

<title>General Abstractions</title>

<para>
<mediaobjectco>
<imageobjectco>
<areaspec>
	<area coords="133 253 220 286" linkend="flatshort/ds_bilinear"/>
	<area coords="138 180 216 208" linkend="flatshort/ds_linear"/>
	<area coords="246 102 336 133" linkend="flatshort/ds_sortable"/>
	<area coords="197 14 282 44" linkend="flatshort/ds_container"/>
	<area coords="15 103 107 134" linkend="flatshort/ds_searchable"/>
	<area coords="245 178 336 209" linkend="flatshort/ds_indexable"/>
	<area coords="128 103 227 134" linkend="flatshort/ds_traversable"/>
	<area coords="352 104 440 134" linkend="flatshort/ds_resizable"/>
</areaspec>
<imageobject>
<imagedata align="center" fileref="image/container.gif"></imagedata>
</imageobject>
</imageobjectco>
</mediaobjectco>
</para>

<para>
The <libraryname>Gobo Eiffel Structure Library</libraryname> follows the
classical design pattern whereby deferred classes introduce
abstract properties, which leaves room for expansion by
inheriting from these deferred classes to implement yet
unavailable containers. The <classname>container</classname>
cluster contains classes describing general abstract notions such
as traversable, resizable or sortable properties.
</para>

<sect1 id="ds_container"><title>Class <classname>DS_CONTAINER</classname></title>

<para>
All data structures are descendant of class
<classname flatshort="true">DS_CONTAINER</classname>.
The classes are generic, the generic parameter representing the
type of the items being held in the containers. <classname>DS_CONTAINER</classname>
provides expected queries such as
<featurename flatshort="ds_container">count</featurename>,
the number of items in the container, and
<featurename flatshort="ds_container">is_empty</featurename>,
checking whether there is any item held in the container. Also
available is feature
<featurename flatshort="ds_container">wipe_out</featurename>,
which empties the container putting it back to a state similar to
what it was just after its creation.
</para>

<para>
The most direct descendant classes of <classname>DS_CONTAINER</classname>
introduce some abstract properties of containers.
</para>

</sect1>
<sect1 id="ds_searchable">
<title>Class <classname>DS_SEARCHABLE</classname></title>

<para>
Some containers can provide facilities to find out whether a
given item is held in this container. The class
<classname flatshort="true">DS_SEARCHABLE</classname>
introduces two features for this purpose:
<featurename flatshort="ds_searchable">has</featurename>
is a boolean query which returns true if the object given as
argument is actually held in the container, and
<featurename flatshort="ds_searchable">occurrences</featurename>
is the number of times an object appears in that container.
</para>

<para>
Depending on the context, several different criteria might be
used to search items in a container. For example, one may want to
check whether a given object appears in a list (using Eiffel's
'<featurename>=</featurename>' comparison criterion) or whether a
similar object is included (using the redefinable feature
<featurename>is_equal</featurename> from class
<classname>ANY</classname> as equality criterion).
In order to achieve this flexibility, the class
<classname>DS_SEARCHABLE</classname> can
be configured with an instance of class
<classname flatshort="true">DS_EQUALITY_TESTER</classname>
which provides a comparison criterion to the container. This
comparison criterion is held in the attribute
<featurename flatshort="ds_searchable">equality_tester</featurename>
and can be changed with
<featurename flatshort="ds_searchable">set_equality_tester</featurename>.
When no <featurename>equality_tester</featurename> has been specified,
the Eiffel's '<featurename>=</featurename>' comparison criterion is used.
By default, <classname>DS_EQUALITY_TESTER</classname> is
implemented using feature <featurename>equal</featurename> from
class <classname>ANY</classname>, but descendant
classes can be easily written to provide user-defined comparison
criteria.
</para>

<para>
The comparison criterion of the container is not only taken
into account by the features <featurename>has</featurename> and
<featurename>occurrences</featurename> but also by the features
<featurename flatshort="ds_linear_cursor">search_forth</featurename>
and <featurename flatshort="ds_bilinear_cursor">search_back</featurename>
provided by the cursor classes of the
<link linkend="traversal">traversal mechanism</link>.
</para>

</sect1>
<sect1><title>Class <classname>DS_TRAVERSABLE</classname></title>

<para>
Some containers can provide facilities in order to inspect
their items one after another. This traversal mechanism is quite
complex since there are different schools of thought for the
design and implementation of such pattern and hence deserves a
<link linkend="traversal">chapter of its own</link> in this
documentation.
</para>

</sect1>
<sect1><title>Class <classname>DS_SORTABLE</classname></title>

<para>
Some containers such as priority queues or binary search trees
keep their items sorted. On the other hand some other containers
do not necessarily keep their items sorted but provide facilities
to sort them on demand according to various comparison criteria
and sorting algorithms. These latter containers inherit from the
class <classname flatshort="true">DS_SORTABLE</classname>.
As just said, this facility depends on various criteria such as
sorting algorithms and here again deserves a
<link linkend="sort">chapter of its own</link>
in this documentation.
</para>

</sect1>
<sect1 id="ds_indexable"><title>Class <classname>DS_INDEXABLE</classname></title>

<para>
Some containers provide an index-based access to their items,
like access to the characters of a <classname>STRING</classname>
or to the elements of an <classname>ARRAY</classname>.
Such containers inherit from the class
<classname flatshort="true">DS_INDEXABLE</classname>
whose items are indexed from 1 to
<featurename flatshort="ds_indexable">count</featurename>.
The basic feature of this class is of course the access routine
<featurename flatshort="ds_indexable">item</featurename>
(by analogy to class <classname>ARRAY</classname> and other classes
from <libraryname>EiffelBase</libraryname>, feature
<infixname>@</infixname> has been added as a synomym of
<featurename>item</featurename>), but it is also equipped with commands to
add and remove items at given index positions, such as
<featurename flatshort="ds_indexable">put</featurename>
or <featurename flatshort="ds_indexable">remove</featurename>.
There are also convenience features to access the first (at index
1) and last (at index <featurename>count</featurename>)
items of the container, such as
<featurename flatshort="ds_indexable">first</featurename>,
<featurename flatshort="ds_indexable">put_last</featurename> or
<featurename flatshort="ds_indexable">remove_first</featurename>.
Have a look at the <link linkend="flatshort/ds_indexable">flat-short form</link>
for a complete list of these features.
</para>

</sect1>
<sect1 id="ds_resizable"><title>Class <classname>DS_RESIZABLE</classname></title>

<para>
Some containers allocate chunks of memory to hold their items.
This is for example the case for containers internally
implemented with arrays (typically named
<classname>DS_ARRAYED_*</classname>).
Such data structures cannot contain more items than initially
planned when allocating the chunk of memory unless they are
resized from time to time. The class
<classname flatshort="true">DS_RESIZABLE</classname>
provides such facility. Apart from the expected feature
<featurename flatshort="ds_resizable">resize</featurename>,
there are also two queries which are the counterpart of
<featurename>count</featurename> and <featurename>is_empty</featurename>
from <classname>DS_CONTAINER</classname>:
<featurename flatshort="ds_resizable">capacity</featurename>
is the maximum number of items that the container can currently hold, and
<featurename flatshort="ds_resizable">is_full</featurename>
checks whether the number of items in the container has reached this
limit.
</para>

</sect1>

</chapter>
