java.util.LinkedHashSet Maven / Gradle / Ivy
/*
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below. For
example, no permission is given for you to incorporate this file, in
whole or in part, in an implementation of a Java specification.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative, as opposed to normative, use. The file and any
files generated from it may be used to generate other informative
documentation, such as a unified set of documents of API signatures for
a platform that includes technologies expressed as Java APIs. The file
may also be used to produce "compilation stubs," which allow
applications to be compiled and validated for such platforms.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 219: Foundation
Profile 1.1. In the event of a discrepency between this work and the
JSR 219 specification, which is available at
http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence.
*/
package java.util;
/**
*
Hash table and linked list implementation of the Set interface,
* with predictable iteration order. This implementation differs from
* HashSet in that it maintains a doubly-linked list running through
* all of its entries. This linked list defines the iteration ordering,
* which is the order in which elements were inserted into the set
* (insertion-order). Note that insertion order is not affected
* if an element is re-inserted into the set. (An element e
* is reinserted into a set s if s.add(e) is invoked when
* s.contains(e) would return true immediately prior to
* the invocation.)
*
*
This implementation spares its clients from the unspecified, generally
* chaotic ordering provided by {@link HashSet}, without incurring the
* increased cost associated with {@link TreeSet}. It can be used to
* produce a copy of a set that has the same order as the original, regardless
* of the original set's implementation:
*
* void foo(Set m) {
* Set copy = new LinkedHashSet(m);
* ...
* }
*
* This technique is particularly useful if a module takes a set on input,
* copies it, and later returns results whose order is determined by that of
* the copy. (Clients generally appreciate having things returned in the same
* order they were presented.)
*
* This class provides all of the optional Set operations, and
* permits null elements. Like HashSet, it provides constant-time
* performance for the basic operations (add, contains and
* remove), assuming the the hash function disperses elements
* properly among the buckets. Performance is likely to be just slightly
* below that of HashSet, due to the added expense of maintaining the
* linked list, with one exception: Iteration over a LinkedHashSet
* requires time proportional to the size of the set, regardless of
* its capacity. Iteration over a HashSet is likely to be more
* expensive, requiring time proportional to its capacity.
*
*
A linked hash set has two parameters that affect its performance:
* initial capacity and load factor. They are defined precisely
* as for HashSet. Note, however, that the penalty for choosing an
* excessively high value for initial capacity is less severe for this class
* than for HashSet, as iteration times for this class are unaffected
* by capacity.
*
*
Note that this implementation is not synchronized. If
* multiple threads access a linked hash set concurrently, and at least one of
* the threads modifies the set, it must be synchronized externally.
* This is typically accomplished by synchronizing on some object that
* naturally encapsulates the set. If no such object exists, the set should
* be "wrapped" using the Collections.synchronizedSetmethod. This is
* best done at creation time, to prevent accidental unsynchronized access:
*
* Set s = Collections.synchronizedSet(new LinkedHashSet(...));
*
*
* The iterators returned by the this class's iterator method are
* fail-fast: if the set is modified at any time after the iterator
* is created, in any way except through the iterator's own remove method, the
* iterator will throw a ConcurrentModificationException. Thus, in
* the face of concurrent modification, the Iterator fails quickly and
* cleanly, rather than risking arbitrary, non-deterministic behavior at an
* undetermined time in the future.
*
*
Note that the fail-fast behavior of an iterator cannot be guaranteed
* as it is, generally speaking, impossible to make any hard guarantees in the
* presence of unsynchronized concurrent modification. Fail-fast iterators
* throw ConcurrentModificationException on a best-effort basis.
* Therefore, it would be wrong to write a program that depended on this
* exception for its correctness: the fail-fast behavior of iterators
* should be used only to detect bugs.
*
*
This class is a member of the
*
* Java Collections Framework.
*
* @author Josh Bloch
* @version 1.8 01/20/03
* @see Object#hashCode()
* @see Collection
* @see Set
* @see HashSet
* @see TreeSet
* @see Hashtable
* @since 1.4
*/
public class LinkedHashSet extends HashSet
implements Set, Cloneable, java.io.Serializable
{
/**
* Constructs a new, empty linked hash set with the specified initial
* capacity and load factor.
*
* @param initialCapacity the initial capacity of the linked hash set
* @param loadFactor the load factor of the linked hash set.
* @throws IllegalArgumentException if the initial capacity is less
* than zero, or if the load factor is nonpositive.
*/
public LinkedHashSet(int initialCapacity, float loadFactor) { }
/**
* Constructs a new, empty linked hash set with the specified initial
* capacity and the default load factor (0.75).
*
* @param initialCapacity the initial capacity of the LinkedHashSet.
* @throws IllegalArgumentException if the initial capacity is less
* than zero.
*/
public LinkedHashSet(int initialCapacity) { }
/**
* Constructs a new, empty linked hash set with the default initial
* capacity (16) and load factor (0.75).
*/
public LinkedHashSet() { }
/**
* Constructs a new linked hash set with the same elements as the
* specified collection. The linked hash set is created with an initial
* capacity sufficient to hold the elements in the specified collection
* and the default load factor (0.75).
*
* @param c the collection whose elements are to be placed into
* this set.
* @throws NullPointerException if the specified collection is null.
*/
public LinkedHashSet(Collection c) { }
}