src/libs/common/Format.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2005-2011 aMule Team ( admin@amule.org / http://www.amule.org )
   5 //
   6 // Any parts of this program derived from the xMule, lMule or eMule project,
   7 // or contributed by third-party developers are copyrighted by their
   8 // respective authors.
   9 //
  10 // This program is free software; you can redistribute it and/or modify
  11 // it under the terms of the GNU General Public License as published by
  12 // the Free Software Foundation; either version 2 of the License, or
  13 // (at your option) any later version.
  14 //
  15 // This program 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
  18 // GNU 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 St, Fifth Floor, Boston, MA  02110-1301, USA
  23 //
  24
  25 #ifndef FORMAT_H
  26 #define FORMAT_H
  27
  28 #include <list>
  29 #include "MuleDebug.h"
  30
  31
  32 /**
  33  * This class offers a typesafe alternative to wxString::Format.
  34  *
  35  * %CFormat has been implemented against the description of printf found
  36  * in the "man 3 printf" manual page.
  37  *
  38  * %CFormat lacks the following capabilities:
  39  *  - The @c "*" width-modifier, because only one argument is fed at a time.
  40  *  - The @c "n" type, just unsafe and won't be implemented.
  41  *  - The @c "C" and @c "S" types, which are considered obsolete.
  42  *  - The Long Double type, which is extremly slow and shouldn't be used.
  43  *
  44  * Support for the C99 @c a, @c A conversions and the non-standard @c ', @c I
  45  * flags depend on the underlying C library. Do not use them.
  46  *
  47  * Supports the glibc-specific @c m conversion on all platforms, where there's
  48  * a way to get the error description. If the underlying C library has a
  49  * thread-safe way to get the error description, then this conversion is
  50  * thread-safe, too.
  51  *
  52  * Deviations from printf(3):
  53  *
  54  * %CFormat tries hard to format the passed POD-type according to the
  55  * conversion type. Basic type conversions may take place to accomplish this
  56  * goal. This results in formats accepting a variety of types, namely:
  57  *  - @c c, @c i, @c d, @c u, @c o, @c x, @c X accept @c wxChar and all integer
  58  *    types,
  59  *  - @c a, @c A, @c e, @c E, @c f, @c F, @c g, @c G accept @c wxChar, integer
  60  *    and floating-point types,
  61  *  - @c p accepts only pointers,
  62  *  - @c s accepts all the above mentioned types in addition to @c wxString and
  63  *    @c wxChar* types.
  64  *
  65  * The only exception from this rule is integer (@c d, @c i, @c u) conversion.
  66  * It will always use the correct conversion (@c i or @c u) depending on the
  67  * signedness of the passed argument.
  68  *
  69  * @c 's' conversions are inspired by the <em>"we're converting to string,
  70  * anyway"</em> mood. Thus they use a 'default' conversion for each accepted
  71  * type: @c 'c' for @c wxChar, @c 'i' and @c 'u' for signed and unsigned
  72  * integers, respectively, @c 'g' for floating-point numbers and @c 'p' for
  73  * pointers.
  74  *
  75  * Other relaxations / differences from printf(3):
  76  *  - Length modifiers are read and validated, but always ignored.
  77  *  - As a consequence, invalid combinations of length modifiers and conversion
  78  *    types are silently ignored (i.e. for example the invalid @c '%%qs'
  79  *    format-specifier is silently treated as @c '%%s').
  80  *  - @c 'p' conversion ignores all modifiers except the argument index reference.
  81  *  - You can mix positional and indexed argument references.
  82  *  - With indexed argument references we allow to leave gaps in the indices.
  83  */
  84 class CFormat
  85 {
  86       private:
  87         /**
  88          * Structure to hold a format specifier.
  89          */
  90         struct FormatSpecifier {
  91                 unsigned        argIndex;       //!< Argument index. (Position, unless specified otherwise.)
  92                 wxChar          flag;           //!< The optional flag character.
  93                 unsigned        width;          //!< The optional field width.
  94                 signed          precision;      //!< The optional precision value.
  95                 // length is not stored
  96                 wxChar          type;           //!< The conversion type.
  97                 size_t          startPos;       //!< Position of the first character of the format-specifier in the format-string.
  98                 size_t          endPos;         //!< Position of the last character of the format-specifier in the format-string.
  99                 wxString        result;         //!< Result of the conversion. Initialized to the format-specifier.
 100         };
 101
 102 public:
 103         /**
 104          * Constructor.
 105          *
 106          * @param str The format-string to be used.
 107          */
 108         CFormat(const wxChar* str)      { Init(str); }
 109
 110         /**
 111          * Constructor.
 112          *
 113          * This form is required to construct from a plain char *
 114          * with wx 2.9
 115          *
 116          * @param str The format-string to be used.
 117          */
 118         CFormat(const wxString& str)    { Init(str); }
 119
 120         /**
 121          * Feeds a value into the format-string.
 122          *
 123          * Passing a type that isn't compatible with the current format
 124          * field results in the field being skipped, and an exception raised.
 125          *
 126          * Passing any type to a CFormat with no free fields results in the
 127          * argument being ignored.
 128          *
 129          * Specialize this member template to teach CFormat how to handle
 130          * other types.
 131          */
 132         template<typename _Tp> CFormat& operator%(_Tp value);
 133
 134         // Overload hack to map all pointer types to void*
 135         template<typename _Tp> CFormat& operator%(_Tp* value)   { return this->operator%<void*>(value); }
 136
 137         // explicit overloads to avoid pass-by-value even in debug builds.
 138         CFormat& operator%(const wxString& value)               { return this->operator%<const wxString&>(value); }
 139         CFormat& operator%(const CFormat& value)                { return this->operator%<const wxString&>(value); }
 140
 141         /**
 142          * Returns the resulting string.
 143          */
 144         wxString GetString() const;
 145
 146         /**
 147          * Implicit conversion to wxString.
 148          */
 149         operator wxString() const               { return GetString(); };
 150
 151 private:
 152         /**
 153          * Initialize internal structures.
 154          *
 155          * Initializes member variables and parses the given format string.
 156          */
 157         void    Init(const wxString& str);
 158
 159         //! Type holding format specifiers.
 160         typedef std::list<FormatSpecifier>      FormatList;
 161
 162         //! Retrieve the modifiers for the given format specifier.
 163         wxString GetModifiers(FormatList::const_iterator it) const;
 164
 165         //! Do one argument conversion.
 166         template<typename _Tp>
 167         void    ProcessArgument(FormatList::iterator it, _Tp value);
 168
 169         //! List of the valid format-specifiers found in the format string.
 170         FormatList      m_formats;
 171
 172         //! Number of the previous argument.
 173         unsigned        m_argIndex;
 174
 175         //! The format-string fed to the parser.
 176         wxString        m_formatString;
 177 };
 178
 179 // type mappings
 180 template<> inline CFormat& CFormat::operator%(char value)               { return *this % (wxChar)value; }
 181 template<> inline CFormat& CFormat::operator%(signed char value)        { return *this % (wxChar)value; }
 182 template<> inline CFormat& CFormat::operator%(unsigned char value)      { return *this % (wxChar)value; }
 183 template<> inline CFormat& CFormat::operator%(bool value)               { return *this % (signed long long)value; }
 184 template<> inline CFormat& CFormat::operator%(signed short value)       { return *this % (signed long long)value; }
 185 template<> inline CFormat& CFormat::operator%(unsigned short value)     { return *this % (unsigned long long)value; }
 186 template<> inline CFormat& CFormat::operator%(signed int value)         { return *this % (signed long long)value; }
 187 template<> inline CFormat& CFormat::operator%(unsigned int value)       { return *this % (unsigned long long)value; }
 188 template<> inline CFormat& CFormat::operator%(signed long value)        { return *this % (signed long long)value; }
 189 template<> inline CFormat& CFormat::operator%(unsigned long value)      { return *this % (unsigned long long)value; }
 190 template<> inline CFormat& CFormat::operator%(float value)              { return *this % (double)value; }
 191 template<> inline CFormat& CFormat::operator%(const wxChar* value)      { return this->operator%<const wxString&>(wxString(value)); }
 192
 193
 194 #if wxCHECK_VERSION(2, 9, 0)
 195 #define WXLONGLONGFMTSPEC wxT(wxLongLongFmtSpec)
 196 #else
 197 #define WXLONGLONGFMTSPEC wxLongLongFmtSpec
 198 #endif
 199
 200 #endif
 201 // File_checked_for_headers