applications/utilities/postProcessing/dataConversion/foamToTecplot360/tecio/tecsrc/TranslatedString.h

   1 /*
   2  * NOTICE and LICENSE for Tecplot Input/Output Library (TecIO) - OpenFOAM
   3  *
   4  * Copyright (C) 1988-2009 Tecplot, Inc.  All rights reserved worldwide.
   5  *
   6  * Tecplot hereby grants OpenCFD limited authority to distribute without
   7  * alteration the source code to the Tecplot Input/Output library, known
   8  * as TecIO, as part of its distribution of OpenFOAM and the
   9  * OpenFOAM_to_Tecplot converter.  Users of this converter are also hereby
  10  * granted access to the TecIO source code, and may redistribute it for the
  11  * purpose of maintaining the converter.  However, no authority is granted
  12  * to alter the TecIO source code in any form or manner.
  13  *
  14  * This limited grant of distribution does not supersede Tecplot, Inc.'s
  15  * copyright in TecIO.  Contact Tecplot, Inc. for further information.
  16  *
  17  * Tecplot, Inc.
  18  * 3535 Factoria Blvd, Ste. 550
  19  * Bellevue, WA 98006, USA
  20  * Phone: +1 425 653 1200
  21  * http://www.tecplot.com/
  22  *
  23  */
  24 /*
  25 *****************************************************************
  26 *****************************************************************
  27 *******                                                  ********
  28 ****** Copyright (C) 1988-2008 Tecplot, Inc.              *******
  29 *******                                                  ********
  30 *****************************************************************
  31 *****************************************************************
  32 */
  33
  34 #ifndef TECPLOT_STRUTIL_TRANSLATEDSTRING
  35 #define TECPLOT_STRUTIL_TRANSLATEDSTRING
  36
  37 #if defined MSWIN
  38 #pragma warning(disable : 4181)
  39 #endif
  40
  41 namespace tecplot
  42 {
  43 namespace strutil
  44 {
  45
  46 /**
  47  * Class responsible for translating strings for internationalization. This
  48  * class is used both to perform the translation and to identify which strings
  49  * are/aren't in need of translation.
  50  *
  51  * With the exception of the empty constructor all translated strings are
  52  * created via static methods or inline helper functions named translate() and
  53  * dontTranslate(). Translated strings created with a call to translate() are
  54  * flagged as needing human translation and return the translated value at
  55  * runtime. Translated strings created with a call to dontTranslate() are
  56  * flagged as not needing human translation and return the non-translated value
  57  * at runtime. Examples:
  58  *
  59  *   ErrMsg(translate("Can I have %d cookies?", numCookies);
  60  *   ErrMsg(dontTranslate("%s"), errMsgString);
  61  *
  62  * Conversion methods exists for std::string so that they operate well
  63  * together. Therefore you can pass translated strings to methods or functions
  64  * that receive std::string or std::string references. Additionally you can
  65  * perform std::string operations by casting the translated string to a
  66  * std::string. For example:
  67  *
  68  *   if (string(dialogTitle).size() != 0)
  69  *     ...do something useful
  70  *
  71  * We have intentionally not provided conversion methods for "const char*" (an
  72  * internal representation of the object's string) because of the risk of the
  73  * client using the pointer after the translated string object goes out of
  74  * scope.
  75  *
  76  * @author David Ossorio
  77  */
  78 class TranslatedString
  79 {
  80 public:
  81     /**
  82      * Enumeration describing available translation modes.
  83      */
  84     typedef enum { DontTranslate, DoTranslate } Mode;
  85
  86     /**
  87      * Constructs an empty translated string. It is equivalent to calling
  88      * TranslatedString::null().
  89      */
  90     TranslatedString();
  91
  92     /**
  93      * Convenience function for creating a NULL translated string.
  94      *
  95      * @return
  96      *     NULL translated string.
  97      */
  98     static TranslatedString null();
  99
 100     /**
 101      * Creates a translated string object and marks it as a string needing
 102      * translation.
 103      *
 104      * @param str
 105      *     Character string to translate.
 106      * @param translatorNotes
 107      *     Optional notes for the human translator describing the meaning
 108      *     of the string.
 109      */
 110     static TranslatedString translate(const char* str,
 111                                       const char* translatorNotes = NULL);
 112
 113     /**
 114      * Creates a translated string object and marks it as a string not needing
 115      * translation.
 116      *
 117      * @param str
 118      *     Character string to translate. The str parameter can be a NULL
 119      *     pointer.
 120      */
 121     static TranslatedString dontTranslate(const char* str);
 122
 123     /**
 124      * Destructor.
 125      */
 126     virtual ~TranslatedString();
 127
 128     /**
 129      * Indicates if the object's string is NULL.
 130      *
 131      * @return
 132      *     true if the object's string is NULL, false otherwise.
 133      */
 134     virtual bool isNull() const;
 135
 136     /**
 137      * Indicates if the object's string is NULL or zero length.
 138      *
 139      * @return
 140      *     true if the object's string is NULL or zero length, false otherwise.
 141      */
 142     virtual bool isNullOrZeroLength() const;
 143
 144     /**
 145      * Returns the internal representation of the object's string. Use this
 146      * result carefully. When this object goes out of scope so does this
 147      * references.
 148      *
 149      * @return
 150      *     Pointer to the internal representation of the object's string.
 151      */
 152     virtual const char* c_str();
 153
 154 #if defined MSWIN
 155     /**
 156      * Returns the internal representation of the wide character version of the
 157      * object's string. Use this result carefully. When this object goes out of
 158      * scope so does this references.
 159      *
 160      * @return
 161      *     Pointer to the internal representation of the object's string.
 162      */
 163     virtual const wchar_t* c_wstr();
 164 #endif
 165
 166     /**
 167      * Returns a copy of the object's string by this object. The result is
 168      * translated or not depending on the platform and how it was created.
 169      *
 170      * @return
 171      *     Copy of the object's string.
 172      */
 173     virtual operator std::string();
 174
 175 #if defined MSWIN
 176     /**
 177      * Returns a copy of the wide character version of the object's string.
 178      * The result is translated or not depending on the platform and how it was
 179      * created.
 180      *
 181      * @return
 182      *     Copy of the wide character version of the object's string.
 183      */
 184     virtual operator std::wstring();
 185 #endif
 186
 187     /**
 188      * Assignment operator.
 189      */
 190     virtual TranslatedString& operator =(const TranslatedString& other);
 191
 192     /**
 193      * Copy constructor.
 194      */
 195     TranslatedString(const TranslatedString& other);
 196
 197 #if !defined NO_ASSERTS
 198     /**
 199      * Used only for assertions.
 200      */
 201     virtual bool isValid() const;
 202 #endif /* !NO_ASSERTS */
 203
 204 private:
 205     /**
 206      * Constructs a translated string. This is declared private to make sure
 207      * clients use translate() or dontTranslate() so that Tecplot's translation
 208      * parser can easily extract strings from the source code.
 209      *
 210      * @param mode
 211      *     Indicates if this string is to be translated or not at runtime.
 212      * @param str
 213      *     Character string to translate.
 214      * @param translatorNotes
 215      *     Optional notes for the human translator describing the meaning
 216      *     of the string.
 217      */
 218     TranslatedString(TranslatedString::Mode mode,
 219                      const char*            str,
 220                      const char*            translatorNotes);
 221
 222     /**
 223      * Convenience method for initialize a translated string.
 224      *
 225      * @param mode
 226      *     Indicates if this string is to be translated or not at runtime.
 227      * @param str
 228      *     Character string to translate.
 229      * @param translatorNotes
 230      *     Optional notes for the human translator describing the meaning
 231      *     of the string.
 232      */
 233     void init(TranslatedString::Mode mode,
 234               const char*            str,
 235               const char*            translatorNotes);
 236
 237     /**
 238      * Private instance data.
 239      */
 240     TranslatedString::Mode  m_mode;
 241     bool                    m_isNull;
 242     std::string             m_string;
 243     std::string            *m_utf8String;
 244 #if defined MSWIN
 245     std::wstring           *m_wideString;
 246 #endif
 247 };
 248
 249 /**
 250  * Convenience function for creating a translated string object and marking it
 251  * as a string needing translation.
 252  *
 253  * @param str
 254  *     Character string to translate.
 255  * @param translatorNotes
 256  *     Optional notes for the human translator describing the meaning
 257  *     of the string.
 258  */
 259 inline TranslatedString translate(const char* str,
 260                                   const char* translatorNotes = NULL)
 261 {
 262     return TranslatedString::translate(str, translatorNotes);
 263 }
 264
 265 /**
 266  * Convenience function for creating a translated string object and marking it
 267  * as a string not needing translation.
 268  *
 269  * @param str
 270  *     Character string to translate. The str parameter can be a NULL
 271  *     pointer.
 272  */
 273 inline TranslatedString dontTranslate(const char* str)
 274 {
 275     return TranslatedString::dontTranslate(str);
 276 }
 277
 278 /**
 279  * Convenience function for creating a translated string object and marks it as
 280  * a string not needing translation.
 281  *
 282  * @param str
 283  *     String to translate.
 284  */
 285 inline TranslatedString dontTranslate(const std::string& str)
 286 {
 287     return TranslatedString::dontTranslate(str.c_str());
 288 }
 289
 290 }
 291 }
 292
 293 #endif