zhash.h

Go to the documentation of this file.

/* Copyright (C) 2013-2016, The Regents of The University of Michigan.
All rights reserved.

This software was developed in the APRIL Robotics Lab under the
direction of Edwin Olson, ebolson@umich.edu. This software may be
available under alternative licensing terms; contact the address above.

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.

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 COPYRIGHT OWNER OR CONTRIBUTORS 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.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the Regents of The University of Michigan.
*/

#ifndef _ZHASH_H
#define _ZHASH_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

#include "zarray.h"


typedef struct zhash zhash_t;

// The contents of the iterator should be considered private. However,
// since our usage model prefers stack-based allocation of iterators,
// we must publicly declare them.
struct zhash_iterator
{
    zhash_t *zh;
    const zhash_t *czh;
    int last_entry; // points to the last entry returned by _next
};

typedef struct zhash_iterator zhash_iterator_t;

zhash_t *zhash_create(size_t keysz, size_t valuesz,
                      uint32_t(*hash)(const void *a),
                      int(*equals)(const void *a, const void *b));

void zhash_destroy(zhash_t *zh);

zhash_t * zhash_copy(const zhash_t* other);

int zhash_contains(const zhash_t *zh, const void *key);

int zhash_get(const zhash_t *zh, const void *key, void *out_value);

int zhash_get_volatile(const zhash_t *zh, const void *key, void *out_p);

int zhash_put(zhash_t *zh, const void *key, const void *value, void *oldkey, void *oldvalue);

int zhash_remove(zhash_t *zh, const void *key, void *oldkey, void *oldvalue);

void zhash_clear(zhash_t *zh);

int zhash_size(const zhash_t *zh);

void zhash_iterator_init(zhash_t *zh, zhash_iterator_t *zit);

void zhash_iterator_init_const(const zhash_t *zh, zhash_iterator_t *zit);

int zhash_iterator_next(zhash_iterator_t *zit, void *outkey, void *outvalue);

int zhash_iterator_next_volatile(zhash_iterator_t *zit, void *outkey, void *outvalue);

void zhash_iterator_remove(zhash_iterator_t *zit);

void zhash_map_keys(zhash_t *zh, void (*f)());

void zhash_map_values(zhash_t *zh, void (*f)());

void zhash_vmap_keys(zhash_t *vh, void (*f)());

void zhash_vmap_values(zhash_t *vh, void (*f)());

zarray_t *zhash_keys(const zhash_t *zh);

zarray_t *zhash_values(const zhash_t *zh);

uint32_t zhash_uint32_hash(const void *a);

int zhash_uint32_equals(const void *a, const void *b);

uint32_t zhash_uint64_hash(const void *a);

int zhash_uint64_equals(const void *a, const void *b);

// functions for keys that can be compared via their pointers.
uint32_t zhash_ptr_hash(const void *a);

int zhash_ptr_equals(const void *a, const void *b);

// Functions for string-typed keys
uint32_t zhash_str_hash(const void *a);

int zhash_str_equals(const void *a, const void *b);

void zhash_debug(zhash_t *zh);

    static inline zhash_t *zhash_str_str_create(void)
    {
        return zhash_create(sizeof(char*), sizeof(char*),
                            zhash_str_hash, zhash_str_equals);
    }



// for zhashes that map strings to strings, this is a convenience
// function that allows easier retrieval of values. NULL is returned
// if the key is not found.
static inline char *zhash_str_str_get(zhash_t *zh, const char *key)
{
    char *value;
    if (zhash_get(zh, &key, &value))
        return value;
    return NULL;
}

    static inline void zhash_str_str_put(zhash_t *zh, char *key, char *value)
    {
        char *oldkey, *oldval;
        if (zhash_put(zh, &key, &value, &oldkey, &oldval)) {
            free(oldkey);
            free(oldval);
        }
    }

    static inline void zhash_str_str_destroy(zhash_t *zh)
    {
        zhash_iterator_t zit;
        zhash_iterator_init(zh, &zit);

        char *key, *value;
        while (zhash_iterator_next(&zit, &key, &value)) {
            free(key);
            free(value);
        }

        zhash_destroy(zh);
    }


static inline uint32_t zhash_int_hash(const void *_a)
{
    assert(_a != NULL);

    uint32_t a = *((int*) _a);
    return a;
}

static inline int zhash_int_equals(const void *_a, const void *_b)
{
    assert(_a != NULL);
    assert(_b != NULL);

    int a = *((int*) _a);
    int b = *((int*) _b);

    return a==b;
}

#ifdef __cplusplus
}
#endif

#endif