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