dtk_string.hpp

Go to the documentation of this file.

#ifdef A93938D6857511E1B78E58294824019B
#    include "util/external/dtk_string_alt.hpp"
#else
 
#ifndef __DTK_STRING_HPP__
#define __DTK_STRING_HPP__
 
#ifdef _MSC_VER
#    pragma warning(disable:4786)
#    pragma warning(disable:4800)
#endif
 
#include "def/define.h"
#include "util/util_stl_dtk.hpp"
#include <cstdio>
#include <string>
 
 
 
#ifdef _MSC_VER
#    if (_MSC_VER > 1200)
#         define Dtk_defined__wchar_t
#    endif
#endif
class Dtk_status;
#if ( defined(Dtk_defined__wchar_t) && defined(_NATIVE_WCHAR_T_DEFINED) )
//#pragma message("_NATIVE_WCHAR_T_DEFINED")
#    define w_str _w_str_w
#else
#    define w_str _w_str_us
#endif
 
#define DTK_A Dtk_string(L"a")
#define DTK_AB Dtk_string(L"ab")
#define DTK_RB Dtk_string(L"rb")
#define DTK_RBP Dtk_string(L"rb+")
#define DTK_R Dtk_string(L"r")
#define DTK_W Dtk_string(L"w")
#define DTK_WP Dtk_string(L"w+")
#define DTK_WB Dtk_string(L"wb")
#define DTK_WBP Dtk_string(L"wb+")
#define DTK_RW Dtk_string(L"rw")
 
//! \ingroup base_types
//! \class Dtk_string
//! \brief This is a high level string class.
//!
//!    This class lets you use ASCII or UNICODE strings.
//! It also has some File fonctions
 
 
class Dtk_string
{
public:
     typedef size_t Size_t;
protected:
     //! \brief Internal representation of the string
     Dtk_WChar_t                        *    m_Str;
     //! \brief compatibility ASCII representation. WARNING this field is not always up to date.
     mutable char                  *    m_CStr;
     //! \brief size of m_Str buffer
     //This fields holds in memory the value of wcslen(m_Str). Caution : it may not be updated in case of user manipulation, if so, the Dtk_string is flagged as dirty (see isDirty()).
     //Due to the use of the last byte to hold this flag, any Dtk_string of size > 2^8 will wrongly be considered dirty
     mutable Size_t                     m_StrSize;
     //! \brief size of m_CStr buffer
     mutable Size_t                     m_CStrSize;
private:
     //! \brief Init
     void init();
     void UpdateLen() const;
protected:
     void _FillFromCharBuffer( const char* inBuffer, const Dtk_Size_t inSize = ( Dtk_Size_t )-1 );
 
public:
     //! \brief Default destructors
     ~Dtk_string();
     //! \brief Default constructor
     Dtk_string();
     //! \brief constructor from a char * (ASCII string)
     //! \param s the ASCII string to convert
     Dtk_string( const char *s );
     Dtk_string( const char* s, const Dtk_Size_t& inCount );
     //! \brief copy constructor
     //! \param s the Dtk_string to copy
 
     Dtk_string( const Dtk_string & );
 
#ifndef DTK_NO_CXX11_RVALUE_REFERENCES
     //! \brief Move constructor
     //! \param s the Dtk_string to move
     Dtk_string( Dtk_string && s ) DTK_NOEXCEPT : m_Str( s.m_Str ), m_CStr( s.m_CStr ), m_StrSize( s.m_StrSize ), m_CStrSize( s.m_CStrSize )
     {
          s.m_Str = 0;
          s.m_CStr = 0;
          s.m_StrSize = 0;
          s.m_CStrSize = 0;
     }
 
