octave_packages/io-1.0.19/xlsread.m

   1 ## Copyright (C) 2009,2010,2011,2012 by Philip Nienhuis <prnienhuis at users.sf.net>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr},  @var{limits}] = xlsread (@var{filename})
  18 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = xlsread (@var{filename}, @var{wsh})
  19 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = xlsread (@var{filename}, @var{range})
  20 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = xlsread (@var{filename}, @var{wsh}, @var{range})
  21 ## @deftypefnx {Function File} [@var{numarr}, @var{txtarr}, @var{rawarr}, @var{limits}] = xlsread (@var{filename}, @var{wsh}, @var{range}, @var{reqintf})
  22 ##
  23 ## Read data contained in range @var{range} from worksheet @var{wsh}
  24 ## in Excel spreadsheet file @var{filename}.
  25 ## Return argument @var{numarr} contains the numeric data, optional
  26 ## return arguments @var{txtarr} and @var{rawarr} contain text strings
  27 ## and the raw spreadsheet cell data, respectively. Return argument
  28 ## @var{limits} contains the outer column/row numbers of the read
  29 ## spreadsheet range where @var{numarr}, @var{txtarr} and @var{rawarr}
  30 ## have come from (remember, xlsread trims outer rows and columns).
  31 ##
  32 ## If @var{filename} does not contain any directory, the file is
  33 ## assumed to be in the current directory. The filename extension
  34 ## (.xls or .xlsx) must be included in the file name; when using the
  35 ## COM interface all file formats can be read that are supported by the
  36 ## locally installed MS-Excel version (e.g., wk1, csv, dbf, etc.).
  37 ##
  38 ## @var{range} is expected to be a regular spreadsheet range format,
  39 ## or "" (empty string, indicating all data in a worksheet).
  40 ## If no range is specified the occupied cell range will have to be
  41 ## determined behind the scenes first; this can take some time for the
  42 ## Java-based interfaces (but the results may be more reliable than
  43 ## that of ActiveX/COM).
  44 ##
  45 ## @var{wsh} is either numerical or text; in the latter case it is
  46 ## case-sensitive and it may be max. 31 characters long.
  47 ## Note that in case of a numerical @var{wsh} this number refers to the
  48 ## position in the worksheet stack, counted from the left in an Excel
  49 ## window. The default is numerical 1, i.e. the leftmost worksheet
  50 ## in the Excel file.
  51 ##
  52 ## If only the first argument is specified, xlsread will try to read
  53 ## all contents (as if a range of @'' (empty string) was specified)
  54 ## from the first = leftmost (or the only) worksheet
  55 ##
  56 ## If only two arguments are specified, xlsread assumes the second
  57 ## argument to be @var{range} if it is a string argument and contains
  58 ##  a ":" or if it is @'' (empty string), and in those cases assumes
  59 ## the data must be read from the first worksheet (not necessarily
  60 ## Sheet1! but the leftmost sheet).
  61 ##
  62 ## However, if only two arguments are specified and the second argument
  63 ## is numeric or a text string that does not contain a ":", it is
  64 ## assumed to be @var{wsh} and to refer to a worksheet. In that case
  65 ## xlsread tries to read all data contained in that worksheet.
  66 ##
  67 ## The optional last argument @var{reqintf} can be used to override
  68 ## the automatic interface selection by xlsread out of the supported
  69 ## ones: COM/Excel, Java/Apache POI, Java/JExcelAPI, Java/OpenXLS, or
  70 ## Java/UNO (OpenOffice.org) (in that -built in- order of preference).
  71 ## For reading from OOXML files a value of 'com', 'poi' or 'uno' must
  72 ## be specified for @var{reqintf} (see help for xlsopen); for Excel'95
  73 ## files use 'com', or if Excel is not installed use 'jxl', 'basic'
  74 ## or 'uno' (POI can't read Excel 95 but will try to fall back to JXL).
  75 ## As @var{reqintf} can also be a cell array of strings, one can
  76 ## select or exclude one or more interfaces.
  77 ##
  78 ## Erroneous data and empty cells are set to NaN in @var{numarr} and
  79 ## turn up empty in @var{txtarr} and @var{rawarr}. Date/time values in
  80 ## Excel are returned as numerical values in @var{numarr}. Note that
  81 ## Excel and Octave have different date base values (1/1/1900 &
  82 ## 1/1/0000, resp.). Spreadsheet date values lying before 1/1/1900 are
  83 ## returned as strings, formatted as they appear in the spreadsheet.
  84 ## @var{numarr} and @var{txtarr} are trimmed from empty outer rows
  85 ## and columns. Be aware that Excel does the same for @var{rawarr},
  86 ## so any returned array may turn out to be smaller than requested in
  87 ## @var{range}.
  88 ##
  89 ## When reading from merged cells, all array elements NOT corresponding
  90 ## to the leftmost or upper Excel cell will be treated as if the
  91 ## "corresponding" Excel cells are empty.
  92 ##
  93 ## xlsread is just a wrapper for a collection of scripts that find out
  94 ## the interface to be used (COM, Java/POI, Java/JXL Java/OXS, Java/UNO)
  95 ## and do the actual reading. For each call to xlsread the interface must
  96 ## be started and the Excel file read into memory. When reading multiple
  97 ## ranges (in optionally multiple worksheets) a significant speed boost
  98 ## can be obtained by invoking those scripts directly as in:
  99 ## xlsopen / xls2oct [/ parsecell] / ... / xlsclose
 100 ##
 101 ## Beware: when using the COM interface, hidden Excel invocations may be
 102 ## kept running silently if not closed explicitly.
 103 ##
 104 ## Examples:
 105 ##
 106 ## @example
 107 ##   A = xlsread ('test4.xls', '2nd_sheet', 'C3:AB40');
 108 ##   (which returns the numeric contents in range C3:AB40 in worksheet
 109 ##   '2nd_sheet' from file test4.xls into numeric array A)
 110 ## @end example
 111 ##
 112 ## @example
 113 ##   [An, Tn, Ra, limits] = xlsread ('Sales2009.xls', 'Third_sheet');
 114 ##   (which returns all data in worksheet 'Third_sheet' in file 'Sales2009.xls'
 115 ##   into array An, the text data into array Tn, the raw cell data into
 116 ##   cell array Ra and the ranges from where the actual data came in limits)
 117 ## @end example
 118 ##
 119 ## @example
 120 ##   numarr = xlsread ('Sales2010.xls', 4, [], @{'JXL', 'COM'@});
 121 ##   (Read all data from 4th worksheet in file Sales2010.xls using either JXL
 122 ##    or COM interface (i.e, exclude POI interface).
 123 ## @end example
 124 ##
 125 ## @seealso {xlswrite, xlsopen, xls2oct, xlsclose, xlsfinfo, oct2xls}
 126 ##
 127 ## @end deftypefn
 128
 129 ## Author: Philip Nienhuis
 130 ## Created: 2009-10-16
 131 ## Updates:
 132 ## 2009-12-29 bug fixes
 133 ## 2010-01-12 added unwind_protect to get rid of stray Excel invocations i.c.o. COM errors
 134 ## 2010-05-31 Updated help text (delays i.c.o. empty range due to getusedrange call)
 135 ## 2010-08-18 Added check for existence of xls after call to xlsopen to
 136 ##         ''     avoid unneeded error message clutter
 137 ## 2010-08-25 Improved help text, esp. sections Excel file types and interfaces
 138 ## 2010-10-20 Dropped wiping xls.limits for COM (nowadays COM can return those)
 139 ## 2010-10-21 Formally added 'BASIC' option as synonym for 'JXL'
 140 ## 2010-11-05 Updated help text
 141 ## 2010-11-13 Added some input checks
 142 ## 2011-04-11 Return upon empty xls struct from xlsopen()
 143 ## 2011-04-17 Suppress xlsopen messages (";" was missing)
 144 ## 2011-09-08 Minor code cleanup; included UNO & OXS support in test
 145 ## 2012-01-26 Fixed "seealso" help string
 146 ## 2012-03-07 Updated texinfo help header
 147
 148 function [ numarr, txtarr, rawarr, lims ] = xlsread (fn, wsh, datrange, reqintf=[])
 149
 150         rstatus = 0;
 151
 152         if (nargout < 1)
 153                 usage ("xlsread: no output argument(s) specified that should receive data");
 154         endif
 155         if (nargin < 1)
 156                 error ("xlsread: no input arguments specified")
 157                 numarr = []; txtarr={}; rawarr = {};
 158                 return
 159         elseif (nargin == 1)
 160                 wsh = 1;
 161                 datrange = '';
 162         elseif (nargin == 2)
 163                 # Find out whether 2nd argument = worksheet or range
 164                 if (isnumeric (wsh) || (isempty (findstr (wsh,':')) && ~isempty (wsh)))
 165                         # Apparently a worksheet specified
 166                         datrange = '';
 167                 else
 168                         # Range specified
 169                         datrange = wsh;
 170                         wsh = 1;
 171                 endif
 172         endif
 173
 174         # A small gesture for Matlab compatibility. JExcelAPI supports BIFF5.
 175         if (~isempty (reqintf) && ischar (reqintf) && strcmpi (reqintf, 'BASIC'))
 176                 reqintf= {"JXL"} ;
 177                 printf ("(BASIC (BIFF5) support request translated to JXL.) \n");
 178         endif
 179
 180         # Checks done. Get raw data into cell array "rawarr". xlsopen finds out
 181         # what interface to use. If none found, just return as xlsopen will complain enough
 182
 183         unwind_protect  # Needed to catch COM errors & able to close stray Excel invocations
 184         # Get pointer array to Excel file
 185         xls_ok = 0;
 186         xls = xlsopen (fn, 0, reqintf);
 187         if (~isempty (xls))
 188                 xls_ok = 1;
 189         else
 190                 return
 191         endif
 192
 193 #       if (strcmp (xls.xtype, 'COM') || strcmp (xls.xtype, 'POI') || strcmp (xls.xtype, 'JXL')...
 194 #                               || strcmp (xls.xtype, 'OXS') || strcmp (xls.xtype, 'UNO'))
 195
 196                 # Get data from Excel file & return handle
 197                 [rawarr, xls, rstatus] = xls2oct (xls, wsh, datrange);
 198
 199                 # Save some results before xls is wiped
 200                 rawlimits = xls.limits;
 201                 xtype = xls.xtype;
 202
 203                 if (rstatus)
 204                         [numarr, txtarr, lims] = parsecell (rawarr, rawlimits);
 205                 else
 206                         rawarr = {}; numarr = []; txtarr = {};
 207                 endif
 208
 209 #       else
 210 #               printf ("Error XLSREAD: reading EXCEL file (BIFF- or OOXML Format) isn\'t supported on this system.\n");
 211 #               printf ("You need to convert the file into a tab- or comma delimited text file or .csv file\n");
 212 #               printf ("and then invoke csvread(), dlmread() or textread()\n\n");
 213 #
 214 #       endif
 215
 216         unwind_protect_cleanup
 217         # Close Excel file
 218         if (xls_ok) xls = xlsclose (xls); endif
 219
 220         end_unwind_protect
 221
 222 endfunction