StdStringUtils.h

Go to the documentation of this file.
00001 /**
00002 \file     StdStringUtils.h
00003 \brief    Additional functions for std::string.
00004 
00005 Useful string functions and emulating some function calls 
00006 used by MFC CString. 
00007 
00008 [1]. Microsoft CString MSDN page
00009 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vcmfc98/html/_mfc_cstring_class_members.asp    
00010 
00011 \author   Glenn D. MacGougan (GDM)
00012 \since    2006-12-20
00013 \date     2007-01-09
00014 
00015 \b "LICENSE INFORMATION" \n
00016 Copyright (c) 2007, refer to 'author' doxygen tags \n
00017 All rights reserved. \n
00018 
00019 Redistribution and use in source and binary forms, with or without
00020 modification, are permitted provided the following conditions are met: \n
00021 
00022 - Redistributions of source code must retain the above copyright
00023   notice, this list of conditions and the following disclaimer. \n
00024 - Redistributions in binary form must reproduce the above copyright
00025   notice, this list of conditions and the following disclaimer in the
00026   documentation and/or other materials provided with the distribution. \n
00027 - The name(s) of the contributor(s) may not be used to endorse or promote 
00028   products derived from this software without specific prior written 
00029   permission. \n
00030 
00031 THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS 
00032 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
00033 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00034 DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
00035 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00036 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
00037 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
00038 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
00039 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
00040 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
00041 SUCH DAMAGE.
00042 */
00043 
00044 #ifndef _STDSTRINGUTILES_H_ 
00045 #define _STDSTRINGUTILES_H_ 
00046 
00047 #include <string>
00048 
00049 namespace StdStringUtils
00050 {
00051   /// \brief    Extract the string from the source string until one of the 
00052   ///           characters in charSet is found.
00053   ///
00054   /// \code 
00055   /// std::string str( "$test,10,20,30*44" );
00056   /// std::string dst;
00057   /// bool result;
00058   /// result = StdStringUtils::SpanExcluding( str, ",*", dst );
00059   /// ASSERT( dst == "$test" );
00060   /// \endcode
00061   ///
00062   /// \author   GDM
00063   /// \return   true if successful, false otherwise.
00064   void SpanExcluding(const std::string &src, const std::string charSet, std::string &dst);    
00065 
00066   /// \brief    Extract the string from the source string until one of the 
00067   ///           characters in charSet is found. Determine the string position of the 
00068   ///           end of the string extracted. ie. To aid in the start position of the 
00069   ///           next search.
00070   ///           
00071   ///
00072   /// \code 
00073   /// std::string str( "$test,10,20,30*44" );
00074   /// std::string dst;
00075   /// std::string::size_type p;
00076   /// bool result;
00077   /// result = StdStringUtils::SpanExcluding( str, ",*", dst, p );
00078   /// ASSERT( dst == "$test" );
00079   /// ASSERT( p == 5 );
00080   /// \endcode
00081   ///
00082   /// \author   GDM
00083   /// \return   true if successful, false otherwise.
00084   void SpanExcluding(const std::string &src, const std::string charSet, std::string &dst, std::string::size_type& pos);
00085 
00086   void SpanNotExcluding(const std::string &src, const std::string charSet, std::string &dst, std::string::size_type& pos);
00087 
00088   /// \brief    Conversion to uppercase.
00089   /// \author   GDM
00090   void MakeUpper(std::string &str);
00091 
00092   /// \brief    Conversion to lowercase
00093   /// \author   GDM
00094   void MakeLower(std::string &str);
00095 
00096   /// \brief    Remove whitespace starting from right edge.
00097   /// \author   GDM
00098   void TrimRight(std::string &str);
00099 
00100   /// \brief    Remove whitespace starting from left side.    
00101   /// \author   GDM
00102   void TrimLeft(std::string &str);
00103 
00104   /// \brief    Remove whitespace from the left and right.
00105   /// \author   GDM
00106   /// \return   A copy of the trimmed string.
00107   void TrimLeftAndRight(std::string &str);
00108 
00109   /// \brief    Get a double from the string.
00110   /// \author   GDM
00111   /// \return   true if successful, false otherwise.
00112   bool GetDouble( const std::string &src, double &dValue );
00113 
00114   /// \brief    Get a float from the string.
00115   /// \author   GDM
00116   /// \return   true if successful, false otherwise.
00117   bool GetFloat( const std::string &src, float &fValue );
00118 
00119   /// \brief    Get an int from the string.
00120   /// \author   GDM
00121   /// \return   true if successful, false otherwise.
00122   bool GetInt( const std::string &src, int &iValue );
00123 
00124   /// \brief    Get an unsigned from the string.
00125   /// \author   GDM
00126   /// \return   true if successful, false otherwise.
00127   bool GetUnsignedInt( const std::string &src, unsigned &uiValue );
00128 
00129 
00130   /// \brief    Extract a substring from a string delimited by a specific delimiter
00131   ///           using a 0-based index.
00132   ///
00133   /// e.g.
00134   /// \code
00135   /// std::string A = "$abcde,11,22,33";
00136   /// std::string B;
00137   /// ExtractField( A, 0, ',', B ); // B == "$abcde" 
00138   /// A = "$abcde 11 22 33";
00139   /// ExtractField( A, 2, 'w', B ); // B == "22" 
00140   /// \endcode
00141   ///    
00142   /// \author   GDM
00143   /// \return  true if successful, false if error.
00144   bool ExtractField( const std::string &str, const unsigned index, const char delimiter, std::string &field );
00145 
00146 
00147   /// \brief  Extract a substring from a string delimited by a specific delimiter
00148   ///         and alter the original string so that the substring and delimiter
00149   ///         are removed.
00150   /// e.g.
00151   /// \code
00152   /// std::string A = "$abcde,11,22,33";
00153   /// std::string B;
00154   /// InplaceExtractField(A, ',' B); // B == "$abcde", A == "11,22,33"
00155   /// InplaceExtractField(A, ',' B); // B == "11", A == "22,33"
00156   /// InplaceExtractField(A, ',' B); // B == "22", A == "33"
00157   /// InplaceExtractField(A, ',' B); // B == "33", A == ""
00158   /// InplaceExtractField(A, ',' B); // B == "", A == ""
00159   /// \endcode    
00160   ///
00161   /// \author   GDM
00162   /// \return  true if successful, false if error.
00163   bool ExtractFieldInplace( std::string &str, const char delimiter, std::string &field );    
00164 
00165 
00166   /// \brief    This function assumes the string is a filename like 
00167   ///           "c:\folder\data.gps". 
00168   ///           BaseName == "c:\folder\data", is the extracted string.
00169   /// \author   GDM
00170   void GetBaseName( const std::string str, std::string &BaseName );
00171 
00172   /// \brief    Assuming this string is a path. Directory is set to the 
00173   ///           folder containing the file.
00174   /// e.g. For:
00175   /// "c:\folder\subfolder\subsubfolder\data.txt", 
00176   /// "c:\folder\subfolder\subsubfolder" is extracted.
00177   /// \author   GDM
00178   void GetDirectoryOfThisStringPath( const std::string str, std::string &Directory );
00179 
00180   /// \brief    Assuming this string is a path. 
00181   ///           FileName is set (without the file path).
00182   /// e.g. For:
00183   /// "c:\folder\subfolder\subsubfolder\data.txt", 
00184   /// "data.txt" is extracted.
00185   /// \author   GDM
00186   void GetFileNameFromThisStringPath( const std::string str, std::string &FileName );
00187 
00188 } // end of namespace StdStringUtils 
00189 
00190 #endif // _STDSTRINGUTILES_H_ 
00191