     //! \brief Move assignment operator
     //! \param s the Dtk_string to move
     Dtk_string& operator=( Dtk_string && s ) DTK_NOEXCEPT
     {
          if( this != &s )
          {
               delete[] m_Str;
               delete[] m_CStr;
               m_Str = s.m_Str;
               m_CStr = s.m_CStr;
               m_StrSize = s.m_StrSize;
               m_CStrSize = s.m_CStrSize;
 
               s.m_Str = 0;
               s.m_CStr = 0;
               s.m_StrSize = 0;
               s.m_CStrSize = 0;
          }
 
          return *this;
     }
#endif
     //Dtk_string(const int);
     //! \brief constructor from a double
     //! \param dbl_val the double value to convert
     Dtk_string( const double dbl_val );
     Dtk_string( const double dbl_val, Dtk_Int32 inWithMorePrecision );
     //! \brief constructor from a float
     //! \param float_val the float value to convert
     Dtk_string( const float float_val );
     void RawCopyFromASCII( const char * inStrToBeCopied, const Dtk_Size_t inCount = -1 );
     /*************************************/
     //! \brief Retrieve the ASCII conversion string.
     //! \return the ASCII string
     //! \warning You can't modify the returned string !!
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string res;
     //! char * tmp_char;
     //! tmp_char = res.c_str(); //you can't modify the tmp_char value
     //! \endcode
     const char * c_str() const;
 
     //! \brief Split a Dtk_string into an array of Dtk_string giving a char array
     //! \param inDelimiters the delimiters string. This string contains each characters used to split the string
     //! \param outResults the result array
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string StringToBeSplitted = L"String To Be-Splitted";
     //! Dtk_string Delimiters = L" -";
     //! Dtk_tab< Dtk_string > Result;
     //! StringToBeSplitted.Split( Delimiters, Result);
     //! //Now Result contains 4 elements
     //! //Result.at(0) is equal to L"String"
     //! //Result.at(1) is equal to L"To"
     //! //Result.at(2) is equal to L"Be"
     //! //Result.at(3) is equal to L"Splitted"
     //!
     //! \endcode
     void Split( const Dtk_string& inDelimiters, Dtk_tab<Dtk_string>& outResults ) const;
     void Split( Dtk_WChar_t * inDelimiters, Dtk_tab<Dtk_string>& outResults ) const;
 
     //! \brief Retrieve the UNICODE string
     //! \return the UNICODE string
     //! \warning You can't modify the returned string !!
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string res;
     //! wchar_t * tmp_char;
     //! tmp_char = res.w_str(); //you can't modify the tmp_char value
     //! \endcode
#if ( defined(Dtk_defined__wchar_t))
     const unsigned short * _w_str_us() const;
     const __wchar_t * _w_str_w() const;
     //! \brief constructor from a wchar_t * (UNICODE string)
     //! \param s the UNICODE string to convert
     Dtk_string( const unsigned short *s );
     //! \brief constructor from a wchar_t * (UNICODE string)
     //! \param s the UNICODE string to convert
     Dtk_string( const __wchar_t *s );
     //! \brief copy the Dtk_string in a char * (UNICODE) string
     //! \param str the buffer string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! wchar_t * tmp;
     //! s1 = L"first string";
     //! tmp = new wchar_t[s1.len() + 1];
     //! s1.get_wchar(tmp); //Now tmp is L"first string"
     //! \endcode
     //! \warning the str string must be allocated before the method call
     void get_wchar( unsigned short * str ) const;
     //! \brief copy the Dtk_string in a char * (UNICODE) string
     //! \param str the buffer string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! wchar_t * tmp;
     //! s1 = L"first string";
     //! tmp = new wchar_t[s1.len() + 1];
     //! s1.get_wchar(tmp); //Now tmp is L"first string"
     //! \endcode
     //! \warning the str string must be allocated before the method call
     void get_wchar( __wchar_t * str ) const;
 
