github.com/searKing/golang/go@v1.2.74/util/spliterator/characteristic.go (about)

     1  // Copyright 2020 The searKing Author. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package spliterator
     6  
     7  type Characteristic int
     8  
     9  const (
    10  	CharacteristicTODO Characteristic = 0x00000000
    11  	/**
    12  	 * Characteristic value signifying that an encounter order is defined for
    13  	 * elements. If so, this Spliterator guarantees that method
    14  	 * {@link #trySplit} splits a strict prefix of elements, that method
    15  	 * {@link #tryAdvance} steps by one element in prefix order, and that
    16  	 * {@link #forEachRemaining} performs actions in encounter order.
    17  	 *
    18  	 * <p>A {@link Collection} has an encounter order if the corresponding
    19  	 * {@link Collection#iterator} documents an order. If so, the encounter
    20  	 * order is the same as the documented order. Otherwise, a collection does
    21  	 * not have an encounter order.
    22  	 *
    23  	 * @apiNote Encounter order is guaranteed to be ascending index order for
    24  	 * any {@link List}. But no order is guaranteed for hash-based collections
    25  	 * such as {@link HashSet}. Clients of a Spliterator that reports
    26  	 * {@code ORDERED} are expected to preserve ordering constraints in
    27  	 * non-commutative parallel computations.
    28  	 */
    29  	CharacteristicOrdered Characteristic = 0x00000010
    30  
    31  	/**
    32  	 * Characteristic value signifying that, for each pair of
    33  	 * encountered elements {@code x, y}, {@code !x.equals(y)}. This
    34  	 * applies for example, to a Spliterator based on a {@link Set}.
    35  	 */
    36  	CharacteristicDistinct Characteristic = 0x00000001
    37  
    38  	/**
    39  	 * Characteristic value signifying that encounter order follows a defined
    40  	 * sort order. If so, method {@link #getComparator()} returns the associated
    41  	 * Comparator, or {@code null} if all elements are {@link Comparable} and
    42  	 * are sorted by their natural ordering.
    43  	 *
    44  	 * <p>A Spliterator that reports {@code SORTED} must also report
    45  	 * {@code ORDERED}.
    46  	 *
    47  	 * @apiNote The spliterators for {@code Collection} classes in the JDK that
    48  	 * implement {@link NavigableSet} or {@link SortedSet} report {@code SORTED}.
    49  	 */
    50  	CharacteristicSorted Characteristic = 0x00000004
    51  
    52  	/**
    53  	 * Characteristic value signifying that the value returned from
    54  	 * {@code estimateSize()} prior to traversal or splitting represents a
    55  	 * finite size that, in the absence of structural source modification,
    56  	 * represents an exact count of the number of elements that would be
    57  	 * encountered by a complete traversal.
    58  	 *
    59  	 * @apiNote Most Spliterators for Collections, that cover all elements of a
    60  	 * {@code Collection} report this characteristic. Sub-spliterators, such as
    61  	 * those for {@link HashSet}, that cover a sub-set of elements and
    62  	 * approximate their reported size do not.
    63  	 */
    64  	CharacteristicSized Characteristic = 0x00000040
    65  
    66  	/**
    67  	 * Characteristic value signifying that the source guarantees that
    68  	 * encountered elements will not be {@code null}. (This applies,
    69  	 * for example, to most concurrent collections, queues, and maps.)
    70  	 */
    71  	CharacteristicNonnulL Characteristic = 0x00000100
    72  
    73  	/**
    74  	 * Characteristic value signifying that the element source cannot be
    75  	 * structurally modified; that is, elements cannot be added, replaced, or
    76  	 * removed, so such changes cannot occur during traversal. A Spliterator
    77  	 * that does not report {@code IMMUTABLE} or {@code CONCURRENT} is expected
    78  	 * to have a documented policy (for example throwing
    79  	 * {@link ConcurrentModificationException}) concerning structural
    80  	 * interference detected during traversal.
    81  	 */
    82  	CharacteristicImmutable Characteristic = 0x00000400
    83  
    84  	/**
    85  	 * Characteristic value signifying that the element source may be safely
    86  	 * concurrently modified (allowing additions, replacements, and/or removals)
    87  	 * by multiple threads without external synchronization. If so, the
    88  	 * Spliterator is expected to have a documented policy concerning the impact
    89  	 * of modifications during traversal.
    90  	 *
    91  	 * <p>A top-level Spliterator should not report both {@code CONCURRENT} and
    92  	 * {@code SpliteratorSIZED}, since the finite size, if known, may change if the source
    93  	 * is concurrently modified during traversal. Such a Spliterator is
    94  	 * inconsistent and no guarantees can be made about any computation using
    95  	 * that Spliterator. Sub-spliterators may report {@code SpliteratorSIZED} if the
    96  	 * sub-split size is known and additions or removals to the source are not
    97  	 * reflected when traversing.
    98  	 *
    99  	 * <p>A top-level Spliterator should not report both {@code CONCURRENT} and
   100  	 * {@code IMMUTABLE}, since they are mutually exclusive. Such a Spliterator
   101  	 * is inconsistent and no guarantees can be made about any computation using
   102  	 * that Spliterator. Sub-spliterators may report {@code IMMUTABLE} if
   103  	 * additions or removals to the source are not reflected when traversing.
   104  	 *
   105  	 * @apiNote Most concurrent collections maintain a consistency policy
   106  	 * guaranteeing accuracy with respect to elements present at the point of
   107  	 * Spliterator construction, but possibly not reflecting subsequent
   108  	 * additions or removals.
   109  	 */
   110  	CharacteristicConcurrent Characteristic = 0x00001000
   111  
   112  	/**
   113  	 * Characteristic value signifying that all Spliterators resulting from
   114  	 * {@code trySplit()} will be both {@link #SpliteratorSIZED} and {@link #SUBSIZED}.
   115  	 * (This means that all child Spliterators, whether direct or indirect, will
   116  	 * be {@code SpliteratorSIZED}.)
   117  	 *
   118  	 * <p>A Spliterator that does not report {@code SpliteratorSIZED} as required by
   119  	 * {@code SUBSIZED} is inconsistent and no guarantees can be made about any
   120  	 * computation using that Spliterator.
   121  	 *
   122  	 * @apiNote Some spliterators, such as the top-level spliterator for an
   123  	 * approximately balanced binary tree, will report {@code SpliteratorSIZED} but not
   124  	 * {@code SUBSIZED}, since it is common to know the size of the entire tree
   125  	 * but not the exact sizes of subtrees.
   126  	 */
   127  	CharacteristicSubsized Characteristic = 0x00004000
   128  )