/*===========================================================================
 *
 * File:	DL_Str.H
 * Author:	Dave Humphrey (uesp@m0use.net)
 * Created On:	Saturday, May 05, 2001
 *
 * Contains string related definitions for Dave's Library of common code.
 *
 *=========================================================================*/
#ifndef __DL_STR_H
#define __DL_STR_H


/*===========================================================================
 *
 * Begin Required Includes
 *
 *=========================================================================*/
  #include "dl_base.h"
  #include "dl_mem.h"
  #include "dl_err.h"
  #include "dl_log.h"
  #include <string.h>
/*===========================================================================
 *		End of Required Includes
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Defines
 *
 *=========================================================================*/

	/* Convert a boolean value to a string */
  #define BooleanToString(Flag) ((Flag) ? "TRUE" : "FALSE")

	/* Shortcut to trimming whitespace from a string */
  #define trim(String) ltrim(rtrim(String))

/*===========================================================================
 *		End of Defines
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Function Prototypes
 *
 *=========================================================================*/

	/* Returns the number of substrings in the given string */
  size_t CountSubstrings (const char* pSourceString, const char* pSearchString);

	/* Is... type functions for strings */
  boolean IsStringNumber (const char* pString);
  boolean IsStringDigit  (const char* pString);
    
	/* Strip whitespace from left/right side of string */
  char* ltrim (char* pString);
  char* rtrim (char* pString);

	/* A strlen() function which can handle NULL strings */
  size_t SafeStrLen (const char* pString);

	/* Seperate a string in a variable/value pair */
  boolean SeperateVarValue (char** ppVariable, char** ppValue, char* pString, 
			    const char SeperatorChar = '=',
			    const char CommentChar   = '#');

	/* A smart string compare function which supports NULL cases and case sensitivity */
  boolean StringChanged (const char* pString1, const char* pString2, const boolean CaseSensitive = FALSE);
	
	/* Convert a string to a boolean value */
  boolean StringToBoolean (boolean& Flag, const char* pString);
  boolean StringToBoolean (const char* pString);

	/* Counts the number of lines in string, seperated by a CR */
  size_t strhgt (const char* pString);

	/* Find a substring in a string with case insensitivity */
  char* stristr (const char* pString, const char* pSubString);

	/* Compares two strings up to the length of the shortest, case insensitive */
  int strlicmp (const char *pString1, const char *pString2);

	/* Return number of characters to first CR or end of string */
  size_t strlinelen (const char* pString);

	/* Returns the maximum line length of lines seperated by CR */
  size_t strmaxlinelen (const char* pString);

	/* Copies a maximum number of character ensuring string is NULL terminated */
  char* strnncpy (char* pDestString, const char* pSourceString, const size_t MaxStringLength);

	/* Output printf() formatted message to a string buffer */
  int  snprintf (char* pBuffer, const size_t MaxLength, const char* pFormat, ...); 
  int vsnprintf (char* pBuffer, const size_t MaxLength, const char* pFormat, va_list Args); 

/*===========================================================================
 *		End of Function Prototypes
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Inline String Functions
 *
 *=========================================================================*/

	/* A strlen() function which can handle NULL strings */
inline size_t SafeStrLen (const char* pString) {
  return ((pString == NULL) ? 0 : strlen(pString));
 }

/*===========================================================================
 *		End of Inline String Functions
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Standard Replacement Function Prototypes
 *
 * These functions are only used in systems where they are not 
 * otherwise available.
 *
 *=========================================================================*/
#if !defined(__TURBOC__) && !defined(_WIN32)

	/* Standard uppercase/lowercase conversion functions */
  char* strlwr (char* pString);
  char* strupr (char* pString);
  
	/* Compare a portion of a string with case insensitivity */
  int strnicmp (const char* pString1, const char* pString2, const size_t MaxStringLength);

#endif
/*===========================================================================
 *		End of Standard Replacement Function Prototypes
 *=========================================================================*/


/*===========================================================================
 *
 * Begin Testing Routine Prototypes
 *
 * Prototypes for test functions of module.  Only available in DEBUG builds.
 *
 *=========================================================================*/
#if defined(_DEBUG)
  void Test_vsnprintf (void);
  void Test_CountSubstrings (void);
  void Test_ltrim (void);
  void Test_rtrim (void);
  void Test_strlinelen (void);
  void Test_SeperateVarValue (void);
  void Test_StringToBoolean (void);
  void Test_StringChanged (void);
  void Test_IsStringNumber (void);
  void Test_stristr (void);
  void Test_strlicmp (void);
  void Test_strnncpy (void);
  void Test_strproper (void);
  void Test_strhgt (void);
  void Test_strmaxlinelen (void);
  void Test_strupr (void);
  void Test_strnicmp (void);
  void Test_DLStr (void);
#endif
/*===========================================================================
 *		End of Testing Routine Prototypes
 *=========================================================================*/




#endif
/*===========================================================================
 *		End of File Dl_str.H
 *=========================================================================*/