-- File:	EntityCluster.cdl
-- Created:	Mon Nov  2 16:03:55 1992
-- Author:	Christian CAILLET
--		<cky@topsn2>
---Copyright:	 Matra Datavision 1992


private class EntityCluster  from Interface  inherits TShared

    ---Purpose : Auxiliary class for EntityList. An EntityList designates an
    --           EntityCluster, which brings itself an fixed maximum count of
    --           Entities. If it is full, it gives access to another cluster
    --           ("Next"). This class is intended to give a good compromise
    --           between access time (faster than a Sequence, good for little
    --           count) and memory use (better than a Sequence in any case,
    --           overall for little count, better than an Array for a very
    --           little count. It is designed for a light management.
    --           Remark that a new Item may not be Null, because this is the
    --           criterium used for "End of List"

uses EntityIterator, Transient

raises OutOfRange, NullObject

is

    Create returns mutable EntityCluster;
    ---Purpose : Creates an empty, non-chained, EntityCluster

    Create (ent : any Transient)  returns mutable EntityCluster;
    ---Purpose : Creates a non-chained EntityCluster, filled with one Entity

    Create (ec : mutable EntityCluster)  returns mutable EntityCluster;
    ---Purpose : Creates an empty EntityCluster, chained with another one
    --           (that is, put BEFORE this other one in the list)

    Create (ant : any Transient; ec : mutable EntityCluster)
    	returns mutable EntityCluster;
    ---Purpose : Creates an EntityCluster, filled with a first Entity, and
    --           chained to another EntityCluster (BEFORE it, as above)


    Append (me : mutable; ent : any Transient)
    ---Purpose : Appends an Entity to the Cluster. If it is not full, adds the
    --           entity directly inside itself. Else, transmits to its Next
    --           and Creates it if it does not yet exist
    	raises NullObject  is static;
    --           Error if <ent> is Null

    Remove (me : mutable; ent : any Transient) returns Boolean
    ---Purpose : Removes an Entity from the Cluster. If it is not found, calls
    --           its Next one to do so.
    --           Returns True if it becomes itself empty, False else
    --           (thus, a Cluster which becomes empty is deleted from the list)
    	raises NullObject  is static;
    --           Error if <ent> is Null

    Remove (me : mutable; num : Integer) returns Boolean
    ---Purpose : Removes an Entity from the Cluster, given its rank. If <num>
    --           is greater than NbLocal, calls its Next with (num - NbLocal),
    --           Returns True if it becomes itself empty, False else
    	raises OutOfRange  is static;
    --           Raises an Exception if there is no Next to do so.

    NbEntities (me) returns Integer  is static;
    ---Purpose : Returns total count of Entities (including Next)

    Value (me; num : Integer)  returns any Transient
    ---Purpose : Returns the Entity identified by its rank in the list
    --           (including Next)
    	raises OutOfRange  is static;
    --           Error if num less than 1 or num more then NbEntities
    ---C++ : return const &

    SetValue (me : mutable; num : Integer; ent : any Transient)
    ---Purpose : Changes an Entity given its rank.
    	raises OutOfRange, NullObject  is static;
    --           Error if <num> is not in [1 - NbEntities], or if <ent> is Null

    FillIterator (me; iter : in out EntityIterator)  is static;
    ---Purpose : Fills an Iterator with designated Entities (includes Next)

    	-- --    Internal Queries, also used by EntityList    -- --

    IsLocalFull (me) returns Boolean  is static private;
    ---Purpose : Returns True if all the set of entities local to a Cluster is
    --           full. Used by EntityList.

    NbLocal (me) returns Integer  is static private;
    ---Purpose : Returns count of entities in the local set (without Next)
    --           Entities can then be read normally by method Value

    HasNext (me) returns Boolean  is static private;
    ---Purpose : Returns True if a Cluster has a Next

    Next (me) returns mutable EntityCluster  is static private;
    ---Purpose : Returns Next Cluster in the chain

fields

    theents : Transient[4];   -- 4 : best compromise for memory use
    thenext : EntityCluster;

friends

    class EntityList  -- of which EntityCluster stores content

end EntityCluster;