ICU-66108.tar.gz

[apple/icu.git] / icuSources / common / unicode / uset.h

diff --git a/icuSources/common/unicode/uset.h b/icuSources/common/unicode/uset.h
index 40510cd4167c8f77d50661dfff7fe09b9ef80532..18482c10e738443f46eeaf47df65381dc7d8abb5 100644 (file)
--- a/icuSources/common/unicode/uset.h
+++ b/icuSources/common/unicode/uset.h
@@ -1,12 +1,14 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 *******************************************************************************
 *
-*   Copyright (C) 2002-2012, International Business Machines
+*   Copyright (C) 2002-2014, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 *
 *******************************************************************************
 *   file name:  uset.h
-*   encoding:   US-ASCII
+*   encoding:   UTF-8
 *   tab size:   8 (not used)
 *   indentation:4
 *
@@ -31,10 +33,14 @@
 #include "unicode/uchar.h"
 #include "unicode/localpointer.h"
 
-#ifndef UCNV_H
-struct USet;
+#ifndef USET_DEFINED
+
+#ifndef U_IN_DOXYGEN
+#define USET_DEFINED
+#endif
 /**
- * A UnicodeSet.  Use the uset_* API to manipulate.  Create with
+ * USet is the C API type corresponding to C++ class UnicodeSet.
+ * Use the uset_* API to manipulate.  Create with
  * uset_open*, and destroy with uset_close.
  * @stable ICU 2.4
  */
@@ -98,8 +104,8 @@ enum {
  *
  * The functionality is straightforward for sets with only single code points,
  * without strings (which is the common case):
- * - USET_SPAN_CONTAINED and USET_SPAN_SIMPLE
- *   work the same.
+ * - USET_SPAN_CONTAINED and USET_SPAN_SIMPLE work the same.
+ * - USET_SPAN_CONTAINED and USET_SPAN_SIMPLE are inverses of USET_SPAN_NOT_CONTAINED.
  * - span() and spanBack() partition any string the same way when
  *   alternating between span(USET_SPAN_NOT_CONTAINED) and
  *   span(either "contained" condition).
@@ -149,7 +155,8 @@ enum {
  */
 typedef enum USetSpanCondition {
     /**
-     * Continue a span() while there is no set element at the current position.
+     * Continues a span() while there is no set element at the current position.
+     * Increments by one code point at a time.
      * Stops before the first set element (character or string).
      * (For code points only, this is like while contains(current)==FALSE).
      *
@@ -161,22 +168,23 @@ typedef enum USetSpanCondition {
      */
     USET_SPAN_NOT_CONTAINED = 0,
     /**
-     * Continue a span() while there is a set element at the current position.
+     * Spans the longest substring that is a concatenation of set elements (characters or strings).
      * (For characters only, this is like while contains(current)==TRUE).
      *
      * When span() returns, the substring between where it started and the position
      * it returned consists only of set elements (characters or strings) that are in the set.
      *
-     * If a set contains strings, then the span will be the longest substring
-     * matching any of the possible concatenations of set elements (characters or strings).
-     * (There must be a single, non-overlapping concatenation of characters or strings.)
-     * This is equivalent to a POSIX regular expression for (OR of each set element)*.
+     * If a set contains strings, then the span will be the longest substring for which there
+     * exists at least one non-overlapping concatenation of set elements (characters or strings).
+     * This is equivalent to a POSIX regular expression for <code>(OR of each set element)*</code>.
+     * (Java/ICU/Perl regex stops at the first match of an OR.)
      *
      * @stable ICU 3.8
      */
     USET_SPAN_CONTAINED = 1,
     /**
-     * Continue a span() while there is a set element at the current position.
+     * Continues a span() while there is a set element at the current position.
+     * Increments by the longest matching element at each position.
      * (For characters only, this is like while contains(current)==TRUE).
      *
      * When span() returns, the substring between where it started and the position
@@ -194,11 +202,13 @@ typedef enum USetSpanCondition {
      * @stable ICU 3.8
      */
     USET_SPAN_SIMPLE = 2,
+#ifndef U_HIDE_DEPRECATED_API
     /**
      * One more than the last span condition.
-     * @stable ICU 3.8
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
      */
     USET_SPAN_CONDITION_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } USetSpanCondition;
 
 enum {