psString.h

Go to the documentation of this file.

/** @file  psString.h
 *
 * -*- mode: C; c-basic-indent: 4; tab-width: 8; indent-tabs-mode: nil -*-
 * vim: set cindent ts=8 sw=4 expandtab:
 *
 *  @brief Contains the declarations of string utility functions
 *
 *  @ingroup SysUtils
 *
 *  String utility functions defined shall provide basic string copying
 *  capabilities.
 *
 *  @author Eric Van Alst, MHPCC
 *  @author David Robbins, MHPCC
 *
 *  @version $Revision: 1.24 $ $Name: rel12 $
 *  @date $Date: 2006/06/27 20:33:22 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_STRING_H
#define PS_STRING_H

#include <sys/types.h>
#include "psType.h"
#include "psList.h"

/** This macro will convert the argument to a quoted string */
#define PS_STRING(S)  #S

/** This macro returns a (static buffer containing) "file:line" */
const char *p_psFileLine(const char *file, int line);
#define PS_FILE_LINE p_psFileLine(__FILE__,__LINE__)

// Doxygen group tags

/** @addtogroup SysUtils
 *  @{
 */

/** Copies the input string
 *
 *  This function shall allocate memory to the length of the input string plus
 *  one and copy the input string to the newly allocated memory.  If 'string'
 *  is 'NULL' then 'NULL' is returned.
 *
 *  @return psString:      Copy of input string
 */
psString psStringCopy(
    const char *string                 ///< Input string of characters to copy
);

/** Copies the input string up to the specified number of characters
 *
 *  This function shall allocate memory to the length specified by nChar
 *  plus one and copy the input string to the newly allocated memory.
 *  This function will only copy nChar bytes from the input to new string,
 *  so if the input string is larger than nChar characters the copied
 *  string will be a substring of the input string.  If the input string
 *  is smaller than nChar bytes then the remaining bytes allocated will
 *  be set to NULL.  If 'string' is 'NULL' then 'NULL' is returned.
 *
 *  @return  psString:   Copy of input string
 */
psString psStringNCopy(
    const char *string,                ///< Input string of characters to copy
    unsigned int nChar                 ///< Number of bytes to allocate for string copy
);

/** Appends a format onto a string
 *
 * This function shall allocate a new string if dest is NULL.  dest shall be
 * automatically extended to the size of the new string.
 *
 * @return ssize_t:     The length of the new string (excluding '\0')
 */
ssize_t psStringAppend(
    char **dest,                        ///< existing string
    const char *format,                 ///< format to append
    ...                                 ///< format arguments
);

/** Prepends a format onto a string
 *
 * This function shall allocate a new string if dest is NULL.  dest shall be
 * automatically extended to the size of the new string.
 *
 * @return ssize_t:     The length of the new string (excluding '\0')
 */
ssize_t psStringPrepend(
    char **dest,                        ///< existing string
    const char *format,                 ///< format to append
    ...                                 ///< format arguments
);

/** Procedure to split the input string into a psList of psStrings.
 *
 *  The string is split at any one of the characters in splitters.  Split
 *  strings of zero length should not be included in the output list.
 *
 *  @return psList*:    The list of (split) psStrings.
 */
psList *psStringSplit(
    const char *string,                ///< String to split
    const char *splitters,             ///< Characters on which to split
    bool multipleAreSignificant        ///< Are multiple occurences significant?
);

/** Procedure to split the input string into a psArray of psStrings.
 *
 *  The string is split at any one of the characters in splitters.  Split
 *  strings of zero length should not be included in the output list.
 *
 *  @return psArray*:       The array of (split) psStrings.
 */
psArray *psStringSplitArray(
    const char *string,                ///< String to split
    const char *splitters,             ///< Characters on which to split
    bool multipleAreSignificant        ///< Are multiple occurences significant?
);

// Given the input string, search for all copies of the key, and replace with the replacement value
// the input string may be freed if not needed
/** Procedure to search an input string and substitute strings where desired.
 *
 *  The input string is searched for all instances of the key, which is then replaced with
 *  the replacement value wherever found.  The input string may be freed if not needed.
 *
 *  @return char*:      the modified input string.
 */
char *psStringSubstitute (
    char *input,                       ///< input string to be modified
    const char *replace,               ///< replacement value
    const char *key                    ///< string to be replaced in input
);

// strip whitespace from head and tail of string
/** Procedure to strip the whitespace from the head and tail of a string.
 *
 *  @return size_t:         Number of whitespaces removed.
 */
size_t psStringStrip(
    char *string                       ///< input string to be stripped.
);


/** @} */// Doxygen - End of SystemGroup Functions

#endif // #ifndef PS_STRING_H

---