Class: Workbook::Row

Inherits:
Array
  • Object
show all
Includes:
Modules::Cache
Defined in:
lib/workbook/row.rb

Instance Attribute Summary collapse

Attributes included from Modules::Cache

#debug_cache

Instance Method Summary collapse

Methods included from Modules::Cache

#cache_valid_from, #caching_enabled?, #fetch_cache, #invalidate_cache!, #valid_cache_key?

Constructor Details

#initialize(cells = [], table = nil, options = {}) ⇒ Row

Initialize a new row

Parameters:

  • cells (Workbook::Row, Array<Workbook::Cell>, Array) (defaults to: [])

    list of cells to initialize the row with, default is empty

  • table (Workbook::Table) (defaults to: nil)

    a row normally belongs to a table, reference it here

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

    Supprted options: parse_cells_on_batch_creation (parse cell values during row-initalization, default: false), cell_parse_options (default {}, see Workbook::Modules::TypeParser)



16
17
18
19
20
21
22
23
24
25
26
27
28
# File 'lib/workbook/row.rb', line 16

def initialize cells=[], table=nil, options={}
  options=options ? {:parse_cells_on_batch_creation=>false,:cell_parse_options=>{},:clone_cells=>false}.merge(options) : {}
  cells = [] if cells==nil
  self.table= table
  cells.each do |c|
    c = c.clone if options[:clone_cells]
    unless c.is_a? Workbook::Cell
      c = Workbook::Cell.new(c)
      c.parse!(options[:cell_parse_options]) if options[:parse_cells_on_batch_creation]
    end
    push c
  end
end

Instance Attribute Details

#formatObject

Returns the value of attribute format



9
10
11
# File 'lib/workbook/row.rb', line 9

def format
  @format
end

#placeholderObject

