Changed license to proper long form.

Added documentation, and updating formatting of some documentation (i.e.
put "code" within <code>...</code>)

Added check for a valid capacity argument passed to constructor.

regards,
Michael

p.s. What's with all the finals?

Index:
D:/home/michael/dev/jakarta/jakarta-commons/collections/src/java/org/apa
che/commons/collections/BinaryHeap.java
===================================================================
RCS file:
/home/cvspublic/jakarta-commons/collections/src/java/org/apache/commons/
collections/BinaryHeap.java,v
retrieving revision 1.2
diff -u -r1.2 BinaryHeap.java
---
D:/home/michael/dev/jakarta/jakarta-commons/collections/src/java/org/apa
che/commons/collections/BinaryHeap.java 4 May 2001 16:31:23 -0000       1.2
+++
D:/home/michael/dev/jakarta/jakarta-commons/collections/src/java/org/apa
che/commons/collections/BinaryHeap.java 3 Feb 2002 16:09:03 -0000
@@ -1,9 +1,62 @@
 /*
- * Copyright (C) The Apache Software Foundation. All rights reserved.
+ * $Header: $
+ * $Revision: $
+ * $Date: $
+ *
+ * ====================================================================
+ *
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software
itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Commons", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products
derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact [EMAIL PROTECTED]
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
  *
- * This software is published under the terms of the Apache Software
License
- * version 1.1, a copy of which has been included with this
distribution in
- * the LICENSE file.
  */
 package org.apache.commons.collections;

@@ -24,23 +77,57 @@
     protected Comparable[]          m_elements;
     protected boolean               m_isMinHeap;

+    /**
+     *  Create a new minimum binary heap.
+     */
     public BinaryHeap()
     {
         this( DEFAULT_CAPACITY, true );
     }

+    /**
+     *  Create a new minimum binary heap with the specified initial
capacity.
+     *
+     *  @param capacity the initial capacity for the heap.  This value
must be
+     *  greater than zero.
+     *
+     *  @exception IllegalArgumentException
+     *   if <code>capacity</code> is &lt;= <code>0</code>
+     **/
     public BinaryHeap( final int capacity )
     {
         this( capacity, true );
     }

+    /**
+     *  Create a new minimum or maximum binary heap
+     *
+     *  @param isMinHeap if <code>true</code> the heap is created as a
minimum
+     *  heap; otherwise, the heap is created as a maximum heap.
+     **/
     public BinaryHeap( final boolean isMinHeap )
     {
         this( DEFAULT_CAPACITY, isMinHeap );
     }

+    /**
+     *  Create a new minimum or maximum binary heap with the specified
initial
+     *  capacity.
+     *
+     *  @param capacity the initial capacity for the heap.  This value
must be
+     *  greater than zero.
+     *
+     *  @param isMinHeap if <code>true</code> the heap is created as a
minimum
+     *  heap; otherwise, the heap is created as a maximum heap.
+     *
+     *  @exception IllegalArgumentException
+     *   if <code>capacity</code> is &lt;= <code>0</code>
+     **/
     public BinaryHeap( final int capacity, final boolean isMinHeap )
     {
+        if( capacity <= 0 ) {
+            throw new IllegalArgumentException( "invalid capacity" );
+        }
         m_isMinHeap = isMinHeap;

         //+1 as 0 is noop
@@ -58,7 +145,7 @@
     /**
      * Test if queue is empty.
      *
-     * @return true if queue is empty else false.
+     * @return true if queue is empty; else false.
      */
     public boolean isEmpty()
     {
@@ -94,7 +181,7 @@
      * Return element on top of heap but don't remove it.
      *
      * @return the element at top of heap
-     * @exception NoSuchElementException if isEmpty() == true
+     * @exception NoSuchElementException if <code>isEmpty() ==
true</code>
      */
     public Comparable peek() throws NoSuchElementException
     {
@@ -106,7 +193,7 @@
      * Return element on top of heap and remove it.
      *
      * @return the element at top of heap
-     * @exception NoSuchElementException if isEmpty() == true
+     * @exception NoSuchElementException if <code>isEmpty() ==
true</code>
      */
     public Comparable pop() throws NoSuchElementException
     {
@@ -131,7 +218,7 @@
      * Percolate element down heap from top.
      * Assume it is a maximum heap.
      *
-     * @param element the element
+     * @param index the index for the element
      */
     protected void percolateDownMinHeap( final int index )
     {
@@ -168,7 +255,7 @@
      * Percolate element down heap from top.
      * Assume it is a maximum heap.
      *
-     * @param element the element
+     * @param index the index of the element
      */
     protected void percolateDownMaxHeap( final int index )
     {
@@ -249,6 +336,9 @@
         m_elements[ hole ] = element;
     }

+    /**
+     *  Increase the size of the heap to support additional elements
+     **/
     protected void grow()
     {
         final Comparable[] elements =

Attachment: BinaryHeap.patch
Description: Binary data

--
To unsubscribe, e-mail:   <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>

Reply via email to