src/libs/common/Format.h

   1 //
   2 // This file is part of the aMule Project.
   3 //
   4 // Copyright (c) 2005-2008 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 "MuleDebug.h"
  29
  30
  31 /**
  32  * Classes that implement this interface are usable as
  33  * arguments for %s format strings. This is needed because
  34  * CFormat objects are typically created as temporary objects,
  35  * which makes external declarations of operator% impossible,
  36  * due to the fact that a non-const reference to a temporary
  37  * object is prohibited, as in:
  38  *      CFormat& operator%(CFormat& fmt, ...)
  39  *
  40  * With this approch, it is possible to use CFormat as usual:
  41  *      CFormat(...) % <some CPrintable object>;
  42  */
  43 class CPrintable
  44 {
  45 public:
  46         /** Must return a "pretty" string representation of the object. */
  47         virtual wxString GetPrintableString() const = 0;
  48
  49 protected:
  50         virtual ~CPrintable() {}
  51 };
  52
  53
  54
  55
  56 /**
  57  * This class offers a typesafe alternative to wxString::Format.
  58  *
  59  * Unlike normal format and printf, this class does not care about the
  60  * type of integer values passed to it, and will handle a value correctly,
  61  * even if the format-string and the actual type dissagree. Therefore, it
  62  * is suggested that only %i and %u be used for integers, for the sake of
  63  * clarity, though %i alone is enough.
  64  *
  65  * The other integer type-fields are supported, but will have no inpact on
  66  * how the value is represented. The only exception to this is the 'o', 'x'
  67  * and 'X' fields, which will always be considered to be unsigned!
  68  *
  69  * CFormat lacks the following capabilities:
  70  *  * The "*" width-modifier, because only one argument is fed at a time.
  71  *  * The "p" type, could be implemented using void* or templates.
  72  *  * The "n" type, just unsafe, wont be implemented.
  73  *  * The Long Double type, which is extremly slow and shouldn't be used.
  74  *
  75  *  CFormat has been implemented against the description of printf found
  76  *  in the "man 3 printf" manual page.
  77  */
  78 class CFormat
  79 {
  80 public:
  81         /**
  82          * Constructor.
  83          *
  84          * @param str The format-string to be used.
  85          */
  86         CFormat(const wxChar* str);
  87
  88         /**
  89          * Constructor.
  90          * This form is required to construct from a plain char *
  91          * with wx 2.9
  92          *
  93          * @param str The format-string to be used.
  94          */
  95         CFormat(const wxString& str);
  96
  97         /**
  98          * Returns true if the resulting string is ready for use.
  99          *
 100          * For a string to be ready to use, all format fields must have
 101          * had a value assigned through the operator% functions.
 102          */
 103         bool IsReady() const;
 104
 105
 106         /**
 107          * Feeds an value into the format-string.
 108          *
 109          * Passing an type that isn't compatible with the current format
 110          * field results in field being skipped, and an exception is raised.
 111          * Passing any type to an CFormat with no free fields results an
 112          * assertion, and the argument being ignored.
 113          *
 114          * Special rules apply to integers, see above.
 115          */
 116         // \{
 117         CFormat& operator%(wxChar value);
 118         CFormat& operator%(signed short value)          { return *this % (signed long long)value; }
 119         CFormat& operator%(unsigned short value)        { return *this % (unsigned long long)value; }
 120         CFormat& operator%(signed int value)            { return *this % (signed long long)value; }
 121         CFormat& operator%(unsigned int value)          { return *this % (unsigned long long)value; }
 122         CFormat& operator%(signed long value)           { return *this % (signed long long)value; }
 123         CFormat& operator%(unsigned long value)         { return *this % (unsigned long long)value; }
 124         CFormat& operator%(signed long long value);
 125         CFormat& operator%(unsigned long long value);
 126         CFormat& operator%(double value);
 127         CFormat& operator%(const wxChar* value)         { return *this % wxString(value); }
 128         CFormat& operator%(const wxString& value);
 129         CFormat& operator%(const CPrintable& value)     { return *this % value.GetPrintableString(); }
 130         CFormat& operator%(void * value);
 131         // \}
 132
 133
 134         /**
 135          * Returns the resulting string, should only be used when all arguments have been given.
 136          */
 137         wxString GetString() const;
 138
 139         /**
 140          * Implicit conversion to wxString.
 141          */
 142         operator wxString() const               { return GetString(); };
 143
 144 private:
 145         /**
 146          * Sets the value of the current field, and locates
 147          * the next format field in the string.
 148          */
 149         void            SetCurrentField(const wxString& value);
 150
 151         /**
 152          * Returns the current format-field, or an empty
 153          * string if no field was found.
 154          */
 155         wxString        GetCurrentField();
 156
 157         /**
 158          * Returns the next field modified to fit the given integer type.
 159          *
 160          * @param fieldType A modifier and type for an integer value.
 161          * @return The resulting format-string.
 162          *
 163          * This function is used to generate the integer-type independant
 164          * fields, by modifying the existing format-string to fit the type
 165          * of the integer value that has been passed to it.
 166          */
 167         wxString        GetIntegerField(const wxChar* fieldType);
 168
 169         //! Index to the current format field.
 170         size_t  m_fieldStart;
 171         //! Length of the current format field.
 172         size_t  m_fieldLength;
 173         //! The number of fields to skip in GetCurrentField
 174         size_t  m_skipCount;
 175
 176         //! The format-string fed to the parser.
 177         wxString        m_format;
 178         //! The current result of arguments fed to the parser.
 179         wxString        m_result;
 180 };
 181
 182
 183 #if wxCHECK_VERSION(2, 9, 0)
 184 #define WXLONGLONGFMTSPEC wxT(wxLongLongFmtSpec)
 185 #else
 186 #define WXLONGLONGFMTSPEC wxLongLongFmtSpec
 187 #endif
 188
 189 #endif
 190 // File_checked_for_headers