badvpn/ncd/NCDVal.h

/**
 * @file NCDVal.h
 * @author Ambroz Bizjak <ambrop7@gmail.com>
 * 
 * @section LICENSE
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the author nor the
 *    names of its contributors may be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef BADVPN_NCDVAL_H
#define BADVPN_NCDVAL_H

#include <stddef.h>
#include <stdint.h>

#include <misc/debug.h>
#include <misc/maxalign.h>
#include <misc/cstring.h>
#include <misc/BRefTarget.h>
#include <ncd/NCDStringIndex.h>

// these are implementation details. The interface is defined below.

#define NCDVAL_FASTBUF_SIZE 64

#define NCDVAL_MAXIDX INT_MAX
#define NCDVAL_MINIDX INT_MIN
#define NCDVAL_TOPPLID (-1 - NCDVAL_MINIDX)

typedef int NCDVal__idx;

typedef struct {
    char *buf;
    NCDVal__idx size;
    NCDVal__idx used;
    NCDVal__idx first_ref;
    NCDVal__idx first_cms_link;
    union {
        char fastbuf[NCDVAL_FASTBUF_SIZE];
        bmax_align_t align_max;
    };
} NCDValMem;

typedef struct {
    NCDValMem *mem;
    NCDVal__idx idx;
} NCDValRef;

typedef struct {
    NCDVal__idx idx;
} NCDValSafeRef;

typedef struct {
    NCDVal__idx elemidx;
} NCDValMapElem;

struct NCDVal__instr;

typedef struct {
    struct NCDVal__instr *instrs;
    size_t num_instrs;
} NCDValReplaceProg;

typedef struct {
    char *data;
    int is_allocated;
} NCDValNullTermString;

typedef struct {
    char *data;
    int is_allocated;
} NCDValContString;

//

#define NCDVAL_STRING 1
#define NCDVAL_LIST 2
#define NCDVAL_MAP 3
#define NCDVAL_PLACEHOLDER 4

/**
 * 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);

/**
 * Initializes the memory object to be a copy of an existing memory object.
 * Value references from the original may be used if they are first turned
 * to {@link NCDValSafeRef} using {@link NCDVal_ToSafe} and back to
 * {@link NCDValRef} using {@link NCDVal_FromSafe} with the new memory object
 * specified. Alternatively, {@link NCDVal_Moved} can be used.
 * Returns 1 on success and 0 on failure.
 */
int NCDValMem_InitCopy (NCDValMem *o, NCDValMem *other) WARN_UNUSED;

/**
 * For each internal link (e.g. list element) to a ComposedString in the memory
 * object, copies the ComposedString to some kind ContinuousString, and updates
 * the link to point to the new ContinuousString.
 * Additionally, if *\a root_val points to a ComposedString, copies it to a new
 * ContinuousString and updates *\a root_val to point to it.
 * \a root_val must be non-NULL and *\a root_val must not be an invalid value
 * reference.
 * Returns 1 on success and 0 on failure. On failure, some strings may have
 * been converted, but the memory object is left in a consistent state.
 */
int NCDValMem_ConvertNonContinuousStrings (NCDValMem *o, NCDValRef *root_val) WARN_UNUSED;

/**
 * Does nothing.
 * The value reference object must either point to a valid value within a valid
 * memory object, or must be an invalid reference (most 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);

/**
 * Determines if a value is a placeholder value.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsPlaceholder (NCDValRef val);

/**
 * Returns the type of the value reference, which must not be an invalid reference.
 * Possible values are NCDVAL_STRING, NCDVAL_LIST, NCDVAL_MAP and NCDVAL_PLACEHOLDER.
 * The placeholder type is only used internally in the interpreter for argument
 * resolution, and is never seen by modules; see {@link NCDVal_NewPlaceholder}.
 */
int NCDVal_Type (NCDValRef val);

/**
 * Returns an invalid reference.
 * An invalid reference must not be passed to any function here, except:
 *   {@link NCDVal_Assert}, {@link NCDVal_IsInvalid}, {@link NCDVal_ToSafe},
 *   {@link NCDVal_FromSafe}, {@link NCDVal_Moved}.
 */
NCDValRef NCDVal_NewInvalid (void);

/**
 * Returns a new placeholder value reference. A placeholder value is a valid value
 * containing an integer placeholder identifier.
 * This always succeeds; however, the caller must ensure the identifier is in the
 * range [0, NCDVAL_TOPPLID).
 * 
 * The placeholder type is only used internally in the interpreter for argument
 * resolution, and is never seen by modules.
 */
NCDValRef NCDVal_NewPlaceholder (NCDValMem *mem, int plid);

/**
 * Returns the indentifier of a placeholder value.
 * The value reference must point to a placeholder value.
 */
int NCDVal_PlaceholderId (NCDValRef val);

