UmyaSpreadsheet.FormulaFunctions (umya_spreadsheet_ex v0.7.0)

View Source

Functions 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 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.

Functions

create_defined_name(spreadsheet, name, formula, sheet_name \\ nil)

@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 struct
  • name - Name for the defined name
  • formula - 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

create_named_range(spreadsheet, name, sheet_name, range)

@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 struct
  • name - Name for the range
  • sheet_name - Name of the worksheet
  • range - Cell range in A1 notation (e.g., "A1:B5")

Examples

iex> UmyaSpreadsheet.create_named_range(spreadsheet, "MyRange", "Sheet1", "A1:B10")
:ok

get_bx(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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

get_data_table_2d(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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

get_data_table_row(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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

get_defined_names(spreadsheet)

@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)"}]

get_formula(spreadsheet, sheet_name, cell_address)

@spec get_formula(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  String.t()

Gets the formula text from a cell.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_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")
""

get_formula_obj(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • A tuple {text, type, shared_index, reference} containing:
    • text: The formula text
    • type: 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"}

get_formula_shared_index(spreadsheet, sheet_name, cell_address)

@spec get_formula_shared_index(
  UmyaSpreadsheet.Spreadsheet.t(),
  String.t(),
  String.t()
) ::
  integer() | nil

Gets the shared index of a formula in a cell.

Parameters

  • spreadsheet: The spreadsheet resource
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • The shared formula index as integer, or nil if not a shared formula

@doc """ Gets the shared index of a formula in a cell.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • The shared formula index as integer, or nil if not a shared formula

Examples

iex> FormulaFunctions.get_formula_shared_index(spreadsheet, "Sheet1", "A1")
0

iex> FormulaFunctions.get_formula_shared_index(spreadsheet, "Sheet1", "B1")
nil

get_formula_type(spreadsheet, sheet_name, cell_address)

@spec get_formula_type(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  String.t()

Gets the formula type of a cell.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_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"

get_input_1deleted(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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

get_input_2deleted(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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

get_r1(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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"

get_r2(spreadsheet, sheet_name, cell_address)

@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 struct
  • sheet_name: Name of the worksheet
  • cell_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"

get_reference(spreadsheet, sheet_name, cell_address)

@spec get_reference(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  String.t() | nil

Gets the reference of a formula.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_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"

get_shared_index(spreadsheet, sheet_name, cell_address)

@spec get_shared_index(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) ::
  integer() | nil

Gets the shared index of a formula.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_address: Cell address (e.g., "A1", "B2")

Returns

  • The shared formula index as integer, or nil if not shared

Examples

iex> FormulaFunctions.get_shared_index(spreadsheet, "Sheet1", "A1")
0

get_text(spreadsheet, sheet_name, cell_address)

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 struct
  • sheet_name: Name of the worksheet
  • cell_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)"

is_formula(spreadsheet, sheet_name, cell_address)

@spec is_formula(UmyaSpreadsheet.Spreadsheet.t(), String.t(), String.t()) :: boolean()

Checks if a cell contains a formula.

Parameters

  • spreadsheet: The spreadsheet struct
  • sheet_name: Name of the worksheet
  • cell_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

set_array_formula(spreadsheet, sheet_name, range, formula)

@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 struct
  • sheet_name - Name of the worksheet
  • range - 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

set_formula(spreadsheet, sheet_name, cell_address, formula)

@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 struct
  • sheet_name - Name of the worksheet
  • cell_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