1/*
2 * Copyright (C) 2007 Google Inc.
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.
20 *
21 * <h2>Collection Types</h2>
22 *
23 * <dl>
24 * <dt>{@link com.google.common.collect.Multimap}
25 * <dd>A new type, which is similar to {@link java.util.Map}, but may contain
26 *     multiple entries with the same key. Some behaviors of
27 *     {@link com.google.common.collect.Multimap} are left unspecified and are
28 *     provided only by the subtypes mentioned below.
29 *
30 * <dt>{@link com.google.common.collect.SetMultimap}
31 * <dd>An extension of {@link com.google.common.collect.Multimap} which has
32 *     order-independent equality and does not allow duplicate entries; that is,
33 *     while a key may appear twice in a {@code SetMultimap}, each must map to a
34 *     different value.  {@code SetMultimap} takes its name from the fact that
35 *     the {@linkplain com.google.common.collect.SetMultimap#get collection of
36 *     values} associated with a given key fulfills the {@link java.util.Set}
37 *     contract.
38 *
39 * <dt>{@link com.google.common.collect.ListMultimap}
40 * <dd>An extension of {@link com.google.common.collect.Multimap} which permits
41 *     duplicate entries, supports random access of values for a particular key,
42 *     and has <i>partially order-dependent equality</i> as defined by
43 *     {@link com.google.common.collect.ListMultimap#equals(Object)}. {@code
44 *     ListMultimap} takes its name from the fact that the {@linkplain
45 *     com.google.common.collect.ListMultimap#get collection of values}
46 *     associated with a given key fulfills the {@link java.util.List} contract.
47 *
48 * <dt>{@link com.google.common.collect.SortedSetMultimap}
49 * <dd>An extension of {@link com.google.common.collect.SetMultimap} for which
50 *     the {@linkplain com.google.common.collect.SortedSetMultimap#get
51 *     collection values} associated with a given key is a
52 *     {@link java.util.SortedSet}.
53 *
54 * <dt>{@link com.google.common.collect.Multiset}
55 * <dd>An extension of {@link java.util.Collection} that may contain duplicate
56 *     values like a {@link java.util.List}, yet has order-independent equality
57 *     like a {@link java.util.Set}.  One typical use for a multiset is to
58 *     represent a histogram.
59 *
60 * <dt>{@link com.google.common.collect.BiMap}
61 * <dd>An extension of {@link java.util.Map} that guarantees the uniqueness of
62 *     its values as well as that of its keys. This is sometimes called an
63 *     "invertible map," since the restriction on values enables it to support
64 *     an {@linkplain com.google.common.collect.BiMap#inverse inverse view} --
65 *     which is another instance of {@code BiMap}.
66 *
67 * <dt>{@link com.google.common.collect.ClassToInstanceMap}
68 * <dd>An extension of {@link java.util.Map} that associates a raw type with an
69 *     instance of that type.
70 * </dl>
71 *
72 * <h2>Collection Implementations</h2>
73 *
74 * <h3>of {@link java.util.List}</h3>
75 * <dl>
76 * <dt>{@link com.google.common.collect.ImmutableList}
77 * </ul>
78 *
79 * <h3>of {@link java.util.Set}</h3>
80 * <dl>
81 * <dt>{@link com.google.common.collect.ImmutableSet}
82 * </ul>
83 *
84 * <h3>of {@link java.util.SortedSet}</h3>
85 * <dl>
86 * <dt>{@link com.google.common.collect.ImmutableSortedSet}
87 * </dl>
88 *
89 * <h3>of {@link java.util.Map}</h3>
90 * <dl>
91 * <dt>{@link com.google.common.collect.ImmutableMap}
92 * <dt>{@link com.google.common.collect.MapMaker} (produced by)
93 * </ul>
94 *
95 * <h3>of {@link java.util.SortedMap}</h3>
96 * <dl>
97 * <dt>{@link com.google.common.collect.ImmutableSortedMap}
98 * </dl>
99 *
100 * <h3>of {@link com.google.common.collect.Multimap}</h3>
101 * <dl>
102 * <dt>{@link com.google.common.collect.ImmutableMultimap}
103 * <dt>{@link com.google.common.collect.Multimaps#newMultimap}
104 * </dl>
105 *
106 * <h3>of {@link com.google.common.collect.ListMultimap}</h3>
107 * <dl>
108 * <dt>{@link com.google.common.collect.ImmutableListMultimap}
109 * <dt>{@link com.google.common.collect.ArrayListMultimap}
110 * <dt>{@link com.google.common.collect.LinkedListMultimap}
111 * <dt>{@link com.google.common.collect.Multimaps#newListMultimap}
112 * </dl>
113 *
114 * <h3>of {@link com.google.common.collect.SetMultimap}</h3>
115 * <dl>
116 * <dt>{@link com.google.common.collect.ImmutableSetMultimap}
117 * <dt>{@link com.google.common.collect.HashMultimap}
118 * <dt>{@link com.google.common.collect.LinkedHashMultimap}
119 * <dt>{@link com.google.common.collect.TreeMultimap}
120 * <dt>{@link com.google.common.collect.Multimaps#newSetMultimap}
121 * <dt>{@link com.google.common.collect.Multimaps#newSortedSetMultimap}
122 * </dl>
123 *
124 * <h3>of {@link com.google.common.collect.Multiset}</h3>
125 * <dl>
126 * <dt>{@link com.google.common.collect.ImmutableMultiset}
127 * <dt>{@link com.google.common.collect.ConcurrentHashMultiset}
128 * <dt>{@link com.google.common.collect.HashMultiset}
129 * <dt>{@link com.google.common.collect.LinkedHashMultiset}
130 * <dt>{@link com.google.common.collect.TreeMultiset}
131 * <dt>{@link com.google.common.collect.EnumMultiset}
132 * </dl>
133 *
134 * <h3>of {@link com.google.common.collect.BiMap}</h3>
135 * <dl>
136 * <dt>{@link com.google.common.collect.HashBiMap}
137 * <dt>{@link com.google.common.collect.EnumBiMap}
138 * <dt>{@link com.google.common.collect.EnumHashBiMap}
139 * </dl>
140 *
141 * <h3>of {@link com.google.common.collect.ClassToInstanceMap}</h3>
142 * <dl>
143 * <dt>{@link com.google.common.collect.ImmutableClassToInstanceMap}
144 * <dt>{@link com.google.common.collect.MutableClassToInstanceMap}
145 * </dl>
146 *
147 * <h2>Skeletal implementations</h2>
148 * <dl>
149 * <dt>{@link com.google.common.collect.AbstractIterator}
150 * <dt>{@link com.google.common.collect.UnmodifiableIterator}
151 * </dl>
152 *
153 * <h2>Utilities</h2>
154 *
155 * <dl>
156 * <dt>{@link com.google.common.collect.Collections2}
157 * <dt>{@link com.google.common.collect.Iterators}
158 * <dt>{@link com.google.common.collect.Iterables}
159 * <dt>{@link com.google.common.collect.Lists}
160 * <dt>{@link com.google.common.collect.Maps}
161 * <dt>{@link com.google.common.collect.Ordering}
162 * <dt>{@link com.google.common.collect.Sets}
163 * <dt>{@link com.google.common.collect.Multisets}
164 * <dt>{@link com.google.common.collect.Multimaps}
165 * <dt>{@link com.google.common.collect.ObjectArrays}
166 * </dl>
167
168 * <h2>Forwarding collections</h2>
169 *
170 * <dl>
171 * <dt>{@link com.google.common.collect.ForwardingCollection }
172 * <dt>{@link com.google.common.collect.ForwardingConcurrentMap }
173 * <dt>{@link com.google.common.collect.ForwardingIterator }
174 * <dt>{@link com.google.common.collect.ForwardingList }
175 * <dt>{@link com.google.common.collect.ForwardingListIterator }
176 * <dt>{@link com.google.common.collect.ForwardingMap }
177 * <dt>{@link com.google.common.collect.ForwardingMapEntry }
178 * <dt>{@link com.google.common.collect.ForwardingMultimap }
179 * <dt>{@link com.google.common.collect.ForwardingMultiset }
180 * <dt>{@link com.google.common.collect.ForwardingObject }
181 * <dt>{@link com.google.common.collect.ForwardingQueue }
182 * <dt>{@link com.google.common.collect.ForwardingSet }
183 * <dt>{@link com.google.common.collect.ForwardingSortedMap }
184 * <dt>{@link com.google.common.collect.ForwardingSortedSet }
185 * </dl>
186 */
187@javax.annotation.ParametersAreNonnullByDefault
188package com.google.common.collect;
189