include/wx/strvararg.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/strvararg.h
   3 // Purpose:     macros for implementing type-safe vararg passing of strings
   4 // Author:      Vaclav Slavik
   5 // Created:     2007-02-19
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2007 REA Elektronik GmbH
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_STRVARARG_H_
  12 #define _WX_STRVARARG_H_
  13
  14 #include "wx/platform.h"
  15 #if wxONLY_WATCOM_EARLIER_THAN(1,4)
  16     #error "OpenWatcom version >= 1.4 is required to compile this code"
  17 #endif
  18
  19 #include "wx/chartype.h"
  20
  21 class WXDLLIMPEXP_BASE wxCStrData;
  22 class WXDLLIMPEXP_BASE wxString;
  23 class WXDLLIMPEXP_BASE wxCharBuffer;
  24 class WXDLLIMPEXP_BASE wxWCharBuffer;
  25
  26
  27 // ----------------------------------------------------------------------------
  28 // WX_DEFINE_VARARG_FUNC* macros
  29 // ----------------------------------------------------------------------------
  30
  31 // This macro is used to implement type-safe wrappers for variadic functions
  32 // that accept strings as arguments. This makes it possible to pass char*,
  33 // wchar_t* or even wxString (as opposed to having to use wxString::c_str())
  34 // to e.g. wxPrintf().
  35 //
  36 // This is done by defining a set of N template function taking 1..N arguments
  37 // (currently, N is set to 30 in this header). These functions are just thin
  38 // wrappers around another variadic function (@a impl) and the only thing
  39 // the wrapper does is that it normalizes the arguments passed in so that
  40 // they are of the type expected by variadic functions taking string
  41 // arguments, i.e., char* or wchar_t*, depending on the build:
  42 //   * char* in the current locale's charset in ANSI build
  43 //   * whchar_t* in the Unicode build
  44 //
  45 // Parameters:
  46 //        rettype   Functions' return type.
  47 //        name      Name of the function.
  48 //        impl      Name of the variadic function that implements 'name'.
  49 #define WX_DEFINE_VARARG_FUNC(rettype, name, impl)                        \
  50         _WX_VARARG_ITER(_WX_VARARG_MAX_ARGS,                              \
  51                         _WX_VARARG_DEFINE_FUNC,                           \
  52                         rettype, name, impl)
  53
  54 // Like WX_DEFINE_VARARG_FUNC, but for variadic functions that don't return
  55 // a value.
  56 #define WX_DEFINE_VARARG_FUNC_VOID(name, impl)                            \
  57         _WX_VARARG_ITER(_WX_VARARG_MAX_ARGS,                              \
  58                         _WX_VARARG_DEFINE_FUNC_VOID,                      \
  59                         void, name, impl)
  60
  61 // Like WX_DEFINE_VARARG_FUNC_VOID, but instead of wrapping an implementation
  62 // function, does nothing in defined functions' bodies.
  63 //
  64 // Used to implement wxLogXXX functions if wxUSE_LOG=0.
  65 #define WX_DEFINE_VARARG_FUNC_NOP(name)                                   \
  66         _WX_VARARG_ITER(_WX_VARARG_MAX_ARGS,                              \
  67                         _WX_VARARG_DEFINE_FUNC_NOP,                       \
  68                         void, name, dummy)
  69
  70 // ----------------------------------------------------------------------------
  71 // implementation
  72 // ----------------------------------------------------------------------------
  73
  74 // Converts an argument passed to wxPrint etc. into standard form expected,
  75 // by wxXXX functions, e.g. all strings (wxString, char*, wchar_t*) are
  76 // converted into wchar_t* or char* depending on the build.
  77 template<typename T>
  78 struct wxArgNormalizer
  79 {
  80     wxArgNormalizer(const T& value) : m_value(value) {}
  81
  82     // Returns the value in a form that can be safely passed to real vararg
  83     // functions. In case of strings, this is char* in ANSI build and wchar_t*
  84     // in Unicode build.
  85     const T& get() const { return m_value; }
  86
  87     const T& m_value;
  88 };
  89
  90 // special cases for converting strings:
  91
  92 template<>
  93 struct WXDLLIMPEXP_BASE wxArgNormalizer<const wxCStrData&>
  94 {
  95     wxArgNormalizer(const wxCStrData& value) : m_value(value) {}
  96     const wxChar *get() const; // FIXME-UTF8: should be wxStringCharType
  97
  98     const wxCStrData& m_value;
  99 };
 100
 101 template<>
 102 struct wxArgNormalizer<wxCStrData> : public wxArgNormalizer<const wxCStrData&>
 103 {
 104     wxArgNormalizer(const wxCStrData& value)
 105         : wxArgNormalizer<const wxCStrData&>(value) {}
 106 };
 107
 108 template<>
 109 struct WXDLLIMPEXP_BASE wxArgNormalizer<const wxString&>
 110 {
 111     wxArgNormalizer(const wxString& value) : m_value(value) {}
 112     const wxChar *get() const; // FIXME-UTF8: should be wxStringCharType
 113
 114     const wxString& m_value;
 115 };
 116
 117 template<>
 118 struct wxArgNormalizer<wxString> : public wxArgNormalizer<const wxString&>
 119 {
 120     wxArgNormalizer(const wxString& value)
 121         : wxArgNormalizer<const wxString&>(value) {}
 122 };
 123
 124 #if wxUSE_UNICODE // FIXME-UTF8: should be wxUSE_UNICODE_WCHAR
 125 template<>
 126 struct WXDLLIMPEXP_BASE wxArgNormalizer<const char*>
 127 {
 128     wxArgNormalizer(const char *value);
 129     ~wxArgNormalizer();
 130     const wchar_t *get() const;
 131
 132     wxWCharBuffer *m_value;
 133 };
 134
 135 template<>
 136 struct wxArgNormalizer<char*> : public wxArgNormalizer<const char*>
 137 {
 138     wxArgNormalizer(char *value)
 139         : wxArgNormalizer<const char*>(value) {}
 140 };
 141 #endif // wxUSE_UNICODE_WCHAR
 142
 143 // FIXME-UTF8
 144 #if 0 // wxUSE_UNICODE_UTF8
 145 // for conversion from local charset to UTF-8
 146 template<>
 147 struct WXDLLIMPEXP_BASE wxArgNormalizer<const char*>
 148 {
 149     wxArgNormalizer(const char *value);
 150     ~wxArgNormalizer();
 151     const char *get() const;
 152
 153     wxCharBuffer *m_value;
 154 };
 155
 156 template<>
 157 struct wxArgNormalizer<char*> : public wxArgNormalizer<const char*>
 158 {
 159     wxArgNormalizer(char *value)
 160         : wxArgNormalizer<const char*>(value) {}
 161 };
 162 #endif // wxUSE_UNICODE_UTF8
 163
 164 #if /*wxUSE_UNICODE_UTF8 || */ !wxUSE_UNICODE // FIXME-UTF8
 165 template<>
 166 struct WXDLLIMPEXP_BASE wxArgNormalizer<const wchar_t*>
 167 {
 168     wxArgNormalizer(const wchar_t *value);
 169     ~wxArgNormalizer();
 170     const char *get() const;
 171
 172     wxCharBuffer *m_value;
 173 };
 174
 175 template<>
 176 struct wxArgNormalizer<wchar_t*> : public wxArgNormalizer<const wchar_t*>
 177 {
 178     wxArgNormalizer(wchar_t *value)
 179         : wxArgNormalizer<const wchar_t*>(value) {}
 180 };
 181 #endif // wxUSE_UNICODE_UTF8 || !wxUSE_UNICODE
 182
 183 // versions for passing wx[W]CharBuffer:
 184 template<>
 185 struct WXDLLIMPEXP_BASE wxArgNormalizer<wxCharBuffer>
 186             : public wxArgNormalizer<const char*>
 187 {
 188     wxArgNormalizer(const wxCharBuffer& buf);
 189 };
 190
 191 template<>
 192 struct WXDLLIMPEXP_BASE wxArgNormalizer<wxWCharBuffer>
 193             : public wxArgNormalizer<const wchar_t*>
 194 {
 195     wxArgNormalizer(const wxWCharBuffer& buf);
 196 };
 197
 198
 199
 200 // NB: The vararg emulation code is limited to 30 arguments at the moment.
 201 //     If you need more, you need to
 202 //        1) increase the value of _WX_VARARG_MAX_ARGS
 203 //        2) add _WX_VARARG_JOIN_* and _WX_VARARG_ITER_* up to the new
 204 //           _WX_VARARG_MAX_ARGS value to the lists below
 205 #define _WX_VARARG_MAX_ARGS        30
 206
 207 #define _WX_VARARG_JOIN_1(m)                                 m(1)
 208 #define _WX_VARARG_JOIN_2(m)       _WX_VARARG_JOIN_1(m),     m(2)
 209 #define _WX_VARARG_JOIN_3(m)       _WX_VARARG_JOIN_2(m),     m(3)
 210 #define _WX_VARARG_JOIN_4(m)       _WX_VARARG_JOIN_3(m),     m(4)
 211 #define _WX_VARARG_JOIN_5(m)       _WX_VARARG_JOIN_4(m),     m(5)
 212 #define _WX_VARARG_JOIN_6(m)       _WX_VARARG_JOIN_5(m),     m(6)
 213 #define _WX_VARARG_JOIN_7(m)       _WX_VARARG_JOIN_6(m),     m(7)
 214 #define _WX_VARARG_JOIN_8(m)       _WX_VARARG_JOIN_7(m),     m(8)
 215 #define _WX_VARARG_JOIN_9(m)       _WX_VARARG_JOIN_8(m),     m(9)
 216 #define _WX_VARARG_JOIN_10(m)      _WX_VARARG_JOIN_9(m),     m(10)
 217 #define _WX_VARARG_JOIN_11(m)      _WX_VARARG_JOIN_10(m),    m(11)
 218 #define _WX_VARARG_JOIN_12(m)      _WX_VARARG_JOIN_11(m),    m(12)
 219 #define _WX_VARARG_JOIN_13(m)      _WX_VARARG_JOIN_12(m),    m(13)
 220 #define _WX_VARARG_JOIN_14(m)      _WX_VARARG_JOIN_13(m),    m(14)
 221 #define _WX_VARARG_JOIN_15(m)      _WX_VARARG_JOIN_14(m),    m(15)
 222 #define _WX_VARARG_JOIN_16(m)      _WX_VARARG_JOIN_15(m),    m(16)
 223 #define _WX_VARARG_JOIN_17(m)      _WX_VARARG_JOIN_16(m),    m(17)
 224 #define _WX_VARARG_JOIN_18(m)      _WX_VARARG_JOIN_17(m),    m(18)
 225 #define _WX_VARARG_JOIN_19(m)      _WX_VARARG_JOIN_18(m),    m(19)
 226 #define _WX_VARARG_JOIN_20(m)      _WX_VARARG_JOIN_19(m),    m(20)
 227 #define _WX_VARARG_JOIN_21(m)      _WX_VARARG_JOIN_20(m),    m(21)
 228 #define _WX_VARARG_JOIN_22(m)      _WX_VARARG_JOIN_21(m),    m(22)
 229 #define _WX_VARARG_JOIN_23(m)      _WX_VARARG_JOIN_22(m),    m(23)
 230 #define _WX_VARARG_JOIN_24(m)      _WX_VARARG_JOIN_23(m),    m(24)
 231 #define _WX_VARARG_JOIN_25(m)      _WX_VARARG_JOIN_24(m),    m(25)
 232 #define _WX_VARARG_JOIN_26(m)      _WX_VARARG_JOIN_25(m),    m(26)
 233 #define _WX_VARARG_JOIN_27(m)      _WX_VARARG_JOIN_26(m),    m(27)
 234 #define _WX_VARARG_JOIN_28(m)      _WX_VARARG_JOIN_27(m),    m(28)
 235 #define _WX_VARARG_JOIN_29(m)      _WX_VARARG_JOIN_28(m),    m(29)
 236 #define _WX_VARARG_JOIN_30(m)      _WX_VARARG_JOIN_29(m),    m(30)
 237
 238 #define _WX_VARARG_ITER_1(m,a,b,c)                               m(1,a,b,c)
 239 #define _WX_VARARG_ITER_2(m,a,b,c)   _WX_VARARG_ITER_1(m,a,b,c)  m(2,a,b,c)
 240 #define _WX_VARARG_ITER_3(m,a,b,c)   _WX_VARARG_ITER_2(m,a,b,c)  m(3,a,b,c)
 241 #define _WX_VARARG_ITER_4(m,a,b,c)   _WX_VARARG_ITER_3(m,a,b,c)  m(4,a,b,c)
 242 #define _WX_VARARG_ITER_5(m,a,b,c)   _WX_VARARG_ITER_4(m,a,b,c)  m(5,a,b,c)
 243 #define _WX_VARARG_ITER_6(m,a,b,c)   _WX_VARARG_ITER_5(m,a,b,c)  m(6,a,b,c)
 244 #define _WX_VARARG_ITER_7(m,a,b,c)   _WX_VARARG_ITER_6(m,a,b,c)  m(7,a,b,c)
 245 #define _WX_VARARG_ITER_8(m,a,b,c)   _WX_VARARG_ITER_7(m,a,b,c)  m(8,a,b,c)
 246 #define _WX_VARARG_ITER_9(m,a,b,c)   _WX_VARARG_ITER_8(m,a,b,c)  m(9,a,b,c)
 247 #define _WX_VARARG_ITER_10(m,a,b,c)  _WX_VARARG_ITER_9(m,a,b,c)  m(10,a,b,c)
 248 #define _WX_VARARG_ITER_11(m,a,b,c)  _WX_VARARG_ITER_10(m,a,b,c) m(11,a,b,c)
 249 #define _WX_VARARG_ITER_12(m,a,b,c)  _WX_VARARG_ITER_11(m,a,b,c) m(12,a,b,c)
 250 #define _WX_VARARG_ITER_13(m,a,b,c)  _WX_VARARG_ITER_12(m,a,b,c) m(13,a,b,c)
 251 #define _WX_VARARG_ITER_14(m,a,b,c)  _WX_VARARG_ITER_13(m,a,b,c) m(14,a,b,c)
 252 #define _WX_VARARG_ITER_15(m,a,b,c)  _WX_VARARG_ITER_14(m,a,b,c) m(15,a,b,c)
 253 #define _WX_VARARG_ITER_16(m,a,b,c)  _WX_VARARG_ITER_15(m,a,b,c) m(16,a,b,c)
 254 #define _WX_VARARG_ITER_17(m,a,b,c)  _WX_VARARG_ITER_16(m,a,b,c) m(17,a,b,c)
 255 #define _WX_VARARG_ITER_18(m,a,b,c)  _WX_VARARG_ITER_17(m,a,b,c) m(18,a,b,c)
 256 #define _WX_VARARG_ITER_19(m,a,b,c)  _WX_VARARG_ITER_18(m,a,b,c) m(19,a,b,c)
 257 #define _WX_VARARG_ITER_20(m,a,b,c)  _WX_VARARG_ITER_19(m,a,b,c) m(20,a,b,c)
 258 #define _WX_VARARG_ITER_21(m,a,b,c)  _WX_VARARG_ITER_20(m,a,b,c) m(21,a,b,c)
 259 #define _WX_VARARG_ITER_22(m,a,b,c)  _WX_VARARG_ITER_21(m,a,b,c) m(22,a,b,c)
 260 #define _WX_VARARG_ITER_23(m,a,b,c)  _WX_VARARG_ITER_22(m,a,b,c) m(23,a,b,c)
 261 #define _WX_VARARG_ITER_24(m,a,b,c)  _WX_VARARG_ITER_23(m,a,b,c) m(24,a,b,c)
 262 #define _WX_VARARG_ITER_25(m,a,b,c)  _WX_VARARG_ITER_24(m,a,b,c) m(25,a,b,c)
 263 #define _WX_VARARG_ITER_26(m,a,b,c)  _WX_VARARG_ITER_25(m,a,b,c) m(26,a,b,c)
 264 #define _WX_VARARG_ITER_27(m,a,b,c)  _WX_VARARG_ITER_26(m,a,b,c) m(27,a,b,c)
 265 #define _WX_VARARG_ITER_28(m,a,b,c)  _WX_VARARG_ITER_27(m,a,b,c) m(28,a,b,c)
 266 #define _WX_VARARG_ITER_29(m,a,b,c)  _WX_VARARG_ITER_28(m,a,b,c) m(29,a,b,c)
 267 #define _WX_VARARG_ITER_30(m,a,b,c)  _WX_VARARG_ITER_29(m,a,b,c) m(30,a,b,c)
 268
 269 // This macro calls another macro 'm' passed as second argument 'N' times,
 270 // with its only argument set to 1..N, and concatenates the results using
 271 // comma as separator.
 272 //
 273 // An example:
 274 //     #define foo(i)  x##i
 275 //     // this expands to "x1,x2,x3,x4"
 276 //     _WX_VARARG_JOIN(4, foo)
 277 //
 278 //
 279 // N must not be greater than _WX_VARARG_MAX_ARGS (=30).
 280 #define _WX_VARARG_JOIN(N, m)             _WX_VARARG_JOIN_IMPL(N, m)
 281 #define _WX_VARARG_JOIN_IMPL(N, m)        _WX_VARARG_JOIN_##N(m)
 282
 283 // This macro calls another macro 'm' passed as second argument 'N' times, with
 284 // its first argument set to 1..N and the remaining arguments set to 'a', 'b'
 285 // and 'c'. The results are separated with whitespace in the expansion.
 286 //
 287 // An example:
 288 //     // this macro expands to:
 289 //     //     foo(1,a,b,c)
 290 //     //     foo(2,a,b,c)
 291 //     //     foo(3,a,b,c)
 292 //     _WX_VARARG_ITER(3, foo, a, b, c)
 293 //
 294 // N must not be greater than _WX_VARARG_MAX_ARGS (=30).
 295 #define _WX_VARARG_ITER(N, m,a,b,c)       _WX_VARARG_ITER_IMPL(N, m, a, b, c)
 296 #define _WX_VARARG_ITER_IMPL(N, m,a,b,c)  _WX_VARARG_ITER_##N(m, a, b, c)
 297
 298 // Generates code snippet for i-th argument in vararg function's prototype.
 299 #define _WX_VARARG_ARG(i)          T##i a##i
 300
 301 // Like _WX_VARARG_ARG_UNUSED, but outputs argument's type with WXUNUSED.
 302 #define _WX_VARARG_ARG_UNUSED(i)   T##i WXUNUSED(a##i)
 303
 304 // Generates code snippet for i-th type in vararg function's template<...>.
 305 #define _WX_VARARG_TEMPL(i)        typename T##i
 306
 307 // Generates code snippet for passing i-th argument of vararg function
 308 // wrapper to its implementation, normalizing it in the process
 309 #define _WX_VARARG_PASS(i)         wxArgNormalizer<T##i>(a##i).get()
 310
 311
 312 // Macro to be used with _WX_VARARG_ITER in the implementation of
 313 // WX_DEFINE_VARARG_FUNC (see its documentation for the meaning of arguments)
 314 #define _WX_VARARG_DEFINE_FUNC(N, rettype, name, impl)                      \
 315     template<_WX_VARARG_JOIN(N, _WX_VARARG_TEMPL)>                          \
 316     rettype name(_WX_VARARG_JOIN(N, _WX_VARARG_ARG))                        \
 317     {                                                                       \
 318         return impl(_WX_VARARG_JOIN(N, _WX_VARARG_PASS));                   \
 319     }
 320
 321 // Macro to be used with _WX_VARARG_ITER in the implementation of
 322 // WX_DEFINE_VARARG_FUNC_VOID (see its documentation for the meaning of
 323 // arguments; rettype is ignored and is used only to satisfy _WX_VARARG_ITER's
 324 // requirements).
 325 #define _WX_VARARG_DEFINE_FUNC_VOID(N, rettype, name, impl)                 \
 326     template<_WX_VARARG_JOIN(N, _WX_VARARG_TEMPL)>                          \
 327     void name(_WX_VARARG_JOIN(N, _WX_VARARG_ARG))                           \
 328     {                                                                       \
 329         impl(_WX_VARARG_JOIN(N, _WX_VARARG_PASS));                          \
 330     }
 331
 332 // Macro to be used with _WX_VARARG_ITER in the implementation of
 333 // WX_DEFINE_VARARG_FUNC_NOP, i.e. empty stub for a disabled vararg function.
 334 // The rettype and impl arguments are ignored.
 335 #define _WX_VARARG_DEFINE_FUNC_NOP(N, rettype, name, impl)                  \
 336     template<_WX_VARARG_JOIN(N, _WX_VARARG_TEMPL)>                          \
 337     void name(_WX_VARARG_JOIN(N, _WX_VARARG_ARG_UNUSED)) {}
 338
 339
 340 #endif // _WX_STRVARARG_H_