ncd: NCDVal: Add documentation. Rename NCDVal_Map{First,Next} to NCDVal_MapOrdered{First,Next}, and implement the former

as unordered iteration. Fix bug in NCDVal_Compare() for maps.

ncd/NCDVal.c

@@ -161,15 +161,28 @@ static NCDValMapElem NCDVal__MapElem (NCDVal__idx elemidx)
     return me;
 }
 
-static void NCDVal__MapAssertElem (NCDValRef map, NCDValMapElem me)
+static void NCDVal__MapAssertElemOnly (NCDValRef map, NCDVal__idx elemidx)
 {
-    ASSERT(NCDVal_IsMap(map))
-    ASSERT(me.elemidx >= map.idx + offsetof(struct NCDVal__map, elems))
-    ASSERT(me.elemidx < map.idx + offsetof(struct NCDVal__map, elems) + NCDVal_MapCount(map) * sizeof(struct NCDVal__mapelem))
-    
-    struct NCDVal__mapelem *me_e = NCDValMem__BufAt(map.mem, me.elemidx);
+#ifndef NDEBUG
+    struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
+    ASSERT(elemidx >= map.idx + offsetof(struct NCDVal__map, elems))
+    ASSERT(elemidx < map.idx + offsetof(struct NCDVal__map, elems) + map_e->count * sizeof(struct NCDVal__mapelem))
+
+    struct NCDVal__mapelem *me_e = NCDValMem__BufAt(map.mem, elemidx);
     NCDVal__AssertValOnly(map.mem, me_e->key_idx);
     NCDVal__AssertValOnly(map.mem, me_e->val_idx);
+#endif
+}
+
+static void NCDVal__MapAssertElem (NCDValRef map, NCDValMapElem me)
+{
+    ASSERT(NCDVal_IsMap(map))
+    NCDVal__MapAssertElemOnly(map, me.elemidx);
+}
+
+static NCDVal__idx NCDVal__MapElemIdx (NCDVal__idx mapidx, NCDVal__idx pos)
+{
+    return mapidx + offsetof(struct NCDVal__map, elems) + pos * sizeof(struct NCDVal__mapelem);
 }
 
 #include "NCDVal_maptree.h"
@@ -320,13 +333,13 @@ int NCDVal_Compare (NCDValRef val1, NCDValRef val2)
         } break;
         
         case NCDVAL_MAP: {
-            NCDValMapElem e1 = NCDVal_MapFirst(val1);
-            NCDValMapElem e2 = NCDVal_MapFirst(val2);
+            NCDValMapElem e1 = NCDVal_MapOrderedFirst(val1);
+            NCDValMapElem e2 = NCDVal_MapOrderedFirst(val2);
             
             while (1) {
                 int inv1 = NCDVal_MapElemInvalid(e1);
                 int inv2 = NCDVal_MapElemInvalid(e2);
-                if (inv1 + inv2 < 2) {
+                if (inv1 || inv2) {
                     return inv2 - inv1;
                 }
                 
@@ -346,8 +359,8 @@ int NCDVal_Compare (NCDValRef val1, NCDValRef val2)
                     return cmp;
                 }
                 
-                e1 = NCDVal_MapNext(val1, e1);
-                e2 = NCDVal_MapNext(val2, e2);
+                e1 = NCDVal_MapOrderedNext(val1, e1);
+                e2 = NCDVal_MapOrderedNext(val2, e2);
             }
         } break;
         
@@ -630,7 +643,7 @@ int NCDVal_MapInsert (NCDValRef map, NCDValRef key, NCDValRef val)
     
     struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
     
-    NCDVal__idx elemidx = map.idx + offsetof(struct NCDVal__map, elems) + map_e->count * sizeof(struct NCDVal__mapelem);
+    NCDVal__idx elemidx = NCDVal__MapElemIdx(map.idx, map_e->count);
     
     struct NCDVal__mapelem *me_e = NCDValMem__BufAt(map.mem, elemidx);
     ASSERT(me_e == &map_e->elems[map_e->count])
