cde/lib/DtSvc/DtUtil2/Utility.h

   1 /*
   2  * CDE - Common Desktop Environment
   3  *
   4  * Copyright (c) 1993-2012, The Open Group. All rights reserved.
   5  *
   6  * These libraries and programs are free software; you can
   7  * redistribute them and/or modify them under the terms of the GNU
   8  * Lesser General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  * These libraries and programs are distributed in the hope that
  13  * they will be useful, but WITHOUT ANY WARRANTY; without even the
  14  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE. See the GNU Lesser General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with these libraries and programs; if not, write
  20  * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  21  * Floor, Boston, MA 02110-1301 USA
  22  */
  23 /*
  24  * File:         Utility.h $XConsortium: Utility.h /main/4 1995/10/26 15:31:55 rswiston $
  25  * Language:     C
  26  *
  27  * (c) Copyright 1988, Hewlett-Packard Company, all rights reserved.
  28  *
  29  * (c) Copyright 1993, 1994 Hewlett-Packard Company                     *
  30  * (c) Copyright 1993, 1994 International Business Machines Corp.       *
  31  * (c) Copyright 1993, 1994 Sun Microsystems, Inc.                      *
  32  * (c) Copyright 1993, 1994 Novell, Inc.                                *
  33  */
  34
  35 #ifndef _Dt_Utility_h
  36 #define _Dt_Utility_h
  37
  38 /******************************************************************************
  39  *
  40  * _DtVectorizeInPlace() takes a string which is made up a group of
  41  * components, separated by a common separator character, and breaks
  42  * the string up into the separate components.  To reduce the amount of
  43  * memory used (and to reduce memory fragmentation), the string is simply
  44  * searched for each occurrence of the separator, and the separator is then
  45  * replaced by a NULL character.  Pointers to the individual components are
  46  * returned as a NULL-terminated array of pointers.
  47  *
  48  * The passed-in string should be malloc'ed space, since the string will
  49  * eventually be freed when the application frees the returned array.  If
  50  * you don't want the original string modified, then a copy should be made,
  51  * before calling this function.
  52  *
  53  * The application is responsible for freeing up this memory, and should do
  54  * so by calling _DtFreeStringVector().
  55  *
  56  * Parameters:
  57  *
  58  *      string           A NULL-terminated string, which is to be vectorized.
  59  *
  60  *      separator        The character which separates the components within
  61  *                       the string.
  62  *
  63  *****************************************************************************/
  64 extern char **  _DtVectorizeInPlace( char * string,
  65                                      char separator );
  66
  67 /******************************************************************************
  68  *
  69  * _DtFreeStringVector will free up the vectorized string array returned by
  70  * a call to _DtVectorizeInPlace().  Both the array used to return the
  71  * vectorized strings, and the original string itself will be freed up.
  72  *
  73  * Parameters:
  74  *
  75  *    stringVector   The array to be freed; originally obtained by a call
  76  *                   to _DtVectorizeInPlace().
  77  *
  78  *****************************************************************************/
  79 extern void     _DtFreeStringVector( char ** stringVector );
  80
  81
  82 /*****************************************************************************
  83  * DtCmd String Utility routines.
  84  *
  85  *****************************************************************************
  86  *
  87  * _DtCmdStringToArrayOfStrings - takes a string and an array of pointers
  88  *   to strings and breaks the string into whitespace separated words.
  89  *
  90  *   A "word" is a sequence of characters that has no whitespace with
  91  *   the following exception:
  92  *
  93  *     -  A word may contain contain whitespace if it is delimited
  94  *        by a pair of matching single or double qotes.
  95  *
  96  *   "Whitespace" is a tab or blank character.
  97  *
  98  *
  99  * NOTES:
 100  *
 101  *   -  The space for the "words" is malloc'd and must be free'd by
 102  *   the caller.
 103  *   -  _DtCmdFreeStringVector() should be used to free up string vectors
 104  *   created by _DtCmdStringToArrayOfStrings().
 105  *
 106  *   -  "theArray" is NULL terminated.
 107  *
 108  * PARAMETERS:
 109  *
 110  *   char theString[];          - The string to parse.
 111  *
 112  *   char *theArray[];          - MODIFIED: gets filled with pointers to
 113  *                                the words that are parsed.
 114  *
 115  *****************************************************************************/
 116
 117
 118 /******************************************************************************
 119  *
 120  * _DtCmdFreeStringVector - takes an array of pointers to strings and
 121  *   frees the malloc'd space for the strings.
 122  *
 123  *   This does NOT free the string vector itself; It assumes that
 124  *   stringv is a static i.e. char *stringv[N].
 125  *
 126  * PARAMETERS:
 127  *
 128  *   char **stringv;    - MODIFIED:  Each string in the array is freed.
 129  *
 130  *****************************************************************************/
 131
 132 extern void _DtCmdStringToArrayOfStrings(
 133                         char theString[],
 134                         char *theArray[]) ;
 135 extern void _DtCmdFreeStringVector(
 136                         char **stringv) ;
 137
 138 #endif /* _Dt_Utility_h */
 139
 140 /* DON'T ADD ANYTHING AFTER THIS #endif */