Module: RubyExcel::Address

Included in:
Data, Element, Section, Sheet
Defined in:
lib/rubyexcel/address.rb

Overview

Provides address translation methods to RubyExcel’s classes

Instance Method Summary collapse

Instance Method Details

#address_to_col_index(address) ⇒ Fixnum

Translates an address to a column index

Parameters:

  • address (String) —

    the address to translate

Returns:

  • (Fixnum) —

    the column index



16
17
18
 
# File 'lib/rubyexcel/address.rb', line 16

def address_to_col_index( address )
  col_index( column_id( address ) )
end

#address_to_indices(address) ⇒ Array<Fixnum>

Translates an address to indices

Parameters:

  • address (String) —

    the address to translate

Returns:

  • (Array<Fixnum>) —

    row index, column index



27
28
29
 
# File 'lib/rubyexcel/address.rb', line 27

def address_to_indices( address )
  [ row_id( address ), address_to_col_index( address ) ]
end

#col_index(letter) ⇒ Fixnum

Translates a column id to an index

Parameters:

  • letter (String) —

    the column id to translate

Returns:

  • (Fixnum) —

    the corresponding index



38
39
40
41
42
43
 
# File 'lib/rubyexcel/address.rb', line 38

def col_index( letter )
  return letter if letter.is_a? Fixnum
  letter !~ /[^A-Z]/ && [1,2,3].include?( letter.length ) or fail ArgumentError, "Invalid column reference: #{ letter }"
  idx, a = 1, 'A'
  loop { return idx if a == letter; idx+=1; a.next! }
end

#col_letter(index) ⇒ String

Translates an index to a column letter

Parameters:

  • index (Fixnum) —

    the index to translate

Returns:

  • (String) —

    the column letter



52
53
54
55
56
 
# File 'lib/rubyexcel/address.rb', line 52

def col_letter( index )
  return index if index.is_a? String
  index > 0 or fail ArgumentError, 'Indexing is 1-based'
  a = 'A'; ( index - 1 ).times { a.next! }; a
end

#column_id(address) ⇒ String

Translates an address to a column id

Parameters:

  • address (String) —

    the address to translate

Returns:

  • (String) —

    the column id



65
66
67
 
# File 'lib/rubyexcel/address.rb', line 65

def column_id( address )
  address[/[A-Z]+/]
end

#expand(address) ⇒ Array<String>

Expands an address to all contained addresses

Parameters:

  • address (String) —

    the address to translate

Returns:

  • (Array<String>) —

    all addresses included within the given address



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/rubyexcel/address.rb', line 76

def expand( address )
  return [[address]] unless address.include? ':'
  
  #Extract the relevant boundaries
  case address
  
  # Row
  when /\A(\d+):(\d+)\z/
  
    start_col, end_col, start_row, end_row = [ 'A', col_letter( sheet.maxcol ) ] + [ $1.to_i, $2.to_i ].sort
    
  # Column
  when /\A([A-Z]+):([A-Z]+)\z/
  
    start_col, end_col, start_row, end_row = [ $1, $2 ].sort + [ 1, sheet.maxrow ]
    
  # Range
  when /([A-Z]+)(\d+):([A-Z]+)(\d+)/
  
    start_col, end_col, start_row, end_row = [ $1, $3 ].sort + [ $2.to_i, $4.to_i ].sort
    
  # Invalid
  else
    fail ArgumentError, 'Invalid address: ' + address
  end
  
  # Return the array of addresses
  ( start_row..end_row ).map { |r| ( start_col..end_col ).map { |c| c + r.to_s } } 
  
end

#indices_to_address(row_idx, column_idx) ⇒ String

Translates indices to an address

Parameters:

  • row_idx (Fixnum) —

    the row index

  • column_idx (Fixnum) —

    the column index

Returns:

  • (String) —

    the corresponding address



115
116
117
118
 
# File 'lib/rubyexcel/address.rb', line 115

def indices_to_address( row_idx, column_idx )
  [ row_idx, column_idx ].all? { |a| a.is_a?( Fixnum ) } or fail ArgumentError, 'Input must be Fixnum'
  col_letter( column_idx ) + row_idx.to_s
end

#multi_array?(obj) ⇒ Boolean

Checks whether an object is a multidimensional Array

Parameters:

  • obj (Object) —

    the object to test

Returns:

  • (Boolean) —

    whether the object is a multidimensional Array



127
128
129
 
# File 'lib/rubyexcel/address.rb', line 127

def multi_array?( obj )
  obj.all? { |el| el.is_a?( Array ) } && obj.is_a?( Array ) rescue false
end

#offset(address, row, col) ⇒ String

Offsets an address by row and column

Parameters:

  • address (String) —

    the address to offset

  • row (Fixnum) —

    the number of rows to offset by

  • col (Fixnum) —

    the number of columns to offset by

Returns:

  • (String) —

    the new address



140
141
142
 
# File 'lib/rubyexcel/address.rb', line 140

def offset(address, row, col)
  ( col_letter( address_to_col_index( address ) + col ) ) + ( row_id( address ) + row ).to_s
end

#row_id(address) ⇒ Fixnum

Translates an address to a row id

Parameters:

  • address (String) —

    the address to translate

Returns:

  • (Fixnum) —

    the row id



165
166
167
 
# File 'lib/rubyexcel/address.rb', line 165

def row_id( address )
  address[/\d+/].to_i
end

#to_range_address(obj1, obj2) ⇒ String

Translates two objects to a range address

Parameters:

Returns:

  • (String) —

    the new address



152
153
154
155
156
 
# File 'lib/rubyexcel/address.rb', line 152

def to_range_address( obj1, obj2 )
  addr = obj1.respond_to?( :address ) ? obj1.address : obj1.to_s
  addr << ':' + ( obj2.respond_to?( :address ) ? obj2.address : obj2.to_s ) if obj2
  addr
end