simgear/misc/strutils.hxx

   1 /**
   2  * \file strutils.hxx
   3  * String utilities.
   4  */
   5
   6 // Written by Bernie Bright, started 1998
   7 //
   8 // Copyright (C) 1998  Bernie Bright - bbright@bigpond.net.au
   9 //
  10 // This library is free software; you can redistribute it and/or
  11 // modify it under the terms of the GNU Library General Public
  12 // License as published by the Free Software Foundation; either
  13 // version 2 of the License, or (at your option) any later version.
  14 //
  15 // This library is distributed in the hope that it will be useful,
  16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 // Library General Public License for more details.
  19 //
  20 // You should have received a copy of the GNU General Public License
  21 // along with this program; if not, write to the Free Software
  22 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  23 //
  24 // $Id$
  25
  26
  27 #ifndef STRUTILS_H
  28 #define STRUTILS_H
  29
  30 #include <simgear/compiler.h>
  31
  32 #include <string>
  33 #include <vector>
  34 #include <cstdlib>
  35
  36 typedef std::vector < std::string > string_list;
  37
  38 namespace simgear {
  39   namespace strutils {
  40
  41 //      /**
  42 //       * atof() wrapper for "string" type
  43 //       */
  44 //      inline double
  45 //      atof( const string& str )
  46 //      {
  47 //          return ::atof( str.c_str() );
  48 //      }
  49
  50 //      /**
  51 //       * atoi() wrapper for "string" type
  52 //       */
  53 //      inline int
  54 //      atoi( const string& str )
  55 //      {
  56 //          return ::atoi( str.c_str() );
  57 //      }
  58
  59         /**
  60          * Strip leading and/or trailing whitespace from s.
  61          * @param s String to strip.
  62          * @return The stripped string.
  63          */
  64         std::string lstrip( const std::string& s );
  65         std::string rstrip( const std::string& s );
  66         std::string strip( const std::string& s );
  67
  68         /**
  69          * Right-padding of a string to a given length
  70          * @param s String to pad
  71          * @param length The total length of the resulting string
  72          * @param c The character to pad with
  73          * @return The padded string
  74          */
  75         std::string rpad( const std::string & s, size_t length, char c );
  76
  77         /**
  78          * Left-padding of a string to a given length
  79          * @param s String to pad
  80          * @param length The total length of the resulting string
  81          * @param c The character to pad with
  82          * @return The padded string
  83          */
  84         std::string lpad( const std::string & s, size_t length, char c );
  85
  86         /**
  87          * Split a string into a words using 'sep' as the delimiter string.
  88          * Produces a result similar to the perl and python functions of the
  89          * same name.
  90          *
  91          * @param s The string to split into words,
  92          * @param sep Word delimiters.  If not specified then any whitespace is a separator,
  93          * @param maxsplit If given, splits at no more than maxsplit places,
  94          * resulting in at most maxsplit+1 words.
  95          * @return Array of words.
  96          */
  97         string_list
  98         split( const std::string& s,
  99                const char* sep = 0,
 100                int maxsplit = 0 );
 101
 102        /**
 103         * create a single string by joining the elements of a list with
 104         * another string.
 105         */
 106        std::string join(const string_list& l, const std::string& joinWith = "");
 107
 108         /**
 109          * Test if a string starts with a string
 110          *
 111          * @param s The string to be tested
 112          * @param substr The string to test
 113          * @return True, if s starts with substr, False otherwise
 114          */
 115         bool starts_with( const std::string & s, const std::string & substr );
 116
 117         /**
 118          * Test if a string ends with a string
 119          *
 120          * @param s The string to be tested
 121          * @param substr The string to test
 122          * @return True, if s ends with substr, False otherwise
 123          */
 124         bool ends_with( const std::string & s, const std::string & substr );
 125
 126     /**
 127      * Strip all leading/trailing whitespace, and transform all interal
 128      * whitespace into a single ' ' character - i.e newlines/carriage returns/
 129      * tabs/multiple spaces will be condensed.
 130      */
 131     std::string simplify(const std::string& s);
 132
 133     /**
 134      * convert a string representing a decimal number, to an int
 135      */
 136     int to_int(const std::string& s, int base = 10);
 137
 138     /**
 139      * Like strcmp(), but for dotted versions strings NN.NN.NN
 140      * any number of terms are supported.
 141      * @return 0 if versions match, -ve number if v1 is lower, +ve if v1
 142      * is greater
 143      */
 144     int compare_versions(const std::string& v1, const std::string& v2);
 145
 146     /**
 147      * Convert a string to upper case.
 148      * @return upper case string
 149      */
 150     std::string uppercase(const std::string &s);
 151
 152         /**
 153      * convert a string in the local Windows 8-bit encoding to UTF-8
 154      * (no-op on other platforms)
 155      */
 156     std::string convertWindowsLocal8BitToUtf8(const std::string& a);
 157
 158     /**
 159      * convert base-64 encoded data to raw bytes (possibly with embedded
 160      * NULs). Throws an exception if input data is not base64, or is
 161      * malformed
 162      */
 163       void decodeBase64(const std::string& a, std::vector<unsigned char>& output);
 164
 165     /**
 166      * convert bytes to hexadecimal equivalent
 167      */
 168     std::string encodeHex(const std::string& bytes);
 169
 170     std::string encodeHex(const unsigned char* rawBytes, unsigned int length);
 171
 172     /**
 173      * Unescape string.
 174      *
 175      * @param str String possibly containing escaped characters.
 176      * @return string with escaped characters replaced by single character
 177      *         values.
 178      */
 179     std::string unescape(const char* str);
 180
 181     inline std::string unescape(const std::string& str)
 182     { return unescape(str.c_str()); }
 183
 184       /**
 185        * Check a printf-style format string for dangerous (buffer-overflowing,
 186        * memory re-writing) format tokens. If a problematic token is
 187        * found, logs an error (SG_WARN) and returns an empty format string.
 188        */
 189       std::string sanitizePrintfFormat(const std::string& input);
 190
 191   } // end namespace strutils
 192 } // end namespace simgear
 193
 194 #endif // STRUTILS_H
 195