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 "n" type, just unsafe, wont be implemented.
  72  *  * The Long Double type, which is extremly slow and shouldn't be used.
  73  *
  74  *  CFormat has been implemented against the description of printf found
  75  *  in the "man 3 printf" manual page.
  76  */
  77 class CFormat
  78 {
  79 public:
  80         /**
  81          * Constructor.
  82          *
  83          * @param str The format-string to be used.
  84          */
  85         CFormat(const wxChar* str);
  86
  87         /**
  88          * Constructor.
  89          * This form is required to construct from a plain char *
  90          * with wx 2.9
  91          *
  92          * @param str The format-string to be used.
  93          */
  94         CFormat(const wxString& str);
  95
  96         /**
  97          * Returns true if the resulting string is ready for use.
  98          *
  99          * For a string to be ready to use, all format fields must have
 100          * had a value assigned through the operator% functions.
 101          */
 102         bool IsReady() const;
 103
 104
 105         /**
 106          * Feeds an value into the format-string.
 107          *
 108          * Passing an type that isn't compatible with the current format
 109          * field results in field being skipped, and an exception is raised.
 110          * Passing any type to an CFormat with no free fields results an
 111          * assertion, and the argument being ignored.
 112          *
 113          * Special rules apply to integers, see above.
 114          */
 115         // \{
 116         CFormat& operator%(wxChar value);
 117         CFormat& operator%(signed short value)          { return *this % (signed long long)value; }
 118         CFormat& operator%(unsigned short value)        { return *this % (unsigned long long)value; }
 119         CFormat& operator%(signed int value)            { return *this % (signed long long)value; }
 120         CFormat& operator%(unsigned int value)          { return *this % (unsigned long long)value; }
 121         CFormat& operator%(signed long value)           { return *this % (signed long long)value; }
 122         CFormat& operator%(unsigned long value)         { return *this % (unsigned long long)value; }
 123         CFormat& operator%(signed long long value);
 124         CFormat& operator%(unsigned long long value);
 125         CFormat& operator%(double value);
 126         CFormat& operator%(const wxChar* value)         { return *this % wxString(value); }
 127         CFormat& operator%(const wxString& value);
 128         CFormat& operator%(const CPrintable& value)     { return *this % value.GetPrintableString(); }
 129         CFormat& operator%(void * value);
 130         // \}
 131
 132
 133         /**
 134          * Returns the resulting string, should only be used when all arguments have been given.
 135          */
 136         wxString GetString() const;
 137
 138         /**
 139          * Implicit conversion to wxString.
 140          */
 141         operator wxString() const               { return GetString(); };
 142
 143 private:
 144         /**
 145          * Sets the value of the current field, and locates
 146          * the next format field in the string.
 147          */
 148         void            SetCurrentField(const wxString& value);
 149
 150         /**
 151          * Returns the current format-field, or an empty
 152          * string if no field was found.
 153          */
 154         wxString        GetCurrentField();
 155
 156         /**
 157          * Returns the next field modified to fit the given integer type.
 158          *
 159          * @param fieldType A modifier and type for an integer value.
 160          * @return The resulting format-string.
 161          *
 162          * This function is used to generate the integer-type independant
 163          * fields, by modifying the existing format-string to fit the type
 164          * of the integer value that has been passed to it.
 165          */
 166         wxString        GetIntegerField(const wxChar* fieldType);
 167
 168         //! Index to the current format field.
 169         size_t  m_fieldStart;
 170         //! Length of the current format field.
 171         size_t  m_fieldLength;
 172         //! The number of fields to skip in GetCurrentField
 173         size_t  m_skipCount;
 174
 175         //! The format-string fed to the parser.
 176         wxString        m_format;
 177         //! The current result of arguments fed to the parser.
 178         wxString        m_result;
 179 };
 180
 181
 182 #if wxCHECK_VERSION(2, 9, 0)
 183 #define WXLONGLONGFMTSPEC wxT(wxLongLongFmtSpec)
 184 #else
 185 #define WXLONGLONGFMTSPEC wxLongLongFmtSpec
 186 #endif
 187
 188 #endif
 189 // File_checked_for_headers