     int cmp( const unsigned short *s2 ) const;
     int cmp( const __wchar_t *s2 ) const;
     int ncmp( const unsigned short *s2, const int count ) const;
     int ncmp( const __wchar_t *s2, const int count ) const;
     int icmp( const unsigned short *s2 ) const;
     int icmp( const __wchar_t *s2 ) const;
     int nicmp( const unsigned short *s2, const size_t size ) const;
     int nicmp( const __wchar_t *s2, const size_t size ) const;
#else
     const Dtk_WChar_t * w_str() const;
     Dtk_string( const Dtk_WChar_t *s );
     //! \brief copy the Dtk_string in a char * (UNICODE) string
     //! \param str the buffer string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! wchar_t * tmp;
     //! s1 = L"first string";
     //! tmp = new wchar_t[s1.len() + 1];
     //! s1.get_wchar(tmp); //Now tmp is L"first string"
     //! \endcode
     //! \warning the str string must be allocated before the method call
     void get_wchar( Dtk_WChar_t * str ) const;
     int cmp( const Dtk_WChar_t *s2 ) const;
     int ncmp( const Dtk_WChar_t *s2, const int count ) const;
     int icmp( const Dtk_WChar_t *s2 ) const;
     int nicmp( const Dtk_WChar_t *s2, const size_t size ) const;
#endif
 
     //! \brief affectation operator from a Dtk_string
     //! \param s the affected value
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string res("this is a sample");
     //! Dtk_string tmp;
     //! tmp = res; //Now tmp is "this is a sample"
     //! \endcode
     Dtk_string& operator = ( const Dtk_string& s );
     //! \brief affectation operator from a char (ASCII) string
     //! \param s the affected value
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp;
     //! tmp = "this is a sample"; //Now tmp is "this is a sample"
     //! \endcode
     Dtk_string& operator = ( const char* s );
 
     //! \brief affectation operator from a float
     //! \param fltval the affected value (a conversion is made)
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp;
     //! tmp = (float)1.0; //Now tmp is "1.0"
     //! \endcode
     Dtk_string& operator = ( const float fltval );
     //! \brief affectation operator from a double
     //! \param dbl_val the affected value (a conversion is made)
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp;
     //! tmp = (double)1.0; //Now tmp is "1.0"
     //! \endcode
     Dtk_string& operator = ( const double dbl_val );
 
     //! \brief access to a specified letter in the Dtk_string
     //! \param i the position of the wanted letter
     //! \return the letter
     Dtk_WChar_t& operator[] ( int );
     const Dtk_WChar_t& operator[] ( int i ) const;
 
     //! \deprecated
     //SetAsDeprecated( "2021.4", "Use clear() method instead" )
     void free_mem();
     //! \brief File Utility : retrieve the file size
     //! \return The file size if success 0 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! Dtk_Size_t size;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! size = s1.FileSize();
     //! \endcode
     Dtk_Size_t FileSize() const;
     Dtk_status ToDtkInt32( Dtk_Int32& outRes ) const;
     Dtk_status ToDtkDouble64( Dtk_Double64& outRes ) const;
 
     //! \brief Converts the Dtk_string to UTF8 string.
     //! \return The UTF8 String allocated with 'new'. Please use 'delete []' to free it.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp = L"30°"; //special ascii string.
     //! char * UTF8Str = tmp.ToUTF8String(); //UTF8Str is ''
     //! delete [] UTF8Str; UTF8Str = NULL;
     //! \endcode
     char * ToUTF8String() const;
 
     Dtk_string Substring( const Dtk_Size_t& inStartIndex, const Dtk_Size_t& inLength ) const;
     //! \brief clear string data
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp = L"one_text";
     //! tmp.clear(); //Now tmp is ""
     //! \endcode
     void clear();
 
     //! \brief affectation operator from a int
     //! \param integer the affected value (a conversion is made)
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string tmp;
     //! tmp.convert_from_int(1); //Now tmp is "1"
     //! \endcode
     void convert_from_int( const int integer, int force_unsigned_int = 0 );
     void ConvertFromUTF8String( const char * inUTF8String );
 
