From b094af549c68669075731c4af275b8f33b4ebebe Mon Sep 17 00:00:00 2001 From: Ryuu Mitsuki Date: Sun, 15 Sep 2024 17:29:32 +0700 Subject: [PATCH] docs: Add the API docs for `prettyDisplay` methods This API documentation addition includes detailed description and parameters, example usages along with the expected output, and an API note for alias methods. This change also suppress warnings during compiling sources or generating Javadoc with linter enabled. --- src/main/java/com/mitsuki/jmatrix/Matrix.java | 397 ++++++++++++++++++ 1 file changed, 397 insertions(+) diff --git a/src/main/java/com/mitsuki/jmatrix/Matrix.java b/src/main/java/com/mitsuki/jmatrix/Matrix.java index 4bd470e..5bbebdd 100644 --- a/src/main/java/com/mitsuki/jmatrix/Matrix.java +++ b/src/main/java/com/mitsuki/jmatrix/Matrix.java @@ -5573,10 +5573,107 @@ final public static void display(double[ ][ ] arr, int index) { } + /*--------------------------- + :: Matrix Pretty Display + ---------------------------*/ + + /** + * Displays this matrix in a formatted and human-readable manner. + * + *

The method prints all rows and columns of the matrix along with the column and row indices. + * If the matrix has {@code null} entries, the method prints {@code } instead. + * + *

The output includes the following formatting features: + *

+ * + *

Example Code:

+ * 
 
+     *   Matrix m = new Matrix(new double[][] {
+     *       { 1, 2, 3 },
+     *       { 4, 5, 6 },
+     *       { 7, 8, 9 }
+     *   });
+     *   m.prettyDisplay();
+     *
+ * + *

Example Output:

+ * 
 
+     *        [1]  [2]  [3]
+     *   [1]  1.0  2.0  3.0
+     *   [2]  4.0  5.0  6.0
+     *   [3]  7.0  8.0  9.0
+     *
+ * + *

Special cases handled: + *

+ * + * @apiNote + * This method is an alias for {@link prettyDisplay(boolean)} method with {@code showIndices} parameter + * set to {@code true} by default. + * + * @since 1.5.0 + * @see #prettyDisplay(boolean) + */ final public void prettyDisplay() { this.prettyDisplay(true); } + /** + * Displays this matrix in a formatted and human-readable manner. + * + *

The method prints all rows and columns of the matrix with an option to show column and row indices. + * If the matrix has {@code null} entries, the method prints {@code } instead. + * + *

The output includes the following formatting features: + *

+ * + *

Example Code:

+ * 
 
+     *   Matrix m = new Matrix(new double[][] {
+     *       { 1, 2, 3 },
+     *       { 4, 5, 6 },
+     *       { 7, 8, 9 }
+     *   });
+     *   m.prettyDisplay(true);
+     *
+ * + *

Example Output:

+ * + *

With {@code showIndices} set to {@code true} (default): + * 

 
+     *        [1]  [2]  [3]
+     *   [1]  1.0  2.0  3.0
+     *   [2]  4.0  5.0  6.0
+     *   [3]  7.0  8.0  9.0
+     *
+ * + *

With {@code showIndices} set to {@code false}: + * 

 
+     *   1.0  2.0  3.0
+     *   4.0  5.0  6.0
+     *   7.0  8.0  9.0
+     *
+ * + *

Special cases handled: + *

+ * + * @param showIndices Whether to display row and column indices along with the array elements. + * + * @since 1.5.0 + * @see #prettyDisplay() + */ final public void prettyDisplay(boolean showIndices) { // If the matrix is null, print if (this.ENTRIES == null) { @@ -5624,10 +5721,110 @@ final public void prettyDisplay(boolean showIndices) { System.out.println(sb.toString()); } + /** + * Displays a specified row of this matrix in a formatted and human-readable manner. + * + *

The method prints the elements of the matrix along with the column and row indices. + * If the given row index is negative, the method supports wrapping by converting it to a valid + * positive index. If the {@code index} is out of bounds, an {@link InvalidIndexException} is thrown. + * + *

The output includes the following formatting features: + *

+ * + *

Example Code:

+ * 
 
+     *   Matrix m = new Matrix(new double[][] {
+     *       { 3, 4, 5 },
+     *       { 1, 2, 3 },
+     *       { 9, 7, 0 }
+     *   });
+     *   m.prettyDisplay(0);
+     *
+ * + *

Example Output:

+ * 
 
+     *        [1]  [2]  [3]
+     *   [1]  3.0  4.0  5.0
+     *
+ * + *

Special cases handled: + *

+ * + * @apiNote + * This method is an alias for {@link #prettyDisplay(int, boolean)} method with {@code showIndices} + * parameter set to {@code true} by default. + * + * @param index The row index to display. Negative indices are supported and will be converted to + * positive by wrapping. + * + * @throws InvalidIndexException If the given row index is out of bounds. + * + * @since 1.5.0 + * @see #prettyDisplay(int, boolean) + */ final public void prettyDisplay(int index) { prettyDisplay(index, true); } + /** + * Displays a specified row of this matrix in a formatted and human-readable manner. + * + *

The method prints the elements of the matrix with an option to show column and row indices. + * If the given row index is negative, the method supports wrapping by converting it to a valid + * positive index. If the {@code index} is out of bounds, an {@link InvalidIndexException} is thrown. + * + *

The output includes the following formatting features: + *

+ * + *

Example Code:

+ * 
 
+     *   Matrix m = new Matrix(new double[][] {
+     *       { 3, 4, 5 },
+     *       { 1, 2, 3 },
+     *       { 9, 7, 0 }
+     *   });
+     *   m.prettyDisplay(0, true);
+     *
+ * + *

Example Output:

+ * + *

With {@code showIndices} set to {@code true}: + * 

 
+     *        [1]  [2]  [3]
+     *   [1]  3.0  4.0  5.0
+     *
+ * + *

With {@code showIndices} set to {@code false}: + * 

 
+     *   3.0  4.0  5.0
+     *
+ * + *

Special cases handled: + *

+ * + * @param index The row index to display. Negative indices are supported and will be converted to + * positive by wrapping. + * @param showIndices Whether to display row and column indices along with the matrix elements. + * + * @throws InvalidIndexException If the given row index is out of bounds. + * + * @since 1.5.0 + * @see #prettyDisplay(int) + */ final public void prettyDisplay(int index, boolean showIndices) { // If the matrix is null, print if (this.ENTRIES == null) { @@ -5681,10 +5878,106 @@ final public void prettyDisplay(int index, boolean showIndices) { System.out.println(sb.toString()); } + /** + * Displays the two-dimensional array in a formatted and human-readable manner. + * + *

The method prints all rows and columns of the array along with the column and row indices. + * If the array is null or empty, the method prints {@code } and exits. + * + *

The output includes the following formatting features: + *

    + *
  • Each element is padded for alignment based on the largest element's width in its column.
    • + *
  • Column headers are displayed.
    • + *
  • Row numbers are displayed to the left of each row.
    • + *
+ * + *

Example Code:

+ * 
 
+     *   Matrix.prettyDisplay(new double[][] {
+     *       { 1, 2, 3 },
+     *       { 4, 5, 6 },
+     *       { 7, 8, 9 }
+     *   });
+     *
+ * + *

Example Output:

+ * 
 
+     *        [1]  [2]  [3]
+     *   [1]  1.0  2.0  3.0
+     *   [2]  4.0  5.0  6.0
+     *   [3]  7.0  8.0  9.0
+     *
+ * + *

Special cases handled: + *

    + *
  • If the array is null or empty, the method prints {@code }.
    • + *
+ * + * @apiNote + * This method is an alias for {@link prettyDisplay(double[][], boolean)} method with + * {@code showIndices} parameter set to {@code true} by default. + * + * @param arr The two-dimensional {@code double} array to display. + * If the array is null or empty, {@code } will be printed. + * + * @since 1.5.0 + * @see #prettyDisplay(double[][], boolean) + */ final public static void prettyDisplay(double[ ][ ] arr) { Matrix.prettyDisplay(arr, true); } + /** + * Displays the two-dimensional array in a formatted and human-readable manner. + * + *

The method prints all rows and columns of the array with an option to show column and row indices. + * If the array is null or empty, the method prints {@code } and exits. + * + *

The output includes the following formatting features: + *

    + *
  • Each element is padded for alignment based on the largest element's width in its column.
    • + *
  • Column headers are displayed if the {@code showIndices} flag is {@code true}.
    • + *
  • If {@code showIndices} is {@code true}, row numbers are displayed to the left of each row.
    • + *
+ * + *

Example Code:

+ * 
 
+     *   Matrix.prettyDisplay(new double[][] {
+     *       { 1, 2, 3 },
+     *       { 4, 5, 6 },
+     *       { 7, 8, 9 }
+     *   }, true);
+     *
+ * + *

Example Output:

+ * + *

With {@code showIndices} set to {@code true}: + * 

 
+     *        [1]  [2]  [3]
+     *   [1]  1.0  2.0  3.0
+     *   [2]  4.0  5.0  6.0
+     *   [3]  7.0  8.0  9.0
+     *
+ * + *

With {@code showIndices} set to {@code false}: + * 

 
+     *   1.0  2.0  3.0
+     *   4.0  5.0  6.0
+     *   7.0  8.0  9.0
+     *
+ * + *

Special cases handled: + *

    + *
  • If the array is null or empty, the method prints {@code }.
    • + *
+ * + * @param arr The two-dimensional {@code double} array to display. + * If the array is null or empty, {@code } will be printed. + * @param showIndices Whether to display row and column indices along with the array elements. + * + * @since 1.5.0 + * @see #prettyDisplay(double[][]) + */ final public static void prettyDisplay(double[ ][ ] arr, boolean showIndices) { // If the two-dimensional array is null, print if (arr == null || arr.length == 0) { @@ -5731,10 +6024,112 @@ final public static void prettyDisplay(double[ ][ ] arr, boolean showIndices) { System.out.println(sb.toString()); } + /** + * Displays a specified row of a two-dimensional array in a formatted and human-readable manner. + * + *

The method prints the elements of the array along with the column and row indices. + * If the given row index is negative, the method supports wrapping by converting it to a valid + * positive index. If the {@code index} is out of bounds, an {@link InvalidIndexException} is thrown. + * + *

The output includes the following formatting features: + *

    + *
  • Each element is padded for alignment based on the largest element's width in its column.
    • + *
  • Column headers are displayed.
    • + *
  • Row numbers are displayed to the left of each row.
    • + *
+ * + *

Example Code:

+ * 
 
+     *   Matrix.prettyDisplay(new double[][] {
+     *       { 3, 4, 5 },
+     *       { 1, 2, 3 },
+     *       { 9, 7, 0 }
+     *   }, 2);
+     *
+ * + *

Example Output:

+ * 
 
+     *        [1]  [2]  [3]
+     *   [3]  9.0  7.0  0.0
+     *
+ * + *

Special cases handled: + *

    + *
  • If the array is null or empty, the method prints {@code }.
    • + *
  • Negative indices are adjusted by adding the array length.
    • + *
+ * + * @apiNote + * This method is an alias for {@link prettyDisplay(double[][], int, boolean)} method with + * {@code showIndices} parameter set to {@code true} by default. + * + * @param arr The two-dimensional {@code double} array to display. + * If the array is null or empty, {@code } will be printed. + * @param index The row index to display. Negative indices are supported and will be converted to + * positive by wrapping. + * + * @throws InvalidIndexException If the given row index is out of bounds. + * + * @since 1.5.0 + * @see #prettyDisplay(double[][], int, boolean) + */ final public static void prettyDisplay(double[ ][ ] arr, int index) { Matrix.prettyDisplay(arr, index, true); } + /** + * Displays a specified row of a two-dimensional array in a formatted and human-readable manner. + * + *

The method prints the elements of the array with an option to show column and row indices. + * If the given row index is negative, the method supports wrapping by converting it to a valid + * positive index. If the {@code index} is out of bounds, an {@link InvalidIndexException} is thrown. + * + *

The output includes the following formatting features: + *

    + *
  • Each element is padded for alignment based on the largest element's width in its column.
    • + *
  • Column headers are displayed if the {@code showIndices} flag is {@code true}.
    • + *
  • If {@code showIndices} is {@code true}, row numbers are displayed to the left of each row.
    • + *
+ * + *

Example Code:

+ * 
 
+     *   Matrix.prettyDisplay(new double[][] {
+     *       { 3, 4, 5 },
+     *       { 1, 2, 3 },
+     *       { 9, 7, 0 }
+     *   }, 0, true);
+     *
+ * + *

Example Output:

+ * + *

With {@code showIndices} set to {@code true} (default): + * 

 
+     *        [1]  [2]  [3]
+     *   [1]  3.0  4.0  5.0
+     *
+ * + *

With {@code showIndices} set to {@code false}: + * 

 
+     *   3.0  4.0  5.0
+     *
+ * + *

Special cases handled: + *

    + *
  • If the array is null or empty, the method prints {@code }.
    • + *
  • Negative indices are adjusted by adding the array length.
    • + *
+ * + * @param arr The two-dimensional {@code double} array to display. + * If the array is null or empty, {@code } will be printed. + * @param index The row index to display. Negative indices are supported and will be converted to + * positive by wrapping. + * @param showIndices Whether to display row and column indices along with the array elements. + * + * @throws InvalidIndexException If the given row index is out of bounds. + * + * @since 1.5.0 + * @see #prettyDisplay(double[][], int) + */ final public static void prettyDisplay(double[ ][ ] arr, int index, boolean showIndices) { // If the two-dimensional array is null, print if (arr == null || arr.length == 0) { @@ -5800,6 +6195,8 @@ final public static void prettyDisplay(double[ ][ ] arr, int index, boolean show * Returns a {@code String} representation of this matrix. * *

Use the {@link #display()} method to display this matrix in simply way. + * Or, consider to use {@link #prettyDisplay()} for more better human-readability and it is + * designed to display the grid-aligned matrix. * * @return the {@code String} representation of this matrix in Python-style array notation. *