# [hmap.h] Type: Finite Map

## contents

#include "standard.h"
#include "prim.h"

       [hmap] implements finite maps based on dynamic hashing.

## Types and macros

HMP_Dom | Abstract domain type of maps
HMP_Rng | Abstract range type of maps

    #define MAP(Alpha,Beta)   HMP_Map          /* Polymorphic MAP - Type        */
    #define MAPIT             HMP_Itr          /* Polymorphic ITR - Type        */
    #define MAPTY             HMP_Typ          /* Polymorphic meta-type of MAPs */

HMP_Typ | Abstract meta-type of maps

HMP_Map | Abstract type of maps

## Meta type of hash maps

    HMP_Typ HMP_newTyp
            (
              HMP_Dom (*domcpy)(HMP_Dom a),
              void    (*domfre)(HMP_Dom a),
              c_bool    (*domequ)(HMP_Dom a, HMP_Dom b),
              long    (*domhsh)(HMP_Dom a),
              HMP_Rng (*rngcpy)(HMP_Rng a),
              void    (*rngfre)(HMP_Rng a)
            )
    #define MAP_newTyp(dc, df, de, dh, rc, rf)                 \
            HMP_newTyp(                                        \
                        (HMP_Dom (*)(HMP_Dom a))           dc, \
                        (void    (*)(HMP_Dom a))           df, \
                        (c_bool    (*)(HMP_Dom a,HMP_Dom b)) de, \
                        (long    (*)(HMP_Dom a))           dh, \
                        (HMP_Rng (*)(HMP_Rng a))           rc, \
                        (void    (*)(HMP_Rng a))           rf  \
                      )
| defines a new hash type function parameter: copies a domain frees a domain equality on domains hash value of domain copies a range frees a range
    void HMP_freeTyp( HMP_Typ t )
    #define MAP_freeTyp HMP_freeTyp
| frees hash type 't'
    HMP_Dom (*HMP_domcpy(HMP_Typ t))(HMP_Dom a)
    #define MAP_domcpy(Alpha,t) ((Alpha (*)(Alpha a))          HMP_domcpy(t))
| get domain copy function of hash type 't'
    void (*HMP_domfre(HMP_Typ t))(HMP_Dom a)
    #define MAP_domfre(Alpha,t) ((void  (*)(Alpha a))          HMP_domfre(t))
| get domain free function of hash type 't'
    c_bool (*HMP_domequ(HMP_Typ t))(HMP_Dom a, HMP_Dom b)
    #define MAP_domequ(Alpha,t) ((c_bool  (*)(Alpha a, Alpha b)) HMP_domequ(t))
| get domain equal function of hash type 't'
    long (*HMP_domhsh(HMP_Typ t))(HMP_Dom a)
    #define MAP_domhsh(Alpha,t) ((long  (*)(Alpha a))          HMP_domhsh(t))
| get domain hash function of hash type 't'
    HMP_Rng (*HMP_rngcpy(HMP_Typ t))(HMP_Rng a)
    #define MAP_rngcpy(Beta ,t) ((Beta  (*)(Beta  a))          HMP_rngcpy(t))
| get range copy function of hash type 't'
    void (*HMP_rngfre(HMP_Typ t))(HMP_Rng a)
    #define MAP_rngfre(Beta ,t) ((void  (*)(Beta  a))          HMP_rngfre(t))
| get range free function of hash type 't'

## Hash Maps

## Creating & Disposing

    HMP_Map HMP_newMap( HMP_Typ t )
    #define MAP_newMap  HMP_newMap
| creates a new empty map
    void HMP_freeMap(HMP_Map m)
    #define MAP_freeMap HMP_freeMap
| removes map 'm' from storage all references to 'm' are invalidated!

## Accessing

    HMP_Typ HMP_MapTyp(HMP_Map m)
    #define MAP_MapTyp HMP_MapTyp
| get meta-type of map 'm'
    long HMP_count(HMP_Map m)
    #define MAP_count HMP_count
| number of domain values on which map 'm' is defined HMP_count(m) == | { d in HMP_Dom | HMP_defined(m,d) } |
    c_bool HMP_emptyMap(HMP_Map m)
    #define MAP_emptyMap HMP_emptyMap
| whether map 'm' is empty HMP_emptyMap(m) == (HMP_count(m) == 0)
    c_bool HMP_defined( HMP_Map m,  HMP_Dom d)
    #define MAP_defined(m,d) HMP_defined(m,(HMP_Dom)(d))
| con con whether domain 'd' is defined in map 'm'
    HMP_Rng HMP_apply( HMP_Map m,  HMP_Dom d)
    #define MAP_apply(Beta,m,d)       ABS_CAST(Beta,HMP_apply(m,(HMP_Dom)(d)))
    #define MAP_apply_small(Beta,m,d) ((Beta)((long)HMP_apply(m,(HMP_Dom)(d))))
    #define MAP_apply_short(m,d)      ((short)((long)HMP_apply(m,(HMP_Dom)(d))))
| con con get range of domain 'd' in map 'm' raises execption if not HMP_defined(m,d)

## Modifying

    void HMP_ovrdom( HMP_Map m,  HMP_Dom d,  HMP_Rng r)
    #define MAP_ovrdom(m,d,r) HMP_ovrdom(m,ABS_CAST(HMP_Dom,d),ABS_CAST(HMP_Rng,r))
