octave_packages/io-1.0.19/xlswrite.m

   1 ## Copyright (C) 2009,2010,2011,2012 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{rstatus} = xlswrite (@var{filename}, @var{arr})
  18 ## @deftypefnx {Function File} @var{rstatus} = xlswrite (@var{filename}, @var{arr}, @var{wsh})
  19 ## @deftypefnx {Function File} @var{rstatus} = xlswrite (@var{filename}, @var{arr}, @var{wsh}, @var{range})
  20 ## @deftypefnx {Function File} @var{rstatus} = xlswrite (@var{filename}, @var{arr}, @var{wsh}, @var{range}, @var{reqintf})
  21 ## Add data in 1D/2D array @var{arr} to worksheet @var{wsh} in Excel
  22 ## spreadsheet file @var{filename} in cell range @var{range}.
  23 ##
  24 ## @var{rstatus} returns 1 if write succeeded, 0 otherwise.
  25 ##
  26 ## @var{filename} must be a valid .xls Excel file name (including file
  27 ## name extension). If @var{filename} does not contain any directory path,
  28 ## the file is saved in the current directory.
  29 ##
  30 ## @var{arr} can be any 1D or 2D array containing numerical or character
  31 ## data (cellstr) except complex. Mixed numeric/text arrays can only be
  32 ## cell arrays.
  33 ##
  34 ## If only 3 arguments are given, the 3rd is assumed to be a spreadsheet
  35 ## range if it contains a ":" or is a completely empty string (corresponding
  36 ## to A1:IV65336 for regular .xls or A1:XFD1048576 for OOXML .xlsx). The
  37 ## 3rd argument is assumed to refer to a worksheet if it is a numeric value
  38 ## or a non-empty text string not containing ":"
  39 ##
  40 ## @var{wsh} can be a number or string (max. 31 chars).
  41 ## In case of a not yet existing Excel file, the first worksheet will be
  42 ## used & named according to @var{wsh} - the extra worksheets that Excel
  43 ## normally creates by default are deleted.
  44 ## In case of existing files, some checks are made for existing worksheet
  45 ## names or numbers, or whether @var{wsh} refers to an existing sheet with
  46 ## a type other than worksheet (e.g., chart).
  47 ## When new worksheets are to be added to the Excel file, they are
  48 ## inserted to the right of all existing worksheets. The pointer to the
  49 ## "active" sheet (shown when Excel opens the file) remains untouched.
  50 ##
  51 ## @var{range} is expected to be a regular spreadsheet range.
  52 ## Data is added to the worksheet; existing data in the requested
  53 ## range will be overwritten.
  54 ## Array @var{arr} will be clipped at the right and/or bottom if its size
  55 ## is bigger than can be accommodated in @var{range}.
  56 ## If @var{arr} is smaller than the @var{range} allows, it is placed
  57 ## in the top left rectangle of @var{range} and remaining cell values
  58 ## outside the rectangle will be retained.
  59 ##
  60 ## If @var{range} contains merged cells, only the elements of @var{arr}
  61 ## corresponding to the top or left Excel cells of those merged cells
  62 ## will be written, other array cells corresponding to that cell will be
  63 ## ignored.
  64 ##
  65 ## The optional last argument @var{reqintf} can be used to override
  66 ## the automatic selection by xlswrite of one interface out of the
  67 ## supported ones: 'com' (ActiveX/Excel), 'poi' (Java/Apache POI), 'jxl'
  68 ## (Java/JExcelAPI), or 'uno' (Java/OpenOffice.org). 'oxs' (Java/OpenXLS)
  69 ## is implemented but disabled for writing as it is too buggy. For
  70 ## writing to OOXML files (.xlsx) a value of 'com', 'poi' or 'uno' must
  71 ## be specified for @var{reqintf}. The value of @var{reqintf} is
  72 ## case-insensitive. Multiple interfaces can be selected if entered as
  73 ## a cell array of strings.
  74 ##
  75 ## xlswrite is a mere wrapper for various scripts which find out what
  76 ## Excel interface to use (COM, POI, etc) plus code to mimic the other
  77 ## brand's syntax. For each call to xlswrite such an interface must be
  78 ## started and possibly an Excel file loaded. When writing to multiple
  79 ## ranges and/or worksheets in the same Excel file, a speed bonus can be
  80 ## obtained by invoking those scripts directly with multiple calls to
  81 ## oct2xls (one for each sheet or range) surrounded by one call to
  82 ## xlsopen and xlsclose:
  83 ## (xlsopen / octxls / oct2xls / .... / xlsclose)
  84 ##
  85 ## Examples:
  86 ##
  87 ## @example
  88 ##   status = xlswrite ('test4.xls', 'arr', 'Third_sheet', 'C3:AB40');
  89 ##   (which adds the contents of array arr (any type) to range C3:AB40
  90 ##   in worksheet 'Third_sheet' in file test4.xls and returns a logical
  91 ##   True (= numerical 1) in status if al went well)
  92 ## @end example
  93 ##
  94 ## @seealso {xlsread, oct2xls, xls2oct, xlsopen, xlsclose, xlsfinfo}
  95 ##
  96 ## @end deftypefn
  97
  98 ## Author: Philip Nienhuis
  99 ## Created: 2009-10-16
 100 ## Updates:
 101 ## 2010-01-04 (Adapted range capacity checks to OOXML)
 102 ## 2010-01-12 (Bug fix; added unwind_protect to xlsopen...xlsclose calls)
 103 ## 2010-01-15 Fixed typos in texinfo
 104 ## 2010-08-18 Added check for existence of xls after call to xlsopen to
 105 ##            avoid unneeded error message clutter
 106 ## 2010-10-27 Changed range -> crange to unhide other range functions
 107 ## 2011-09-08 Minor code syntax updates
 108 ## 2012-01-26 Fixed "seealso" help string
 109 ## 2012-06-07 Replaced all tabs by double space
 110
 111 function [ rstatus ] = xlswrite (filename, arr, arg3, arg4, arg5)
 112
 113   rstatus = 0;
 114
 115   # Sanity checks
 116   if (nargin < 2)
 117     usage ("Insufficient arguments - see 'help xlswrite'");
 118   elseif (~ischar (filename))
 119     error ("First argument must be a filename (incl. suffix)");
 120   elseif (nargin == 2)
 121     # Assume first worksheet and full worksheet starting at A1
 122     wsh = 1;
 123     if (strcmp (tolower (filename(end-4:end-1)), 'xls'))
 124       crange = "A1:XFD1048576";  # OOXML has ridiculously large limits
 125     else
 126       crange = "A1:IV65536";    # Regular xls limits
 127     endif
 128   elseif (nargin == 3)
 129     # Find out whether 3rd argument = worksheet or range
 130     if (isnumeric (arg3) || (isempty (findstr (arg3, ':')) && ~isempty (arg3)))
 131       # Apparently a worksheet specified
 132       wsh = arg3;
 133       if (strcmp (tolower (filename(end-4:end-1)), 'xls'))
 134         crange = "A1:XFD1048576";  # OOXML has ridiculously large limits
 135       else
 136         crange = "A1:IV65536";    # Regular xls limits
 137       endif
 138     else
 139       # Range specified
 140       wsh = 1;
 141       crange = arg3;
 142     endif
 143   elseif (nargin >= 4)
 144     wsh = arg3;
 145     crange = arg4;
 146   endif
 147   if (nargin == 5)
 148     reqintf = arg5;
 149   else
 150     reqintf = [];
 151   endif
 152
 153   # Parse range
 154   [topleft, nrows, ncols, trow, lcol] = parse_sp_range (crange);
 155
 156   # Check if arr fits in range
 157   [nr, nc] = size (arr);
 158   if ((nr > nrows) || (nc > ncols))
 159     # Array too big; truncate
 160     nr = min (nrows, nr);
 161     nc = min (ncols, nc);
 162     warning ("xlswrite - array truncated to %d by %d to fit in range %s", ...
 163          nrows, ncols, crange);
 164   endif
 165
 166   unwind_protect        # Needed to be sure Excel can be closed i.c.o. errors
 167     xls_ok = 0;
 168     xls = xlsopen (filename, 1, reqintf);
 169     xls_ok = 1;
 170
 171     [xls, rstatus] = oct2xls (arr(1:nr, 1:nc), xls, wsh, topleft);
 172
 173   unwind_protect_cleanup
 174     if (xls_ok), xls = xlsclose (xls); endif
 175
 176   end_unwind_protect
 177
 178 endfunction