function C = readcell(filename,varargin)
%READCELL Create a cell array by reading from a file.
%
%   Use the READCELL function to create a cell array by reading
%   column-oriented data from a file. READCELL can automatically determine
%   the file format from its extension.
%
%   C = READCELL(FILENAME) creates a cell array by reading from a file.
%   FILENAME can be one of these:
%
%       - For local files, FILENAME can be an absolute path that contains
%         a filename and file extension. FILENAME can also be a relative
%         path to the current directory or to a directory on the MATLAB
%         path. For example, to import a file on the MATLAB path:
%
%            C = readcell("patients.xls");
%
%       - For files from an Internet URL or stored at a remote location,
%         FILENAME must be a full path using a Uniform Resource Locator
%         (URL). For example, to import a remote file from Amazon S3,
%         specify the full URL for the file:
%
%            C = readcell("s3://bucketname/path_to_file/my_data.xls");
%
%         For more information on accessing remote data, see "Work with
%         Remote Data" in the documentation.
%
%   C = READCELL(FILENAME, OPTS) creates a cell array by reading
%   from a file stored at FILENAME using the supplied ImportOptions OPTS.
%   OPTS specifies selected variable names, and other information regarding
%   the data.
%   Note: Variable types specified in ImportOptions are not used in READCELL.
%
%   C = READCELL(___, Name, Value) specifies additional parameters
%   using one or more name-value pair arguments.
%
%   Name-Value Pairs for both TEXT and SPREADSHEET files:
%   -----------------------------------------------------
%
%   "FileType"             - Specify the file as "text" or "spreadsheet".
%
%   "Range"                - The range to consider when detecting data.
%                            Specified using any of the following syntaxes:
%                            - start cell: A string or character vector
%                              containing a column letter and a row number,
%                              or a 2 element numeric vector indicating
%                              the starting row and column.
%                            - full range: A start and end cell separated
%                              by colon, e.g. "C2:N15", or a four element
%                              numeric vector containing start row, start
%                              column, end row, end column, e.g. [2 3 15 13].
%                            - row range: A string or character vector
%                              containing a starting row number and ending
%                              row number, separated by a colon.
%                            - column range: A string or character vector
%                              containing a starting column letter and
%                              ending column letter, separated by a colon.
%                            - row number: A numeric scalar indicating the
%                              first row where data is found.
%
%   "NumHeaderLines"       - The number of header lines in the file.
%
%   "ExpectedNumVariables" - The expected number of variables.   
% 
%   "TextType"             - "char" or "string" the type to use for
%                            text variables.
%
%   "DatetimeType"         - "datetime", "text", or "exceldatenum" the
%                            type to use for dates.
%                            Note: "exceldatenum" is not allowed for text. 
%
%   Name-Value Pairs for TEXT only:
%   -------------------------------
%
%   "Delimiter"                 - The delimiter(s) to use in the file.
%
%   "CommentStyle"              - The style of comments in the file.
%
%   "LineEnding"                - The line ending for the file.
%
%   "DateLocale"                - The locale used to interpret month and
%                                 day names in datetime text. LOCALE
%                                 must be a character vector or scalar
%                                 string in the form xx_YY. See the
%                                 documentation for DATETIME for more
%                                 information.
%
%   "Encoding"                  - The text encoding of the file.
%
%   "DurationType"              - "duration" or "text" the type to use
%                                 for duration.
%
%   "Whitespace"                - Characters to treat as whitespace.
%
%   "ConsecutiveDelimitersRule" - What to do with consecutive delimiters
%                                 that appear in the file:
%                                 - "split" - each delimiter separates a
%                                             single field
%                                 - "join"  - groups of delimiters separate
%                                             single fields
%                                 - "error" - ignored for detection
%                                             (treated as "split"), but the
%                                             resulting read will error.
%
%   "LeadingDelimitersRule"     - What to do with delimiters at the beginning
%                                 of a line.
%
%   Name-Value Pairs for SPREADSHEETS only:
%   ---------------------------------------
%
%   "Sheet"    - The sheet from which to detect the data.
%
%   "UseExcel" - A logical value that specifies whether or not to read the
%                spreadsheet file using Microsoft(R) Excel(R) for
%                Windows(R). Set "UseExcel" to one of these values:
%                - false -  Does not open an instance of Microsoft Excel 
%                           to read the file. This is the default setting.
%                           This setting may cause the data to be 
%                           written differently for files with 
%                           live updates (e.g. formula evaluation or plugins).
%                - true  -  Opens an instance of Microsoft Excel to read 
%                           the file on a Windows system with Excel installed.
%
%   Parameters which are also accepted with import options. These may have
%   slightly different behavior when used with import options:
%
%   Name-Value Pairs supported with Import Options OPTS:
%   ----------------------------------------------------
%
%       Text only parameters:
%         "DateLocale" -   Override the locale used when importing dates.
%         "Encoding"   -   Override the encoding defined in import options.
%
%       Spreadsheet only parameters:
%         "Sheet"      -   Override the sheet value in the import options.
%         "UseExcel"   -   Same behavior as READCELL without import options.
%
%    For example, import a sub-set of the heterogeneous data in a file:
%       opts = detectImportOptions("patients.xls");
%       opts.SelectedVariableNames = ["LastName", "Diastolic"];
%       C = readcell("patients.xls", opts);
%
%    See also WRITECELL, DETECTIMPORTOPTIONS, READTABLE, READMATRIX.

%    Copyright 2018-2020 The MathWorks, Inc.

try
    func = matlab.io.internal.functions.FunctionStore.getFunctionByName('readcell');
    CC = onCleanup(@()func.WorkSheet.clear());
    C = func.validateAndExecute(filename,varargin{:});
catch ME
    throw(ME);
end
