(*
4.2 Discrete Map Interface

This section provides the definition module for the Map abstraction
described in the previous chapter. In this variant, the domain and
range are constrained to discrete values representable using the CHAR
basic data type. Thus, characters and enumerations can be used as either
a domain or range or both. Domains may be further restricted to any
contiguous subrange, for example the capital letters A through Z from
the ASCII character set. The same is true for ranges.
*)

DEFINITION MODULE MapDSBMI;
(*====================================================================
    Version  : 2.0 16 Sep 1990 C. Lins
    Compiler : Generic pc Modula-2
    Component: Monolithic Structures - Map (Opaque version)
               Discrete Sequential Bounded Managed Iterator

    INTRODUCTION
    This module provides operations for the discrete map abstract
   data type.

    REVISION HISTORY
    v1.01  04 May 1988  C. Lins
      Initial implementation for TML Modula-2.
   v2.00  16 Sep 1990  C. Lins
     Created generic pc version
   (C) Copyright 1990 Charles A. Lins
=====================================================================*)

FROM MapTypes IMPORT
    (*--Type*) Exceptions;

FROM ErrorHandling IMPORT
    (*--Type*) HandlerProc;

FROM TypeManager IMPORT
    (*--Type*) TypeID;


    (*-----------------------*)

(*
4.2.1  Type Declarations
*)

TYPE  Item   = [0 .. 255];	(*-- !! WARNING: Changed from BYTE *)
TYPE  Domain = Item;
TYPE  Range  = Item;

TYPE  DomainType = RECORD
        dataType : TypeID; (*-- data type id for Domain *)
        first    : Domain; (*-- first element of Domain *)
        last     : Domain; (*-- last element of Domain *)
      END (*--DomainType*);

TYPE  RangeType = RECORD
        dataType  : TypeID; (*-- data type id for Range *)
        first     : Range;  (*-- first element of Range *)
        last      : Range;  (*-- last element of Range *)
        undefined : Range;  (*-- undefined element of Range *)
      END (*--RangeType*);

TYPE  Map;
VAR   NullMap : Map;


(*---------------------------------*)
(*--          EXCEPTIONS         --*)

CONST ModuleID = 1;

PROCEDURE MapError   ()              : Exceptions  (*-- out   *);

PROCEDURE GetHandler (    theError   : Exceptions  (*-- in    *))
                                     : HandlerProc (*-- out   *);

PROCEDURE SetHandler (    theError   : Exceptions  (*-- in    *);
                          theHandler : HandlerProc (*-- in    *));


(*---------------------------------*)
(*--        CONSTRUCTORS         --*)

PROCEDURE Create  (    theDomain : DomainType (*-- in    *);
                       theRange  : RangeType  (*-- in    *))
                                 : Map        (*-- out   *);

PROCEDURE Destroy (VAR theMap    : Map        (*-- inout *));

PROCEDURE Clear   (VAR theMap    : Map        (*-- inout *));

PROCEDURE Assign  (    theMap    : Map        (*-- in    *);
                   VAR toMap     : Map        (*-- inout *));

PROCEDURE Bind    (VAR theMap    : Map        (*-- inout *);
                       theItemIn : Domain     (*-- in    *);
                       toItemIn  : Range      (*-- in    *));

PROCEDURE Unbind  (VAR theMap    : Map        (*-- inout *);
                       theItemIn : Domain     (*-- in    *));


(*---------------------------------*)
(*--         SELECTORS           --*)

PROCEDURE IsDefined (    theMap    : Map        (*-- in    *))
                                   : BOOLEAN    (*-- out   *);

PROCEDURE IsEmpty   (    theMap    : Map        (*-- in    *))
                                   : BOOLEAN    (*-- out   *);

PROCEDURE IsEqual   (    left      : Map        (*-- in    *);
                         right     : Map        (*-- in    *))
                                   : BOOLEAN    (*-- out   *);

PROCEDURE ExtentOf  (    theMap    : Map        (*-- in    *))
                                   : CARDINAL   (*-- out   *);

PROCEDURE DomainOf  (    theMap    : Map        (*-- in    *);
                     VAR theDomain : DomainType (*-- out   *));

PROCEDURE RangeOf   (    theMap    : Map        (*-- in    *);
                     VAR theRange  : RangeType  (*-- out   *));

PROCEDURE IsBound   (    theMap    : Map        (*-- in    *);
                         theItem   : Domain     (*-- in    *))
                                   : BOOLEAN    (*-- out   *);

PROCEDURE BoundTo   (    theMap    : Map        (*-- in    *);
                         theItem   : Domain     (*-- in    *))
                                   : Range      (*-- out   *);

PROCEDURE IsBoundTo (    theMap    : Map        (*-- in    *);
                         theItem   : Domain     (*-- in    *);
                     VAR toItem    : Range      (*-- out   *))
                                   : BOOLEAN    (*-- out   *);


(*---------------------------------*)
(*--         ITERATORS           --*)

TYPE  LoopAccessProc = PROCEDURE (Domain, Range) : BOOLEAN;
TYPE  LoopChangeProc = PROCEDURE (Domain, VAR Range) : BOOLEAN;

PROCEDURE LoopOver   (    theMap    : Map            (*-- in    *);
                          theProcess: LoopAccessProc (*-- in    *));

PROCEDURE LoopChange (    theMap    : Map            (*-- in    *);
                          theProcess: LoopChangeProc (*-- in    *));


TYPE  AccessProc = PROCEDURE (Domain, Range);
TYPE  ChangeProc = PROCEDURE (Domain, VAR Range);

PROCEDURE Traverse   (    theMap    : Map            (*-- in    *);
                          theProcess: AccessProc     (*-- in    *));

PROCEDURE TravChange (    theMap    : Map            (*-- in    *);
                          theProcess: ChangeProc     (*-- in    *));

END MapDSBMI.