Where Online Learning is simpler!

The C and C++ Include Header Files

/usr/include/unicode/usimplenumberformatter.h


$ cat -n /usr/include/unicode/usimplenumberformatter.h

     1	// © 2022 and later: Unicode, Inc. and others.
     2	// License & terms of use: http://www.unicode.org/copyright.html
     3	
     4	#ifndef __USIMPLENUMBERFORMATTER_H__
     5	#define __USIMPLENUMBERFORMATTER_H__
     6	
     7	#include "unicode/utypes.h"
     8	
     9	#if !UCONFIG_NO_FORMATTING
    10	
    11	#include "unicode/uformattednumber.h"
    12	#include "unicode/unumberoptions.h"
    13	
    14	/**
    15	 * \file
    16	 * \brief C API: Simple number formatting focused on low memory and code size.
    17	 *
    18	 * These functions render locale-aware number strings but without the bells and whistles found in
    19	 * other number formatting APIs such as those in unumberformatter.h, like units and currencies.
    20	 *
    21	 * Example using C++ helpers:
    22	 *
    23	 * <pre>
    24	 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale("de-CH", status));
    25	 * LocalUFormattedNumberPointer uresult(unumf_openResult(status));
    26	 * usnumf_formatInt64(uformatter.getAlias(), 55, uresult.getAlias(), status);
    27	 * assertEquals("",
    28	 *     u"55",
    29	 *     ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), nullptr, status));
    30	 * </pre>
    31	 *
    32	 * Example using pure C:
    33	 * 
    34	 * <pre>
    35	 * UErrorCode ec = U_ZERO_ERROR;
    36	 * USimpleNumberFormatter* uformatter = usnumf_openForLocale("bn", &ec);
    37	 * USimpleNumber* unumber = usnum_openForInt64(1000007, &ec);
    38	 * UFormattedNumber* uresult = unumf_openResult(&ec);
    39	 * usnumf_format(uformatter, unumber, uresult, &ec);
    40	 * int32_t len;
    41	 * const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);
    42	 * if (assertSuccess("Formatting end-to-end", &ec)) {
    43	 *     assertUEquals("Should produce a result in Bangla digits", u"১০,০০,০০৭", str);
    44	 * }
    45	
    46	 * // Cleanup:
    47	 * unumf_closeResult(uresult);
    48	 * usnum_close(unumber);
    49	 * usnumf_close(uformatter);
    50	 * </pre>
    51	 */
    52	
    53	#ifndef U_HIDE_DRAFT_API
    54	
    55	
    56	/**
    57	 * An explicit sign option for a SimpleNumber.
    58	 *
    59	 * @draft ICU 73
    60	 */
    61	typedef enum USimpleNumberSign {
    62	    /**
    63	     * Render a plus sign.
    64	     *
    65	     * @draft ICU 73
    66	     */
    67	    UNUM_SIMPLE_NUMBER_PLUS_SIGN,
    68	    /**
    69	     * Render no sign.
    70	     *
    71	     * @draft ICU 73
    72	     */
    73	    UNUM_SIMPLE_NUMBER_NO_SIGN,
    74	    /**
    75	     * Render a minus sign.
    76	     *
    77	     * @draft ICU 73
    78	     */
    79	    UNUM_SIMPLE_NUMBER_MINUS_SIGN,
    80	} USimpleNumberSign;
    81	
    82	
    83	struct USimpleNumber;
    84	/**
    85	 * C-compatible version of icu::number::SimpleNumber.
    86	 *
    87	 * @draft ICU 73
    88	 */
    89	typedef struct USimpleNumber USimpleNumber;
    90	
    91	
    92	struct USimpleNumberFormatter;
    93	/**
    94	 * C-compatible version of icu::number::SimpleNumberFormatter.
    95	 *
    96	 * @draft ICU 73
    97	 */
    98	typedef struct USimpleNumberFormatter USimpleNumberFormatter;
    99	
   100	
   101	/**
   102	 * Creates a new USimpleNumber to be formatted with a USimpleNumberFormatter.
   103	 *
   104	 * @draft ICU 73
   105	 */
   106	U_CAPI USimpleNumber* U_EXPORT2
   107	usnum_openForInt64(int64_t value, UErrorCode* ec);
   108	
   109	
   110	/**
   111	 * Overwrites the value in a USimpleNumber to an int64_t.
   112	 *
   113	 * This can be used to reset the number value after formatting.
   114	 *
   115	 * @draft ICU 73
   116	 */
   117	U_CAPI void U_EXPORT2
   118	usnum_setToInt64(USimpleNumber* unumber, int64_t value, UErrorCode* ec);
   119	
   120	
   121	/**
   122	 * Changes the value of the USimpleNumber by a power of 10.
   123	 *
   124	 * This function immediately mutates the inner value.
   125	 *
   126	 * @draft ICU 73
   127	 */
   128	U_CAPI void U_EXPORT2
   129	usnum_multiplyByPowerOfTen(USimpleNumber* unumber, int32_t power, UErrorCode* ec);
   130	
   131	
   132	/**
   133	 * Rounds the value currently stored in the USimpleNumber to the given power of 10.
   134	 *
   135	 * This function immediately mutates the inner value.
   136	 *
   137	 * @draft ICU 73
   138	 */
   139	U_CAPI void U_EXPORT2
   140	usnum_roundTo(USimpleNumber* unumber, int32_t power, UNumberFormatRoundingMode roundingMode, UErrorCode* ec);
   141	
   142	
   143	/**
   144	 * Pads the beginning of the number with zeros up to the given minimum number of integer digits.
   145	 *
   146	 * This setting is applied upon formatting the number.
   147	 *
   148	 * @draft ICU 73
   149	 */
   150	U_CAPI void U_EXPORT2
   151	usnum_setMinimumIntegerDigits(USimpleNumber* unumber, int32_t minimumIntegerDigits, UErrorCode* ec);
   152	
   153	
   154	/**
   155	 * Pads the end of the number with zeros up to the given minimum number of fraction digits.
   156	 *
   157	 * This setting is applied upon formatting the number.
   158	 *
   159	 * @draft ICU 73
   160	 */
   161	U_CAPI void U_EXPORT2
   162	usnum_setMinimumFractionDigits(USimpleNumber* unumber, int32_t minimumFractionDigits, UErrorCode* ec);
   163	
   164	
   165	/**
   166	 * Truncates digits from the beginning of the number to the given maximum number of integer digits.
   167	 *
   168	 * This function immediately mutates the inner value.
   169	 *
   170	 * @draft ICU 73
   171	 */
   172	U_CAPI void U_EXPORT2
   173	usnum_truncateStart(USimpleNumber* unumber, int32_t maximumIntegerDigits, UErrorCode* ec);
   174	
   175	
   176	/**
   177	 * Sets the sign of the number: an explicit plus sign, explicit minus sign, or no sign.
   178	 *
   179	 * This setting is applied upon formatting the number.
   180	 *
   181	 * NOTE: This does not support accounting sign notation.
   182	 *
   183	 * @draft ICU 73
   184	 */
   185	U_CAPI void U_EXPORT2
   186	usnum_setSign(USimpleNumber* unumber, USimpleNumberSign sign, UErrorCode* ec);
   187	
   188	
   189	/**
   190	 * Creates a new USimpleNumberFormatter with all locale defaults.
   191	 *
   192	 * @draft ICU 73
   193	 */
   194	U_CAPI USimpleNumberFormatter* U_EXPORT2
   195	usnumf_openForLocale(const char* locale, UErrorCode* ec);
   196	
   197	
   198	/**
   199	 * Creates a new USimpleNumberFormatter, overriding the grouping strategy.
   200	 *
   201	 * @draft ICU 73
   202	 */
   203	U_CAPI USimpleNumberFormatter* U_EXPORT2
   204	usnumf_openForLocaleAndGroupingStrategy(
   205	       const char* locale, UNumberGroupingStrategy groupingStrategy, UErrorCode* ec);
   206	
   207	
   208	/**
   209	 * Formats a number using this SimpleNumberFormatter.
   210	 *
   211	 * The USimpleNumber is cleared after calling this function. It can be re-used via
   212	 * usnum_setToInt64.
   213	 *
   214	 * @draft ICU 73
   215	 */
   216	U_CAPI void U_EXPORT2
   217	usnumf_format(
   218	    const USimpleNumberFormatter* uformatter,
   219	    USimpleNumber* unumber,
   220	    UFormattedNumber* uresult,
   221	    UErrorCode* ec);
   222	
   223	
   224	/**
   225	 * Formats an integer using this SimpleNumberFormatter.
   226	 *
   227	 * For more control over the formatting, use USimpleNumber.
   228	 *
   229	 * @draft ICU 73
   230	 */
   231	U_CAPI void U_EXPORT2
   232	usnumf_formatInt64(
   233	    const USimpleNumberFormatter* uformatter,
   234	    int64_t value,
   235	    UFormattedNumber* uresult,
   236	    UErrorCode* ec);
   237	
   238	
   239	/**
   240	 * Frees the memory held by a USimpleNumber.
   241	 *
   242	 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
   243	 *
   244	 * @draft ICU 73
   245	 */
   246	U_CAPI void U_EXPORT2
   247	usnum_close(USimpleNumber* unumber);
   248	
   249	
   250	/**
   251	 * Frees the memory held by a USimpleNumberFormatter.
   252	 *
   253	 * @draft ICU 73
   254	 */
   255	U_CAPI void U_EXPORT2
   256	usnumf_close(USimpleNumberFormatter* uformatter);
   257	
   258	
   259	#if U_SHOW_CPLUSPLUS_API
   260	U_NAMESPACE_BEGIN
   261	
   262	/**
   263	 * \class LocalUSimpleNumberPointer
   264	 * "Smart pointer" class; closes a USimpleNumber via usnum_close().
   265	 * For most methods see the LocalPointerBase base class.
   266	 *
   267	 * NOTE: Normally, a USimpleNumber should be adopted by usnumf_formatAndAdoptNumber.
   268	 * If you use LocalUSimpleNumberPointer, call `.orphan()` when passing to that function.
   269	 *
   270	 * Usage:
   271	 * <pre>
   272	 * LocalUSimpleNumberPointer uformatter(usnumf_openForInteger(...));
   273	 * // no need to explicitly call usnum_close()
   274	 * </pre>
   275	 *
   276	 * @see LocalPointerBase
   277	 * @see LocalPointer
   278	 * @draft ICU 73
   279	 */
   280	U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberPointer, USimpleNumber, usnum_close);
   281	
   282	/**
   283	 * \class LocalUSimpleNumberFormatterPointer
   284	 * "Smart pointer" class; closes a USimpleNumberFormatter via usnumf_close().
   285	 * For most methods see the LocalPointerBase base class.
   286	 *
   287	 * Usage:
   288	 * <pre>
   289	 * LocalUSimpleNumberFormatterPointer uformatter(usnumf_openForLocale(...));
   290	 * // no need to explicitly call usnumf_close()
   291	 * </pre>
   292	 *
   293	 * @see LocalPointerBase
   294	 * @see LocalPointer
   295	 * @draft ICU 73
   296	 */
   297	U_DEFINE_LOCAL_OPEN_POINTER(LocalUSimpleNumberFormatterPointer, USimpleNumberFormatter, usnumf_close);
   298	
   299	U_NAMESPACE_END
   300	#endif // U_SHOW_CPLUSPLUS_API
   301	
   302	#endif // U_HIDE_DRAFT_API
   303	
   304	#endif /* #if !UCONFIG_NO_FORMATTING */
   305	#endif //__USIMPLENUMBERFORMATTER_H__