text: // Copyright 2017 Yahoo Holdings. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
  /**
   * @author  Peter Boros
   * @date    2004/10/01
   * @version $Id$
   * @file    conceptnet.h
   * @brief   Concept network class definition.
   *
   */
  
  #pragma once
  
  #include <cassert>
  #include <stdlib.h>
  #include "file.h" // for FileAccessMethod
  #include "fsa.h"
  
  
  namespace fsa {
  
  // {{{ class ConceptNet
  
  /**
   * @class ConceptNet
   * @brief Class for compact representation of a concept network.
   */
  class ConceptNet {
  
  public:
  
    class Handle; // defined in conceptnethandle.h
  
  private:
    static const uint32_t MAGIC = 238579428;    /**< Magic number identifying concept net files. */
  
    static const FileAccessMethod _default_file_access_method = FILE_ACCESS_MMAP;   /**< Default file access method (read/mmap). */
  
    /**
     * @struct Header
     * @brief Concept net data file header.
     */
    struct Header {
      uint32_t _magic;             /**< Magic number.                        */
      uint32_t _version;           /**< Version number. (currently not used) */
      uint32_t _checksum;          /**< Checksum. (currently not used)       */
      uint32_t _index_size;        /**< Size of index structure.             */
      uint32_t _info_size;         /**< Size of info structure.              */
      uint32_t _catindex_size;     /**< Size of category index.              */
      uint32_t _strings_size;      /**< Size of string storage.              */
      uint32_t _max_freq;          /**< Reseved for normalization purposes.  */
      uint32_t _max_cfreq;         /**< Reseved for normalization purposes.  */
      uint32_t _max_qfreq;         /**< Reseved for normalization purposes.  */
      uint32_t _max_sfreq;         /**< Reseved for normalization purposes.  */
      uint32_t _max_efreq;         /**< Reseved for normalization purposes.  */
      uint32_t _max_afreq;         /**< Reseved for normalization purposes.  */
      uint32_t _dummy[51];         /**< Reserved.                            */
    };
  
    /**
     * @struct UnitData
     * @brief Unit data structure.
     */
    struct UnitData {
      uint32_t     _term;          /**< Offset of unit string in string storage.     */
      uint32_t     _frq;           /**< Unit frequency.                              */
      uint32_t     _cfrq;          /**< Frequency of the unit as complete query.     */
      uint32_t     _qfrq;          /**< Frequency of the unit as part of a query.    */
      uint32_t     _sfrq;          /**< Number of queries containing all unit terms. */
      uint32_t     _exts;          /**< If non-zero: offset of extension info in info structure.   */
      uint32_t     _assocs;        /**< If non-zero: offset of association info in info structure. */
      uint32_t     _cats;          /**< If non-zero: offset of category info in info structure.    */
    };
  
    void         *_mmap_addr;      /**< mmap address, NULL is file has not been mmapped.   */
    size_t        _mmap_length;    /**< mmap length.                                       */
  
    FSA           _unit_fsa;       /**< %FSA containing the units (with hash).    */
    uint32_t      _index_size;     /**< Size of the index structure.              */
    UnitData     *_index;          /**< Pointer to the index structure in memory. */
    uint32_t      _info_size;      /**< Size of the info structure.               */
    uint32_t     *_info;           /**< Pointer to the info structure in memory.  */
    uint32_t      _catindex_size;  /**< Size of the catergory index.              */
    uint32_t     *_catindex;       /**< Pointer to the category index in memory.  */
    uint32_t      _strings_size;   /**< Size of the string storage.               */
    char         *_strings;        /**< Pointer to the string storage in memory.  */
  
    bool _ok;                      /**< Flag indicating successful initialization. */
  
    /**
     * @brief Reset the object.
     *
     * Resets the object to an empty %ConceptNet, and releases allocated memory.
     */
    void reset();
  
    /**
     * @brief Read the concept net data file from disk.
     *
     * @param datafile Name of the concept net data file.
     * @param fam File access mode (read or mmap). If not set, the
     *            global default access mode will be used.
     * @return True on success.
     */
    bool read(const char *datafile, fsa::FileAccessMethod fam = FILE_ACCESS_UNDEF);
  
    /**
     * @brief Unimplemented private default constructor.
     */
    ConceptNet();
    /**
     * @brief Unimplemented private copy constructor.
     */
    ConceptNet(const ConceptNet&);
    /**
     * @brief Unimplemented private assignement operator.
     */
    const ConceptNet& operator=(const ConceptNet&);
  
  public:
  
    /**
     * @brief Constructor.
     *
     * @param fsafile %FSA file containing the units, with a perfect has
     *                (used for indexing the data file).
     * @param datafile Concept net data file.
     * @param fam File access mode (read or mmap). If not set, the
     *            global default access mode will be used.
     */
    ConceptNet(const char *fsafile, const char *datafile=NULL, FileAccessMethod fam = FILE_ACCESS_UNDEF);
    ConceptNet(const std::string &fsafile, const std::string &datafile, FileAccessMethod fam = FILE_ACCESS_UNDEF);
  
    /**
     * @brief Destructor.
     */
    virtual ~ConceptNet();
  
    /**
     * @brief Check if initialization was successful.
     *
     * @return True if the initialization of the object succeeded.
     */
    bool isOk() const
    {
      return _ok;
    }
  
    /**
     * @brief Get the concept net %FSA.
     *
     * Get the concept net %FSA. The object continues to be owned by the
     * concept net.
     *
     * @return The concept net %FSA.
     */
    const FSA& getFSA() const
    {
      assert(_ok);
      return _unit_fsa;
    }
  
    /**
     * @brief Look up a unit.
     *
     * Look up a unit in the concept net, and get its index.
     *
     * @param unit Unit string.
     * @return Index of the unit, or -1 if not found.
     */
    int lookup(const char *unit) const;
  
    /**
     * @brief Look up a unit index.
     *
     * Look up a unit index in the concept net, and get the unit string.
     *
     * @param idx Unit index.
     * @return Pointer to the unit string, or NULL if index is out of range.
     */
    const char * lookup(int idx) const;
  
    /**
     * @brief Get the unit frequency of the unit.
     *
     * @param idx Unit index.
     * @return Unit frequency, or -1 if the index is out of range.
     */
    int frq(int idx) const;
  
    /**
     * @brief Get the unit frequency of the unit.
     *
     * @param unit Unit string.
     * @return Unit frequency, or -1 if the unit is not found.
     */
    int frq(const char *unit) const;
  
    /**
     * @brief Get the frequency of the unit as a complete query.
     *
     * @param idx Unit index.
     * @return Unit-C frequency, or -1 if the index is out of range.
     */
    int cFrq(int idx) const;
  
    /**
     * @brief Get the frequency of the unit as a complete query.
     *
     * @param unit Unit string.
     * @return Unit-C frequency, or -1 if the unit is not found.
     */
    int cFrq(const char *unit) const;
  
    /**
     * @brief Get the frequency of the unit as part of a query.
     *
     * @param idx Unit index.
     * @return Unit-Q frequency, or -1 if the index is out of range.
     */
    int qFrq(int idx) const;
  
    /**
     * @brief Get the frequency of the unit as part of a query.
     *
     * @param unit Unit string.
     * @return Unit-Q frequency, or -1 if the unit is not found.
     */
    int qFrq(const char *unit) const;
  
    /**
     * @brief Get the frequency of queries containing all terms of the unit.
     *
     * @param idx Unit index.
     * @return Unit-S frequency, or -1 if the index is out of range.
     */
    int sFrq(int idx) const;
  
    /**
     * @brief Get the frequency of queries containing all terms of the unit.
     *
     * @param unit Unit string.
     * @return Unit-Q frequency, or -1 if the unit is not found.
     */
    int sFrq(const char *unit) const;
  
    /**
     * @brief Get the unit score (100.0*cFrq/qFrq).
     *
     * @param idx Unit index.
     * @return Unit score, or -1.0 if the index is out of range.
     */
    double score(int idx) const;
  
    /**
     * @brief Get the unit score (100.0*cFrq/qFrq).
     *
     * @param unit Unit string.
     * @return Unit score, or -1. if the unit is not found.
     */
    double score(const char *unit) const;
  
    /**
     * @brief Get the unit strength (100.0*qFrq/sFrq).
     *
     * @param idx Unit index.
     * @return Unit strength, or -1.0 if the index is out of range.
     */
    double strength(int idx) const;
  
    /**
     * @brief Get the unit strength (100.0*qFrq/sFrq).
     *
     * @param unit Unit string.
     * @return Unit strength, or -1. if the unit is not found.
     */
    double strength(const char *unit) const;
  
    /**
     * @brief Get the number of extensions for the unit.
     *
     * @param idx Unit index.
     * @return Number of extensions for the unit, -1 if the index is out
     *         of range.
     */
    int numExt(int idx) const;
  
    /**
     * @brief Get the number of associations for the unit.
     *
     * @param idx Unit index.
     * @return Number of associations for the unit, -1 if the index is out
     *         of range.
     */
    int numAssoc(int idx) const;
  
    /**
     * @brief Get the number of categories for the unit.
     *
     * @param idx Unit index.
     * @return Number of categories for the unit, -1 if the index is out
     *         of range.
     */
    int numCat(int idx) const;
  
    /**
     * @brief Get the index of an extension.
     *
     * @param idx Unit index.
     * @param j Number of the extension (extensions of each unit are
     *          sorted by decreasing weight).
     * @return Extension (unit) index, -1 if idx or j is out
     *         of range.
     */
    int ext(int idx, int j) const;
  
    /**
     * @brief Get the frequency of an extension.
     *
     * @param idx Unit index.
     * @param j Number of the extension (extensions of each unit are
     *          sorted by decreasing weight).
     * @return Extension frequency, -1 if idx or j is out
     *         of range.
     */
    int extFrq(int idx, int j) const;
  
    /**
     * @brief Get the index of an association.
     *
     * @param idx Unit index.
     * @param j Number of the association (associations of each unit are
     *          sorted by decreasing weight).
     * @return Association (unit) index, -1 if idx or j is out
     *         of range.
     */
    int assoc(int idx, int j) const;
  
    /**
     * @brief Get the frequency of an association.
     *
     * @param idx Unit index.
     * @param j Number of the association (associations of each unit are
     *          sorted by decreasing weight).
     * @return Association frequency, -1 if idx or j is out
     *         of range.
     */
    int assocFrq(int idx, int j) const;
  
    /**
     * @brief Get the index of a category.
     *
     * @param idx Unit index.
     * @param j Number of the category.
     * @return Catergory index, -1 if idx or j is out of range.
     */
    int cat(int idx, int j) const;
  
    /**
     * @brief Get the name of a category.
     *
     * @param catIdx Category index.
     * @return Catergory name, or NULL if catIdx is out of range.
     */
    const char *catName(int catIdx) const;
  
  };
  
  // }}}
  
  } // namespace fsa
  
  