chaine 3.13.1__cp313-cp313-musllinux_1_2_x86_64.whl

chaine/_core/crfsuite/include/crfsuite.h

@@ -0,0 +1,1077 @@
+/*
+ *      CRFsuite library.
+ *
+ * Copyright (c) 2007-2010, Naoaki Okazaki
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the names of the authors nor the names of its contributors
+ *       may be used to endorse or promote products derived from this
+ *       software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/* $Id$ */
+
+#ifndef __CRFSUITE_H__
+#define __CRFSUITE_H__
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif /*__cplusplus*/
+
+#include <limits.h>
+#include <stdio.h>
+#include <stdarg.h>
+
+/**
+ * \addtogroup crfsuite_api CRFSuite C API
+ * @{
+ *
+ *  The CRFSuite C API provides a low-level library for manupulating
+ *  CRFSuite in C language.
+ */
+
+/**
+ * \addtogroup crfsuite_misc Miscellaneous definitions and functions
+ * @{
+ */
+
+/** Version number of CRFSuite library. */
+#define CRFSUITE_VERSION "0.12.2"
+
+/** Copyright string of CRFSuite library. */
+#define CRFSUITE_COPYRIGHT "Copyright (c) 2007-2013 Naoaki Okazaki"
+
+   /** Type of a float value. */
+   typedef double floatval_t;
+
+/** Maximum value of a float value. */
+#define FLOAT_MAX DBL_MAX
+
+   /**
+    * Status codes.
+    */
+   enum
+   {
+      /** Success. */
+      CRFSUITE_SUCCESS = 0,
+      /** Unknown error occurred. */
+      CRFSUITEERR_UNKNOWN = INT_MIN,
+      /** Insufficient memory. */
+      CRFSUITEERR_OUTOFMEMORY,
+      /** Unsupported operation. */
+      CRFSUITEERR_NOTSUPPORTED,
+      /** Incompatible data. */
+      CRFSUITEERR_INCOMPATIBLE,
+      /** Internal error. */
+      CRFSUITEERR_INTERNAL_LOGIC,
+      /** Overflow. */
+      CRFSUITEERR_OVERFLOW,
+      /** Not implemented. */
+      CRFSUITEERR_NOTIMPLEMENTED,
+   };
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_object Object interfaces and utilities.
+    * @{
+    */
+
+   struct tag_crfsuite_model;
+   /** CRFSuite model interface. */
+   typedef struct tag_crfsuite_model crfsuite_model_t;
+
+   struct tag_crfsuite_trainer;
+   /** CRFSuite trainer interface. */
+   typedef struct tag_crfsuite_trainer crfsuite_trainer_t;
+
+   struct tag_crfsuite_tagger;
+   /** CRFSuite tagger interface. */
+   typedef struct tag_crfsuite_tagger crfsuite_tagger_t;
+
+   struct tag_crfsuite_dictionary;
+   /** CRFSuite dictionary interface. */
+   typedef struct tag_crfsuite_dictionary crfsuite_dictionary_t;
+
+   struct tag_crfsuite_params;
+   /** CRFSuite parameter interface. */
+   typedef struct tag_crfsuite_params crfsuite_params_t;
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_data Dataset (attribute, item, instance, dataset)
+    * @{
+    */
+
+   /**
+    * An attribute.
+    *  An attribute consists of an attribute id with its value.
+    */
+   typedef struct
+   {
+      int aid;          /**< Attribute id. */
+      floatval_t value; /**< Value of the attribute. */
+   } crfsuite_attribute_t;
+
+   /**
+    * An item.
+    *  An item consists of an array of attributes.
+    */
+   typedef struct
+   {
+      /** Number of contents associated with the item. */
+      int num_contents;
+      /** Maximum number of contents (internal use). */
+      int cap_contents;
+      /** Array of the attributes. */
+      crfsuite_attribute_t *contents;
+   } crfsuite_item_t;
+
+   /**
+    * An instance (sequence of items and labels).
+    *  An instance consists of a sequence of items and labels.
+    */
+   typedef struct
+   {
+      /** Number of items/labels in the sequence. */
+      int num_items;
+      /** Maximum number of items/labels (internal use). */
+      int cap_items;
+      /** Array of the item sequence. */
+      crfsuite_item_t *items;
+      /** Array of the label sequence. */
+      int *labels;
+      /** Instance weight. */
+      floatval_t weight;
+      /** Group ID of the instance. */
+      int group;
+   } crfsuite_instance_t;
+
+   /**
+    * A data set.
+    *  A data set consists of an array of instances and dictionary objects
+    *  for attributes and labels.
+    */
+   typedef struct
+   {
+      /** Number of instances. */
+      int num_instances;
+      /** Maximum number of instances (internal use). */
+      int cap_instances;
+      /** Array of instances. */
+      crfsuite_instance_t *instances;
+
+      /** Dictionary object for attributes. */
+      crfsuite_dictionary_t *attrs;
+      /** Dictionary object for labels. */
+      crfsuite_dictionary_t *labels;
+   } crfsuite_data_t;
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_evaluation Evaluation utility
+    * @{
+    */
+
+   /**
+    * Label-wise performance values.
+    */
+   typedef struct
+   {
+      /** Number of correct predictions. */
+      int num_correct;
+      /** Number of occurrences of the label in the gold-standard data. */
+      int num_observation;
+      /** Number of predictions. */
+      int num_model;
+      /** Precision. */
+      floatval_t precision;
+      /** Recall. */
+      floatval_t recall;
+      /** F1 score. */
+      floatval_t fmeasure;
+   } crfsuite_label_evaluation_t;
+
+   /**
+    * An overall performance values.
+    */
+   typedef struct
+   {
+      /** Number of labels. */
+      int num_labels;
+      /** Array of label-wise evaluations. */
+      crfsuite_label_evaluation_t *tbl;
+
+      /** Number of correctly predicted items. */
+      int item_total_correct;
+      /** Total number of items. */
+      int item_total_num;
+      /** Total number of occurrences of labels in the gold-standard data. */
+      int item_total_observation;
+      /** Total number of predictions. */
+      int item_total_model;
+      /** Item-level accuracy. */
+      floatval_t item_accuracy;
+
+      /** Number of correctly predicted instances. */
+      int inst_total_correct;
+      /** Total number of instances. */
+      int inst_total_num;
+      /** Instance-level accuracy. */
+      floatval_t inst_accuracy;
+
+      /** Macro-averaged precision. */
+      floatval_t macro_precision;
+      /** Macro-averaged recall. */
+      floatval_t macro_recall;
+      /** Macro-averaged F1 score. */
+      floatval_t macro_fmeasure;
+   } crfsuite_evaluation_t;
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_object
+    * @{
+    */
+
+   /**
+    * Type of callback function for logging.
+    *  @param  user        Pointer to the user-defined data.
+    *  @param  format      Format string (compatible with prinf()).
+    *  @param  args        Optional arguments for the format string.
+    *  @return int         \c 0 to continue; non-zero to cancel the training.
+    */
+   typedef int (*crfsuite_logging_callback)(void *user, const char *format, va_list args);
+
+   /**
+    * CRFSuite model interface.
+    */
+   struct tag_crfsuite_model
+   {
+      /**
+       * Pointer to the internal data (internal use only).
+       */
+      void *internal;
+
+      /**
+       * Reference counter (internal use only).
+       */
+      int nref;
+
+      /**
+       * Increment the reference counter.
+       *  @param  model       The pointer to this model instance.
+       *  @return int         The reference count after this increment.
+       */
+      int (*addref)(crfsuite_model_t *model);
+
+      /**
+       * Decrement the reference counter.
+       *  @param  model       The pointer to this model instance.
+       *  @return int         The reference count after this operation.
+       */
+      int (*release)(crfsuite_model_t *model);
+
+      /**
+       * Obtain the pointer to crfsuite_tagger_t interface.
+       *  @param  model       The pointer to this model instance.
+       *  @param  ptr_tagger  The pointer that receives a crfsuite_tagger_t
+       *                      pointer.
+       *  @return int         The status code.
+       */
+      int (*get_tagger)(crfsuite_model_t *model, crfsuite_tagger_t **ptr_tagger);
+
+      /**
+       * Obtain the pointer to crfsuite_dictionary_t interface for labels.
+       *  @param  model       The pointer to this model instance.
+       *  @param  ptr_labels  The pointer that receives a crfsuite_dictionary_t
+       *                      pointer.
+       *  @return int         The status code.
+       */
+      int (*get_labels)(crfsuite_model_t *model, crfsuite_dictionary_t **ptr_labels);
+
+      /**
+       * Obtain the pointer to crfsuite_dictionary_t interface for attributes.
+       *  @param  model       The pointer to this model instance.
+       *  @param  ptr_attrs   The pointer that receives a crfsuite_dictionary_t
+       *                      pointer.
+       *  @return int         The status code.
+       */
+      int (*get_attrs)(crfsuite_model_t *model, crfsuite_dictionary_t **ptr_attrs);
+
+      /**
+       * Print the learned transitions as JSON.
+       *  @param  model       The pointer to this model instance.
+       *  @param  fpo         The FILE* pointer.
+       *  @return int         The status code.
+       */
+      int (*dump_transitions)(crfsuite_model_t *model, FILE *fpo);
+
+      /**
+       * Print the learned states as JSON.
+       *  @param  model       The pointer to this model instance.
+       *  @param  fpo         The FILE* pointer.
+       *  @return int         The status code.
+       */
+      int (*dump_states)(crfsuite_model_t *model, FILE *fpo);
+   };
+
+   /**
+    * CRFSuite trainer interface.
+    */
+   struct tag_crfsuite_trainer
+   {
+      /**
+       * Pointer to the internal data (internal use only).
+       */
+      void *internal;
+
+      /**
+       * Reference counter (internal use only).
+       */
+      int nref;
+
+      /**
+       * Increment the reference counter.
+       *  @param  trainer     The pointer to this trainer instance.
+       *  @return int         The reference count after this increment.
+       */
+      int (*addref)(crfsuite_trainer_t *trainer);
+
+      /**
+       * Decrement the reference counter.
+       *  @param  trainer     The pointer to this trainer instance.
+       *  @return int         The reference count after this operation.
+       */
+      int (*release)(crfsuite_trainer_t *trainer);
+
+      /**
+       * Obtain the pointer to crfsuite_params_t interface.
+       *  @param  trainer     The pointer to this trainer instance.
+       *  @return crfsuite_params_t*  The pointer to crfsuite_params_t.
+       */
+      crfsuite_params_t *(*params)(crfsuite_trainer_t *trainer);
+
+      /**
+       * Set the callback function and user-defined data.
+       *  @param  trainer     The pointer to this trainer instance.
+       *  @param  user        The pointer to the user-defined data.
+       *  @param  cbm         The pointer to the callback function.
+       */
+      void (*set_message_callback)(crfsuite_trainer_t *trainer, void *user, crfsuite_logging_callback cbm);
+
+      /**
+       * Start a training process.
+       *  @param  trainer     The pointer to this trainer instance.
+       *  @param  data        The poiinter to the data set.
+       *  @param  filename    The filename to which the trainer stores the model.
+       *                      If an empty string is specified, this function
+       *                      does not sture the model to a file.
+       *  @param  holdout     The holdout group.
+       *  @return int         The status code.
+       */
+      int (*train)(crfsuite_trainer_t *trainer, const crfsuite_data_t *data, const char *filename, int holdout);
+   };
+
+   /**
+    * CRFSuite tagger interface.
+    */
+   struct tag_crfsuite_tagger
+   {
+      /**
+       * Pointer to the internal data (internal use only).
+       */
+      void *internal;
+
+      /**
+       * Reference counter (internal use only).
+       */
+      int nref;
+
+      /**
+       * Increment the reference counter.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @return int         The reference count after this increment.
+       */
+      int (*addref)(crfsuite_tagger_t *tagger);
+
+      /**
+       * Decrement the reference counter.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @return int         The reference count after this operation.
+       */
+      int (*release)(crfsuite_tagger_t *tagger);
+
+      /**
+       * Set an instance to the tagger.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  inst        The item sequence to be tagged.
+       *  @return int         The status code.
+       */
+      int (*set)(crfsuite_tagger_t *tagger, crfsuite_instance_t *inst);
+
+      /**
+       * Obtain the number of items in the current instance.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @return int         The number of items of the instance set by
+       *                      set() function.
+       *  @return int         The status code.
+       */
+      int (*length)(crfsuite_tagger_t *tagger);
+
+      /**
+       * Find the Viterbi label sequence.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  labels      The label array that receives the Viterbi label
+       *                      sequence. The number of elements in the array must
+       *                      be no smaller than the number of item.
+       *  @param  ptr_score   The pointer to a float variable that receives the
+       *                      score of the Viterbi label sequence.
+       *  @return int         The status code.
+       */
+      int (*viterbi)(crfsuite_tagger_t *tagger, int *labels, floatval_t *ptr_score);
+
+      /**
+       * Compute the score of a label sequence.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  path        The label sequence.
+       *  @param  ptr_score   The pointer to a float variable that receives the
+       *                      score of the label sequence.
+       *  @return int         The status code.
+       */
+      int (*score)(crfsuite_tagger_t *tagger, int *path, floatval_t *ptr_score);
+
+      /**
+       * Compute the log of the partition factor (normalization constant).
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  ptr_score   The pointer to a float variable that receives the
+       *                      logarithm of the partition factor.
+       *  @return int         The status code.
+       */
+      int (*lognorm)(crfsuite_tagger_t *tagger, floatval_t *ptr_norm);
+
+      /**
+       * Compute the marginal probability of a label at a position.
+       *  This function computes P(y_t = l | x), the probability when
+       *  y_t is the label (l).
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  l           The label.
+       *  @param  t           The position.
+       *  @param  ptr_prob    The pointer to a float variable that receives the
+       *                      marginal probability.
+       *  @return int         The status code.
+       */
+      int (*marginal_point)(crfsuite_tagger_t *tagger, int l, int t, floatval_t *ptr_prob);
+
+      /**
+       * Compute the marginal probability of a partial label sequence.
+       *  @param  tagger      The pointer to this tagger instance.
+       *  @param  path        The partial label sequence.
+       *  @param  begin       The start position of the partial label sequence.
+       *  @param  end         The last+1 position of the partial label sequence.
+       *  @param  ptr_prob    The pointer to a float variable that receives the
+       *                      marginal probability.
+       *  @return int         The status code.
+       */
+      int (*marginal_path)(crfsuite_tagger_t *tagger, const int *path, int begin, int end, floatval_t *ptr_prob);
+   };
+
+   /**
+    * CRFSuite dictionary interface.
+    */
+   struct tag_crfsuite_dictionary
+   {
+      /**
+       * Pointer to the internal data (internal use only).
+       */
+      void *internal;
+
+      /**
+       * Reference counter (internal use only).
+       */
+      int nref;
+
+      /**
+       * Increment the reference counter.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @return int         The reference count after this increment.
+       */
+      int (*addref)(crfsuite_dictionary_t *dic);
+
+      /**
+       * Decrement the reference counter.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @return int         The reference count after this operation.
+       */
+      int (*release)(crfsuite_dictionary_t *dic);
+
+      /**
+       * Assign and obtain the integer ID for the string.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @param  str         The string.
+       *  @return int         The ID associated with the string if any,
+       *                      the new ID otherwise.
+       */
+      int (*get)(crfsuite_dictionary_t *dic, const char *str);
+
+      /**
+       * Obtain the integer ID for the string.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @param  str         The string.
+       *  @return int         The ID associated with the string if any,
+       *                      \c -1 otherwise.
+       */
+      int (*to_id)(crfsuite_dictionary_t *dic, const char *str);
+
+      /**
+       * Obtain the string for the ID.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @param  id          the string ID.
+       *  @param  pstr        \c *pstr points to the string associated with
+       *                      the ID if any, \c NULL otherwise.
+       *  @return int         \c 0 if the string ID is associated with a string,
+       *                      \c 1 otherwise.
+       */
+      int (*to_string)(crfsuite_dictionary_t *dic, int id, char const **pstr);
+
+      /**
+       * Obtain the number of strings in the dictionary.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @return int         The number of strings stored in the dictionary.
+       */
+      int (*num)(crfsuite_dictionary_t *dic);
+
+      /**
+       * Free the memory block allocated by to_string() function.
+       *  @param  dic         The pointer to this dictionary instance.
+       *  @param  str         The pointer to the string whose memory block is
+       *                      freed.
+       */
+      void (*free)(crfsuite_dictionary_t *dic, const char *str);
+   };
+
+   /**
+    * CRFSuite parameter interface.
+    */
+   struct tag_crfsuite_params
+   {
+      /**
+       * Pointer to the instance data (internal use only).
+       */
+      void *internal;
+
+      /**
+       * Reference counter (internal use only).
+       */
+      int nref;
+
+      /**
+       * Increment the reference counter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @return int         The reference count after this increment.
+       */
+      int (*addref)(crfsuite_params_t *params);
+
+      /**
+       * Decrement the reference counter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @return int         The reference count after this operation.
+       */
+      int (*release)(crfsuite_params_t *params);
+
+      /**
+       * Obtain the number of available parameters.
+       *  @param  params      The pointer to this parameter instance.
+       *  @return int         The number of parameters maintained by this object.
+       */
+      int (*num)(crfsuite_params_t *params);
+
+      /**
+       * Obtain the name of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  i           The parameter index.
+       *  @param  ptr_name    *ptr_name points to the parameter name.
+       *  @return int         \c 0 always.
+       */
+      int (*name)(crfsuite_params_t *params, int i, char **ptr_name);
+
+      /**
+       * Set a parameter value.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  value       The parameter value in string format.
+       *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
+       */
+      int (*set)(crfsuite_params_t *params, const char *name, const char *value);
+
+      /**
+       * Get a parameter value.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  ptr_value   *ptr_value presents the parameter value in string
+       *                      format.
+       *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
+       */
+      int (*get)(crfsuite_params_t *params, const char *name, char **ptr_value);
+
+      /**
+       * Set an integer value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  value       The parameter value.
+       *  @return int         \c 0 if the parameter value is set successfully,
+       *                      \c -1 otherwise (unknown parameter or incompatible
+       *                      type).
+       */
+      int (*set_int)(crfsuite_params_t *params, const char *name, int value);
+
+      /**
+       * Set a float value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  value       The parameter value.
+       *  @return int         \c 0 if the parameter value is set successfully,
+       *                      \c -1 otherwise (unknown parameter or incompatible
+       *                      type).
+       */
+      int (*set_float)(crfsuite_params_t *params, const char *name, floatval_t value);
+
+      /**
+       * Set a string value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  value       The parameter value.
+       *  @return int         \c 0 if the parameter value is set successfully,
+       *                      \c -1 otherwise (unknown parameter or incompatible
+       *                      type).
+       */
+      int (*set_string)(crfsuite_params_t *params, const char *name, const char *value);
+
+      /**
+       * Get an integer value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  ptr_value   The pointer to a variable that receives the
+       *                      integer value.
+       *  @return int         \c 0 if the parameter value is obtained
+       *                      successfully, \c -1 otherwise (unknown parameter
+       *                      or incompatible type).
+       */
+      int (*get_int)(crfsuite_params_t *params, const char *name, int *ptr_value);
+
+      /**
+       * Get a float value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  ptr_value   The pointer to a variable that receives the
+       *                      float value.
+       *  @return int         \c 0 if the parameter value is obtained
+       *                      successfully, \c -1 otherwise (unknown parameter
+       *                      or incompatible type).
+       */
+      int (*get_float)(crfsuite_params_t *params, const char *name, floatval_t *ptr_value);
+
+      /**
+       * Get a string value of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  ptr_value   *ptr_value presents the parameter value.
+       *  @return int         \c 0 if the parameter value is obtained
+       *                      successfully, \c -1 otherwise (unknown parameter
+       *                      or incompatible type).
+       */
+      int (*get_string)(crfsuite_params_t *params, const char *name, char **ptr_value);
+
+      /**
+       * Get the help message of a parameter.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  name        The parameter name.
+       *  @param  ptr_type    The pointer to \c char* to which this function
+       *                      store the type of the parameter.
+       *  @param  ptr_help    The pointer to \c char* to which this function
+       *                      store the help message of the parameter.
+       *  @return int         \c 0 if the parameter is found, \c -1 otherwise.
+       */
+      int (*help)(crfsuite_params_t *params, const char *name, char **ptr_type, char **ptr_help);
+
+      /**
+       * Free the memory block of a string allocated by this object.
+       *  @param  params      The pointer to this parameter instance.
+       *  @param  str         The pointer to the string.
+       */
+      void (*free)(crfsuite_params_t *params, const char *str);
+   };
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_object
+    * @{
+    */
+
+   /**
+    * Create an instance of an object by an interface identifier.
+    *  @param  iid         The interface identifier.
+    *  @param  ptr         The pointer to \c void* that points to the
+    *                      instance of the object if successful,
+    *                      *ptr points to \c NULL otherwise.
+    *  @return int         \c 1 if this function creates an object successfully,
+    *                      \c 0 otherwise. Note that this is inconsistent with the
+    *                      other CRFsuite API calls.
+    */
+   int crfsuite_create_instance(const char *iid, void **ptr);
+
+   /**
+    * Create an instance of a model object from a model file.
+    *  @param  filename    The filename of the model.
+    *  @param  ptr         The pointer to \c void* that points to the
+    *                      instance of the model object if successful,
+    *                      *ptr points to \c NULL otherwise.
+    *  @return int         \c 0 if this function creates an object successfully,
+    *                      \c 1 otherwise.
+    */
+   int crfsuite_create_instance_from_file(const char *filename, void **ptr);
+
+   /**
+    * Create an instance of a model object from a model in memory.
+    *  @param  data        A pointer to the model data.
+    *                      Must be 16-byte aligned.
+    *  @param  size        A size (in bytes) of the model data.
+    *  @param  ptr         The pointer to \c void* that points to the
+    *                      instance of the model object if successful,
+    *                      *ptr points to \c NULL otherwise.
+    *  @return int         \c 0 if this function creates an object successfully,
+    *                      \c 1 otherwise
+    */
+   int crfsuite_create_instance_from_memory(const void *data, size_t size, void **ptr);
+
+   /**
+    * Create instances of tagging object from a model file.
+    *  @param  filename    The filename of the model.
+    *  @param  ptr_tagger  The pointer to \c void* that points to the
+    *                      instance of the tagger object if successful,
+    *                      *ptr points to \c NULL otherwise.
+    *  @param  ptr_attrs   The pointer to \c void* that points to the
+    *                      instance of the dictionary object for attributes
+    *                      if successful, *ptr points to \c NULL otherwise.
+    *  @param  ptr_labels  The pointer to \c void* that points to the
+    *                      instance of the dictionary object for labels
+    *                      if successful, *ptr points to \c NULL otherwise.
+    *  @return int         \c 0 if this function creates an object successfully,
+    *                      \c 1 otherwise.
+    */
+   int crfsuite_create_tagger(
+       const char *filename,
+       crfsuite_tagger_t **ptr_tagger,
+       crfsuite_dictionary_t **ptr_attrs,
+       crfsuite_dictionary_t **ptr_labels);
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_data
+    * @{
+    */
+
+   /**
+    * Initialize an attribute structure.
+    *  @param  attr        The pointer to crfsuite_attribute_t.
+    */
+   void crfsuite_attribute_init(crfsuite_attribute_t *attr);
+
+   /**
+    * Set an attribute and its value.
+    *  @param  attr        The pointer to crfsuite_attribute_t.
+    *  @param  aid         The attribute identifier.
+    *  @param  value       The attribute value.
+    */
+   void crfsuite_attribute_set(crfsuite_attribute_t *attr, int aid, floatval_t value);
+
+   /**
+    * Copy the content of an attribute structure.
+    *  @param  dst         The pointer to the destination.
+    *  @param  src         The pointer to the source.
+    */
+   void crfsuite_attribute_copy(crfsuite_attribute_t *dst, const crfsuite_attribute_t *src);
+
+   /**
+    * Swap the contents of two attribute structures.
+    *  @param  x           The pointer to an attribute structure.
+    *  @param  y           The pointer to another attribute structure.
+    */
+   void crfsuite_attribute_swap(crfsuite_attribute_t *x, crfsuite_attribute_t *y);
+
+   /**
+    * Initialize an item structure.
+    *  @param  item        The pointer to crfsuite_item_t.
+    */
+   void crfsuite_item_init(crfsuite_item_t *item);
+
+   /**
+    * Initialize an item structure with the number of attributes.
+    *  @param  item        The pointer to crfsuite_item_t.
+    *  @param  num_attributes  The number of attributes.
+    */
+   void crfsuite_item_init_n(crfsuite_item_t *item, int num_attributes);
+
+   /**
+    * Uninitialize an item structure.
+    *  @param  item        The pointer to crfsuite_item_t.
+    */
+   void crfsuite_item_finish(crfsuite_item_t *item);
+
+   /**
+    * Copy the content of an item structure.
+    *  @param  dst         The pointer to the destination.
+    *  @param  src         The pointer to the source.
+    */
+   void crfsuite_item_copy(crfsuite_item_t *dst, const crfsuite_item_t *src);
+
+   /**
+    * Swap the contents of two item structures.
+    *  @param  x           The pointer to an item structure.
+    *  @param  y           The pointer to another item structure.
+    */
+   void crfsuite_item_swap(crfsuite_item_t *x, crfsuite_item_t *y);
+
+   /**
+    * Append an attribute to the item structure.
+    *  @param  item        The pointer to crfsuite_item_t.
+    *  @param  attr        The attribute to be added to the item.
+    *  @return int         \c 0 if successful, \c -1 otherwise.
+    */
+   int crfsuite_item_append_attribute(crfsuite_item_t *item, const crfsuite_attribute_t *attr);
+
+   /**
+    * Check whether the item has no attribute.
+    *  @param  item        The pointer to crfsuite_item_t.
+    *  @return int         \c 1 if the item has no attribute, \c 0 otherwise.
+    */
+   int crfsuite_item_empty(crfsuite_item_t *item);
+
+   /**
+    * Initialize an instance structure.
+    *  @param  seq         The pointer to crfsuite_instance_t.
+    */
+   void crfsuite_instance_init(crfsuite_instance_t *seq);
+
+   /**
+    * Initialize an instance structure with the number of items.
+    *  @param  seq         The pointer to crfsuite_instance_t.
+    *  @param  num_items   The number of items.
+    */
+   void crfsuite_instance_init_n(crfsuite_instance_t *seq, int num_items);
+
+   /**
+    * Uninitialize an instance structure.
+    *  @param  seq         The pointer to crfsuite_instance_t.
+    */
+   void crfsuite_instance_finish(crfsuite_instance_t *seq);
+
+   /**
+    * Copy the content of an instance structure.
+    *  @param  dst         The pointer to the destination.
+    *  @param  src         The pointer to the source.
+    */
+   void crfsuite_instance_copy(crfsuite_instance_t *dst, const crfsuite_instance_t *src);
+
+   /**
+    * Swap the contents of two instance structures.
+    *  @param  x           The pointer to an instance structure.
+    *  @param  y           The pointer to another instance structure.
+    */
+   void crfsuite_instance_swap(crfsuite_instance_t *x, crfsuite_instance_t *y);
+
+   /**
+    * Append a pair of item and label to the instance structure.
+    *  @param  seq         The pointer to crfsuite_instance_t.
+    *  @param  item        The item to be added to the instance.
+    *  @param  label       The label to be added to the instance.
+    *  @return int         \c 0 if successful, \c -1 otherwise.
+    */
+   int crfsuite_instance_append(crfsuite_instance_t *seq, const crfsuite_item_t *item, int label);
+
+   /**
+    * Check whether the instance has no item.
+    *  @param  seq         The pointer to crfsuite_instance_t.
+    *  @return int         \c 1 if the instance has no attribute, \c 0 otherwise.
+    */
+   int crfsuite_instance_empty(crfsuite_instance_t *seq);
+
+   /**
+    * Initialize a dataset structure.
+    *  @param  data        The pointer to crfsuite_data_t.
+    */
+   void crfsuite_data_init(crfsuite_data_t *data);
+
+   /**
+    * Initialize a dataset structure with the number of instances.
+    *  @param  data        The pointer to crfsuite_data_t.
+    *  @param  n           The number of instances.
+    */
+   void crfsuite_data_init_n(crfsuite_data_t *data, int n);
+
+   /**
+    * Uninitialize a dataset structure.
+    *  @param  data        The pointer to crfsuite_data_t.
+    */
+   void crfsuite_data_finish(crfsuite_data_t *data);
+
+   /**
+    * Copy the content of a dataset structure.
+    *  @param  dst         The pointer to the destination.
+    *  @param  src         The pointer to the source.
+    */
+   void crfsuite_data_copy(crfsuite_data_t *dst, const crfsuite_data_t *src);
+
+   /**
+    * Swap the contents of two dataset structures.
+    *  @param  x           The pointer to a dataset structure.
+    *  @param  y           The pointer to another dataset structure.
+    */
+   void crfsuite_data_swap(crfsuite_data_t *x, crfsuite_data_t *y);
+
+   /**
+    * Append an instance to the dataset structure.
+    *  @param  data        The pointer to crfsuite_data_t.
+    *  @param  inst        The instance to be added to the dataset.
+    *  @return int         \c 0 if successful, \c -1 otherwise.
+    */
+   int crfsuite_data_append(crfsuite_data_t *data, const crfsuite_instance_t *inst);
+
+   /**
+    * Obtain the maximum length of the instances in the dataset.
+    *  @param  data        The pointer to crfsuite_data_t.
+    *  @return int         The maximum number of items of the instances in the
+    *                      dataset.
+    */
+   int crfsuite_data_maxlength(crfsuite_data_t *data);
+
+   /**
+    * Obtain the total number of items in the dataset.
+    *  @param  data        The pointer to crfsuite_data_t.
+    *  @return int         The total number of items in the dataset.
+    */
+   int crfsuite_data_totalitems(crfsuite_data_t *data);
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_evaluation
+    */
+   /**@{*/
+
+   /**
+    * Initialize an evaluation structure.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    *  @param  n           The number of labels in the dataset.
+    */
+   void crfsuite_evaluation_init(crfsuite_evaluation_t *eval, int n);
+
+   /**
+    * Uninitialize an evaluation structure.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    */
+   void crfsuite_evaluation_finish(crfsuite_evaluation_t *eval);
+
+   /**
+    * Reset an evaluation structure.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    */
+   void crfsuite_evaluation_clear(crfsuite_evaluation_t *eval);
+
+   /**
+    * Accmulate the correctness of the predicted label sequence.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    *  @param  reference   The reference label sequence.
+    *  @param  prediction  The predicted label sequence.
+    *  @param  T           The length of the label sequence.
+    *  @return int         \c 0 if succeeded, \c 1 otherwise.
+    */
+   int crfsuite_evaluation_accmulate(crfsuite_evaluation_t *eval, const int *reference, const int *prediction, int T);
+
+   /**
+    * Finalize the evaluation result.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    */
+   void crfsuite_evaluation_finalize(crfsuite_evaluation_t *eval);
+
+   /**
+    * Print the evaluation result.
+    *  @param  eval        The pointer to crfsuite_evaluation_t.
+    *  @param  labels      The pointer to the label dictionary.
+    *  @param  cbm         The callback function to receive the evaluation result.
+    *  @param  user        The pointer to the user data that is forwarded to the
+    *                      callback function.
+    */
+   void crfsuite_evaluation_output(crfsuite_evaluation_t *eval, crfsuite_dictionary_t *labels, crfsuite_logging_callback cbm, void *user);
+
+   /**@}*/
+
+   /**
+    * \addtogroup crfsuite_misc Miscellaneous definitions and functions
+    * @{
+    */
+
+   /**
+    * Increments the value of the integer variable as an atomic operation.
+    *  @param  count       The pointer to the integer variable.
+    *  @return             The value after this increment.
+    */
+   int crfsuite_interlocked_increment(int *count);
+
+   /**
+    * Decrements the value of the integer variable as an atomic operation.
+    *  @param  count       The pointer to the integer variable.
+    *  @return             The value after this decrement.
+    */
+   int crfsuite_interlocked_decrement(int *count);
+
+   /**@}*/
+
+   /**@}*/
+
+   /**
+@mainpage CRFsuite: a fast implementation of Conditional Random Fields (CRFs)
+
+@section intro Introduction
+
+This document describes information for using
+<a href="http://www.chokkan.org/software/crfsuite">CRFsuite</a> from external
+programs. CRFsuite provides two APIs:
+- @link crfsuite_api C API @endlink: low-level and complete interface, which
+ is used by the official frontend program.
+- @link crfsuite_hpp_api C++/SWIG API @endlink: high-level and easy-to-use
+ interface for a number of programming languages (e.g, C++ and Python),
+ which is a wrapper for the C API.
+
+*/
+
+#ifdef __cplusplus
+}
+#endif /*__cplusplus*/
+
+#endif /*__CRFSUITE_H__*/