changeset 7744:03cddb267af7

Docs.
author psandoz
date Tue, 26 Mar 2013 14:08:03 +0100
parents fcd5e03f8609
children 198eedb8ec82
files src/share/classes/java/util/Spliterator.java src/share/classes/java/util/Spliterators.java
diffstat 2 files changed, 31 insertions(+), 10 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Spliterator.java	Tue Mar 26 11:56:05 2013 +0100
+++ b/src/share/classes/java/util/Spliterator.java	Tue Mar 26 14:08:03 2013 +0100
@@ -393,18 +393,23 @@
     }
 
     /**
-     * If this Spliterator's source supports characteristic {@link #SORTED}
-     * based on a {@link Comparator}, returns it, else returns {@code null} if
-     * natural order.  Otherwise, if the source does not support
-     * {@link #SORTED}, returns an undefined value.
+     * If this Spliterator's source is {@link #SORTED} by a {@link Comparator}
+     * return that {@code Comparator}.  If the source is {@code SORTED}
+     * naturally return {@code null}.  Otherwise, if the source is not
+     * {@code SORTED} throw {@link IllegalStateException}.
      *
      * @implSpec
-     * The default implementation returns {@code null}.
+     * The default implementation returns null if this spliterator reports
+     * {@code SORTED}, otherwise throws {@code IllegalStateException}.
      *
      * @return a Comparator, or {@code null} if natural order.
+     * @throws IllegalStateException if the spliterator does not report
+     *         {@code SORTED}.
      */
     default Comparator<? super T> getComparator() {
-        return null;
+        if (hasCharacteristics(Spliterator.SORTED))
+            return null;
+        throw new IllegalStateException();
     }
 
     /**
--- a/src/share/classes/java/util/Spliterators.java	Tue Mar 26 11:56:05 2013 +0100
+++ b/src/share/classes/java/util/Spliterators.java	Tue Mar 26 14:08:03 2013 +0100
@@ -47,8 +47,12 @@
     /**
      * Creates an empty {@code Spliterator}
      *
+     * <p>The empty spliterator reports {@link Spliterator#SIZED} and
+     * {@link Spliterator#SUBSIZED}.  Calls to
+     * {@link java.util.Spliterator#trySplit()} return {@code null}.
+     *
      * @param <T> Type of elements
-     * @return An empty {@code Spliterator}
+     * @return An empty spliterator
      */
     public static <T> Spliterator<T> emptySpliterator() {
         return new AbstractEmptySpliterator.OfRef<>();
@@ -57,7 +61,11 @@
     /**
      * Creates an empty {@code Spliterator.OfInt}
      *
-     * @return An empty {@code Spliterator.OfInt}
+     * <p>The empty spliterator reports {@link Spliterator#SIZED} and
+     * {@link Spliterator#SUBSIZED}.  Calls to
+     * {@link java.util.Spliterator#trySplit()} return {@code null}.
+     *
+     * @return An empty spliterator
      */
     public static Spliterator.OfInt emptyIntSpliterator() {
         return new AbstractEmptySpliterator.OfInt();
@@ -66,7 +74,11 @@
     /**
      * Creates an empty {@code Spliterator.OfLong}
      *
-     * @return An empty {@code Spliterator.OfLong}
+     * <p>The empty spliterator reports {@link Spliterator#SIZED} and
+     * {@link Spliterator#SUBSIZED}.  Calls to
+     * {@link java.util.Spliterator#trySplit()} return {@code null}.
+     *
+     * @return An empty spliterator
      */
     public static Spliterator.OfLong emptyLongSpliterator() {
         return new AbstractEmptySpliterator.OfLong();
@@ -75,7 +87,11 @@
     /**
      * Creates an empty {@code Spliterator.OfDouble}
      *
-     * @return An empty {@code Spliterator.OfDouble}
+     * <p>The empty spliterator reports {@link Spliterator#SIZED} and
+     * {@link Spliterator#SUBSIZED}.  Calls to
+     * {@link java.util.Spliterator#trySplit()} return {@code null}.
+     *
+     * @return An empty spliterator
      */
     public static Spliterator.OfDouble emptyDoubleSpliterator() {
         return new AbstractEmptySpliterator.OfDouble();