     /*utils functions*/
     Dtk_bool is_NULL() const;
     Dtk_bool is_not_NULL() const;
     //! \brief Retrieve the length of the Dtk_string
     //! \return the Dtk_string length
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string res;
     //! int length;
     //! length = res.len();
     //! \endcode
     int len() const;
 
 
     //! \brief copy the Dtk_string in a char * (ASCII) string
     //! \param inoutStr the buffer string. If NULL the method only processes the resulting ASCII length - for buffer allocation -
     //! \return The ASCII string length.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! char * tmp = NULL;
     //! s1 = L"first string";
     //! Dtk_Size_t Len = s1.get_char(tmp); //We process the resulting string length
     //! tmp = new char[Len + 1];
     //! s1.get_char(tmp); //Now tmp is "first string"
     //! \endcode
     //! \warning the str string must be allocated before the method call
     //! \remarks there is a conversion from UNICODE to ASCII string
     //! so some ugly characters may occur...
     //SetAsDeprecated( "2021.4", "This method is insecure. Use get_char(char * inoutStr, const Dtk_Size_t inBufferSize ) method instead" )
     Dtk_Size_t get_char( char * inoutStr ) const;
     //! \brief concat the Dtk_string with the Dtk_string given in parameter
     //! \param s2 the Dtk_string to concat
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s1 = L"first string";
     //! s2 = L"second string";
     //! s1.cat(s2); //Now s1 is L"first stringsecond string"
     //! \endcode
     //! \remarks this method is similar to operator '+'
     void cat( const Dtk_string &s2 );
 
     //! \brief Converts the Dtk_string to Upper case.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1 = L"My String";
     //! s1.ToUpper();
     //! //Now the s1 is L"MY STRING"
     //! \endcode
     void ToUpper();
 
     //! \brief Converts the Dtk_string to Lower case.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1 = L"My String";
     //! s1.ToLower();
     //! //Now the s1 is L"my string"
     //! \endcode
     void ToLower();
 
     //! \brief compare the Dtk_string with the string given in parameter
     //! \param s2 : Dtk_string to be compared with
     //! \return  > 0 if this is greater than s2, 0 if they are identical, < 0 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1.cmp(s2) != 0)
     //! {
     //! ...
     //! }
     //! \endcode
     //! \remark this method is similar to '==', '<', '>', '>=', '<=', '!=' operators
     int cmp( const Dtk_string &s2 ) const;
     //! \brief compare the count first character of the Dtk_string with the string given in parameter
     //! \param s2 : Dtk_string to be compared with
     //! \param count : the number of characters to be compared
     //! \return  > 0 if this is greater than s2, 0 if they are identical, < 0 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1.cmp(s2,3) != 0)
     //! {
     //! ...
     //! }
     //! \endcode
     int ncmp( const Dtk_string &s2, const int count ) const;
     //! \brief Perform a lowercase comparison of strings
     //! \param s2 : Dtk_string to be compared with
     //! \return  > 0 if this is greater than s2, 0 if they are identical, < 0 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1.cmp(s2,3) != 0)
     //! {
     //! ...
     //! }
     //! \endcode
     int icmp( const Dtk_string &s2 ) const;
     //! \brief Compare characters of two strings without regard to case.
     //! \param s2 : Dtk_string to be compared with
     //! \param size : the number of characters to be compared
     //! \return  > 0 if this is greater than s2, 0 if they are identical, < 0 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1.cmp(s2,3) != 0)
     //! {
     //! ...
     //! }
     //! \endcode
     int nicmp( const Dtk_string &s2, const size_t size ) const;
     //! \brief copy the Dtk_string given in parameter in the Dtk_string
     //! \param s2 the Dtk_string to be copied
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s1 = L"first string";
     //! s2 = L"second string";
     //! s1.cpy(s2); //Now s1 is L"second string"
     //! \endcode
     //! \remarks this method is similar to operator '='
     void cpy( Dtk_string s2 );
     //! \brief copy a number of characters of the Dtk_string in an other Dtk_string
     //! \param s2 the Dtk_string to be copied
     //! \param size the number of character to be copied
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s2 = L"first string";
     //! s1.ncpy(s2,4); //Now s1 is L"firs"
     //! \endcode
     void ncpy( const Dtk_string & s2, size_t size );
     //! \brief find the position of a substring into a Dtk_string
     //! \param s1 the searched substring
     //! \return the position of the first character of the substring if success -1 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! int pos;
     //! s1 = L"first string";
     //! s2 = L"str";
     //! pos = s1.find_substring(s2); //Now pos is equal to 6
     //! \endcode
     int find_substring( const Dtk_string &s1 ) const;
     //! \brief find the position of a character into a Dtk_string
     //! \param car the searched character (UNICODE or ASCII form)
     //! \return the position of the first occurrence of car if success -1 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! int pos;
     //! s1 = L"first string";
     //! pos = s1.find_first(L's'); //Now pos is equal to 3
     //! \endcode
     int find_first( int character ) const;
     //! \brief find the position of a character into a Dtk_string
     //! \param car the searched character (UNICODE or ASCII form)
     //! \return the position of the last occurrence of car if success -1 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! int pos;
     //! s1 = L"first string";
     //! pos = s1.find_last(L's'); //Now pos is equal to 6
     //! \endcode
     int find_last( int character ) const;
     //! \brief retrieve the left part of the Dtk_string from a position
     //! \param pos : start position
     //! \return the left part of the Dtk_string if success or a NULL Dtk_string else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s1 = L"first string";
     //! s2 = s1.left(3); //Now s2 is equal to L"firs"
     //! \endcode
     //! \remark the pivot character is included in the resulted Dtk_string
     Dtk_string left( int pos ) const;
     //! \brief retrieve the right part of the Dtk_string from a position
     //! \param pos : start position
     //! \return the right part of the Dtk_string if success or a NULL Dtk_string else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s1 = L"first string";
     //! s2 = s1.right(3); //Now s2 is equal to L"st string"
     //! \endcode
     //! \remark the pivot character is included in the resulted Dtk_string
     Dtk_string right( int pos ) const;
     //! \brief retrieve the left part of the Dtk_string from a position
     //! \param pos : start position
     //! \return the left part of the Dtk_string if success or a NULL Dtk_string else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! s1 = L"first string";
     //! s2 = s1.left_exclusive(3); //Now s2 is equal to L"fir"
     //! \endcode
     //! \remark the pivot character is NOT included in the resulted Dtk_string
     Dtk_string left_exclusive( int pos ) const;
     void LeftExclusive( const int& pos, Dtk_string& outRes ) const;
     //! \brief retrieve the right part of the Dtk_string from a position
      //! \param pos : start position
      //! \return the right part of the Dtk_string if success or a NULL Dtk_string else
      //!
      //! \b Sample:
      //! \code
      //! Dtk_string s1,s2;
      //! s1 = L"first string";
      //! s2 = s1.right_exclusive(3); //Now s2 is equal to L"t string"
      //! \endcode
      //! \remark the pivot character is NOT included in the resulted Dtk_string
     Dtk_string right_exclusive( int pos ) const;
     void RightExclusive( const int& pos, Dtk_string& outRes ) const;
 