/**
 * Copies a value into the specified memory object. The source
 * must not be an invalid reference, however it may reside in any memory
 * object (including 'mem').
 * 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 whether a safe reference is a placeholder.
 */
int NCDVal_IsSafeRefPlaceholder (NCDValSafeRef sval);

/**
 * Gets the placeholder ID of a placeholder safe reference.
 */
int NCDVal_GetSafeRefPlaceholderId (NCDValSafeRef sval);

/**
 * Determines if all strings within this value are ContinuousString's,
 * by recusively walking the entire value.
 * If all strings are ContinuousString's, returns 1; if there is at least
 * one string which is not a ContinuousString, returns 0.
 * The value reference must not be an invalid reference.
 */
int NCDVal_HasOnlyContinuousStrings (NCDValRef val);

/**
 * Determines if the value implements the String interface.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsString (NCDValRef val);

/**
 * Determines if the value implements the ContinuousString interface.
 * A ContinuousString also implements the String interface.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsContinuousString (NCDValRef val);

/**
 * Determines if the value is a StoredString.
 * A StoredString implements the ContinuousString interface.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsStoredString (NCDValRef val);

/**
 * Determines if the value is an IdString. See {@link NCDVal_NewIdString}
 * for details.
 * An IdString implements the ContinuousString interface.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsIdString (NCDValRef val);

/**
 * Determines if a value is an ExternalString.
 * See {@link NCDVal_NewExternalString} for details.
 * An ExternalString implements the ContinuousString interface.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsExternalString (NCDValRef val);

/**
 * Determines if a value is a ComposedString.
 * A ComposedString implements the String interface.
 */
int NCDVal_IsComposedString (NCDValRef val);

/**
 * Determines if a value is a String which contains no null bytes.
 * The value reference must not be an invalid reference.
 */
int NCDVal_IsStringNoNulls (NCDValRef val);

/**
 * Equivalent to NCDVal_NewStringBin(mem, data, strlen(data)).
 */
NCDValRef NCDVal_NewString (NCDValMem *mem, const char *data);

/**
 * Builds a new StoredString.
 * Returns a reference to the new value, or an invalid reference
 * on out of memory.
 * WARNING: The buffer passed must NOT be part of any value in the
 * memory object specified. In particular, you may NOT use this
 * function to copy a string that resides in the same memory object.
 * 
 * A StoredString is a kind of ContinuousString which is represented directly in the
 * value memory object.
 */
NCDValRef NCDVal_NewStringBin (NCDValMem *mem, const uint8_t *data, size_t len);

/**
 * Builds a new StoredString of the given length with undefined contents.
 * You can define the contents of the string later by copying to the address
 * returned by {@link NCDVal_StringData}.
 */
NCDValRef NCDVal_NewStringUninitialized (NCDValMem *mem, size_t len);

/**
 * Builds a new IdString.
 * Returns a reference to the new value, or an invalid reference
 * on out of memory.
 * 
 * An IdString is a kind of ContinuousString which is represented efficiently as a string
 * identifier via {@link NCDStringIndex}.
 */
NCDValRef NCDVal_NewIdString (NCDValMem *mem, NCD_string_id_t string_id,
                              NCDStringIndex *string_index);

/**
 * Builds a new ExternalString, pointing to the given external data. A reference to
 * the external data is taken using {@link BRefTarget}, unless 'ref_target' is
 * NULL. The data must not change while this value exists.
 * Returns a reference to the new value, or an invalid reference
 * on out of memory.
 * 
 * An ExternalString is a kind of ContinuousString where the actual string contents are
 * stored outside of the value memory object.
 */
NCDValRef NCDVal_NewExternalString (NCDValMem *mem, const char *data, size_t len,
                                    BRefTarget *ref_target);

/**
 * Callback function which is called for ComposedString's to access the underlying string resource.
 * \a user is whatever was passed to 'resource.user' in {@link NCDVal_NewComposedString}.
 * \a offset is the offset from the beginning of the string exposed by the resource; it will be
 * >= 'offset' and < 'offset' + 'length' as given to NCDVal_NewComposedString.
 * This callback must set *\a out_data and *\a out_length to represent a continuous (sub-)region
 * of the string that starts at the byte at index \a offset. The pointed-to data must remain
 * valid and unchanged until all references to the string resource are released.
 * \a *out_data must be set to non-NULL and *\a out_length must be set to greater than zero,
 * since the conditions above imply that there is at least one byte available from \a offset.
 */
typedef void (*NCDVal_ComposedString_func_getptr) (void *user, size_t offset, const char **out_data, size_t *out_length);

/**
 * Structure representing a string resource used by ComposedString's,
 * to simplify {@link NCDVal_NewComposedString} and {@link NCDVal_ComposedStringResource}.
 */
typedef struct {
    NCDVal_ComposedString_func_getptr func_getptr;
    void *user;
    BRefTarget *ref_target;
} NCDValComposedStringResource;

