updates floor/ceiling to throw NoSuchElementException in corner cases

Author: kevin-wayne

src/main/java/edu/princeton/cs/algs4/BST.java

@@ -43,22 +43,26 @@
  *  value associated with a key to {@code null} is equivalent to deleting the key
  *  from the symbol table.
  *  <p>
- *  This implementation uses an (unbalanced) binary search tree. It requires that
+ *  It requires that
  *  the key type implements the {@code Comparable} interface and calls the
  *  {@code compareTo()} and method to compare two keys. It does not call either
  *  {@code equals()} or {@code hashCode()}.
+ *  <p>
+ *  This implementation uses an (unbalanced) <em>binary search tree</em>.
  *  The <em>put</em>, <em>contains</em>, <em>remove</em>, <em>minimum</em>,
  *  <em>maximum</em>, <em>ceiling</em>, <em>floor</em>, <em>select</em>, and
- *  <em>rank</em>  operations each take
- *  linear time in the worst case, if the tree becomes unbalanced.
- *  The <em>size</em>, and <em>is-empty</em> operations take constant time.
- *  Construction takes constant time.
+ *  <em>rank</em>  operations each take &Theta;(<em>n</em>) time in the worst
+ *  case, where <em>n</em> is the number of key-value pairs.
+ *  The <em>size</em> and <em>is-empty</em> operations take &Theta;(1) time.
+ *  The keys method takes &Theta;(<em>n</em>) time in the worst case.
+ *  Construction takes &Theta;(1) time.
  *  <p>
- *  For additional documentation, see <a href="https://algs4.cs.princeton.edu/32bst">Section 3.2</a> of
- *  <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
- *  For other implementations, see {@link ST}, {@link BinarySearchST},
- *  {@link SequentialSearchST}, {@link RedBlackBST},
+ *  For alternative implementations of the symbol table API, see {@link ST},
+ *  {@link BinarySearchST}, {@link SequentialSearchST}, {@link RedBlackBST},
  *  {@link SeparateChainingHashST}, and {@link LinearProbingHashST},
+ *  For additional documentation, see
+ *  <a href="https://algs4.cs.princeton.edu/32bst">Section 3.2</a> of
+ *  <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
  *
  *  @author Robert Sedgewick
  *  @author Kevin Wayne
@@ -284,7 +288,7 @@ public Key floor(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to floor() is null");
         if (isEmpty()) throw new NoSuchElementException("calls floor() with empty symbol table");
         Node x = floor(root, key);
-        if (x == null) return null;
+        if (x == null) throw new NoSuchElementException("argument to floor() is too small");
         else return x.key;
     } 
 
@@ -299,7 +303,10 @@ private Node floor(Node x, Key key) {
     } 
 
     public Key floor2(Key key) {
-        return floor2(root, key, null);
+        Key x = floor2(root, key, null);
+        if (x == null) throw new NoSuchElementException("argument to floor() is too small");
+        else return x;
+
     }
 
     private Key floor2(Node x, Key key, Key best) {
@@ -322,7 +329,7 @@ public Key ceiling(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to ceiling() is null");
         if (isEmpty()) throw new NoSuchElementException("calls ceiling() with empty symbol table");
         Node x = ceiling(root, key);
-        if (x == null) return null;
+        if (x == null) throw new NoSuchElementException("argument to floor() is too large");
         else return x.key;
     }
 

src/main/java/edu/princeton/cs/algs4/RedBlackBST.java

@@ -59,16 +59,18 @@
  *  &Theta;(log <em>n</em>) time in the worst case, where <em>n</em> is the
  *  number of key-value pairs in the symbol table.
  *  The <em>size</em>, and <em>is-empty</em> operations take &Theta;(1) time.
- *  The <em>keys</em> method takes time proportional to the number of keys
- *  returned by the iterator.
+ *  The <em>keys</em> methods take
+ *  <em>O</em>(log <em>n</em> + <em>m</em>) time, where <em>m</em> is
+ *  the number of keys returned by the iterator.
  *  Construction takes &Theta;(1) time.
  *  <p>
+ *  For alternative implementations of the symbol table API, see {@link ST},
+ *  {@link BinarySearchST}, {@link SequentialSearchST}, {@link BST},
+ *  {@link SeparateChainingHashST}, {@link LinearProbingHashST}, and
+ *  {@link AVLTreeST}.
  *  For additional documentation, see
  *  <a href="https://algs4.cs.princeton.edu/33balanced">Section 3.3</a> of
  *  <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
- *  For other implementations of the same API, see {@link ST}, {@link BinarySearchST},
- *  {@link SequentialSearchST}, {@link BST},
- *  {@link SeparateChainingHashST}, {@link LinearProbingHashST}, and {@link AVLTreeST}.
  *
  *  @author Robert Sedgewick
  *  @author Kevin Wayne
@@ -480,7 +482,7 @@ public Key floor(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to floor() is null");
         if (isEmpty()) throw new NoSuchElementException("calls floor() with empty symbol table");
         Node x = floor(root, key);
-        if (x == null) return null;
+        if (x == null) throw new NoSuchElementException("argument to floor() is too small");
         else           return x.key;
     }    
 
@@ -506,7 +508,7 @@ public Key ceiling(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to ceiling() is null");
         if (isEmpty()) throw new NoSuchElementException("calls ceiling() with empty symbol table");
         Node x = ceiling(root, key);
-        if (x == null) return null;
+        if (x == null) throw new NoSuchElementException("argument to ceiling() is too small");
         else           return x.key;  
     }
 

src/main/java/edu/princeton/cs/algs4/ST.java

@@ -31,10 +31,12 @@
  *  value associated with a key to {@code null} is equivalent to deleting the key
  *  from the symbol table.
  *  <p>
- *  This implementation uses a red-black BST. It requires that
+ *  It requires that
  *  the key type implements the {@code Comparable} interface and calls the
  *  {@code compareTo()} and method to compare two keys. It does not call either
  *  {@code equals()} or {@code hashCode()}.
+ *  <p>
+ *  This implementation uses a <em>red-black BST</em>.
  *  The <em>put</em>, <em>get</em>, <em>contains</em>, <em>remove</em>,
  *  <em>minimum</em>, <em>maximum</em>, <em>ceiling</em>, and <em>floor</em>
  *  operations each take &Theta;(log <em>n</em>) time in the worst case,
@@ -211,7 +213,7 @@ public Key max() {
     public Key ceiling(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to ceiling() is null");
         Key k = st.ceilingKey(key);
-        if (k == null) throw new NoSuchElementException("all keys are less than " + key);
+        if (k == null) throw new NoSuchElementException("argument to ceiling() is too large");
         return k;
     }
 
@@ -226,7 +228,7 @@ public Key ceiling(Key key) {
     public Key floor(Key key) {
         if (key == null) throw new IllegalArgumentException("argument to floor() is null");
         Key k = st.floorKey(key);
-        if (k == null) throw new NoSuchElementException("all keys are greater than " + key);
+        if (k == null) throw new NoSuchElementException("argument to floor() is too small");
         return k;
     }