/*
  Copyright (c) 2015 Alex Diener
  
  This software is provided 'as-is', without any express or implied
  warranty. In no event will the authors be held liable for any damages
  arising from the use of this software.
  
  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:
  
  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
  
  Alex Diener alex@ludobloom.com
*/

#ifndef __DataHashTable_H__
#define __DataHashTable_H__

typedef struct DataHashTable DataHashTable;

#include "dynamictypes/DataValue.h"
#include "utilities/HashTable.h"
#include <stdint.h>
#include <stdbool.h>
#include <stdlib.h>

struct DataHashTable {
	HashTable * hashTable;
};

/** Returns an empty hash table. */
DataHashTable * hashCreate(void);

/** Returns a hash table initialized with the specified string keys and values. */
DataHashTable * hashCreateWithKeysAndValues(const char * key, DataValue value, ...) __attribute__((sentinel));

/** Returns a deep copy of a hash table. */
DataHashTable * hashCopy(DataHashTable * hash);

/** Disposes the hash table and all entries in it over which the hash table has ownership. */
void hashDispose(DataHashTable * hash);

/** Returns true if an entry with the specified key exists in the hash table. Does not search recursively. */
bool hashHas(DataHashTable * hash, const char * key);

/** Removes the entry with the specified key, if it exists. A return value of true indicates that the item
    was successfully removed; false indicates that it was not found in the hash table. */
bool hashDelete(DataHashTable * hash, const char * key);

/** Return a pointer to the DataValue corresponding to the specified key, or NULL if it doesn't exist in
    the hash table. Note that modifying the hash table may invalidate this pointer, so be sure to make a
    local copy of its contents if you need to cache it. */
DataValue * hashGet(DataHashTable * hash, const char * key);

/** Sets the specified value for the specified key in the hash table. If a value with the same key already
    exists, it will be overwritten. */
void hashSet(DataHashTable * hash, const char * key, DataValue value);

/** Returns the number of items in the hash. */
size_t hashGetCount(DataHashTable * hash);

/** Returns an array containing all keys that exist in the hash table. The caller is responsible for freeing
    the returned pointer. However, the elements contained in this array must NOT be freed; only the array
    itself.
    
    Although you can pass NULL for outCount and count the items with hashGetCount, it's recommended to instead
    retrieve the number of items with outCount. */
const char ** hashGetKeys(DataHashTable * hash, size_t * outCount);

/** Returns the string that would have been returned at the specified index on a call to hashGetKeys, without
    any extra allocations. Querying every key this way is less performant than calling hashGetKeys, but may
    be more convenient for single access. Returns NULL if index is out of range. */
const char * hashGetKeyAtIndex(DataHashTable * hash, size_t index);

#endif