/**
 * Returns a cstring referencing a range within a {@link NCDValComposedStringResource}.
 * \a offset and \a length specify the range within the resource which the returned
 * cstring will reference. To reference the contents of a ComposedString, use:
 *   - resource = NCDVal_ComposedStringResource(composedstring),
 *   - offset = NCDVal_ComposedStringOffset(composedstring),
 *   - length = NCDVal_StringLength(composedstring).
 * 
 * The returned cstring is valid as long as the resource is not released. Note that
 * a reference to resource.ref_target may need to be taken to ensure the resource
 * is not released while it is being referenced by the returned cstring (unless
 * resource.ref_target is NULL).
 */
b_cstring NCDValComposedStringResource_Cstring (NCDValComposedStringResource resource, size_t offset, size_t length);

/**
 * Builds a new ComposedString from a string resource.
 * A reference to the underlying string resource via the {@link BRefTarget} object
 * specified in 'resource.ref_target'.
 * 
 * A ComposedString is a kind of String with an abstract representation exposed via the
 * {@link NCDVal_ComposedString_func_getptr} callback.
 */
NCDValRef NCDVal_NewComposedString (NCDValMem *mem, NCDValComposedStringResource resource, size_t offset, size_t length);

/**
 * Returns a pointer to the data of a ContinuousString.
 * WARNING: the string data may not be null-terminated. To get a null-terminated
 * version, use {@link NCDVal_StringNullTerminate}.
 * The value reference must point to a ContinuousString.
 */
const char * NCDVal_StringData (NCDValRef contstring);

/**
 * Returns the length of a String.
 * The value reference must point to a String.
 */
size_t NCDVal_StringLength (NCDValRef string);

/**
 * Returns a {@link b_cstring} interface to the given string value.
 * The returned cstring is valid as long as the memory object exists.
 * However, if the memory object is moved or copied, the cstring is
 * invalid in the new or moved (respectively) memory object.
 */
b_cstring NCDVal_StringCstring (NCDValRef string);

/**
 * Produces a null-terminated continuous version of a String. On success, the result is
 * stored into an {@link NCDValNullTermString} structure, and the null-terminated
 * string is available via its 'data' member. This function may either simply pass
 * through the data pointer (if the string is known to be continuous and null-terminated) or
 * produce a null-terminated dynamically allocated copy.
 * On success, {@link NCDValNullTermString_Free} should be called to release any allocated
 * memory when the null-terminated string is no longer needed. This must be called before
 * the memory object is freed, because it may point to data inside the memory object.
 * It is guaranteed that *out is not modified on failure.
 * Returns 1 on success and 0 on failure.
 */
int NCDVal_StringNullTerminate (NCDValRef string, NCDValNullTermString *out) WARN_UNUSED;

/**
 * Returns a dummy {@link NCDValNullTermString} which can be freed using
 * {@link NCDValNullTermString_Free}, but need not be.
 */
NCDValNullTermString NCDValNullTermString_NewDummy (void);

/**
 * Releases any memory which was dynamically allocated by {@link NCDVal_StringNullTerminate}
 * to null-terminate a string.
 */
void NCDValNullTermString_Free (NCDValNullTermString *o);

/**
 * Produces a continuous version of a String. On success, the result is stored into an
 * {@link NCDValContString} structure, and the continuous string is available via its
 * 'data' member. This function may either simply pass through the data pointer (if the
 * string is known to be continuous) or produce a continuous dynamically allocated copy.
 * On success, {@link NCDValContString_Free} should be called to release any allocated
 * memory when the continuous string is no longer needed. This must be called before
 * the memory object is freed, because it may point to data inside the memory object.
 * It is guaranteed that *out is not modified on failure.
 * Returns 1 on success and 0 on failure.
 */
int NCDVal_StringContinuize (NCDValRef string, NCDValContString *out) WARN_UNUSED;

/**
 * Returns a dummy {@link NCDValContString} which can be freed using
 * {@link NCDValContString_Free}, but need not be.
 */
NCDValContString NCDValContString_NewDummy (void);

/**
 * Releases any memory which was dynamically allocated by {@link NCDVal_StringContinuize}
 * to continuize a string.
 */
void NCDValContString_Free (NCDValContString *o);

/**
 * Returns the string ID and the string index of an IdString.
 * Both the \a out_string_id and \a out_string_index pointers must be non-NULL.
 */
void NCDVal_IdStringGet (NCDValRef idstring, NCD_string_id_t *out_string_id,
                         NCDStringIndex **out_string_index);

/**
 * Returns the string ID of an IdString.
 */
NCD_string_id_t NCDVal_IdStringId (NCDValRef idstring);

/**
 * Returns the string index of an IdString.
 */
NCDStringIndex * NCDVal_IdStringStringIndex (NCDValRef idstring);

