/*
 * Copyright (c) 2001 by Cliff Green. All rights reserved. Individual files
 * may be covered by other copyrights (as noted in the file itself).
 *
 * Redistribution and use in source and binary forms are permitted
 * provided that this entire copyright notice is duplicated in all such
 * copies.
 *
 * This software is provided "as is" and without any expressed or implied
 * warranties, including, without limitation, the implied warranties of
 * merchantibility and fitness for any particular purpose.
*/
/*
//----------------------------------------------------------------------
// Source file:   strutils.h
// Written by:    Cliff Green, 1997-2001
// Compiler:      Metrowerks CodeWarrior Pro 6
// History:
//   Modified:    5/15/2001
//   By:          Cliff Green
//   Comments:    Updated documentation, copyright notices, etc.
//   Modified:    6/12/2001
//   By:          Cliff Green
//   Comments:    Added header file include, minor typo fixes.
//   Modified:    8/15/2001
//   By:          Cliff Green
//   Comments:    Added fromStr template function.
//----------------------------------------------------------------------
// This commentheader supports documentation tools such as Doc++ and
// Doxygen: http://www.doxygen.org/
//----------------------------------------------------------------------
*/
/**
 *  This module contains both C and C++ string utility functions. This can
 *  safely be compiled with both C and C++ compilers.
 *
 *  Note that this file contains the 'extern "C"' wrapper for the C
 *  functions as opposed to the way the Soundex C function is handled (to
 *  illustrate a couple of approaches). This allows the header file to be
 *  included in either C or C++ applications.
 *
 *  The C++ utilities include the following (many use the C library ctype.h
 *  tolower functionality). Some of these functions are not quite
 *  "politically correct" and are not as flexible since they do not consider
 *  non-Ascii / foreign language character sets (which is why there's not a
 *  built-in 'tolower' in the std::string class). To provide more flexibility
 *  and "political correctness", there are some utility functors and
 *  algorithms provided for case-insensitive string comparisons (extending
 *  the STL portion of the C++ std lib):
 *
 *    toLower:       takes std::string, returns lowercased std::string
 *    toLowerAlpha:  same as toLower, leaves out non-alpha chars
 *    CompareNoCase: utility functor, ignores case
 *    compareNoCase: takes two std::strings, compares using CompareNoCase
 *    compareNoCaseAlpha: compares two std::strings, ignores non-alpha and case
 *    toStr:         given templatized val, return string representation (requires
 *                   templatized type to have operator<< overloaded)
 *    fromStr:       given a string, returns value of templatized type (requires
 *                   templatized type to have operator>> overloaded)
 *
 *  Pre-conditions and post-conditions should be obvious from function usage - empty
 *  strings are acceptable for case conversion (an empty string is returned), and
 *  empty strings are acceptable for case-insenstive comparisons (true is returned).
 *  The toStr and fromStr functions require appropriate operator overloading, as noted.
 *
 */

#ifndef STRUTILS_H
#define STRUTILS_H

#include <ctype.h>

#ifdef __cplusplus

// #include <cctype> // VC++ 5 / 6 doesn't handle properly
#include <string>
#include <sstream>    // stringstream
#include <functional> // binary_function

namespace Util {

   const std::string toLower (const std::string&);
   const std::string toLowerAlpha (const std::string&);

   struct CompareNoCase : public std::binary_function<char, char, bool> {
      bool operator() (char x, char y) const {
         return tolower(x) == tolower(y);
      }
   };
   bool compareNoCase (const std::string&, const std::string&);
   bool compareNoCaseAlpha (const std::string&, const std::string&);

   template <typename T>
      const std::string toStr (const T& val) {
         std::ostringstream os;
         os << val;
         return os.str();
      }
   template <typename T>
      const T fromStr (const std::string& s) {
         std::istringstream is(s);
         T val;
         is >> val;
         return val;
      }

}

extern "C" {

#endif

/* function prototypes for alpha string utilities */
int strlen_alpha (const char*);
char* strcpy_alpha (char*, const char*);

#ifdef __cplusplus
}
#endif

#endif /* end of header file */