| var con con defines pair ( 'd', 'r' ) or updates range of domain 'd' in map 'm' m := m \ { (d, r) }
    void HMP_dfndom( HMP_Map m,  HMP_Dom d,  HMP_Rng r)
    #define MAP_dfndom(m,d,r) HMP_dfndom(m,ABS_CAST(HMP_Dom,d),ABS_CAST(HMP_Rng,r))
    #define MAP_define        MAP_dfndom
| var con con defines pair ( 'd', 'r' ) in map'm' m := m U { (d, r) }; raises exception if HMP_defined(m,d)
    void HMP_upddom( HMP_Map m,  HMP_Dom d,  HMP_Rng r)
    #define MAP_upddom(m,d,r) HMP_upddom(m,(HMP_Dom)(d),(HMP_Rng)(r))
    #define MAP_update        MAP_upddom
| var con con updates range of domain 'd' in map 'm' m := m \ { (d, r) }; raises exception if not HMP_defined(m,d)
    void HMP_rmvdom( HMP_Map m,  HMP_Dom d)
    #define MAP_rmvdom(m,d) HMP_rmvdom(m,(HMP_Dom)(d))
    #define MAP_remove      MAP_rmvdom
| con con removes domain 'd' from map 'm' makes m(d) be undefined; raises exception if not HMP_defined(m,d)
    void HMP_rmvall( HMP_Map m)
    #define MAP_rmvall HMP_rmvall
| var clears map 'm' makes m(d) be undefined for all d

## Basic hash set iterator

     Do not modify the content of an hash set
         while using a basic iterator on this set.

HMP_Itr | Abstract type of iterators on maps

## Creating & Disposing

    HMP_Itr HMP_newItr(HMP_Map m)
    #define MAP_newItr HMP_newItr
| creates an iterator on hash set 'm'
    void HMP_freeItr(HMP_Itr i)
    #define MAP_freeItr HMP_freeItr
| removes iterator 'i'

## Accessing & Modifiying

    c_bool HMP_emptyItr(HMP_Itr i)
    #define MAP_emptyItr HMP_emptyItr
| whether iterator 'i' is empty
    void HMP_getItr(HMP_Itr i, HMP_Dom *d)
    #define MAP_getItr(i,d) HMP_getItr(i,(HMP_Dom *) d)
| get the next domain from iterator 'i' into 'd' raises exception if 'HMP_emptyItr(i)'
    void HMP_getItrAsg(HMP_Itr i, HMP_Dom *d, HMP_Rng *r)
    #define MAP_getItrAsg(i,d,r) HMP_getItrAsg(i,(HMP_Dom *)(d),(HMP_Rng *)(r))
| get the next pair ( domain, range ) from iterator 'i' into 'd' and 'r' raises exception if 'HMP_emptyItr(i)'

## Convenient iterator macros

     For - statement with basic iterators. Make sure to
         free the iterator if you leave the loop via break.

    #define MAP_forItr(DomVar,ItrVar,MapExpr)           \
            for (ItrVar = MAP_newItr(MapExpr);          \
                 MAP_emptyItr(ItrVar)                   \
                 ? (MAP_freeItr(ItrVar),         C_False) \
                 : (MAP_getItr(ItrVar, &DomVar), C_True );\
                )

    #define MAP_forItrAsg(DomVar,RngVar,ItrVar,MapExpr)             \
            for (ItrVar = MAP_newItr(MapExpr);                      \
                 MAP_emptyItr(ItrVar)                               \
                 ? (MAP_freeItr(ItrVar),         C_False)             \
                 : (MAP_getItrAsg(ItrVar, &DomVar, &RngVar), C_True );\
                )

## Operations on maps

    MAP(_,_) MAP_copy(MAP(_,_) a)
| copies map 'a'; The result map references the type of map 'a'.

## Printing

    void HMP_fprintMap
         (
           FILE     *f,
           HMP_Map   m,
           int       indent,
           void    (*fprintPair)(FILE *f, HMP_Dom d, HMP_Rng r, int indent)
         )
    #define MAP_fprintMap HMP_fprintMap
| prints map 'm' to file 'f'
    void HMP_printMap
         (
           HMP_Map  m,
           int      indent,
           void    (*printPair)(HMP_Dom d, HMP_Rng r, int indent)
         )
    #define MAP_printMap HMP_printMap
| prints map 'm' to 'stdout'

## Debugging & Profiling

    void HMP_technicalView
         (
           HMP_Map m,
           int     indent,
           void  (*printPair)(HMP_Dom d, HMP_Rng r, int indent)
         )
| For visual inspection and debugging purposes

## Primitive Maps

       Primitive maps have an implicit meta-type which treats the
       domain and range values as anonymous pointer.
       The domain / range copy function return the element itself.
       The domain / range free function do nothing.
       The domain equal function performs a simple '==' operation.
       The domain hash function simply hashes the domain ( pointer ) value.

    void MAP_init(void)
| inits this module ( create meta-type )
    void MAP_quit(void)
| quits this module ( free meta-type )
     MAP(_,_) MAP_newPrimMap(void)
| creates a primitive map
    c_bool MAP_prim_equal(MAP(_,_) a, MAP(_,_) b)
| whether the primitive maps 'a' and 'b' are equal
     MAP(_,_) MAP_prim_copy(MAP(_,_) a)
| copies the primitive map 'a'