UmyaSpreadsheet.FormulaFunctions (umya_spreadsheet_ex v0.7.0)
View SourceFunctions for working with formulas in spreadsheets.
Summary
Functions
Creates a defined name in the spreadsheet with an associated formula.
Creates a named range in the spreadsheet.
Gets the bx property of a formula.
Gets the data table 2D property of a formula.
Gets the data table row property of a formula.
Gets all defined names in the spreadsheet.
Gets the formula text from a cell.
Gets the complete formula object from a cell.
Gets the shared index of a formula in a cell.
Gets the formula type of a cell.
Gets the input 1 deleted property of a formula.
Gets the input 2 deleted property of a formula.
Gets the R1 property of a formula.
Gets the R2 property of a formula.
Gets the reference of a formula.
Gets the shared index of a formula.
Gets the text content of a formula in a cell.
Checks if a cell contains a formula.
Sets an array formula for a range of cells. Array formulas can return multiple values across a range of cells.
Sets a regular formula in a cell.
Functions
@spec create_defined_name( UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t(), String.t() | nil ) :: :ok | {:error, atom()}
Creates a defined name in the spreadsheet with an associated formula.
Parameters
spreadsheet
- The spreadsheet structname
- Name for the defined nameformula
- Formula string (without leading =)sheet_name
- Optional name of the worksheet to scope the defined name to
Examples
iex> UmyaSpreadsheet.create_defined_name(spreadsheet, "TaxRate", "0.15")
:ok
iex> UmyaSpreadsheet.create_defined_name(spreadsheet, "Department", "Sales", "Sheet1")
:ok
@spec create_named_range( UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t(), String.t() ) :: :ok | {:error, atom()}
Creates a named range in the spreadsheet.
Parameters
spreadsheet
- The spreadsheet structname
- Name for the rangesheet_name
- Name of the worksheetrange
- Cell range in A1 notation (e.g., "A1:B5")
Examples
iex> UmyaSpreadsheet.create_named_range(spreadsheet, "MyRange", "Sheet1", "A1:B10")
:ok
@spec get_bx(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean() | nil
Gets the bx property of a formula.
The bx property indicates whether the formula calculation should be done on exit from the cell.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if bx is set,false
if not set,nil
if no formula
Examples
iex> FormulaFunctions.get_bx(spreadsheet, "Sheet1", "A1")
true
@spec get_data_table_2d(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean() | nil
Gets the data table 2D property of a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if this is a 2D data table,false
if not,nil
if no formula
Examples
iex> FormulaFunctions.get_data_table_2d(spreadsheet, "Sheet1", "A1")
false
@spec get_data_table_row(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean() | nil
Gets the data table row property of a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if this is a data table row,false
if not,nil
if no formula
Examples
iex> FormulaFunctions.get_data_table_row(spreadsheet, "Sheet1", "A1")
true
@spec get_defined_names(UmyaSpreadsheet.Spreadsheet.t()) :: [{String.t(), String.t()}]
Gets all defined names in the spreadsheet.
Parameters
spreadsheet
: The spreadsheet struct
Returns
- A list of tuples containing {name, address} for each defined name
Examples
iex> FormulaFunctions.get_defined_names(spreadsheet)
[{"MyRange", "Sheet1!A1:B2"}, {"Total", "SUM(A1:A10)"}]
@spec get_formula(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t()
Gets the formula text from a cell.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The formula text as a string, empty string if no formula
Examples
iex> FormulaFunctions.get_formula(spreadsheet, "Sheet1", "A1")
"=SUM(B1:B10)"
iex> FormulaFunctions.get_formula(spreadsheet, "Sheet1", "B1")
""
@spec get_formula_obj(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: {String.t(), String.t(), integer() | nil, String.t() | nil}
Gets the complete formula object from a cell.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- A tuple
{text, type, shared_index, reference}
containing:text
: The formula texttype
: The formula type as string ("Normal", "Array", "DataTable", "Shared")shared_index
: The shared formula index (nil if not shared)reference
: The formula reference (nil if none)
Examples
iex> FormulaFunctions.get_formula_obj(spreadsheet, "Sheet1", "A1")
{"=SUM(B1:B10)", "Normal", nil, nil}
iex> FormulaFunctions.get_formula_obj(spreadsheet, "Sheet1", "C1")
{"=A1+B1", "Shared", 0, "C1:C10"}
@spec get_formula_type(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t()
Gets the formula type of a cell.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The formula type as a string: "Normal", "Array", "DataTable", "Shared", or "None"
Examples
iex> FormulaFunctions.get_formula_type(spreadsheet, "Sheet1", "A1")
"Normal"
iex> FormulaFunctions.get_formula_type(spreadsheet, "Sheet1", "B1")
"Array"
@spec get_input_1deleted(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean() | nil
Gets the input 1 deleted property of a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if input 1 is deleted,false
if not,nil
if no formula
Examples
iex> FormulaFunctions.get_input_1deleted(spreadsheet, "Sheet1", "A1")
false
@spec get_input_2deleted(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean() | nil
Gets the input 2 deleted property of a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if input 2 is deleted,false
if not,nil
if no formula
Examples
iex> FormulaFunctions.get_input_2deleted(spreadsheet, "Sheet1", "A1")
false
@spec get_r1(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t() | nil
Gets the R1 property of a formula.
The R1 property is used in data table formulas to specify the first input cell reference.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The R1 reference as a string, or
nil
if not set
Examples
iex> FormulaFunctions.get_r1(spreadsheet, "Sheet1", "A1")
"A1"
@spec get_r2(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t() | nil
Gets the R2 property of a formula.
The R2 property is used in data table formulas to specify the second input cell reference.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The R2 reference as a string, or
nil
if not set
Examples
iex> FormulaFunctions.get_r2(spreadsheet, "Sheet1", "A1")
"B1"
@spec get_reference(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t() | nil
Gets the reference of a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The formula reference as a string, or
nil
if no reference
Examples
iex> FormulaFunctions.get_reference(spreadsheet, "Sheet1", "A1")
"A1:A10"
@spec get_text(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: String.t()
Gets the text content of a formula in a cell.
This is similar to get_formula/3
but specifically gets the text property
from the CellFormula object.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
- The formula text as a string, empty string if no formula
Examples
iex> FormulaFunctions.get_text(spreadsheet, "Sheet1", "A1")
"=SUM(B1:B10)"
@spec is_formula(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean()
Checks if a cell contains a formula.
Parameters
spreadsheet
: The spreadsheet structsheet_name
: Name of the worksheetcell_address
: Cell address (e.g., "A1", "B2")
Returns
true
if the cell contains a formula,false
otherwise
Examples
iex> FormulaFunctions.is_formula(spreadsheet, "Sheet1", "A1")
true
iex> FormulaFunctions.is_formula(spreadsheet, "Sheet1", "B1")
false
@spec set_array_formula( UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t(), String.t() ) :: :ok | {:error, atom()}
Sets an array formula for a range of cells. Array formulas can return multiple values across a range of cells.
Parameters
spreadsheet
- The spreadsheet structsheet_name
- Name of the worksheetrange
- Cell range in A1 notation (e.g., "A1:B5")formula
- Formula string (without leading =)
Examples
iex> UmyaSpreadsheet.set_array_formula(spreadsheet, "Sheet1", "A1:A3", "ROW(1:3)")
:ok
@spec set_formula(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t(), String.t()) :: :ok | {:error, atom()}
Sets a regular formula in a cell.
Parameters
spreadsheet
- The spreadsheet structsheet_name
- Name of the worksheetcell_address
- Cell address in A1 notation (e.g., "A1", "B2")formula
- Formula string (without leading =)
Examples
iex> UmyaSpreadsheet.set_formula(spreadsheet, "Sheet1", "A1", "SUM(B1:B10)")
:ok