     //! \brief Removes all occurrences of a given char at the beginning - leading - or the end - trailing - into the Dtk_string
     //! \param inCharToBeTrimmed the searched Dtk_WChar_t
     //! \param inTrimLeadingCharacters DTK_TRUE If you want to trim leading characters. DTK_FALSE otherwise. DTK_TRUE by default.
     //! \param inTrimTrailingCharacters DTK_TRUE If you want to trim leading characters. DTK_FALSE otherwise. DTK_TRUE by default.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L" Test Test Test ";
     //! s1.TrimCharacters( ' ', DTK_TRUE, DTK_FALSE ); //Trim only leading ' ' characters
     //! //Now the string equals L"Test Test Test "
     //! \endcode
     void TrimCharacters( const Dtk_WChar_t inCharToBeTrimmed,
                               const Dtk_bool inTrimLeadingCharacters = DTK_TRUE,
                               const Dtk_bool inTrimTrailingCharacters = DTK_TRUE );
     //! \brief Removes all occurrences of a given char at the beginning - leading - and the end - trailing - into the Dtk_string
     //! \param inCharToBeTrimmed the searched Dtk_WChar_t
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L" Test Test Test ";
     //! s1.TrimLeadingCharacters( ' ' );
     //! //Now the string equals L"Test Test Test "
     //! \endcode
     inline void TrimLeadingCharacters( const Dtk_WChar_t inCharToBeTrimmed )
     {
          TrimCharacters( inCharToBeTrimmed, DTK_TRUE, DTK_FALSE );
     }
     //! \brief Removes all occurrences of a given char at the end - trailing - into the Dtk_string
     //! \param inCharToBeTrimmed the searched Dtk_WChar_t
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L" Test Test Test ";
     //! s1.TrimTrailingCharacters( ' ' );
     //! //Now the string equals L" Test Test Test"
     //! \endcode
     inline void TrimTrailingCharacters( const Dtk_WChar_t inCharToBeTrimmed )
     {
          TrimCharacters( inCharToBeTrimmed, DTK_FALSE, DTK_TRUE );
     }
     //! \brief Removes all occurrences of a given char at the beginning - leading - and the end - trailing - into the Dtk_string
     //! \param inCharToBeTrimmed the searched Dtk_WChar_t
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L" Test Test Test ";
     //! s1.TrimLeadingAndTrailingCharacters( ' ' );
     //! //Now the string equals L"Test Test Test"
     //! \endcode
     inline void TrimLeadingAndTrailingCharacters( const Dtk_WChar_t inCharToBeTrimmed )
     {
          TrimCharacters( inCharToBeTrimmed, DTK_TRUE, DTK_TRUE );
     }
     //! \brief Counts all the occurrences of a given substring into the Dtk_string
     //! \param substring the searched substring
     //! \return the occurrences number of the substring.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! Dtk_string s2;
     //! int nb;
     //! s1 = L"first string. Second string";
     //! s2 = L"string";
     //! nb = s1.count_substring_occurrences(s2); //Now nb is equal to 2
     //! \endcode
     int count_substring_occurrences( const Dtk_string &substring ) const;
     //! \brief Counts all the occurrences of a given character into the Dtk_string
     //! \param car the searched substring
     //! \return the occurrences number of the car.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! int nb;
     //! s1 = L"occurrences";
     //! nb = s1.count_char_occurrences('c'); //Now nb is equal to 3
     //! \endcode
     int count_char_occurrences( const int car ) const;
 
