Enhance docs, add tests in HeapElement (#5981)

This commit is contained in:
Hardik Pawar
2024-10-26 21:09:28 +05:30
committed by GitHub
parent 08bd1ffe73
commit 8a18d451d6
3 changed files with 126 additions and 37 deletions

View File

@ -1,14 +1,24 @@
package com.thealgorithms.datastructures.heaps;
/**
* Class for heap elements.<br>
* Class representing an element in a heap.
*
* <p>
* A heap element contains two attributes: a key which will be used to build the
* tree (int or double, either primitive type or object) and any kind of
* IMMUTABLE object the user sees fit to carry any information he/she likes. Be
* aware that the use of a mutable object might jeopardize the integrity of this
* information.
* A heap element contains two attributes: a key used for ordering in the heap
* (which can be of type int or double, either as primitive types or as wrapper objects)
* and an additional immutable object that can store any supplementary information the user desires.
* Note that using mutable objects may compromise the integrity of this information.
* </p>
*
* <p>
* The key attribute is used to determine the order of elements in the heap,
* while the additionalInfo attribute can carry user-defined data associated with the key.
* </p>
*
* <p>
* This class provides multiple constructors to accommodate various key types and includes
* methods to retrieve the key and additional information.
* </p>
*
* @author Nicolas Renard
*/
@ -19,9 +29,10 @@ public class HeapElement {
// Constructors
/**
* @param key : a number of primitive type 'double'
* @param info : any kind of IMMUTABLE object. May be null, since the
* purpose is only to carry additional information of use for the user
* Creates a HeapElement with the specified key and additional information.
*
* @param key the key of the element (primitive type double)
* @param info any immutable object containing additional information, may be null
*/
public HeapElement(double key, Object info) {
this.key = key;
@ -29,9 +40,10 @@ public class HeapElement {
}
/**
* @param key : a number of primitive type 'int'
* @param info : any kind of IMMUTABLE object. May be null, since the
* purpose is only to carry additional information of use for the user
* Creates a HeapElement with the specified key and additional information.
*
* @param key the key of the element (primitive type int)
* @param info any immutable object containing additional information, may be null
*/
public HeapElement(int key, Object info) {
this.key = key;
@ -39,9 +51,10 @@ public class HeapElement {
}
/**
* @param key : a number of object type 'Integer'
* @param info : any kind of IMMUTABLE object. May be null, since the
* purpose is only to carry additional information of use for the user
* Creates a HeapElement with the specified key and additional information.
*
* @param key the key of the element (object type Integer)
* @param info any immutable object containing additional information, may be null
*/
public HeapElement(Integer key, Object info) {
this.key = key;
@ -49,9 +62,10 @@ public class HeapElement {
}
/**
* @param key : a number of object type 'Double'
* @param info : any kind of IMMUTABLE object. May be null, since the
* purpose is only to carry additional information of use for the user
* Creates a HeapElement with the specified key and additional information.
*
* @param key the key of the element (object type Double)
* @param info any immutable object containing additional information, may be null
*/
public HeapElement(Double key, Object info) {
this.key = key;
@ -59,7 +73,9 @@ public class HeapElement {
}
/**
* @param key : a number of primitive type 'double'
* Creates a HeapElement with the specified key.
*
* @param key the key of the element (primitive type double)
*/
public HeapElement(double key) {
this.key = key;
@ -67,7 +83,9 @@ public class HeapElement {
}
/**
* @param key : a number of primitive type 'int'
* Creates a HeapElement with the specified key.
*
* @param key the key of the element (primitive type int)
*/
public HeapElement(int key) {
this.key = key;
@ -75,7 +93,9 @@ public class HeapElement {
}
/**
* @param key : a number of object type 'Integer'
* Creates a HeapElement with the specified key.
*
* @param key the key of the element (object type Integer)
*/
public HeapElement(Integer key) {
this.key = key;
@ -83,7 +103,9 @@ public class HeapElement {
}
/**
* @param key : a number of object type 'Double'
* Creates a HeapElement with the specified key.
*
* @param key the key of the element (object type Double)
*/
public HeapElement(Double key) {
this.key = key;
@ -92,46 +114,57 @@ public class HeapElement {
// Getters
/**
* @return the object containing the additional info provided by the user.
* Returns the object containing the additional information provided by the user.
*
* @return the additional information
*/
public Object getInfo() {
return additionalInfo;
}
/**
* @return the key value of the element
* Returns the key value of the element.
*
* @return the key of the element
*/
public double getKey() {
return key;
}
// Overridden object methods
/**
* Returns a string representation of the heap element.
*
* @return a string describing the key and additional information
*/
@Override
public String toString() {
return "Key: " + key + " - " + additionalInfo.toString();
return "Key: " + key + " - " + (additionalInfo != null ? additionalInfo.toString() : "No additional info");
}
/**
* @param otherHeapElement
* @return true if the keys on both elements are identical and the
* additional info objects are identical.
* Compares this heap element to another object for equality.
*
* @param o the object to compare with
* @return true if the keys and additional information are identical, false otherwise
*/
@Override
public boolean equals(Object o) {
if (o != null) {
if (!(o instanceof HeapElement)) {
return false;
}
HeapElement otherHeapElement = (HeapElement) o;
return ((this.key == otherHeapElement.key) && (this.additionalInfo.equals(otherHeapElement.additionalInfo)));
if (o instanceof HeapElement otherHeapElement) {
return this.key == otherHeapElement.key && (this.additionalInfo != null ? this.additionalInfo.equals(otherHeapElement.additionalInfo) : otherHeapElement.additionalInfo == null);
}
return false;
}
/**
* Returns a hash code value for the heap element.
*
* @return a hash code value for this heap element
*/
@Override
public int hashCode() {
int result = 0;
result = 31 * result + (int) key;
result = 31 * result + (additionalInfo != null ? additionalInfo.hashCode() : 0);
int result = 31 * (int) key;
result += (additionalInfo != null) ? additionalInfo.hashCode() : 0;
return result;
}
}