Class: Axlsx::Cell

Inherits:
Object
  • Object
show all
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.

Examples:

Manually creating and manipulating Cell objects

ws = Workbook.new.add_worksheet
# This is the simple, and recommended way to create cells. Data types will automatically be determined for you.
ws.add_row :values => [1,"fish",Time.now]

# but you can also do this
r = ws.add_row
r.add_cell 1

# or even this
r = ws.add_row
c = Cell.new row, 1, :value=>integer

# cells can also be accessed via Row#cells. The example here changes the cells type, which will automatically updated the value from 1 to 1.0
r.cells.last.type = :float

See Also:

Constant Summary collapse

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']

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of Cell.

Parameters:

  • row (Row) —

    The row this cell belongs to.

  • value (Any) (defaults to: "") —

    The value associated with this cell.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

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

  • scheme (Symbol) —

    must be one of :none, major, :minor



205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 205

def initialize(row, value="", options={})
  self.row=row
  @font_name = @charset = @family = @b = @i = @strike = @outline = @shadow = nil
  @condense = @u = @vertAlign = @sz = @color = @scheme = @extend = @ssti = nil
  @styles = row.worksheet.workbook.styles
  @row.cells << self
  options.each do |o|
    self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
  end
  @style ||= 0
  @type ||= cell_type_from_value(value)
  @value = cast_value(value)
end

Instance Attribute Details

#b ⇒ Boolean

The inline bold property for the cell

Returns:

  • (Boolean) 


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

def b
  @b
end

#charset ⇒ String

The inline charset property for the cell

Returns:

  • (String) 


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

def charset
  @charset
end

#color ⇒ Color

The inline color property for the cell

Returns:



153
154
155
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 153

def color
  @color
end

#condense ⇒ Boolean

The inline condense property for the cell

Returns:

  • (Boolean) 


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

def condense
  @condense
end

#extend ⇒ Boolean

The inline extend property for the cell

Returns:

  • (Boolean) 


141
142
143
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 141

def extend
  @extend
end

#family ⇒ String

The inline family property for the cell

Returns:

  • (String) 


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

def family
  @family
end

#font_name ⇒ String

The inline font_name property for the cell

Returns:

  • (String) 


87
88
89
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 87

def font_name
  @font_name
end

#i ⇒ Boolean

The inline italic property for the cell

Returns:

  • (Boolean) 


111
112
113
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 111

def i
  @i
end

#outline ⇒ Boolean

The inline outline property for the cell

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 123

def outline
  @outline
end

#row ⇒ Row

The row this cell belongs to.

Returns:



46
47
48
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 46

def row
  @row
end

#scheme ⇒ Symbol

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

Returns:

  • (Symbol) 


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

def scheme
  @scheme
end

#shadow ⇒ Boolean

The inline shadow property for the cell

Returns:

  • (Boolean) 


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

def shadow
  @shadow
end

#ssti ⇒ Integer

The Shared Strings Table index for this cell

Returns:

  • (Integer) 


221
222
223
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 221

def ssti
  @ssti
end

#strike ⇒ Boolean

The inline strike property for the cell

Returns:

  • (Boolean) 


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

def strike
  @strike
end

#style ⇒ Integer

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

Returns:

  • (Integer)

See Also:



42
43
44
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 42

def style
  @style
end

#sz ⇒ Boolean

The inline sz property for the cell

Returns:

  • (Boolean) 


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

def sz
  @sz
end

#type ⇒ Symbol

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.

Returns:

  • (Symbol) —

    The type of data this cell’s value is cast to.

Raises:

  • (ArgumentExeption) —

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

See Also:

  • #cell_type_from_value


59
60
61
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 59

def type
  @type
end

#u ⇒ Boolean

The inline underline property for the cell

Returns:

  • (Boolean) 


147
148
149
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 147

def u
  @u
end

#value ⇒ String, ...

The value of this cell.

Returns:

  • (String, Integer, Float, Time) —

    casted value based on cell’s type attribute.



70
71
72
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 70

def value
  @value
end

#vertAlign ⇒ Symbol

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

Returns:

  • (Symbol) 


169
170
171
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 169

