#pragma region CPL License /* Nuclex Native Framework Copyright (C) 2002-2023 Nuclex Development Labs This library is free software; you can redistribute it and/or modify it under the terms of the IBM Common Public License as published by the IBM Corporation; either version 1.0 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the IBM Common Public License for more details. You should have received a copy of the IBM Common Public License along with this library */ #pragma endregion // CPL License #ifndef NUCLEX_SUPPORT_COLLECTIONS_MAP_H #define NUCLEX_SUPPORT_COLLECTIONS_MAP_H #include "Nuclex/Support/Config.h" #include // for std::size_t namespace Nuclex { namespace Support { namespace Collections { // ------------------------------------------------------------------------------------------- // /// Interface for a container that maps keys to values /// Type of the key the map uses /// Type of values that are stored in the map template class Map { /// Destroys the map public: virtual ~Map() = default; /// Stores a value in the map /// Key under which the value can be looked up later /// Value that will be stored under its key in the map /// /// True if the key did not exist before and was inserted, /// false if the key already existed and its value was replaced. /// public: virtual bool Insert(const TKey &key, const TValue &value) = 0; /// Stores a value in the map if it doesn't exist yet /// Key under which the value can be looked up later /// Value that will be stored under its key in the map /// /// True if the key did not exist before and was inserted, /// false if the key already existed and left unchanged /// public: virtual bool TryInsert(const TKey &key, const TValue &value) = 0; /// Returns the value of the specified element in the map /// Key of the element that will be looked up public: virtual const TValue &Get(const TKey &key) const = 0; // TODO: Code smell - TryGet() couldn't be adapted to Get() // Can't pinpoint the design flaw, if the interface design is cohesive, // such situations should resolve themselves, something is suboptimal here. /// Tries to look up an element in the map /// Key of the element that will be looked up /// Will receive the value if the element was found /// /// True if an element was returned, false if the key didn't exist /// public: virtual bool TryGet(const TKey &key, TValue &value) const = 0; /// Tries to take an element from the map (removing it) /// Key of the element that will be taken from the map /// Will receive the value taken from the map /// /// True if an element was found and removed from the map, false if the key didn't exist /// public: virtual bool TryTake(const TKey &key, TValue &value) = 0; // CHECK: Could provide a TryTake() with output method to allow for move semantics. //public: virtual bool TryTake(const TKey &key, const std::function &valueCallback) = 0; /// Removes the specified element from the map if it exists /// Key of the element that will be removed if present /// True if the element was found and removed, false otherwise public: virtual bool TryRemove(const TKey &key) = 0; /// Removes all items from the map public: virtual void Clear() = 0; /// Counts the numebr of elements currently in the map /// /// The approximate number of elements that had been in the map during the call /// public: virtual std::size_t Count() const = 0; /// Checks if the map is empty /// True if the map had been empty during the call public: virtual bool IsEmpty() const = 0; }; // ------------------------------------------------------------------------------------------- // }}} // namespace Nuclex::Support::Collections #endif // NUCLEX_SUPPORT_COLLECTIONS_MAP_H