Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ufieldpositer.h @ 69:33d812a61356

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