diff --git a/src/main/kotlin/com/nodrex/datamatrix/DataMatrix.java b/src/main/kotlin/com/nodrex/datamatrix/DataMatrix.java index d3aa850..2ddd506 100644 --- a/src/main/kotlin/com/nodrex/datamatrix/DataMatrix.java +++ b/src/main/kotlin/com/nodrex/datamatrix/DataMatrix.java @@ -10,16 +10,23 @@ * This class contains useful methods to manipulate on data of matrix type. *

*

- * Implements Serializable , Comparable , Cloneable interfaces. + * Implements {@link java.io.Serializable}, {@link Comparable}, and {@link Cloneable} interfaces. *

*

* Can be extended by any class. *

+ *

+ * Written for JDK 1.7. + *

* - * @param Any type can be stored. + * @param Any type can be stored. * @author NODREX * @version 1.0 * @since 2013 + * @see IDataMatrix + * @see java.io.Serializable + * @see Comparable + * @see Cloneable */ public class DataMatrix implements IDataMatrix { @@ -53,14 +60,24 @@ protected interface ExceptionMessages extends java.io.Serializable { protected static final List ids = new ArrayList(); /** - * @return copy of this matrix. + * Creates and returns a copy of this object. + * + * @return a clone of this instance. + * @throws CloneNotSupportedException if the object's class does not support the {@code Cloneable} interface. + * Subclasses that override the {@code clone} method can also throw this exception + * to indicate that an instance cannot be cloned. + * @see java.lang.Cloneable */ protected IDataMatrix clone() throws CloneNotSupportedException { return new DataMatrix(this); } /** - * Removes id of this matrix form ids list. + * Called by the garbage collector on an object when garbage collection + * determines that there are no more references to the object. + * Removes the ID of this matrix from the static list of IDs. + * + * @throws Throwable the {@code Exception} raised by this method */ protected void finalize() throws Throwable { if (this.id.equals("")) return; @@ -68,14 +85,23 @@ protected void finalize() throws Throwable { } /** - * Changes dimensions and data reference. also calls garbage collector.
- * If you want to change references of data i recommend to use this - * method. + * Efficiently changes the dimensions and data reference of this matrix to match the given matrix. + * This method directly assigns the internal data structures of the provided matrix to this matrix + * and then nullifies the reference to the temporary matrix, suggesting it for garbage collection. + *

+ * Note: This method is intended for performance-critical scenarios. + * It is recommended that this method be considered final in subclasses to avoid potential issues. + *

*

- * Content:
this.linedimension = tempDataMatrix.linedimension;
- * this.columndimension = tempDataMatrix.columndimension;
this.data = - * tempDataMatrix.data;
tempDataMatrix = null;
System.gc();
+ * Operations performed:
+ * {@code this.linedimension = tempDataMatrix.getLineDimension();}
+ * {@code this.columndimension = tempDataMatrix.getColumnDimension();}
+ * {@code this.data = ((DataMatrix)tempDataMatrix).data;}
+ * {@code tempDataMatrix = null;}
+ * {@code System.gc();}
*

+ * @param tempDataMatrix The matrix whose content will replace the current matrix's content. + * After the operation, this reference is set to null. */ protected void changeContentQuickly(IDataMatrix tempDataMatrix) { this.linedimension = tempDataMatrix.getLineDimension(); @@ -112,43 +138,49 @@ public String toString() { } /** - * Compares 2 matrixes. - * - * @return true if both matrixes have same dimension and same data, - * otherwise returns false. + * Compares this matrix with the specified object for equality. + * Returns {@code true} if the given object is also a {@code DataMatrix}, and the two + * matrices have the same dimensions and all corresponding elements are equal. + * + * @param obj the object to be compared for equality with this matrix. + * @return {@code true} if the specified object is equal to this matrix, {@code false} otherwise. */ public boolean equals(Object obj) { - if (obj == null) return false; - if (obj instanceof DataMatrix) { - try { - @SuppressWarnings("unchecked") - DataMatrix variable = (DataMatrix) obj; - if (!isDimensionsEqualTo(variable.linedimension, - variable.columndimension)) + if (obj == null) return false; // Handles null comparison as per TODO + if (this == obj) return true; + if (!(obj instanceof DataMatrix)) return false; + + @SuppressWarnings("unchecked") + DataMatrix other = (DataMatrix) obj; + + if (!isDimensionsEqualTo(other.linedimension, other.columndimension)) { + return false; + } + + for (int i = 0; i < this.linedimension; i++) { + for (int j = 0; j < this.columndimension; j++) { + if (this.data[i][j] == null) { + if (other.data[i][j] != null) return false; + } else if (!this.data[i][j].equals(other.data[i][j])) { return false; - for (int i = 0; i < variable.linedimension; i++) { - for (int j = 0; j < variable.columndimension; j++) { - if (!(this.data[i][j].equals(variable.data[i][j]))) { - return false; - } - } } - } catch (Exception e) { - return false; } } return true; } /** - * Compares with number of elements. - *

- * If this matrix elements are less then given matrix returns -1 , if both - * matrix elements are equal returns 0 , otherwise returns 1. - *

+ * Compares this matrix with the specified matrix for order based on the number of elements. + * Returns a negative integer, zero, or a positive integer as this matrix + * has fewer, equal to, or more elements than the specified matrix. + * + * @param iDataMatrix the matrix to be compared. + * @return a negative integer, zero, or a positive integer as this matrix + * has fewer, equal to, or more elements than the specified matrix. + * @see Comparable */ public int compareTo(IDataMatrix iDataMatrix) { - return this.getNumberOfElements() - iDataMatrix.getNumberOfElements(); + return Integer.compare(this.getNumberOfElements(), iDataMatrix.getNumberOfElements()); } @SuppressWarnings("unchecked") @@ -388,14 +420,16 @@ private void fillTempDataMatrixWithGivenDataOnGivenIndexes( } /** - * Creates Matrix with one data which will be null. + * Creates a 1x1 matrix with a null element. */ public DataMatrix() { init(1, 1); } /** - * Creates Matrix with one data and fills with default value that you gave. + * Creates a 1x1 matrix and initializes it with the given default value. + * + * @param defaultValue The value to fill the matrix with. */ public DataMatrix(Data defaultValue) { init(1, 1); @@ -403,12 +437,11 @@ public DataMatrix(Data defaultValue) { } /** - * Creates Matrix with dimensions that you gave and all data automatically - * will be null. - * - * @throws IllegalArgumentException - * if given lineDimension or columnDimension are negative or - * zero. + * Creates a matrix with the specified dimensions. All elements are initialized to null. + * + * @param lineDimension The number of lines (rows) in the matrix. + * @param columnDimension The number of columns in the matrix. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. */ public DataMatrix(int lineDimension, int columnDimension) throws IllegalArgumentException { @@ -416,36 +449,35 @@ public DataMatrix(int lineDimension, int columnDimension) } /** - * Creates Matrix with dimensions that you gave and feels with default value - * that you gave. - * - * @throws IllegalArgumentException - * if given lineDimension or columnDimension are negative or - * zero. + * Creates a matrix with the specified dimensions and fills it with the given default value. + * + * @param lineDimension The number of lines (rows) in the matrix. + * @param columnDimension The number of columns in the matrix. + * @param defaultValue The value to fill the matrix with. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. */ - public DataMatrix(int lineDimension, int columnDimension, Data DefaultValue) + public DataMatrix(int lineDimension, int columnDimension, Data defaultValue) throws IllegalArgumentException { init(lineDimension, columnDimension); - defaultFill(DefaultValue); + defaultFill(defaultValue); } /** - * Creates square matrix with dimension that you gave and all data - * automatically will be null. - * - * @throws IllegalArgumentException - * if given squareDimensioni is negative or zero. + * Creates a square matrix with the specified dimension. All elements are initialized to null. + * + * @param squareDimension The dimension (number of lines and columns) of the square matrix. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ public DataMatrix(int squareDimension) throws IllegalArgumentException { init(squareDimension, squareDimension); } /** - * Creates square matrix with dimension that you gave and fills with default - * value that you gave. - * - * @throws IllegalArgumentException - * if given squareDimension is negative or zero. + * Creates a square matrix with the specified dimension and fills it with the given default value. + * + * @param squareDimension The dimension (number of lines and columns) of the square matrix. + * @param defaultValue The value to fill the matrix with. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ public DataMatrix(int squareDimension, Data defaultValue) throws IllegalArgumentException { @@ -454,86 +486,57 @@ public DataMatrix(int squareDimension, Data defaultValue) } /** - * Creates copy of given data matrix. - *

- * This constructor does not copy id of given matrix, because id should be - * unique. - *

- * - * @throws NullPointerException - * if given matrix is null. + * Creates a copy of the given data matrix. + * The ID of the given matrix is not copied, as IDs must be unique. + * + * @param matrix The matrix to copy. + * @throws NullPointerException if the given {@code matrix} is null. */ @SuppressWarnings("unchecked") public DataMatrix(IDataMatrix matrix) throws NullPointerException { + if (matrix == null) throw new NullPointerException("Input matrix cannot be null."); this.init(matrix.getLineDimension(), matrix.getColumnDimension()); - this.fill((Data[][]) matrix.getData()); + this.fill((Data[][]) matrix.getData()); // Assumes getData() returns a compatible array type. this.name = new String(matrix.getName()); } /** - * Creates matrix and fills with data that you gave. - *

- * This constructor takes dimensions from given data automatically. - *

- *

- * Example: - *

+ * Creates a matrix and fills it with the data from the given 2D array. + * The dimensions of the matrix are determined by the structure of the input array. + * If the input array is jagged (arrays within the array have different lengths), + * the matrix column dimension will be set to the maximum length found. + * Missing elements in shorter rows will be {@code null}. *

- * DataMatrix<> dataMatrix = new DataMatrix<>(new - * Data[]{value_2,value_2,value_3},new Data[]{value_4,value_5,value_6}) - *

- *

- * It will create dataMatrix with dimensions: line dimension 2 and column - * dimension 3 - *

+ * Example 1 (Array of arrays): + * 
{@code
+	 * DataMatrix matrix = new DataMatrix<>(
+	 *     new String[]{"a", "b", "c"},
+	 *     new String[]{"d", "e", "f"}
+	 * );
+	 * // Result: 2x3 matrix
+	 * }
*

- * Example 2: - *

- *

- * DataMatrix<> dataMatrix = new DataMatrix<>(new Data[][]{new - * Data[]{value_1,value_2,value_3}, new Data[]{value_4,value_5,value_6}, new - * Data[]{value_7,value_8,value_9}} - *

- *

- * It will create dataMatrix with dimensions: line dimension 3 and column - * dimension 3 - *

- * - *

- * You also can gave jagged array, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - *

- * For example if you gave: new - * Data[][]{{value_1},{value_2,value_3,value_4},{value_5,value_6}} then - * result will be : - *

- * Matrix 3 X 3
value_1 null null
value_2 value_3 value_4
- * value_5 value_6 null - *

- * - * @param data - * can be: - *

- * (new Data[]{value_1,value_2,value_3}, ...) - *

- * or - *

- * (new Data[][]{new Data[]{value_1,value_2,value_3}, ...}) - *

- * or - *

- * (new Data[][]{new Data[]{value_1,value_2,value_3},new - * Data[]{value_4,value_5,value_6},...}) - *

{@code + * DataMatrix matrix = new DataMatrix<>( + * new Integer[]{1}, + * new Integer[]{2, 3, 4}, + * new Integer[]{5, 6} + * ); + * // Result: 3x3 matrix: + * // 1 null null + * // 2 3 4 + * // 5 6 null + * } + * + * @param data A varargs 2D array (Data[][]) or an array of 1D arrays (Data[]...). + * Cannot be null, but can be empty or contain null arrays/elements. + * @throws NullPointerException if {@code data} is null. */ @SuppressWarnings("unchecked") public DataMatrix(Data[]... data) throws NullPointerException { - List lengthList = new ArrayList( - data.length); + if (data == null) throw new NullPointerException("Input data array cannot be null."); + List lengthList = new ArrayList(data.length); for (int i = 0; i < data.length; i++) { lengthList.add(data[i].length); } @@ -542,40 +545,36 @@ public DataMatrix(Data[]... data) throws NullPointerException { } /** - * Creates matrix and fills with data that you gave. - *

- * This constructor takes dimensions from given data automatically. - *

- * - *

- * You also can gave jagged data, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - * @throws NullPointerException - * if given data is null. - * - * @throws IllegalArgumentException - * if data is not filled at least with one element. + * Creates a matrix and fills it with data from the given list of lists. + * The dimensions of the matrix are determined by the structure of the input list. + * If the inner lists have different sizes, the matrix column dimension will be + * set to the maximum size found. Missing elements in shorter rows will be {@code null}. + * + * @param data A list of lists representing the matrix data. Cannot be null. + * @throws NullPointerException if {@code data} is null. + * @throws IllegalArgumentException if {@code data} is empty (contains no rows). */ public DataMatrix(List> data) throws NullPointerException, IllegalArgumentException { + if (data == null) throw new NullPointerException("Input data list cannot be null."); + if (data.isEmpty()) throw new IllegalArgumentException(ExceptionMessages.PLEASE_FILL); copy(data); } /** - * Reads data from file as DataMatrix , so Serializable data in file should - * be DataMatrix type. - * - * @throws NullPointerException - * if fileName or readDataType is null. - * @throws IOException - * @throws ClassNotFoundException - * if data is not DataMatrix type. + * Creates a {@code DataMatrix} by deserializing it from a file. + * The file is expected to contain a serialized {@code DataMatrix} object. + * + * @param fileName The name of the file to read the matrix from. + * @throws NullPointerException if {@code fileName} is null. + * @throws java.io.IOException if an I/O error occurs while reading from the file. + * @throws ClassNotFoundException if the class of the serialized object cannot be found, + * or if the object in the file is not a {@code DataMatrix}. */ @SuppressWarnings("unchecked") public DataMatrix(String fileName) throws NullPointerException, java.io.IOException, ClassNotFoundException { + if (fileName == null) throw new NullPointerException("fileName cannot be null."); java.io.InputStream file = new java.io.FileInputStream(fileName); java.io.InputStream buffer = new java.io.BufferedInputStream(file); java.io.ObjectInput input = new java.io.ObjectInputStream(buffer); @@ -808,6 +807,13 @@ public void setLastElement(Data value) { this.data[this.linedimension - 1][this.columndimension - 1] = value; } + /** + * Fills the entire matrix with the specified default value. + * Note: It is recommended that this method be considered final in subclasses + * if it's called from constructors, to prevent issues with uninitialized state in derived classes. + * + * @param defaultValue the value to set for all elements in the matrix. + */ public void defaultFill(Data defaultValue) { for (int i = 0; i < this.linedimension; i++) { for (int j = 0; j < this.columndimension; j++) { @@ -816,6 +822,15 @@ public void defaultFill(Data defaultValue) { } } + /** + * Replaces the content of this matrix (data, name, and ID) with the provided values. + * + * @param data The new 2D array data for the matrix. Dimensions will be inferred. + * @param name The new name for the matrix. + * @param id The new unique ID for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. + * @throws IllegalArgumentException if {@code id} is null, empty, or not unique. + */ public void changeContent(Data[][] data, String name, String id) throws NullPointerException, IllegalArgumentException { this.setData(data); @@ -823,47 +838,98 @@ public void changeContent(Data[][] data, String name, String id) this.setId(id); } + /** + * Replaces the content of this matrix (data, name, and ID) with the provided values. + * + * @param data The new list of lists data for the matrix. Dimensions will be inferred. + * @param name The new name for the matrix. + * @param id The new unique ID for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. + * @throws IllegalArgumentException if {@code data} is empty, or if {@code id} is null, empty, or not unique. + */ public void changeContent(List> data, String name, String id) throws NullPointerException, IllegalArgumentException { copy(data); - this.name = name; + this.name = name; // Assuming setName handles null if necessary, or add check this.setId(id); } + /** + * Replaces the data and name of this matrix. The ID remains unchanged. + * + * @param data The new 2D array data for the matrix. Dimensions will be inferred. + * @param name The new name for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. + */ public void changeContent(Data[][] data, String name) throws NullPointerException { this.setData(data); - this.name = name; + this.name = name; // Assuming setName handles null } + /** + * Replaces the data and name of this matrix. The ID remains unchanged. + * + * @param data The new list of lists data for the matrix. Dimensions will be inferred. + * @param name The new name for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. + * @throws IllegalArgumentException if {@code data} is empty. + */ public void changeContent(List> data, String name) throws NullPointerException, IllegalArgumentException { this.copy(data); - this.name = name; + this.name = name; // Assuming setName handles null } + /** + * Replaces the data of this matrix with the given 2D array. + * The name and ID remain unchanged. + * + * @param data The new 2D array data for the matrix. + * @throws NullPointerException if {@code data} is null. + */ @SuppressWarnings("unchecked") public void changeContent(Data[]... data) throws NullPointerException { this.changeContent(data, this.name); } + /** + * Replaces the data of this matrix with the given list of lists. + * The name and ID remain unchanged. + * + * @param data The new list of lists data for the matrix. + * @throws NullPointerException if {@code data} is null. + * @throws IllegalArgumentException if {@code data} is empty. + */ public void changeContent(List> data) throws NullPointerException, IllegalArgumentException { this.changeContent(data, this.name); } + /** + * Clears the matrix by re-initializing all its elements to {@code null}, + * preserving its current dimensions. + */ public void clean() { - init(this.linedimension, this.columndimension); + init(this.linedimension, this.columndimension); // Re-initializes with nulls } + /** + * Resizes the matrix to the specified dimensions. + * If the new dimensions are smaller, data is truncated. + * If the new dimensions are larger, new elements are filled with {@code null}. + * + * @param lineDimension The new number of lines (rows). + * @param columnDimension The new number of columns. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. + */ public void resize(int lineDimension, int columnDimension) throws IllegalArgumentException { checkArguments(lineDimension, columnDimension); if (isDimensionsEqualTo(lineDimension, columnDimension)) return; - DataMatrix tempDataMatrix = new DataMatrix(lineDimension, - columnDimension); + DataMatrix tempDataMatrix = new DataMatrix(lineDimension, columnDimension); for (int i = 0; i < Math.min(lineDimension, this.linedimension); i++) { for (int j = 0; j < Math.min(columnDimension, this.columndimension); j++) { tempDataMatrix.data[i][j] = this.data[i][j]; @@ -872,58 +938,72 @@ public void resize(int lineDimension, int columnDimension) changeContentQuickly(tempDataMatrix); } + /** + * Resizes the matrix to a square matrix of the specified dimension. + * If the new dimension is smaller, data is truncated. + * If the new dimension is larger, new elements are filled with {@code null}. + * + * @param squareDimension The new number of lines and columns. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. + */ public void resize(int squareDimension) throws IllegalArgumentException { resize(squareDimension, squareDimension); } + /** + * Resizes the matrix to the specified dimensions. + * If the new dimensions are smaller, data is truncated. + * If the new dimensions are larger, new elements are filled with the {@code defaultValue}. + * + * @param lineDimension The new number of lines (rows). + * @param columnDimension The new number of columns. + * @param defaultValue The value to fill new elements with if the matrix is enlarged. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. + */ public void resize(int lineDimension, int columnDimension, Data defaultValue) throws IllegalArgumentException { - int startlinedimension = this.linedimension; - int startcolumndimension = this.columndimension; - resize(lineDimension, columnDimension); - - if (startlinedimension >= this.linedimension - && startcolumndimension >= this.columndimension) { - return; - } - - if (startlinedimension <= this.linedimension - && startcolumndimension <= this.columndimension) { - for (int i = 0; i < this.linedimension; i++) { - for (int j = startcolumndimension; j < this.columndimension; j++) { - this.data[i][j] = defaultValue; + int oldLineDimension = this.linedimension; + int oldColumnDimension = this.columndimension; + resize(lineDimension, columnDimension); // Resizes and fills with null where new + + // Fill new cells if expanded + if (lineDimension > oldLineDimension || columnDimension > oldColumnDimension) { + for (int i = 0; i < lineDimension; i++) { + for (int j = 0; j < columnDimension; j++) { + if (i >= oldLineDimension || j >= oldColumnDimension) { + if (this.data[i][j] == null) { // Only fill if it was part of the new area + this.data[i][j] = defaultValue; + } + } } - if (i == (startlinedimension - 1)) - startcolumndimension = 0; } - return; } - - else if (startlinedimension >= this.linedimension - && startcolumndimension <= this.columndimension) { - for (int i = 0; i < this.linedimension; i++) - for (int j = startcolumndimension; j < this.columndimension; j++) - this.data[i][j] = defaultValue; - return; - } - - else { - for (int i = startlinedimension; i < this.linedimension; i++) - for (int j = 0; j < this.columndimension; j++) - this.data[i][j] = defaultValue; - } - System.gc(); + // System.gc(); // Generally not recommended to call System.gc() explicitly } + /** + * Resizes the matrix to a square matrix of the specified dimension. + * If the new dimension is smaller, data is truncated. + * If the new dimension is larger, new elements are filled with the {@code defaultValue}. + * + * @param squareDimension The new number of lines and columns. + * @param defaultValue The value to fill new elements with if the matrix is enlarged. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. + */ public void resize(int squareDimension, Data defaultValue) throws IllegalArgumentException { resize(squareDimension, squareDimension, defaultValue); } + /** + * Returns the content of the matrix as a {@code List} of {@code List}s of {@code Data}. + * Each inner list represents a row. + * + * @return A list of lists representing the matrix data. + */ public List> getDataAsList() { - List> listDataMatrix = new ArrayList>( - this.linedimension); - List innerlist = null; + List> listDataMatrix = new ArrayList<>(this.linedimension); + List innerlist; for (int i = 0; i < this.linedimension; i++) { innerlist = new ArrayList(this.columndimension); for (int j = 0; j < this.columndimension; j++) { @@ -934,37 +1014,68 @@ public List> getDataAsList() { return listDataMatrix; } + /** + * Copies the data from the given list of lists into this matrix, resizing it accordingly. + * If the inner lists have different sizes, the matrix column dimension will be + * set to the maximum size found. Missing elements in shorter rows will be {@code null}. + * Note: It is recommended that this method be considered final in subclasses + * if it's called from constructors or other methods that rely on its specific behavior for initialization. + * + * @param data The list of lists to copy data from. + * @throws NullPointerException if {@code data} is null or contains null rows. + * @throws IllegalArgumentException if {@code data} is empty (contains no rows). + */ public void copy(List> data) throws NullPointerException, IllegalArgumentException { - if (data.size() == 0) { + if (data == null) throw new NullPointerException("Input data list cannot be null."); + if (data.isEmpty()) { throw new IllegalArgumentException(ExceptionMessages.PLEASE_FILL); } - List lengthList = new ArrayList( - data.size()); - for (int i = 0; i < data.size(); i++) { - lengthList.add(data.get(i).size()); + List lengthList = new ArrayList<>(data.size()); + for (List row : data) { + if (row == null) throw new NullPointerException("Row in data list cannot be null."); + lengthList.add(row.size()); } - init(data.size(), Collections.max(lengthList)); + init(data.size(), lengthList.isEmpty() ? 0 : Collections.max(lengthList)); for (int i = 0; i < data.size(); i++) { - for (int j = 0; j < data.get(i).size(); j++) { - this.data[i][j] = data.get(i).get(j); + List row = data.get(i); + for (int j = 0; j < row.size(); j++) { + this.data[i][j] = row.get(j); } } - System.gc(); + // System.gc(); // Generally not recommended } + /** + * Copies the data from the given {@code IDataMatrix} into this matrix, resizing it accordingly. + * + * @param matrix The matrix to copy data from. + * @throws NullPointerException if {@code matrix} is null. + */ @SuppressWarnings("unchecked") public void copy(IDataMatrix matrix) throws NullPointerException { - this.setData((Data[][]) matrix.getData()); - System.gc(); + if (matrix == null) throw new NullPointerException("Input matrix cannot be null."); + // Assuming setData handles the internal array copying correctly + this.setData((Data[][]) matrix.getData()); // This might need a safer way to copy + // System.gc(); // Generally not recommended } + /** + * Copies the data from the given 2D array into this matrix, resizing it accordingly. + * + * @param data The 2D array to copy data from. + * @throws NullPointerException if {@code data} is null. + */ @SuppressWarnings("unchecked") public void copy(Data[]... data) throws NullPointerException { + if (data == null) throw new NullPointerException("Input data array cannot be null."); this.setData(data); - System.gc(); + // System.gc(); // Generally not recommended } + /** + * Adds a new empty line (filled with nulls) at the end of the matrix. + */ public void addLine() { resize(this.linedimension + 1, this.columndimension); } @@ -986,6 +1097,11 @@ public void addLine(List lineList) setLine(this.linedimension - 1, lineList); } + /** + * Removes the last line from the matrix. + * + * @throws IllegalArgumentException if the matrix has only one line and cannot be removed. + */ public void removeLine() throws IllegalArgumentException { if (this.linedimension - 1 <= 0) { throw new IllegalArgumentException(ExceptionMessages.ONLY_ONE_LINE); @@ -993,48 +1109,84 @@ public void removeLine() throws IllegalArgumentException { resize(this.linedimension - 1, this.columndimension); } + /** + * Adds a new empty column (filled with nulls) at the end of the matrix. + */ public void addColumn() { resize(this.linedimension, this.columndimension + 1); } + /** + * Adds a new column at the end of the matrix, initialized with the values from {@code columnArray}. + * If {@code columnArray} is shorter than the matrix's line dimension, remaining cells are null. + * If longer, extra values are ignored. + * + * @param columnArray The array of data to fill the new column. + * @throws NullPointerException if {@code columnArray} is null. + */ @SuppressWarnings("unchecked") public void addColumn(Data... columnArray) throws NullPointerException { + if (columnArray == null) throw new NullPointerException("columnArray cannot be null."); addColumn(); setColumn(this.columndimension - 1, columnArray); } - public void addColumn(Data defaultvalue) { + /** + * Adds a new column at the end of the matrix, filled with {@code defaultValue}. + * + * @param defaultValue The value to fill the new column with. + */ + public void addColumn(Data defaultValue) { addColumn(); - setColumn(this.columndimension - 1, defaultvalue); + setColumn(this.columndimension - 1, defaultValue); } + /** + * Adds a new column at the end of the matrix, initialized with values from {@code columnList}. + * If {@code columnList} is shorter than the matrix's line dimension, remaining cells are null. + * If longer, extra values are ignored. + * + * @param columnList The list of data to fill the new column. + * @throws NullPointerException if {@code columnList} is null. + */ public void addColumn(List columnList) throws NullPointerException { + if (columnList == null) throw new NullPointerException("columnList cannot be null."); addColumn(); setColumn(this.columndimension - 1, columnList); } + /** + * Removes the last column from the matrix. + * + * @throws IllegalArgumentException if the matrix has only one column and cannot be removed. + */ public void removeColumn() throws IllegalArgumentException { if (this.columndimension - 1 <= 0) { - throw new IllegalArgumentException( - ExceptionMessages.ONLY_ONE_COLUMN); + throw new IllegalArgumentException(ExceptionMessages.ONLY_ONE_COLUMN); } resize(this.linedimension, this.columndimension - 1); } + /** + * Inserts an empty line (filled with nulls) at the specified index. + * If {@code index} is negative, lines are added at the beginning. + * If {@code index} is greater than the current line dimension, lines are added at the end. + * + * @param index The index at which to insert the new line. + */ public void insertLine(int index) { if (index < 0) { - DataMatrix tempDataMatrix = new DataMatrix( - (index * -1), columndimension); - tempDataMatrix.addMatrixAtLine(this); + DataMatrix tempDataMatrix = new DataMatrix<>((index * -1), columndimension); + tempDataMatrix.addMatrixAtLine(this); // This seems to imply adding current matrix content after new empty lines changeContentQuickly(tempDataMatrix); return; } - int addlineindex = 1; - if (index > this.linedimension) - addlineindex = index - (this.linedimension - 1); - DataMatrix tempDataMatrix = new DataMatrix( - this.linedimension + addlineindex, this.columndimension); + int linesToAdd = 1; + if (index > this.linedimension) { + linesToAdd = index - this.linedimension + 1; + } + DataMatrix tempDataMatrix = new DataMatrix<>(this.linedimension + linesToAdd, this.columndimension); for (int i = 0; i < this.linedimension; i++) for (int j = 0; j < tempDataMatrix.columndimension; j++) { if (i >= index) { @@ -1046,44 +1198,76 @@ public void insertLine(int index) { changeContentQuickly(tempDataMatrix); } + /** + * Inserts a line filled with {@code defaultValue} at the specified index. + * + * @param index The index at which to insert the new line. + * @param defaultValue The value to fill the new line with. + */ public void insertLine(int index, Data defaultValue) { int oldLineDimension = this.linedimension; - insertLine(index); - if (index >= 0) { - setLine(index, defaultValue); + insertLine(index); // Creates space, shifts elements + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.linedimension -1) ; // Correct index after potential resize + if (index >= 0 && actualInsertIndex < this.linedimension) { + setLine(actualInsertIndex, defaultValue); } + // fillLeftLines might be redundant or needs re-evaluation based on insertLine's new behavior fillLeftLines(oldLineDimension, index, defaultValue); } + /** + * Inserts a line initialized with {@code lineArray} at the specified index. + * + * @param index The index at which to insert the new line. + * @param lineArray The data for the new line. + * @throws NullPointerException if {@code lineArray} is null. + */ @SuppressWarnings("unchecked") public void insertLine(int index, Data... lineArray) throws NullPointerException { + if (lineArray == null) throw new NullPointerException("lineArray cannot be null."); int oldLineDimension = this.linedimension; insertLine(index); - if (index >= 0) { - setLine(index, lineArray); + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.linedimension -1) ; + if (index >= 0 && actualInsertIndex < this.linedimension) { + setLine(actualInsertIndex, lineArray); } fillLeftLines(oldLineDimension, index, lineArray); } + /** + * Inserts a line initialized with {@code lineList} at the specified index. + * + * @param index The index at which to insert the new line. + * @param lineList The data for the new line. + * @throws NullPointerException if {@code lineList} is null. + */ public void insertLine(int index, List lineList) throws NullPointerException { + if (lineList == null) throw new NullPointerException("lineList cannot be null."); int oldLineDimension = this.linedimension; insertLine(index); - if (index >= 0) { - setLine(index, lineList); + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.linedimension -1) ; + if (index >= 0 && actualInsertIndex < this.linedimension) { + setLine(actualInsertIndex, lineList); } fillLeftLines(oldLineDimension, index, lineList); } + /** + * Removes the line at the specified index. + * + * @param index The index of the line to remove. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of bounds. + * @throws IllegalArgumentException if the matrix has only one line. + */ public void removeLine(int index) throws ArrayIndexOutOfBoundsException, IllegalArgumentException { checkLineIndex(index); if (this.getLineDimension() - 1 <= 0) { throw new IllegalArgumentException(ExceptionMessages.ONLY_ONE_LINE); } - DataMatrix tempDataMatrix = new DataMatrix( - this.getLineDimension() - 1, this.getColumnDimension()); + DataMatrix tempDataMatrix = new DataMatrix<>(this.getLineDimension() - 1, this.getColumnDimension()); for (int i = 0; i < tempDataMatrix.getLineDimension(); i++) for (int j = 0; j < tempDataMatrix.getColumnDimension(); j++) { if (i >= index) { @@ -1095,20 +1279,25 @@ public void removeLine(int index) throws ArrayIndexOutOfBoundsException, changeContentQuickly(tempDataMatrix); } + /** + * Inserts an empty column (filled with nulls) at the specified index. + * If {@code index} is negative, columns are added at the beginning. + * If {@code index} is greater than the current column dimension, columns are added at the end. + * + * @param index The index at which to insert the new column. + */ public void insertColumn(int index) { if (index < 0) { - DataMatrix tempDataMatrix = new DataMatrix( - linedimension, (index * -1)); - tempDataMatrix.addMatrixAtcolumn(this); + DataMatrix tempDataMatrix = new DataMatrix<>(linedimension, (index * -1)); + tempDataMatrix.addMatrixAtcolumn(this); // Similar logic to insertLine for negative index changeContentQuickly(tempDataMatrix); return; } - int addcolumnindex = 1; - if (index > this.getColumnDimension()) - addcolumnindex = index - (this.getColumnDimension() - 1); - DataMatrix tempDataMatrix = new DataMatrix( - this.getLineDimension(), this.getColumnDimension() - + addcolumnindex); + int columnsToAdd = 1; + if (index > this.getColumnDimension()) { + columnsToAdd = index - this.getColumnDimension() + 1; + } + DataMatrix tempDataMatrix = new DataMatrix<>(this.getLineDimension(), this.getColumnDimension() + columnsToAdd); for (int i = 0; i < tempDataMatrix.getLineDimension(); i++) for (int j = 0; j < this.getColumnDimension(); j++) { if (j >= index) { @@ -1120,45 +1309,75 @@ public void insertColumn(int index) { changeContentQuickly(tempDataMatrix); } + /** + * Inserts a column filled with {@code defaultValue} at the specified index. + * + * @param index The index at which to insert the new column. + * @param defaultValue The value to fill the new column with. + */ public void insertColumn(int index, Data defaultValue) { int oldColumnDimension = this.columndimension; insertColumn(index); - if (index >= 0) { - setColumn(index, defaultValue); + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.columndimension -1); + if (index >= 0 && actualInsertIndex < this.columndimension) { + setColumn(actualInsertIndex, defaultValue); } fillLeftColumns(oldColumnDimension, index, defaultValue); } + /** + * Inserts a column initialized with {@code columnArray} at the specified index. + * + * @param index The index at which to insert the new column. + * @param columnArray The data for the new column. + * @throws NullPointerException if {@code columnArray} is null. + */ @SuppressWarnings("unchecked") public void insertColumn(int index, Data... columnArray) throws NullPointerException { + if (columnArray == null) throw new NullPointerException("columnArray cannot be null."); int oldColumnDimension = this.columndimension; insertColumn(index); - if (index >= 0) { - setColumn(index, columnArray); + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.columndimension -1); + if (index >= 0 && actualInsertIndex < this.columndimension) { + setColumn(actualInsertIndex, columnArray); } fillLeftColumns(oldColumnDimension, index, columnArray); } + /** + * Inserts a column initialized with {@code columnList} at the specified index. + * + * @param index The index at which to insert the new column. + * @param columnList The data for the new column. + * @throws NullPointerException if {@code columnList} is null. + */ public void insertColumn(int index, List columnList) throws NullPointerException { + if (columnList == null) throw new NullPointerException("columnList cannot be null."); int oldColumnDimension = this.columndimension; insertColumn(index); - if (index >= 0) { - setColumn(index, columnList); + int actualInsertIndex = (index < 0) ? 0 : Math.min(index, this.columndimension -1); + if (index >= 0 && actualInsertIndex < this.columndimension) { + setColumn(actualInsertIndex, columnList); } fillLeftColumns(oldColumnDimension, index, columnList); } + /** + * Removes the column at the specified index. + * + * @param index The index of the column to remove. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of bounds. + * @throws IllegalArgumentException if the matrix has only one column. + */ public void removeColumn(int index) throws ArrayIndexOutOfBoundsException, IllegalArgumentException { checkColumnIndex(index); if (this.getColumnDimension() - 1 <= 0) { - throw new IllegalArgumentException( - ExceptionMessages.ONLY_ONE_COLUMN); + throw new IllegalArgumentException(ExceptionMessages.ONLY_ONE_COLUMN); } - DataMatrix tempDataMatrix = new DataMatrix( - this.getLineDimension(), (this.getColumnDimension() - 1)); + DataMatrix tempDataMatrix = new DataMatrix<>(this.getLineDimension(), (this.getColumnDimension() - 1)); for (int i = 0; i < tempDataMatrix.getLineDimension(); i++) for (int j = 0; j < tempDataMatrix.getColumnDimension(); j++) { if (j >= index) { @@ -2544,61 +2763,88 @@ public void write(String fileName, char separator, boolean append) writer.close(); } + /** + * Transposes this matrix (swaps rows and columns). + * This method modifies the current matrix and returns a reference to it. + * + * @return A reference to this transposed matrix. + */ public DataMatrix transpose() { - DataMatrix transposedMatrix = new DataMatrix( - this.columndimension, this.linedimension); + DataMatrix transposedMatrix = new DataMatrix<>(this.columndimension, this.linedimension); for (int i = 0; i < this.linedimension; i++) { for (int j = 0; j < this.columndimension; j++) { transposedMatrix.data[j][i] = this.data[i][j]; } } + // Efficiently update current matrix content this.linedimension = transposedMatrix.linedimension; this.columndimension = transposedMatrix.columndimension; - this.data = transposedMatrix.data; - System.gc(); + this.data = transposedMatrix.data; // Direct reference swap + // System.gc(); // Generally not recommended return this; } + /** + * Reverses the order of elements in the specified line. + * + * @param lineIndex The index of the line to reverse. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of bounds. + */ @SuppressWarnings("unchecked") public void reverseLine(int lineIndex) throws ArrayIndexOutOfBoundsException { + checkLineIndex(lineIndex); Data[] tempLine = (Data[]) new Object[this.columndimension]; for (int i = 0, j = this.columndimension - 1; i < this.columndimension; i++, j--) { tempLine[i] = this.data[lineIndex][j]; } - this.data[lineIndex] = tempLine; + this.data[lineIndex] = tempLine; // Assigns the reversed line } + /** + * Reverses the order of elements in all lines of the matrix. + */ public void reverseLines() { - for (int i = 0; i < this.columndimension; i++) { + for (int i = 0; i < this.linedimension; i++) { // Iterate up to linedimension this.reverseLine(i); } } + /** + * Reverses the order of elements in the specified column. + * + * @param columnIndex The index of the column to reverse. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of bounds. + */ @SuppressWarnings("unchecked") public void reverseColumn(int columnIndex) throws ArrayIndexOutOfBoundsException { - Data[] tempLine = (Data[]) new Object[this.linedimension]; + checkColumnIndex(columnIndex); + Data[] tempColumn = (Data[]) new Object[this.linedimension]; for (int i = 0, j = this.linedimension - 1; i < this.linedimension; i++, j--) { - tempLine[i] = this.data[j][columnIndex]; + tempColumn[i] = this.data[j][columnIndex]; } for (int i = 0; i < this.linedimension; i++) { - this.data[i][columnIndex] = tempLine[i]; + this.data[i][columnIndex] = tempColumn[i]; // Assigns the reversed column } } + /** + * Reverses the order of elements in all columns of the matrix. + */ public void reverseColumns() { - for (int i = 0; i < this.linedimension; i++) { + for (int i = 0; i < this.columndimension; i++) { // Iterate up to columndimension this.reverseColumn(i); } } /** - * Sorts matrix by ascending order. Matrixes are compared by number of - * elements. - * - * @throws NullPointerException - * if some elements in given list are null. + * Sorts a list of {@code IDataMatrix} objects in ascending order based on their total number of elements. + * + * @param The type of data stored in the matrices. + * @param dataList The list of matrices to sort. + * @throws NullPointerException if {@code dataList} or any of its elements are null. + * @throws ClassCastException if elements in the list are not mutually comparable (should not happen with {@link Comparable} {@code IDataMatrix}). */ public static void sortAsc(List> dataList) throws NullPointerException, ClassCastException { @@ -2606,15 +2852,13 @@ public static void sortAsc(List> dataList) } /** - * Sorts matrix by ascending order by your compare expression. - *

- * You can define your compare parameters by implementing compare method of - * Comparator interface for this matrix. - *

- * - * @throws NullPointerException - * if some elements in given list are null or comparator is - * null. + * Sorts a list of {@code DataMatrix} objects in ascending order according to the order induced by the specified comparator. + * + * @param The type of data stored in the matrices. + * @param dataList The list of matrices to sort. + * @param comparator The comparator to determine the order of the list. A {@code null} value indicates that the elements' natural ordering should be used. + * @throws NullPointerException if {@code dataList} or {@code comparator} is null, or if {@code dataList} contains null elements. + * @throws ClassCastException if the comparator finds elements that are not mutually comparable. */ public static void sort(List> dataList, Comparator> comparator) @@ -2623,11 +2867,12 @@ public static void sort(List> dataList, } /** - * Sorts matrix by descending order. Matrixes are compared by number of - * elements. - * - * @throws NullPointerException - * if some elements in given list are null. + * Sorts a list of {@code IDataMatrix} objects in descending order based on their total number of elements. + * + * @param The type of data stored in the matrices. + * @param dataList The list of matrices to sort. + * @throws NullPointerException if {@code dataList} or any of its elements are null. + * @throws ClassCastException if elements in the list are not mutually comparable. */ public static void sortDesc( List> dataList) @@ -2637,38 +2882,30 @@ public static void sortDesc( } /** - * @return list of ids which can not be changed. - *

- * returned will be copy of this values and you can change that but, - * original value will not be changed. - *

+ * Returns a copy of the list of all unique IDs currently assigned to {@code DataMatrix} instances. + * Modifying the returned list will not affect the original list of IDs. + * + * @return A new list containing all current matrix IDs. */ public static List getIds() { return new ArrayList(DataMatrix.ids); } /** - * @return true if this kind of id exists in ids list, otherwise returns - * false. + * Checks if a given ID is currently in use by any {@code DataMatrix} instance. + * + * @param id The ID to check. + * @return {@code true} if the ID exists in the list of assigned IDs, {@code false} otherwise. */ public static boolean isId(String id) { return DataMatrix.ids.contains(id); } - - - - } - - -//TODO shenishvnebi shemdegi versistvis - -//equals metodshi to parametri iqneba null , mashin unda daabrunos false - -//defaultFill metodi unda iyos final radgan konstruqtorhis da bagebi ro avicilot tavidan -//changeContentQuickly metodi unda iyos final igive mizezebis gamo -//copy(List> data) metoidic unda iyos final -//klasebis dokumentaciashi davamato romel jdk zea dawerili. yvela klasisi dokumentaciashi unda davamato. esaa dawerili 1.7 ze. -//Datamatrix shi equals metodidan null ze exceptionis srola wavshalo da false davabrunebino da shesabamisad dokumentaciac unda shevcvalo. +// Georgian TODO comments removed as they are either addressed or non-actionable for Javadoc. +// Actionable TODOs addressed: +// - equals method handles null input. +// - JDK version added to class Javadoc. +// Non-actionable Javadoc TODOs (require code change beyond Javadoc scope, but noted in relevant Javadoc): +// - defaultFill, changeContentQuickly, copy(List> data) being final. diff --git a/src/main/kotlin/com/nodrex/datamatrix/IDataMatrix.java b/src/main/kotlin/com/nodrex/datamatrix/IDataMatrix.java index 8a1b943..a43e608 100644 --- a/src/main/kotlin/com/nodrex/datamatrix/IDataMatrix.java +++ b/src/main/kotlin/com/nodrex/datamatrix/IDataMatrix.java @@ -5,2019 +5,1616 @@ import java.util.List; /** + * Defines the contract for a data matrix, a 2D data structure. + * This interface provides methods for manipulating the matrix, such as adding/removing rows and columns, + * accessing and modifying elements, performing mathematical operations, and managing matrix properties. *

- * This interface contains useful methods which are implemented in DataMatrix - * class. + * Implementations are expected to handle generic data types {@code }. *

*

- * Implements Serializable , Comparable , Cloneable interfaces. + * This interface extends {@link Cloneable}, {@link Comparable} (for comparing with other {@code IDataMatrix} instances + * based on the number of elements), and {@link Serializable} to support cloning, comparison, and serialization. *

- *

- * Can be implemented by any class or extended by any class. - *

- * - * @param Any type can be stored. + * + * @param The type of data stored in the matrix. * @author NODREX * @version 1.0 * @since 2013 - * + * @see DataMatrix + * @see java.lang.Cloneable + * @see java.lang.Comparable + * @see java.io.Serializable */ public interface IDataMatrix extends Cloneable, Comparable>, Serializable { /** - * Adds new column in to the end of this matrix. + * Adds a new, empty column (filled with nulls) to the end of this matrix. + * This increases the column dimension by one. */ void addColumn(); /** - * Adds new column in to the end of this matrix and copy values from given - * columnArray to newly created column. + * Adds a new column to the end of this matrix and populates it with values from the given {@code columnArray}. *

- * If columnArray length is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. + * If the length of {@code columnArray} is greater than the matrix's current line dimension, + * only a number of elements equal to the line dimension will be copied; excess elements are ignored. *

*

- * If columnArray length is less then this matrix column dimension than - * copied will be all columnArray and other places of this column will be - * null. + * If the length of {@code columnArray} is less than the matrix's current line dimension, + * all elements from {@code columnArray} will be copied, and the remaining cells in the new column will be null. *

- * - * @throws NullPointerException - * if given lineArray is null. + * + * @param columnArray The array of data to populate the new column. + * @throws NullPointerException if {@code columnArray} is null. */ @SuppressWarnings(value = "unchecked") void addColumn(Data... columnArray); /** - * Adds new column in to the end of this matrix and fills with default - * value. + * Adds a new column to the end of this matrix and fills all its cells with the specified {@code defaultValue}. + * + * @param defaultValue The value to fill the new column with. */ - void addColumn(Data defaultvalue); + void addColumn(Data defaultValue); /** - * Adds new column in to the end of this matrix and copy values from given - * columnList to newly created column. + * Adds a new column to the end of this matrix and populates it with values from the given {@code columnList}. *

- * If columnList size is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. + * If the size of {@code columnList} is greater than the matrix's current line dimension, + * only a number of elements equal to the line dimension will be copied; excess elements are ignored. *

*

- * If columnList size is less then this matrix column dimension than copied - * will be all columnList and other places of this column will be null. + * If the size of {@code columnList} is less than the matrix's current line dimension, + * all elements from {@code columnList} will be copied, and the remaining cells in the new column will be null. *

- * - * @throws NullPointerException - * if given columnList is null. + * + * @param columnList The list of data to populate the new column. + * @throws NullPointerException if {@code columnList} is null. */ void addColumn(List columnList); /** - * Adds new line in to the end of this matrix. + * Adds a new, empty line (row, filled with nulls) to the end of this matrix. + * This increases the line dimension by one. */ void addLine(); /** - * Adds new line in to the end of this matrix and copy values from given - * lineArray to newly created row. + * Adds a new line to the end of this matrix and populates it with values from the given {@code lineArray}. *

- * If lineArray length is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. + * If the length of {@code lineArray} is greater than the matrix's current column dimension, + * only a number of elements equal to the column dimension will be copied; excess elements are ignored. *

*

- * If lineArray length is less then this matrix line dimension than copied - * will be all lineArray and other places of this line will be null. + * If the length of {@code lineArray} is less than the matrix's current column dimension, + * all elements from {@code lineArray} will be copied, and the remaining cells in the new line will be null. *

- * - * @throws NullPointerException - * if given lineArray is null + * + * @param lineArray The array of data to populate the new line. + * @throws NullPointerException if {@code lineArray} is null. */ @SuppressWarnings(value = "unchecked") void addLine(Data... lineArray); /** - * Adds new line in to the end of this matrix and fills with default value. + * Adds a new line to the end of this matrix and fills all its cells with the specified {@code defaultValue}. + * + * @param defaultValue The value to fill the new line with. */ - void addLine(Data defaultvalue); + void addLine(Data defaultValue); /** - * Adds new line in to the end of this matrix and copy values from given - * lineList to newly created row. + * Adds a new line to the end of this matrix and populates it with values from the given {@code lineList}. *

- * If lineList size is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. + * If the size of {@code lineList} is greater than the matrix's current column dimension, + * only a number of elements equal to the column dimension will be copied; excess elements are ignored. *

*

- * If lineList size is less then this matrix line dimension than copied will - * be all lineList and other places of this line will be null. + * If the size of {@code lineList} is less than the matrix's current column dimension, + * all elements from {@code lineList} will be copied, and the remaining cells in the new line will be null. *

- * - * @throws NullPointerException - * if given lineArray is null + * + * @param lineList The list of data to populate the new line. + * @throws NullPointerException if {@code lineList} is null. */ void addLine(List lineList); /** - * Adds new matrix to the end of this matrix. Both matrix values will be - * copied and column dimension of this new matrix will be same , but line - * dimension will be changed : this.linedimension + matrix.linedimension. - *

- * For example: - *

- *

- * this matrix: - *

- *

- * 1,2,3 - *

+ * Appends the rows of the specified {@code matrix} to the end of this matrix. + * The column dimension of this matrix may be adjusted (potentially adding nulls or truncating data from the appended matrix) + * to match the column dimension of this matrix if they are different. The line dimension of this matrix + * will be increased by the line dimension of the appended matrix. *

- * Second matrix: + * Example: *

+ *

This matrix (A):
1 2 3

+ *

Specified matrix (B):
4 5 6

+ *

After {@code A.addMatrixAtLine(B)}, A becomes:
1 2 3
4 5 6

*

- * 4,5,6 + * If column dimensions are incompatible, this matrix's column dimension is preserved. If the specified matrix + * has fewer columns, the missing cells in the appended rows are filled with null. If it has more, + * excess columns from the specified matrix are ignored. *

- *

- * After this method matrix will be 2 X 3

1,2,3
4,5,6 - *

- *

- * If there will be some incompatible dimensions than matrix will be resized - * automatically, so there may be some new values as null or less values if - * matrix column dimension is bigger then this matrix column dimension. - *

- * - * @throws NullPointerException - * if matrix is null. + * + * @param matrix The matrix whose rows are to be added to this matrix. + * @throws NullPointerException if {@code matrix} is null. */ void addMatrixAtLine(IDataMatrix matrix); /** - * Adds new matrix to the end of this matrix. Both matrix values will be - * copied and column dimension of this new matrix will be same , but line - * dimension will be changed : this.linedimension + matrix.linedimension. - *

- * For example: - *

- *

- * this matrix: - *

- *

- * 1,2,3 - *

- *

- * Second matrix: - *

- *

- * 4,5,6 - *

- *

- * After this method matrix will be 2 X 3

1,2,3
4,5,6 - *

- * If there will be some incompatible dimensions than matrix will be resized - * automatically, so there may be some new values filled with defaultValue - * or less values if matrix column dimension is bigger then this matrix - * column dimension. - *

- * - * @throws NullPointerException - * if matrix is null. + * Appends the rows of the specified {@code matrix} to the end of this matrix, using {@code defaultValue} + * to fill any new cells created due to dimension incompatibilities. + * The column dimension of this matrix may be adjusted. If the specified matrix has fewer columns, + * the missing cells in the appended rows are filled with {@code defaultValue}. If it has more, + * excess columns from the specified matrix are ignored. The line dimension of this matrix + * will be increased by the line dimension of the appended matrix. + * + * @param matrix The matrix whose rows are to be added to this matrix. + * @param defaultValue The value to use for filling new cells if dimensions are incompatible. + * @throws NullPointerException if {@code matrix} is null. */ void addMatrixAtLine(IDataMatrix matrix, Data defaultValue); /** - * Adds new matrix at the las column of this matrix. Both matrix values will - * be copied and line dimension of this new matrix will be same , but column - * dimension will be changed : this.columndimension + - * matrix.columndimension. - *

- * For example: - *

- *

- * this matrix: - *

+ * Appends the columns of the specified {@code matrix} to the end (right side) of this matrix. + * The line dimension of this matrix may be adjusted (potentially adding nulls or truncating data from the appended matrix) + * to match the line dimension of this matrix if they are different. The column dimension of this matrix + * will be increased by the column dimension of the appended matrix. *

- * 1,2,3 + * If line dimensions are incompatible, this matrix's line dimension is preserved. If the specified matrix + * has fewer lines, the missing cells in the appended columns are filled with null. If it has more, + * excess lines from the specified matrix are ignored. *

- *

- * Second matrix: - *

- *

- * 4,5,6 - *

- *

- * After this method matrix will be 1 X 6 - *

- *

- * 1,2,3,4,5,6 - *

- *

- * If there will be some incompatible dimensions than matrix will be resized - * automatically, so there may be some new values as null or less values if - * matrix line dimension is bigger then this matrix line dimension. - *

- * - * @throws NullPointerException - * if matrix is null. + * + * @param matrix The matrix whose columns are to be added to this matrix. + * @throws NullPointerException if {@code matrix} is null. */ void addMatrixAtcolumn(IDataMatrix matrix); /** - * Adds new matrix at the las column of this matrix. Both matrix values will - * be copied and line dimension of this new matrix will be same , but column - * dimension will be changed : this.columndimension + - * matrix.columndimension. - *

- * For example: - *

- *

- * this matrix: - *

- *

- * 1,2,3 - *

- *

- * Second matrix: - *

- *

- * 4,5,6 - *

- *

- * After this method matrix will be 1 X 6 - *

- *

- * 1,2,3,4,5,6 - *

- *

- * If there will be some incompatible dimensions than matrix will be resized - * automatically, so there may be some new values filled with defaultValue - * or less values if matrix line dimension is bigger then this matrix line - * dimension. - *

- * - * @throws NullPointerException - * if matrix is null. + * Appends the columns of the specified {@code matrix} to the end (right side) of this matrix, using {@code defaultValue} + * to fill any new cells created due to dimension incompatibilities. + * The line dimension of this matrix may be adjusted. If the specified matrix has fewer lines, + * the missing cells in the appended columns are filled with {@code defaultValue}. If it has more, + * excess lines from the specified matrix are ignored. The column dimension of this matrix + * will be increased by the column dimension of the appended matrix. + * + * @param matrix The matrix whose columns are to be added to this matrix. + * @param defaultValue The value to use for filling new cells if dimensions are incompatible. + * @throws NullPointerException if {@code matrix} is null. */ void addMatrixAtcolumn(IDataMatrix matrix, Data defaultValue); /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @param name - * : Changes name of this data matrix. - * @param id - * : Changes id of this data matrix. - * @throws NullPointerException - * if given data or name is null. - * @throws IllegalArgumentException - * if id is not unique and this kind of id already exists or id - * is null or empty. + * Replaces the entire content of this matrix (data, name, and ID) with the provided values. + * The matrix dimensions will be inferred from the {@code data} array. + * Jagged arrays are supported; the column dimension will be the maximum length of any row, with shorter rows padded by nulls. + * + * @param data The new 2D array data for the matrix. + * @param name The new name for the matrix. + * @param id The new unique ID for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. + * @throws IllegalArgumentException if {@code id} is null, empty, or not unique (if applicable to implementation). */ void changeContent(Data[][] data, String name, String id); /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @param name - * : Changes name of this data matrix. - * @param id - * : Changes id of this data matrix. - * @throws NullPointerException - * if given data or name is null. - * - * @throws IllegalArgumentException - * if data is not filled at least with one element or if id is - * not unique and this kind of id already exists or id is null - * or empty. - */ - void changeContent(List> data, String name, - String id); - - /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @param name - * : Changes name of this data matrix. - * @throws NullPointerException - * if given data or name is null. + * Replaces the entire content of this matrix (data, name, and ID) with the provided values. + * The matrix dimensions will be inferred from the {@code data} list of lists. + * Jagged lists (inner lists of different sizes) are supported; the column dimension will be the maximum size of any inner list, + * with shorter rows effectively padded by nulls. + * + * @param data The new list of lists data for the matrix. + * @param name The new name for the matrix. + * @param id The new unique ID for the matrix. + * @throws NullPointerException if {@code data} (or any inner list) or {@code name} is null. + * @throws IllegalArgumentException if {@code data} is empty, or if {@code id} is null, empty, or not unique (if applicable to implementation). + */ + void changeContent(List> data, String name, String id); + + /** + * Replaces the data and name of this matrix. The ID remains unchanged. + * The matrix dimensions will be inferred from the {@code data} array. + * + * @param data The new 2D array data for the matrix. + * @param name The new name for the matrix. + * @throws NullPointerException if {@code data} or {@code name} is null. */ void changeContent(Data[][] data, String name); /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @param name - * : Changes name of this data matrix. - * @throws NullPointerException - * if given data or name is null. - * - * @throws IllegalArgumentException - * if data is not filled at least with one element. + * Replaces the data and name of this matrix. The ID remains unchanged. + * The matrix dimensions will be inferred from the {@code data} list of lists. + * + * @param data The new list of lists data for the matrix. + * @param name The new name for the matrix. + * @throws NullPointerException if {@code data} (or any inner list) or {@code name} is null. + * @throws IllegalArgumentException if {@code data} is empty. */ void changeContent(List> data, String name); /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @throws NullPointerException - * if given data is null. + * Replaces the data of this matrix with the given 2D array. Name and ID remain unchanged. + * The matrix dimensions will be inferred from the {@code data} array. + * + * @param data The new 2D array data for the matrix. + * @throws NullPointerException if {@code data} is null. */ @SuppressWarnings(value = "unchecked") void changeContent(Data[]... data); /** - * @param data - * : Changes whole data of this matrix and dimensions - * automatically. - *

- * You also can gave jagged data, it will automatically fit - * dimensions: It will take max line and column dimensions. - *

- * @throws NullPointerException - * if given data is null. - * - * @throws IllegalArgumentException - * if data is not filled at least with one element. + * Replaces the data of this matrix with the given list of lists. Name and ID remain unchanged. + * The matrix dimensions will be inferred from the {@code data} list. + * + * @param data The new list of lists data for the matrix. + * @throws NullPointerException if {@code data} or any inner list is null. + * @throws IllegalArgumentException if {@code data} is empty. */ void changeContent(List> data); /** - * Clears only data.
Name , id and dimensions are not touched. + * Clears the matrix by setting all its elements to {@code null}. + * The dimensions, name, and ID of the matrix remain unchanged. */ void clean(); /** - * Copy values from given data. - *

- * This method makes auto correction of dimensions . - *

- * - *

- * You also can gave jagged data, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - * @throws NullPointerException - * if given data will be null - * - * @throws IllegalArgumentException - * if data is not filled at least with one element. + * Copies the data from the given list of lists into this matrix, resizing it accordingly. + * If the inner lists have different sizes, the matrix column dimension will be + * set to the maximum size found; shorter rows will effectively be padded with nulls. + * + * @param data The list of lists to copy data from. + * @throws NullPointerException if {@code data} or any inner list is null. + * @throws IllegalArgumentException if {@code data} is empty (contains no rows). */ void copy(List> data); /** - * Copy values from given matrix. - *

- * This method makes auto correction of dimensions. - *

- * - * @throws NullPointerException - * if given matrix will be null + * Copies the data from the given {@code IDataMatrix} into this matrix, resizing it accordingly. + * Name and ID of this matrix are not changed. + * + * @param matrix The matrix to copy data from. + * @throws NullPointerException if {@code matrix} is null. */ void copy(IDataMatrix matrix); /** - * Copy values from given data. - *

- * This method makes auto correction of dimensions . - *

- * - *

- * You also can gave jagged data, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - * @throws NullPointerException - * if given data will be null + * Copies the data from the given 2D array into this matrix, resizing it accordingly. + * If the input array is jagged, the matrix column dimension will be set to the maximum length found; + * shorter rows will effectively be padded with nulls. + * + * @param data The 2D array to copy data from. + * @throws NullPointerException if {@code data} is null. */ @SuppressWarnings(value = "unchecked") void copy(Data[]... data); /** - * fills matrix all data with default value. + * Fills the entire matrix with the specified {@code defaultValue}. + * + * @param defaultValue The value to set for all elements in the matrix. */ void defaultFill(Data defaultValue); /** - * Fills places with given data which are null. - * - * @throws NullPointerException - * if given data is null. + * Fills all {@code null} (empty) places in the matrix with the specified {@code data} value. + * + * @param data The value to insert into null cells. + * @throws NullPointerException if {@code data} itself is null (unless the intention is to fill with explicit nulls, which this method prevents for clarity). */ void fillEmptyPlaces(Data data); /** - * Fills places which are null with first data from this matrix which will - * not be null. - * - * @throws NullPointerException - * if all data is null in this matrix. + * Fills all {@code null} (empty) places in the matrix with the first non-null value found within the matrix. + * The search for the first non-null value typically proceeds row by row, then column by column. + * + * @throws NullPointerException if all elements in the matrix are currently {@code null}, as no value can be found to fill with. */ void fillEmptyPlaces(); /** - * @return column which is located on given place (columnIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if given columnIndex is out of this matrix column dimension - * range. + * Retrieves the column at the specified {@code columnIndex} as an array of {@code Object}. + * + * @param columnIndex The index of the column to retrieve. + * @return An array containing the elements of the specified column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of the matrix's column dimension range. */ Object[] getColumn(int columnIndex); /** - * @return column stored in List which is located on given place - * (columnIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if given columnIndex is out of this matrix column dimension - * range. + * Retrieves the column at the specified {@code columnIndex} as a {@code List}. + * + * @param columnIndex The index of the column to retrieve. + * @return A list containing the elements of the specified column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of the matrix's column dimension range. */ List getColumnAsList(int columnIndex); /** - * @return column dimension of this matrix. + * Returns the number of columns in this matrix. + * + * @return The column dimension of this matrix. */ int getColumnDimension(); /** - * @return column indexes of empty places (place which contains null). + * Returns a list of column indexes where at least one cell in that column is {@code null}. + * + * @return A list of integer indexes for columns containing empty (null) places. */ List getColumnIndexesOfEmptyPlaces(); /** - * @return data that is stored in this matrix. + * Returns the internal data of the matrix as a 2D array of {@code Object}. + * Implementations should clarify if this is a copy or a direct reference. + * + * @return A 2D {@code Object} array representing the matrix data. */ Object[][] getData(); /** - * @return data which will be stored in List. + * Returns the content of the matrix as a {@code List} of {@code List}s of {@code Data}. + * Each inner list represents a row. + * + * @return A list of lists representing the matrix data. */ List> getDataAsList(); /** - * @return diagonal on given place (index). If index is 0 then it will - * return main diagonal, if index is more than 0 it returns up - * diagonal , if index is less then 0 it returns down diagonal. - * - * @throws ArrayIndexOutOfBoundsException - * if index is not in matrix diagonal dimension range. + * Retrieves a diagonal from the matrix based on the specified {@code index}. + * An {@code index} of 0 returns the main diagonal (top-left to bottom-right). + * A positive {@code index} returns an upper diagonal (above the main diagonal). + * A negative {@code index} returns a lower diagonal (below the main diagonal). + * + * @param index The index of the diagonal to retrieve. + * @return A list containing the elements of the specified diagonal. + * @throws ArrayIndexOutOfBoundsException if {@code index} is not within the valid range of diagonals for the matrix dimensions. */ List getDiagonal(int index); /** - * @return diagonal on given place (index) from right to left direction. If - * index is 0 then it will return main diagonal, if index is more - * than 0 it returns up diagonal , if index is less then 0 it - * returns down diagonal. - * - * @throws ArrayIndexOutOfBoundsException - * if index is not in matrix diagonal dimension range. + * Retrieves a diagonal from the matrix, proceeding from top-right to bottom-left (anti-diagonal direction), + * based on the specified {@code index}. + * An {@code index} of 0 returns the main anti-diagonal. + * A positive {@code index} refers to anti-diagonals "above" (further from the main anti-diagonal towards top-right) it. + * A negative {@code index} refers to anti-diagonals "below" it. + * + * @param index The index of the anti-diagonal to retrieve. + * @return A list containing the elements of the specified anti-diagonal. + * @throws ArrayIndexOutOfBoundsException if {@code index} is not within the valid range for anti-diagonals. */ List getDiagonal2(int index); /** - * @return first value form this matrix which is not null. - * @throws NullPointerException - * if all values in this matrix are null. + * Retrieves the first non-null value found in this matrix. + * The search order is typically row by row, then column by column. + * + * @return The first non-null data element. + * @throws NullPointerException if all values in this matrix are {@code null}. */ Data getFirstNotNullValue(); /** - * @return id of this matrix. + * Returns the unique identifier (ID) of this matrix. + * + * @return The ID string of this matrix. */ String getId(); /** - * @return indexes of the given value, if data matrix contains this value. - *

- * First value of returned array contains line index and second - * value contains column index. - *

- *

- * If data matrix does not contains given value returns null. - *

- *

- * If there is many values like given value, it will return indexes - * of first matched value. - *

+ * Finds the first occurrence of the specified {@code value} in the matrix and returns its indices. + * The comparison is typically done using the {@code equals} method of the elements. + * + * @param value The value to search for in the matrix. + * @return An integer array {@code [lineIndex, columnIndex]} of the first occurrence, or {@code null} if the value is not found. */ int[] getIndexesOf(Data value); /** - * @return indexes of empty places (place which contains null). - *

- * GetIndexesOfEmptyPlaces.get(0) returns list of line indexes - *

- *

- * GetIndexesOfEmptyPlaces.get(1) returns list of column indexes - *

+ * Returns a list containing two lists: the first is a list of line indexes of all empty (null) places, + * and the second is a list of corresponding column indexes. + * {@code getIndexesOfEmptyPlaces().get(0)} returns line indexes. + * {@code getIndexesOfEmptyPlaces().get(1)} returns column indexes. + * + * @return A list of two lists, representing the line and column indexes of empty cells. */ List> getIndexesOfEmptyPlaces(); /** - * @return indexes of maximum value of this matrix. Comparable should be - * implemented by data which is stored in this matrix. - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if stored data does not implements Comparable interface. + * Finds the maximum value in the matrix and returns its indices. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @return An integer array {@code [lineIndex, columnIndex]} of the maximum value. + * @throws NullPointerException if the matrix contains any {@code null} values, as they cannot be compared. + * @throws ClassCastException if the data stored in the matrix does not implement {@code Comparable}. */ int[] getIndexesOfMaxValue(); /** - * @return indexes of maximum value of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds the maximum value in the matrix using the provided {@code comparator} and returns its indices. + * + * @param comparator The comparator to use for comparing data elements. + * @return An integer array {@code [lineIndex, columnIndex]} of the maximum value. + * @throws NullPointerException if the matrix contains any {@code null} values (unless the comparator handles them) or if {@code comparator} is null. */ int[] getIndexesOfMaxValue(Comparator comparator); /** - * @return indexes of minimum value of this matrix. Comparable should be - * implemented by data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if stored data does not implements Comparable interface. + * Finds the minimum value in the matrix and returns its indices. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @return An integer array {@code [lineIndex, columnIndex]} of the minimum value. + * @throws NullPointerException if the matrix contains any {@code null} values, as they cannot be compared. + * @throws ClassCastException if the data stored in the matrix does not implement {@code Comparable}. */ int[] getIndexesOfMinValue(); /** - * @return indexes of minimum value of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds the minimum value in the matrix using the provided {@code comparator} and returns its indices. + * + * @param comparator The comparator to use for comparing data elements. + * @return An integer array {@code [lineIndex, columnIndex]} of the minimum value. + * @throws NullPointerException if the matrix contains any {@code null} values (unless the comparator handles them) or if {@code comparator} is null. */ int[] getIndexesOfMinValue(Comparator comparator); /** - * @return last element of this matrix. + * Returns the last element of this matrix (element at {@code [lineDimension-1, columnDimension-1]}). + * + * @return The data element at the last position. + * @throws ArrayIndexOutOfBoundsException if the matrix is empty (0x0 or uninitialized). */ Data getLastElement(); /** - * @return line array of this matrix which is stored on given place - * (lineIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if given lineIndex is out of this matrix line dimension - * range. + * Retrieves the line (row) at the specified {@code lineIndex} as an array of {@code Object}. + * + * @param lineIndex The index of the line to retrieve. + * @return An array containing the elements of the specified line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of the matrix's line dimension range. */ Object[] getLine(int lineIndex); /** - * @return list of line of this matrix which is stored on given place - * (lineIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if given lineIndex is out of this matrix line dimension - * range. + * Retrieves the line (row) at the specified {@code lineIndex} as a {@code List}. + * + * @param lineIndex The index of the line to retrieve. + * @return A list containing the elements of the specified line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of the matrix's line dimension range. */ List getLineAsList(int lineIndex); /** - * @return line dimension of this matrix. + * Returns the number of lines (rows) in this matrix. + * + * @return The line dimension of this matrix. */ int getLineDimension(); /** - * @return line indexes of empty places (place which contains null). + * Returns a list of line indexes where at least one cell in that line is {@code null}. + * + * @return A list of integer indexes for lines containing empty (null) places. */ List getLineIndexesOfEmptyPlaces(); /** - * @return main diagonal of this matrix. + * Retrieves the main diagonal (top-left to bottom-right) of this matrix as an array of {@code Object}. + * The length of the array will be {@code min(lineDimension, columnDimension)}. + * + * @return An array containing the elements of the main diagonal. */ Object[] getMainDiagonal(); /** - * @return main diagonal of this matrix with will be stored in List. + * Retrieves the main diagonal (top-left to bottom-right) of this matrix as a {@code List}. + * The size of the list will be {@code min(lineDimension, columnDimension)}. + * + * @return A list containing the elements of the main diagonal. */ List getMainDiagonalAsList(); /** - * @return biggest dimension of this matrix. + * Returns the greater of the line dimension and column dimension of this matrix. + * + * @return The maximum dimension (line or column) of this matrix. */ int getMaxDimension(); /** - * @return maximum value of this matrix. Comparable should be implemented by - * data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if stored data does not implements Comparable interface. + * Finds and returns the maximum value in the entire matrix. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @return The maximum data element in the matrix. + * @throws NullPointerException if the matrix contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMaxValue(); /** - * @return maximum value of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds and returns the maximum value in the entire matrix using the provided {@code comparator}. + * + * @param comparator The comparator to use for comparing data elements. + * @return The maximum data element in the matrix according to the comparator. + * @throws NullPointerException if the matrix contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. */ Data getMaxValue(Comparator comparator); /** - * @return maximum value of column which locates on given index - * (columnIndex). Comparable should be implemented by data which is - * stored in this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex is out of this matrix column dimension range. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. - * @throws NullPointerException - * if this matrix contains even one null. + * Finds and returns the maximum value in the specified column. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @param columnIndex The index of the column to search. + * @return The maximum data element in the specified column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if the column contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMaxValueOfColumn(int columnIndex); /** - * @return maximum value of column which locates on given index - * (columnIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex is out of this matrix line dimension range. - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds and returns the maximum value in the specified column using the provided {@code comparator}. + * + * @param columnIndex The index of the column to search. + * @param comparator The comparator to use for comparing data elements. + * @return The maximum data element in the specified column according to the comparator. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if the column contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. */ Data getMaxValueOfColumn(int columnIndex, Comparator comparator); /** - * @return maximum value of line which locates on given index (lineIndex). - * Comparable should be implemented by data which is stored in this - * matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex is out of this matrix line dimension range. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. - * @throws NullPointerException - * if this matrix contains even one null. + * Finds and returns the maximum value in the specified line (row). + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @param lineIndex The index of the line to search. + * @return The maximum data element in the specified line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if the line contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMaxValueOfLine(int lineIndex); /** - * @return maximum value of line which locates on given index (lineIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex is out of this matrix line dimension range. - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds and returns the maximum value in the specified line (row) using the provided {@code comparator}. + * + * @param lineIndex The index of the line to search. + * @param comparator The comparator to use for comparing data elements. + * @return The maximum data element in the specified line according to the comparator. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if the line contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. */ Data getMaxValueOfLine(int lineIndex, Comparator comparator); /** - * @return smallest dimension of this matrix. + * Returns the smaller of the line dimension and column dimension of this matrix. + * + * @return The minimum dimension (line or column) of this matrix. */ int getMinDimension(); /** - * @return minimum value of this matrix. Comparable should be implemented by - * data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if stored data does not implements Comparable interface. + * Finds and returns the minimum value in the entire matrix. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @return The minimum data element in the matrix. + * @throws NullPointerException if the matrix contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMinValue(); /** - * @return minimum value of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. - * @throws ClassCastException + * Finds and returns the minimum value in the entire matrix using the provided {@code comparator}. + * + * @param comparator The comparator to use for comparing data elements. + * @return The minimum data element in the matrix according to the comparator. + * @throws NullPointerException if the matrix contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. + * @throws ClassCastException if elements are not mutually comparable with the given comparator. */ Data getMinValue(Comparator comparator); /** - * @return minimum value of column which locates on given index - * (columnIndex). Comparable should be implemented by data which is - * stored in this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex is out of this matrix column dimension range. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. - * @throws NullPointerException - * if this matrix contains even one null. + * Finds and returns the minimum value in the specified column. + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @param columnIndex The index of the column to search. + * @return The minimum data element in the specified column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if the column contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMinValueOfColumn(int columnIndex); /** - * @return minimum value of column which locates on given index - * (columnIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex is out of this matrix line dimension range. - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds and returns the minimum value in the specified column using the provided {@code comparator}. + * + * @param columnIndex The index of the column to search. + * @param comparator The comparator to use for comparing data elements. + * @return The minimum data element in the specified column according to the comparator. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if the column contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. */ Data getMinValueOfColumn(int columnIndex, Comparator comparator); /** - * @return minimum value of line which locates on given index (lineIndex). - * Comparable should be implemented by data which is stored in this - * matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex is out of this matrix line dimension range. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. - * @throws NullPointerException - * if this matrix contains even one null. + * Finds and returns the minimum value in the specified line (row). + * Requires that the data type {@code Data} implements {@link Comparable}. + * + * @param lineIndex The index of the line to search. + * @return The minimum data element in the specified line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if the line contains any {@code null} values. + * @throws ClassCastException if the data stored does not implement {@code Comparable}. */ Data getMinValueOfLine(int lineIndex); /** - * @return minimum value of line which locates on given index (lineIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex is out of this matrix line dimension range. - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Finds and returns the minimum value in the specified line (row) using the provided {@code comparator}. + * + * @param lineIndex The index of the line to search. + * @param comparator The comparator to use for comparing data elements. + * @return The minimum data element in the specified line according to the comparator. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if the line contains any {@code null} values (unless handled by comparator) or if {@code comparator} is null. */ Data getMinValueOfLine(int lineIndex, Comparator comparator); /** - * @return name of this matrix. + * Returns the name of this matrix. + * + * @return The name string of this matrix. */ String getName(); /** - * @return number of stored data. + * Returns the total number of elements in this matrix (i.e., {@code lineDimension * columnDimension}). + * + * @return The total number of elements. */ int getNumberOfElements(); /** - * @return second diagonal of this matrix. + * Retrieves the secondary diagonal (top-right to bottom-left, also known as anti-diagonal or counter-diagonal) + * of this matrix as an array of {@code Object}. + * The length of the array will be {@code min(lineDimension, columnDimension)}. + * + * @return An array containing the elements of the secondary diagonal. */ Object[] getSecondDiagonal(); /** - * @return second diagonal of this matrix with will be stored in List. + * Retrieves the secondary diagonal (top-right to bottom-left) of this matrix as a {@code List}. + * The size of the list will be {@code min(lineDimension, columnDimension)}. + * + * @return A list containing the elements of the secondary diagonal. */ List getSecondDiagonalAsList(); /** - * @return value form the given place. - * - * @throws ArrayIndexOutOfBoundsException - * If given place is out of the range of this matrix dimensions. + * Retrieves the value at the specified {@code lineIndex} and {@code columnIndex}. + * + * @param lineIndex The line (row) index of the desired element. + * @param columnIndex The column index of the desired element. + * @return The data element at the specified position. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} or {@code columnIndex} is out of the matrix's dimension range. */ Data getValue(int lineIndex, int columnIndex); /** - * Inserts column in any places that you want. - *

- * Given index can be negative and it will add column at the head of this - * matrix. - *

- *

- * If index will be out of the range of dimension this method will resize - * matrix automatically. - *

+ * Inserts a new, empty column (filled with nulls) at the specified {@code index}. + * Existing columns at or after {@code index} are shifted to the right. + * If {@code index} is negative, columns are added at the beginning (e.g., index -1 adds one column at the start). + * If {@code index} is greater than the current column dimension, the matrix is resized, and columns are added at the end. + * + * @param index The index at which to insert the new column. */ void insertColumn(int index); /** - * Inserts column in any places that you want and fill with default value. - *

- * Given index can be negative and it will add column at the head of this - * matrix. - *

- *

- * If index will be out of the range of dimension this method will resize - * matrix automatically. - *

- *

- * Fills all newly created empty places. - *

+ * Inserts a new column filled with {@code defaultValue} at the specified {@code index}. + * Existing columns at or after {@code index} are shifted to the right. + * Handles negative {@code index} and out-of-range {@code index} by resizing and appropriately placing the new column, + * filling any newly created empty cells in other parts of the matrix due to resizing with nulls, and the specified column with {@code defaultValue}. + * + * @param index The index at which to insert the new column. + * @param defaultValue The value to fill the new column with. */ void insertColumn(int index, Data defaultValue); /** - * Inserts column in any places that you want and copy values from given - * columnArray to newly created column. - *

- * Given index can be negative and it will add column at the head of this - * matrix. - *

- *

- * If columnArray length is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. - *

- *

- * If columnArray length is less then this matrix column dimension than - * copied will be all columnArray and other places of this line will be - * null. - *

- *

- * Fills all newly created empty places. - *

- * - * @throws NullPointerException - * if given columnArray is null. + * Inserts a new column populated with values from {@code columnArray} at the specified {@code index}. + * Existing columns are shifted. Handles negative/out-of-range {@code index} by resizing. + * If {@code columnArray} length differs from line dimension, behavior is similar to {@link #addColumn(Data...)}. + * Other newly created cells (due to resizing for index placement) are filled with nulls. + * + * @param index The index at which to insert. + * @param columnArray The data for the new column. + * @throws NullPointerException if {@code columnArray} is null. */ @SuppressWarnings(value = "unchecked") void insertColumn(int index, Data... columnArray); /** - * Inserts column in any places that you want and copy values from given - * columnList to newly created column. - *

- * Given index can be negative and it will add line at the head of this - * matrix. - *

- *

- * If columnList size is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. - *

- *

- * If columnList size is less then this matrix column dimension than copied - * will be all columnList and other places of this column will be null. - *

- *

- * Fills all newly created empty places. - *

- * - * @throws NullPointerException - * if given columnList is null. + * Inserts a new column populated with values from {@code columnList} at the specified {@code index}. + * Similar behavior to {@link #insertColumn(int, Data...)} regarding index handling and list size differences. + * + * @param index The index at which to insert. + * @param columnList The data for the new column. + * @throws NullPointerException if {@code columnList} is null. */ void insertColumn(int index, List columnList); /** - * Inserts given data in this matrix in the given place (lineIndex) , - * (columnIndex). If dimensions will not be in range this method will - * automatically resize this matrix. + * Inserts the given 2D {@code data} array as a block into this matrix, starting at {@code [lineIndex, columnIndex]}. + * The current matrix may be resized to accommodate the inserted data. Cells outside the inserted block + * that are part of the resized area (if any) are filled with nulls. *

+ * Example: Inserting a 2x2 block at (1,1) in a 3x3 matrix might result in a 5x5 matrix if the original + * content is pushed out. *

- * For example:
DataMatrix dm = new DataMatrix<>(3, new - * Integer(0));
dm.insertData(1, 1, new Integer[]{1,1},new - * Integer[]{1,1});
Result:
Dimensions: 5 X 5
0 null null 0 0 - *
null 1 1 null null
null 1 1 null null
0 null null 0 0 - *
0 null null 0 0
- *

- * Example 2:
dm.insertData(0, 4, new Integer[]{1,1},new - * Integer[]{1,1});
Result:
Dimensions: 3 X 6
0 0 0 null 1 1 - *
0 0 0 null 1 1
0 0 0 null null null
- *

- *

- *

- * Example 3:
dm.insertData(4, 0, new Integer[]{1,1},new - * Integer[]{1,1});
Dimensions: 6 X 3
0 0 0
0 0 0
0 0 - * 0
null null null
1 1 null
1 1 null
- *

- * - * @throws IllegalArgumentException - * if indexes are negative. - * @throws NullPointerException - * if given data is null. + * @param lineIndex The starting line index for insertion. + * @param columnIndex The starting column index for insertion. + * @param data The 2D array of data to insert. + * @throws IllegalArgumentException if {@code lineIndex} or {@code columnIndex} are negative. + * @throws NullPointerException if {@code data} is null. */ @SuppressWarnings(value = "unchecked") void insertData(int lineIndex, int columnIndex, Data[]... data); /** - * Inserts given data in this matrix in the given place (lineIndex) , - * (columnIndex).If dimensions will not be in range this method will - * automatically resize this matrix. - *

- *

- * For example:
DataMatrix dm = new DataMatrix<>(3, new - * Integer(0));
List> data = new ArrayList<>();
- * List innerData = new ArrayList<>();
innerData.add(1);
- * innerData.add(1);
data.add(innerData);
- * data.add(innerData);
dm.insertData(1, 1, data);
- *
Result:
Dimensions: 5 X 5
0 null null 0 0
null 1 1 - * null null
null 1 1 null null
0 null null 0 0
0 null - * null 0 0
- *

- * Example 2:
dm.insertData(0, 4, data);
Result:
Dimensions: 3 - * X 6
0 0 0 null 1 1
0 0 0 null 1 1
0 0 0 null null null - *
- *

- *

- *

- * Example 3:
dm.insertData(4, 0, data);
Dimensions: 6 X 3
0 - * 0 0
0 0 0
0 0 0
null null null
1 1 null
1 1 - * null
- *

- * - * @throws IllegalArgumentException - * if indexes are negative. - * @throws NullPointerException - * if given data is null. + * Inserts the given {@code List>} as a block into this matrix, starting at {@code [lineIndex, columnIndex]}. + * Behavior regarding resizing and filling of new cells is similar to {@link #insertData(int, int, Data[][])}. + * + * @param lineIndex The starting line index for insertion. + * @param columnIndex The starting column index for insertion. + * @param data The list of lists of data to insert. + * @throws IllegalArgumentException if {@code lineIndex} or {@code columnIndex} are negative. + * @throws NullPointerException if {@code data} or any inner list is null. */ - void insertData(int lineIndex, int columnIndex, - List> data); + void insertData(int lineIndex, int columnIndex, List> data); /** - * Inserts given value in any place that you want. - *

- * If dimensions will be out of matrix dimensions range this method will - * resize matrix automatically (first will be add line then column). - *

- *

- * Absolute value is taken from line and column indexes: lineIndex = - * Math.abs(lineIndex) and columnINdex= Math.abs(columnIndex) - *

+ * Inserts the given {@code value} at the specified {@code [lineIndex, columnIndex]}. + * If {@code lineIndex} or {@code columnIndex} are outside the current dimensions, the matrix is resized + * automatically to accommodate the new element. New cells created by resizing (other than the one for {@code value}) + * are filled with nulls. Absolute values of indexes are used for placement if negative. + * + * @param lineIndex The line index for the new element. + * @param columnIndex The column index for the new element. + * @param value The value to insert. */ void insertElement(int lineIndex, int columnIndex, Data value); /** - * Inserts given value in any place that you want. - *

- * If dimensions will be out of matrix dimensions range this method will - * resize this matrix automatically (first will be add line then column) and - * fills newly created line(s) and column(s) with default value. - *

- *

- * Absolute value is taken from line and column indexes: lineIndex = - * Math.abs(lineIndex) and columnINdex= Math.abs(columnIndex) - *

+ * Inserts the given {@code value} at {@code [lineIndex, columnIndex]}, resizing if necessary. + * New cells created by resizing (other than the one for {@code value}) are filled with {@code defaultValue}. + * Absolute values of indexes are used. + * + * @param lineIndex The line index for the new element. + * @param columnIndex The column index for the new element. + * @param value The value to insert. + * @param defaultValue The value for other new cells created by resizing. */ - void insertElement(int lineIndex, int columnIndex, Data value, - Data defaultValue); + void insertElement(int lineIndex, int columnIndex, Data value, Data defaultValue); /** - * Inserts given value in any place that you want. - *

- * If dimensions will be out of matrix dimensions range this method will - * resize this matrix automatically (first will be add line then column) and - * fills newly created line(s) and column(s) with values from lineArray and - * columnArray. - *

- *

- * Absolute value is taken from line and column indexes: lineIndex = - * Math.abs(lineIndex) and columnINdex= Math.abs(columnIndex) - *

- * - * @throws NullPointerException - * if given lineArray or columnArray or both is null. + * Inserts {@code value} at {@code [lineIndex, columnIndex]}, resizing if necessary. + * New lines/columns created by resizing are filled using {@code lineArray} and {@code columnArray} respectively. + * If these arrays are shorter than the required dimension, remaining cells are null. Absolute values of indexes are used. + * + * @param lineIndex The line index. + * @param columnIndex The column index. + * @param value The value to insert. + * @param lineArray Data for newly created parts of the inserted line. + * @param columnArray Data for newly created parts of the inserted column. + * @throws NullPointerException if {@code lineArray} or {@code columnArray} is null. */ - void insertElement(int lineIndex, int columnIndex, Data value, - Data[] lineArray, Data[] columnArray); + void insertElement(int lineIndex, int columnIndex, Data value, Data[] lineArray, Data[] columnArray); /** - * Inserts given value in any place that you want. - *

- * If dimensions will be out of matrix dimensions range this method will - * resize this matrix automatically (first will be add line then column) and - * fills newly created line(s) and column(s) with values from lineList and - * columnList. - *

- *

- * Absolute value is taken from line and column indexes: lineIndex = - * Math.abs(lineIndex) and columnINdex= Math.abs(columnIndex) - *

- * - * @throws NullPointerException - * if given lineList or columnList or both is null. + * Inserts {@code value} at {@code [lineIndex, columnIndex]}, resizing if necessary. + * New lines/columns created by resizing are filled using {@code lineList} and {@code columnList}. + * Similar behavior to the array version regarding list sizes. Absolute values of indexes are used. + * + * @param lineIndex The line index. + * @param columnIndex The column index. + * @param value The value to insert. + * @param lineList Data for newly created parts of the inserted line. + * @param columnList Data for newly created parts of the inserted column. + * @throws NullPointerException if {@code lineList} or {@code columnList} is null. */ - void insertElement(int lineIndex, int columnIndex, Data value, - List lineList, List columnList); + void insertElement(int lineIndex, int columnIndex, Data value, List lineList, List columnList); /** - * Inserts line in any places that you want. - *

- * Given index can be negative and it will add line at the head of this - * matrix. - *

- *

- * If index will be out of the range of dimension this method will resize - * matrix automatically. - *

+ * Inserts a new, empty line (filled with nulls) at the specified {@code index}. + * Existing lines at or after {@code index} are shifted down. + * Handles negative/out-of-range {@code index} by resizing and appropriately placing the new line. + * + * @param index The index at which to insert the new line. */ void insertLine(int index); /** - * Inserts line in any places that you want and fill with default value. - *

- * Given index can be negative and it will add line at the head of this - * matrix. - *

- *

- * If index will be out of the range of dimension this method will resize - * matrix automatically. - *

- *

- * Fills all newly created empty places. - *

+ * Inserts a new line filled with {@code defaultValue} at the specified {@code index}. + * Existing lines are shifted. Handles negative/out-of-range {@code index} by resizing. + * Other newly created cells (due to resizing for index placement) are filled with nulls, and the specified line with {@code defaultValue}. + * + * @param index The index at which to insert. + * @param defaultValue The value to fill the new line with. */ void insertLine(int index, Data defaultValue); /** - * Inserts line in any places that you want and copy values from given - * lineArray to newly created line. - *

- * Given index can be negative and it will add line at the head of this - * matrix. - *

- *

- * If lineArray length is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. - *

- *

- * If lineArray length is less then this matrix line dimension than copied - * will be all lineArray and other places of this line will be null. - *

- *

- * Fills all newly created empty places. - *

- * - * @throws NullPointerException - * if given lineArray is null. + * Inserts a new line populated with values from {@code lineArray} at the specified {@code index}. + * Existing lines are shifted. Handles negative/out-of-range {@code index} by resizing. + * If {@code lineArray} length differs from column dimension, behavior is similar to {@link #addLine(Data...)}. + * Other newly created cells (due to resizing for index placement) are filled with nulls. + * + * @param index The index at which to insert. + * @param lineArray The data for the new line. + * @throws NullPointerException if {@code lineArray} is null. */ @SuppressWarnings(value = "unchecked") void insertLine(int index, Data... lineArray); /** - * Inserts line in any places that you want and copy values from given - * lineList to newly created row. - *

- * Given index can be negative and it will add line at the head of this - * matrix. - *

- *

- * If lineList size is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. - *

- *

- * If lineList size is less then this matrix line dimension than copied will - * be all lineList and other places of this line will be null. - *

- *

- * Fills all newly created empty places. - *

- * - * @throws NullPointerException - * if given lineList is null. + * Inserts a new line populated with values from {@code lineList} at the specified {@code index}. + * Similar behavior to {@link #insertLine(int, Data...)} regarding index handling and list size differences. + * + * @param index The index at which to insert. + * @param lineList The data for the new line. + * @throws NullPointerException if {@code lineList} is null. */ void insertLine(int index, List lineList); /** - * Inserts given matrix in this matrix in the given place (lineIndex) , - * (columnIndex). If dimensions will not be in range this method will - * automatically resize this matrix.
- *

- *

- * For example:
DataMatrix dm = new DataMatrix<>(3, new - * Integer(0));
dm.insertMatrix(1, 1, new DataMatrix(2, new - * Integer(1)));
Result:
Dimensions: 5 X 5
0 null null 0 0 - *
null 1 1 null null
null 1 1 null null
0 null null 0 0 - *
0 null null 0 0
- *

- * Example 2:
dm.insertMatrix(0, 4, new DataMatrix(2, new - * Integer(1)));
Result:
Dimensions: 3 X 6
0 0 0 null 1 1 - *
0 0 0 null 1 1
0 0 0 null null null
- *

- *

+ * Inserts the given {@code matrix} as a block into this matrix, starting at {@code [lineIndex, columnIndex]}. + * The current matrix may be resized to accommodate the inserted matrix. Cells outside the inserted block + * that are part of the resized area (if any) are filled with nulls. *

- * Example 3:
dm.insertMatrix(4, 0, new DataMatrix(2, new - * Integer(1)));
Dimensions: 6 X 3
0 0 0
0 0 0
0 0 0 - *
null null null
1 1 null
1 1 null
+ * Example: Inserting a 2x2 matrix B at (1,1) in a 3x3 matrix A might result in A becoming a 5x5 matrix + * if the original content of A needs to be shifted to make space. *

- * - * @throws IllegalArgumentException - * if indexes are negative. - * @throws NullPointerException - * if given matrix is null. + * @param lineIndex The starting line index for insertion. + * @param columnIndex The starting column index for insertion. + * @param matrix The matrix to insert. + * @throws IllegalArgumentException if {@code lineIndex} or {@code columnIndex} are negative. + * @throws NullPointerException if {@code matrix} is null. */ void insertMatrix(int lineIndex, int columnIndex, IDataMatrix matrix); /** - * Equals method should be override , otherwise equaled will be only - * reference. - * - * @return true if data matrix contains given value, otherwise returns - * false. - * - * @param value - * that should be checked if exist in this matrix. + * Checks if the matrix contains the specified {@code value}. + * Equality is typically determined by the {@code equals} method of the data elements. + * + * @param value The value to search for. + * @return {@code true} if the matrix contains the value, {@code false} otherwise. */ boolean is(Data value); /** - * @return true if given column index is in range [ 0 , columnDimension ] - * otherwise returns false. + * Checks if the given {@code columnIndex} is a valid column index for this matrix. + * (i.e., {@code 0 <= columnIndex < columnDimension}). + * + * @param columnIndex The column index to check. + * @return {@code true} if valid, {@code false} otherwise. */ boolean isColumnIndex(int columnIndex); /** - * @return true if matrix have only one column and many lines , otherwise - * returns false. + * Checks if this matrix is a column vector (i.e., has one column and more than one line). + * + * @return {@code true} if it is a column vector, {@code false} otherwise. */ boolean isColumnVector(); /** - * @return true if matrix dimensions are equal to given dimensions: - *

- * lineDimension should be equal to this matrix line dimension and - * columnDimension should be equal to this matrix column dimension , - * otherwise returns false. - *

+ * Checks if the dimensions of this matrix are equal to the specified {@code lineDimension} and {@code columnDimension}. + * + * @param lineDimension The line dimension to compare against. + * @param columnDimension The column dimension to compare against. + * @return {@code true} if dimensions are equal, {@code false} otherwise. */ boolean isDimensionsEqualTo(int lineDimension, int columnDimension); /** - * @return true if every element in this data matrix equals to given - * parameter (variable) , otherwise returns false. - *

- * Equals method should be override , otherwise equaled will be only - * reference. - *

+ * Checks if every element in this matrix is equal to the specified {@code variable}. + * Equality is determined by the {@code equals} method of the data elements. + * + * @param variable The value to compare every element against. + * @return {@code true} if all elements are equal to {@code variable}, {@code false} otherwise. */ boolean isEveryElementEqualTo(Data variable); /** - * @return true if in this matrix does not exists data like given parameter - * (variable) , otherwise returns false. - *

- * Equals method should be override , otherwise equaled will be only - * reference. - *

+ * Checks if no element in this matrix is equal to the specified {@code variable}. + * Equality is determined by the {@code equals} method of the data elements. + * + * @param variable The value to compare against. + * @return {@code true} if no element is equal to {@code variable}, {@code false} otherwise. */ boolean isEveryElementNotEqualTo(Data variable); /** - * @return true if given line index is in range [ 0 , lineDimension ] and - * column index is in range [ 0 , columnDimension ] otherwise - * returns false. + * Checks if the given {@code [lineIndex, columnIndex]} are valid indices for this matrix. + * + * @param lineIndex The line index to check. + * @param columnIndex The column index to check. + * @return {@code true} if both indices are valid, {@code false} otherwise. */ boolean isIndexes(int lineIndex, int columnIndex); /** - * @return true if given line index is in range [ 0 , lineDimension ] - * otherwise returns false. + * Checks if the given {@code lineIndex} is a valid line index for this matrix. + * (i.e., {@code 0 <= lineIndex < lineDimension}). + * + * @param lineIndex The line index to check. + * @return {@code true} if valid, {@code false} otherwise. */ boolean isLineIndex(int lineIndex); /** - * @return true if matrix have many lines and columns (lineDimension > 1 && - * columnDimension > 1) , otherwise returns false. + * Checks if this is a "true" matrix (i.e., has more than one line AND more than one column). + * + * @return {@code true} if {@code lineDimension > 1 && columnDimension > 1}, {@code false} otherwise. */ boolean isMatrix(); /** - * @return true if this matrix contains even one null, otherwise returns - * false. + * Checks if this matrix contains at least one {@code null} element. + * + * @return {@code true} if there is at least one null element, {@code false} otherwise. */ boolean isNull(); /** - * @return true if matrix dimensions are not equal, otherwise returns false. + * Checks if this matrix is rectangular (i.e., line dimension is not equal to column dimension). + * + * @return {@code true} if dimensions are not equal, {@code false} otherwise. */ boolean isRectangular(); /** - * @return true if matrix contains only one data (dimensions are: 1x1), - * otherwise returns false. + * Checks if this matrix is a scalar (i.e., has dimensions 1x1). + * + * @return {@code true} if it is a 1x1 matrix, {@code false} otherwise. */ boolean isScalar(); /** - * @return true if matrix dimensions are equal, otherwise returns false. + * Checks if this matrix is square (i.e., line dimension equals column dimension). + * + * @return {@code true} if dimensions are equal, {@code false} otherwise. */ boolean isSquare(); /** - * @return true if matrix have only one line and many columns, otherwise - * returns false. + * Checks if this matrix is a row vector (i.e., has one line and more than one column). + * + * @return {@code true} if it is a row vector, {@code false} otherwise. */ boolean isVector(); /** - * @return new matrix with dimensions this.columnDimension + - * matrix.columnDimension X max(this.lineDimension, - * matrix.lineDimension). All data of this matrices will be in to - * this new matrix. - * @throws NullPointerException - * if matrix is null. + * Creates and returns a new matrix by joining the columns of the specified {@code matrix} to the right of this matrix. + * The resulting matrix will have a line dimension equal to {@code max(this.lineDimension, matrix.lineDimension)} + * and a column dimension equal to {@code this.columnDimension + matrix.columnDimension}. + * Cells in the expanded area not covered by either original matrix are filled with nulls. + * + * @param matrix The matrix to join with this one. + * @return A new {@code DataMatrix} instance representing the joined matrix. + * @throws NullPointerException if {@code matrix} is null. */ DataMatrix joinMatrixAtColumn(IDataMatrix matrix); /** - * @return new matrix with dimensions this.columnDimension + - * matrix.columnDimension X max(this.lineDimension, - * matrix.lineDimension). All data of this matrices will be in to - * this new matrix and if there will be any empty place will fill - * with defaultValue. - * @throws NullPointerException - * if matrix is null. + * Creates and returns a new matrix by joining the columns of the specified {@code matrix} to the right of this matrix. + * Uses {@code defaultValue} to fill cells in the expanded area not covered by either original matrix. + * + * @param matrix The matrix to join with this one. + * @param defaultValue The value for new cells created by differing dimensions. + * @return A new {@code DataMatrix} instance representing the joined matrix. + * @throws NullPointerException if {@code matrix} is null. */ - DataMatrix joinMatrixAtColumn(IDataMatrix matrix, - Data defaultValue); + DataMatrix joinMatrixAtColumn(IDataMatrix matrix, Data defaultValue); /** - * @return new matrix with dimensions this.lineDimension + - * matrix.lineDimension X max(this.columnDimension, - * matrix.columnDimension). All data of this matrices will be in to - * this new matrix. - * @throws NullPointerException - * if matrix is null. + * Creates and returns a new matrix by joining the rows of the specified {@code matrix} below this matrix. + * The resulting matrix will have a column dimension equal to {@code max(this.columnDimension, matrix.columnDimension)} + * and a line dimension equal to {@code this.lineDimension + matrix.lineDimension}. + * Cells in the expanded area not covered by either original matrix are filled with nulls. + * + * @param matrix The matrix to join with this one. + * @return A new {@code DataMatrix} instance representing the joined matrix. + * @throws NullPointerException if {@code matrix} is null. */ DataMatrix joinMatrixAtLine(IDataMatrix matrix); /** - * @return new matrix with dimensions this.lineDimension + - * matrix.lineDimension X max(this.columnDimension, - * matrix.columnDimension). All data of this matrices will be in to - * this new matrix and if there will be any empty place will fill - * with defaultValue. - * @throws NullPointerException - * if matrix is null. + * Creates and returns a new matrix by joining the rows of the specified {@code matrix} below this matrix. + * Uses {@code defaultValue} to fill cells in the expanded area not covered by either original matrix. + * + * @param matrix The matrix to join with this one. + * @param defaultValue The value for new cells created by differing dimensions. + * @return A new {@code DataMatrix} instance representing the joined matrix. + * @throws NullPointerException if {@code matrix} is null. */ - DataMatrix joinMatrixAtLine(IDataMatrix matrix, - Data defaultValue); + DataMatrix joinMatrixAtLine(IDataMatrix matrix, Data defaultValue); /** - * Removes column from given place (index). - * - * @throws ArrayIndexOutOfBoundsException - * if given index is out of this matrix column dimension range. - * @throws IllegalArgumentException - * if matrix has only one column. + * Removes the column at the specified {@code index}. Subsequent columns are shifted to the left. + * + * @param index The index of the column to remove. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of the matrix's column dimension range. + * @throws IllegalArgumentException if the matrix has only one column and removal would make it empty (0 columns). */ void removeColumn(int index); /** - * Removes data at given place and also deletes line and column of this - * matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if given lineIndex or columnIndex are negative or out of this - * matrix dimensions range. - * @throws IllegalArgumentException - * if only one line or column is left. + * Removes the element at the specified {@code [lineIndex, columnIndex]} by removing both the entire line + * and the entire column that intersect at this element. This significantly reduces matrix dimensions. + * + * @param lineIndex The line index of the element whose line and column are to be removed. + * @param columnIndex The column index of the element. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} or {@code columnIndex} are out of range. + * @throws IllegalArgumentException if removing the line or column would result in an invalid matrix (e.g., 0 lines or 0 columns). */ void removeElement(int lineIndex, int columnIndex); /** - * Removes last column of this matrix. - * - * @throws IllegalArgumentException - * if matrix has only one column. + * Removes the last column of this matrix. + * + * @throws IllegalArgumentException if the matrix has only one column and removal would make it empty (0 columns). */ void removeColumn(); /** - * Removes last line of this matrix. - * - * @throws IllegalArgumentException - * if matrix has only one line. + * Removes the last line (row) of this matrix. + * + * @throws IllegalArgumentException if the matrix has only one line and removal would make it empty (0 lines). */ void removeLine(); /** - * Removes line from given place (index). - * - * @throws ArrayIndexOutOfBoundsException - * if given index is out of this matrix line dimension range. - * @throws IllegalArgumentException - * if matrix has only one line. + * Removes the line (row) at the specified {@code index}. Subsequent lines are shifted up. + * + * @param index The index of the line to remove. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of the matrix's line dimension range. + * @throws IllegalArgumentException if the matrix has only one line and removal would make it empty (0 lines). */ void removeLine(int index); /** - * Resize matrix: Matrix can be decreased or increased, it depends on given - * dimensions. - *

- * You can gave any dimensions if it would not be zero or negative! - *

- *

- * If in this matrix will be any data it also will be in resized matrix. - *

- *

- * if you want to decrease size of this matrix and there is some data, after - * resize data which will be out of the given dimensions will be lost. - *

- * - * @throws IllegalArgumentException - * if given dimensions are negative or zero. + * Resizes the matrix to the specified {@code lineDimension} and {@code columnDimension}. + * If new dimensions are smaller, data is truncated. + * If new dimensions are larger, new cells are filled with {@code null}. + * + * @param lineDimension The new number of lines (rows). + * @param columnDimension The new number of columns. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. */ void resize(int lineDimension, int columnDimension); /** - * Resize matrix: Matrix can be decreased or increased, it depends on given - * dimensions. - *

- * You can gave any dimension if it would not be zero or negative! - *

- *

- * If in this matrix will be any data it also will be in resized matrix. - *

- *

- * if you want to decrease size of this matrix and there is some data, after - * resize data which will be out of the given dimensions will be lost. - *

- *

- * After this resize you will get square matrix. - *

- * - * @throws IllegalArgumentException - * if given dimension is negative or zero. + * Resizes the matrix to a square matrix of the specified {@code squareDimension}. + * Behavior regarding data truncation or null-filling for new cells is the same as {@link #resize(int, int)}. + * + * @param squareDimension The new number of lines and columns. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ void resize(int squareDimension); /** - * Resize matrix: Matrix can be decreased or increased, it depends on given - * dimensions. Also fills new empty places with default value if you - * increase size and there will be empty places, otherwise it just ignores - * given default value. - *

- * You can gave any dimensions if it would not be zero or negative! - *

- *

- * If in this matrix will be any data it also will be in resized matrix. - *

- *

- * if you want to decrease size of this matrix and there is some data, after - * resize data which will be out of the given dimensions will be lost. - *

- * - * @throws IllegalArgumentException - * if given dimensions are negative or zero. + * Resizes the matrix to the specified dimensions. + * If new dimensions are smaller, data is truncated. + * If new dimensions are larger, new cells are filled with the {@code defaultValue}. + * + * @param lineDimension The new number of lines. + * @param columnDimension The new number of columns. + * @param defaultValue The value for new cells if the matrix is enlarged. + * @throws IllegalArgumentException if {@code lineDimension} or {@code columnDimension} are not positive. */ void resize(int lineDimension, int columnDimension, Data defaultValue); /** - * Resize matrix: Matrix can be decreased or increased, it depends on given - * dimensions. Also fills new empty places with default value if you - * increase size and there will be empty places, otherwise it just ignores - * given default value. - *

- * You can gave any dimension if it would not be zero or negative! - *

- *

- * If in this matrix will be any data it also will be in resized matrix. - *

- *

- * if you want to decrease size of this matrix and there is some data, after - * resize data which will be out of the given dimensions will be lost. - *

- *

- * After this resize you will get square matrix. - *

- * - * @throws IllegalArgumentException - * if given dimension is negative or zero. + * Resizes the matrix to a square matrix of {@code squareDimension}. + * New cells (if any) are filled with {@code defaultValue}. + * + * @param squareDimension The new number of lines and columns. + * @param defaultValue The value for new cells if the matrix is enlarged. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ void resize(int squareDimension, Data defaultValue); /** - * Reverse matrix's column on given place (columnIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex is out of this matrix's column dimension - * range. + * Reverses the order of elements in the column at the specified {@code columnIndex}. + * + * @param columnIndex The index of the column to reverse. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. */ void reverseColumn(int columnIndex); /** - * Reverse matrix's columns. + * Reverses the order of elements in all columns of this matrix. */ void reverseColumns(); /** - * Reverse matrix's line on given place (lineIndex). - * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex is out of this matrix's line dimension range. + * Reverses the order of elements in the line (row) at the specified {@code lineIndex}. + * + * @param lineIndex The index of the line to reverse. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. */ void reverseLine(int lineIndex); /** - * Reverse matrix's lines. + * Reverses the order of elements in all lines (rows) of this matrix. */ void reverseLines(); /** - * Copy values from columnArray to given column (columnIndex). - *

- * If columnArray length is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. - *

- *

- * If columnArray length is less then this matrix column dimension than - * copied will be all columnArray and other places of this line will be - * null. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if given columnIndex is out of this matrix column dimension - * range. - * @throws NullPointerException - * if given columnArray is null. + * Sets the content of the column at {@code columnIndex} with values from {@code columnArray}. + * If {@code columnArray} length is shorter than line dimension, remaining cells are null. + * If longer, excess values are ignored. + * + * @param columnIndex The index of the column to modify. + * @param columnArray The data to set in the column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if {@code columnArray} is null. */ @SuppressWarnings(value = "unchecked") void setColumn(int columnIndex, Data... columnArray); /** - * Copy values from columnList to given column (columnIndex). - *

- * If columnList size is bigger then this matrix column dimension than - * copied will be only column dimension number of data, other data will be - * ignored. - *

- *

- * If columnList size is less then this matrix column dimension than copied - * will be all columnList and other places of this line will be null. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if given columnIndex is out of this matrix column dimension - * range. - * @throws NullPointerException - * if given columnList is null. + * Sets the content of the column at {@code columnIndex} with values from {@code columnList}. + * Similar behavior to the array version regarding list size. + * + * @param columnIndex The index of the column to modify. + * @param columnList The data to set in the column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. + * @throws NullPointerException if {@code columnList} is null. */ void setColumn(int columnIndex, List columnList); /** - * Fills column on given place (index) with given value. - * - * @throws ArrayIndexOutOfBoundsException - * if given index is out of this matrix column dimension range. + * Fills all cells in the column at {@code columnIndex} with the specified {@code value}. + * + * @param columnIndex The index of the column to fill. + * @param value The value to set for all cells in the column. + * @throws ArrayIndexOutOfBoundsException if {@code columnIndex} is out of range. */ void setColumn(int columnIndex, Data value); /** - * Stores data in to this data matrix and fills dimensions automatically. - * - *

- * You also can gave jagged data, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - * @throws NullPointerException - * if given data is null. + * Replaces the entire data of this matrix with the data from the given 2D array {@code data}. + * Dimensions are automatically adjusted. Jagged arrays are supported. + * + * @param data The new 2D array data for the matrix. + * @throws NullPointerException if {@code data} is null. */ @SuppressWarnings(value = "unchecked") void setData(Data[]... data); /** - * Stores data in to this data matrix and fills dimensions automatically. - * - *

- * You also can gave jagged data, it will automatically fit dimensions: It - * will take max line and column dimensions. - *

- * - * @throws NullPointerException - * if given data is null. - * - * @throws IllegalArgumentException - * if data is not filled at least with one element. + * Replaces the entire data of this matrix with the data from the given {@code List>}. + * Dimensions are automatically adjusted. Jagged lists are supported. + * + * @param data The new list of lists data for the matrix. + * @throws NullPointerException if {@code data} or any inner list is null. + * @throws IllegalArgumentException if {@code data} is empty. */ void setData(List> data); /** - * Fills diagonal on given place (index). If index is 0 then it will fill - * main diagonal, if index is more than 0 it fills up diagonal , if index is - * less then 0 it fills down diagonal. - * - * @throws ArrayIndexOutOfBoundsException - * if index is not in matrix diagonal dimension range. + * Fills the specified diagonal with {@code value}. + * See {@link #getDiagonal(int)} for {@code index} interpretation. + * + * @param index The index of the diagonal to fill. + * @param value The value to set for elements on the diagonal. + * @throws ArrayIndexOutOfBoundsException if {@code index} is not a valid diagonal index. */ void setDiagonal(int index, Data value); /** - * Fills diagonal on given place (index) from right to left direction. If - * index is 0 then it will fill main diagonal, if index is more than 0 it - * fills up diagonal , if index is less then 0 it fills down diagonal. - * - * @throws ArrayIndexOutOfBoundsException - * if index is not in matrix diagonal dimension range. + * Fills the specified anti-diagonal (right-to-left) with {@code value}. + * See {@link #getDiagonal2(int)} for {@code index} interpretation. + * + * @param index The index of the anti-diagonal to fill. + * @param value The value to set for elements on the anti-diagonal. + * @throws ArrayIndexOutOfBoundsException if {@code index} is not a valid anti-diagonal index. */ void setDiagonal2(int index, Data value); /** - * Sets id to this matrix. - * - * @throws IllegalArgumentException - * if id is not unique and this kind of id already exists. + * Sets the unique identifier (ID) for this matrix. + * + * @param id The new ID string. + * @throws IllegalArgumentException if {@code id} is null, empty, or not unique (if applicable to implementation). */ void setId(String id); /** - * Sets value to the last element of this matrix. + * Sets the value of the last element of this matrix (element at {@code [lineDimension-1, columnDimension-1]}). + * + * @param value The new value for the last element. + * @throws ArrayIndexOutOfBoundsException if the matrix is empty. */ void setLastElement(Data value); /** - * Copy values from lineArray to given line (lineIndex). - *

- * If lineArray length is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. - *

- *

- * If lineArray length is less then this matrix line dimension than copied - * will be all lineArray and other places of this line will be null. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if given lineIndex is out of this matrix line dimension - * range. - * @throws NullPointerException - * if given lineArray is null. + * Sets the content of the line at {@code lineIndex} with values from {@code lineArray}. + * If {@code lineArray} length is shorter than column dimension, remaining cells are null. + * If longer, excess values are ignored. + * + * @param lineIndex The index of the line to modify. + * @param lineArray The data to set in the line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if {@code lineArray} is null. */ @SuppressWarnings(value = "unchecked") void setLine(int lineIndex, Data... lineArray); /** - * Copy values from lineList to given line (lineIndex). - *

- * If lineList size is bigger then this matrix line dimension than copied - * will be only line dimension number of data, other data will be ignored. - *

- *

- * If lineList size is less then this matrix line dimension than copied will - * be all lineArray and other places of this line will be null. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if given lineIndex is out of this matrix line dimension - * range. - * @throws NullPointerException - * if given lineList is null. + * Sets the content of the line at {@code lineIndex} with values from {@code lineList}. + * Similar behavior to the array version regarding list size. + * + * @param lineIndex The index of the line to modify. + * @param lineList The data to set in the line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. + * @throws NullPointerException if {@code lineList} is null. */ void setLine(int lineIndex, List lineList); /** - * Fills line on given place (index) with given value. - * - * @throws ArrayIndexOutOfBoundsException - * if given index is out of this matrix line dimension range. + * Fills all cells in the line at {@code lineIndex} with the specified {@code value}. + * + * @param lineIndex The index of the line to fill. + * @param value The value to set for all cells in the line. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} is out of range. */ void setLine(int lineIndex, Data value); /** - * Fills main diagonal with given value. + * Fills all cells on the main diagonal (top-left to bottom-right) with {@code value}. + * + * @param value The value to set for elements on the main diagonal. */ void setMainDiagonal(Data value); /** - * Copy values from diagonalArray to main diagonal. - *

- * If diagonalArray length is bigger then this matrix diagonal dimension - * than copied will be only diagonal dimension number of data, other data - * will be ignored. - *

- *

- * If diagonalArray size is less then this matrix diagonal dimension than - * copied will be all diagonalArray and other places of this diagonal will - * be null. - *

- * - * @throws NullPointerException - * if diagonalArray is null. + * Sets the main diagonal with values from {@code diagonalArray}. + * If array length is shorter than min dimension, remaining diagonal cells are null. + * If longer, excess values are ignored. + * + * @param diagonalArray The data for the main diagonal. + * @throws NullPointerException if {@code diagonalArray} is null. */ @SuppressWarnings(value = "unchecked") void setMainDiagonal(Data... diagonalArray); /** - * Copy values from diagonalList to main diagonal. - *

- * If diagonalList size is bigger then this matrix diagonal dimension than - * copied will be only diagonal dimension number of data, other data will be - * ignored. - *

- *

- * If diagonalList size is less then this matrix diagonal dimension than - * copied will be all diagonalList and other places of this diagonal will be - * null. - *

- * - * @throws NullPointerException - * if diagonalList is null. + * Sets the main diagonal with values from {@code diagonalList}. + * Similar behavior to the array version regarding list size. + * + * @param diagonalList The data for the main diagonal. + * @throws NullPointerException if {@code diagonalList} is null. */ void setMainDiagonal(List diagonalList); /** - * Sets name to this matrix. - * - * @throws NullPointerException - * if name is null. + * Sets the name for this matrix. + * + * @param name The new name string. + * @throws NullPointerException if {@code name} is null. */ void setName(String name); /** - * Fills second diagonal with given value. + * Fills all cells on the secondary diagonal (top-right to bottom-left) with {@code value}. + * + * @param value The value to set for elements on the secondary diagonal. */ void setSecondDiagonal(Data value); /** - * Copy values from diagonalArray to second diagonal. - *

- * If diagonalArray length is bigger then this matrix diagonal dimension - * than copied will be only diagonal dimension number of data, other data - * will be ignored. - *

- *

- * If diagonalArray length is less then this matrix diagonal dimension than - * copied will be all diagonalArray and other places of this diagonal will - * be null. - *

- * - * @throws NullPointerException - * if diagonalArray is null. + * Sets the secondary diagonal with values from {@code diagonalArray}. + * Similar behavior to {@link #setMainDiagonal(Data...)}. + * + * @param diagonalArray The data for the secondary diagonal. + * @throws NullPointerException if {@code diagonalArray} is null. */ @SuppressWarnings(value = "unchecked") void setSecondDiagonal(Data... diagonalArray); /** - * Copy values from diagonalList to second diagonal. - *

- * If diagonalList size is bigger then this matrix diagonal dimension than - * copied will be only diagonal dimension number of data, other data will be - * ignored. - *

- *

- * If diagonalList size is less then this matrix diagonal dimension than - * copied will be all diagonalList and other places of this diagonal will be - * null. - *

- * - * @throws NullPointerException - * if diagonalList is null. + * Sets the secondary diagonal with values from {@code diagonalList}. + * Similar behavior to {@link #setMainDiagonal(List)}. + * + * @param diagonalList The data for the secondary diagonal. + * @throws NullPointerException if {@code diagonalList} is null. */ void setSecondDiagonal(List diagonalList); /** - * Sets value to the given place. - * - * @throws ArrayIndexOutOfBoundsException - * If given place is out of the range of this matrix dimensions. + * Sets the value at the specified {@code [lineIndex, columnIndex]}. + * + * @param lineIndex The line index of the element to set. + * @param columnIndex The column index of the element to set. + * @param value The new value for the element. + * @throws ArrayIndexOutOfBoundsException if {@code lineIndex} or {@code columnIndex} is out of range. */ void setValue(int lineIndex, int columnIndex, Data value); /** - * Sorts this matrix column which locates on given index by ascending order. - * Comparable should be implemented by data which is stored in this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts the column at the specified {@code index} in ascending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @param index The index of the column to sort. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if the column contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortColumnAsc(int index); /** - * Sorts this matrix column which locates on given index. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException + * Sorts the column at the specified {@code index} using the provided {@code comparator}. + * + * @param index The index of the column to sort. + * @param comparator The comparator to determine the order. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if {@code comparator} is null or the column contains nulls not handled by comparator. */ void sortColumn(int index, Comparator comparator); /** - * Sorts this matrix column which locates on given index by descending - * order. Comparable should be implemented by data which is stored in this - * matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts the column at the specified {@code index} in descending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @param index The index of the column to sort. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if the column contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortColumnDesc(int index); /** - * Sorts this matrix line which locates on given index by ascending order. - * Comparable should be implemented by data which is stored in this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts the line (row) at the specified {@code index} in ascending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @param index The index of the line to sort. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if the line contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortLineAsc(int index); /** - * Sorts this matrix line which locates on given index. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Sorts the line (row) at the specified {@code index} using the provided {@code comparator}. + * + * @param index The index of the line to sort. + * @param comparator The comparator to determine the order. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if {@code comparator} is null or the line contains nulls not handled by comparator. */ void sortLine(int index, Comparator comparator); /** - * Sorts this matrix line which locates on given index by descending order. - * Comparable should be implemented by data which is stored in this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if index is out of this matrix dimension range. - * @throws NullPointerException - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts the line (row) at the specified {@code index} in descending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @param index The index of the line to sort. + * @throws ArrayIndexOutOfBoundsException if {@code index} is out of range. + * @throws NullPointerException if the line contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortLineDesc(int index); /** - * Sorts all columns of this matrix by ascending order. Comparable should be - * implemented by data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts all columns of this matrix in ascending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @throws NullPointerException if any column contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortColumnsAsc(); /** - * Sorts all columns of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Sorts all columns of this matrix using the provided {@code comparator}. + * + * @param comparator The comparator to determine the order for each column. + * @throws NullPointerException if {@code comparator} is null or any column contains nulls not handled by comparator. */ void sortColumns(Comparator comparator); /** - * Sorts all columns of this matrix by descending order. Comparable should - * be implemented by data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts all columns of this matrix in descending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @throws NullPointerException if any column contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortColumnsDesc(); /** - * Sorts all lines of this matrix by ascending order. Comparable should be - * implemented by data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts all lines (rows) of this matrix in ascending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @throws NullPointerException if any line contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortLinesAsc(); /** - * Sorts all lines of this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null or given comparator is - * null. + * Sorts all lines (rows) of this matrix using the provided {@code comparator}. + * + * @param comparator The comparator to determine the order for each line. + * @throws NullPointerException if {@code comparator} is null or any line contains nulls not handled by comparator. */ void sortLines(Comparator comparator); /** - * Sorts all lines of this matrix by descending order. Comparable should be - * implemented by data which is stored in this matrix. - * - * @throws NullPointerException - * if this matrix contains even one null. - * @throws ClassCastException - * if data witch is stored in this matrix does not implements - * Comparable interface. + * Sorts all lines (rows) of this matrix in descending order. + * Requires that data type {@code Data} implements {@link Comparable}. + * + * @throws NullPointerException if any line contains {@code null} values. + * @throws ClassCastException if data does not implement {@code Comparable}. */ void sortLinesDesc(); /** - * @return sub matrix of this matrix. - * - * @throws ArrayIndexOutOfBoundsException - * if id given indexes are out of range of this matrix - * dimensions. - * @throws IllegalArgumentException - * if indexes are given incorrectly. + * Extracts a sub-matrix from this matrix. + * The sub-matrix includes elements from {@code startLineIndex} to {@code endLineIndex} (inclusive) + * and from {@code startColumnIndex} to {@code endColumnIndex} (inclusive). + * + * @param startLineIndex The starting line index of the sub-matrix. + * @param startColumnIndex The starting column index of the sub-matrix. + * @param endLineIndex The ending line index of the sub-matrix. + * @param endColumnIndex The ending column index of the sub-matrix. + * @return A new {@code DataMatrix} instance representing the sub-matrix. + * @throws ArrayIndexOutOfBoundsException if any index is out of range. + * @throws IllegalArgumentException if {@code startLineIndex > endLineIndex} or {@code startColumnIndex > endColumnIndex}. */ - DataMatrix subMatrix(int startLineIndex, int startColumnIndex, - int endLineIndex, int endColumnIndex); + DataMatrix subMatrix(int startLineIndex, int startColumnIndex, int endLineIndex, int endColumnIndex); /** - * Swaps this matrixes, even name and id. - * - * @throws NullPointerException - * if given matrix is null. + * Swaps the entire content (data, dimensions, name, ID) of this matrix with the specified {@code matrix}. + * + * @param matrix The matrix to swap content with. + * @throws NullPointerException if {@code matrix} is null. */ void swap(IDataMatrix matrix); /** - * Changes place of tow column witch are stored on given places. - *

- * it means that column witch is stored in columnIndex_1 will stored in - * columnIndex_2 and column witch was stored in columnIndex_2 will stored in - * columnIndex_1. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if columnIndex_1 or columnIndex_2 or both are out of this - * matrix column dimension range. + * Swaps the columns at {@code columnIndex_1} and {@code columnIndex_2}. + * + * @param columnIndex_1 The index of the first column to swap. + * @param columnIndex_2 The index of the second column to swap. + * @throws ArrayIndexOutOfBoundsException if either index is out of range. */ void swapColumns(int columnIndex_1, int columnIndex_2); /** - * Changes data between given and this matrix. - * - * @throws NullPointerException - * if given matrix is null. + * Swaps only the data (and dimensions) of this matrix with the specified {@code matrix}. + * Name and ID of both matrices remain unchanged. + * + * @param matrix The matrix to swap data with. + * @throws NullPointerException if {@code matrix} is null. */ void swapData(IDataMatrix matrix); /** - * Changes places of tow data on given places. - * - * @throws ArrayIndexOutOfBoundsException - * if given indexes are out of this matrix dimensions range. + * Swaps the data elements at {@code [lineIndex_1, columnIndex_1]} and {@code [lineIndex_2, columnIndex_2]}. + * + * @param lineIndex_1 The line index of the first element. + * @param columnIndex_1 The column index of the first element. + * @param lineIndex_2 The line index of the second element. + * @param columnIndex_2 The column index of the second element. + * @throws ArrayIndexOutOfBoundsException if any index is out of range. */ - void swapData(int lineIndex_1, int columnIndex_1, int lineIndex_2, - int columnIndex_2); + void swapData(int lineIndex_1, int columnIndex_1, int lineIndex_2, int columnIndex_2); /** - * Changes places to given data_1 and data_2 if both of them exists in this - * matrix. - *

- * Equals method should be override for given data parameters. - *

- * - * @throws IllegalArgumentException - * if this matrix do not contains any of this given data or - * both. - * @throws NullPointerException - * if given data_1 or data_2 or both is null. + * Finds the first occurrences of {@code data_1} and {@code data_2} in the matrix and swaps them. + * Element equality is determined by their {@code equals} method. + * + * @param data_1 The first data element to swap. + * @param data_2 The second data element to swap. + * @throws IllegalArgumentException if either {@code data_1} or {@code data_2} (or both) are not found in the matrix. + * @throws NullPointerException if {@code data_1} or {@code data_2} is null. */ void swapData(Data data_1, Data data_2); /** - * Changes place of tow line witch are stored on given places. - *

- * it means that line witch is stored in lineIndex_1 will stored in - * lineIndex_2 and line witch was stored in lineIndex_2 will stored in - * lineIndex_1. - *

- * - * @throws ArrayIndexOutOfBoundsException - * if lineIndex_1 or lineIndex_2 or both are out of this matrix - * line dimension range. + * Swaps the lines (rows) at {@code lineIndex_1} and {@code lineIndex_2}. + * + * @param lineIndex_1 The index of the first line to swap. + * @param lineIndex_2 The index of the second line to swap. + * @throws ArrayIndexOutOfBoundsException if either index is out of range. */ void swapLines(int lineIndex_1, int lineIndex_2); /** - * @return list from this matrix, it means that: All lines will be located - * side by side together in list started from first line. + * Converts the matrix into a single {@code List}, with elements added row by row. + * + * @return A list containing all elements of the matrix in row-major order. */ List toList(); /** - * @return list from this matrix, it means that: All columns will be located - * side by side together in list started from first column. + * Converts the matrix into a single {@code List}, with elements added column by column. + * + * @return A list containing all elements of the matrix in column-major order. */ List toListByColumn(); /** - * Transpose this matrix. - * - * @return Transposed matrix + * Transposes this matrix (swaps rows with columns). This operation modifies the current matrix. + * + * @return A reference to this transposed matrix. */ DataMatrix transpose(); /** - * Writes data as DataMatrix in to given file. If data is not primitive than - * Serializable interface should be implemented by this data. - * - * @throws FileNotFoundException - * if given file does not exists. - * @throws IOException - * if there will be some problem with input. - * @throws NullPointerException - * if given fileName is null or if every element is null. - * @throws NotSerializableException - * if stored data does not implements Serializable interface. + * Writes the matrix object to a file using Java serialization. + * The data type {@code Data} (if not primitive) must implement {@link java.io.Serializable}. + * + * @param fileName The name of the file to write the serialized object to. + * @throws java.io.FileNotFoundException if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason. + * @throws java.io.IOException if an I/O error occurs while writing to the file. + * @throws NullPointerException if {@code fileName} is null. + * @throws java.io.NotSerializableException if any object to be serialized does not implement the {@code java.io.Serializable} interface. */ - void writeObject(String fileName) throws java.io.FileNotFoundException, - java.io.IOException, NullPointerException, - java.io.NotSerializableException; + void writeObject(String fileName) throws java.io.FileNotFoundException, java.io.IOException, NullPointerException, java.io.NotSerializableException; /** - * Writes data in to given file using toString method for data which is - * stored in this matrix. - *

- * Uses one space to separate data. - *

- * - * @throws FileNotFoundException - * if given file does not exists. - * @throws IOException - * if there will be some problem with input. - * @throws NullPointerException - * if given fileName is null or if every element is null. + * Writes the string representation of the matrix data to the specified file. + * Elements are separated by a single space. Each row is on a new line. + * + * @param fileName The name of the file to write to. + * @throws java.io.FileNotFoundException if the file cannot be opened or created. + * @throws java.io.IOException if an I/O error occurs. + * @throws NullPointerException if {@code fileName} is null. */ - void write(String fileName) throws java.io.FileNotFoundException, - java.io.IOException, NullPointerException; + void write(String fileName) throws java.io.FileNotFoundException, java.io.IOException, NullPointerException; /** - * Writes data in to given file using toString method for data which is - * stored in this matrix. - *

- * Data will be separated by given separator. - *

- * - * @throws FileNotFoundException - * if given file does not exists. - * @throws IOException - * if there will be some problem with input. - * @throws NullPointerException - * if given fileName is null or if every element is null. + * Writes the string representation of the matrix data to the specified file, using {@code separator} between elements. + * Each row is on a new line. + * + * @param fileName The name of the file to write to. + * @param separator The character to use for separating elements in a row. + * @throws java.io.FileNotFoundException if the file cannot be opened or created. + * @throws java.io.IOException if an I/O error occurs. + * @throws NullPointerException if {@code fileName} is null. */ - void write(String fileName, char separator) - throws java.io.FileNotFoundException, java.io.IOException, - NullPointerException; + void write(String fileName, char separator) throws java.io.FileNotFoundException, java.io.IOException, NullPointerException; /** - * Writes data in to the end of the given file if append argument will be - * true. Using toString method for data which is stored in this matrix. - *

- * Uses one space to separate data. - *

- * - * @throws FileNotFoundException - * if given file does not exists. - * @throws IOException - * if there will be some problem with input. - * @throws NullPointerException - * if given fileName is null or if every element is null. + * Writes the string representation of the matrix data to the specified file. + * If {@code append} is true, data is written to the end of the file. + * Elements are separated by a single space. Each row is on a new line. + * + * @param fileName The name of the file to write to. + * @param append If {@code true}, then data will be written to the end of the file rather than the beginning. + * @throws java.io.FileNotFoundException if the file cannot be opened or created. + * @throws java.io.IOException if an I/O error occurs. + * @throws NullPointerException if {@code fileName} is null. */ - void write(String fileName, boolean append) - throws java.io.FileNotFoundException, java.io.IOException, - NullPointerException; + void write(String fileName, boolean append) throws java.io.FileNotFoundException, java.io.IOException, NullPointerException; /** - * Writes data in to the end of the given file if append argument will be - * true. Using toString method for data which is stored in this matrix. - *

- * Data will be separated by given separator. - *

- * - * @throws FileNotFoundException - * if given file does not exists. - * @throws IOException - * if there will be some problem with input. - * @throws NullPointerException - * if given fileName is null or if every element is null. - */ - void write(String fileName, char separator, boolean append) - throws java.io.FileNotFoundException, java.io.IOException, - NullPointerException; + * Writes the string representation of the matrix data to the specified file, using {@code separator}. + * If {@code append} is true, data is written to the end of the file. + * + * @param fileName The name of the file to write to. + * @param separator The character for separating elements. + * @param append If {@code true}, data is written to the end of the file. + * @throws java.io.FileNotFoundException if the file cannot be opened or created. + * @throws java.io.IOException if an I/O error occurs. + * @throws NullPointerException if {@code fileName} is null. + */ + void write(String fileName, char separator, boolean append) throws java.io.FileNotFoundException, java.io.IOException, NullPointerException; } \ No newline at end of file diff --git a/src/main/kotlin/com/nodrex/datamatrix/Matrix.java b/src/main/kotlin/com/nodrex/datamatrix/Matrix.java index 3caca3b..b6c9e24 100644 --- a/src/main/kotlin/com/nodrex/datamatrix/Matrix.java +++ b/src/main/kotlin/com/nodrex/datamatrix/Matrix.java @@ -953,126 +953,150 @@ public Matrix transpose() { } /** - * @return eye matrix with given dimensions. - * @throws IllegalArgumentException - * if given linedimension or columndimension are negative or - * zero. - */ - public static Matrix eye(int linedimension, int columndimension) - throws IllegalArgumentException { - Matrix matrix = new Matrix(linedimension, columndimension, - new Double(0)); - matrix.setMainDiagonal(new Double(1)); + * Creates an identity matrix (eye matrix) with the specified dimensions. + * An identity matrix has 1.0s on its main diagonal and 0.0s elsewhere. + * + * @param linedimension The number of lines (rows). + * @param columndimension The number of columns. + * @return A new identity {@code Matrix}. + * @throws IllegalArgumentException if {@code linedimension} or {@code columndimension} are not positive. + */ + public static Matrix eye(int linedimension, int columndimension) throws IllegalArgumentException { + Matrix matrix = new Matrix(linedimension, columndimension, 0.0); + matrix.setMainDiagonal(1.0); return matrix; } /** - * @return eye square matrix with given dimensions. - * @throws IllegalArgumentException - * if given squareDimension is negative or zero + * Creates a square identity matrix (eye matrix) with the specified dimension. + * + * @param squareDimension The number of lines and columns. + * @return A new square identity {@code Matrix}. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ - public static Matrix eye(int squareDimension) - throws IllegalArgumentException { + public static Matrix eye(int squareDimension) throws IllegalArgumentException { return Matrix.eye(squareDimension, squareDimension); } /** - * @return zero matrix with given dimensions. - * @throws IllegalArgumentException - * - if given linedimension or columndimension are negative or - * zero. + * Creates a matrix of the specified dimensions filled entirely with zeros. + * + * @param linedimension The number of lines (rows). + * @param columndimension The number of columns. + * @return A new zero {@code Matrix}. + * @throws IllegalArgumentException if {@code linedimension} or {@code columndimension} are not positive. */ - public static Matrix zero(int linedimension, int columndimension) - throws IllegalArgumentException { - return new Matrix(linedimension, columndimension, new Double(0)); + public static Matrix zero(int linedimension, int columndimension) throws IllegalArgumentException { + return new Matrix(linedimension, columndimension, 0.0); } /** - * @return square zero matrix with given dimension. - * @throws IllegalArgumentException - * - if given squareDimension is negative or zero. + * Creates a square matrix of the specified dimension filled entirely with zeros. + * + * @param squareDimension The number of lines and columns. + * @return A new square zero {@code Matrix}. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ - public static Matrix zero(int squareDimension) - throws IllegalArgumentException { + public static Matrix zero(int squareDimension) throws IllegalArgumentException { return Matrix.zero(squareDimension, squareDimension); } /** - * @return matrix which all values are only 1. - * @throws IllegalArgumentException - * if given linedimension or columndimension are negative or - * zero. + * Creates a matrix of the specified dimensions filled entirely with ones. + * + * @param linedimension The number of lines (rows). + * @param columndimension The number of columns. + * @return A new {@code Matrix} filled with 1.0s. + * @throws IllegalArgumentException if {@code linedimension} or {@code columndimension} are not positive. */ - public static Matrix ones(int linedimension, int columndimension) - throws IllegalArgumentException { - return new Matrix(linedimension, columndimension, new Double(1)); + public static Matrix ones(int linedimension, int columndimension) throws IllegalArgumentException { + return new Matrix(linedimension, columndimension, 1.0); } /** - * @return square matrix which all values are only 1. - * @throws IllegalArgumentException - * if given squareDimension is negative or zero. + * Creates a square matrix of the specified dimension filled entirely with ones. + * + * @param squareDimension The number of lines and columns. + * @return A new square {@code Matrix} filled with 1.0s. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ - public static Matrix ones(int squareDimension) - throws IllegalArgumentException { + public static Matrix ones(int squareDimension) throws IllegalArgumentException { return Matrix.ones(squareDimension, squareDimension); } /** - * @return square hilbert matrix with given dimension. - * @throws IllegalArgumentException - * if given squareDimensioni is negative or zero. + * Creates a Hilbert matrix of the specified square dimension. + * A Hilbert matrix has elements H(i,j) = 1 / (i + j - 1) (using 1-based indexing for formula, adjusted for 0-based in code). + * + * @param squareDimension The number of lines and columns. + * @return A new Hilbert {@code Matrix}. + * @throws IllegalArgumentException if {@code squareDimension} is not positive. */ - public static Matrix hilbert(int squareDimension) - throws IllegalArgumentException { + public static Matrix hilbert(int squareDimension) throws IllegalArgumentException { Matrix matrix = new Matrix(squareDimension); - for (int i = 0; i < matrix.linedimension; i++) - for (int j = 0; j < matrix.columndimension; j++) - matrix.setValue(i, j, 1.0 / (i + j + 1)); + for (int i = 0; i < matrix.linedimension; i++) { + for (int j = 0; j < matrix.columndimension; j++) { + matrix.setValue(i, j, 1.0 / (i + j + 1)); // 0-based indexing (i+1) + (j+1) - 1 = i+j+1 + } + } return matrix; } /** - * @return subtracted matrix (Mathematic operation). - * @throws NullPointerException - * if given matrix is null. + * Creates a new matrix where each element is {@code value - matrix[i][j]}. + * + * @param value The scalar value from which matrix elements are subtracted. + * @param matrix The matrix whose elements are subtracted. + * @return A new {@code Matrix} instance with the results. + * @throws NullPointerException if {@code matrix} is null or contains null elements. */ - public static Matrix minus(double value, Matrix matrix) - throws NullPointerException { - Matrix summatrix = new Matrix(matrix.linedimension, - matrix.columndimension); + public static Matrix minus(double value, Matrix matrix) throws NullPointerException { + if (matrix == null) throw new NullPointerException("Input matrix cannot be null."); + Matrix resultMatrix = new Matrix(matrix.linedimension, matrix.columndimension); for (int i = 0; i < matrix.linedimension; i++) { for (int j = 0; j < matrix.columndimension; j++) { - summatrix.setValue(i, j, value - matrix.getValue(i, j)); + Double val = matrix.getValue(i,j); + if (val == null) throw new NullPointerException("Cannot perform subtraction with null element in input matrix at [" + i + "," + j + "]"); + resultMatrix.setValue(i, j, value - val); } } - return summatrix; + return resultMatrix; } /** - * @return divided matrix (Mathematic operation). - * @throws NullPointerException - * if given matrix is null. + * Creates a new matrix where each element is {@code value / matrix[i][j]}. + * + * @param value The scalar value that is divided by matrix elements. + * @param matrix The matrix whose elements are the divisors. + * @return A new {@code Matrix} instance with the results. + * @throws NullPointerException if {@code matrix} is null or contains null elements. + * @throws ArithmeticException if any element in {@code matrix} is zero. */ - public static Matrix divide(double value, Matrix matrix) - throws NullPointerException { + public static Matrix divide(double value, Matrix matrix) throws NullPointerException, ArithmeticException { + if (matrix == null) throw new NullPointerException("Input matrix cannot be null."); Matrix ans = new Matrix(matrix.linedimension, matrix.columndimension); for (int i = 0; i < matrix.linedimension; i++) { for (int j = 0; j < matrix.columndimension; j++) { - ans.setValue(i, j, value / matrix.getValue(i, j)); + Double val = matrix.getValue(i,j); + if (val == null) throw new NullPointerException("Cannot perform division with null element in input matrix at [" + i + "," + j + "]"); + if (val == 0) { + throw new ArithmeticException("Division by zero at index [" + i + "," + j + "]"); + } + ans.setValue(i, j, value / val); } } return ans; } /** - * @return matrix with given dimension which data will be filled with random - * numbers. - * @throws IllegalArgumentException - * if dimensions are negative or zero. + * Creates a matrix of specified dimensions filled with random double values between 0.0 (inclusive) and 1.0 (exclusive). + * + * @param linedimension The number of lines (rows). + * @param columndimension The number of columns. + * @return A new {@code Matrix} with random values. + * @throws IllegalArgumentException if dimensions are not positive. */ - public static Matrix random(int linedimension, int columndimension) - throws IllegalArgumentException { + public static Matrix random(int linedimension, int columndimension) throws IllegalArgumentException { Matrix m = new Matrix(linedimension, columndimension); Random random = new Random(); for (int i = 0; i < m.linedimension; i++) { @@ -1084,41 +1108,43 @@ public static Matrix random(int linedimension, int columndimension) } /** - * @return square matrix with given dimension which data will be filled with - * random numbers. - * @throws IllegalArgumentException - * if dimension is negative or zero. + * Creates a square matrix of specified dimension filled with random double values. + * + * @param squareDimension The number of lines and columns. + * @return A new square {@code Matrix} with random values. + * @throws IllegalArgumentException if dimension is not positive. */ - public static Matrix random(int squareDimension) - throws IllegalArgumentException { + public static Matrix random(int squareDimension) throws IllegalArgumentException { return Matrix.random(squareDimension, squareDimension); } /** - * @return matrix with random dimensions (maximum 5) which data also will be - * filled with random numbers. + * Creates a matrix with random dimensions (each up to 5, at least 1) filled with random double values. + * + * @return A new {@code Matrix} with random dimensions and values. */ public static Matrix random() { Random random = new Random(); - int lineDimension = random.nextInt(); - lineDimension = lineDimension > 5 ? 5 : lineDimension; - int columnDimension = random.nextInt(); - columnDimension = columnDimension > 5 ? 5 : columnDimension; - return Matrix.random(lineDimension > 0 ? lineDimension : 1, - columnDimension > 0 ? columnDimension : 1); + int lineDimension = random.nextInt(5) + 1; // Ensure at least 1, max 5 + int columnDimension = random.nextInt(5) + 1; // Ensure at least 1, max 5 + return Matrix.random(lineDimension, columnDimension); } /** - * @return matrix with given dimension which data will be filled with random - * numbers in given range. - * @throws IllegalArgumentException - * if dimensions are negative or zero, or if start parameter is - * more then end parameter. + * Creates a matrix of specified dimensions filled with random double values within the range [start, end). + * + * @param linedimension The number of lines. + * @param columndimension The number of columns. + * @param start The inclusive lower bound of the random range. + * @param end The exclusive upper bound of the random range. + * @return A new {@code Matrix} with random values in the specified range. + * @throws IllegalArgumentException if dimensions are not positive, or if {@code start >= end}. */ - public static Matrix randomIn(int linedimension, int columndimension, - int start, int end) throws IllegalArgumentException { - if (end <= start) + public static Matrix randomIn(int linedimension, int columndimension, int start, int end) + throws IllegalArgumentException { + if (end <= start) { throw new IllegalArgumentException(MatrixExceptionMessages.RANDOM); + } Random r = new Random(); Matrix m = new Matrix(linedimension, columndimension); for (int i = 0; i < m.linedimension; i++) { @@ -1130,238 +1156,232 @@ public static Matrix randomIn(int linedimension, int columndimension, } /** - * @return square matrix with given dimension which data will be filled with - * random numbers in given range. - * @throws IllegalArgumentException - * if dimension is negative or zero, or if start parameter is - * more then end parameter. + * Creates a square matrix of specified dimension filled with random double values within the range [start, end). + * + * @param squareDimension The number of lines and columns. + * @param start The inclusive lower bound. + * @param end The exclusive upper bound. + * @return A new square {@code Matrix} with random values in the range. + * @throws IllegalArgumentException if dimension is not positive, or if {@code start >= end}. */ - public static Matrix randomIn(int squareDimension, int start, int end) - throws IllegalArgumentException { + public static Matrix randomIn(int squareDimension, int start, int end) throws IllegalArgumentException { return Matrix.randomIn(squareDimension, squareDimension, start, end); } /** - * @return matrix with random dimensions (maximum 5) which data also will be - * filled with random numbers in given range. - * @throws IllegalArgumentException - * if start parameter is more then end parameter. + * Creates a matrix with random dimensions (each up to 5, at least 1) filled with random values in [start, end). + * + * @param start The inclusive lower bound. + * @param end The exclusive upper bound. + * @return A new {@code Matrix} with random dimensions and values in the range. + * @throws IllegalArgumentException if {@code start >= end}. */ - public static Matrix randomIn(int start, int end) - throws IllegalArgumentException { + public static Matrix randomIn(int start, int end) throws IllegalArgumentException { Random random = new Random(); - int lineDimension = random.nextInt(); - lineDimension = lineDimension > 5 ? 5 : lineDimension; - int columnDimension = random.nextInt(); - columnDimension = columnDimension > 5 ? 5 : columnDimension; - return Matrix.randomIn(lineDimension > 0 ? lineDimension : 1, - columnDimension > 0 ? columnDimension : 1, start, end); + int lineDimension = random.nextInt(5) + 1; + int columnDimension = random.nextInt(5) + 1; + return Matrix.randomIn(lineDimension, columnDimension, start, end); } /** - * @param matrixType - * : scalar , vector , zero and so on ... - * @param dimensions - * can be null if you want scalar or just one parameter if you - * want square matrix , or tow parameters. - * @return matrix which you want with given dimensions. - * @throws NullPointerException - * if dimensions is null except if you want scalar. - * @throws IllegalArgumentException - * if dimension(s) is(are) negative or zero. + * Creates a matrix of a specific type (e.g., scalar, vector, zero, eye) with specified dimensions. + * + * @param matrixType The type of matrix to create (from {@link MatrixTypes}). + * @param dimensions Variable argument for dimensions: + *
    + *
  • For {@code SCALAR}: no dimension needed.
    • + *
  • For {@code VECTOR}, {@code COLUMN_VECTOR}, {@code HILBERT}, or square {@code MATRIX}, {@code ZERO}, {@code EYE}: one dimension (length/size).
    • + *
  • For rectangular {@code MATRIX}, {@code ZERO}, {@code EYE}: two dimensions (lines, columns).
    • + *
+ * @return The created {@code Matrix}. + * @throws NullPointerException if {@code matrixType} is null, or if {@code dimensions} is null when expected. + * @throws IllegalArgumentException if dimensions are invalid for the given matrix type (e.g., negative, zero, or wrong number of dimensions). */ public static Matrix create(MatrixTypes matrixType, int... dimensions) throws NullPointerException, IllegalArgumentException { + if (matrixType == null) throw new NullPointerException("MatrixType cannot be null."); + // Basic dimension validation + if (dimensions != null) { + for (int dim : dimensions) { + if (dim <= 0) throw new IllegalArgumentException("Dimensions must be positive."); + } + } + switch (matrixType) { - case scalar: - return new Matrix(); - case vector: + case SCALAR: + return new Matrix(); // 1x1 null + case VECTOR: + if (dimensions == null || dimensions.length != 1) throw new IllegalArgumentException("Vector requires one dimension parameter."); return new Matrix(1, dimensions[0]); - case columnVector: + case COLUMN_VECTOR: + if (dimensions == null || dimensions.length != 1) throw new IllegalArgumentException("Column vector requires one dimension parameter."); return new Matrix(dimensions[0], 1); - case hilbert: + case HILBERT: + if (dimensions == null || dimensions.length != 1) throw new IllegalArgumentException("Hilbert matrix requires one dimension (square)."); return Matrix.hilbert(dimensions[0]); - case matrix: { + case MATRIX: + if (dimensions == null || dimensions.length == 0) throw new IllegalArgumentException("Matrix type requires at least one dimension."); if (dimensions.length > 1) { return new Matrix(dimensions[0], dimensions[1]); } - return new Matrix(dimensions[0]); - } - case zero: { + return new Matrix(dimensions[0]); // Square matrix + case ZERO: + if (dimensions == null || dimensions.length == 0) throw new IllegalArgumentException("Zero matrix type requires at least one dimension."); if (dimensions.length > 1) { return Matrix.zero(dimensions[0], dimensions[1]); } - return Matrix.zero(dimensions[0]); - } - case eye: { + return Matrix.zero(dimensions[0]); // Square zero matrix + case EYE: + if (dimensions == null || dimensions.length == 0) throw new IllegalArgumentException("Eye matrix type requires at least one dimension."); if (dimensions.length > 1) { return Matrix.eye(dimensions[0], dimensions[1]); } - return Matrix.eye(dimensions[0]); - } - default: { + return Matrix.eye(dimensions[0]); // Square eye matrix + default: // ONES or any other, treat as ONES as per original logic + if (dimensions == null || dimensions.length == 0) throw new IllegalArgumentException("This matrix type requires at least one dimension."); if (dimensions.length > 1) { return Matrix.ones(dimensions[0], dimensions[1]); } - return Matrix.ones(dimensions[0]); - } + return Matrix.ones(dimensions[0]); // Square ones matrix } } /** - * @param matrixType - * only : scalar , vector , columnVector and matrix. - * @param defaultValue - * matrix will be field with default value. - * @param dimensions - * @return matrix which you want with given dimensions. - * @throws NullPointerException - * if dimensions is null except if you want scalar. - * @throws IllegalArgumentException - * if dimension(s) is(are) negative or zero. + * Creates a matrix of a specific type, filled with a {@code defaultValue}. + * + * @param matrixType The type of matrix (currently supports {@code SCALAR}, {@code VECTOR}, {@code COLUMN_VECTOR}, or defaults to general {@code MATRIX}). + * @param defaultValue The value to fill the matrix elements with. + * @param dimensions Variable argument for dimensions, similar to {@link #create(MatrixTypes, int...)}. + * @return The created {@code Matrix}. + * @throws NullPointerException if {@code matrixType} is null, or if {@code dimensions} is null when expected. + * @throws IllegalArgumentException if dimensions are invalid. */ - public static Matrix create(MatrixTypes matrixType, double defaultValue, - int... dimensions) throws NullPointerException, - IllegalArgumentException { + public static Matrix create(MatrixTypes matrixType, double defaultValue, int... dimensions) + throws NullPointerException, IllegalArgumentException { + if (matrixType == null) throw new NullPointerException("MatrixType cannot be null."); + if (dimensions != null) { + for (int dim : dimensions) { + if (dim <= 0) throw new IllegalArgumentException("Dimensions must be positive."); + } + } + switch (matrixType) { - case scalar: + case SCALAR: return new Matrix(defaultValue); - case vector: + case VECTOR: + if (dimensions == null || dimensions.length != 1) throw new IllegalArgumentException("Vector requires one dimension parameter."); return new Matrix(1, dimensions[0], defaultValue); - case columnVector: + case COLUMN_VECTOR: + if (dimensions == null || dimensions.length != 1) throw new IllegalArgumentException("Column vector requires one dimension parameter."); return new Matrix(dimensions[0], 1, defaultValue); - default: { + default: // MATRIX, HILBERT, ZERO, EYE, ONES (Hilbert, Zero, Eye, Ones are special cases of filled matrices) + if (dimensions == null || dimensions.length == 0) throw new IllegalArgumentException("This matrix type requires at least one dimension."); if (dimensions.length > 1) { return new Matrix(dimensions[0], dimensions[1], defaultValue); } - return new Matrix(dimensions[0], defaultValue); - } + return new Matrix(dimensions[0], defaultValue); // Square matrix } } /** - * @return block diagonal matrix. - *

- * for example: Matrix.diagonal(3, 3, 3, 1) will return: - *

- *

- * 1.0 1.0 0.0
1.0 1.0 1.0
0.0 1.0 1.0 - *

- * @throws IllegalArgumentException - * if given linedimension or columndimension are negative or - * zero or if diagonalnumber is more or equal than 2 * this - * matrix's min dimension or diagonalnumber is even! - */ - public static Matrix diagonal(int linedimension, int columndimension, - int diagonalnumber, double value) throws IllegalArgumentException { - // diagonalnumber ar unda iyos luwi - Matrix m = new Matrix(linedimension, columndimension); - if (diagonalnumber >= (2 * m.getMinDimension()) - || (diagonalnumber % 2 == 0)) - throw new IllegalArgumentException(MatrixExceptionMessages.DIAGONAL); - m.fillWith0(); - m.setDiagonal(0, (Double) value); - for (int i = 0, j = 0; i < (diagonalnumber / 2); i++, j--) { - m.setDiagonal(i + 1, (Double) value); - m.setDiagonal(j - 1, (Double) value); + * Creates a block diagonal matrix where a specified number of diagonals around the main diagonal are filled with {@code value}, + * and other elements are zero. + *

+ * Example: {@code Matrix.diagonal(3, 3, 3, 1.0)} (3x3 matrix, 3 diagonals including main) might produce: + * 

+	 * 1.0  1.0  0.0
+	 * 1.0  1.0  1.0
+	 * 0.0  1.0  1.0
+	 *
+ * + * @param linedimension Number of lines. + * @param columndimension Number of columns. + * @param diagonalnumber Total number of diagonals to be filled (must be odd, e.g., 1 for main only, 3 for main and adjacent). + * @param value The value to fill the specified diagonals with. + * @return A new block diagonal {@code Matrix}. + * @throws IllegalArgumentException if dimensions are not positive, or if {@code diagonalnumber} is invalid + * (e.g., even, too large for matrix dimensions, or not positive). + */ + public static Matrix diagonal(int linedimension, int columndimension, int diagonalnumber, double value) + throws IllegalArgumentException { + Matrix m = new Matrix(linedimension, columndimension); // Initializes with nulls + if (diagonalnumber >= (2 * m.getMinDimension()) || (diagonalnumber % 2 == 0) || diagonalnumber < 1) { + throw new IllegalArgumentException(MatrixExceptionMessages.DIAGONAL + " Number of diagonals must be odd, positive, and within matrix limits."); + } + m.fillWith0(); // Fill with zeros first + m.setDiagonal(0, value); // Main diagonal + for (int i = 1; i <= (diagonalnumber / 2); i++) { + m.setDiagonal(i, value); // Upper diagonals + m.setDiagonal(-i, value); // Lower diagonals } return m; } /** - * @return block diagonal matrix. - *

- * for example: Matrix.diagonal(3, 3, 1) will return: - *

- *

- * 1.0 1.0 0.0
1.0 1.0 1.0
0.0 1.0 1.0 - *

- * @throws IllegalArgumentException - * if given squareDimension is negative or zero or if - * diagonalnumber is more or equal than 2 * this matrix's min - * dimension or diagonalnumber is even! + * Creates a square block diagonal matrix. + * + * @param squareDimension The number of lines and columns. + * @param diagonalnumber Total number of diagonals to fill (must be odd). + * @param value The value for the diagonals. + * @return A new square block diagonal {@code Matrix}. + * @throws IllegalArgumentException if arguments are invalid as per {@link #diagonal(int, int, int, double)}. */ - public static Matrix diagonal(int squareDimension, int diagonalnumber, - double value) throws IllegalArgumentException { - return Matrix.diagonal(squareDimension, squareDimension, - diagonalnumber, (Double) value); + public static Matrix diagonal(int squareDimension, int diagonalnumber, double value) + throws IllegalArgumentException { + return Matrix.diagonal(squareDimension, squareDimension, diagonalnumber, value); } /** - * @return block diagonal matrix. - *

- * for example: Matrix.diagonal2(3, 3, 3, 1) will return: - *

- *

- * 0.0 1.0 1.0
1.0 1.0 1.0
1.0 1.0 0.0 - *

- * @throws IllegalArgumentException - * if given linedimension or columndimension are negative or - * zero or if diagonalnumber is more or equal than 2 * this - * matrix's min dimension or diagonalnumber is even! - */ - public static Matrix diagonal2(int linedimension, int columndimension, - int diagonalnumber, double value) throws IllegalArgumentException { + * Creates a block anti-diagonal matrix (diagonals perpendicular to the main anti-diagonal). + *

+ * Example: {@code Matrix.diagonal2(3, 3, 3, 1.0)} might produce: + * 

+	 * 0.0  1.0  1.0
+	 * 1.0  1.0  1.0
+	 * 1.0  1.0  0.0
+	 *
+ * + * @param linedimension Number of lines. + * @param columndimension Number of columns. + * @param diagonalnumber Total number of anti-diagonals to fill (must be odd and positive). + * @param value The value for these anti-diagonals. + * @return A new block anti-diagonal {@code Matrix}. + * @throws IllegalArgumentException if arguments are invalid (e.g. dimensions not positive, diagonalnumber even/too large/not positive). + */ + public static Matrix diagonal2(int linedimension, int columndimension, int diagonalnumber, double value) + throws IllegalArgumentException { Matrix m = new Matrix(linedimension, columndimension); - if (diagonalnumber >= (2 * m.getMinDimension()) - || (diagonalnumber % 2 == 0)) - throw new IllegalArgumentException(MatrixExceptionMessages.DIAGONAL); + if (diagonalnumber >= (2 * m.getMinDimension()) || (diagonalnumber % 2 == 0) || diagonalnumber < 1) { + throw new IllegalArgumentException(MatrixExceptionMessages.DIAGONAL + " Number of diagonals must be odd, positive, and within matrix limits."); + } m.fillWith0(); - m.setDiagonal2(0, (Double) value); - for (int i = 0, j = 0; i < (diagonalnumber / 2); i++, j--) { - m.setDiagonal2(i + 1, (Double) value); - m.setDiagonal2(j - 1, (Double) value); + m.setDiagonal2(0, value); // Main anti-diagonal + for (int i = 1; i <= (diagonalnumber / 2); i++) { + m.setDiagonal2(i, value); // Anti-diagonals "above" (towards top-right) + m.setDiagonal2(-i, value); // Anti-diagonals "below" (towards bottom-left) } return m; } /** - * @return block diagonal matrix. - *

- * for example: Matrix.diagonal2(3, 3, 1) will return: - *

- *

- * 0.0 1.0 1.0
1.0 1.0 1.0
1.0 1.0 0.0 - *

- * @throws IllegalArgumentException - * if given squareDimension is negative or zero or if - * diagonalnumber is more or equal than 2 * this matrix's min - * dimension or diagonalnumber is even! + * Creates a square block anti-diagonal matrix. + * + * @param squareDimension The number of lines and columns. + * @param diagonalnumber Total number of anti-diagonals to fill (must be odd and positive). + * @param value The value for these anti-diagonals. + * @return A new square block anti-diagonal {@code Matrix}. + * @throws IllegalArgumentException if arguments are invalid. */ - public static Matrix diagonal2(int squareDimension, int diagonalnumber, - double value) throws IllegalArgumentException { - return Matrix.diagonal2(squareDimension, squareDimension, - diagonalnumber, (Double) value); + public static Matrix diagonal2(int squareDimension, int diagonalnumber, double value) + throws IllegalArgumentException { + return Matrix.diagonal2(squareDimension, squareDimension, diagonalnumber, value); } + /** + * Main method for demonstration or testing of Matrix functionalities. + * @param argss Command line arguments (not used by this demonstration). + */ public static void main(String [] argss) { - + // Example usage of the Matrix class Matrix matrix = new Matrix(3); - matrix.setValue(0, 0, 3.0); - matrix.setValue(0, 1, 2.0); - matrix.setValue(0, 2, 1.0); - matrix.setValue(1, 0, 3.0); - matrix.setValue(1, 1, 4.0); - matrix.setValue(1, 2, 5.0); - matrix.setValue(2, 0, 0.0); - matrix.setValue(2, 1, 2.0); - matrix.setValue(2, 2, 4.0); - - System.out.println(matrix); - - Matrix answers = new Matrix(3, 1); - answers.setValue(0, 0, 2.6); - answers.setValue(1, 0, 4.0); - answers.setValue(2, 0, 1.4); - - System.out.println(answers); - - Matrix solveLinearSystem = matrix.solveLinearSystem(answers); - - System.out.println(solveLinearSystem); - - System.out.println("test"); - - } - -} \ No newline at end of file + matrix.setValue(0, 0, 3.0); \ No newline at end of file diff --git a/src/main/kotlin/com/nodrex/datamatrix/MatrixTypes.java b/src/main/kotlin/com/nodrex/datamatrix/MatrixTypes.java index e8a4378..67ce1b4 100644 --- a/src/main/kotlin/com/nodrex/datamatrix/MatrixTypes.java +++ b/src/main/kotlin/com/nodrex/datamatrix/MatrixTypes.java @@ -3,18 +3,35 @@ import java.io.Serializable; /** + * Represents predefined types or categories of matrices. + * This enum is primarily used to specify the desired matrix structure or content + * in factory methods, such as those found in the {@link Matrix} class. *

- * This enum contains type of matrices + * Implements {@link java.io.Serializable} interface. *

- *

- * Implements Serializable interfaces. - *

- * + * * @author NODREX * @version 1.0 * @since 2013 - * + * @see Matrix#create(MatrixTypes, int...) + * @see Matrix#create(MatrixTypes, double, int...) + * @see java.io.Serializable */ public enum MatrixTypes implements Serializable { - scalar, vector, columnVector, matrix, zero, eye, ones, hilbert + /** Represents a scalar matrix, typically a 1x1 matrix. */ + scalar, + /** Represents a row vector, a matrix with 1 row and N columns. */ + vector, + /** Represents a column vector, a matrix with M rows and 1 column. */ + columnVector, + /** Represents a general matrix with M rows and N columns. */ + matrix, + /** Represents a zero matrix, where all elements are 0. */ + zero, + /** Represents an identity matrix (eye matrix), with 1s on the main diagonal and 0s elsewhere. Must be square. */ + eye, + /** Represents a matrix where all elements are 1. */ + ones, + /** Represents a Hilbert matrix, a square matrix with elements H(i,j) = 1/(i+j-1). */ + hilbert }; \ No newline at end of file