     //! \brief File Utility: Splits Fullpath into drive/path/filename/extension
     //! \param[out] drive: drive buffer or NULL if not wanted...
     //! \param[out] path: path buffer or NULL if not wanted...
     //! \param[out] filename: filename buffer or NULL if not wanted...
     //! \param[out] extension: extension buffer or NULL if not wanted...
     //! \return always 1
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! Dtk_string drive,path,filename,ext;
     //!
     //! s1 = L"c:\\toto\\tata\\titi\\tutu.tete";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L"c:"
     //! //path = L"\toto\tata\titi\"
     //! //filename = L"tutu"
     //! //ext = L"tete"
     //!
     //! s1 = L"/toto/tata/titi/tutu.tete ";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L"/toto/tata/titi/"
     //! //filename = L"tutu"
     //! //ext = L"tete"
     //!
     //! s1 = L"toto/tata/titi/tutu.tete";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L"toto/tata/titi/"
     //! //filename = L"tutu"
     //! //ext = L"tete"
     //!
     //! s1 = L"../tata/titi/tutu.tete";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L"../tata/titi/"
     //! //filename = L"tutu"
     //! //ext = L"tete"
     //!
     //! s1 = L"tutu";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L""
     //! //filename = L"tutu"
     //! //ext = L""
     //!
     //! s1 = L"titi/.tutu";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L"titi/"
     //! //filename = L""
     //! //ext = L"tutu"
     //!
     //! s1 = L".tutu.tete";
     //! s1.traite_nom_fichier(&drive,&path,&filename,&ext);
     //! //drive = L""
     //! //path = L""
     //! //filename = L".tutu"
     //! //ext = L"tete"
     //!
     //! \endcode
     //SetAsDeprecated( "2024.2", "" )
     int traite_nom_fichier(
          Dtk_string * drive,
          Dtk_string * path,
          Dtk_string * filename,
          Dtk_string * extension ) const;
     //! \brief Replaces all occurrences of a character in a string with a new character.
     //! \param old_char : character to be replaced
     //! \param new_char : character to replace
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L"first string";
     //! s1.replace(L's', L't'); // Now s1 is equal to L"firtt ttring"
     //! \endcode
     int replace( const int& old_char, const int& new_char );
     //! \brief Removes all occurrences of a character in a string.
     //! \param removed_char : character to be removed
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L"first string";
     //! s1.removechar(L'r'); // Now s1 is equal to L"fist sting"
     //! \endcode
     int removechar( const int& removed_char );
 
