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 188 package com.google.common.collect; 189
