Class: Axlsx::Cell

Inherits:
Object
  • Object
show all
Includes:
OptionsParser
Defined in:
lib/axlsx/workbook/worksheet/cell.rb

Overview

Note:

The recommended way to generate cells is via Worksheet#add_row

A cell in a worksheet. Cell stores inforamation requried to serialize a single worksheet cell to xml. You must provde the Row that the cell belongs to and the cells value. The data type will automatically be determed if you do not specify the :type option. The default style will be applied if you do not supply the :style option. Changing the cell's type will recast the value to the type specified. Altering the cell's value via the property accessor will also automatically cast the provided value to the cell's type.

See Also:

Constant Summary

INLINE_STYLES =

An array of available inline styes. TODO change this to a hash where each key defines attr name and validator (and any info the validator requires) then move it out to a module so we can re-use in in other classes. needs to define bla=(v) and bla methods on the class that hook into a set_attr method that kicks the suplied validator and updates the instance_variable for the key

[:value, :type, :font_name, :charset,
:family, :b, :i, :strike, :outline,
:shadow, :condense, :extend, :u,
:vertAlign, :sz, :color, :scheme].freeze
CELL_TYPES =
[:date, :time, :float, :integer, :richtext,
:string, :boolean, :iso_8601].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from OptionsParser

#parse_options

Constructor Details

#initialize(row, value = nil, options = {}) ⇒ Cell

Returns a new instance of Cell

Options Hash (options):

  • type (Symbol)

    The intended data type for this cell. If not specified the data type will be determined internally based on the vlue provided.

  • style (Integer)

    The index of the cellXfs item to be applied to this cell. If not specified, the default style (0) will be applied.

  • font_name (String)
  • charset (Integer)
  • family (String)
  • b (Boolean)
  • i (Boolean)
  • strike (Boolean)
  • outline (Boolean)
  • shadow (Boolean)
  • condense (Boolean)
  • extend (Boolean)
  • u (Boolean)
  • vertAlign (Symbol)

    must be one of :baseline, :subscript, :superscript

  • sz (Integer)
  • color (String)

    an 8 letter rgb specification

  • formula_value (Number)

    The value to cache for a formula cell.

  • scheme (Symbol)

    must be one of :none, major, :minor



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 33

def initialize(row, value = nil, options = {})
  @row = row
  # Do not use instance vars if not needed to use less RAM
  # And do not call parse_options on frequently used options
  # to get less GC cycles
  type = options.delete(:type) || cell_type_from_value(value)
  self.type = type unless type == :string
  

  val = options.delete(:style)
  self.style = val unless val.nil? || val == 0
  val = options.delete(:formula_value)
  self.formula_value = val unless val.nil?
  
  parse_options(options) 

  self.value = value
  value.cell = self if contains_rich_text?
end

Instance Attribute Details

#bBoolean

The inline bold property for the cell



180
181
182
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 180

def b
  @b
end

#charsetString

The inline charset property for the cell As far as I can tell, this is pretty much ignored. However, based on the spec it should be one of the following: 0  ANSI_CHARSET 1 DEFAULT_CHARSET 2 SYMBOL_CHARSET 77 MAC_CHARSET 128 SHIFTJIS_CHARSET 129  HANGUL_CHARSET 130  JOHAB_CHARSET 134  GB2312_CHARSET 136  CHINESEBIG5_CHARSET 161  GREEK_CHARSET 162  TURKISH_CHARSET 163  VIETNAMESE_CHARSET 177  HEBREW_CHARSET 178  ARABIC_CHARSET 186  BALTIC_CHARSET 204  RUSSIAN_CHARSET 222  THAI_CHARSET 238  EASTEUROPE_CHARSET 255  OEM_CHARSET



161
162
163
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 161

def charset
  @charset
end

#colorColor

The inline color property for the cell



234
235
236
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 234

def color
  @color
end

#condenseBoolean

The inline condense property for the cell



210
211
212
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 210

def condense
  @condense
end

#extendBoolean

The inline extend property for the cell



216
217
218
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 216

def extend
  @extend
end

#familyInteger

The inline family property for the cell 1 Roman 2 Swiss 3 Modern 4 Script 5 Decorative



172
173
174
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 172

def family
  @family
end

#font_nameString

The inline font_name property for the cell



135
136
137
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 135

def font_name
  @font_name
end

#formula_valueObject

this is the cached value for formula cells. If you want the values to render in iOS/Mac OSX preview you need to set this.



55
56
57
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 55

def formula_value
  @formula_value
end

#iBoolean

The inline italic property for the cell



186
187
188
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 186

def i
  @i
end

#nameObject

returns the name of the cell



349
350
351
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 349

def name
  @name
end

#outlineBoolean

The inline outline property for the cell



198
199
200
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 198

def outline
  @outline
end

#rowRow (readonly)

The row this cell belongs to.



80
81
82
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 80

def row
  @row
end

#schemeSymbol

The inline scheme property for the cell this must be one of [:none, major, minor]



260
261
262
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 260

def scheme
  @scheme
end

#shadowBoolean

The inline shadow property for the cell



204
205
206
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 204

def shadow
  @shadow
end

#sstiInteger

The Shared Strings Table index for this cell



269
270
271
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 269

def ssti
  @ssti
end

#strikeBoolean

The inline strike property for the cell



192
193
194
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 192

def strike
  @strike
end

#szInteter

The inline sz property for the cell



243
244
245
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 243

def sz
  @sz
end

#uBoolean, String

Note:

true is for backwards compatability and is reassigned to :single

