1/*
2 * Copyright (C) 2007 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17/**
18 * This package contains generic collection interfaces and implementations, and
19 * other utilities for working with collections. It is a part of the open-source
20 * <a href="http://guava-libraries.googlecode.com">Guava libraries</a>.
21 *
22 * <h2>Collection Types</h2>
23 *
24 * <dl>
25 * <dt>{@link com.google.common.collect.BiMap}
26 * <dd>An extension of {@link java.util.Map} that guarantees the uniqueness of
27 *     its values as well as that of its keys. This is sometimes called an
28 *     "invertible map," since the restriction on values enables it to support
29 *     an {@linkplain com.google.common.collect.BiMap#inverse inverse view} --
30 *     which is another instance of {@code BiMap}.
31 *
32 * <dt>{@link com.google.common.collect.Multiset}
33 * <dd>An extension of {@link java.util.Collection} that may contain duplicate
34 *     values like a {@link java.util.List}, yet has order-independent equality
35 *     like a {@link java.util.Set}.  One typical use for a multiset is to
36 *     represent a histogram.
37 *
38 * <dt>{@link com.google.common.collect.Multimap}
39 * <dd>A new type, which is similar to {@link java.util.Map}, but may contain
40 *     multiple entries with the same key. Some behaviors of
41 *     {@link com.google.common.collect.Multimap} are left unspecified and are
42 *     provided only by the subtypes mentioned below.
43 *
44 * <dt>{@link com.google.common.collect.ListMultimap}
45 * <dd>An extension of {@link com.google.common.collect.Multimap} which permits
46 *     duplicate entries, supports random access of values for a particular key,
47 *     and has <i>partially order-dependent equality</i> as defined by
48 *     {@link com.google.common.collect.ListMultimap#equals(Object)}. {@code
49 *     ListMultimap} takes its name from the fact that the {@linkplain
50 *     com.google.common.collect.ListMultimap#get collection of values}
51 *     associated with a given key fulfills the {@link java.util.List} contract.
52 *
53 * <dt>{@link com.google.common.collect.SetMultimap}
54 * <dd>An extension of {@link com.google.common.collect.Multimap} which has
55 *     order-independent equality and does not allow duplicate entries; that is,
56 *     while a key may appear twice in a {@code SetMultimap}, each must map to a
57 *     different value.  {@code SetMultimap} takes its name from the fact that
58 *     the {@linkplain com.google.common.collect.SetMultimap#get collection of
59 *     values} associated with a given key fulfills the {@link java.util.Set}
60 *     contract.
61 *
62 * <dt>{@link com.google.common.collect.SortedSetMultimap}
63 * <dd>An extension of {@link com.google.common.collect.SetMultimap} for which
64 *     the {@linkplain com.google.common.collect.SortedSetMultimap#get
65 *     collection values} associated with a given key is a
66 *     {@link java.util.SortedSet}.
67 *
68 * <dt>{@link com.google.common.collect.Table}
69 * <dd>A new type, which is similar to {@link java.util.Map}, but which indexes
70 *     its values by an ordered pair of keys, a row key and column key.
71 *
72 * <dt>{@link com.google.common.collect.ClassToInstanceMap}
73 * <dd>An extension of {@link java.util.Map} that associates a raw type with an
74 *     instance of that type.
75 * </dl>
76 *
77 * <h2>Collection Implementations</h2>
78 *
79 * <h3>of {@link java.util.List}</h3>
80 * <ul>
81 * <li>{@link com.google.common.collect.ImmutableList}
82 * </ul>
83 *
84 * <h3>of {@link java.util.Set}</h3>
85 * <ul>
86 * <li>{@link com.google.common.collect.ImmutableSet}
87 * <li>{@link com.google.common.collect.ImmutableSortedSet}
88 * <li>{@link com.google.common.collect.ContiguousSet} (see {@code Ranges})
89 * </ul>
90 *
91 * <h3>of {@link java.util.Map}</h3>
92 * <ul>
93 * <li>{@link com.google.common.collect.ImmutableMap}
94 * <li>{@link com.google.common.collect.ImmutableSortedMap}
95 * <li>{@link com.google.common.collect.MapMaker}
96 * </ul>
97 *
98 * <h3>of {@link com.google.common.collect.BiMap}</h3>
99 * <ul>
100 * <li>{@link com.google.common.collect.ImmutableBiMap}
101 * <li>{@link com.google.common.collect.HashBiMap}
102 * <li>{@link com.google.common.collect.EnumBiMap}
103 * <li>{@link com.google.common.collect.EnumHashBiMap}
104 * </ul>
105 *
106 * <h3>of {@link com.google.common.collect.Multiset}</h3>
107 * <ul>
108 * <li>{@link com.google.common.collect.ImmutableMultiset}
109 * <li>{@link com.google.common.collect.HashMultiset}
110 * <li>{@link com.google.common.collect.LinkedHashMultiset}
111 * <li>{@link com.google.common.collect.TreeMultiset}
112 * <li>{@link com.google.common.collect.EnumMultiset}
113 * <li>{@link com.google.common.collect.ConcurrentHashMultiset}
114 * </ul>
115 *
116 * <h3>of {@link com.google.common.collect.Multimap}</h3>
117 * <ul>
118 * <li>{@link com.google.common.collect.ImmutableMultimap}
119 * <li>{@link com.google.common.collect.ImmutableListMultimap}
120 * <li>{@link com.google.common.collect.ImmutableSetMultimap}
121 * <li>{@link com.google.common.collect.ArrayListMultimap}
122 * <li>{@link com.google.common.collect.HashMultimap}
123 * <li>{@link com.google.common.collect.TreeMultimap}
124 * <li>{@link com.google.common.collect.LinkedHashMultimap}
125 * <li>{@link com.google.common.collect.LinkedListMultimap}
126 * </ul>
127 *
128 * <h3>of {@link com.google.common.collect.Table}</h3>
129 * <ul>
130 * <li>{@link com.google.common.collect.ImmutableTable}
131 * <li>{@link com.google.common.collect.ArrayTable}
132 * <li>{@link com.google.common.collect.HashBasedTable}
133 * <li>{@link com.google.common.collect.TreeBasedTable}
134 * </ul>
135 *
136 * <h3>of {@link com.google.common.collect.ClassToInstanceMap}</h3>
137 * <ul>
138 * <li>{@link com.google.common.collect.ImmutableClassToInstanceMap}
139 * <li>{@link com.google.common.collect.MutableClassToInstanceMap}
140 * </ul>
141 *
142 * <h2>Classes of static utility methods</h2>
143 *
144 * <ul>
145 * <li>{@link com.google.common.collect.Collections2}
146 * <li>{@link com.google.common.collect.Iterators}
147 * <li>{@link com.google.common.collect.Iterables}
148 * <li>{@link com.google.common.collect.Lists}
149 * <li>{@link com.google.common.collect.Maps}
150 * <li>{@link com.google.common.collect.Sets}
151 * <li>{@link com.google.common.collect.Multisets}
152 * <li>{@link com.google.common.collect.Multimaps}
153 * <li>{@link com.google.common.collect.SortedMaps}
154 * <li>{@link com.google.common.collect.Tables}
155 * <li>{@link com.google.common.collect.ObjectArrays}
156 * </ul>
157 *
158 * <h2>Comparison</h2>
159 *
160 * <ul>
161 * <li>{@link com.google.common.collect.Ordering}
162 * <li>{@link com.google.common.collect.ComparisonChain}
163 * </ul>
164 *
165 * <h2>Abstract implementations</h2>
166 *
167 * <ul>
168 * <li>{@link com.google.common.collect.AbstractIterator}
169 * <li>{@link com.google.common.collect.AbstractLinkedIterator}
170 * <li>{@link com.google.common.collect.ImmutableCollection}
171 * <li>{@link com.google.common.collect.UnmodifiableIterator}
172 * <li>{@link com.google.common.collect.UnmodifiableListIterator}
173 * </ul>
174 *
175 * <h2>Ranges</h2>
176 *
177 * <ul>
178 * <li>{@link com.google.common.collect.Range}
179 * <li>{@link com.google.common.collect.Ranges}
180 * <li>{@link com.google.common.collect.DiscreteDomain}
181 * <li>{@link com.google.common.collect.DiscreteDomains}
182 * <li>{@link com.google.common.collect.ContiguousSet}
183 * </ul>
184 *
185 * <h2>Other</h2>
186 *
187 * <ul>
188 * <li>{@link com.google.common.collect.Interner},
189 *     {@link com.google.common.collect.Interners}
190 * <li>{@link com.google.common.collect.Constraint},
191 *     {@link com.google.common.collect.Constraints}
192 * <li>{@link com.google.common.collect.MapConstraint},
193 *     {@link com.google.common.collect.MapConstraints}
194 * <li>{@link com.google.common.collect.MapDifference},
195 *     {@link com.google.common.collect.SortedMapDifference}
196 * <li>{@link com.google.common.collect.MinMaxPriorityQueue}
197 * <li>{@link com.google.common.collect.PeekingIterator}
198 * </ul>
199 *
200 * <h2>Forwarding collections</h2>
201 *
202 * <ul>
203 * <li>{@link com.google.common.collect.ForwardingCollection}
204 * <li>{@link com.google.common.collect.ForwardingConcurrentMap}
205 * <li>{@link com.google.common.collect.ForwardingIterator}
206 * <li>{@link com.google.common.collect.ForwardingList}
207 * <li>{@link com.google.common.collect.ForwardingListIterator}
208 * <li>{@link com.google.common.collect.ForwardingListMultimap}
209 * <li>{@link com.google.common.collect.ForwardingMap}
210 * <li>{@link com.google.common.collect.ForwardingMapEntry}
211 * <li>{@link com.google.common.collect.ForwardingMultimap}
212 * <li>{@link com.google.common.collect.ForwardingMultiset}
213 * <li>{@link com.google.common.collect.ForwardingObject}
214 * <li>{@link com.google.common.collect.ForwardingQueue}
215 * <li>{@link com.google.common.collect.ForwardingSet}
216 * <li>{@link com.google.common.collect.ForwardingSetMultimap}
217 * <li>{@link com.google.common.collect.ForwardingSortedMap}
218 * <li>{@link com.google.common.collect.ForwardingSortedMultiset}
219 * <li>{@link com.google.common.collect.ForwardingSortedSet}
220 * <li>{@link com.google.common.collect.ForwardingSortedSetMultimap}
221 * <li>{@link com.google.common.collect.ForwardingTable}
222 * </ul>
223 */
224@javax.annotation.ParametersAreNonnullByDefault
225package com.google.common.collect;
226