/**
 * @file map.hpp
 * @brief J Library Map ヘッダファイル。
 * @copyright  2001 - 2024  Nomura Kei
 * @depends
 *   j/util/collection.hpp
 */
#ifndef J_UTIL_MAP_HPP
#define J_UTIL_MAP_HPP

#include <optional>
#include <j/util/collection.hpp>

namespace j
{
    namespace util
    {

        template <typename K, typename V>
        class Map
        {
        public:
            virtual ~Map() = default;

            /**
             * このマップ内のキー値マッピングの数を返します。
             *
             * @return このマップ内のキーと値のマッピング数
             */
            virtual int size() const noexcept = 0;

            /**
             * このマップがキーと値のマッピングを保持しない場合に true を返します。
             *
             * @return このマップがキーと値のマッピングを保持しない場合は true
             */
            virtual bool isEmpty() const noexcept = 0;

            /**
             * 指定のキーのマッピングが、このマップに含まれている場合に true を返します。
             *
             * @param key このマップ内にあるかどうかが判定されるキー
             * @return このマップが指定されたキーのマッピングを保持する場合は true
             */
            virtual bool containsKey(const K &key) const = 0;

            /**
             * マップが1つまたは複数のキーを指定された値にマッピングしている場合に true を返します。
             *
             * @param value このマップにあるかどうかが判定される値
             * @return このマップが1つまたは複数のキーを指定された値にマッピングしている場合は true
             */
            virtual bool containsValue(const V &value) const = 0;

            /**
             * 指定されたキーがマップされている値を返します。
             * このマップにそのキーのマッピングが含まれていない場合は、要素を値初期化して参照を返す。
             *
             * @param key 関連付けられた値が返されるキー
             * @return 指定されたキーがマップされている値。
             */
            virtual std::optional<V> get(const K &key) const = 0;

            /**
             * 指定された値と指定されたキーをこのマップで関連付けます。
             *
             * @param key 指定された値が関連付けられるキー
             * @param value 指定されたキーに関連付けられる値
             * @return key に以前関連付けられていた値。
             */
            virtual std::optional<V> put(const K &key, const V &value) = 0;

            /**
             * このマップからキーのマッピングを削除します。
             *
             * @param key マッピングがマップから削除されるキー
             * @return key に以前に関連付けられていた値
             */
            virtual std::optional<V> remove(const K &key) = 0;

            /**
             * マップからマッピングをすべて削除します。
             */
            virtual void clear() = 0;
        };

    } // namespace util
} // namespace j

#endif // J_UTIL_MAP_HPP