001/*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the
010 * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
011 * express or implied. See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014
015package com.google.common.collect;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019
020import com.google.common.annotations.GwtIncompatible;
021import com.google.common.annotations.J2ktIncompatible;
022import com.google.errorprone.annotations.CanIgnoreReturnValue;
023import com.google.errorprone.annotations.DoNotCall;
024import com.google.errorprone.annotations.concurrent.LazyInit;
025import java.io.InvalidObjectException;
026import java.io.ObjectInputStream;
027import java.io.Serializable;
028import java.util.Arrays;
029import java.util.Collection;
030import java.util.Collections;
031import java.util.Comparator;
032import java.util.Iterator;
033import java.util.List;
034import java.util.function.Function;
035import java.util.function.ToIntFunction;
036import java.util.stream.Collector;
037import javax.annotation.CheckForNull;
038import org.checkerframework.checker.nullness.qual.Nullable;
039
040/**
041 * A {@link SortedMultiset} whose contents will never change, with many other important properties
042 * detailed at {@link ImmutableCollection}.
043 *
044 * <p><b>Warning:</b> as with any sorted collection, you are strongly advised not to use a {@link
045 * Comparator} or {@link Comparable} type whose comparison behavior is <i>inconsistent with
046 * equals</i>. That is, {@code a.compareTo(b)} or {@code comparator.compare(a, b)} should equal zero
047 * <i>if and only if</i> {@code a.equals(b)}. If this advice is not followed, the resulting
048 * collection will not correctly obey its specification.
049 *
050 * <p>See the Guava User Guide article on <a href=
051 * "https://github.com/google/guava/wiki/ImmutableCollectionsExplained">immutable collections</a>.
052 *
053 * @author Louis Wasserman
054 * @since 12.0
055 */
056@GwtIncompatible // hasn't been tested yet
057public abstract class ImmutableSortedMultiset<E> extends ImmutableMultiset<E>
058    implements SortedMultiset<E> {
059  // TODO(lowasser): GWT compatibility
060
061  /**
062   * Returns a {@code Collector} that accumulates the input elements into a new {@code
063   * ImmutableMultiset}. Elements are sorted by the specified comparator.
064   *
065   * <p><b>Warning:</b> {@code comparator} should be <i>consistent with {@code equals}</i> as
066   * explained in the {@link Comparator} documentation.
067   *
068   * @since 21.0
069   */
070  public static <E> Collector<E, ?, ImmutableSortedMultiset<E>> toImmutableSortedMultiset(
071      Comparator<? super E> comparator) {
072    return toImmutableSortedMultiset(comparator, Function.identity(), e -> 1);
073  }
074
075  /**
076   * Returns a {@code Collector} that accumulates elements into an {@code ImmutableSortedMultiset}
077   * whose elements are the result of applying {@code elementFunction} to the inputs, with counts
078   * equal to the result of applying {@code countFunction} to the inputs.
079   *
080   * <p>If the mapped elements contain duplicates (according to {@code comparator}), the first
081   * occurrence in encounter order appears in the resulting multiset, with count equal to the sum of
082   * the outputs of {@code countFunction.applyAsInt(t)} for each {@code t} mapped to that element.
083   *
084   * @since 22.0
085   */
086  public static <T extends @Nullable Object, E>
087      Collector<T, ?, ImmutableSortedMultiset<E>> toImmutableSortedMultiset(
088          Comparator<? super E> comparator,
089          Function<? super T, ? extends E> elementFunction,
090          ToIntFunction<? super T> countFunction) {
091    checkNotNull(comparator);
092    checkNotNull(elementFunction);
093    checkNotNull(countFunction);
094    return Collector.of(
095        () -> TreeMultiset.create(comparator),
096        (multiset, t) ->
097            multiset.add(checkNotNull(elementFunction.apply(t)), countFunction.applyAsInt(t)),
098        (multiset1, multiset2) -> {
099          multiset1.addAll(multiset2);
100          return multiset1;
101        },
102        (Multiset<E> multiset) -> copyOfSortedEntries(comparator, multiset.entrySet()));
103  }
104
105  /**
106   * Returns the empty immutable sorted multiset.
107   *
108   * <p><b>Performance note:</b> the instance returned is a singleton.
109   */
110  @SuppressWarnings("unchecked")
111  public static <E> ImmutableSortedMultiset<E> of() {
112    return (ImmutableSortedMultiset) RegularImmutableSortedMultiset.NATURAL_EMPTY_MULTISET;
113  }
114
115  /** Returns an immutable sorted multiset containing a single element. */
116  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(E e1) {
117    RegularImmutableSortedSet<E> elementSet =
118        (RegularImmutableSortedSet<E>) ImmutableSortedSet.of(e1);
119    long[] cumulativeCounts = {0, 1};
120    return new RegularImmutableSortedMultiset<>(elementSet, cumulativeCounts, 0, 1);
121  }
122
123  /**
124   * Returns an immutable sorted multiset containing the given elements sorted by their natural
125   * ordering.
126   *
127   * @throws NullPointerException if any element is null
128   */
129  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(E e1, E e2) {
130    return copyOf(Ordering.natural(), Arrays.asList(e1, e2));
131  }
132
133  /**
134   * Returns an immutable sorted multiset containing the given elements sorted by their natural
135   * ordering.
136   *
137   * @throws NullPointerException if any element is null
138   */
139  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(E e1, E e2, E e3) {
140    return copyOf(Ordering.natural(), Arrays.asList(e1, e2, e3));
141  }
142
143  /**
144   * Returns an immutable sorted multiset containing the given elements sorted by their natural
145   * ordering.
146   *
147   * @throws NullPointerException if any element is null
148   */
149  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(
150      E e1, E e2, E e3, E e4) {
151    return copyOf(Ordering.natural(), Arrays.asList(e1, e2, e3, e4));
152  }
153
154  /**
155   * Returns an immutable sorted multiset containing the given elements sorted by their natural
156   * ordering.
157   *
158   * @throws NullPointerException if any element is null
159   */
160  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(
161      E e1, E e2, E e3, E e4, E e5) {
162    return copyOf(Ordering.natural(), Arrays.asList(e1, e2, e3, e4, e5));
163  }
164
165  /**
166   * Returns an immutable sorted multiset containing the given elements sorted by their natural
167   * ordering.
168   *
169   * @throws NullPointerException if any element is null
170   */
171  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> of(
172      E e1, E e2, E e3, E e4, E e5, E e6, E... remaining) {
173    int size = remaining.length + 6;
174    List<E> all = Lists.newArrayListWithCapacity(size);
175    Collections.addAll(all, e1, e2, e3, e4, e5, e6);
176    Collections.addAll(all, remaining);
177    return copyOf(Ordering.natural(), all);
178  }
179
180  /**
181   * Returns an immutable sorted multiset containing the given elements sorted by their natural
182   * ordering.
183   *
184   * @throws NullPointerException if any of {@code elements} is null
185   */
186  public static <E extends Comparable<? super E>> ImmutableSortedMultiset<E> copyOf(E[] elements) {
187    return copyOf(Ordering.natural(), Arrays.asList(elements));
188  }
189
190  /**
191   * Returns an immutable sorted multiset containing the given elements sorted by their natural
192   * ordering. To create a copy of a {@code SortedMultiset} that preserves the comparator, call
193   * {@link #copyOfSorted} instead. This method iterates over {@code elements} at most once.
194   *
195   * <p>Note that if {@code s} is a {@code Multiset<String>}, then {@code
196   * ImmutableSortedMultiset.copyOf(s)} returns an {@code ImmutableSortedMultiset<String>}
197   * containing each of the strings in {@code s}, while {@code ImmutableSortedMultiset.of(s)}
198   * returns an {@code ImmutableSortedMultiset<Multiset<String>>} containing one element (the given
199   * multiset itself).
200   *
201   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
202   * safe to do so. The exact circumstances under which a copy will or will not be performed are
203   * undocumented and subject to change.
204   *
205   * <p>This method is not type-safe, as it may be called on elements that are not mutually
206   * comparable.
207   *
208   * @throws ClassCastException if the elements are not mutually comparable
209   * @throws NullPointerException if any of {@code elements} is null
210   */
211  public static <E> ImmutableSortedMultiset<E> copyOf(Iterable<? extends E> elements) {
212    // Hack around E not being a subtype of Comparable.
213    // Unsafe, see ImmutableSortedMultisetFauxverideShim.
214    @SuppressWarnings("unchecked")
215    Ordering<E> naturalOrder = (Ordering<E>) Ordering.<Comparable<?>>natural();
216    return copyOf(naturalOrder, elements);
217  }
218
219  /**
220   * Returns an immutable sorted multiset containing the given elements sorted by their natural
221   * ordering.
222   *
223   * <p>This method is not type-safe, as it may be called on elements that are not mutually
224   * comparable.
225   *
226   * @throws ClassCastException if the elements are not mutually comparable
227   * @throws NullPointerException if any of {@code elements} is null
228   */
229  public static <E> ImmutableSortedMultiset<E> copyOf(Iterator<? extends E> elements) {
230    // Hack around E not being a subtype of Comparable.
231    // Unsafe, see ImmutableSortedMultisetFauxverideShim.
232    @SuppressWarnings("unchecked")
233    Ordering<E> naturalOrder = (Ordering<E>) Ordering.<Comparable<?>>natural();
234    return copyOf(naturalOrder, elements);
235  }
236
237  /**
238   * Returns an immutable sorted multiset containing the given elements sorted by the given {@code
239   * Comparator}.
240   *
241   * @throws NullPointerException if {@code comparator} or any of {@code elements} is null
242   */
243  public static <E> ImmutableSortedMultiset<E> copyOf(
244      Comparator<? super E> comparator, Iterator<? extends E> elements) {
245    checkNotNull(comparator);
246    return new Builder<E>(comparator).addAll(elements).build();
247  }
248
249  /**
250   * Returns an immutable sorted multiset containing the given elements sorted by the given {@code
251   * Comparator}. This method iterates over {@code elements} at most once.
252   *
253   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
254   * safe to do so. The exact circumstances under which a copy will or will not be performed are
255   * undocumented and subject to change.
256   *
257   * @throws NullPointerException if {@code comparator} or any of {@code elements} is null
258   */
259  public static <E> ImmutableSortedMultiset<E> copyOf(
260      Comparator<? super E> comparator, Iterable<? extends E> elements) {
261    if (elements instanceof ImmutableSortedMultiset) {
262      @SuppressWarnings("unchecked") // immutable collections are always safe for covariant casts
263      ImmutableSortedMultiset<E> multiset = (ImmutableSortedMultiset<E>) elements;
264      if (comparator.equals(multiset.comparator())) {
265        if (multiset.isPartialView()) {
266          return copyOfSortedEntries(comparator, multiset.entrySet().asList());
267        } else {
268          return multiset;
269        }
270      }
271    }
272    elements = Lists.newArrayList(elements); // defensive copy
273    TreeMultiset<E> sortedCopy = TreeMultiset.create(checkNotNull(comparator));
274    Iterables.addAll(sortedCopy, elements);
275    return copyOfSortedEntries(comparator, sortedCopy.entrySet());
276  }
277
278  /**
279   * Returns an immutable sorted multiset containing the elements of a sorted multiset, sorted by
280   * the same {@code Comparator}. That behavior differs from {@link #copyOf(Iterable)}, which always
281   * uses the natural ordering of the elements.
282   *
283   * <p>Despite the method name, this method attempts to avoid actually copying the data when it is
284   * safe to do so. The exact circumstances under which a copy will or will not be performed are
285   * undocumented and subject to change.
286   *
287   * <p>This method is safe to use even when {@code sortedMultiset} is a synchronized or concurrent
288   * collection that is currently being modified by another thread.
289   *
290   * @throws NullPointerException if {@code sortedMultiset} or any of its elements is null
291   */
292  public static <E> ImmutableSortedMultiset<E> copyOfSorted(SortedMultiset<E> sortedMultiset) {
293    return copyOfSortedEntries(
294        sortedMultiset.comparator(), Lists.newArrayList(sortedMultiset.entrySet()));
295  }
296
297  private static <E> ImmutableSortedMultiset<E> copyOfSortedEntries(
298      Comparator<? super E> comparator, Collection<Entry<E>> entries) {
299    if (entries.isEmpty()) {
300      return emptyMultiset(comparator);
301    }
302    ImmutableList.Builder<E> elementsBuilder = new ImmutableList.Builder<>(entries.size());
303    long[] cumulativeCounts = new long[entries.size() + 1];
304    int i = 0;
305    for (Entry<E> entry : entries) {
306      elementsBuilder.add(entry.getElement());
307      cumulativeCounts[i + 1] = cumulativeCounts[i] + entry.getCount();
308      i++;
309    }
310    return new RegularImmutableSortedMultiset<>(
311        new RegularImmutableSortedSet<E>(elementsBuilder.build(), comparator),
312        cumulativeCounts,
313        0,
314        entries.size());
315  }
316
317  @SuppressWarnings("unchecked")
318  static <E> ImmutableSortedMultiset<E> emptyMultiset(Comparator<? super E> comparator) {
319    if (Ordering.natural().equals(comparator)) {
320      return (ImmutableSortedMultiset<E>) RegularImmutableSortedMultiset.NATURAL_EMPTY_MULTISET;
321    } else {
322      return new RegularImmutableSortedMultiset<>(comparator);
323    }
324  }
325
326  ImmutableSortedMultiset() {}
327
328  @Override
329  public final Comparator<? super E> comparator() {
330    return elementSet().comparator();
331  }
332
333  @Override
334  public abstract ImmutableSortedSet<E> elementSet();
335
336  @LazyInit @CheckForNull transient ImmutableSortedMultiset<E> descendingMultiset;
337
338  @Override
339  public ImmutableSortedMultiset<E> descendingMultiset() {
340    ImmutableSortedMultiset<E> result = descendingMultiset;
341    if (result == null) {
342      return descendingMultiset =
343          this.isEmpty()
344              ? emptyMultiset(Ordering.from(comparator()).reverse())
345              : new DescendingImmutableSortedMultiset<E>(this);
346    }
347    return result;
348  }
349
350  /**
351   * {@inheritDoc}
352   *
353   * <p>This implementation is guaranteed to throw an {@link UnsupportedOperationException}.
354   *
355   * @throws UnsupportedOperationException always
356   * @deprecated Unsupported operation.
357   */
358  @CanIgnoreReturnValue
359  @Deprecated
360  @Override
361  @DoNotCall("Always throws UnsupportedOperationException")
362  @CheckForNull
363  public final Entry<E> pollFirstEntry() {
364    throw new UnsupportedOperationException();
365  }
366
367  /**
368   * {@inheritDoc}
369   *
370   * <p>This implementation is guaranteed to throw an {@link UnsupportedOperationException}.
371   *
372   * @throws UnsupportedOperationException always
373   * @deprecated Unsupported operation.
374   */
375  @CanIgnoreReturnValue
376  @Deprecated
377  @Override
378  @DoNotCall("Always throws UnsupportedOperationException")
379  @CheckForNull
380  public final Entry<E> pollLastEntry() {
381    throw new UnsupportedOperationException();
382  }
383
384  @Override
385  public abstract ImmutableSortedMultiset<E> headMultiset(E upperBound, BoundType boundType);
386
387  @Override
388  public ImmutableSortedMultiset<E> subMultiset(
389      E lowerBound, BoundType lowerBoundType, E upperBound, BoundType upperBoundType) {
390    checkArgument(
391        comparator().compare(lowerBound, upperBound) <= 0,
392        "Expected lowerBound <= upperBound but %s > %s",
393        lowerBound,
394        upperBound);
395    return tailMultiset(lowerBound, lowerBoundType).headMultiset(upperBound, upperBoundType);
396  }
397
398  @Override
399  public abstract ImmutableSortedMultiset<E> tailMultiset(E lowerBound, BoundType boundType);
400
401  /**
402   * Returns a builder that creates immutable sorted multisets with an explicit comparator. If the
403   * comparator has a more general type than the set being generated, such as creating a {@code
404   * SortedMultiset<Integer>} with a {@code Comparator<Number>}, use the {@link Builder} constructor
405   * instead.
406   *
407   * @throws NullPointerException if {@code comparator} is null
408   */
409  public static <E> Builder<E> orderedBy(Comparator<E> comparator) {
410    return new Builder<>(comparator);
411  }
412
413  /**
414   * Returns a builder that creates immutable sorted multisets whose elements are ordered by the
415   * reverse of their natural ordering.
416   *
417   * <p>Note: the type parameter {@code E} extends {@code Comparable<?>} rather than {@code
418   * Comparable<? super E>} in order to accommodate users of obsolete javac versions affected by <a
419   * href="https://bugs.openjdk.org/browse/JDK-6468354">JDK-6468354</a>.
420   */
421  public static <E extends Comparable<?>> Builder<E> reverseOrder() {
422    return new Builder<>(Ordering.<E>natural().reverse());
423  }
424
425  /**
426   * Returns a builder that creates immutable sorted multisets whose elements are ordered by their
427   * natural ordering. The sorted multisets use {@link Ordering#natural()} as the comparator. This
428   * method provides more type-safety than {@link #builder}, as it can be called only for classes
429   * that implement {@link Comparable}.
430   *
431   * <p>Note: the type parameter {@code E} extends {@code Comparable<?>} rather than {@code
432   * Comparable<? super E>} in order to accommodate users of obsolete javac versions affected by <a
433   * href="https://bugs.openjdk.org/browse/JDK-6468354">JDK-6468354</a>.
434   */
435  public static <E extends Comparable<?>> Builder<E> naturalOrder() {
436    return new Builder<>(Ordering.natural());
437  }
438
439  /**
440   * A builder for creating immutable multiset instances, especially {@code public static final}
441   * multisets ("constant multisets"). Example:
442   *
443   * <pre>{@code
444   * public static final ImmutableSortedMultiset<Bean> BEANS =
445   *     new ImmutableSortedMultiset.Builder<Bean>(colorComparator())
446   *         .addCopies(Bean.COCOA, 4)
447   *         .addCopies(Bean.GARDEN, 6)
448   *         .addCopies(Bean.RED, 8)
449   *         .addCopies(Bean.BLACK_EYED, 10)
450   *         .build();
451   * }</pre>
452   *
453   * <p>Builder instances can be reused; it is safe to call {@link #build} multiple times to build
454   * multiple multisets in series.
455   *
456   * @since 12.0
457   */
458  public static class Builder<E> extends ImmutableMultiset.Builder<E> {
459    /**
460     * Creates a new builder. The returned builder is equivalent to the builder generated by {@link
461     * ImmutableSortedMultiset#orderedBy(Comparator)}.
462     */
463    public Builder(Comparator<? super E> comparator) {
464      super(TreeMultiset.<E>create(checkNotNull(comparator)));
465    }
466
467    /**
468     * Adds {@code element} to the {@code ImmutableSortedMultiset}.
469     *
470     * @param element the element to add
471     * @return this {@code Builder} object
472     * @throws NullPointerException if {@code element} is null
473     */
474    @CanIgnoreReturnValue
475    @Override
476    public Builder<E> add(E element) {
477      super.add(element);
478      return this;
479    }
480
481    /**
482     * Adds each element of {@code elements} to the {@code ImmutableSortedMultiset}.
483     *
484     * @param elements the elements to add
485     * @return this {@code Builder} object
486     * @throws NullPointerException if {@code elements} is null or contains a null element
487     */
488    @CanIgnoreReturnValue
489    @Override
490    public Builder<E> add(E... elements) {
491      super.add(elements);
492      return this;
493    }
494
495    /**
496     * Adds a number of occurrences of an element to this {@code ImmutableSortedMultiset}.
497     *
498     * @param element the element to add
499     * @param occurrences the number of occurrences of the element to add. May be zero, in which
500     *     case no change will be made.
501     * @return this {@code Builder} object
502     * @throws NullPointerException if {@code element} is null
503     * @throws IllegalArgumentException if {@code occurrences} is negative, or if this operation
504     *     would result in more than {@link Integer#MAX_VALUE} occurrences of the element
505     */
506    @CanIgnoreReturnValue
507    @Override
508    public Builder<E> addCopies(E element, int occurrences) {
509      super.addCopies(element, occurrences);
510      return this;
511    }
512
513    /**
514     * Adds or removes the necessary occurrences of an element such that the element attains the
515     * desired count.
516     *
517     * @param element the element to add or remove occurrences of
518     * @param count the desired count of the element in this multiset
519     * @return this {@code Builder} object
520     * @throws NullPointerException if {@code element} is null
521     * @throws IllegalArgumentException if {@code count} is negative
522     */
523    @CanIgnoreReturnValue
524    @Override
525    public Builder<E> setCount(E element, int count) {
526      super.setCount(element, count);
527      return this;
528    }
529
530    /**
531     * Adds each element of {@code elements} to the {@code ImmutableSortedMultiset}.
532     *
533     * @param elements the {@code Iterable} to add to the {@code ImmutableSortedMultiset}
534     * @return this {@code Builder} object
535     * @throws NullPointerException if {@code elements} is null or contains a null element
536     */
537    @CanIgnoreReturnValue
538    @Override
539    public Builder<E> addAll(Iterable<? extends E> elements) {
540      super.addAll(elements);
541      return this;
542    }
543
544    /**
545     * Adds each element of {@code elements} to the {@code ImmutableSortedMultiset}.
546     *
547     * @param elements the elements to add to the {@code ImmutableSortedMultiset}
548     * @return this {@code Builder} object
549     * @throws NullPointerException if {@code elements} is null or contains a null element
550     */
551    @CanIgnoreReturnValue
552    @Override
553    public Builder<E> addAll(Iterator<? extends E> elements) {
554      super.addAll(elements);
555      return this;
556    }
557
558    /**
559     * Returns a newly-created {@code ImmutableSortedMultiset} based on the contents of the {@code
560     * Builder}.
561     */
562    @Override
563    public ImmutableSortedMultiset<E> build() {
564      return copyOfSorted((SortedMultiset<E>) contents);
565    }
566  }
567
568  @J2ktIncompatible // serialization
569  private static final class SerializedForm<E> implements Serializable {
570    final Comparator<? super E> comparator;
571    final E[] elements;
572    final int[] counts;
573
574    @SuppressWarnings("unchecked")
575    SerializedForm(SortedMultiset<E> multiset) {
576      this.comparator = multiset.comparator();
577      int n = multiset.entrySet().size();
578      elements = (E[]) new Object[n];
579      counts = new int[n];
580      int i = 0;
581      for (Entry<E> entry : multiset.entrySet()) {
582        elements[i] = entry.getElement();
583        counts[i] = entry.getCount();
584        i++;
585      }
586    }
587
588    Object readResolve() {
589      int n = elements.length;
590      Builder<E> builder = new Builder<>(comparator);
591      for (int i = 0; i < n; i++) {
592        builder.addCopies(elements[i], counts[i]);
593      }
594      return builder.build();
595    }
596  }
597
598  @Override
599  @J2ktIncompatible // serialization
600  Object writeReplace() {
601    return new SerializedForm<E>(this);
602  }
603
604  @J2ktIncompatible // java.io.ObjectInputStream
605  private void readObject(ObjectInputStream stream) throws InvalidObjectException {
606    throw new InvalidObjectException("Use SerializedForm");
607  }
608
609  /**
610   * Not supported. Use {@link #toImmutableSortedMultiset} instead. This method exists only to hide
611   * {@link ImmutableMultiset#toImmutableMultiset} from consumers of {@code
612   * ImmutableSortedMultiset}.
613   *
614   * @throws UnsupportedOperationException always
615   * @deprecated Use {@link ImmutableSortedMultiset#toImmutableSortedMultiset}.
616   * @since 21.0
617   */
618  @DoNotCall("Use toImmutableSortedMultiset.")
619  @Deprecated
620  public static <E> Collector<E, ?, ImmutableMultiset<E>> toImmutableMultiset() {
621    throw new UnsupportedOperationException();
622  }
623
624  /**
625   * Not supported. Use {@link #toImmutableSortedMultiset} instead. This method exists only to hide
626   * {@link ImmutableMultiset#toImmutableMultiset} from consumers of {@code
627   * ImmutableSortedMultiset}.
628   *
629   * @throws UnsupportedOperationException always
630   * @deprecated Use {@link ImmutableSortedMultiset#toImmutableSortedMultiset}.
631   * @since 22.0
632   */
633  @DoNotCall("Use toImmutableSortedMultiset.")
634  @Deprecated
635  public static <T extends @Nullable Object, E>
636      Collector<T, ?, ImmutableMultiset<E>> toImmutableMultiset(
637          Function<? super T, ? extends E> elementFunction,
638          ToIntFunction<? super T> countFunction) {
639    throw new UnsupportedOperationException();
640  }
641
642  /**
643   * Not supported. Use {@link #naturalOrder}, which offers better type-safety, instead. This method
644   * exists only to hide {@link ImmutableMultiset#builder} from consumers of {@code
645   * ImmutableSortedMultiset}.
646   *
647   * @throws UnsupportedOperationException always
648   * @deprecated Use {@link ImmutableSortedMultiset#naturalOrder}, which offers better type-safety.
649   */
650  @DoNotCall("Use naturalOrder.")
651  @Deprecated
652  public static <E> ImmutableSortedMultiset.Builder<E> builder() {
653    throw new UnsupportedOperationException();
654  }
655
656  /**
657   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
658   * Comparable} element.</b> Proper calls will resolve to the version in {@code
659   * ImmutableSortedMultiset}, not this dummy version.
660   *
661   * @throws UnsupportedOperationException always
662   * @deprecated <b>Pass a parameter of type {@code Comparable} to use {@link
663   *     ImmutableSortedMultiset#of(Comparable)}.</b>
664   */
665  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
666  @Deprecated
667  public static <E> ImmutableSortedMultiset<E> of(E e1) {
668    throw new UnsupportedOperationException();
669  }
670
671  /**
672   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
673   * Comparable} element.</b> Proper calls will resolve to the version in {@code
674   * ImmutableSortedMultiset}, not this dummy version.
675   *
676   * @throws UnsupportedOperationException always
677   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
678   *     ImmutableSortedMultiset#of(Comparable, Comparable)}.</b>
679   */
680  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
681  @Deprecated
682  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2) {
683    throw new UnsupportedOperationException();
684  }
685
686  /**
687   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
688   * Comparable} element.</b> Proper calls will resolve to the version in {@code
689   * ImmutableSortedMultiset}, not this dummy version.
690   *
691   * @throws UnsupportedOperationException always
692   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
693   *     ImmutableSortedMultiset#of(Comparable, Comparable, Comparable)}.</b>
694   */
695  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
696  @Deprecated
697  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3) {
698    throw new UnsupportedOperationException();
699  }
700
701  /**
702   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
703   * Comparable} element.</b> Proper calls will resolve to the version in {@code
704   * ImmutableSortedMultiset}, not this dummy version.
705   *
706   * @throws UnsupportedOperationException always
707   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
708   *     ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable)}. </b>
709   */
710  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
711  @Deprecated
712  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3, E e4) {
713    throw new UnsupportedOperationException();
714  }
715
716  /**
717   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
718   * Comparable} element.</b> Proper calls will resolve to the version in {@code
719   * ImmutableSortedMultiset}, not this dummy version.
720   *
721   * @throws UnsupportedOperationException always
722   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
723   *     ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable, Comparable)} .
724   *     </b>
725   */
726  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
727  @Deprecated
728  public static <E> ImmutableSortedMultiset<E> of(E e1, E e2, E e3, E e4, E e5) {
729    throw new UnsupportedOperationException();
730  }
731
732  /**
733   * Not supported. <b>You are attempting to create a multiset that may contain a non-{@code
734   * Comparable} element.</b> Proper calls will resolve to the version in {@code
735   * ImmutableSortedMultiset}, not this dummy version.
736   *
737   * @throws UnsupportedOperationException always
738   * @deprecated <b>Pass the parameters of type {@code Comparable} to use {@link
739   *     ImmutableSortedMultiset#of(Comparable, Comparable, Comparable, Comparable, Comparable,
740   *     Comparable, Comparable...)} . </b>
741   */
742  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
743  @Deprecated
744  public static <E> ImmutableSortedMultiset<E> of(
745      E e1, E e2, E e3, E e4, E e5, E e6, E... remaining) {
746    throw new UnsupportedOperationException();
747  }
748
749  /**
750   * Not supported. <b>You are attempting to create a multiset that may contain non-{@code
751   * Comparable} elements.</b> Proper calls will resolve to the version in {@code
752   * ImmutableSortedMultiset}, not this dummy version.
753   *
754   * @throws UnsupportedOperationException always
755   * @deprecated <b>Pass parameters of type {@code Comparable} to use {@link
756   *     ImmutableSortedMultiset#copyOf(Comparable[])}.</b>
757   */
758  @DoNotCall("Elements must be Comparable. (Or, pass a Comparator to orderedBy or copyOf.)")
759  @Deprecated
760  // The usage of "Z" here works around bugs in Javadoc (JDK-8318093) and JDiff.
761  public static <Z> ImmutableSortedMultiset<Z> copyOf(Z[] elements) {
762    throw new UnsupportedOperationException();
763  }
764
765  private static final long serialVersionUID = 0xcafebabe;
766}