/** @file  psString.h
 *
 *  @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
 *
 *  @version $Revision: 1.9 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2004-10-27 00:57:31 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_STRING_H
#define PS_STRING_H

#include "psType.h"

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

// 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.
 *
 *  @return char*      Copy of input string
 *
 */
char *psStringCopy(
    const char *str
    /**< 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.
 *
 *  @return  char* Copy of input string
 *
 */

/*@null@*/

char *psStringNCopy(
    const char *str,
    /**< Input string of characters to copy */

    psS32 nChar
    /**< Number of bytes to allocate for string copy */
);

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

#endif
