tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

ufieldpositer.h (4513B)

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