Where Online Learning is simpler!

The C and C++ Include Header Files

/usr/include/unicode/uformattednumber.h


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

     1	// © 2022 and later: Unicode, Inc. and others.
     2	// License & terms of use: http://www.unicode.org/copyright.html
     3	
     4	#ifndef __UFORMATTEDNUMBER_H__
     5	#define __UFORMATTEDNUMBER_H__
     6	
     7	#include "unicode/utypes.h"
     8	
     9	#if !UCONFIG_NO_FORMATTING
    10	
    11	#include "unicode/ufieldpositer.h"
    12	#include "unicode/uformattedvalue.h"
    13	#include "unicode/umisc.h"
    14	
    15	/**
    16	 * \file
    17	 * \brief C API: Formatted number result from various number formatting functions.
    18	 *
    19	 * Create a `UFormattedNumber` to hold the result of a number formatting operation. The same
    20	 * `UFormattedNumber` can be reused multiple times.
    21	 *
    22	 * <pre>
    23	 * LocalUFormattedNumberPointer uresult(unumf_openResult(status));
    24	 *
    25	 * // pass uresult.getAlias() to your number formatter
    26	 *
    27	 * int32_t length;
    28	 * const UChar* s = ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), &length, status));
    29	 *
    30	 * // The string result is in `s` with the given `length` (it is also NUL-terminated).
    31	 * </pre>
    32	 */
    33	
    34	
    35	struct UFormattedNumber;
    36	/**
    37	 * C-compatible version of icu::number::FormattedNumber.
    38	 *
    39	 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
    40	 *
    41	 * @stable ICU 62
    42	 */
    43	typedef struct UFormattedNumber UFormattedNumber;
    44	
    45	
    46	/**
    47	 * Creates an object to hold the result of a UNumberFormatter
    48	 * operation. The object can be used repeatedly; it is cleared whenever
    49	 * passed to a format function.
    50	 *
    51	 * @param ec Set if an error occurs.
    52	 * @stable ICU 62
    53	 */
    54	U_CAPI UFormattedNumber* U_EXPORT2
    55	unumf_openResult(UErrorCode* ec);
    56	
    57	
    58	/**
    59	 * Returns a representation of a UFormattedNumber as a UFormattedValue,
    60	 * which can be subsequently passed to any API requiring that type.
    61	 *
    62	 * The returned object is owned by the UFormattedNumber and is valid
    63	 * only as long as the UFormattedNumber is present and unchanged in memory.
    64	 *
    65	 * You can think of this method as a cast between types.
    66	 *
    67	 * @param uresult The object containing the formatted string.
    68	 * @param ec Set if an error occurs.
    69	 * @return A UFormattedValue owned by the input object.
    70	 * @stable ICU 64
    71	 */
    72	U_CAPI const UFormattedValue* U_EXPORT2
    73	unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
    74	
    75	
    76	/**
    77	 * Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.
    78	 * If bufferCapacity is greater than the required length, a terminating NUL is written.
    79	 * If bufferCapacity is less than the required length, an error code is set.
    80	 *
    81	 * Also see ufmtval_getString, which returns a NUL-terminated string:
    82	 *
    83	 *     int32_t len;
    84	 *     const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);
    85	 *
    86	 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
    87	 *
    88	 * @param uresult The object containing the formatted number.
    89	 * @param buffer Where to save the string output.
    90	 * @param bufferCapacity The number of UChars available in the buffer.
    91	 * @param ec Set if an error occurs.
    92	 * @return The required length.
    93	 * @stable ICU 62
    94	 */
    95	U_CAPI int32_t U_EXPORT2
    96	unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
    97	                     UErrorCode* ec);
    98	
    99	
   100	/**
   101	 * Determines the start and end indices of the next occurrence of the given <em>field</em> in the
   102	 * output string. This allows you to determine the locations of, for example, the integer part,
   103	 * fraction part, or symbols.
   104	 *
   105	 * This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}.
   106	 *
   107	 * If a field occurs just once, calling this method will find that occurrence and return it. If a
   108	 * field occurs multiple times, this method may be called repeatedly with the following pattern:
   109	 *
   110	 * <pre>
   111	 * UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0};
   112	 * while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) {
   113	 *   // do something with ufpos.
   114	 * }
   115	 * </pre>
   116	 *
   117	 * This method is useful if you know which field to query. If you want all available field position
   118	 * information, use unumf_resultGetAllFieldPositions().
   119	 *
   120	 * NOTE: All fields of the UFieldPosition must be initialized before calling this method.
   121	 *
   122	 * @param uresult The object containing the formatted number.
   123	 * @param ufpos
   124	 *            Input+output variable. On input, the "field" property determines which field to look up,
   125	 *            and the "endIndex" property determines where to begin the search. On output, the
   126	 *            "beginIndex" field is set to the beginning of the first occurrence of the field after the
   127	 *            input "endIndex", and "endIndex" is set to the end of that occurrence of the field
   128	 *            (exclusive index). If a field position is not found, the FieldPosition is not changed and
   129	 *            the method returns false.
   130	 * @param ec Set if an error occurs.
   131	 * @stable ICU 62
   132	 */
   133	U_CAPI UBool U_EXPORT2
   134	unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
   135	
   136	
   137	/**
   138	 * Populates the given iterator with all fields in the formatted output string. This allows you to
   139	 * determine the locations of the integer part, fraction part, and sign.
   140	 *
   141	 * This is an alternative to the more powerful {@link ufmtval_nextPosition} API.
   142	 *
   143	 * If you need information on only one field, use {@link ufmtval_nextPosition} or
   144	 * {@link unumf_resultNextFieldPosition}.
   145	 *
   146	 * @param uresult The object containing the formatted number.
   147	 * @param ufpositer
   148	 *         A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}. Iteration
   149	 *         information already present in the UFieldPositionIterator is deleted, and the iterator is reset
   150	 *         to apply to the fields in the formatted string created by this function call. The field values
   151	 *         and indexes returned by {@link #ufieldpositer_next} represent fields denoted by
   152	 *         the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot
   153	 *         overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a
   154	 *         grouping separator field for ',' and an integer field encompassing the entire string.
   155	 * @param ec Set if an error occurs.
   156	 * @stable ICU 62
   157	 */
   158	U_CAPI void U_EXPORT2
   159	unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
   160	                                 UErrorCode* ec);
   161	
   162	
   163	/**
   164	 * Extracts the formatted number as a "numeric string" conforming to the
   165	 * syntax defined in the Decimal Arithmetic Specification, available at
   166	 * http://speleotrove.com/decimal
   167	 *
   168	 * This endpoint is useful for obtaining the exact number being printed
   169	 * after scaling and rounding have been applied by the number formatter.
   170	 *
   171	 * @param uresult        The input object containing the formatted number.
   172	 * @param  dest          the 8-bit char buffer into which the decimal number is placed
   173	 * @param  destCapacity  The size, in chars, of the destination buffer.  May be zero
   174	 *                       for precomputing the required size.
   175	 * @param  ec            receives any error status.
   176	 *                       If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for
   177	 *                       preflighting.
   178	 * @return Number of chars in the data.  Does not include a trailing NUL.
   179	 * @stable ICU 68
   180	 */
   181	U_CAPI int32_t U_EXPORT2
   182	unumf_resultToDecimalNumber(
   183	       const UFormattedNumber* uresult,
   184	       char* dest,
   185	       int32_t destCapacity,
   186	       UErrorCode* ec);
   187	
   188	
   189	/**
   190	 * Releases the UFormattedNumber created by unumf_openResult().
   191	 *
   192	 * @param uresult An object created by unumf_openResult().
   193	 * @stable ICU 62
   194	 */
   195	U_CAPI void U_EXPORT2
   196	unumf_closeResult(UFormattedNumber* uresult);
   197	
   198	
   199	#if U_SHOW_CPLUSPLUS_API
   200	U_NAMESPACE_BEGIN
   201	
   202	/**
   203	 * \class LocalUFormattedNumberPointer
   204	 * "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult().
   205	 * For most methods see the LocalPointerBase base class.
   206	 *
   207	 * Usage:
   208	 * <pre>
   209	 * LocalUFormattedNumberPointer uformatter(unumf_openResult(...));
   210	 * // no need to explicitly call unumf_closeResult()
   211	 * </pre>
   212	 *
   213	 * @see LocalPointerBase
   214	 * @see LocalPointer
   215	 * @stable ICU 62
   216	 */
   217	U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
   218	
   219	U_NAMESPACE_END
   220	#endif // U_SHOW_CPLUSPLUS_API
   221	
   222	
   223	#endif /* #if !UCONFIG_NO_FORMATTING */
   224	#endif //__UFORMATTEDNUMBER_H__