Dogcows Code - chaz/yoink/blob - src/stlplus/strings/string_utilities.hpp

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