(*!m2pim*) (* Copyright (c) 2017 Modula-2 Software Foundation. *)

DEFINITION MODULE Dictionary;

(* Key/Value Dictionary *)

IMPORT String;

FROM String IMPORT StringT; (* alias for String.String *)


(* Key type *)

TYPE Key = StringT;


(* Value type *)

TYPE Value = StringT;


(* Status type *)

TYPE Status =
  ( Success,
    KeyAlreadyPresent,
    EntryNotFound,
    NilNotPermitted,
    AllocationFailed );


(* Procedure type for passing to procedure WithKeyValuePairsDo *)

TYPE VisitorProc = PROCEDURE ( Key, Value );


(* Invalid key and value sentinels *)

CONST
  NilKey = String.Nil;
  NilValue = String.Nil;


(* Introspection *)

(* ---------------------------------------------------------------------------
 * function Dictionary.count()
 * ---------------------------------------------------------------------------
 * Returns the number of key/value pairs in the global dictionary.
 * Does not set dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE count ( ) : CARDINAL;


(* ---------------------------------------------------------------------------
 * function Dictionary.status()
 * ---------------------------------------------------------------------------
 * Returns the status of the last operation on the global dictionary.
 * Does not set dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE status ( ) : Status;


(* Lookup Operations *)

(* ---------------------------------------------------------------------------
 * function Dictionary.isPresent(key)
 * ---------------------------------------------------------------------------
 * Returns TRUE if key is present in the global dictionary, else FALSE.
 * Fails and returns NIL if key is NIL.  Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE isPresent ( key : Key ) : BOOLEAN;


(* ---------------------------------------------------------------------------
 * function Dictionary.valueForKey(key)
 * ---------------------------------------------------------------------------
 * Returns the value stored for key in the global dictionary, or NIL if no key 
 * is present in the dictionary. Fails if key is NIL. Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE valueForKey ( key : Key ) : Value;


(* Insert Operations *)

(* ---------------------------------------------------------------------------
 * procedure Dictionary.StoreValueForKey(key, value)
 * ---------------------------------------------------------------------------
 * Stores value for key in the global dictionary.  Fails if key or value or
 * both are NIL.  Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE StoreValueForKey ( key : Key; value : Value );


(* ---------------------------------------------------------------------------
 * procedure Dictionary.StoreArrayForKey(key, array)
 * ---------------------------------------------------------------------------
 * Obtains an interned string for array, then stores the string as value for
 * key in the global dictionary.  Fails if key is NIL or if array produces a
 * NIL string.  Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE StoreArrayForKey
  ( key : Key; VAR (* CONST *) array : ARRAY OF CHAR );


(* Removal Operations *)

(* ---------------------------------------------------------------------------
 * procedure Dictionary.RemoveKey(key)
 * ---------------------------------------------------------------------------
 * Removes key and its value from the global dictionary.  Fails if key is NIL
 * or if key is not present in the dictionary.  Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE RemoveKey ( key : Key );


(* Iteration *)

(* ---------------------------------------------------------------------------
 * procedure Dictionary.WithKeyValuePairsDo(p)
 * ---------------------------------------------------------------------------
 * Iterates over all key/value pairs in the global dictionary in key order
 * and calls calls visitor procedure p for each pair, passing key and value.
 * Keys are ordered in ASCII collation order.  Sets dictionary status.
 * ------------------------------------------------------------------------ *)

PROCEDURE WithKeyValuePairsDo ( p : VisitorProc );


END Dictionary.