@@ -678,18 +691,56 @@ NCDValMapElem NCDVal_MapFirst (NCDValRef map)
     
     struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
     
+    if (map_e->count == 0) {
+        return NCDVal__MapElem(-1);
+    }
+    
+    NCDVal__idx elemidx = NCDVal__MapElemIdx(map.idx, 0);
+    NCDVal__MapAssertElemOnly(map, elemidx);
+    
+    return NCDVal__MapElem(elemidx);
+}
+
+NCDValMapElem NCDVal_MapNext (NCDValRef map, NCDValMapElem me)
+{
+    NCDVal__MapAssertElem(map, me);
+    
+    struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
+    ASSERT(map_e->count > 0)
+    
+    NCDVal__idx last_elemidx = NCDVal__MapElemIdx(map.idx, map_e->count - 1);
+    ASSERT(me.elemidx <= last_elemidx)
+    
+    if (me.elemidx == last_elemidx) {
+        return NCDVal__MapElem(-1);
+    }
+    
+    NCDVal__idx elemidx = me.elemidx + sizeof(struct NCDVal__mapelem);
+    NCDVal__MapAssertElemOnly(map, elemidx);
+    
+    return NCDVal__MapElem(elemidx);
+}
+
+NCDValMapElem NCDVal_MapOrderedFirst (NCDValRef map)
+{
+    ASSERT(NCDVal_IsMap(map))
+    
+    struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
+    
     NCDVal__MapTreeNode ref = NCDVal__MapTree_GetFirst(&map_e->tree, map.mem);
+    ASSERT(ref.link == -1 || (NCDVal__MapAssertElemOnly(map, ref.link), 1))
     
     return NCDVal__MapElem(ref.link);
 }
 
-NCDValMapElem NCDVal_MapNext (NCDValRef map, NCDValMapElem me)
+NCDValMapElem NCDVal_MapOrderedNext (NCDValRef map, NCDValMapElem me)
 {
     NCDVal__MapAssertElem(map, me);
     
     struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
     
     NCDVal__MapTreeNode ref = NCDVal__MapTree_GetNext(&map_e->tree, map.mem, NCDVal__MapTree_Deref(map.mem, me.elemidx));
+    ASSERT(ref.link == -1 || (NCDVal__MapAssertElemOnly(map, ref.link), 1))
     
     return NCDVal__MapElem(ref.link);
 }
@@ -724,6 +775,7 @@ NCDValMapElem NCDVal_MapFindKey (NCDValRef map, NCDValRef key)
     struct NCDVal__map *map_e = NCDValMem__BufAt(map.mem, map.idx);
     
     NCDVal__MapTreeNode ref = NCDVal__MapTree_LookupExact(&map_e->tree, map.mem, key);
+    ASSERT(ref.link == -1 || (NCDVal__MapAssertElemOnly(map, ref.link), 1))
     
     return NCDVal__MapElem(ref.link);
 }

ncd/NCDVal.h

@@ -36,6 +36,8 @@
 #include <misc/debug.h>
 #include <structure/CAvl.h>
 
+// these are implementation details. The interface is defined below.
+
 #define NCDVAL_FASTBUF_SIZE 64
 #define NCDVAL_FIRST_SIZE 256
 
