icuSources/i18n/unicode/ufieldpositer.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *****************************************************************************************
   5 * Copyright (C) 2015-2016, International Business Machines
   6 * Corporation and others. All Rights Reserved.
   7 *****************************************************************************************
   8 */
   9
  10 #ifndef UFIELDPOSITER_H
  11 #define UFIELDPOSITER_H
  12
  13 #include "unicode/utypes.h"
  14
  15 #if !UCONFIG_NO_FORMATTING
  16
  17 #include "unicode/localpointer.h"
  18
  19 /**
  20  * \file
  21  * \brief C API: UFieldPositionIterator for use with format APIs.
  22  *
  23  * Usage:
  24  * ufieldpositer_open creates an empty (unset) UFieldPositionIterator.
  25  * This can be passed to format functions such as {@link #udat_formatForFields},
  26  * which will set it to apply to the fields in a particular formatted string.
  27  * ufieldpositer_next can then be used to iterate over those fields,
  28  * providing for each field its type (using values that are specific to the
  29  * particular format type, such as date or number formats), as well as the
  30  * start and end positions of the field in the formatted string.
  31  * A given UFieldPositionIterator can be re-used for different format calls;
  32  * each such call resets it to apply to that format string.
  33  * ufieldpositer_close should be called to dispose of the UFieldPositionIterator
  34  * when it is no longer needed.
  35  *
  36  * @see FieldPositionIterator
  37  */
  38
  39 /**
  40  * Opaque UFieldPositionIterator object for use in C.
  41  * @stable ICU 55
  42  */
  43 struct UFieldPositionIterator;
  44 typedef struct UFieldPositionIterator UFieldPositionIterator;  /**< C typedef for struct UFieldPositionIterator. @stable ICU 55 */
  45
  46 /**
  47  * Open a new, unset UFieldPositionIterator object.
  48  * @param status
  49  *          A pointer to a UErrorCode to receive any errors.
  50  * @return
  51  *          A pointer to an empty (unset) UFieldPositionIterator object,
  52  *          or NULL if an error occurred.
  53  * @stable ICU 55
  54  */
  55 U_STABLE UFieldPositionIterator* U_EXPORT2
  56 ufieldpositer_open(UErrorCode* status);
  57
  58 /**
  59  * Close a UFieldPositionIterator object. Once closed it may no longer be used.
  60  * @param fpositer
  61  *          A pointer to the UFieldPositionIterator object to close.
  62  * @stable ICU 55
  63  */
  64 U_STABLE void U_EXPORT2
  65 ufieldpositer_close(UFieldPositionIterator *fpositer);
  66
  67
  68 #if U_SHOW_CPLUSPLUS_API
  69
  70 U_NAMESPACE_BEGIN
  71
  72 /**
  73  * \class LocalUFieldPositionIteratorPointer
  74  * "Smart pointer" class, closes a UFieldPositionIterator via ufieldpositer_close().
  75  * For most methods see the LocalPointerBase base class.
  76  *
  77  * @see LocalPointerBase
  78  * @see LocalPointer
  79  * @stable ICU 55
  80  */
  81 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFieldPositionIteratorPointer, UFieldPositionIterator, ufieldpositer_close);
  82
  83 U_NAMESPACE_END
  84
  85 #endif // U_SHOW_CPLUSPLUS_API
  86
  87 /**
  88  * Get information for the next field in the formatted string to which this
  89  * UFieldPositionIterator currently applies, or return a negative value if there
  90  * are no more fields.
  91  * @param fpositer
  92  *          A pointer to the UFieldPositionIterator object containing iteration
  93  *          state for the format fields.
  94  * @param beginIndex
  95  *          A pointer to an int32_t to receive information about the start offset
  96  *          of the field in the formatted string (undefined if the function
  97  *          returns a negative value). May be NULL if this information is not needed.
  98  * @param endIndex
  99  *          A pointer to an int32_t to receive information about the end offset
 100  *          of the field in the formatted string (undefined if the function
 101  *          returns a negative value). May be NULL if this information is not needed.
 102  * @return
 103  *          The field type (non-negative value), or a negative value if there are
 104  *          no more fields for which to provide information. If negative, then any
 105  *          values pointed to by beginIndex and endIndex are undefined.
 106  *
 107  *          The values for field type depend on what type of formatter the
 108  *          UFieldPositionIterator has been set by; for a date formatter, the
 109  *          values from the UDateFormatField enum. For more information, see the
 110  *          descriptions of format functions that take a UFieldPositionIterator*
 111  *          parameter, such as {@link #udat_formatForFields}.
 112  *
 113  * @stable ICU 55
 114  */
 115 U_STABLE int32_t U_EXPORT2
 116 ufieldpositer_next(UFieldPositionIterator *fpositer,
 117                    int32_t *beginIndex, int32_t *endIndex);
 118
 119 #endif /* #if !UCONFIG_NO_FORMATTING */
 120
 121 #endif