feat: Add pretty display functionality and negative index support

[mitsuki31]

Overview

This pull request introduces enhancements to the Matrix class by adding functionality for pretty displaying matrix data and supporting negative indices in matrix display methods. These changes are aimed at improving the readability and usability of matrix and array representations, particularly for debugging and data analysis.

Details

Pretty Display Functionality

New Methods Added

• prettyDisplay(): Displays the entire matrix with optional column and row indices.

  public void prettyDisplay();

• prettyDisplay(boolean): Allows toggling the display of row and column indices.

  public void prettyDisplay(boolean showIndices);

• prettyDisplay(int): Displays a specific row of the matrix with optional row and column indices.

  public void prettyDisplay(int index);

• prettyDisplay(int, boolean): Provides the option to show row and column indices for a specific row.

  public void prettyDisplay(int index, boolean showIndices);

• prettyDisplay(double[][]): Static method to pretty print a 2D array with optional index display.

  public static void prettyDisplay(double[][] arr);

• prettyDisplay(double[][], boolean): Static method to pretty print a 2D array with index display option.

  public static void prettyDisplay(double[][] arr, boolean showIndices);

• prettyDisplay(double[][], int): Static method to pretty print a specific row of a 2D array with optional index display.

  public static void prettyDisplay(double[][] arr, int index);

• prettyDisplay(double[][], int, boolean): Static method to pretty print a specific row of a 2D array with customizable index display.

  public static void prettyDisplay(double[][] arr, int index, boolean showIndices);

Features and Enhancements

• Formats the matrix or array into a neatly aligned grid.
• Calculates the maximum width for each column to ensure proper alignment.
• Provides options to include row and column indices for better data interpretation.
• Handles null matrices and arrays gracefully, displaying <null_matrix> or <null_2darray> as appropriate.
• Implements support for negative row indices, allowing indices relative to the end of the matrix or array.
• Raises InvalidIndexException for out-of-bounds indices, with clear error messages.

Support for Negative Indices

• Enhancements:
  • Modified the display(int) method to support negative indices. Negative indices are interpreted as counting from the end of the matrix (e.g., -1 for the last row, -2 for the second-to-last row).
  • Adjusted the index calculation to convert negative indices into valid positive indices.
  • Added checks to ensure that the adjusted index is within the valid range of matrix rows.
  • Improved error handling by raising an InvalidIndexException with a descriptive message if the index is out of bounds.
  • Updated the static display(double[][], int) method to support negative indices similarly.

Impact

Functionality

• The new prettyDisplay() methods provide enhanced visualization of matrix data, making it easier to read and analyze.
• Support for negative indices improves flexibility in accessing matrix rows and aligns with common conventions.

Backward Compatibility

• These changes are backward compatible. Existing functionality remains unaffected while new features are added.

Examples

Example Code

Here's how you might use the new prettyDisplay() and updated display() methods in practice:

import com.mitsuki.jmatrix.Matrix;

public class MatrixExample {
    public static void main(String[] args) {
        // Create a sample matrix
        double[][] data = {
            {1.234, 56.78, 1234.5},
            {7.89, 0.12, 345.67},
            {123.45, 678.9, 10.11}
        };
        
        // Initialize the matrix
        Matrix matrix = new Matrix(data);

        // Pretty display the entire matrix with indices
        System.out.println("Pretty display with indices:");
        matrix.prettyDisplay(true);
        
        // Pretty display the entire matrix without indices
        System.out.println("\nPretty display without indices:");
        matrix.prettyDisplay(false);
        
        // Pretty display a specific row (index 1) with indices
        System.out.println("\nPretty display of row 2 with indices:");
        matrix.prettyDisplay(1, true);
        
        // Pretty display a specific row (index 1) without indices
        System.out.println("\nPretty display of row 2 without indices:");
        matrix.prettyDisplay(1, false);

        // Pretty display the entire array (static method) with indices
        System.out.println("\nStatic pretty display of the entire array with indices:");
        Matrix.prettyDisplay(data, true);
        
        // Pretty display a specific row of the array (index 0) with indices
        System.out.println("\nStatic pretty display of row 1 with indices:");
        Matrix.prettyDisplay(data, 0, true);
        
        // Using negative indices
        System.out.println("\nPretty display of the last row using negative index:");
        matrix.prettyDisplay(-1, true);

        // Using invalid index (e.g., index out of bounds)
        System.out.println("\nTrying invalid index (4):");
        try {
            matrix.prettyDisplay(4, true);
        } catch (InvalidIndexException e) {
            System.out.println(e.getMessage());
        }

        // Display a specific row using the display method with negative index
        System.out.println("\nDisplay the second-to-last row using negative index:");
        matrix.display(-2);
    }
}

Example Output

Given the example matrix data, the output would look like this:

Pretty display with indices:
     [1]     [2]    [3]   
[1]  1.234   56.78  1234.5  
[2]  7.89    0.12   345.67  
[3]  123.45  678.9  10.11   

Pretty display without indices:
1.234   56.78  1234.5  
7.89    0.12   345.67  
123.45  678.9  10.11  

Pretty display of row 2 with indices:
     [1]   [2]   [3]   
[2]  7.89  0.12  345.67  

Pretty display of row 2 without indices:
7.89  0.12  345.67  

Static pretty display of the entire array with indices:
     [1]     [2]    [3]   
[1]  1.234   56.78  1234.5  
[2]  7.89    0.12   345.67  
[3]  123.45  678.9  10.11   

Static pretty display of row 1 with indices:
     [1]    [2]    [3]   
[1]  1.234  56.78  1234.5  

Pretty display of the last row using negative index:
     [1]     [2]    [3]   
[3]  123.45  678.9  10.11  

Trying invalid index (4):
Given row index is out of bounds: 4

Display the second-to-last row using negative index:
[2.89, 0.12, 345.67]

Notes

• The output shows the matrix with properly aligned columns and optional row and column indices.
• For negative index examples, the matrix displays the rows counted from the end.
• The error handling for invalid indices demonstrates appropriate exception messages.