interface/wx/numformatter.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/numformatter.h
   3 // Purpose:     interface to wxNumberFormatter
   4 // Author:      Fulvio Senore, Vadim Zeitlin
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxNumberFormatter
  10
  11     Helper class for formatting and parsing numbers with thousands separators.
  12
  13     This class contains only static functions, so users must not create instances
  14     but directly call the member functions.
  15
  16     @since 2.9.2
  17
  18     @library{wxbase}
  19 */
  20 class wxNumberFormatter
  21 {
  22 public:
  23     /**
  24         Bit masks used with ToString().
  25      */
  26     enum Style
  27     {
  28         /**
  29             This flag cab be used to indicate absence of any other flags below.
  30          */
  31         Style_None              = 0x00,
  32
  33         /**
  34             If this flag is given, thousands separators will be inserted in the
  35             number string representation as defined by the current locale.
  36          */
  37         Style_WithThousandsSep  = 0x01,
  38
  39         /**
  40             If this flag is given, trailing zeroes in a floating point number
  41             string representation will be omitted.
  42
  43             If the number is actually integer, the decimal separator will be
  44             omitted as well. To give an example, formatting the number @c 1.23
  45             with precision 5 will normally yield "1.23000" but with this flag
  46             it would return "1.23". And formatting @c 123 with this flag will
  47             return just "123" for any precision.
  48
  49             This flag can't be used with ToString() overload taking the integer
  50             value.
  51          */
  52         Style_NoTrailingZeroes  = 0x02
  53     };
  54
  55     /**
  56         Returns string representation of an integer number.
  57
  58         By default, the string will use thousands separators if appropriate for
  59         the current locale. This can be avoided by passing Style_None as @a
  60         flags in which case the call to the function has exactly the same
  61         effect as <code>wxString::Format("%ld", val)</code>.
  62
  63         Notice that calling ToString() with a value of type @c int and
  64         non-default flags results in ambiguity between this overload and the
  65         one below. To resolve it, you need to cast the value to @c long.
  66
  67         @param val
  68             The variable to convert to a string.
  69         @param flags
  70             Combination of values from the Style enumeration (except for
  71             Style_NoTrailingZeroes which can't be used with this overload).
  72     */
  73     static wxString ToString(long val, int flags = Style_WithThousandsSep);
  74
  75     /**
  76         Returns string representation of a floating point number.
  77
  78         @param val
  79             The variable to convert to a string.
  80         @param precision
  81             Number of decimals to write in formatted string.
  82         @param flags
  83             Combination of values from the Style enumeration.
  84     */
  85     static wxString
  86     ToString(double val, int precision, int flags = Style_WithThousandsSep);
  87
  88
  89     /**
  90         Parse a string representation of a number possibly including thousands
  91         separators.
  92
  93         These functions parse number representation in the current locale. On
  94         success they return @true and store the result at the location pointed
  95         to by @a val (which can't be @NULL), otherwise @false is returned.
  96
  97         @see wxString::ToLong(), wxString::ToDouble()
  98      */
  99     //@{
 100     static bool FromString(wxString s, long *val);
 101     static bool FromString(wxString s, double *val);
 102     //@}
 103
 104     /**
 105         Get the decimal separator for the current locale.
 106
 107         Decimal separators is always defined and we fall back to returning '.'
 108         in case of an error.
 109      */
 110     static wxChar GetDecimalSeparator();
 111
 112     /**
 113         Get the thousands separator if grouping of the digits is used by the
 114         current locale.
 115
 116         The value returned in @a sep should be only used if the function
 117         returns @true, otherwise no thousands separator should be used at all.
 118
 119         @param sep
 120             Points to the variable receiving the thousands separator character
 121             if it is used by the current locale. May be @NULL if only the
 122             function return value is needed.
 123      */
 124     static bool GetThousandsSeparatorIfUsed(wxChar *sep);
 125
 126 };