making performance guarantees in API more precise

Author: kevin-wayne

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

@@ -28,11 +28,12 @@
  *  acyclic graphs (DAGs). The edge weights can be positive, negative, or zero.
  *  <p>
  *  This implementation uses a topological-sort based algorithm.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>,
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Each call to {@code distTo(int)} and {@code hasPathTo(int)} takes constant time;
- *  each call to {@code pathTo(int)} takes time proportional to the number of
- *  edges in the shortest path returned.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in the
+ *  worst case, where <em>V</em> is the number of vertices and
+ *  <em>E</em> is the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the
+ *  edge-weighted digraph).
  *  <p>
  *  For additional documentation,   
  *  see <a href="https://algs4.cs.princeton.edu/44sp">Section 4.4</a> of   

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

@@ -26,11 +26,12 @@
  *  graphs (DAGs). The edge weights can be positive, negative, or zero.
  *  <p>
  *  This implementation uses a topological-sort based algorithm.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>,
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Each call to {@code distTo(int)} and {@code hasPathTo(int)} takes constant time;
- *  each call to {@code pathTo(int)} takes time proportional to the number of
- *  edges in the shortest path returned.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in the
+ *  worst case, where <em>V</em> is the number of vertices and
+ *  <em>E</em> is the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the
+ *  edge-weighted digraph).
  *  <p>
  *  For additional documentation,    
  *  see <a href="https://algs4.cs.princeton.edu/44sp">Section 4.4</a> of    

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

@@ -37,14 +37,14 @@
  *  This class finds either a shortest path from the source vertex <em>s</em>
  *  to every other vertex or a negative cycle reachable from the source vertex.
  *  <p>
- *  This implementation uses the Bellman-Ford-Moore algorithm.
- *  The constructor takes time proportional to <em>V</em> (<em>V</em> + <em>E</em>)
- *  in the worst case, where <em>V</em> is the number of vertices and <em>E</em>
- *  is the number of edges.
- *  Each call to {@code distTo(int)} and {@code hasPathTo(int)},
- *  {@code hasNegativeCycle} takes constant time;
- *  each call to {@code pathTo(int)} and {@code negativeCycle()}
- *  takes time proportional to length of the path returned.
+ *  This implementation uses a queue-based implementation of 
+ *  the Bellman-Ford-Moore algorithm.
+ *  The constructor takes &Theta;(<em>V</em> (<em>V</em> + <em>E</em>)) time
+ *  in the worst case, where <em>V</em> is the number of vertices and
+ *  <em>E</em> is the number of edges. In practice, it performs much better.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the
+ *  edge-weighted digraph).
  *  <p>
  *  For additional documentation,    
  *  see <a href="https://algs4.cs.princeton.edu/44sp">Section 4.4</a> of    

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

@@ -28,16 +28,20 @@
  *  The {@code BinaryInsertion} class provides a static method for sorting an
  *  array using an optimized binary insertion sort with half exchanges.
  *  <p>
- *  This implementation makes ~ n lg n compares for any array of length n.
- *  However, in the worst case, the running time is quadratic because the
- *  number of array accesses can be proportional to n^2 (e.g, if the array
- *  is reverse sorted). As such, it is not suitable for sorting large
- *  arrays (unless the number of inversions is small).
+ *  In the worst case, this implementation makes
+ *  ~ <em>n</em> log<sub>2</sub><em>n</em> compares to sort an array of length
+ *  <em>n</em>. However, in the worst case, the running time is
+ *  &Theta;(<em>n</em><sup>2</sup>) because the number of array accesses
+ *  can be quadratic.
+ *  As such, it is not suitable for sorting large arrays
+ *  (unless the number of inversions is small).
  *  <p>
- *  The sorting algorithm is stable and uses O(1) extra memory.
+ *  This sorting algorithm is stable.
+ *  It uses &Theta;(1) extra memory (not including the input array).
  *  <p>
- *  For additional documentation, see <a href="https://algs4.cs.princeton.edu/21elementary">Section 2.1</a> of
- *  <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
+ *  For additional documentation,
+ *  see <a href="https://algs4.cs.princeton.edu/21elementary">Section 2.1</a>
+ *  of <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
  *
  *  @author Ivan Pesin
  *  @author Robert Sedgewick

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

