/*
 *  Copyright (c) Huawei Technologies Co., Ltd. 2025. All rights reserved.
 *  This source file is part of the Cangjie project, licensed under Apache-2.0
 *  with Runtime Library Exception.
 *
 *  See https://cangjie-lang.cn/pages/LICENSE for license information.
 */

package stdx.string_intern

internal import std.collection.Set
internal import std.collection.Map

/**
 * @brief  A Generic Cache Interface Based on Key and Value
 */
interface ICache<K, V> where K <: Hashable & Equatable<K> {

    /**
     * Release a specified number of caches: For example, in the LRU cache, the specified number of least used elements are released.
     *
     * @param numberToReleasee Number of released cache elements
     * @return Number of cached elements that are actually released. If 10 elements are requested to be released but only three elements are actually released in the cache, 3 is returned.
     */
    func release(numberToRelease: Int64): Int64

    /**
     * Obtain a cache object from the cache.
     *
     * @param key Cached key
     * @return If the cache element of the corresponding key exists, the type of Option is returned. Otherwise, Option.None is returned.
     */
    func get(key: K): Option<ICacheObj<K, V>>

    /**
     * Obtain the size of the current cache.
     * <p>
     * @return Number of elements in the cache
     */
    func getSize(): Int64

    /**
     * Remove an element object whose key is key from the cache.
     * <p>
     * @param key Cache key
     * @return Whether the element object corresponding to the cache exists
     */
    func remove(key: K): Bool

    /**
     * Delete all elements from the cache.
     * <p>
     */
    func removeAll(): Unit

    /**
     * Put a cache object into the cache.
     * <p>
     * @param cobj Cache object
     */
    func put(cobj: ICacheObj<K, V>): Unit

    func putIfAbsent(cobj: ICacheObj<K, V>): ?ICacheObj<K, V>

    /**
     * Obtain multiple cache objects based on key values.
     * <p>
     * @param keys
     * @return Multiple objects are stored using a map. The key of the map is the key value, and the value of the map is the cache object.
     */
    func getCacheObjs(keys: Set<K>): Map<K, Option<ICacheObj<K, V>>>

    /**
     * Cache initialization
     * <p>
     * @param cacheConfigs Definition of cache configuration attributes
     */
    func initialize(cacheConfigs: ICacheConfig): Unit
}