1 /*

     2  * Copyright (c) 2017, 2017, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 package org.graalvm.collections;

    26 

    27 import java.util.Iterator;

    28 

    29 /**

    30  * Memory efficient set data structure.

    31  *

    32  * @since 1.0

    33  */

    34 public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {

    35 

    36     /**

    37      * Adds {@code element} to this set if it is not already present.

    38      *

    39      * @return {@code true} if this set did not already contain {@code element}.

    40      * @since 1.0

    41      */

    42     boolean add(E element);

    43 

    44     /**

    45      * Removes {@code element} from this set if it is present. This set will not contain

    46      * {@code element} once the call returns.

    47      *

    48      * @since 1.0

    49      */

    50     void remove(E element);

    51 

    52     /**

    53      * Removes all of the elements from this set. The set will be empty after this call returns.

    54      *

    55      * @since 1.0

    56      */

    57     void clear();

    58 

    59     /**

    60      * Adds all of the elements in {@code other} to this set if they're not already present.

    61      *

    62      * @since 1.0

    63      */

    64     default void addAll(EconomicSet<E> other) {

    65         addAll(other.iterator());

    66     }

    67 

    68     /**

    69      * Adds all of the elements in {@code values} to this set if they're not already present.

    70      *

    71      * @since 1.0

    72      */

    73     default void addAll(Iterable<E> values) {

    74         addAll(values.iterator());

    75     }

    76 

    77     /**

    78      * Adds all of the elements enumerated by {@code iterator} to this set if they're not already

    79      * present.

    80      *

    81      * @since 1.0

    82      */

    83     default void addAll(Iterator<E> iterator) {

    84         while (iterator.hasNext()) {

    85             add(iterator.next());

    86         }

    87     }

    88 

    89     /**

    90      * Removes from this set all of its elements that are contained in {@code other}.

    91      *

    92      * @since 1.0

    93      */

    94     default void removeAll(EconomicSet<E> other) {

    95         removeAll(other.iterator());

    96     }

    97 

    98     /**

    99      * Removes from this set all of its elements that are contained in {@code values}.

   100      *

   101      * @since 1.0

   102      */

   103     default void removeAll(Iterable<E> values) {

   104         removeAll(values.iterator());

   105     }

   106 

   107     /**

   108      * Removes from this set all of its elements that are enumerated by {@code iterator}.

   109      *

   110      * @since 1.0

   111      */

   112     default void removeAll(Iterator<E> iterator) {

   113         while (iterator.hasNext()) {

   114             remove(iterator.next());

   115         }

   116     }

   117 

   118     /**

   119      * Removes from this set all of its elements that are not contained in {@code other}.

   120      *

   121      * @since 1.0

   122      */

   123     default void retainAll(EconomicSet<E> other) {

   124         Iterator<E> iterator = iterator();

   125         while (iterator.hasNext()) {

   126             E key = iterator.next();

   127             if (!other.contains(key)) {

   128                 iterator.remove();

   129             }

   130         }

   131     }

   132 

   133     /**

   134      * Creates a new set guaranteeing insertion order when iterating over its elements with the

   135      * default {@link Equivalence#DEFAULT} comparison strategy.

   136      *

   137      * @since 1.0

   138      */

   139     static <E> EconomicSet<E> create() {

   140         return EconomicSet.create(Equivalence.DEFAULT);

   141     }

   142 

   143     /**

   144      * Creates a new set guaranteeing insertion order when iterating over its elements.

   145      *

   146      * @since 1.0

   147      */

   148     static <E> EconomicSet<E> create(Equivalence strategy) {

   149         return EconomicMapImpl.create(strategy, true);

   150     }

   151 

   152     /**

   153      * Creates a new set guaranteeing insertion order when iterating over its elements with the

   154      * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the

   155      * specified collection.

   156      *

   157      * @since 1.0

   158      */

   159     static <E> EconomicSet<E> create(int initialCapacity) {

   160         return EconomicSet.create(Equivalence.DEFAULT, initialCapacity);

   161     }

   162 

   163     /**

   164      * Creates a new set guaranteeing insertion order when iterating over its elements with the

   165      * default {@link Equivalence#DEFAULT} comparison strategy and inserts all elements of the

   166      * specified collection.

   167      *

   168      * @since 1.0

   169      */

   170     static <E> EconomicSet<E> create(UnmodifiableEconomicSet<E> c) {

   171         return EconomicSet.create(Equivalence.DEFAULT, c);

   172     }

   173 

   174     /**

   175      * Creates a new set guaranteeing insertion order when iterating over its elements and

   176      * initializes with the given capacity.

   177      *

   178      * @since 1.0

   179      */

   180     static <E> EconomicSet<E> create(Equivalence strategy, int initialCapacity) {

   181         return EconomicMapImpl.create(strategy, initialCapacity, true);

   182     }

   183 

   184     /**

   185      * Creates a new set guaranteeing insertion order when iterating over its elements and inserts

   186      * all elements of the specified collection.

   187      *

   188      * @since 1.0

   189      */

   190     static <E> EconomicSet<E> create(Equivalence strategy, UnmodifiableEconomicSet<E> c) {

   191         return EconomicMapImpl.create(strategy, c, true);

   192     }

   193 }