@@ -104,48 +106,310 @@ typedef struct {
 #define NCDVAL_LIST 2
 #define NCDVAL_MAP 3
 
+/**
+ * Initializes a value memory object.
+ * A value memory object holds memory for value structures. Values within
+ * the memory are referenced using {@link NCDValRef} objects, which point
+ * to values within memory objects.
+ * 
+ * Values may be added to a memory object using functions such as
+ * {@link NCDVal_NewString}, {@link NCDVal_NewList} and {@link NCDVal_NewMap},
+ * and {@link NCDVal_NewCopy}, which return references to the new values within
+ * the memory object.
+ * 
+ * It is not possible to remove values from the memory object, or modify existing
+ * values other than adding elements to pre-allocated slots in lists and maps.
+ * Once a value is added, it will consume memory as long as its memory object
+ * exists. This is by design - this code is intended and optimized for constructing
+ * and passing around values, not for operating on them in place. In fact, al
+ * values within a memory object are stored in a single memory buffer, as an
+ * embedded data structure with relativepointers. For example, map values use an
+ * embedded AVL tree.
+ */
 void NCDValMem_Init (NCDValMem *o);
+
+/**
+ * Frees a value memory object.
+ * All values within the memory object cease to exist, and any {@link NCDValRef}
+ * object pointing to them must no longer be used.
+ */
 void NCDValMem_Free (NCDValMem *o);
 
+/**
+ * Does nothing.
+ * The value reference object must either point to a valid value within a valid
+ * memory object, or must be an invalid reference (all functions operating on
+ * {@link NCDValRef} implicitly require that).
+ */
 void NCDVal_Assert (NCDValRef val);
+
+/**
+ * Determines if a value reference is invalid.
+ */
 int NCDVal_IsInvalid (NCDValRef val);
+
+/**
+ * Returns the type of the value reference, which must not be an invalid reference.
+ * Possible values are NCDVAL_STRING, NCDVAL_LIST and NCDVAL_MAP.
+ */
 int NCDVal_Type (NCDValRef val);
+
+/**
+ * Returns an invalid reference.
+ */
 NCDValRef NCDVal_NewInvalid (void);
+
+/**
+ * Copies a value into the specified memory object. The source
+ * must not be an invalid reference, but may reside in a different
+ * memory object.
+ * Returns a reference to the copied value. On out of memory, returns
+ * an invalid reference.
+ */
 NCDValRef NCDVal_NewCopy (NCDValMem *mem, NCDValRef val);
+
+/**
+ * Compares two values, both of which must not be invalid references.
+ * Returns -1, 0 or 1.
+ */
 int NCDVal_Compare (NCDValRef val1, NCDValRef val2);
 
+/**
+ * Converts a value reference to a safe referece format, which remains valid
+ * if the memory object is moved (safe references do not contain a pointer
+ * to the memory object, unlike {@link NCDValRef} references).
+ */
 NCDValSafeRef NCDVal_ToSafe (NCDValRef val);
+
+/**
+ * Converts a safe value reference to a normal value reference.
+ * This should be used to recover references from safe references
+ * after the memory object is moved.
+ */
 NCDValRef NCDVal_FromSafe (NCDValMem *mem, NCDValSafeRef sval);
+
+/**
+ * Fixes a value reference after its memory object was moved.
+ */
 NCDValRef NCDVal_Moved (NCDValMem *mem, NCDValRef val);
 
+/**
+ * Determines if a value is a string value.
+ * The value reference must not be an invalid reference.
+ */
 int NCDVal_IsString (NCDValRef val);
+
+/**
+ * Determines if a value is a string value which has no null bytes.
+ * The value reference must not be an invalid reference.
+ */
 int NCDVal_IsStringNoNulls (NCDValRef val);
+
+/**
+ * Builds a new string value from a null-terminated array of bytes.
+ * Equivalent to NCDVal_NewStringBin(mem, data, strlen(data)).
+ * Returns a reference to the new value, or an invalid reference
+ * on out of memory.
+ */
 NCDValRef NCDVal_NewString (NCDValMem *mem, const char *data);
+
+/**
+ * Builds a new string value.
+ * Returns a reference to the new value, or an invalid reference
+ * on out of memory.
+ */
 NCDValRef NCDVal_NewStringBin (NCDValMem *mem, const uint8_t *data, size_t len);
+
+/**
+ * Returns a pointer to the data of a string value. An extra null byte
+ * is always appended to the actual contents of the string.
+ * The value reference must point to a string value.
+ */
 const char * NCDVal_StringValue (NCDValRef string);
+
+/**
+ * Returns the length of the string value, excluding the automatically
+ * appended null byte.
+ * The value reference must point to a string value.
+ */
 size_t NCDVal_StringLength (NCDValRef string);
+
+/**
+ * Determines if the string value has any null bytes in its contents,
+ * i.e. that length > strlen().
+ * The value reference must point to a string value.
+ */
 int NCDVal_StringHasNulls (NCDValRef string);
+
+/**
+ * Determines if the string value is equal to the given null-terminated
+ * string.
+ * The value reference must point to a string value.
+ */
 int NCDVal_StringEquals (NCDValRef string, const char *data);
 
+/**
+ * Determines if a value is a list value.
+ * The value reference must not be an invalid reference.
+ */
 int NCDVal_IsList (NCDValRef val);
+
+/**
+ * Builds a new list value. The 'maxcount' argument specifies how
+ * many element slots to preallocate. Not more than that many
+ * elements may be appended to the list using {@link NCDVal_ListAppend}.
+ * Returns a reference to the new value, or an invalid reference
+ * on out of memory.
+ */
 NCDValRef NCDVal_NewList (NCDValMem *mem, size_t maxcount);
+
+/**
+ * Appends a value to to the list value.
+ * The 'list' reference must point to a list value, and the
+ * 'elem' reference must be non-invalid and point to a value within
+ * the same memory object as the list.
+ * Inserting a value into a list does not in any way change it;
+ * internally, the list only points to it.
+ */
 void NCDVal_ListAppend (NCDValRef list, NCDValRef elem);
+
+/**
+ * Returns the number of elements in a list value, i.e. the number
+ * of times {@link NCDVal_ListAppend} was called.
+ * The 'list' reference must point to a list value.
+ */
 size_t NCDVal_ListCount (NCDValRef list);
+
+/**
+ * Returns the maximum number of elements a list value may contain,
+ * i.e. the 'maxcount' argument to {@link NCDVal_NewList}.
+ * The 'list' reference must point to a list value.
+ */
 size_t NCDVal_ListMaxCount (NCDValRef list);
+
+/**
+ * Returns a reference to the value at the given position 'pos' in a list,
+ * starting with zero.
+ * The 'list' reference must point to a list value.
+ * The position 'pos' must refer to an existing element, i.e.
+ * pos < NCDVal_ListCount().
+ */
 NCDValRef NCDVal_ListGet (NCDValRef list, size_t pos);
+
+/**
+ * Returns references to elements within a list by writing them
+ * via (NCDValRef *) variable arguments.
+ * If 'num' == NCDVal_ListCount(), succeeds, returing 1 and writing 'num'
+ * references, as mentioned.
+ * If 'num' != NCDVal_ListCount(), fails, returning 0, without writing any
+ * references
+ */
 int NCDVal_ListRead (NCDValRef list, int num, ...);
+
+/**
+ * Like {@link NCDVal_ListRead}, but the list can contain more than 'num'
+ * elements.
+ */
 int NCDVal_ListReadHead (NCDValRef list, int num, ...);
 
+/**
+ * Determines if a value is a map value.
+ * The value reference must not be an invalid reference.
+ */
 int NCDVal_IsMap (NCDValRef val);
+
+/**
+ * Builds a new map value. The 'maxcount' argument specifies how
+ * many entry slots to preallocate. Not more than that many
+ * entries may be inserted to the map using {@link NCDVal_MapInsert}.
+ * Returns a reference to the new value, or an invalid reference
+ * on out of memory.
+ */
 NCDValRef NCDVal_NewMap (NCDValMem *mem, size_t maxcount);
+
+/**
+ * Inserts an entry to the map value.
+ * The 'map' reference must point to a map value, and the
+ * 'key' and 'val' references must be non-invalid and point to values within
+ * the same memory object as the map.
+ * Inserting an entry does not in any way change the 'key'and 'val';
+ * internally, the map only points to it.
+ * You must not modify the key after inserting it into a map. This is because
+ * the map builds an embedded AVL tree of entries indexed by keys.
+ * If 'key' does not exist in the map, succeeds, returning 1.
+ * If 'key' already exists in the map, fails, returning 0.
+ */
 int NCDVal_MapInsert (NCDValRef map, NCDValRef key, NCDValRef val);
+
+/**
+ * Returns the number of entries in a map value, i.e. the number
+ * of times {@link NCDVal_MapInsert} was called successfully.
+ * The 'map' reference must point to a map value.
+ */
 size_t NCDVal_MapCount (NCDValRef map);
+
+/**
+ * Returns the maximum number of entries a map value may contain,
+ * i.e. the 'maxcount' argument to {@link NCDVal_NewMap}.
+ * The 'map' reference must point to a map value.
+ */
 size_t NCDVal_MapMaxCount (NCDValRef map);
+
+/**
+ * Determines if a map entry reference is invalid. This is used in combination
+ * with the map iteration functions to detect the end of iteration.
+ */
 int NCDVal_MapElemInvalid (NCDValMapElem me);
+
+/**
+ * Returns a reference to the first entry in a map, with respect to some
+ * arbitrary order.
+ * If the map is empty, returns an invalid map entry reference.
+ */
 NCDValMapElem NCDVal_MapFirst (NCDValRef map);
+
+/**
+ * Returns a reference to the entry in a map that follows the entry referenced
+ * by 'me', with respect to some arbitrary order.
+ * The 'me' argument must be a non-invalid reference to an entry in the map.
+ * If 'me' is the last entry, returns an invalid map entry reference.
+ */
 NCDValMapElem NCDVal_MapNext (NCDValRef map, NCDValMapElem me);
+
+/**
+ * Like {@link NCDVal_MapFirst}, but with respect to the order defined by
+ * {@link NCDVal_Compare}.
+ * Ordered iteration is slower and should only be used when needed.
+ */
+NCDValMapElem NCDVal_MapOrderedFirst (NCDValRef map);
+
+/**
+ * Like {@link NCDVal_MapNext}, but with respect to the order defined by
+ * {@link NCDVal_Compare}.
+ * Ordered iteration is slower and should only be used when needed.
+ */
+NCDValMapElem NCDVal_MapOrderedNext (NCDValRef map, NCDValMapElem me);
+
+/**
+ * Returns a reference to the key of the map entry referenced by 'me'.
+ * The 'me' argument must be a non-invalid reference to an entry in the map.
+ */
 NCDValRef NCDVal_MapElemKey (NCDValRef map, NCDValMapElem me);
+
+/**
+ * Returns a reference to the value of the map entry referenced by 'me'.
+ * The 'me' argument must be a non-invalid reference to an entry in the map.
+ */
 NCDValRef NCDVal_MapElemVal (NCDValRef map, NCDValMapElem me);
+
+/**
+ * Looks for a key in the map. The 'key' reference must be a non-invalid
+ * value reference, and may point to a value in a different memory object
+ * than the map.
+ * If the key exists in the map, returns a reference to the corresponding
+ * map entry.
+ * If the key does not exist, returns an invalid map entry reference.
+ */
 NCDValMapElem NCDVal_MapFindKey (NCDValRef map, NCDValRef key);
 
 #endif

ncd/NCDValueGenerator.c

@@ -249,7 +249,7 @@ static int generate_val (NCDValRef value, ExpString *out_str)
             
             int is_first = 1;
             
-            for (NCDValMapElem e = NCDVal_MapFirst(value); !NCDVal_MapElemInvalid(e); e = NCDVal_MapNext(value, e)) {
+            for (NCDValMapElem e = NCDVal_MapOrderedFirst(value); !NCDVal_MapElemInvalid(e); e = NCDVal_MapOrderedNext(value, e)) {
                 NCDValRef ekey = NCDVal_MapElemKey(value, e);
                 NCDValRef eval = NCDVal_MapElemVal(value, e);