Class: IronCalc::UserModel

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

Overview

The recommended, higher-level IronCalc API. Auto-evaluates after every action and records diffs for collaboration (#flush_send_queue / #apply_external_diffs). Mirrors IronCalc's WebAssembly binding and is a superset of the Python binding's UserModel. Styling is per-property via #update_range_style.

Instance Method Summary collapse

Methods included from DefinedNames

#defined_names, #valid_defined_name?

Methods included from Batch

#batch

Instance Method Details

#apply_external_diffs(diffs) ⇒ void

This method returns an undefined value.

Applies a peer's diff blob (from #flush_send_queue) for collaboration.

Parameters:

  • diffs (String) —

    binary diff blob

Raises:

  • (IronCalc::Error) 



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

#can_redo ⇒ Boolean

Returns:

  • (Boolean) 



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

#can_undo ⇒ Boolean

Returns:

  • (Boolean) 



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

#delete_columns(sheet, column, column_count) ⇒ void

This method returns an undefined value.

Parameters:

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

Raises:

  • (IronCalc::Error) 



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

#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 932

#delete_rows(sheet, row, row_count) ⇒ void

This method returns an undefined value.

Parameters:

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

Raises:

  • (IronCalc::Error) 



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

#delete_sheet(sheet) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)

Raises:

  • (IronCalc::Error) 



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

#evaluate ⇒ void

This method returns an undefined value.

Forces a recalculation. Usually unnecessary — the user model auto-evaluates after each action; exposed for parity.




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

#flush_send_queue ⇒ String

Returns and clears the queued diffs to broadcast to collaborators.

Returns:

  • (String) —

    binary diff blob




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

#get_cell_content(sheet, row, column) ⇒ String

Returns the cell's content: formula or literal text.

Parameters:

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

Returns:

  • (String)

Raises:

  • (IronCalc::Error) 



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

#get_cell_style(sheet, row, column) ⇒ Hash

Returns the cell style as a Hash with Symbol keys, like Model#get_style_for_cell.

Parameters:

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

Returns:

  • (Hash)

Raises:

  • (IronCalc::Error) 



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

#get_cell_type(sheet, row, column) ⇒ Symbol

Returns the cell type as a Symbol (see Model#get_cell_type).

Parameters:

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

Returns:

  • (Symbol)

Raises:

  • (IronCalc::Error) 



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

#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 789

#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 906

#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 731

#get_frozen_columns_count(sheet) ⇒ Integer

Parameters:

  • sheet (Integer)

Returns:

  • (Integer)

Raises:

  • (IronCalc::Error) 



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

#get_frozen_rows_count(sheet) ⇒ Integer

Parameters:

  • sheet (Integer)

Returns:

  • (Integer)

Raises:

  • (IronCalc::Error) 



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

#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 795

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

Returns [min_row, max_row, min_column, max_column] over non-empty cells.

Parameters:

  • sheet (Integer)

Returns:

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

Raises:

  • (IronCalc::Error) 



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

#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 871

#insert_columns(sheet, column, column_count) ⇒ void

This method returns an undefined value.

Parameters:

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

Raises:

  • (IronCalc::Error) 



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

#insert_rows(sheet, row, row_count) ⇒ void

This method returns an undefined value.

Parameters:

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

Raises:

  • (IronCalc::Error) 



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

#is_column_hidden(sheet, column) ⇒ Boolean

Parameters:

  • sheet (Integer)
  • column (Integer)

Returns:

  • (Boolean)

Raises:

  • (IronCalc::Error) 



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

#is_row_hidden(sheet, row) ⇒ Boolean

Parameters:

  • sheet (Integer)
  • row (Integer)

Returns:

  • (Boolean)

Raises:

  • (IronCalc::Error) 



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

#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 939

#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 912

#new_sheet ⇒ void

This method returns an undefined value.

Adds a new sheet with an auto-generated name.

Raises:

  • (IronCalc::Error) 



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

#pause_evaluation ⇒ void

This method returns an undefined value.

Suspends the automatic recalculation this API does after every action — useful when writing many cells at once. While paused, formula cells read back as #ERROR! until evaluated.




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

#range_clear_all(range) ⇒ void

This method returns an undefined value.

Clears the contents and style of every cell in a range. Undoable.

Parameters:

  • range (Hash) —

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

Raises:

  • (IronCalc::Error) 



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

#range_clear_contents(range) ⇒ void

This method returns an undefined value.

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

Parameters:

  • range (Hash) —

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

Raises:

  • (IronCalc::Error) 



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

#range_clear_formatting(range) ⇒ void

This method returns an undefined value.

Clears the style of every cell in a range, keeping the contents. Undoable.

Parameters:

  • range (Hash) —

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

Raises:

  • (IronCalc::Error) 



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

#redo ⇒ void

This method returns an undefined value.

Redoes the last undone change.

Raises:

  • (IronCalc::Error) 



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

#rename_sheet(sheet, new_name) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • new_name (String)

Raises:

  • (IronCalc::Error) 



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

#resume_evaluation ⇒ void

This method returns an undefined value.

Re-enables automatic recalculation. Does not recalculate by itself; call evaluate afterwards to bring the workbook up to date.




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

#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 656

#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 644

#set_columns_hidden(sheet, column_start, column_end, hidden) ⇒ void

This method returns an undefined value.

Hides or shows columns column_start to column_end, inclusive. Undoable.

Parameters:

  • sheet (Integer)
  • column_start (Integer)
  • column_end (Integer)
  • hidden (Boolean)

Raises:

  • (IronCalc::Error) 



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

#set_columns_width(sheet, column_start, column_end, width) ⇒ void

This method returns an undefined value.

Sets the width of columns column_start to column_end, inclusive.

Parameters:

  • sheet (Integer)
  • column_start (Integer)
  • column_end (Integer)
  • width (Float)

Raises:

  • (IronCalc::Error) 



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

#set_frozen_columns_count(sheet, count) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • count (Integer)

Raises:

  • (IronCalc::Error) 



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

#set_frozen_rows_count(sheet, count) ⇒ void

This method returns an undefined value.

Parameters:

  • sheet (Integer)
  • count (Integer)

Raises:

  • (IronCalc::Error) 



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

#set_rows_height(sheet, row_start, row_end, height) ⇒ void

This method returns an undefined value.

Sets the height of rows row_start to row_end, inclusive.

Parameters:

  • sheet (Integer)
  • row_start (Integer)
  • row_end (Integer)
  • height (Float)

Raises:

  • (IronCalc::Error) 



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

#set_rows_hidden(sheet, row_start, row_end, hidden) ⇒ void

This method returns an undefined value.

Hides or shows rows row_start to row_end, inclusive. Undoable.

Parameters:

  • sheet (Integer)
  • row_start (Integer)
  • row_end (Integer)
  • hidden (Boolean)

Raises:

  • (IronCalc::Error) 



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

#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 876

#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. Triggers recalculation.

Parameters:

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

Raises:

  • (IronCalc::Error) 



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

#to_bytes ⇒ String

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

Returns:

  • (String) —

    binary string




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

#to_xlsx_bytes ⇒ String

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

Returns:

  • (String) —

    binary string

Raises:

  • (IronCalc::Error) 



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

#undo ⇒ void

This method returns an undefined value.

Undoes the last change.

Raises:

  • (IronCalc::Error) 



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

#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 922

#update_range_style(range, style_path, value) ⇒ void

This method returns an undefined value.

Sets a single style property on every cell of a range, e.g. bold for B2:C10: update_range_style({sheet: 0, row: 2, column: 2, width: 2, height: 9}, "font.b", "true"). This is the user model's styling primitive: the engine's UserModel has no whole-style setter.

Parameters:

  • range (Hash) —

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

  • style_path (String) —

    dotted path, e.g. "font.b", "fill.color"

  • value (String)

Raises:

  • (IronCalc::Error) —

    also if range is missing a key




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