     //! \brief File Utility : Retrieves the drive in Dtk_string form
     //! \return the drive string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.drive(); //result is L"C:"
     //! \endcode
     Dtk_string drive() const;
     //! \brief File Utility : Retrieves the path in Dtk_string form
     //! \return the path string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.path(); //result is L"\dir\dir2\"
     //! \endcode
     Dtk_string path() const;
     //! \brief File Utility : Retrieves the filename in Dtk_string form
     //! \return the filename string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.filename(); //result is L"filename"
     //! \endcode
     Dtk_string filename() const;
     //! \brief File Utility : Retrieves the extension in Dtk_string form
     //! \return the extension string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.extension(); //result is L"extension"
     //! \endcode
     Dtk_string extension() const;
     int test_extension( const Dtk_string &ext ) const;
 
     //! \brief File Utility : Retrieves the full path in Dtk_string form
     //! \return the full path string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! s1.FullPath( res ); //res == L"C:/dir/dir2/"
     //! \endcode
     //! \remark the full path '\\' are converted into '/'.
     void FullPath( Dtk_string& outFullPath ) const;
 
     //! \brief File Utility : Retrieves the filename extension in Dtk_string form
     //! \return the filename extension string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! s1.FileNameExtension( res ); //res == L"filename.extension"
     //! \endcode
     void FileNameExtension( Dtk_string& outFileNameExtension ) const;
 
     //int test_extension(const char *ext);
     //int test_extension(const wchar_t * ext);
     //! \brief File Utility : Open a file with the given rights
     //! \param droits the given rights (in ASCII, UNICODE or Dtk_string form
     //! - you can use define such as 'DTK_A' or 'DTK_WP' for example - )
     //! \return the FILE * pointer if success or NULL else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! FILE * res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.ouvrir_fichier(DTK_WP);
     //! if(res)
     //!        fclose(res); // We close the file
     //! \endcode
     FILE * ouvrir_fichier( const Dtk_string &droits ) const;
 
     //! \brief File Utility : Open a file with the given rights
     //! \param inRights the given rights (in ASCII, UNICODE or Dtk_string form
     //! - you can use define such as 'DTK_A' or 'DTK_WP' for example - )
     //! \return the FILE * pointer if success or NULL else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! FILE * res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.OpenFile(DTK_WP);
     //! if(res)
     //!        fclose(res); // We close the file
     //! \endcode
     FILE * OpenFile( const Dtk_string &inRights ) const;
 
     //! \brief File Utility : Delete a file
     //! \return 0 if success -1 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! FILE * res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.ouvrir_fichier(DTK_WP);
     //! if(res)
     //! {
     //!        fclose(res); // We close the file
     //!        s1.unlink(); // We delete the file
     //! }
     //! \endcode
     int unlink() const;
     //! \brief File Utility : Create a Directory
     //! \return 0 if success -1 else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! FILE * res;
     //! s1 = L"C:\\dir\\dir2\\";
     //! res = s1.mkdir();
     //! \endcode
     int mkdir() const;
     int rmdir() const;
     //! \brief File Utility : tests if a file exists
     //! \return true if file exists false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! Dtk_bool res;
     //! s1 = L"C:\\dir\\dir2\\filename.extension";
     //! res = s1.existe_fichier();
     //! if(res)
     //! {
     //!        s1.unlink(); // We delete the file
     //! }
     //! \endcode
     Dtk_bool existe_fichier() const;
     //! \deprecated Use FileSize() method instead
     SetAsDeprecated( "2022.3", "Use FileSize() method instead" )
          long taille_fichier() const;
 
