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 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:
%
%             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
%                             tocalculate 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", "spreadsheet", or "xml".
%
%   "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.
%
%   "MissingRule"           - Rules for interpreting missing or
%                             unavailable data:
%                             "fill"      Replace missing data with the
%                                         contents of the "FillValue"
%                                         property.
%                             "error"     Stop importing and display an
%                                         error message showing the missing
%                                         record and field.
%                             "omitrow"   Omit rows that contain missing
%                                         data.
%                             "omitvar"   Omit variables that contain
%                                         missing data.
%
%   "ImportErrorRule"       - Rules for interpreting nonconvertible
%                             or bad data:
%                             "fill"      Replace the data where errors
%                                         occur with the contents of the
%                                         "FillValue" property.
%                             "error"     Stop importing and display an
%                                         error message showing the
%                                         error-causing record and field.
%                             "omitrow"   Omit rows where errors occur.
%                             "omitvar"   Omit variables where errors
%                                         occur.
%
%   "TreatAsMissing"        - Text which is used in 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".
%                             Defaults to "datetime".
%
%   "WebOptions"            - HTTP(s) request options, specified as a 
%                             weboptions object. 
%
%   Name-Value Pairs for TEXT and SPREADSHEET only:
%   -----------------------------------------------
%
%   "Range"                 - The range to consider when detecting data.
%                             Specified using any of the following syntaxes:
%                             - Starting 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.
%                             - Rectangular 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.
%                             - Starting row number: A numeric scalar
%                               indicating the first row where data is found.
%
%   "NumHeaderLines"        - The number of lines which appear before the
%                             data, variable names, etc..
%
%   "ExpectedNumVariables"  - The expected number of variables.
%
%   "ReadVariableNames"     - Whether or not to expect variable names in
%                             the file. Defaults to true.
%
%   Name-Value Pairs for TEXT and XML only:
%   ---------------------------------------
%
%   "Encoding"           - The character encoding scheme associated with
%                          the file.
%
%   "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". Defaults to "duration".
%
%   "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"     - Whether or not to remove nonnumeric characters
%                          from a numeric variable. Defaults to false.
%
%   "HexType"            - Set the output type of a hexadecimal
%                          variable.
%
%   "BinaryType"         - Set the output type of a binary variable.
%
%   "CollectOutput"      - Whether or not to concatenate consecutive output
%                          of the same MATLAB class into a single array.
%                          Defaults to false.
%
%   Name-Value Pairs for TEXT only:
%   -------------------------------
%
%   "Delimiter"                 - Field delimiter characters in a delimited
%                                 text file, specified as a character
%                                 vector, string scalar, cell array of
%                                 character vectors, or string array.
%
%   "CommentStyle"              - Style of comments, specified as a
%                                 character vector, string scalar, cell
%                                 array of character vectors, or string
%                                 array.
%
%   "LineEnding"                - End-of-line characters, specified as a
%                                 character vector, string scalar, cell
%                                 array of character vectors, or string
%                                 array.
%
%   "ConsecutiveDelimitersRule" - Rule to apply to fields containing
%                                 multiple consecutive delimiters:
%                                 "split"     Split consecutive delimiters
%                                             into multiple fields.
%                                 "join"      Join the delimiters into one
%                                             single delimiter.
%                                 "error"     Ignore consecutive delimiters
%                                             during detection (treated as
%                                             "split"), but the
%                                             resulting read will error.
%
%   "LeadingDelimitersRule"     - Rule to apply to delimiters at the
%                                 beginning of a line:
%                                 "keep"      Keep leading delimiters.
%                                 "ignore"    Ignore leading delimiters.
%                                 "error"     Ignore leading delimiters
%                                             during detection, but the
%                                             resulting read will error.
%
%   "TrailingDelimiterRule"     - Rule to apply to delimiters at the
%                                 end of a line:
%                                 "keep"      Keep trailing delimiters.
%                                 "ignore"    Ignore trailing delimiters.
%                                 "error"     Ignore trailing delimiters
%                                             during detection, but the
%                                             resulting read will error.
%
%   "VariableWidths"            - Widths of the variables for a fixed width
%                                 file.
%
%   "EmptyLineRule"             - Rule to apply to empty lines in the file:
%                                 "skip"      Skip empty lines.
%                                 "read"      Read empty lines.
%                                 "error"     Ignore empty lines during
%                                             detection, but the resulting
%                                             read will error.
%
%   "VariableNamesLine"         - The line where the variable names are
%                                 located.
%
%   "PartialFieldRule"          - Rule to handle partial fields in the data:
%                                 "keep"      Keep the partial field data
%                                             and convert the text to the
%                                             appropriate data type.
%                                 "fill"      Replace missing data with the
%                                             contents of the "FillValue"
%                                             property.
%                                 "omitrow"   Omit rows that contain
%                                             partial data.
%                                 "omitvar"   Omit variables that contain
%                                             partial data.
%                                 "wrap"      Begin reading the next line
%                                             of characters.
%                                 "error"     Ignore partial field data
%                                             during detection, but the
%                                             resulting read will error.
%
%   "VariableUnitsLine"         - The line where the variable units are
%                                 located.
%
%   "VariableDescriptionsLine"  - The line where the variable descriptions
%                                 are located.
%
%   "ExtraColumnsRule"          - Rule to apply to extra columns of data
%                                 that appear after the expected variables:
%                                 "addvars"   Creates new variables to 
%                                             import extra columns. If there
%                                             are N extra columns, then import
%                                             new variables as "ExtraVar1",
%                                             "ExtraVar2",..., "ExtraVarN".
%                                 "ignore"    Ignore the extra columns of
%                                             data.
%                                 "wrap"      Wrap the extra columns of
%                                             data to new records.
%                                 "error"     Display an error message and
%                                             abort the import operation.
%
%   Name-Value Pairs for SPREADSHEET only:
%   --------------------------------------
%
%   "UseExcel"                  - Whether or not to read the spreadsheet
%                                 file using Microsoft(R) Excel(R) on 
%                                 Windows(R):
%                                 true  - Opens an instance of Microsoft Excel
%                                         to read the file on a Windows system
%                                         with Excel installed.
%                                 false - Does not open an instance of Microsoft
%                                         Excel to read the file. This is the
%                                         default setting.
%
%   "Sheet"                     - The sheet from which to read the timetable.
%
%   "DataRange"                 - Where the timetable data is located.
%
%   "VariableNamesRange"        - Where the variable names are located.
%
%   "VariableUnitsRange"        - Where the variable units are located.
%
%   "VariableDescriptionsRange" - Where the variable descriptions are
%                                 located.
%
%   Name-Value Pairs for XML only:
%   ------------------------------
%
%   "RowNodeName"                  - Node name which delineates rows of
%                                    the output timetable.
%
%   "RowSelector"                  - XPath expression that selects the XML
%                                    Element nodes which delineate rows of
%                                    the output timetable.
%
%   "VariableNodeNames"            - Node names which will be treated as
%                                    variables of the output timetable.
%
%   "VariableSelectors"            - XPath expressions that select the XML
%                                    Element nodes to be treated as variables
%                                    of the output timetable.
%
%   "TableNodeName"                - Name of the node which contains timetable
%                                    data. If multiple nodes have the same
%                                    name, READTABLE uses the first node
%                                    with that name.
%
%   "TableSelector"                - XPath expression that selects the XML
%                                    Element node containing the table data.
%
%   "VariableUnitsSelector"        - XPath expression that selects the XML
%                                    Element nodes containing the variable
%                                    units.
%
%   "VariableDescriptionsSelector" - XPath expression that selects the XML
%                                    Element nodes containing the variable
%                                    descriptions.
%
%   "RepeatedNodeRule"             - Rule for managing repeated nodes in a
%                                    given row of a timetable:
%                                    "addcol"     Add a column for each
%                                                 repeated node.
%                                    "ignore"     Ignore repeated nodes.
%                                    "error"      Ignore repeated nodes
%                                                 during detection, but the
%                                                 resulting read will error.
%
%   "ImportAttributes"             - Import XML node attributes as variables
%                                    of the output timetable. Defaults to true.
%
%   "AttributeSuffix"              - Suffix to append to all output timetable
%                                    variable names corresponding to
%                                    attributes in the XML file. Defaults
%                                    to "Attribute".
%
%   "RegisteredNamespaces"         - The namespace prefixes that are mapped
%                                    to namespace URLs for use in selector
%                                    expressions.
%
%   Name-Value Pairs supported with Import Options OPTS:
%   ----------------------------------------------------
%
%       Supported for all file types:
%         "WebOptions" -   HTTP(s) request options, specified as a 
%                          weboptions object.
%
%   These have slightly different behavior when used with import options:
%
%       T = readtimetable(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 and XML 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-2021 The MathWorks, Inc.

try
    if any(cellfun(@(arg) isa(arg,"matlab.io.ImportOptions"),varargin),'all')
        error(message('MATLAB:textio:io:OptsSecondArg','readtimetable'))
    end
    func = matlab.io.internal.functions.FunctionStore.getFunctionByName("readtimetable");
    C = onCleanup(@()func.WorkSheet.clear());
    TT = func.validateAndExecute(filename,varargin{:});
catch ME
    throw(ME);
end
