assoc interface description

crux-00047: $SRC/assoc/README.assoc

* "assoc": key-value arrays of xpr expressions

  Assocs are maps from xpr expressions to xpr expressions.

  Adding, finding, and deleting key-value pairs from
  an assoc are all linear operations.   

  The interface is largely self evident.

  An associative array of xprs is properly declared and initialized this way:

      #include "strt/strt.h"
      #include "tup/tup.h"
      #include "tupt/tupt.h"
      #include "assoc/assoc.h"
      #include "xpr/xpr.h"

      struct assoc an_assoc = {0};

    int assoc_length (struct tup *);
      Return the current number of entries.

    void assoc_bind (struct assoc *,
                     struct xpr_ref * key,
                     struct xpr_ref * value);

      Bind (or rebind) a key.

    int assoc_lookup (struct xpr_ref * out,
                      struct assoc *,
                      struct xpr_ref * key);
      Lookup and retrieve a binding.  

      Returns 1 if a binding is found, 0 otherwise.

      0 may be passed for 'out' if the value is not needed.

    void assoc_kv (struct xpr_ref * ok,
                   struct xpr_ref * ov,
                   struct assoc *,
                   int n);
      Return the nth key value pair from an assoc.
      0 may be passed for ok and ov.

    int assoc_delete (struct assoc *, struct xpr_ref * key);
      Remove a binding.  Return 1 if a binding was found, 0 otherwise.
      
    void assoc_clear (struct assoc *, struct xpr_ref * key);
      Remove all bindings.

    void assoc_trim (struct assoc *);
      Compact an assoc in memory if possible (after deletions).

    void assoc_copy (struct assoc *, struct assoc *);
      Copy an assoc.

/*
    Copyright (C) 2015 Thomas Lord (Berkeley, CA;  lord@basiscraft.com)

    This file is part of Crux.

    Crux is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Crux is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Crux.  If not, see <http://www.gnu.org/licenses/>.

*/

/*

    This file is part of Crux.

    Crux is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Crux is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Crux.  If not, see <http://www.gnu.org/licenses/>.

*/