     //! \brief File Utility : retrieve The OS Path Separator as char.
     //! \return '\\' on Windows/Cygwin, '/' otherwise.
     inline static const char PathSeparatorChar()
     {
# if defined(_WIN32) || defined(__CYGWIN__) // Windows default, including MinGW and Cygwin
          return '\\';
# else
          return '/';
# endif
     }
     //! \brief File Utility : Retrieves The OS Path Separator as Dtk_WChar_t.
     //! \return L'\\' on Windows/Cygwin, L'/' otherwise.
     inline static const Dtk_WChar_t PathSeparatorWChar()
     {
# if defined(_WIN32) || defined(__CYGWIN__) // Windows default, including MinGW and Cygwin
          return L'\\';
# else
          return L'/';
# endif
     }
     //! \brief File Utility : Retrieves The OS Path Separator as Dtk_string.
     //! \return "\\" on Windows/Cygwin, "/" otherwise.
     inline static const Dtk_string PathSeparatorString()
     {
# if defined(_WIN32) || defined(__CYGWIN__) // Windows default, including MinGW and Cygwin
          return L"\\";
# else
          return "/";
# endif
     }
 
     //! \brief File Utility : Fixes path separator consistency.
     //! It lets you replace the '\' or '/' by the OS needed separator.
     //! \remark It uses the PathSeparatorChar method to get the correct path separator.
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1;
     //! s1 = L"\\dir/dir2\\filename.extension";
     //! s1.FixPathSeparator();
     //! On Windows the path is now L"\\dir\\dir2\\filename.extension"
     //! On Linux/MacOS the path is now L"/dir/dir2/filename.extension"
     //! \endcode
     void FixPathSeparator();
 
     //! \brief concat two Dtk_string
     //! \param s1 the first Dtk_string to concat
     //! \param s2 the second Dtk_string to concat
     //! \return the resulting Dtk_string
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2,res;
     //! s1 = L"first string";
     //! s2 = L"second string";
     //! res = s1 + s2; //Now res is L"first stringsecond string"
     //! \endcode
     friend Dtk_string operator + ( const Dtk_string &s1, const Dtk_string &s2 );
 
     //! \brief concat an int to the Dtk_string (convert the int to Dtk_string)
     //! \param integer the int to concat
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,res;
     //! int val;
     //! s1 = L"first string";
     //! val = 2;
     //! s1.add_int(val); //Now res is L"first string2"
     //! \endcode
     void add_int( const int integer, int force_unsigned_int = 0 );
 
     void Merge( const Dtk_string &s2 );
     Dtk_string& operator += ( const Dtk_string &s2 );
 
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if they are identical false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 == s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator == ( const Dtk_string &s1, const Dtk_string &s2 );
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if s1 is greater than s2 false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 > s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator > ( const Dtk_string &s1, const Dtk_string &s2 );
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if s1 is smaller than s2 false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 < s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator < ( const Dtk_string &s1, const Dtk_string &s2 );
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if s1 is greater or equal than s2 false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 >= s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator >= ( const Dtk_string &s1, const Dtk_string &s2 );
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if s1 is smaller or equal than s2 false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 <= s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator <= ( const Dtk_string &s1, const Dtk_string &s2 );
     //! \brief compare two Dtk_string
     //! \param s1 the first Dtk_string to compare
     //! \param s2 the second Dtk_string to compare
     //! \return true if s1 is different of s2 false else
     //!
     //! \b Sample:
     //! \code
     //! Dtk_string s1,s2;
     //! ...
     //! if(s1 != s2)
     //! {
     //! ...
     //! }
     //! \endcode
     friend bool operator != ( const Dtk_string &s1, const Dtk_string &s2 );
     friend std::ostream& operator<<( std::ostream&, const Dtk_string& );
 
 
 
};
 
namespace Dtk_StringUtility
{
     std::string ToUtf8( wchar_t const * );
     std::string ToUtf8( Dtk_string const & );
 
     Dtk_string FromUtf8( char const * );
}
 
 
#endif // __DTK_STRING_HPP__
 
#endif // A93938D6857511E1B78E58294824019B