--- name: "Spreadsheet::ParseExcel::Cell" section: "3pm" platform: "linux" package: "libspreadsheet-parseexcel-perl" version: "0.6600-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Spreadsheet::ParseExcel::Cell" --- # Spreadsheet::ParseExcel::Cell(3pm) A class for Cell data and formatting. ## NAME Spreadsheet::ParseExcel::Cell - A class for Cell data and formatting. ## SYNOPSIS See the documentation for Spreadsheet::ParseExcel. ## DESCRIPTION This module is used in conjunction with Spreadsheet::ParseExcel. See the documentation for Spreadsheet::ParseExcel. ## Methods The following Cell methods are available: ``` $cell->value() $cell->unformatted() $cell->get_format() $cell->type() $cell->encoding() $cell->is_merged() $cell->get_rich_text() $cell->get_hyperlink() ``` ### value() The `"value()"` method returns the formatted value of the cell. ``` my $value = $cell->value(); ``` Formatted in this sense refers to the numeric format of the cell value. For example a number such as 40177 might be formatted as 40,117, 40117.000 or even as the date 2009/12/30. If the cell doesn't contain a numeric format then the formatted and unformatted cell values are the same, see the `"unformatted()"` method below. For a defined `$cell` the `"value()"` method will always return a value. In the case of a cell with formatting but no numeric or string contents the method will return the empty string `''`. ### unformatted() The `"unformatted()"` method returns the unformatted value of the cell. ``` my $unformatted = $cell->unformatted(); ``` Returns the cell value without a numeric format. See the `"value()"` method above. ### get\_format() The `"get_format()"` method returns the Spreadsheet::ParseExcel::Format object for the cell. ``` my $format = $cell->get_format(); ``` If a user defined format hasn't been applied to the cell then the default cell format is returned. ### type() The `"type()"` method returns the type of cell such as Text, Numeric or Date. If the type was detected as Numeric, and the Cell Format matches `"m{^[dmy][-\\/dmy]*$}i"`, it will be treated as a Date type. ``` my $type = $cell->type(); ``` See also "Dates and Time in Excel". ### encoding() The `"encoding()"` method returns the character encoding of the cell. ``` my $encoding = $cell->encoding(); ``` This method is only of interest to developers. In general Spreadsheet::ParseExcel will return all character strings in UTF-8 regardless of the encoding used by Excel. The `"encoding()"` method returns one of the following values: - • 0: Unknown format. This shouldn't happen. In the default case the format should be 1. - • 1: 8bit ASCII or single byte UTF-16. This indicates that the characters are encoded in a single byte. In Excel 95 and earlier This usually meant ASCII or an international variant. In Excel 97 it refers to a compressed UTF-16 character string where all of the high order bytes are 0 and are omitted to save space. - • 2: UTF-16BE. - • 3: Native encoding. In Excel 95 and earlier this encoding was used to represent multi-byte character encodings such as SJIS. ### is\_merged() The `"is_merged()"` method returns true if the cell is merged. ``` my $is_merged = $cell->is_merged(); ``` Returns `"undef"` if the property isn't set. ### get\_rich\_text() The `"get_rich_text()"` method returns an array ref of font information about each string block in a "rich", i.e. multi-format, string. ``` my $rich_text = $cell->get_rich_text(); ``` The return value is an arrayref of arrayrefs in the form: ``` [ [ $start_position, $font_object ], ..., ] ``` Returns undef if the property isn't set. ### get\_hyperlink() If a cell contains a hyperlink, the `"get_hyperlink()"` method returns an array ref of information about it. A cell can contain at most one hyperlink. If it does, it contains no other value. Otherwise, it returns undef; The array contains: - • 0: Description (what's displayed); undef if not present - • 1: Link, converted to an appropriate URL - Note: Relative links are based on the input file. `%REL`% is used if the input file is unknown (e.g. a file handle or scalar) - • 2: Target - target frame (or undef if none) ## Dates and Time in Excel Dates and times in Excel are represented by real numbers, for example "Jan 1 2001 12:30 PM" is represented by the number 36892.521. The integer part of the number stores the number of days since the epoch and the fractional part stores the percentage of the day. A date or time in Excel is just like any other number. The way in which it is displayed is controlled by the number format: ``` Number format $cell->value() $cell->unformatted() ============= ============== ============== 'dd/mm/yy' '28/02/08' 39506.5 'mm/dd/yy' '02/28/08' 39506.5 'd-m-yyyy' '28-2-2008' 39506.5 'dd/mm/yy hh:mm' '28/02/08 12:00' 39506.5 'd mmm yyyy' '28 Feb 2008' 39506.5 'mmm d yyyy hh:mm AM/PM' 'Feb 28 2008 12:00 PM' 39506.5 ``` The Spreadsheet::ParseExcel::Utility module contains a function called `"ExcelLocaltime"` which will convert between an unformatted Excel date/time number and a `"localtime()"` like array. For date conversions using the CPAN `"DateTime"` framework see DateTime::Format::Excel http://search.cpan.org/search?dist=DateTime-Format-Excel ## AUTHOR Current maintainer 0.60+: Douglas Wilson dougw@cpan.org Maintainer 0.40-0.59: John McNamara jmcnamara@cpan.org Maintainer 0.27-0.33: Gabor Szabo szabgab@cpan.org Original author: Kawai Takanori kwitknr@cpan.org ## COPYRIGHT Copyright (c) 2014 Douglas Wilson Copyright (c) 2009-2013 John McNamara Copyright (c) 2006-2008 Gabor Szabo Copyright (c) 2000-2006 Kawai Takanori All rights reserved. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.