dictionary.h

Go to the documentation of this file.

/*
 *  dictionary.h
 *
 *  This file is part of NEST.
 *
 *  Copyright (C) 2004 The NEST Initiative
 *
 *  NEST 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.
 *
 *  NEST 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 NEST.  If not, see <http://www.gnu.org/licenses/>.
 *
 */
 
#ifndef DICTIONARY_H
#define DICTIONARY_H
 
#include <concepts>
#include <map>
#include <memory>
#include <string>
#include <utility>
#include <variant>
#include <vector>
 
#include "config.h"
#include "exceptions.h"
#include "logging.h"
 
#ifdef HAVE_BOOST
#include <boost/type_index.hpp>
#endif
 
namespace nest
{
class Parameter;
class NodeCollection;
}
 
class dictionary_;
class Dictionary;
class AnyVector;
struct EmptyList;
 
 
template < typename... Scalars >
struct DictionarySchemaBuilder
{
  template < typename... Extras >
  using VariantType = std::variant< std::monostate, Scalars..., std::vector< Scalars >..., Extras... >;
};
 
using DictionarySchema = DictionarySchemaBuilder< double, long, bool, std::string, Dictionary >;
 
using any_type = DictionarySchema::VariantType< std::shared_ptr< nest::NodeCollection >,
  std::vector< std::vector< double > >,
  std::vector< std::vector< std::vector< double > > >,
  std::vector< std::vector< std::vector< long > > >,
  std::shared_ptr< nest::Parameter >,
  AnyVector,
  nest::VerbosityLevel,
  EmptyList >;
 
class AnyVector : public std::vector< any_type >
{
  using vectype_ = std::vector< any_type >;
  using vectype_::vectype_;  // Inherit constructors
};
 
struct EmptyList
{
  bool operator==( const EmptyList& ) const = default;
};
 
std::ostream& operator<<( std::ostream& os, const EmptyList& );
 
std::ostream& operator<<( std::ostream& os, const std::monostate& );
 
std::ostream& operator<<( std::ostream& os, const AnyVector& av );
 
std::ostream& operator<<( std::ostream& os, const Dictionary& dict );
 
template < typename T >
concept Integer = std::integral< T > and not std::same_as< T, bool > and not std::same_as< T, char >;
 
template < typename T >
concept DictionaryEntryType = std::is_constructible_v< any_type, T >;
 
class Dictionary : public std::shared_ptr< dictionary_ >
{
public:
  Dictionary()
    : std::shared_ptr< dictionary_ >( std::make_shared< dictionary_ >() )
  {
  }
 
  any_type& operator[]( const std::string& key );
  any_type& operator[]( std::string&& key );
  any_type& at( const std::string& key );
  const any_type& at( const std::string& key ) const;
 
  bool operator==( const Dictionary& other ) const;
 
  auto begin() const;
  auto end() const;
 
  auto size() const;
  auto empty() const;
  void clear();
  auto find( const std::string& key ) const;
 
  bool known( const std::string& key ) const;
 
  void mark_as_accessed( const std::string& key ) const;
 
  bool has_been_accessed( const std::string& key ) const;
 
  void init_access_flags( const bool thread_local_dict = false ) const;
 
  void
  all_entries_accessed( const std::string& where, const std::string& what, const bool thread_local_dict = false ) const;
 
  template < DictionaryEntryType T >
  T get( const std::string& key ) const;
 
  template < typename T >
  std::vector< T >& get_or_create_vector( const std::string& key );
 
  template < typename T >
  bool update_value( const std::string& key, T& value ) const;
 
  template < Integer T >
  bool update_integer_value( const std::string& key, T& value ) const;
 
  bool update_dictionary( Dictionary& dict_out ) const;
};
 
template < typename T >
std::string
pretty_typename()
{
#ifdef HAVE_BOOST
  return boost::typeindex::type_id< T >().pretty_name();
#else
  return typeid( T ).name();
#endif
}
 
std::string get_typename( const any_type& operand );
 
std::string get_dict_typenames( const Dictionary& dict );
 
struct DictEntry_
{
  DictEntry_()
    : item( any_type() )
    , accessed( false )
  {
  }
 
  DictEntry_( const any_type& item )
    : item( item )
    , accessed( false )
  {
  }
 
  bool
  operator==( const DictEntry_& other ) const
  {
    return item == other.item;
  }
 
  any_type item;          
  mutable bool accessed;  
};
 
class dictionary_ : public std::map< std::string, DictEntry_ >
{
  using maptype_ = std::map< std::string, DictEntry_ >;
  using maptype_::maptype_;  // Inherit constructors
 
  template < typename T >
  T
  cast_value_( const any_type& value, const std::string& key ) const
  {
    try
    {
      return std::get< T >( value );
    }
    catch ( const std::bad_variant_access& )
    {
      std::string msg =
        String::compose( "Failed to cast '%1' from %2 to type %3", key, get_typename( value ), pretty_typename< T >() );
      throw nest::TypeMismatch( msg );
    }
  }
 