@@ -16,20 +16,20 @@
 
 /**
  *  The {@code Bipartite} class represents a data type for 
- *  determining whether an undirected graph is bipartite or whether
- *  it has an odd-length cycle.
+ *  determining whether an undirected graph is <em>bipartite</em> or whether
+ *  it has an <em>odd-length cycle</em>.
+ *  A graph is bipartite if and only if it has no odd-length cycle.
  *  The <em>isBipartite</em> operation determines whether the graph is
  *  bipartite. If so, the <em>color</em> operation determines a
  *  bipartition; if not, the <em>oddCycle</em> operation determines a
  *  cycle with an odd number of edges.
  *  <p>
- *  This implementation uses depth-first search.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>
- *  (in the worst case),
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Afterwards, the <em>isBipartite</em> and <em>color</em> operations
- *  take constant time; the <em>oddCycle</em> operation takes time proportional
- *  to the length of the cycle.
+ *  This implementation uses <em>depth-first search</em>.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in
+ *  the worst case, where <em>V</em> is the number of vertices and <em>E</em>
+ *  is the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the graph).
  *  See {@link BipartiteX} for a nonrecursive version that uses breadth-first
  *  search.
  *  <p>

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

@@ -14,20 +14,20 @@
 
 /**
  *  The {@code BipartiteX} class represents a data type for 
- *  determining whether an undirected graph is bipartite or whether
- *  it has an odd-length cycle.
+ *  determining whether an undirected graph is <em>bipartite</em> or whether
+ *  it has an <em>odd-length cycle</em>.
+ *  A graph is bipartite if and only if it has no odd-length cycle.
  *  The <em>isBipartite</em> operation determines whether the graph is
  *  bipartite. If so, the <em>color</em> operation determines a
  *  bipartition; if not, the <em>oddCycle</em> operation determines a
  *  cycle with an odd number of edges.
  *  <p>
- *  This implementation uses breadth-first search and is nonrecursive.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>
- *  (in the worst case),
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Afterwards, the <em>isBipartite</em> and <em>color</em> operations
- *  take constant time; the <em>oddCycle</em> operation takes time proportional
- *  to the length of the cycle.
+ *  This implementation uses <em>breadth-first search</em> and is nonrecursive.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in
+ *  in the worst case, where <em>V</em> is the number of vertices
+ *  and <em>E</em> is the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the graph).
  *  See {@link Bipartite} for a recursive version that uses depth-first search.
  *  <p>
  *  For additional documentation,

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

@@ -29,17 +29,16 @@
 package edu.princeton.cs.algs4;
 
 /**
- *  The {@code BreadthDirectedFirstPaths} class represents a data type for finding
- *  shortest paths (number of edges) from a source vertex <em>s</em>
+ *  The {@code BreadthDirectedFirstPaths} class represents a data type for
+ *  finding shortest paths (number of edges) from a source vertex <em>s</em>
  *  (or set of source vertices) to every other vertex in the digraph.
  *  <p>
  *  This implementation uses breadth-first search.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>,
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Each call to {@link #distTo(int)} and {@link #hasPathTo(int)} takes constant time;
- *  each call to {@link #pathTo(int)} takes time proportional to the length
- *  of the path.
- *  It uses extra space (not including the digraph) proportional to <em>V</em>.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in the
+ *  worst case, where <em>V</em> is the number of vertices and <em>E</em> is
+ *  the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the digraph).
  *  <p>
  *  For additional documentation, 
  *  see <a href="https://algs4.cs.princeton.edu/42digraph">Section 4.2</a> of 

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

@@ -48,12 +48,11 @@
  *  to every other vertex in an undirected graph.
  *  <p>
  *  This implementation uses breadth-first search.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>,
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Each call to {@link #distTo(int)} and {@link #hasPathTo(int)} takes constant time;
- *  each call to {@link #pathTo(int)} takes time proportional to the length
- *  of the path.
- *  It uses extra space (not including the graph) proportional to <em>V</em>.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time in the
+ *  worst case, where <em>V</em> is the number of vertices and <em>E</em>
+ *  is the number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the graph).
  *  <p>
  *  For additional documentation,
  *  see <a href="https://algs4.cs.princeton.edu/41graph">Section 4.1</a>   

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

@@ -47,14 +47,15 @@
 
  *  <p>
  *  This implementation uses depth-first search.
- *  The constructor takes time proportional to <em>V</em> + <em>E</em>
- *  (in the worst case),
- *  where <em>V</em> is the number of vertices and <em>E</em> is the number of edges.
- *  Afterwards, the <em>id</em>, <em>count</em>, <em>connected</em>,
- *  and <em>size</em> operations take constant time.
+ *  The constructor takes &Theta;(<em>V</em> + <em>E</em>) time,
+ *  where <em>V</em> is the number of vertices and <em>E</em> is the
+ *  number of edges.
+ *  Each instance method takes &Theta;(1) time.
+ *  It uses &Theta;(<em>V</em>) extra space (not including the graph).
  *  <p>
- *  For additional documentation, see <a href="https://algs4.cs.princeton.edu/41graph">Section 4.1</a>   
- *  of <i>Algorithms, 4th Edition</i> by Robert Sedgewick and Kevin Wayne.
+ *  For additional documentation, see 
+ *  <a href="https://algs4.cs.princeton.edu/41graph">Section 4.1</a>   
+ *  of <em>Algorithms, 4th Edition</em> by Robert Sedgewick and Kevin Wayne.
  *
  *  @author Robert Sedgewick
  *  @author Kevin Wayne

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

@@ -37,9 +37,9 @@
  *  <p>
  *  This implementation uses {@link AcyclicLP} to find a longest
  *  path in a DAG.
- *  The running time is proportional to <em>V</em> + <em>E</em>,
- *  where <em>V</em> is the number of jobs and <em>E</em> is the
- *  number of precedence constraints.
+ *  The program takes &Theta;(<em>V</em> + <em>E</em>) time in
+ *  the worst case, where <em>V</em> is the number of jobs and
+ *  <em>E</em> is the number of precedence constraints.
  *  <p>
  *  For additional documentation,
  *  see <a href="https://algs4.cs.princeton.edu/44sp">Section 4.4</a> of