icuSources/i18n/unicode/ufieldpositer.h

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