/**
 * Returns the reference target of an ExternalString. This may be NULL
 * if the external string is not associated with a reference target.
 */
BRefTarget * NCDVal_ExternalStringTarget (NCDValRef externalstring);

/**
 * Returns the underlying string resource of a ComposedString.
 */
NCDValComposedStringResource NCDVal_ComposedStringResource (NCDValRef composedstring);

/**
 * Returns the resource offset of a ComposedString.
 */
size_t NCDVal_ComposedStringOffset (NCDValRef composedstring);

/**
 * Determines if the String has any null bytes in its contents.
 */
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 the String is equal to the given string represented
 * by an {@link NCDStringIndex} identifier.
 * NOTE: \a string_index must be equal to the string_index of every ID-string
 * that exist within this memory object.
 */
int NCDVal_StringEqualsId (NCDValRef string, NCD_string_id_t string_id,
                           NCDStringIndex *string_index);

/**
 * Compares two String's in a manner similar to memcmp().
 * The startN and length arguments must refer to a valid region within
 * stringN, i.e. startN + length <= length_of_stringN must hold.
 */
int NCDVal_StringMemCmp (NCDValRef string1, NCDValRef string2, size_t start1, size_t start2, size_t length);

/**
 * Copies a part of a String to a buffer.
 * \a start and \a length must refer to a valid region within the string,
 * i.e. start + length <= length_of_string must hold.
 */
void NCDVal_StringCopyOut (NCDValRef string, size_t start, size_t length, char *dst);

/**
 * Determines if a part of a String is equal to the \a length bytes in \a data.
 * \a start and \a length must refer to a valid region within the string,
 * i.e. start + length <= length_of_string must hold.
 */
int NCDVal_StringRegionEquals (NCDValRef string, size_t start, size_t length, 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.
 * You must not modify the element after it has been inserted into the
 * list.
 * Returns 1 on success and 0 on failure (depth limit exceeded).
 */
int NCDVal_ListAppend (NCDValRef list, NCDValRef elem) WARN_UNUSED;

/**
 * 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 insertion fails due to a maximum depth limit, returns 0.
 * Otherwise returns 1, and *out_inserted is set to 1 if the key did not
 * yet exist and the entry was inserted, and to 0 if it did exist and the
 * entry was not inserted. The 'out_inserted' pointer may be NULL, in which
 * case *out_inserted is never set.
 */
int NCDVal_MapInsert (NCDValRef map, NCDValRef key, NCDValRef val, int *out_inserted) WARN_UNUSED;

/**
 * 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);

/**
 * Retrieves the value reference to the value of the map entry whose key is a
 * string value equal to the given null-terminated string. If there is no such
 * entry, returns an invalid value reference.
 */
NCDValRef NCDVal_MapGetValue (NCDValRef map, const char *key_str);

/**
 * Builds a placeholder replacement program, which is a list of instructions for
 * efficiently replacing placeholders in identical values in identical memory
 * objects.
 * To actually perform replacements, make copies of the memory object of this value
 * using {@link NCDValMem_InitCopy}, then call {@link NCDValReplaceProg_Execute}
 * on the copies.
 * The value passed must be a valid value, and not a placeholder.
 * Returns 1 on success, 0 on failure.
 */
int NCDValReplaceProg_Init (NCDValReplaceProg *o, NCDValRef val);

/**
 * Frees the placeholder replacement program.
 */
void NCDValReplaceProg_Free (NCDValReplaceProg *o);

/**
 * Callback used by {@link NCDValReplaceProg_Execute} to allow the caller to produce
 * values of placeholders.
 * This function should build a new value within the memory object 'mem' (which is
 * the same as of the memory object where placeholders are being replaced).
 * On success, it should return 1, writing a valid value reference to *out.
 * On failure, it can either return 0, or return 1 but write an invalid value reference.
 * This callback must not access the memory object in any other way than building
 * new values in it; it must not modify any values that were already present at the
 * point it was called.
 */
typedef int (*NCDVal_replace_func) (void *arg, int plid, NCDValMem *mem, NCDValRef *out);

/**
 * Executes the replacement program, replacing placeholders in a value.
 * The memory object must given be identical to the memory object which was used in
 * {@link NCDValReplaceProg_Init}; see {@link NCDValMem_InitCopy}.
 * This will call the callback 'replace', which should build the values to replace
 * the placeholders.
 * Returns 1 on success and 0 on failure. On failure, the entire memory object enters
 * and inconsistent state and must be freed using {@link NCDValMem_Free} before
 * performing any other operation on it.
 * The program is passed by value instead of pointer because this appears to be faster.
 * Is is not modified in any way.
 */
int NCDValReplaceProg_Execute (NCDValReplaceProg prog, NCDValMem *mem, NCDVal_replace_func replace, void *arg);

#endif