The placeholder attribute is used in compares (corresponds to newly created or removed lines (depending which side you're on)



8
9
10
# File 'lib/workbook/row.rb', line 8

def placeholder
  @placeholder
end

Instance Method Details

#+(row) ⇒ Workbook::Row

plus

Parameters:

Returns:



79
80
81
82
83
# File 'lib/workbook/row.rb', line 79

def +(row)
  rv = super(row)
  rv = Workbook::Row.new(rv) unless rv.class == Workbook::Row
  return rv
end

#<<(cell) ⇒ Object

Add cell

Parameters:

  • cell (Workbook::Cell, Numeric, String, Time, Date, TrueClass, FalseClass, NilClass)

    or value to add



71
72
73
74
# File 'lib/workbook/row.rb', line 71

def <<(cell)
  cell = Workbook::Cell.new(cell) unless cell.class == Workbook::Cell
  super(cell)
end

#<=>(other) ⇒ Workbook::Row

Compares one row wiht another

Parameters:

Returns:



236
237
238
239
240
241
# File 'lib/workbook/row.rb', line 236

def <=> other
  a = self.header? ? 0 : 1
  b = other.header? ? 0 : 1
  return (a <=> b) if (a==0 or b==0)
  compare_without_header other
end

#[](index_or_hash) ⇒ Workbook::Cell?

Overrides normal Array's []-function with support for symbols that identify a column based on the header-values

Examples:

Lookup using fixnum or header value encoded as symbol

row[1] #=> <Cell value="a">
row[:a] #=> <Cell value="a">

Parameters:

  • index_or_hash (Fixnum, Symbol, String)

    that identifies the column (strings are converted to symbols)

Returns:



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
# File 'lib/workbook/row.rb', line 102

def [](index_or_hash)
  if index_or_hash.is_a? Symbol
    rv = nil
    begin
      rv = to_hash[index_or_hash]
    rescue NoMethodError
    end
    return rv
  elsif index_or_hash.is_a? String
    symbolized = Workbook::Cell.new(index_or_hash).to_sym
    self[symbolized]
  else
    if index_or_hash
      return to_a[index_or_hash]
    end
  end
end

#[]=(index_or_hash, value) ⇒ Workbook::Cell?

Overrides normal Array's []=-function with support for symbols that identify a column based on the header-values

Examples:

Lookup using fixnum or header value encoded as symbol (strings are converted to symbols)

row[1] #=> <Cell value="a">
row[:a] #=> <Cell value="a">

Parameters:

  • index_or_hash (Fixnum, Symbol, String)

    that identifies the column

  • value (String, Fixnum, NilClass, Date, DateTime, Time, Float)

Returns:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
# File 'lib/workbook/row.rb', line 129

def []= (index_or_hash, value)
  index = index_or_hash
  if index_or_hash.is_a? Symbol
    index = table_header_keys.index(index_or_hash)
  elsif index_or_hash.is_a? String
    symbolized = Workbook::Cell.new(index_or_hash).to_sym
    index = table_header_keys.index(symbolized)
  end

  value_celled = Workbook::Cell.new
  if value.is_a? Workbook::Cell
    value_celled = value
  else
    current_cell = self[index]
    if current_cell.is_a? Workbook::Cell
      value_celled = current_cell
    end
    value_celled.value=(value)
  end
  super(index,value_celled)
end

#cloneWorkbook::Row

clone the row with together with the cells

Returns:



259
260
261
# File 'lib/workbook/row.rb', line 259

def clone
  Workbook::Row.new(self, nil, {:clone_cells=>true})
end

#compactObject

Compact detaches the row from the table



251
252
253
254
# File 'lib/workbook/row.rb', line 251

def compact
  r = self.clone
  r = r.collect{|c| c unless c.nil?}.compact
end

#compare_without_headerObject



7
# File 'lib/workbook/row.rb', line 7

alias_method :compare_without_header, :<=>

#concat(row) ⇒ self

concat

Parameters:

Returns:

  • (self)

    self



88
89
90
91
# File 'lib/workbook/row.rb', line 88

def concat(row)
  row = Workbook::Row.new(row) unless row.class == Workbook::Row
  super(row)
end

#find_cells_by_background_color(color = :any, options = {}) ⇒ Array<Symbol>, Workbook::Row<Workbook::Cell>

Returns an array of cells allows you to find cells by a given color, normally a string containing a hex

Parameters:

  • color (String) (defaults to: :any)

    a CSS-style hex-string

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

    Option :hash_keys (default true) returns row as an array of symbols

Returns:



156
157
158
159
160
161
# File 'lib/workbook/row.rb', line 156

def find_cells_by_background_color color=:any, options={}
  options = {:hash_keys=>true}.merge(options)
  cells = self.collect {|c| c if c.format.has_background_color?(color) }.compact
  r = Row.new cells
  options[:hash_keys] ? r.to_symbols : r
end

#first?Boolean, NilClass

Is this the first row in the table

Returns:

  • (Boolean, NilClass)

    returns nil if it doesn't belong to a table, false when it isn't the first row of a table and true when it is.



173
174
175
# File 'lib/workbook/row.rb', line 173

def first?
  table != nil and self.object_id == table.first.object_id
end

#header?Boolean

Returns true when the row belongs to a table and it is the header row (typically the first row)

Returns:

  • (Boolean)


166
167
168
# File 'lib/workbook/row.rb', line 166

def header?
  table != nil and self.object_id == table_header.object_id
end

#keyWorkbook::Cell

The first cell of the row is considered to be the key

Returns:



246
247
248
# File 'lib/workbook/row.rb', line 246

def key
  first
end

#no_values?Boolean

Returns true when all the cells in the row have values whose to_s value equals an empty string

Returns:

  • (Boolean)


180
181
182
# File 'lib/workbook/row.rb', line 180

def no_values?
  all? {|c| c.value.to_s == ''}
end

#placeholder?Boolean

An internal function used in diffs

Returns:

  • (Boolean)

    returns true when this row is not an actual row, but a placeholder row to 'compare' against



33
34
35
# File 'lib/workbook/row.rb', line 33

def placeholder?
  placeholder ? true : false
end

#push(cell) ⇒ Object

Add cell

Parameters:

  • cell (Workbook::Cell, Numeric, String, Time, Date, TrueClass, FalseClass, NilClass)

    or value to add



64
65
66
67
# File 'lib/workbook/row.rb', line 64

def push(cell)
  cell = Workbook::Cell.new(cell) unless cell.class == Workbook::Cell
  super(cell)
end

#set_table(t) ⇒ Object

Set reference to the table this row belongs to without adding the row to the table

Parameters:



47
48
49
# File 'lib/workbook/row.rb', line 47

def set_table(t)
  @table = t
end

#tableWorkbook::Table

Returns the table this row belongs to

Returns:



40
41
42
# File 'lib/workbook/row.rb', line 40

def table
  @table
end

#table=(t) ⇒ Object

Set reference to the table this row belongs to and add the row to this table

Parameters:

Raises:

  • (ArgumentError)


54
55
56
57
58
59
60
# File 'lib/workbook/row.rb', line 54

def table= t
  raise ArgumentError, "table should be a Workbook::Table (you passed a #{t.class})" unless t.is_a?(Workbook::Table) or t == nil
  if t
    @table = t
    table.push(self) #unless table.index(self) and self.placeholder?
  end
end

#table_headerObject



198
199
200
# File 'lib/workbook/row.rb', line 198

def table_header
  table.header
end

#table_header_keysObject



202
203
204
# File 'lib/workbook/row.rb', line 202

def table_header_keys
  table_header.to_symbols
end

#to_aArray<Workbook::Cell>

Converts the row to an array of Workbook::Cell's

Returns:



194
195
196
# File 'lib/workbook/row.rb', line 194

def to_a
  self.collect{|c| c}
end

#to_hashHash

Returns a hash representation of this row

Returns:

  • (Hash)


209
210
211
212
213
214
215
# File 'lib/workbook/row.rb', line 209

def to_hash
  keys = table_header_keys
  values = self
  hash = {}
  keys.each_with_index {|k,i| hash[k]=values[i]}
  return hash
end

#to_hash_with_valuesHash

Returns a hash representation of this row

it differs from #to_hash as it doesn't contain the Workbook's Workbook::Cell-objects, but the actual values contained in these cells

Returns:

  • (Hash)


224
225
226
227
228
229
230
# File 'lib/workbook/row.rb', line 224

def to_hash_with_values
  keys = table_header_keys
  values = self
  @hash_with_values = {}
  keys.each_with_index {|k,i| v=values[i]; v=v.value if v; @hash_with_values[k]=v}
  return @hash_with_values
end

#to_symbolsArray<Symbol>

Converts a row to an array of symbol representations of the row content, see also: Workbook::Cell#to_sym

Returns:

  • (Array<Symbol>)

    returns row as an array of symbols



186
187
188
189
190
# File 'lib/workbook/row.rb', line 186

def to_symbols
  fetch_cache(:to_symbols){
    collect{|c| c.to_sym}
  }
end

#trim(desired_length = nil) ⇒ Workbook::Row

remove all the trailing nil-cells (returning a trimmed clone)

Parameters:

  • desired_length (Integer) (defaults to: nil)

    of the new row

Returns:



267
268
269
# File 'lib/workbook/row.rb', line 267

def trim(desired_length=nil)
  self.clone.trim!(desired_length)
end

#trim!(desired_length = nil) ⇒ Workbook::Row

remove all the trailing nil-cells (returning a trimmed self)

Parameters:

  • desired_length (Integer) (defaults to: nil)

    of the new row

Returns:



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
# File 'lib/workbook/row.rb', line 275

def trim!(desired_length=nil)
  self_count = self.count-1
  self.count.times do |index|
    index = self_count - index
    if desired_length and index < desired_length
      break
    elsif desired_length and index >= desired_length
      self.delete_at(index)
    elsif self[index].nil?
      self.delete_at(index)
    else
      break
    end
  end
  (desired_length - self.count).times{|a| self << (Workbook::Cell.new(nil))} if desired_length and (desired_length - self.count) > 0
  self
end