include/sphinxbase/strfuncs.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 1995-2004 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37 /**
  38  * @file strfuncs.h
  39  * @brief Miscellaneous useful string functions
  40  */
  41
  42 #ifndef __SB_STRFUNCS_H__
  43 #define __SB_STRFUNCS_H__
  44
  45 #include <stdarg.h>
  46
  47 /* Win32/WinCE DLL gunk */
  48 #include <sphinxbase/sphinxbase_export.h>
  49 #include <sphinxbase/prim_type.h>
  50
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55 #if 0
  56 /* Fool Emacs. */
  57 }
  58 #endif
  59
  60 /**
  61  * Concatenate a NULL-terminated argument list of strings, returning a
  62  * newly allocated string.
  63  **/
  64 SPHINXBASE_EXPORT
  65 char *string_join(const char *base, ...);
  66
  67 /**
  68  * Which end of a string to operate on for string_trim().
  69  */
  70 enum string_edge_e {
  71     STRING_START,       /**< Beginning of string. */
  72     STRING_END,         /**< End of string. */
  73     STRING_BOTH         /**< Both ends of string. */
  74 };
  75
  76 /**
  77  * Remove whitespace from a string, modifying it in-place.
  78  *
  79  * @param string string to trim, contents will be modified.
  80  * @param which one of STRING_START, STRING_END, or STRING_BOTH.
  81  */
  82 SPHINXBASE_EXPORT
  83 char *string_trim(char *string, enum string_edge_e which);
  84
  85 /**
  86  * Locale independent version of atof().
  87  *
  88  * This function behaves like atof() in the "C" locale.  Switching
  89  * locale in a threaded program is extremely uncool, therefore we need
  90  * this since we pass floats as strings in 1000 different places.
  91  */
  92 SPHINXBASE_EXPORT
  93 double atof_c(char const *str);
  94
  95 SPHINXBASE_EXPORT
  96 uint32 utf8_decode(uint32 *state, uint32 *codep, uint32 *byte);
  97
  98 /* FIXME: Both of these string splitting functions basically suck.  I
  99  have attempted to fix them as best I can.  (dhuggins@cs, 20070808) */
 100
 101 /**
 102  * Convert a line to an array of "words", based on whitespace separators.  A word
 103  * is a string with no whitespace chars in it.
 104  * Note that the string line is modified as a result: NULL chars are placed after
 105  * every word in the line.
 106  * Return value: No. of words found; -1 if no. of words in line exceeds n_wptr.
 107  */
 108 SPHINXBASE_EXPORT
 109 int32 str2words (char *line,    /**< In/Out: line to be parsed.  This
 110                                    string will be modified! (NUL
 111                                    characters inserted at word
 112                                    boundaries) */
 113                  char **wptr,   /**< In/Out: Array of pointers to
 114                                    words found in line.  The array
 115                                    must be allocated by the caller.
 116                                    It may be NULL in which case the
 117                                    number of words will be counted.
 118                                    This allows you to allcate it to
 119                                    the proper size, e.g.:
 120
 121                                    n = str2words(line, NULL, 0);
 122                                    wptr = ckd_calloc(n, sizeof(*wptr));
 123                                    str2words(line, wptr, n);
 124                                 */
 125                  int32 n_wptr   /**< In: Size of wptr array, ignored
 126                                    if wptr == NULL */
 127         );
 128
 129 /**
 130  * Yet another attempt at a clean "next-word-in-string" function.  See arguments below.
 131  * @return Length of word returned, or -1 if nothing found.
 132  * This allows you to scan through a line:
 133  *
 134  * <pre>
 135  * while ((n = nextword(line, delim, &word, &delimfound)) >= 0) {
 136  *     ... do something with word ..
 137  *     word[n] = delimfound;
 138  *     line = word + n;
 139  * }
 140  * </pre>
 141  */
 142 SPHINXBASE_EXPORT
 143 int32 nextword (char *line, /**< Input: String being searched for next word.
 144                                Will be modified by this function (NUL characters inserted) */
 145                 const char *delim, /**< Input: A word, if found, must be delimited at either
 146                                  end by a character from this string (or at the end
 147                                  by the NULL char) */
 148                 char **word,/**< Output: *word = ptr within line to beginning of first
 149                                  word, if found.  Delimiter at the end of word replaced
 150                                  with the NULL char. */
 151                 char *delimfound /**< Output: *delimfound = original delimiter found at the end
 152                                     of the word.  (This way, the caller can restore the
 153                                     delimiter, preserving the original string.) */
 154         );
 155
 156 #ifdef __cplusplus
 157 }
 158 #endif
 159
 160
 161 #endif /* __SB_STRFUNCS_H__ */