package Spreadsheet::ParseExcel::Cell;
###############################################################################
#
# Spreadsheet::ParseExcel::Cell - A class for Cell data and formatting.
#
# Used in conjunction with Spreadsheet::ParseExcel.
#
# Copyright (c) 2014 Douglas Wilson
# Copyright (c) 2009-2013 John McNamara
# Copyright (c) 2006-2008 Gabor Szabo
# Copyright (c) 2000-2006 Kawai Takanori
#
# perltidy with standard settings.
#
# Documentation after __END__
#
use strict;
use warnings;
our $VERSION = '0.64';
###############################################################################
#
# new()
#
# Constructor.
#
sub new {
my ( $package, %properties ) = @_;
my $self = \%properties;
bless $self, $package;
}
###############################################################################
#
# value()
#
# Returns the formatted value of the cell.
#
sub value {
my $self = shift;
return $self->{_Value};
}
###############################################################################
#
# unformatted()
#
# Returns the unformatted value of the cell.
#
sub unformatted {
my $self = shift;
return $self->{Val};
}
###############################################################################
#
# get_format()
#
# Returns the Format object for the cell.
#
sub get_format {
my $self = shift;
return $self->{Format};
}
###############################################################################
#
# type()
#
# Returns the type of cell such as Text, Numeric or Date.
#
sub type {
my $self = shift;
return $self->{Type};
}
###############################################################################
#
# encoding()
#
# Returns the character encoding of the cell.
#
sub encoding {
my $self = shift;
if ( !defined $self->{Code} ) {
return 1;
}
elsif ( $self->{Code} eq 'ucs2' ) {
return 2;
}
elsif ( $self->{Code} eq '_native_' ) {
return 3;
}
else {
return 0;
}
return $self->{Code};
}
###############################################################################
#
# is_merged()
#
# Returns true if the cell is merged.
#
sub is_merged {
my $self = shift;
return $self->{Merged};
}
###############################################################################
#
# get_rich_text()
#
# Returns an array ref of font information about each string block in a "rich",
# i.e. multi-format, string.
#
sub get_rich_text {
my $self = shift;
return $self->{Rich};
}
###############################################################################
#
# Mapping between legacy method names and new names.
#
{
no warnings; # Ignore warnings about variables used only once.
*Value = *value;
}
1;
__END__
=pod
=head1 NAME
Spreadsheet::ParseExcel::Cell - A class for Cell data and formatting.
=head1 SYNOPSIS
See the documentation for Spreadsheet::ParseExcel.
=head1 DESCRIPTION
This module is used in conjunction with Spreadsheet::ParseExcel. See the documentation for Spreadsheet::ParseExcel.
=head1 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()
=head2 value()
The C<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 C<unformatted()> method below.
For a defined C<$cell> the C<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 C<''>.
=head2 unformatted()
The C<unformatted()> method returns the unformatted value of the cell.
my $unformatted = $cell->unformatted();
Returns the cell value without a numeric format. See the C<value()> method above.
=head2 get_format()
The C<get_format()> method returns the L<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.
=head2 type()
The C<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 C<m{^[dmy][-\\/dmy]*$}i>, it will be treated as a Date type.
my $type = $cell->type();
See also L<Dates and Time in Excel>.
=head2 encoding()
The C<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 C<encoding()> method returns one of the following values:
=over
=item * 0: Unknown format. This shouldn't happen. In the default case the format should be 1.
=item * 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.
=item * 2: UTF-16BE.
=item * 3: Native encoding. In Excel 95 and earlier this encoding was used to represent multi-byte character encodings such as SJIS.
=back
=head2 is_merged()
The C<is_merged()> method returns true if the cell is merged.
my $is_merged = $cell->is_merged();
Returns C<undef> if the property isn't set.
=head2 get_rich_text()
The C<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.
=head1 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 L<Spreadsheet::ParseExcel::Utility> module contains a function called C<ExcelLocaltime> which will convert between an unformatted Excel date/time number and a C<localtime()> like array.
For date conversions using the CPAN C<DateTime> framework see L<DateTime::Format::Excel> http://search.cpan.org/search?dist=DateTime-Format-Excel
=head1 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
=head1 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.
=cut