/**
 * @file kc_map.h
 * @brief MAp モジュールヘッダファイル
 * @copyright  2002 - 2023  Nomura Kei
 * @depends
 *	kc.h
 */
#ifndef KC_LIST_H
#define KC_LIST_H

#include <kc.h>

#ifdef __cplusplus
extern "C"
{
	namespace kc
	{
		using namespace std;
#endif

		/**
		 * マップ。
		 */
		typedef struct KcMap_
		{
			/**
			 * マップに格納されている要素の数を返します。
			 *
			 * @param map 対象マップ
			 * @return 要素の数
			 */
			size_t (*size)(struct KcMap_ *map);

			/**
			 * マップに要素を追加します。
			 * オブジェクトはコピーして追加されます。
			 * 追加に失敗した場合、NULL が返されます。
			 *
			 * @param map  対象マップ
			 * @param key  キー
			 * @param obj  キーに対応するオブジェクト
			 * @param size オブジェクトのサイズ
			 * @return 追加したオブジェクトへのポインタ
			 */
			void *(*put)(struct KcMap_ *map, const char *key, const void *obj, size_t size);

			/**
			 * 指定されたキーに対応するオブジェクトを取得します。
			 * オブジェクトは参照が渡されます。
			 * size が NULL でない場合、取得されたオブジェクトのサイズが格納されます。
			 *
			 * @param map  対象マップ
			 * @param key  キー
			 * @param size オブジェクトのサイズ
			 * @return オブジェクトへのポインタ
			 */
			void *(*get)(struct KcMap_ *map, const char *key, size_t *size);

			/**
			 * 指定されたキーに対応するオブジェクトを削除します。
			 *
			 * @param map  対象マップ
			 * @param key  キー
			 */
			void (*remove)(struct KcMap_ *map, const char *key);

			/**
			 * マップ内のすべての要素を対象リストから削除します。
			 *
			 * @param list 対象リスト
			 */
			void (*clear)(struct KcMap_ *map);

			/**
			 * マップに格納されている要素を引数に、指定されたハンドラを実行します。
			 * ハンドラ関数が false を返す場合、呼出し処置は中断されます。
			 *
			 * @param map 対象マップ
			 * @param handler ハンドラ関数
			 * @param args ハンドラ関数に渡されるユーザーデータ
			 */
			void (*entries)(struct KcMap_ *map, bool (*handler)(const char *key, const void *val, size_t size, void *args), void *args);

			/**
			 * マップ管理情報
			 * 本オブジェクトはリスト実装者が利用するための情報へのポインタとなります。
			 */
			void *_info;

		} KcMap;

		/**
		 * マップ を構築します。
		 *
		 * @return cap マップのキー管理容量
		 */
		KcMap *KcMap_new(size_t cap);

		/**
		 * マップを破棄します。
		 * @param map 破棄するマップ
		 */
		void KcMap_delete(KcMap *map);

		/**
		 * 指定されたキーに対応するハッシュコードを返します。
		 */
		int KcMap_hash_code(const char *key);

#ifdef __cplusplus
	} // namespace kc
} // extern "C"
#endif
#endif // KC_LIST_H