  template < Integer RetT >
  RetT
  cast_to_integer_( const any_type& value, const std::string& key ) const
  {
    return std::visit(
      [ key ]( auto&& arg ) -> RetT
      {
        using T = std::decay_t< decltype( arg ) >;
 
        // Compile-time check: Is it an Integer?
        if constexpr ( Integer< T > )
        {
          // Runtime check: Does the value fit safely?
          if ( std::in_range< RetT >( arg ) )
          {
            return static_cast< RetT >( arg );
          }
 
          throw std::out_of_range( "Value causes data loss or overflow." );
        }
        else
        {
          throw std::runtime_error(
            String::compose( "The dictionary value with key %1 does not hold a numeric integer type.", key ) );
        }
      },
      value );
  }
 
  void register_access_( const DictEntry_& entry ) const;
 
public:
  template < DictionaryEntryType T >
  T
  get( const std::string& key ) const
  {
    return cast_value_< T >( at( key ), key );
  }
 
  template < typename T >
  std::vector< T >&
  get_or_create_vector( const std::string& key )
  {
    // try_emplace will only insert if key doesn't exist.
    auto [ iter, success ] = maptype_::try_emplace( key, std::vector< T >() );
 
    return std::get< std::vector< T > >( iter->second.item );
  }
 
  template < typename T >
  bool
  update_value( const std::string& key, T& value ) const
  {
    auto it = find( key );
    if ( it != end() )
    {
      value = cast_value_< T >( it->second.item, key );
      return true;
    }
    return false;
  }
 
  template < Integer T >
  bool
  update_integer_value( const std::string& key, T& value ) const
  {
    auto it = find( key );
    if ( it != end() )
    {
      value = cast_to_integer_< T >( it->second.item, key );
      return true;
    }
    return false;
  }
 
  bool
  update_dictionary( Dictionary& dict_out ) const
  {
    for ( const auto& [ key, value ] : *this )
    {
      dict_out[ key ] = value.item;
    }
    return size() > 0;
  }
 
  bool
  known( const std::string& key ) const
  {
    return maptype_::contains( key );
  }
 
  void
  mark_as_accessed( const std::string& key ) const
  {
    register_access_( maptype_::at( key ) );
  }
 
  bool
  has_been_accessed( const std::string& key ) const
  {
    return maptype_::at( key ).accessed;
  }
 
  bool operator==( const dictionary_& other ) const;
 
  bool
  operator!=( const dictionary_& other ) const
  {
    return not( *this == other );
  }
 
  void init_access_flags( const bool thread_local_dict = false ) const;
 
  void
  all_entries_accessed( const std::string& where, const std::string& what, const bool thread_local_dict = false ) const;
 
  // Wrappers for access flags
  any_type& operator[]( const std::string& key );
  any_type& operator[]( std::string&& key );
  any_type& at( const std::string& key );
  const any_type& at( const std::string& key ) const;
  iterator find( const std::string& key );
  const_iterator find( const std::string& key ) const;
};
 
 
template <>
double dictionary_::cast_value_< double >( const any_type& value, const std::string& key ) const;
 
inline auto
Dictionary::begin() const
{
  return ( *this )->begin();
}
 
inline auto
Dictionary::end() const
{
  return ( *this )->end();
}
 
template <>
std::vector< double > dictionary_::cast_value_< std::vector< double > >( const any_type& value,
  const std::string& key ) const;
 
template <>
std::vector< std::string > dictionary_::cast_value_< std::vector< std::string > >( const any_type& value,
  const std::string& key ) const;
 
inline bool
Dictionary::operator==( const Dictionary& other ) const
{
  return **this == *other;
}
 
inline auto
Dictionary::size() const
{
  return ( *this )->size();
}
 
inline auto
Dictionary::empty() const
{
  return ( *this )->empty();
}
 
inline void
Dictionary::clear()
{
  ( *this )->clear();
}
 
inline auto
Dictionary::find( const std::string& key ) const
{
  return ( *this )->find( key );
}
 
inline bool
Dictionary::known( const std::string& key ) const
{
  return ( *this )->known( key );
}
 
inline void
Dictionary::mark_as_accessed( const std::string& key ) const
{
  ( *this )->mark_as_accessed( key );
}
 
inline bool
Dictionary::has_been_accessed( const std::string& key ) const
{
  return ( *this )->has_been_accessed( key );
}
 
inline void
Dictionary::init_access_flags( const bool thread_local_dict ) const
{
  ( *this )->init_access_flags( thread_local_dict );
}
 
inline void
Dictionary::all_entries_accessed( const std::string& where,
  const std::string& what,
  const bool thread_local_dict ) const
{
  ( *this )->all_entries_accessed( where, what, thread_local_dict );
}
 
template < DictionaryEntryType T >
inline T
Dictionary::get( const std::string& key ) const
{
  return ( *this )->get< T >( key );
}
template < typename T >
std::vector< T >&
Dictionary::get_or_create_vector( const std::string& key )
{
  return ( *this )->get_or_create_vector< T >( key );
}
 
template < typename T >
inline bool
Dictionary::update_value( const std::string& key, T& value ) const
{
  return ( *this )->update_value( key, value );
}
 
template < Integer T >
inline bool
Dictionary::update_integer_value( const std::string& key, T& value ) const
{
  return ( *this )->update_integer_value( key, value );
}
 
inline bool
Dictionary::update_dictionary( Dictionary& out_dict ) const
{
  return ( *this )->update_dictionary( out_dict );
}
 
#endif /* DICTIONARY_H */