-- File:	Interface_BitMap.cdl
-- Created:	Fri Sep  1 10:01:00 1995
-- Author:	Christian CAILLET
--		<cky@fidox>
---Copyright:	 Matra Datavision 1995


class BitMap  from Interface

    ---Purpose : A bit map simply allows to associate a boolean flag to each
    --           item of a list, such as a list of entities, etc... numbered
    --           between 1 and a positive count nbitems
    --           
    --           The BitMap class allows to associate several binary flags,
    --           each of one is identified by a number from 0 to a count
    --           which can remain at zero or be positive : nbflags
    --           
    --           Flags lists over than numflag=0 are added after creation
    --           Each of one can be named, hence the user can identify it
    --           either by its flag number or by a name which gives a flag n0
    --           (flag n0 0 has no name)

uses CString, HSequenceOfAsciiString from TColStd,
     HArray1OfInteger from TColStd

is

    Create (nbitems : Integer; resflags : Integer = 0) returns BitMap;
    ---Purpose : Creates a BitMap for <nbitems> items
    --           One flag is defined, n0 0
    --           <resflags> prepares allocation for <resflags> more flags
    --           Flags values start at false

    Create (other : BitMap; copied : Boolean = Standard_False) returns BitMap;
    ---Purpose : Creates a BitMap from another one
    --           if <copied> is True, copies data
    --           else, data are not copied, only the header object is

    Internals (me; nbitems , nbwords, nbflags : out Integer;
    	       flags : out mutable HArray1OfInteger;
    	       names : out mutable HSequenceOfAsciiString);
    ---Purpose : Returns internal values, used for copying
    --           Flags values start at false

    Reservate (me : in out; moreflags : Integer);
    ---Purpose : Reservates for a count of more flags

    SetLength (me : in out; nbitems : Integer);
    ---Purpose : Sets for a new count of items, which can be either less or
    --           greater than the former one
    --           For new items, their flags start at false

    AddFlag (me : in out; name : CString = "") returns Integer;
    ---Purpose : Adds a flag, a name can be attached to it
    --           Returns its flag number
    --           Makes required reservation

    AddSomeFlags (me : in out; more : Integer) returns Integer;
    ---Purpose : Adds several flags (<more>) with no name
    --           Returns the number of last added flag

    RemoveFlag   (me : in out; num : Integer) returns Boolean;
    ---Purpose : Removes a flag given its number.
    --           Returns True if done, false if num is out of range

    SetFlagName  (me : in out; num : Integer; name : CString) returns Boolean;
    ---Purpose : Sets a name for a flag, given its number
    --           name can be empty (to erase the name of a flag)
    --           Returns True if done, false if : num is out of range, or
    --           name non-empty already set to another flag

    NbFlags (me) returns Integer;
    ---Purpose : Returns the count of flags (flag 0 not included)

    Length  (me) returns Integer;
    ---Purpose : Returns the count of items (i.e. the length of the bitmap)

    FlagName (me; num : Integer) returns CString;
    ---Purpose : Returns the name recorded for a flag, or an empty string

    FlagNumber (me; name : CString) returns Integer;
    ---Purpose : Returns the number or a flag given its name, or zero

    	--  Access to flag values  --

    Value (me; item : Integer; flag : Integer = 0) returns Boolean;
    ---Purpose : Returns the value (true/false) of a flag, from :
    --           - the number of the item
    --           - the flag number, by default 0

    SetValue (me; item : Integer; val : Boolean; flag : Integer = 0);
    ---Purpose : Sets a new value for a flag

    SetTrue  (me; item : Integer; flag : Integer = 0);
    ---Purpose : Sets a flag to True

    SetFalse (me; item : Integer; flag : Integer = 0);
    ---Purpose : Sets a flag to False

    CTrue    (me; item : Integer; flag : Integer = 0) returns Boolean;
    ---Purpose : Returns the former value for a flag and sets it to True
    --           (before : value returned; after : True)

    CFalse   (me; item : Integer; flag : Integer = 0) returns Boolean;
    ---Purpose : Returns the former value for a flag and sets it to False
    --           (before : value returned; after : False)

    Init (me; val : Boolean; flag : Integer = 0);
    ---Purpose : Initialises all the values of Flag Number <flag> to a given
    --           value <val>

fields

    thenbitems : Integer;
    thenbwords : Integer;
    thenbflags : Integer;
    theflags   : HArray1OfInteger;
    thenames   : HSequenceOfAsciiString;

end BitMap;