root/trunk/whisperlib/common/base/strutil.h

// Copyright (c) 2009, Whispersoft s.r.l.
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Whispersoft s.r.l. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Author: Cosmin Tudorache & Catalin Popescu

//
// We have here a bunch of utilities for manipulating strings
//

#ifndef __COMMON_BASE_STRUTIL_H__
#define __COMMON_BASE_STRUTIL_H__

#include <strings.h>
#include <string.h>
#include <iostream>
#include <sstream>
#include <string>
#include <vector>
#include <set>
#include <map>
#include <algorithm>
#include <whisperlib/common/base/types.h>
#include <whisperlib/common/base/log.h>

#include <whisperlib/common/base/third-party/string_util.h>

namespace strutil {

// Test string equality.
bool StrEql(const char* str1, const char* str2);
bool StrEql(const string& str1, const string& str2);

// Test string equality. Ignore case.
bool StrIEql(const char* str1, const char* str2);
bool StrIEql(const string& str1, const string& str2);

// Tests if this string starts with the specified prefix.
bool StrPrefix(const char* str, const char* prefix);
bool StrStartsWith(const char* str, const char* prefix);
bool StrStartsWith(const string& str, const string& prefix);

// Tests if this string starts with the specified prefix - ignoring case.
bool StrCasePrefix(const char* str, const char* prefix);
bool StrIStartsWith(const char* str, const char* prefix);
bool StrIStartsWith(const string& str, const string& prefix);

// Tests if string ends with the specified sufix.
bool StrSuffix(const char* str, const char* suffix);
bool StrSuffix(const string& str, const string& suffix);
bool StrEndsWith(const char* str, const char* suffix);
bool StrEndsWith(const string& str, const string& suffix);

// Passes over the spaces (and tabs) of the given string
const char* StrFrontTrim(const char* str);
// Passes over the spaces (and tabs) of the given string
string StrFrontTrim(const string& str);

// Removes the front and back spaces (and tabs) of the given string
string StrTrim(const string& str);

// Removes the front and back characters from chars_to_trim for the
// given string str
string StrTrimChars(const string& str, const char* chars_to_trim);

// Removes all spaces from the given string
string StrTrimCompress(const string& str);

// Compares two strings w/o case
inline bool StrCaseEqual(const string& s1, const string& s2) {
  return ( s1.size() == s2.size() &&
           !strncasecmp(s1.c_str(), s2.c_str(), s1.size()) );
}

// Moves data inside buffer drom buf + shift_size to the beginning
// of the buffer and fills w/ fill_value afterwards
void ShiftLeftBuffer(void* buf,
                     size_t buf_size,
                     size_t shift_size,
                     int fill_value);

// Given an array of strings it joins them using the provided glue string
string JoinStrings(const char* pieces[], size_t size, const char* glue);

// Given an array of strings it joins them using the provided glue string
string JoinStrings(const vector<string>& pieces, const char* glue);

// Takes a string, a separator and splits the string in constituting componants
// separated by the separator (which is in none of them);
void SplitString(const string& s,
                 const string& separator,
                 vector<string>* output);

// Splits a string in two - befors and after the first occurance of the
// sepparator. If separator is not found, the first string will be the
// input string. The separator will not appear at all.
inline pair<string, string> SplitFirst(const char* s, char separator) {
  const char* slash_pos = strchr(s,  separator);
  if ( !slash_pos ) {
    return make_pair(string(s), string(""));
  }
  return make_pair(string(s, slash_pos - s), string(slash_pos + 1));
}

// Splits a string that contains a list of pairs of elements:
// <elem1_1>sep2<elem1_2>sep1<elem2_1>sep2<elem2_2>sep1...
//   ...sep1<elemN_1>sep2<elemN_2>
//
void SplitPairs(const string& s,
                const string& elements_separator,  // sep1
                const string& pair_separator,      // sep2
                vector< pair<string, string> >* output);

// Splits a string on separators outside the brackets
// e.g.
// SplitBracketedString("a(b, c, d(3)), d(), e(d(3))", ',', '(', ')')
// will generate:
// ["a(b, c, d(3))", " d()", " e(d(3))"]
// Returns false on error (misplaced brackets etc..
bool SplitBracketedString(const char* s,
                          const char separator,
                          const char open_bracket,
                          const char close_bracket,
                          vector<string>* output);
// Removes outermost brackets from a string
// parsed by SplitBracketedString
string RemoveOutermostBrackets(const string& s,
                               const char open_bracket,
                               const char close_bracket);

// Directory name processing helpers
const char* Basename(const char* filename);
string Basename(const string& filename);
string Dirname(const string& filename);
string CutExtension(const string& filename);
string Extension(const string& filename);

/// TODO(cpopescu): use eveywhere a path separator const.

// normalizes a file path (collapses ../, ./ // etc)  but leaves
// all the prefix '/'
string NormalizePath(const string& path);

// Joins to paths together, cannonically
inline string JoinPaths(const string& path1, const string& path2) {
  if ( path1.empty() ) return NormalizePath(path2);
  if ( path2.empty() ) return NormalizePath(path1);
  if ( path1 == "/" ) {
    return NormalizePath(path1 + path2);
  }
  return NormalizePath(path1 + "/" + path2);
}

// similar with NormalizePath, but collapses the prefix '/'
string NormalizeUrlPath(const string& path);


// Transforms a data buffer to a printable string (a'la od)
string PrintableDataBuffer(const void* buffer, size_t size);
// Similar to PrintableDataBuffer but returns only the HEXA printing.
string PrintableDataBufferHexa(const void* buffer, size_t size);

// Some useful functions for formatted printing in a string ..
string StringPrintf(const char* format, ...);
string StringPrintf(const char* format, va_list args);
void StringAppendf(string* s, const char* format, va_list args);


struct toupper_s {
  int operator()(int c) {
    return ::toupper(c);
  }
};
struct tolower_s {
  int operator()(int c) {
    return ::tolower(c);
  }
};

inline const string& StrToUpper(string& s) {
  transform(s.begin(), s.end(), s.begin(), toupper_s());
  return s;
}

inline const string& StrToLower(string& s) {
  transform(s.begin(), s.end(), s.begin(), tolower_s());
  return s;
}

// Small helper to get the string representation of an object
template <class T>
string StringOf(T object) {
  ostringstream os;
  os << object;
  return os.str();
}

template <typename K, typename V>
string ToString(const map<K, V>& m) {
  ostringstream oss;
  oss << "map #" << m.size() << "{";
  for ( typename map<K, V>::const_iterator it = m.begin(); it != m.end(); ) {
    const K& k = it->first;
    const V& v = it->second;
    oss << "[" << k << ", " << v << "]";
    ++it;
    if ( it != m.end() ) {
      oss << ", ";
    }
  }
  oss << "}";
  return oss.str();
}
template <typename T>
string ToString(const set<T>& v) {
  ostringstream oss;
  oss << "set #" << v.size() << "{";
  for ( typename set<T>::const_iterator it = v.begin(); it != v.end(); ) {
    const T& t = *it;
    oss << t;
    ++it;
    if ( it != v.end() ) {
      oss << ", ";
    }
  }
  oss << "}";
  return oss.str();
}
template <typename T>
string ToString(const vector<T>& v) {
  ostringstream oss;
  oss << "vector #" << v.size() << "{";
  for ( typename vector<T>::const_iterator it = v.begin(); it != v.end(); ) {
    const T& t = *it;
    oss << t;
    ++it;
    if ( it != v.end() ) {
      oss << ", ";
    }
  }
  oss << "}";
  return oss.str();
}

// Works with numeric types only: int8, uint8, int16, uint16, ...
// e.g. 0xa3 => "10100011"
template <typename T>
string ToBinary(T x) {
  char txt[(sizeof(T) + 1) * 8] = {0,};
  for ( uint32 i = 0; i < sizeof(T) * 8; i++ ) {
    if ( i % 8 == 0 && i > 0) {
      txt[i] = ' ';
      continue;
    }
    txt[i + i/8] = ((x >> (sizeof(T) * 8 - 1 - i)) & 1) == 1 ? '1' : '0';
  }
  txt[(sizeof(T) + 1) * 8 - 1] = '\0';
  return txt;
}

// return a string s such that:
//      s > prefix
//  and
//     does not exists s' such that:
//        s > s' > prefix
//
string GetNextInLexicographicOrder(const string& prefix);

// Utility for finding bounds in a map keyed by strings, givven a key prefix
template<class C>
void GetBounds(const string& prefix,
               map<string, C>* m,
               typename map<string, C>::iterator* begin,
               typename map<string, C>::iterator* end) {
  if ( prefix.empty() ) {
    *begin = m->begin();
  } else {
    *begin = m->lower_bound(prefix);
  }
  const string upper_bound = strutil::GetNextInLexicographicOrder(prefix);
  if ( upper_bound.empty() ) {
    *end = m->end();
  } else {
    *end = m->upper_bound(upper_bound);
  }
}
template<class C>
void GetBounds(const string& prefix,
               const map<string, C>& m,
               typename map<string, C>::const_iterator* begin,
               typename map<string, C>::const_iterator* end) {
  if ( prefix.empty() ) {
    *begin = m.begin();
  } else {
    *begin = m.lower_bound(prefix);
  }
  const string upper_bound = strutil::GetNextInLexicographicOrder(prefix);
  if ( upper_bound.empty() ) {
    *end = m.end();
  } else {
    *end = m.upper_bound(upper_bound);
  }
}

//  Replace characters "szCharsToEscape" in "text" with escape sequences
// marked by "escape". The escaped chars are replaced by "escape" character
// followed by their ASCII code as 2 digit text.
//
//  The escape char is replace by "escape""escape".
// e.g.
//  StrEscape("a,., b,c", '#', ",.") => "a#44#46#44 b#44c"
//  StrEscape("a,.# b,c", '#', ",.") => "a#44#46## b#44c"
string StrEscape(const char* text, char escape,
                      const char* chars_to_escape);
string StrEscape(const string& text,
                 char escape,
                 const char* chars_to_escape);
string StrNEscape(const char* text, size_t size, char escape,
                  const char* chars_to_escape);


//  The reverse of StrEscape.
string StrUnescape(const char* text, char escape);
string StrUnescape(const string& text, char escape);

// Escapes a string for JSON encoding
string JsonStrEscape(const char* text, size_t size);
inline string JsonStrEscape(const string& text) {
  return JsonStrEscape(text.c_str(), text.size());
}
string JsonStrUnescape(const char* text, size_t size);
inline string JsonStrUnescape(const string& text) {
  return JsonStrUnescape(text.c_str(), text.length());
}

// Returns true if the string is a valid identifier (a..z A..Z 0..9 and _)
// TODO(cosmin): clear this up!
//               Can it start with a digit?
inline bool IsValidIdentifier(const char* s) {
  if ( *s < '0' || (*s > '9' && *s < 'A') ||  (*s > 'Z' && *s < 'a') || *s > 'z' ) {
    return false;
  }
  ++s;
  while ( *s ) {
    if ( *s < '0' ||
         (*s > '9' && *s < 'A') ||
         (*s > 'Z' && *s < '_') ||
         (*s > '_' && *s < 'a') ||
         *s > 'z' ) {
      return false;
    }
    ++s;
  }
  return true;
}

// Replaces named variables in the given string with corresponding one
// found in the 'vars' map, much in the vein of python formatters.
//
// E.g.
// string s("We found user ${User} who wants to \${10 access ${Resource}.")
// map<string, string> m;
// m["User"] = "john";
// m["Resource"] = "disk";
// cout << strutil::StrMapFormat(s, m, "${", "}", '\\') << endl;
//
// Would result in:
// We found user john who wants to ${10 access disk.
// escape_char escapes first chars in both arg_begin and arg_end.
//
string StrMapFormat(const char* s,
                    const map<string, string>& m,
                    const char* arg_begin = "${",
                    const char* arg_end = "}",
                    char escape_char = '\\');

}

# endif  // __COMMON_BASE_STRUTIL_H__