Package com.github.miachm.sods

Class Range

java.lang.Object
com.github.miachm.sods.Range
public class Range extends Object
A range represents a subset of a Sheet. You use ranges for write/read content in a Sheet. It references a specific subset of the Sheet.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Clear all the content/styles of the cells in this range
    void
    copyTo(Range dest)
    Copy the content of this range to another, this include values and formatting
    OfficeAnnotation
    getAnnotation()
    Returns the annotation/comment of the first Cell in this range.
    OfficeAnnotation[][]
    getAnnotations()
    Returns the rectangular grid of the annotations for this range.
    Range
    getCell(int row, int column)
    Get a specific cell of this Range using relative coords for example, (0,0) would be the first cell of this range
    int
    getColumn()
    Get the starting column index of this range.
    String
    getFormula()
    Get the formula String of the first cell of the range
    String[][]
    getFormulas()
    Returns the formulas (A1 notation) for the cells in the range.
    int
    getLastColumn()
    Returns the end column position.
    int
    getLastRow()
    Returns the end row position.
    Range[]
    getMergedCells()
    Returns an array of Range objects representing merged cells that either are fully within the current range, or contain at least one cell in the current range.
    int
    getNumColumns()
    Number of columns which contains this range
    int
    getNumRows()
    Number of rows which contains this range
    int
    getNumValues()
    Return the number of cells which contains this range
    int
    getRow()
    Get the starting row index of this range.
    Sheet
    getSheet()
    Returns the sheet where this range is contained
    Style
    getStyle()
    Returns the formating style of the top-left cell in the range.
    Style[][]
    getStyles()
    Returns the rectangular grid of formating styles for this range.
    Object
    getValue()
    Returns the value of the top-left cell in the range.
    Object[][]
    getValues()
    Returns the rectangular grid of values for this range.
    boolean
    isPartOfMerge()
    Determines if the range is part of an existing cell's block
    void
    merge()
    Merges the cells in the range together into a single block.
    void
    setAnnotation(OfficeAnnotation annotation)
    Set an annotation for all the cells in this range.
    void
    setAnnotations(OfficeAnnotation... annotations)
    Set a set of anotations to the range.
    void
    setAnnotations(OfficeAnnotation[][] annotations)
    Set a set of annotations to the range.
    void
    setBackgroundColor(Color color)
    Set a cell background color to the entire range
    void
    setBackgroundColors(Color... color)
    Set a set of cell background colors to the range.
    void
    setBackgroundColors(Color[][] color)
    Set a set of cell background colors formatting to the range.
    void
    setFontBold(boolean bold)
    Set a font bold style to the entire range
    void
    setFontBolds(boolean... bold)
    Set a set of font bolds styles to the range.
    void
    setFontBolds(boolean[][] bold)
    Set a set of font bolds formatting to the range.
    void
    setFontColor(Color color)
    Set a font color to the entire range
    void
    setFontColors(Color... color)
    Set a set of font colors styles to the range.
    void
    setFontColors(Color[][] color)
    Set a set of font colors formatting to the range.
    void
    setFontItalic(boolean italic)
    Set a font italic style to the entire range
    void
    setFontItalics(boolean... italic)
    Set a set of font italics styles to the range.
    void
    setFontItalics(boolean[][] italic)
    Set a set of font italics formatting to the range.
    void
    setFontSize(int fontSize)
    Set the font size to the entire range
    void
    setFontSizes(int... fontSizes)
    Set a set of font sizes to the range.
    void
    setFontSizes(int[][] fontSizes)
    Set a set of font sizes to the range.
    void
    setFontUnderline(boolean underline)
    Set a font underline style to the entire range
    void
    setFontUnderlines(boolean... underline)
    Set a set of font underlines styles to the range.
    void
    setFontUnderlines(boolean[][] underline)
    Set a set of font underlines formatting to the range.
    void
    setFormula(String formula)
    Set a formula for every cell in the range.
    void
    setFormulas(String... formula)
    Set a set of formulas to the range.
    void
    setFormulas(String[][] formula)
    Set a set of formulas to the range.
    void
    setStyle(Style style)
    Set a format style for all the cells of the range
    void
    setStyles(Style... style)
    Set a set of format styles to the range.
    void
    setStyles(Style[][] style)
    Set a set of styles to the range.
    void
    setValue(Object o)
    Set a value to the entire range
    void
    setValues(Object... o)
    Set a set of values to the range.
    void
    setValues(Object[][] o)
    Set a set of values to the range.
    void
    split()
    Breaks apart any combined cells on the range.
    String
    toString()
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • clear

      public void clear()
      Clear all the content/styles of the cells in this range

    • copyTo

      public void copyTo(Range dest)
      Copy the content of this range to another, this include values and formatting
      Parameters:
      dest - The destination range, it must have the same size of the orig range.
      Throws:
      IllegalArgumentException - if the range hasn't the same size

    • getCell

      public Range getCell(int row, int column)
      Get a specific cell of this Range using relative coords for example, (0,0) would be the first cell of this range
      Parameters:
      row - The X Cord
      column - The Y Cord
      Returns:
      A range which contains that specific cell
      Throws:
      IndexOutOfBoundsException - if the coordinates are invalid

    • getColumn

      public int getColumn()
      Get the starting column index of this range. For example a value of 2, indicates what this range starts at the third column of the sheet.
      Returns:
      An integer with the column index

    • getFormula

      public String getFormula()
      Get the formula String of the first cell of the range
      Returns:
      the formula text representation, it can be null

    • getFormulas

      public String[][] getFormulas()
      Returns the formulas (A1 notation) for the cells in the range. Entries in the 2D array are null for cells with no formula.
      Returns:
      The formulas of the range

    • getLastColumn

      public int getLastColumn()
      Returns the end column position.
      Returns:
      The coordinate of the end column position in the sheet.

    • getLastRow

      public int getLastRow()
      Returns the end row position.
      Returns:
      The coordinate of the end row position in the sheet.

    • getMergedCells

      public Range[] getMergedCells()
      Returns an array of Range objects representing merged cells that either are fully within the current range, or contain at least one cell in the current range.
      Returns:
      An array with all the Ranges[]

    • getNumColumns

      public int getNumColumns()
      Number of columns which contains this range
      Returns:
      the number of columns

    • getNumRows

      public int getNumRows()
      Number of rows which contains this range
      Returns:
      the number of columns

    • getRow

      public int getRow()
      Get the starting row index of this range. For example a value of 2, indicates what this range starts at the third row of the sheet.
      Returns:
      An integer with the row index

    • getSheet

      public Sheet getSheet()
      Returns the sheet where this range is contained
      Returns:
      A not-null sheet object

    • getValue

      public Object getValue()
      Returns the value of the top-left cell in the range. The values could be String, Float, Integer, OfficeCurrency, OfficePercentage or a LocalDate Empty cells returns a null object
      Returns:
      the value in this cell
      See Also:

    • getValues

      public Object[][] getValues()
      Returns the rectangular grid of values for this range. The values could be String, Float, Integer, OfficeCurrency, OfficePercentage or a LocalDate Empty cells returns a null object
      Returns:
      A two-dimensional array of values.
      See Also:

    • getStyle

      public Style getStyle()
      Returns the formating style of the top-left cell in the range. It's safe to manipulate the Style object since is a copy of the original one
      Returns:
      the style in this cell. It can not be null.

    • getStyles

      public Style[][] getStyles()
      Returns the rectangular grid of formating styles for this range. It's safe to manipulate the Styles objects since they are copies of the original ones
      Returns:
      A two-dimensional array of values. It can not be null

    • getAnnotation

      public OfficeAnnotation getAnnotation()
      Returns the annotation/comment of the first Cell in this range.
      Returns:
      An object which contains the comment, or null if it doesn't exist
      See Also:

    • getAnnotations

      public OfficeAnnotation[][] getAnnotations()
      Returns the rectangular grid of the annotations for this range. It will be null if the cell doesn't have comments
      Returns:
      A two-dimensional array of values. It can not be null
      See Also:

    • getNumValues

      public int getNumValues()
      Return the number of cells which contains this range
      Returns:
      The number of cells in this range

    • setValue

      public void setValue(Object o)
      Set a value to the entire range
      Parameters:
      o - The value object, it can be Integer, Float, Date, OfficeCurrency, OfficePercentage. Differents values types will be considered as Strings and toString() will be invoked
      See Also:

    • setValues

      public void setValues(Object... o)
      Set a set of values to the range. The values must have the same size of the entire range itself 
           Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setValues(1, 2, 3, 4); // Set the values for the range
      Parameters:
      o - The values array, it must the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setValues

      public void setValues(Object[][] o)
      Set a set of values to the range. The values array must have the same size of the entire range itself
      Parameters:
      o - The values 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontBold

      public void setFontBold(boolean bold)
      Set a font bold style to the entire range
      Parameters:
      bold - Boolean which indicates if the font has bold style or not

    • setFontBolds

      public void setFontBolds(boolean... bold)
      Set a set of font bolds styles to the range. The array must have the same size of the entire range itself 
           Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setFontBolds(true, false, true, false); // Set the font bold formatting for the range
      Parameters:
      bold - The font bolds array, it must the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontBolds

      public void setFontBolds(boolean[][] bold)
      Set a set of font bolds formatting to the range. The format array must have the same size of the entire range itself
      Parameters:
      bold - The format 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontItalic

      public void setFontItalic(boolean italic)
      Set a font italic style to the entire range
      Parameters:
      italic - Boolean which indicates if the font has italic style or not

    • setFontItalics

      public void setFontItalics(boolean... italic)
      Set a set of font italics styles to the range. The array must have the same size of the entire range itself 
           Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setFontItalics(true, false, true, false); // Set the font italic formatting for the range
      Parameters:
      italic - The font italics array, it must the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontItalics

      public void setFontItalics(boolean[][] italic)
      Set a set of font italics formatting to the range. The format array must have the same size of the entire range itself
      Parameters:
      italic - The format 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontUnderline

      public void setFontUnderline(boolean underline)
      Set a font underline style to the entire range
      Parameters:
      underline - Boolean which indicates if the font has underline style or not

    • setFontUnderlines

      public void setFontUnderlines(boolean... underline)
      Set a set of font underlines styles to the range. The array must have the same size of the entire range itself 
           Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setFontUnderlines(true, false, true, false); // Set the font underline formatting for the range
      Parameters:
      underline - The font underline array, it must the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontUnderlines

      public void setFontUnderlines(boolean[][] underline)
      Set a set of font underlines formatting to the range. The format array must have the same size of the entire range itself
      Parameters:
      underline - The format 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontColor

      public void setFontColor(Color color)
      Set a font color to the entire range
      Parameters:
      color - The color to aplicate. A null value indicates no color

    • setFontColors

      public void setFontColors(Color... color)
      Set a set of font colors styles to the range. The array must have the same size of the entire range itself 
           Color red = new Color(255, 0, 0);
     Color green = new Color(0, 255, 0);
     Color blue = new Color(0, 0, 255);
     Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setFontColors(red, green, blue, null); // Set the font colors for the range
      Parameters:
      color - The font colors array, it must the same size of the range itself. Null values indicates no color
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontColors

      public void setFontColors(Color[][] color)
      Set a set of font colors formatting to the range. The format array must have the same size of the entire range itself
      Parameters:
      color - The format 2D-array, it must have the same size of the range itself. A null value in the array indicates no color
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setBackgroundColor

      public void setBackgroundColor(Color color)
      Set a cell background color to the entire range
      Parameters:
      color - The color to aplicate. A null value indicates "no color"

    • setBackgroundColors

      public void setBackgroundColors(Color... color)
      Set a set of cell background colors to the range. The array must have the same size of the entire range itself 
           Color red = new Color(255, 0, 0);
     Color green = new Color(0, 255, 0);
     Color blue = new Color(0, 0, 255);
     Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setBackgroundColors(red, green, blue, null); // Set the background colors for the range
      Parameters:
      color - The background colors array, it must the same size of the range itself. Null values indicates no color
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setBackgroundColors

      public void setBackgroundColors(Color[][] color)
      Set a set of cell background colors formatting to the range. The format array must have the same size of the entire range itself
      Parameters:
      color - The format 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFontSize

      public void setFontSize(int fontSize)
      Set the font size to the entire range
      Parameters:
      fontSize - The fontsize to aplicate. A value of -1 unsets the font size
      Throws:
      IllegalArgumentException - if the font size is less of -1

    • setFontSizes

      public void setFontSizes(int... fontSizes)
      Set a set of font sizes to the range. The array must have the same size of the entire range itself 
           Range range = sheet.getRange(0, 0, 2, 2); // 2x2 Range
     range.setBackgroundColors(20, 15, -1, 12); // Set the font sizes for the range
      Parameters:
      fontSizes - The background colors array, it must the same size of the range itself. -1 values unsets the font size
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range or a font size is less of -1

    • setFontSizes

      public void setFontSizes(int[][] fontSizes)
      Set a set of font sizes to the range. The format array must have the same size of the entire range itself
      Parameters:
      fontSizes - The format 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range or a font size is less of -1

    • setFormula

      public void setFormula(String formula)
      Set a formula for every cell in the range. Note that this method doesn't evaluate the formula. It just sets the formula value for when you decide to save it to a file.
      Parameters:
      formula - The formula string representation in the same format of a regular spreadsheet, a example would be: "A1+A2+A3"

    • setFormulas

      public void setFormulas(String... formula)
      Set a set of formulas to the range. The array must have the same size of the entire range itself. Note that this method doesn't evaluate the formulas. It jus sets the formula value for when you decide to save it to a file.
      Parameters:
      formula - The formulas array, it must the same size of the range itself. The format of each formula should be same used in a regular spreadsheet, for example: "A1+A2+A3"
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setFormulas

      public void setFormulas(String[][] formula)
      Set a set of formulas to the range. The formula array must have the same size of the entire range itself Note that this method doesn't evaluate the formulas. It jus sets the formula value for when you decide to save it to a file.
      Parameters:
      formula - The formula 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • setStyle

      public void setStyle(Style style)
      Set a format style for all the cells of the range
      Parameters:
      style - The style to apply. Cells will receive a clone of this object.
      Throws:
      IllegalArgumentException - if the style is null

    • setStyles

      public void setStyles(Style... style)
      Set a set of format styles to the range. The array must have the same size of the entire range itself.
      Parameters:
      style - The style array, it must the same size of the range itself.
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range or a style is null

    • setStyles

      public void setStyles(Style[][] style)
      Set a set of styles to the range. The array must have the same size of the entire range itself
      Parameters:
      style - The style 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range or a style is null

    • setAnnotation

      public void setAnnotation(OfficeAnnotation annotation)
      Set an annotation for all the cells in this range.
      Parameters:
      annotation - The annotation to be setted in the range
      See Also:

    • setAnnotations

      public void setAnnotations(OfficeAnnotation... annotations)
      Set a set of anotations to the range. The array must have the same size of the entire range itself.
      Parameters:
      annotations - The annotations array, it must the same size of the range itself.
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • setAnnotations

      public void setAnnotations(OfficeAnnotation[][] annotations)
      Set a set of annotations to the range. The array must have the same size of the entire range itself
      Parameters:
      annotations - The annotations 2D-array, it must have the same size of the range itself
      Throws:
      IllegalArgumentException - if the number of values is not equals to the size of range

    • merge

      public void merge()
      Merges the cells in the range together into a single block. If the range only contains a cell, no actions will be taken
      Throws:
      AssertionError - if a cell is already in a group. No changes will be done

    • split

      public void split()
      Breaks apart any combined cells on the range. The full group must be inside of the range or a IllegalArgumentException would be thrown.
      Throws:
      IllegalArgumentException - If a group is not fully included on the range, no changes will be done

    • isPartOfMerge

      public boolean isPartOfMerge()
      Determines if the range is part of an existing cell's block
      Returns:
      True if the range overlap any merged cells