[wxWidgets.git] / interface / wx / numformatter.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wx/numformatter.h
// Purpose:     interface to wxNumberFormatter
// Author:      Fulvio Senore, Vadim Zeitlin
// Licence:     wxWindows licence
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxNumberFormatter

    Helper class for formatting and parsing numbers with thousands separators.

    This class contains only static functions, so users must not create instances
    but directly call the member functions.

    @since 2.9.2

    @library{wxbase}
*/
class wxNumberFormatter
{
public:
    /**
        Bit masks used with ToString().
     */
    enum Style
    {
        /**
            This flag can be used to indicate absence of any other flags below.
         */
        Style_None              = 0x00,

        /**
            If this flag is given, thousands separators will be inserted in the
            number string representation as defined by the current locale.
         */
        Style_WithThousandsSep  = 0x01,

        /**
            If this flag is given, trailing zeroes in a floating point number
            string representation will be omitted.

            If the number is actually integer, the decimal separator will be
            omitted as well. To give an example, formatting the number @c 1.23
            with precision 5 will normally yield "1.23000" but with this flag
            it would return "1.23". And formatting @c 123 with this flag will
            return just "123" for any precision.

            This flag can't be used with ToString() overload taking the integer
            value.
         */
        Style_NoTrailingZeroes  = 0x02
    };

    /**
        Returns string representation of an integer number.

        By default, the string will use thousands separators if appropriate for
        the current locale. This can be avoided by passing Style_None as @a
        flags in which case the call to the function has exactly the same
        effect as <code>wxString::Format("%ld", val)</code>.

        Notice that calling ToString() with a value of type @c int and
        non-default flags results in ambiguity between this overload and the
        one below. To resolve it, you need to cast the value to @c long.

        @param val
            The variable to convert to a string.
        @param flags
            Combination of values from the Style enumeration (except for
            Style_NoTrailingZeroes which can't be used with this overload).
    */
    static wxString ToString(long val, int flags = Style_WithThousandsSep);

    /**
        Returns string representation of a floating point number.

        @param val
            The variable to convert to a string.
        @param precision
            Number of decimals to write in formatted string.
        @param flags
            Combination of values from the Style enumeration.
    */
    static wxString
    ToString(double val, int precision, int flags = Style_WithThousandsSep);


    /**
        Parse a string representation of a number possibly including thousands
        separators.

        These functions parse number representation in the current locale. On
        success they return @true and store the result at the location pointed
        to by @a val (which can't be @NULL), otherwise @false is returned.

        @see wxString::ToLong(), wxString::ToDouble()
     */
    //@{
    static bool FromString(wxString s, long *val);
    static bool FromString(wxString s, double *val);
    //@}

    /**
        Get the decimal separator for the current locale.

        Decimal separators is always defined and we fall back to returning '.'
        in case of an error.
     */
    static wxChar GetDecimalSeparator();

    /**
        Get the thousands separator if grouping of the digits is used by the
        current locale.

        The value returned in @a sep should be only used if the function
        returns @true, otherwise no thousands separator should be used at all.

        @param sep
            Points to the variable receiving the thousands separator character
            if it is used by the current locale. May be @NULL if only the
            function return value is needed.
     */
    static bool GetThousandsSeparatorIfUsed(wxChar *sep);

};
Commit	Line	Data
6686fbad VZ	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	/**
6d0b86b7	29	This flag can be used to indicate absence of any other flags below.
6686fbad VZ	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	};