1Excel::Writer::XLSX::UtUisleirtyC(o3n)tributed Perl DocuEmxecnetla:t:iWorniter::XLSX::Utility(3)
2
6 Utility - Helper functions for Excel::Writer::XLSX.
7
9 Functions to help with some common tasks when using
10 Excel::Writer::XLSX.
11 These functions mainly relate to dealing with rows and columns in A1
13 notation and to handling dates and times.
14 use Excel::Writer::XLSX::Utility; # Import everything
16 ($row, $col) = xl_cell_to_rowcol( 'C2' ); # (1, 2)
18 $str = xl_rowcol_to_cell( 1, 2 ); # C2
19 $str = xl_col_to_name( 702 ); # AAA
20 $str = xl_inc_col( 'Z1' ); # AA1
21 $str = xl_dec_col( 'AA1' ); # Z1
22 $date = xl_date_list(2002, 1, 1); # 37257
24 $date = xl_parse_date( '11 July 1997' ); # 35622
25 $time = xl_parse_time( '3:21:36 PM' ); # 0.64
26 $date = xl_decode_date_EU( '13 May 2002' ); # 37389
27
29 This module provides a set of functions to help with some common tasks
30 encountered when using the Excel::Writer::XLSX module. The two main
31 categories of function are:
32 Row and column functions: these are used to deal with Excel's A1
34 representation of cells. The functions in this category are:
35 xl_rowcol_to_cell
37 xl_cell_to_rowcol
38 xl_col_to_name
39 xl_range
40 xl_range_formula
41 xl_inc_row
42 xl_dec_row
43 xl_inc_col
44 xl_dec_col
45 Date and Time functions: these are used to convert dates and times to
47 the numeric format used by Excel. The functions in this category are:
48 xl_date_list
50 xl_date_1904
51 xl_parse_time
52 xl_parse_date
53 xl_parse_date_init
54 xl_decode_date_EU
55 xl_decode_date_US
56 All of these functions are exported by default. However, you can use
58 import lists if you wish to limit the functions that are imported:
59 use Excel::Writer::XLSX::Utility; # Import everything
61 use Excel::Writer::XLSX::Utility qw(xl_date_list); # xl_date_list only
62 use Excel::Writer::XLSX::Utility qw(:rowcol); # Row/col functions
63 use Excel::Writer::XLSX::Utility qw(:dates); # Date functions
64
66 Excel::Writer::XLSX supports two forms of notation to designate the
67 position of cells: Row-column notation and A1 notation.
68 Row-column notation uses a zero based index for both row and column
70 while A1 notation uses the standard Excel alphanumeric sequence of
71 column letter and 1-based row. Columns range from A to XFD, i.e. 0 to
72 16,383, rows range from 0 to 1,048,575 in Excel 2007+. For example:
73 (0, 0) # The top left cell in row-column notation.
75 ('A1') # The top left cell in A1 notation.
76 (1999, 29) # Row-column notation.
78 ('AD2000') # The same cell in A1 notation.
79 Row-column notation is useful if you are referring to cells
81 programmatically:
82 for my $i ( 0 .. 9 ) {
84 $worksheet->write( $i, 0, 'Hello' ); # Cells A1 to A10
85 }
86 A1 notation is useful for setting up a worksheet manually and for
88 working with formulas:
89 $worksheet->write( 'H1', 200 );
91 $worksheet->write( 'H2', '=H7+1' );
92 The functions in the following sections can be used for dealing with A1
94 notation, for example:
95 ( $row, $col ) = xl_cell_to_rowcol('C2'); # (1, 2)
97 $str = xl_rowcol_to_cell( 1, 2 ); # C2
98 Cell references in Excel can be either relative or absolute. Absolute
100 references are prefixed by the dollar symbol as shown below:
101 A1 # Column and row are relative
103 $A1 # Column is absolute and row is relative
104 A$1 # Column is relative and row is absolute
105 $A$1 # Column and row are absolute
106 An absolute reference only makes a difference if the cell is copied.
108 Refer to the Excel documentation for further details. All of the
109 following functions support absolute references.
110 xl_rowcol_to_cell($row, $col, $row_absolute, $col_absolute)
112 Parameters: $row: Integer
113 $col: Integer
114 $row_absolute: Boolean (1/0) [optional, default is 0]
115 $col_absolute: Boolean (1/0) [optional, default is 0]
116 Returns: A string in A1 cell notation
118 This function converts a zero based row and column cell reference to a
120 A1 style string:
121 $str = xl_rowcol_to_cell( 0, 0 ); # A1
123 $str = xl_rowcol_to_cell( 0, 1 ); # B1
124 $str = xl_rowcol_to_cell( 1, 0 ); # A2
125 The optional parameters $row_absolute and $col_absolute can be used to
127 indicate if the row or column is absolute:
128 $str = xl_rowcol_to_cell( 0, 0, 0, 1 ); # $A1
130 $str = xl_rowcol_to_cell( 0, 0, 1, 0 ); # A$1
131 $str = xl_rowcol_to_cell( 0, 0, 1, 1 ); # $A$1
132 See above for an explanation of absolute cell references.
134 xl_cell_to_rowcol($string)
136 Parameters: $string String in A1 format
137 Returns: List ($row, $col)
139 This function converts an Excel cell reference in A1 notation to a zero
141 based row and column. The function will also handle Excel's absolute,
142 "$", cell notation.
143 my ( $row, $col ) = xl_cell_to_rowcol('A1'); # (0, 0)
145 my ( $row, $col ) = xl_cell_to_rowcol('B1'); # (0, 1)
146 my ( $row, $col ) = xl_cell_to_rowcol('C2'); # (1, 2)
147 my ( $row, $col ) = xl_cell_to_rowcol('$C2'); # (1, 2)
148 my ( $row, $col ) = xl_cell_to_rowcol('C$2'); # (1, 2)
149 my ( $row, $col ) = xl_cell_to_rowcol('$C$2'); # (1, 2)
150 xl_col_to_name($col, $col_absolute)
152 Parameters: $col: Integer
153 $col_absolute: Boolean (1/0) [optional, default is 0]
154 Returns: A column string name.
156 This function converts a zero based column reference to a string:
158 $str = xl_col_to_name(0); # A
160 $str = xl_col_to_name(1); # B
161 $str = xl_col_to_name(702); # AAA
162 The optional parameter $col_absolute can be used to indicate if the
164 column is absolute:
165 $str = xl_col_to_name( 0, 0 ); # A
167 $str = xl_col_to_name( 0, 1 ); # $A
168 $str = xl_col_to_name( 1, 1 ); # $B
169 xl_range($row_1, $row_2, $col_1, $col_2, $row_abs_1, $row_abs_2,
171 $col_abs_1, $col_abs_2)
172 Parameters: $sheetname String
173 $row_1: Integer
174 $row_2: Integer
175 $col_1: Integer
176 $col_2: Integer
177 $row_abs_1: Boolean (1/0) [optional, default is 0]
178 $row_abs_2: Boolean (1/0) [optional, default is 0]
179 $col_abs_1: Boolean (1/0) [optional, default is 0]
180 $col_abs_2: Boolean (1/0) [optional, default is 0]
181 Returns: A worksheet range formula as a string.
183 This function converts zero based row and column cell references to an
185 A1 style range string:
186 my $str = xl_range( 0, 9, 0, 0 ); # A1:A10
188 my $str = xl_range( 1, 8, 2, 2 ); # C2:C9
189 my $str = xl_range( 0, 3, 0, 4 ); # A1:E4
190 my $str = xl_range( 0, 3, 0, 4, 1 ); # A$1:E4
191 my $str = xl_range( 0, 3, 0, 4, 1, 1 ); # A$1:E$4
192 xl_range_formula($sheetname, $row_1, $row_2, $col_1, $col_2)
194 Parameters: $sheetname String
195 $row_1: Integer
196 $row_2: Integer
197 $col_1: Integer
198 $col_2: Integer
199 Returns: A worksheet range formula as a string.
201 This function converts zero based row and column cell references to an
203 A1 style formula string:
204 my $str = xl_range_formula( 'Sheet1', 0, 9, 0, 0 ); # =Sheet1!$A$1:$A$10
206 my $str = xl_range_formula( 'Sheet2', 6, 65, 1, 1 ); # =Sheet2!$B$7:$B$66
207 my $str = xl_range_formula( 'New data', 1, 8, 2, 2 );# ='New data'!$C$2:$C$9
208 This is useful for setting ranges in Chart objects:
210 $chart->add_series(
212 categories => xl_range_formula( 'Sheet1', 1, 9, 0, 0 ),
213 values => xl_range_formula( 'Sheet1', 1, 9, 1, 1 ),
214 );
215 # Which is the same as:
217 $chart->add_series(
219 categories => '=Sheet1!$A$2:$A$10',
220 values => '=Sheet1!$B$2:$B$10',
221 );
222 xl_inc_row($string)
224 Parameters: $string, a string in A1 format
225 Returns: Incremented string in A1 format
227 This functions takes a cell reference string in A1 notation and
229 increments the row. The function will also handle Excel's absolute,
230 "$", cell notation:
231 my $str = xl_inc_row( 'A1' ); # A2
233 my $str = xl_inc_row( 'B$2' ); # B$3
234 my $str = xl_inc_row( '$C3' ); # $C4
235 my $str = xl_inc_row( '$D$4' ); # $D$5
236 xl_dec_row($string)
238 Parameters: $string, a string in A1 format
239 Returns: Decremented string in A1 format
241 This functions takes a cell reference string in A1 notation and
243 decrements the row. The function will also handle Excel's absolute,
244 "$", cell notation:
245 my $str = xl_dec_row( 'A2' ); # A1
247 my $str = xl_dec_row( 'B$3' ); # B$2
248 my $str = xl_dec_row( '$C4' ); # $C3
249 my $str = xl_dec_row( '$D$5' ); # $D$4
250 xl_inc_col($string)
252 Parameters: $string, a string in A1 format
253 Returns: Incremented string in A1 format
255 This functions takes a cell reference string in A1 notation and
257 increments the column. The function will also handle Excel's absolute,
258 "$", cell notation:
259 my $str = xl_inc_col( 'A1' ); # B1
261 my $str = xl_inc_col( 'Z1' ); # AA1
262 my $str = xl_inc_col( '$B1' ); # $C1
263 my $str = xl_inc_col( '$D$5' ); # $E$5
264 xl_dec_col($string)
266 Parameters: $string, a string in A1 format
267 Returns: Decremented string in A1 format
269 This functions takes a cell reference string in A1 notation and
271 decrements the column. The function will also handle Excel's absolute,
272 "$", cell notation:
273 my $str = xl_dec_col( 'B1' ); # A1
275 my $str = xl_dec_col( 'AA1' ); # Z1
276 my $str = xl_dec_col( '$C1' ); # $B1
277 my $str = xl_dec_col( '$E$5' ); # $D$5
278
280 Dates and times in Excel are represented by real numbers, for example
281 "Jan 1 2001 12:30 AM" is represented by the number 36892.521.
282 The integer part of the number stores the number of days since the
284 epoch and the fractional part stores the percentage of the day in
285 seconds.
286 A date or time in Excel is like any other number. To display the number
288 as a date you must apply a number format to it: Refer to the
289 "set_num_format()" method in the Excel::Writer::XLSX documentation:
290 $date = xl_date_list( 2001, 1, 1, 12, 30 );
292 $format->set_num_format( 'mmm d yyyy hh:mm AM/PM' );
293 $worksheet->write( 'A1', $date, $format ); # Jan 1 2001 12:30 AM
294 The date handling functions below are supplied for historical reasons.
296 In the current version of the module it is easier to just use the
297 "write_date_time()" function to write dates or times. See the DATES AND
298 TIME IN EXCEL section of the main Excel::Writer::XLSX documentation for
299 details.
300 In addition to using the functions below you must install the
302 Date::Manip and Date::Calc modules. See REQUIREMENTS and the individual
303 requirements of each functions.
304 For a "DateTime.pm" solution see the DateTime::Format::Excel module.
306 xl_date_list($years, $months, $days, $hours, $minutes, $seconds)
308 Parameters: $years: Integer
309 $months: Integer [optional, default is 1]
310 $days: Integer [optional, default is 1]
311 $hours: Integer [optional, default is 0]
312 $minutes: Integer [optional, default is 0]
313 $seconds: Float [optional, default is 0]
314 Returns: A number that represents an Excel date
316 or undef for an invalid date.
317 Requires: Date::Calc
319 This function converts an array of data into a number that represents
321 an Excel date. All of the parameters are optional except for $years.
322 $date1 = xl_date_list( 2002, 1, 2 ); # 2 Jan 2002
324 $date2 = xl_date_list( 2002, 1, 2, 12 ); # 2 Jan 2002 12:00 pm
325 $date3 = xl_date_list( 2002, 1, 2, 12, 30 ); # 2 Jan 2002 12:30 pm
326 $date4 = xl_date_list( 2002, 1, 2, 12, 30, 45 ); # 2 Jan 2002 12:30:45 pm
327 This function can be used in conjunction with functions that parse date
329 and time strings. In fact it is used in most of the following
330 functions.
331 xl_parse_time($string)
333 Parameters: $string, a textual representation of a time
334 Returns: A number that represents an Excel time
336 or undef for an invalid time.
337 This function converts a time string into a number that represents an
339 Excel time. The following time formats are valid:
340 hh:mm [AM|PM]
342 hh:mm [AM|PM]
343 hh:mm:ss [AM|PM]
344 hh:mm:ss.ss [AM|PM]
345 The meridian, AM or PM, is optional and case insensitive. A 24 hour
347 time is assumed if the meridian is omitted.
348 $time1 = xl_parse_time( '12:18' );
350 $time2 = xl_parse_time( '12:18:14' );
351 $time3 = xl_parse_time( '12:18:14 AM' );
352 $time4 = xl_parse_time( '1:18:14 AM' );
353 Time in Excel is expressed as a fraction of the day in seconds.
355 Therefore you can calculate an Excel time as follows:
356 $time = ( $hours * 3600 + $minutes * 60 + $seconds ) / ( 24 * 60 * 60 );
358 xl_parse_date($string)
360 Parameters: $string, a textual representation of a date and time
361 Returns: A number that represents an Excel date
363 or undef for an invalid date.
364 Requires: Date::Manip and Date::Calc
366 This function converts a date and time string into a number that
368 represents an Excel date.
369 The parsing is performed using the "ParseDate()" function of the
371 Date::Manip module. Refer to the "Date::Manip" documentation for
372 further information about the date and time formats that can be parsed.
373 In order to use this function you will probably have to initialise some
374 "Date::Manip" variables via the "xl_parse_date_init()" function, see
375 below.
376 xl_parse_date_init( "TZ=GMT", "DateFormat=non-US" );
378 $date1 = xl_parse_date( "11/7/97" );
380 $date2 = xl_parse_date( "Friday 11 July 1997" );
381 $date3 = xl_parse_date( "10:30 AM Friday 11 July 1997" );
382 $date4 = xl_parse_date( "Today" );
383 $date5 = xl_parse_date( "Yesterday" );
384 Note, if you parse a string that represents a time but not a date this
386 function will add the current date. If you want the time without the
387 date you can do something like the following:
388 $time = xl_parse_date( "10:30 AM" );
390 $time -= int( $time );
391 xl_parse_date_init("variable=value", ...)
393 Parameters: A list of Date::Manip variable strings
394 Returns: A list of all the Date::Manip strings
396 Requires: Date::Manip
398 This function is used to initialise variables required by the
400 Date::Manip module. You should call this function before calling
401 "xl_parse_date()". It need only be called once.
402 This function is a thin wrapper for the "Date::Manip::Date_Init()"
404 function. You can use "Date_Init()" directly if you wish. Refer to the
405 "Date::Manip" documentation for further information.
406 xl_parse_date_init( "TZ=MST", "DateFormat=US" );
408 $date1 = xl_parse_date( "11/7/97" ); # November 7th 1997
409 xl_parse_date_init( "TZ=GMT", "DateFormat=non-US" );
411 $date1 = xl_parse_date( "11/7/97" ); # July 11th 1997
412 xl_decode_date_EU($string)
414 Parameters: $string, a textual representation of a date and time
415 Returns: A number that represents an Excel date
417 or undef for an invalid date.
418 Requires: Date::Calc
420 This function converts a date and time string into a number that
422 represents an Excel date.
423 The date parsing is performed using the "Decode_Date_EU()" function of
425 the Date::Calc module. Refer to the "Date::Calc" documentation for
426 further information about the date formats that can be parsed. Also
427 note the following from the "Date::Calc" documentation:
428 "If the year is given as one or two digits only (i.e., if the year is
430 less than 100), it is mapped to the window 1970 -2069 as follows:"
431 0 <= $year < 70 ==> $year += 2000;
433 70 <= $year < 100 ==> $year += 1900;
434 The time portion of the string is parsed using the "xl_parse_time()"
436 function described above.
437 Note: the EU in the function name means that a European date format is
439 assumed if it is not clear from the string. See the first example
440 below.
441 $date1 = xl_decode_date_EU( "11/7/97" ); #11 July 1997
443 $date2 = xl_decode_date_EU( "Sat 12 Sept 1998" );
444 $date3 = xl_decode_date_EU( "4:30 AM Sat 12 Sept 1998" );
445 xl_decode_date_US($string)
447 Parameters: $string, a textual representation of a date and time
448 Returns: A number that represents an Excel date
450 or undef for an invalid date.
451 Requires: Date::Calc
453 This function converts a date and time string into a number that
455 represents an Excel date.
456 The date parsing is performed using the "Decode_Date_US()" function of
458 the Date::Calc module. Refer to the "Date::Calc" documentation for
459 further information about the date formats that can be parsed. Also
460 note the following from the "Date::Calc" documentation:
461 "If the year is given as one or two digits only (i.e., if the year is
463 less than 100), it is mapped to the window 1970 -2069 as follows:"
464 0 <= $year < 70 ==> $year += 2000;
466 70 <= $year < 100 ==> $year += 1900;
467 The time portion of the string is parsed using the "xl_parse_time()"
469 function described above.
470 Note: the US in the function name means that an American date format is
472 assumed if it is not clear from the string. See the first example
473 below.
474 $date1 = xl_decode_date_US( "11/7/97" ); # 7 November 1997
476 $date2 = xl_decode_date_US( "Sept 12 Saturday 1998" );
477 $date3 = xl_decode_date_US( "4:30 AM Sept 12 Sat 1998" );
478 xl_date_1904($date)
480 Parameters: $date, an Excel date with a 1900 epoch
481 Returns: an Excel date with a 1904 epoch or zero if
483 the $date is before 1904
484 This function converts an Excel date based on the 1900 epoch into a
486 date based on the 1904 epoch.
487 $date1 = xl_date_list( 2002, 1, 13 ); # 13 Jan 2002, 1900 epoch
489 $date2 = xl_date_1904( $date1 ); # 13 Jan 2002, 1904 epoch
490 See also the "set_1904()" workbook method in the Excel::Writer::XLSX
492 documentation.
493
495 The date and time functions require functions from the Date::Manip and
496 Date::Calc modules. The required functions are "autoused" from these
497 modules so that you do not have to install them unless you wish to use
498 the date and time routines. Therefore it is possible to use the row and
499 column functions without having "Date::Manip" and "Date::Calc"
500 installed.
501 For more information about "autousing" refer to the documentation on
503 the "autouse" pragma.
504
506 When using the autoused functions from "Date::Manip" and "Date::Calc"
507 on Perl 5.6.0 with "-w" you will get a warning like this:
508 "Subroutine xxx redefined ..."
510 The current workaround for this is to put "use warnings;" near the
512 beginning of your program.
513
515 John McNamara jmcnamara@cpan.org
516
518 Copyright MM-MMXVIII, John McNamara.
519 All Rights Reserved. This module is free software. It may be used,
521 redistributed and/or modified under the same terms as Perl itself.
522perl v5.28.0 2018-04-14 Excel::Writer::XLSX::Utility(3)