The inline underline property for the cell. It must be one of :none, :single, :double, :singleAccounting, :doubleAccounting, true



225
226
227
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 225

def u
  @u
end

#valueString, ...

The value of this cell.



106
107
108
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 106

def value
  @value
end

#vertAlignSymbol

The inline vertical alignment property for the cell this must be one of [:baseline, :subscript, :superscript]



250
251
252
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 250

def vertAlign
  @vertAlign
end

Instance Method Details

#autowidthObject



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 351

def autowidth
  return if is_formula? || value.nil?
  if contains_rich_text?
    string_width('', font_size) + value.autowidth
  elsif styles.cellXfs[style].alignment && styles.cellXfs[style].alignment.wrap_text
    max_width = 0
    value.to_s.split(/\r?\n/).each do |line|
      width = string_width(line, font_size)
      max_width = width if width > max_width
    end
    max_width
  else
    string_width(value, font_size)
  end
end

#clean_valueObject

Returns the sanatized value TODO find a better way to do this as it accounts for 30% of processing time in benchmarking...



370
371
372
373
374
375
376
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 370

def clean_value
  if type == :string && !Axlsx::trust_input
    Axlsx::sanitize(::CGI.escapeHTML(@value.to_s))
  else
    @value.to_s
  end
end

#contains_rich_text?Boolean



120
121
122
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 120

def contains_rich_text?
  type == :richtext
end

#indexInteger



272
273
274
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 272

def index
  @row.index(self)
end

#is_array_formula?Boolean



329
330
331
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 329

def is_array_formula?
  type == :string && @value.to_s.start_with?('{=') && @value.to_s.end_with?('}')
end

#is_formula?Boolean



325
326
327
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 325

def is_formula?
  type == :string && @value.to_s.start_with?(?=)
end

#is_text_run?Boolean

Indicates that the cell has one or more of the custom cell styles applied.



116
117
118
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 116

def is_text_run?
  defined?(@is_text_run) && @is_text_run && !contains_rich_text?
end

#merge(target) ⇒ Object

Merges all the cells in a range created between this cell and the cell or string name for a cell provided

See Also:

  • Axlsx::Cell.worksheetworksheet.merge_cells


307
308
309
310
311
312
313
314
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 307

def merge(target)
  start, stop = if target.is_a?(String)
                  [self.r, target]
                elsif(target.is_a?(Cell))
                  Axlsx.sort_cells([self, target]).map { |c| c.r }
                end
  self.row.worksheet.merge_cells "#{start}:#{stop}" unless stop.nil?
end

#plain_string?Boolean

Indicates if the cell is good for shared string table



125
126
127
128
129
130
131
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 125

def plain_string?
  type == :string &&         # String typed
    !is_text_run? &&          # No inline styles
    !@value.nil? &&           # Not nil
    !@value.empty? &&         # Not empty
    !@value.start_with?(?=)  # Not a formula
end

#posArray



300
301
302
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 300

def pos
  [index, row.row_index]
end

#rString

Returns The alpha(column)numeric(row) reference for this sell.

Examples:

Relative Cell Reference

ws.rows.first.cells.first.r #=> "A1"


279
280
281
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 279

def r
  Axlsx::cell_r index, @row.row_index
end

#r_absString

Returns The absolute alpha(column)numeric(row) reference for this sell.

Examples:

Absolute Cell Reference

ws.rows.first.cells.first.r #=> "$A$1"


286
287
288
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 286

def r_abs
  "$#{r.match(%r{([A-Z]+)([0-9]+)})[1,2].join('$')}"
end

#reference(absolute = true) ⇒ String

returns the absolute or relative string style reference for this cell. returned.



338
339
340
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 338

def reference(absolute=true)
  absolute ? r_abs : r
end

#styleInteger

The index of the cellXfs item to be applied to this cell.

See Also:



74
75
76
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 74

def style
  defined?(@style) ? @style : 0
end

#style=(v) ⇒ Integer

Returns The cellXfs item index applied to this cell.

Raises:

  • (ArgumentError)

    Invalid cellXfs id if the value provided is not within cellXfs items range.



292
293
294
295
296
297
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 292

def style=(v)
  Axlsx::validate_unsigned_int(v)
  count = styles.cellXfs.size
  raise ArgumentError, "Invalid cellXfs id" unless v < count
  @style = v
end

#to_xml_string(r_index, c_index, str = '') ⇒ String

Serializes the cell



321
322
323
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 321

def to_xml_string(r_index, c_index, str = '')
  CellSerializer.to_xml_string r_index, c_index, self, str
end

#typeSymbol

Note:

If the value provided cannot be cast into the type specified, type is changed to :string and the following logic is applied. :string to :integer or :float, type conversions always return 0 or 0.0 :string, :integer, or :float to :time conversions always return the original value as a string and set the cells type to :string. No support is currently implemented for parsing time strings.

The cell's data type. Currently only six types are supported, :date, :time, :float, :integer, :string and :boolean. Changing the type for a cell will recast the value into that type. If no type option is specified in the constructor, the type is automatically determed.

Raises:

  • (ArgumentExeption)

    Cell.type must be one of [:date, time, :float, :integer, :string, :boolean]

See Also:

  • #cell_type_from_value


93
94
95
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 93

def type
  defined?(@type) ? @type : :string
end

#type=(v) ⇒ Object

See Also:

  • type


98
99
100
101
102
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 98

def type=(v)
  RestrictionValidator.validate :cell_type, CELL_TYPES, v
  @type = v
  self.value = @value unless !defined?(@value) || @value.nil?
end