function TT = readtimetable(filename,varargin)
%READTIMETABLE Create a timetable by reading from a file.
%
%    Use the READTIMETABLE function to create a timetable by reading
%    time-stamped tabular data from a file stored at FILENAME.
%    READTIMETABLE automatically determines the file format from its
%    extension.
%
%    TT = READTIMETABLE(FILENAME) creates a timetable by reading from a
%    file. The first datetime or duration variable detected in the file
%    becomes the time vector for the output timetable, while the remaining
%    variables in the file become variables in TT.
%    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:
%
%           TT = READTIMETABLE("timetable.xls");
%
%      - For remote files, FILENAME must be a full path using an uniform
%        resource locator (URL). For example, to import a remote
%        file from Amazon S3 cloud specify the full URL for the file:
%
%           TT = READTIMETABLE("s3://bucketname/path_to_file/my_timetable.xls");
%
%        For more information on accessing remote data, see "Work with
%        Remote Data" in the documentation.
%
%    TT = READTIMETABLE(FILENAME, OPTS) creates a timetable by reading from
%    a file using the supplied ImportOptions OPTS. OPTS specifies variable
%    names, selected variable names, variable types, and other information
%    regarding the data.
%
%    TT = READTIMETABLE(___, Name, Value) specifies additional parameters
%    using one or more name-value pair arguments.
%
%   Timetable Conversion Name-Value Pairs (for ALL file types):
%   -----------------------------------------------------------
%
%   "RowTimes"              - Specify the name of any variable in the file
%                             containing datetime or duration values to be
%                             used as the row times of the output timetable.
%                             Alternatively, provide a vector of duration or
%                             datetime values to be used as the vector of row
%                             times of the output timetable.
%
%   "TimeStep"              - The duration or calendar duration value used to
%                             calculate regularly spaced row times.
%
%   "SampleRate"            - The positive numeric scalar used to calculate
%                             regularly spaced row times.
%
%   "StartTime"             - The datetime scalar or duration scalar to specify
%                             a start time instead of zero seconds. This is to
%                             be used with either the "SampleRate" or "TimeStep"
%                             name-value pair arguments.
%
%   Name-Value Pairs for ALL file types:
%   ------------------------------------
%
%   "FileType"              - Specify the file as "text", "delimitedtext",
%                             "fixedwidth", or "spreadsheet".
%
%   "VariableNamingRule"    - A character vector or a string scalar that
%                             specifies how the output variables are named.
%                             It can have either of the following values:
%
%                             'modify'   Modify variable names to make them
%                                        valid MATLAB Identifiers.
%                                        (default)
%                             'preserve' Preserve original variable names
%                                        allowing names with spaces and
%                                        non-ASCII characters.
%
%   "ReadVariableNames"     - Whether or not to expect variable names in
%                             the file.
%
%   "TreatAsMissing"        - Text which is used in a file to represent
%                             missing data, e.g. "NA".
%
%   "TextType"              - The type to use for text variables, specified
%                             as "char" or "string".
%
%   "DatetimeType"          - The type to use for date variables, specified
%                             as "datetime", "text", or "exceldatenum".
%                             Note: "exceldatenum" not allowed for text
%
%   "ExpectedNumVariables"  - The expected number of variables.
%
%   Name-Value Pairs for TEXT and SPREADSHEET only:
%   -----------------------------------------------
%
%   "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.
%
%   Name-Value Pairs for TEXT only:
%   -------------------------------
%
%   "Encoding"           - The character encoding scheme associated with
%                          the file. If not specified, the encoding is
%                          assumed to be "UTF-8".
%                          If the "Encoding" parameter value is "system",
%                          then READTABLE uses your system"s default
%                          encoding.
%
%   "DateLocale"         - The locale used to interpret month and day
%                          names in datetime text. Must be a character
%                          vector or scalar string in the form xx_YY.
%                          See the documentation for DATETIME for more
%                          information.
%
%   "DurationType"       - The type to use for duration, specified as
%                          "duration" or "text".
%
%   "Whitespace"         - Characters to treat as whitespace.
%
%   "DecimalSeparator"   - Character used to separate the integer part
%                          of a number from the decimal part of the
%                          number.
%
%   "ThousandsSeparator" - Character used to separate the thousands
%                          place digits.
%
%   "TrimNonNumeric"     - Logical used to specify that prefixes and
%                          suffixes must be removed leaving only the
%                          numeric data.
%
%   "HexType"            - Set the output type of a hexadecimal
%                          variable.
%
%   "BinaryType"         - Set the output type of a binary variable.
%
%   "Delimiter"                 - The delimiter(s) to use in the file.
%
%   "CommentStyle"              - The style of comments in the file.
%
%   "LineEnding"                - The line ending for the file.
%
%   "ConsecutiveDelimitersRule" - Behaviors to apply to fields containing
%                                 multiple consecutive delimiters:
%                                 - "split" - split consecutive delimiters
%                                             into multiple fields.
%                                 - "join"  - consecutive delimiters are
%                                             treated as a single delimiter.
%                                 - "error" - Ignored during detection
%                                             (treated as "split"), but the
%                                             resulting read will error.
%
%   "LeadingDelimitersRule"     - Behaviors to apply to delimiters at the
%                                 beginning of a line:
%                                 - "keep"   - keep the delimiter
%                                 - "ignore" - ignore the delimiter
%                                 - "error"  - return an error
%
%   Name-Value Pairs for SPREADSHEET only:
%   --------------------------------------
%
%   "Sheet"    - The sheet from which to detect the timetable.
%
%   "UseExcel" - A logical value that specifies whether or not to read the
%                spreadsheet file using Microsoft(R) Excel(R) on
%                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.
%
%
%   Name-Value Pairs supported with Import Options OPTS:
%   ----------------------------------------------------
%
%   These have slightly different behavior when used with import options:
%
%       T = readtable(FILENAME, OPTS, "Name1", Value1, "Name2", Value2, ...)
%
%         "ReadVariableNames" true  - Reads the variable names from the
%                                     opts.VariableNamesRange or opts.VariableNamesLine
%                                     location.
%                             false - Uses variable names from the import options.
%
%       The following name-value pairs have the same behavior as
%       READTIMETABLE without import options for both text and spreadsheet files:
%         "RowTimes"
%         "TimeStep"
%         "SampleRate"
%         "StartTime"
%
%       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.
%
%   For example:
%
%      TT = readtimetable("quarterlyFinances1999To2019.csv", ...
%             "TimeStep", calquarters(1), ...        % Time stamp at every quarter
%             "StartTime", datetime(1999, 1, 1), ... % Start time stamps at January 1, 1999
%             "VariableNamingRule", "preserve",  ... % Keep whitespace in variable names
%             "TrimNonNumeric", true);               % Ignore "$" signs
%
%   See also WRITETIMETABLE, TIMETABLE, DETECTIMPORTOPTIONS, READTABLE

%   Copyright 2018-2020 The MathWorks, Inc.

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