kicad/include/lru_cache.h

/*
 * This program source code file is part of KiCad, a free EDA CAD application.
 *
 * Copyright (C) 2015 Mario Luzeiro <mrluzeiro@ua.pt>
 * Copyright (C) 1992-2015 KiCad Developers, see AUTHORS.txt for contributors.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program 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
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, you may find one here:
 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 * or you may search the http://www.gnu.org website for the version 2 license,
 * or you may write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
 */

/**
 * @file  lru_cache.h
 * @brief Template define a least-recently-used cache algo based on wxHashMap and wxString
 *        http://docs.wxwidgets.org/3.0/classwx_hash_map.html
 */

#ifndef LRU_CACHE_H
#define LRU_CACHE_H


#include <list>
#include <iterator>
#include <map>
#include <stdexcept>
#include <wx/string.h>


/**
 *  Template LRU_WXSTR_CACHE
 *  template for a wxString key based LRU cache
 *
 * @code
 * LRU_WXSTR_CACHE< int > cache;
 *
 * cache.Resize( 3 );
 *
 * cache.Insert( "First",  1 );
 * cache.Insert( "Second", 2 );
 *
 * printf(" cache.Size() %d \n", cache.Size() ); // size == 2
 * printf(" cache.MaxSize() %d \n", cache.MaxSize() ); // max size == 3
 * @endcode
 */
template< typename t_value >
class LRU_WXSTR_CACHE
{

private:

    /**
     * Declares KEY_VALUE_PAIR
     * Declares a pair with the key (wxString) and a value
     */
    typedef std::pair< wxString, t_value > KEY_VALUE_PAIR;

    /**
     * Declares LIST_ITERATOR
     * Declares a iterator type for a list of KEY_VALUE_PAIR
     */
    typedef std::list< KEY_VALUE_PAIR > CACHED_LIST;


    /**
     * Declares LIST_ITERATOR
     * Declares a iterator type for a list of KEY_VALUE_PAIR
     */
    typedef typename CACHED_LIST::iterator LIST_ITERATOR;


    /**
     * Declares WXSTR_HASH_MAP
     * Declares a map type of LIST_ITERATOR based on a wxString key
     */
    typedef std::map< wxString, LIST_ITERATOR > WXSTR_HASH_MAP;

    /**
     * Declares MAP_ITERATOR
     * Declares a iterator for the map
     */
    typedef typename WXSTR_HASH_MAP::iterator MAP_ITERATOR;


    /**
     * list of cached items
     */
    CACHED_LIST m_cached_list;

     /**
     * Cache map with iterators of the list
     */
     WXSTR_HASH_MAP m_map_iterators;


    /**
     *  Max capacity of the cache
     */
    size_t m_maxSize;

public:


     /**
     * Constructor LRU_WXSTR_CACHE
     * @param aMaxSize - initial max number of items of the cache
     */
    LRU_WXSTR_CACHE( size_t aMaxSize = 1 ) : m_maxSize( aMaxSize ) {}


    /**
     * Function Insert
     * @param aKey = the string key that is the reference of this entry
     * @param aValue = the value to add
     */
     void Insert( const wxString &aKey, const t_value &aValue )
     {
        MAP_ITERATOR it = m_map_iterators.find( aKey );

        if( it != m_map_iterators.end() )
        {
            // It already exists, so must remove it from list and form the map
            // it->second have a iterator from the list m_cached_list
            m_cached_list.erase( it->second );
            m_map_iterators.erase( it );
        }

        // Inserts a new element at the beginning of the list, a pair of <aKey, aValue>
        m_cached_list.push_front( KEY_VALUE_PAIR( aKey, aValue) );

        // Insert a new key and the added list iterator to the map
        m_map_iterators[aKey] = m_cached_list.begin();

        // Manage the size of the list
        if( m_cached_list.size() > m_maxSize )
        {
            // Get an iterator to the end of the list
            LIST_ITERATOR last_it = m_cached_list.end();

            // This gets the real iterator that is the latest one
            last_it--;

            // Remove the key from the map
            m_map_iterators.erase( last_it->first );

            // Removes the last element in the list
            m_cached_list.pop_back();
        }
     }


    /**
     * Function Get
     * Returns an existent value from the given key.
     * The key must exists, if not it will throw an error.
     * Use function Exists to check first if you can get that key
     * @param aKey = an existent key
     * @return t_value
     */
    const t_value& Get( const wxString &aKey )
    {
        MAP_ITERATOR map_it = m_map_iterators.find( aKey );

        if( map_it == m_map_iterators.end() )
        {
            throw std::range_error( "Requested a key that dont exists" );
        }

        // This will update the list and put in the beginning the iterator that we are getting
        m_cached_list.splice( m_cached_list.begin(), m_cached_list, map_it->second );

        // Return the t_value from the <key, value> pair that was in the list
        return map_it->second->second;
    }


    /**
     * Function Exists
     * @param aKey key to look for
     * @return true if the aKey exists
     */
    bool Exists( const wxString &aKey ) const
    {
        return ( m_map_iterators.find( aKey ) != m_map_iterators.end() );
    }


    /**
     * Function Resize
     * If aNewSize is smaller than the current maxSize then the items back in the list are discarded
     * This function can be used to empty the cache, setting the new size to 0
     * @param aNewSize - resize the store capability of the list to aNewSize
     */
    void Resize( size_t aNewSize )
    {
        m_maxSize = aNewSize;

        while( m_map_iterators.size() > m_maxSize )
        {
            // Remove the key from the map
            m_map_iterators.erase( m_cached_list.back().first );

            // Remove the back of the list
            m_cached_list.pop_back();
        }
    }


    /**
     * Function Size
     * @return size_t current size of the cache
     */
    size_t Size() const
    {
        return m_map_iterators.size();
    }


    /**
     * Function MaxSize
     * @return size_t current max size of the cache
     */
    size_t MaxSize() const
    {
        return m_maxSize;
    }


};

#endif // LRU_CACHE_H