def vertAlign
  @vertAlign
end

Instance Method Details

#index ⇒ Integer

Returns The index of the cell in the containing row.

Returns:

  • (Integer) —

    The index of the cell in the containing row.



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

def index
  @row.cells.index(self)
end

#is_text_run? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def is_text_run?
  @is_text_run ||= false
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

Parameters:

  • target (Cell, String) —

    The last cell, or str ref for the cell in the merge range

See Also:

  • Axlsx::Cell.worksheetworksheet.merge_cells


269
270
271
272
273
274
275
276
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 269

def merge(target)
  range_end = if target.is_a?(String)
                target
              elsif(target.is_a?(Cell))
                target.r
              end
  self.row.worksheet.merge_cells "#{self.r}:#{range_end}" unless range_end.nil?
end

#pos ⇒ Array

Returns of x/y coordinates in the cheet for this cell.

Returns:

  • (Array) —

    of x/y coordinates in the cheet for this cell.



262
263
264
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 262

def pos
  [index, row.index]
end

#r ⇒ String

Note:

this will be discontinued in 1.1.0 - prefer Axlsx.cell_r

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

Examples:

Relative Cell Reference

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

Returns:

  • (String) —

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



241
242
243
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 241

def r
  "#{Axlsx::col_ref(index)}#{@row.index+1}"
end

#r_abs ⇒ String

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

Examples:

Absolute Cell Reference

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

Returns:

  • (String) —

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



248
249
250
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 248

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

#run_xml_string(str = '') ⇒ String

builds an xml text run based on this cells attributes.

Parameters:

  • str (String) (defaults to: '') —

    The string instance this run will be concated to.

Returns:

  • (String) 


281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 281

def run_xml_string(str = '')
  if is_text_run?
    data = self.instance_values.reject{|key, value| value == nil }
    keys = data.keys & INLINE_STYLES
    keys.delete ['value', 'type']
    str << "<r><rPr>"
    keys.each do |key|
      case key
      when 'font_name'
        str << "<rFont val='"<< @font_name << "'/>"
      when 'color'
        str << data[key].to_xml_string
      else
        "<" << key.to_s << " val='" << data[key].to_s << "'/>"
      end
    end
    str << "</rPr>" << "<t>" << value.to_s << "</t></r>"
  else
    str << "<t>" << value.to_s << "</t>"
  end
  str
end

#shareable_hash ⇒ Object

equality comparison to test value, type and inline style attributes this is how we work out if the cell needs to be added or already exists in the shared strings table



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

def shareable_hash
  self_hash = {}
  INLINE_STYLES.each { |style| self_hash[style] = self.instance_variable_get("@" + style) }
  self_hash['color'] = self_hash['color'].instance_values if self_hash['color']
  self_hash
end

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

Serializes the cell

Parameters:

  • r_index (Integer) —

    The row index for the cell

  • c_index (Integer) —

    The cell index in the row.

  • str (String) (defaults to: '') —

    The string index the cell content will be appended to. Defaults to empty string.

Returns:

  • (String) —

    xml text for the cell



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/axlsx/workbook/worksheet/cell.rb', line 309

def to_xml_string(r_index, c_index, str = '')
  return str if @value.nil?
  str << '<c r="' << Axlsx::cell_r(c_index, r_index) << '" s="' << @style.to_s << '" '
  case @type
  when :string
    #parse formula
    if @value.start_with?('=')
      str  << 't="str"><f>' << @value.to_s.gsub('=', '') << '</f>'
    else
      #parse shared
      if @ssti
        str << 't="s"><v>' << @ssti.to_s << '</v>'
      else
        str << 't="inlineStr"><is>' << run_xml_string << '</is>'
      end
    end
  when :date
    # TODO: See if this is subject to the same restriction as Time below
    str << '><v>' << DateTimeConverter::date_to_serial(@value).to_s << '</v>'
  when :time
    str << '><v>' << DateTimeConverter::time_to_serial(@value).to_s << '</v>'
  when :boolean
    str << 't="b"><v>' << @value.to_s << '</v>'
  else
    str << '><v>' << @value.to_s << '</v>'
  end
  str << '</c>'
end