strings/string_utilities.hpp

    1: #ifndef STLPLUS_STRING_UTILITIES
    2: #define STLPLUS_STRING_UTILITIES
    3: ////////////////////////////////////////////////////////////////////////////////
    4: 
    5: //   Author:    Andy Rushton
    6: //   Copyright: (c) Andy Rushton, 2007
    7: //   License:   BSD License, see ../docs/license.html
    8: 
    9: //   Utilities for manipulating std::strings
   10: 
   11: ////////////////////////////////////////////////////////////////////////////////
   12: #include "strings_fixes.hpp"
   13: #include "format_types.hpp"
   14: #include <vector>
   15: #include <string>
   16: #include <stdexcept>
   17: #include <time.h>
   18: 
   19: namespace stlplus
   20: {
   21: 
   22:   ////////////////////////////////////////////////////////////////////////////////
   23:   // Padding function allows a string to be printed in a fixed-width field
   24:   ////////////////////////////////////////////////////////////////////////////////
   25: 
   26:   // The definitions for the alignment are declared in format_types.hpp
   27:   // Any other value will cause std::invalid_argument to be thrown
   28: 
   29:   std::string pad(const std::string& str,
   30:                   alignment_t alignment,
   31:                   unsigned width,
   32:                   char padch = ' ')
   33:     throw(std::invalid_argument);
   34: 
   35:   ////////////////////////////////////////////////////////////////////////////////
   36:   // whitespace trimming
   37:   ////////////////////////////////////////////////////////////////////////////////
   38: 
   39:   std::string trim_left(const std::string& val);
   40:   std::string trim_right(const std::string& val);
   41:   std::string trim(const std::string& val);
   42: 
   43:   ////////////////////////////////////////////////////////////////////////////////
   44:   // case conversion for std::strings
   45:   ////////////////////////////////////////////////////////////////////////////////
   46: 
   47:   std::string lowercase(const std::string& val);
   48:   std::string uppercase(const std::string& val);
   49: 
   50:   ////////////////////////////////////////////////////////////////////////////////
   51:   // character translation - inspired by Unix 'tr' command
   52:   ////////////////////////////////////////////////////////////////////////////////
   53: 
   54:   // convert characters represented in from_set to the characters in the same position in to_set
   55:   // for example:
   56:   //   filename = translate(filename,"abcdefghijklmnopqrstuvwxyz","ABCDEFGHIJKLMNOPQRSTUVWXYZ");
   57:   // converts the filename to uppercase and returns the result (Note that the
   58:   // uppercase function does this more easily). If the from_set is longer than
   59:   // the to_set, then the overlap represents characters to delete (i.e. they map
   60:   // to nothing)
   61: 
   62:   std::string translate(const std::string& input,
   63:                         const std::string& from_set,
   64:                         const std::string& to_set = std::string());
   65: 
   66:   ////////////////////////////////////////////////////////////////////////////////
   67:   // wildcard matching
   68:   ////////////////////////////////////////////////////////////////////////////////
   69: 
   70:   // this function does wildcard matching of the wildcard expression against the candidate std::string
   71:   // wildcards are NOT regular expressions
   72:   // the wildcard characters are * and ? where * matches 1 or more characters and ? matches only one
   73:   // there are also character sets [a-z] [qwertyuiop] etc. which match 1 character
   74:   // TODO: character sets like [:alpha:]
   75:   // TODO eventually: regular expression matching and substitution (3rd party library?)
   76: 
   77:   bool match_wildcard(const std::string& wild,
   78:                       const std::string& match);
   79: 
   80:   ////////////////////////////////////////////////////////////////////////////////
   81:   // Perl-inspired split/join functions
   82:   ////////////////////////////////////////////////////////////////////////////////
   83: 
   84:   // splits the string at every occurance of splitter and adds it as a separate string to the return value
   85:   // the splitter is removed
   86:   // a string with no splitter in it will give a single-value vector
   87:   // an empty string gives an empty vector
   88: 
   89:   std::vector<std::string> split (const std::string& str,
   90:                                   const std::string& splitter = "\n");
   91: 
   92:   // the reverse of the above
   93:   // joins the string vector to create a single string with the joiner inserted between the joins
   94:   // Note: the joiner will not be added at the beginning or the end
   95:   // However, there are optional fields to add such prefix and suffix strings
   96: 
   97:   std::string join (const std::vector<std::string>&,
   98:                     const std::string& joiner = "\n",
   99:                     const std::string& prefix = "",
  100:                     const std::string& suffix = "");
  101: 
  102:   ////////////////////////////////////////////////////////////////////////////////
  103:   // special displays
  104:   ////////////////////////////////////////////////////////////////////////////////
  105: 
  106:   // display the parameter as a number in bytes, kbytes, Mbytes, Gbytes depending on range
  107: 
  108:   std::string display_bytes(long bytes);
  109: 
  110:   // display the parameter in seconds as a string representation in weeks, days, hours, minutes, seconds
  111:   // e.g. "1d 1:01:01" means 1 day, 1 hour, 1 minute and 1 second
  112: 
  113:   std::string display_time(time_t seconds);
  114: 
  115:   ////////////////////////////////////////////////////////////////////////////////
  116: 
  117: } // end namespace stlplus
  118: 
  119: #endif