Class: IronCalc::Model

Inherits:
Object
  • Object
show all
Includes:
DefinedNames
Defined in:
lib/ironcalc/native_methods.rb

Overview

The raw IronCalc API. You must call #evaluate yourself after changing inputs; misuse can leave the workbook in an inconsistent state. This mirrors the Python binding's Model. For most uses prefer UserModel, which auto-evaluates.

Instance Method Summary collapse

Methods included from DefinedNames

#defined_names, #valid_defined_name?

Instance Method Details

#add_sheet(name) ⇒ void

This method returns an undefined value.

Adds a new sheet with the given name.

Parameters:

  • name (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 463

#copy_cell_style(source_cell, destination_cell) ⇒ void

This method returns an undefined value.

Copies one cell's style (and nothing else) onto another cell, in any sheet.

Parameters:

  • source_cell (Array(Integer, Integer, Integer)) —

    [sheet, row, column]

  • destination_cell (Array(Integer, Integer, Integer)) —

    [sheet, row, column]

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 323

#delete_column_style(sheet, column) ⇒ void

This method returns an undefined value.

Removes a column's default style.

Parameters:

  • sheet (Integer)
  • column (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 330

#delete_columns(sheet, column, column_count) ⇒ void

This method returns an undefined value.

Deletes column_count columns starting at column.

Parameters:

  • sheet (Integer)
  • column (Integer)
  • column_count (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 368

#delete_defined_name(name, scope) ⇒ void

This method returns an undefined value.

Deletes a defined name. Fails if no name matches in that scope.

Parameters:

  • name (String)
  • scope (Integer, nil)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 525

#delete_row_style(sheet, row) ⇒ void

This method returns an undefined value.

Removes a row's default style.

Parameters:

  • sheet (Integer)
  • row (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 337

#delete_rows(sheet, row, row_count) ⇒ void

This method returns an undefined value.

Deletes row_count rows starting at row.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • row_count (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 360

#delete_sheet(sheet) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 473

#evaluate ⇒ void

This method returns an undefined value.

Recalculates the whole workbook. Call after #set_user_input.




# File 'lib/ironcalc/native_methods.rb', line 220

#get_all_cells ⇒ Array<Hash>

Every cell the workbook holds a record for, as { index:, row:, column: } hashes (+index+ is the 0-based sheet index), ordered by sheet, then row, then column. A cell emptied with range_clear_contents keeps its record and is still listed; combine with is_empty_cell if you only want cells that have a value.

Returns:

  • (Array<Hash>) 



# File 'lib/ironcalc/native_methods.rb', line 606

#get_cell_formula(sheet, row, column) ⇒ String?

The cell's formula including the leading =, or nil if it is not a formula cell.

Returns:

  • (String, nil)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 595

#get_cell_type(sheet, row, column) ⇒ Symbol

Returns the cell type as a Symbol: :number, :text, :logical_value, :error_value, :array or :compound_data.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)

Returns:

  • (Symbol)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 250

#get_cell_value_by_index(sheet, row, column) ⇒ nil, ...

The cell's value as a Ruby object — nil, String, Float or true/false — unformatted. Compare get_formatted_cell_value, which always returns a String, and get_localized_cell_content, which returns what the user typed.

The engine has no error variant here, so an error cell comes back as the String "#DIV/0!" and is indistinguishable from that literal text. Use get_cell_type, which reports :error_value, to tell them apart.

Returns:

  • (nil, String, Float, Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 577

#get_cell_value_by_ref(cell_ref) ⇒ nil, ...

Like get_cell_value_by_index, addressed by an A1-style reference that includes the sheet, e.g. "Sheet1!C4".

Parameters:

  • cell_ref (String)

Returns:

  • (nil, String, Float, Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 588

#get_column_style(sheet, column) ⇒ Hash?

The default style for a whole column, as a Hash, or nil if the column carries no style of its own.

Parameters:

  • sheet (Integer)
  • column (Integer)

Returns:

  • (Hash, nil)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 288

#get_column_width(sheet, column) ⇒ Float

Returns width in pixels.

Parameters:

  • sheet (Integer)
  • column (Integer)

Returns:

  • (Float) —

    width in pixels

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 376

#get_defined_name_list ⇒ Array<Hash>

Defined names as one Hash per name, with symbol keys :name, :scope (0-based sheet index, or nil for workbook scope) and :formula. Also available as DefinedNames#defined_names.

Returns:

  • (Array<Hash>) 



# File 'lib/ironcalc/native_methods.rb', line 498

#get_formatted_cell_value(sheet, row, column) ⇒ String

The cell's value with its number format applied, as displayed — e.g. "$ 5.75".

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)

Returns:

  • (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 259

#get_frozen_columns_count(sheet) ⇒ Integer

Parameters:

  • sheet (Integer)

Returns:

  • (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 428

#get_frozen_rows_count(sheet) ⇒ Integer

Parameters:

  • sheet (Integer)

Returns:

  • (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 433

#get_localized_cell_content(sheet, row, column) ⇒ String

Returns the cell's content in the model's locale: the formula (e.g. "=A1+1") or literal text.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)

Returns:

  • (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 241

#get_row_height(sheet, row) ⇒ Float

Returns height in pixels.

Parameters:

  • sheet (Integer)
  • row (Integer)

Returns:

  • (Float) —

    height in pixels

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 382

#get_row_style(sheet, row) ⇒ Hash?

The default style for a whole row, as a Hash, or nil if the sheet holds no record for that row. A row whose style was deleted reads back as the default style rather than nil; the column equivalent returns nil.

Parameters:

  • sheet (Integer)
  • row (Integer)

Returns:

  • (Hash, nil)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 296

#get_sheet_dimensions(sheet) ⇒ Array(Integer, Integer, Integer, Integer)

Returns [min_row, max_row, min_column, max_column] over non-empty cells (an empty sheet returns [1, 1, 1, 1]).

Parameters:

  • sheet (Integer)

Returns:

  • (Array(Integer, Integer, Integer, Integer))

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 491

#get_style_for_cell(sheet, row, column) ⇒ Hash

Returns the cell style as a Hash with Symbol keys, e.g. {num_fmt: "general", font: {b: false, ...}, ...}.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)

Returns:

  • (Hash)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 268

#get_worksheets_properties ⇒ Array<Hash>

Returns one Hash per sheet with symbol keys :name, :state, :sheet_id and :color.

Returns:

  • (Array<Hash>) 



# File 'lib/ironcalc/native_methods.rb', line 450

#insert_columns(sheet, column, column_count) ⇒ void

This method returns an undefined value.

Inserts column_count columns before column.

Parameters:

  • sheet (Integer)
  • column (Integer)
  • column_count (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 352

#insert_rows(sheet, row, row_count) ⇒ void

This method returns an undefined value.

Inserts row_count rows before row.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • row_count (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 344

#insert_sheet(sheet_name, sheet_index, sheet_id) ⇒ void

This method returns an undefined value.

Adds a sheet at sheet_index rather than appending it.

Parameters:

  • sheet_name (String)
  • sheet_index (Integer) —

    0-based position to insert at

  • sheet_id (Integer, nil) —

    normally nil, so the engine allocates one

Raises:

  • (IronCalc::Error) —

    also if sheet_id is already in use, which the engine itself does not check




# File 'lib/ironcalc/native_methods.rb', line 614

#is_column_hidden(sheet, column) ⇒ Boolean

Parameters:

  • sheet (Integer)
  • column (Integer)

Returns:

  • (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 402

#is_empty_cell(sheet, row, column) ⇒ Boolean

Whether the cell holds no content.

Returns:

  • (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 601

#is_row_hidden(sheet, row) ⇒ Boolean

Parameters:

  • sheet (Integer)
  • row (Integer)

Returns:

  • (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 415

#is_valid_defined_name(name, scope, formula) ⇒ Integer?

Checks whether #new_defined_name would succeed for these arguments, raising with the reason if not. DefinedNames#valid_defined_name? answers the same question as a boolean.

Parameters:

  • name (String)
  • scope (Integer, nil)
  • formula (String)

Returns:

  • (Integer, nil) —

    the sheet_id of the scope's sheet (as in get_worksheets_properties), or nil for workbook scope

Raises:

  • (IronCalc::Error) —

    with the reason, e.g. the name is already taken in that scope




# File 'lib/ironcalc/native_methods.rb', line 532

#new_defined_name(name, scope, formula) ⇒ void

This method returns an undefined value.

Adds a defined name. Fails if the name is not a valid identifier (+"A1"+ is not: it parses as a cell reference), if it is already taken in that scope, or if the formula does not parse.

Parameters:

  • name (String)
  • scope (Integer, nil) —

    0-based sheet index, or nil for workbook scope

  • formula (String) —

    e.g. "Sheet1!$C$1"

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 505

#new_sheet ⇒ void

This method returns an undefined value.

Adds a new sheet with an auto-generated name.




# File 'lib/ironcalc/native_methods.rb', line 469

#range_clear_all(area) ⇒ void

This method returns an undefined value.

Clears the contents and style of every cell in a range, removing the cells entirely. Compare range_clear_contents, which keeps the style.

Parameters:

  • area (Hash) —

    the engine's Area: {sheet:, row:, column:, width:, height:}

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 544

#range_clear_contents(range) ⇒ void

This method returns an undefined value.

Clears the contents (not the style) of every cell in a range.

Parameters:

  • range (Hash) —

    the engine's Area: {sheet:, row:, column:, width:, height:}

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 234

#rename_sheet(old_name, new_name) ⇒ void

This method returns an undefined value.

Renames the sheet called old_name.

Parameters:

  • old_name (String)
  • new_name (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 478

#rename_sheet_by_index(sheet_index, new_name) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet_index (Integer)
  • new_name (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 485

#save_to_icalc(file) ⇒ void

This method returns an undefined value.

Saves the workbook to the internal binary icalc format.

Parameters:

  • file (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 209

#save_to_xlsx(file) ⇒ void

This method returns an undefined value.

Saves the workbook to an xlsx file. Fails if the file already exists.

Parameters:

  • file (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 198

#set_cell_style(sheet, row, column, style) ⇒ void

This method returns an undefined value.

Sets the cell style. Takes a complete style, as returned by #get_style_for_cell: read one, change it, pass it back. Keys may be Symbols or Strings.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)
  • style (Hash)

Raises:

  • (IronCalc::Error) —

    also if the style is incomplete




# File 'lib/ironcalc/native_methods.rb', line 277

#set_column_hidden(sheet, column, hidden) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • column (Integer)
  • hidden (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 408

#set_column_style(sheet, column, style) ⇒ void

This method returns an undefined value.

Sets the default style for a whole column. Takes a complete style, as #set_cell_style does.

Parameters:

  • sheet (Integer)
  • column (Integer)
  • style (Hash)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 305

#set_column_width(sheet, column, width) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • column (Integer)
  • width (Float)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 388

#set_frozen_columns(sheet, frozen_columns) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • frozen_columns (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 438

#set_frozen_rows(sheet, frozen_rows) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • frozen_rows (Integer)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 444

#set_row_height(sheet, row, height) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • height (Float)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 395

#set_row_hidden(sheet, row, hidden) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • hidden (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 421

#set_row_style(sheet, row, style) ⇒ void

This method returns an undefined value.

Sets the default style for a whole row. Takes a complete style, as #set_cell_style does.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • style (Hash)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 314

#set_sheet_color(sheet, color) ⇒ void

This method returns an undefined value.

Sets the sheet tab color.

Parameters:

  • sheet (Integer)
  • color (String, Array, nil) —

    "#RRGGBB", a [theme, tint] pair, or nil to clear

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 455

#set_sheet_state(sheet, state) ⇒ void

This method returns an undefined value.

Sets a sheet's visibility. Matches the :state value reported by get_worksheets_properties.

Parameters:

  • sheet (Integer)
  • state (String) —

    "visible", "hidden" or "veryHidden" (+"very_hidden"+ is also accepted)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 623

#set_user_input(sheet, row, column, value) ⇒ void

This method returns an undefined value.

Sets a cell's input, parsed as a user typing it would be: "3.5" is a number, "Hello" a string, "=A1*2" a formula.

Parameters:

  • sheet (Integer)
  • row (Integer)
  • column (Integer)
  • value (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 224

#to_bytes ⇒ String

Serializes the workbook to icalc bytes (load with IronCalc.load_from_bytes). This is IronCalc's internal format, not xlsx; see #to_xlsx_bytes.

Returns:

  • (String) —

    binary string




# File 'lib/ironcalc/native_methods.rb', line 215

#to_xlsx_bytes ⇒ String

Serializes the workbook to xlsx bytes (load with IronCalc.load_from_xlsx_bytes).

Returns:

  • (String) —

    binary string

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 204

#update_cell_with_bool(sheet, row, column, value) ⇒ void

This method returns an undefined value.

Sets a boolean without input parsing.

Parameters:

  • value (Boolean)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 565

#update_cell_with_formula(sheet, row, column, formula) ⇒ void

This method returns an undefined value.

Stores a formula directly. Call evaluate afterwards.

Parameters:

  • formula (String) —

    including the leading =

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 571

#update_cell_with_number(sheet, row, column, value) ⇒ void

This method returns an undefined value.

Sets a number without input parsing.

Parameters:

  • value (Float)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 559

#update_cell_with_text(sheet, row, column, value) ⇒ void

This method returns an undefined value.

Stores value as text without parsing it, so "007" stays "007" and +"=1+1"+ stays a string. Compare set_user_input, which parses.

Parameters:

  • value (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 552

#update_defined_name(name, scope, new_name, new_scope, new_formula) ⇒ void

This method returns an undefined value.

Renames, re-scopes and/or repoints an existing defined name.

Parameters:

  • name (String) —

    the current name

  • scope (Integer, nil) —

    the current scope

  • new_name (String)
  • new_scope (Integer, nil)
  • new_formula (String)

Raises:

  • (IronCalc::Error) 



# File 'lib/ironcalc/native_methods.rb', line 515