classdef (AllowedSubclasses = {?timetable ?table}) tabular < matlab.mixin.internal.indexing.DotParen & matlab.internal.datatypes.saveLoadCompatibility 

% Internal abstract superclass for table and timetable.

% This class is for internal use only and will change in a future release. Do not use this class.

%   Copyright 2016-2019 The MathWorks, Inc.

    properties(Constant, Access='protected') % *** may go back to private if every instance is in tabular

        arrayPropsDflts = struct('Description', {''}, ...

                                 'UserData'   , [],...

                                 'TableCustomProperties',struct);

    end

    properties(Abstract, Constant, Access='protected')

        % Constant properties are not persisted when serialized

        propertyNames

        defaultDimNames

        dispRowLabelsHeader

        emptyPropertiesObj

    end

    properties(Abstract, Access='protected')

        metaDim

        rowDim

        varDim

        data

        arrayProps

    end

    properties(Dependent, SetAccess='protected')

        %PROPERTIES Table or timetable metadata properties.

        %   T.Properties, where T is a table or a timetable, contains the

        %   following metadata:

        %

        %       Description               - A character vector describing the table

        %       UserData                  - A variable containing any additional information associated

        %                                   with the table.  You can assign any value to this property.

        %       DimensionNames            - A two-element cell array of character vectors containing names

        %                                   of the dimensions of the table

        %       VariableNames             - A cell array containing names of the variables in the table

        %       VariableDescriptions      - A cell array of character vectors containing descriptions of

        %                                   the variables in the table

        %       VariableUnits             - A cell array of character vectors containing units for the

        %                                   variables in table

        %       RowNames (tables)         - A cell array of nonempty, distinct character vectors containing

        %                                   names of the rows in the table

        %       RowTimes (timetables)     - A datetime or durations vector containing times associated

        %                                   with each row in the timetable

        %       StartTime (timetables)    - First time value in the timetable

        %       SampleRate (timetables)   - For a timetable with a regularly-spaced time

        %                                   vector, the frequency of the samples

        %       TimeStep (timetables)     - For a timetable with a regularly-spaced time

        %                                   vector, the time interval between samples

        %       CustomProperties          - A container for user-defined per-table or per-variable custom 

        %                                   metadata fields. Add custom properties using ADDPROP.

        %

        %   See also TABLE, TIMETABLE, ADDPROP, RMPROP.

        Properties

    end

    methods % dependent property get methods

        function val = get.Properties(a)

            val = getProperties(a);

        end

    end

    methods(Hidden)

        function props = getProperties(t)

            % This function is for internal use only and will change in a future release.

            % Do not use this function. Use t.Properties instead.

            import matlab.internal.datatypes.mergeScalarStructs

            props = t.emptyPropertiesObj; % TableProperties or TimetableProperties

            p = mergeScalarStructs(t.arrayProps, ...

                                   t.metaDim.getProperties(), ...

                                   t.varDim.getProperties(), ...

                                   t.rowDim.getProperties());

            p.CustomProperties = matlab.tabular.CustomProperties(...

                p.TableCustomProperties,...

                p.VariableCustomProperties);

            p = rmfield(p,["VariableCustomProperties","TableCustomProperties"]);

            f = fieldnames(p);

            for i = 1:numel(f)

                props.(f{i}) = p.(f{i});

            end

        end

        function t = setProperties(t,s)

            %SET Set some or all table properties from a scalar struct or properties object.

            % This function is for internal use only and will change in a future release.

            % Do not use this function. Use t.Properties instead.

            if isstruct(s) && isscalar(s)

                fnames = fieldnames(s);

            elseif isa(s, class(t.emptyPropertiesObj))

                fnames = properties(s);

            else

                error(message('MATLAB:table:InvalidPropertiesAssignment',class(t.emptyPropertiesObj),class(t)));

            end

            for i = 1:length(fnames)

                fn = fnames{i};

                t = t.setProperty(fn,s.(fn));

            end

        end

        % Allows tab completion after dot to suggest variables

        function p = properties(t)

            % This will be called for properties of an instance, but the built-in will

            % still be called for the class name.  It will return just Properties,

            % which is correct.

            pp = [t.varDim.labels(:); 'Properties'; t.metaDim.labels(:)];

            if nargout == 0

                % get 1 or 0 newlines based on format loose/compact

                line_ending = repmat(newline,1,strcmp(matlab.internal.display.formatSpacing,'loose'));

                fprintf([line_ending '%s\n' line_ending], getString(message('MATLAB:ClassUstring:PROPERTIES_FUNCTION_LABEL',class(t))));

                fprintf('    %s\n',pp{:});

                fprintf(line_ending);

            else

                p = pp;

            end

        end

        function f = fieldnames(t), f = properties(t); end

        function f = fields(t),     f = properties(t); end

        function vars = getVars(t,asStruct)

            % This function is for internal use only and will change in a future release.

            % Do not use this function. Use table2struct(t,'AsScalar',true) instead.

            if nargin < 2 || asStruct

                [fnames, fixed] =  t.varDim.makeValidName(t.varDim.labels,'warn');

                fnames = matlab.lang.makeUniqueStrings(fnames, fixed,namelengthmax);

                vars = cell2struct(t.data,fnames,2);

            else

                vars = t.data;

            end

        end

        function n = getCustomPropertyNames(t)

            % Used in tab completion for rmprop.

            n = [fieldnames(t.varDim.customProps); fieldnames(t.arrayProps.TableCustomProperties)]';

        end

        function t1 = transferNonRowProperties(t,t1)

            % This function is for internal use only and will change in a future release.

            % Do not use this function. Used by table2timetable.

            f = fieldnames(t.arrayProps);

            for ii = 1:numel(f)

                t1.arrayProps.(f{ii}) = t.arrayProps.(f{ii});

            end

            t_varDim = t.varDim;

            t1.varDim = t1.varDim.init(t_varDim.length,t_varDim.labels,t_varDim.descrs,t_varDim.units,t_varDim.continuity,t_varDim.customProps);

        end

        function [indices,isLabels] = subs2inds(t,subs,subsType,dim)

            % This function is for internal use only and will change in a future release.

            % Do not use this function.

            switch subsType

            case 'assignment'

                sType = matlab.internal.tabular.private.tabularDimension.subsType.assignment;

            case 'reference'

                sType = matlab.internal.tabular.private.tabularDimension.subsType.reference;

            case 'deletion'

                sType = matlab.internal.tabular.private.tabularDimension.subsType.deletion;

            end

            switch dim

            case 'varDim'

                [indices,~,~,~,isLabels] = t.varDim.subs2inds(subs,sType,t.data);

            case 'rowDim'

                [indices,~,~,~,isLabels] = t.rowDim.subs2inds(subs,sType);

            case 'metaDim'

                [indices,~,~,~,isLabels] = t.metaDim.subs2inds(subs,sType);

            end

        end

        % Methods we don't want to clutter things up with

        e = end(t,k,n)

        B = repelem(A,M,N,varargin)

        disp(t,bold,indent,fullChar,nestedLevel)

        display(obj, name)

        [varargout] = subsref(t,s)

        t = subsasgn(t,s,b)

        % These functions are for internal use only and will change in a

        % future release.  Do not use these functions.

        b = dotParenReference(t,vn,s1,s2,varargin)

        sz = numArgumentsFromSubscript(t,s,context)

        [vars,varData,sortMode,varargout] = sortrowsFlagChecks(t,doIssortedrows,vars,sortMode,varargin)

        [vars,varData,sortMode,labels,varargin] =  topkrowsFlagChecks(a,vars,sortMode,varargin)

        %% Variable Editor methods

        % These functions are for internal use only and will change in a

        % future release.  Do not use these functions.

        varargout  = variableEditorGridSize(t)

        [names,indices,classes,iscellstr,charArrayWidths] = variableEditorColumnNames(t)

        rowNames   = variableEditorRowNames(t)

        [code,msg] = variableEditorRowDeleteCode(t,workspaceVariableName,rowIntervals)

        [code,msg] = variableEditorColumnDeleteCode(t,workspaceVariableName,columnIntervals)

        t          = variableEditorPaste(t,rows,columns,data)

        t          = variableEditorInsert(t,orientation,row,col,data)

        [code,msg] = variableEditorSetDataCode(t,workspaceVariableName,row,col,rhs)

        [code,msg] = variableEditorUngroupCode(t,varName,col)

        [code,msg] = variableEditorGroupCode(t,varName,startCol,endCol)

        metaData   = variableEditorMetadata(t)

        [code,msg] = variableEditorMetadataCode(t,varName,index,propertyName,propertyString)

        [code,msg] = variableEditorRowNameCode(t,varName,index,rowName)

        [code,msg] = variableEditorSortCode(t,varName,tableVariableNames,direction)

        [code,msg] = variableEditorMoveColumn(t,varName,startCol,endCol)

        %% Error stubs

        % Methods to override functions and throw helpful errors

        function d = double(t,varargin),     throwInvalidNumericConversion(t); end %#ok<STOUT>

        function s = single(t,varargin),     throwInvalidNumericConversion(t); end %#ok<STOUT>

        function n = length(t,varargin),     error(message('MATLAB:table:UndefinedLengthFunction',class(t))); end %#ok<STOUT>

        function t = transpose(t,varargin),  throwUndefinedTransposeError(t); end

        function t = ctranspose(t,varargin), throwUndefinedTransposeError(t); end

        function t = permute(t,varargin),    throwUndefinedError(t); end

        function t = reshape(t,varargin),    throwUndefinedError(t); end

        function t = plot(t,varargin),       error(message('MATLAB:table:NoPlotMethod')); end %#ok<INUSD>

        function t = sort(t,varargin)

            import matlab.lang.correction.ReplaceIdentifierCorrection

            throw(MException(message('MATLAB:table:UndefinedSortFunction',class(t))) ...

            	.addCorrection(ReplaceIdentifierCorrection('sort','sortrows')));

        end

    end % hidden methods block

    methods(Abstract, Hidden, Static)

        t = empty(varargin)

        % These functions are for internal use only and will change in a

        % future release.  Do not use these functions.

        t = fromScalarStruct(s)

        t = init(vars, numRows, rowLabels, numVars, varnames)

    end % abstract hidden static methods block

    methods(Access = 'protected')

        t = setDescription(t,newDescr)

        t = setUserData(t,newData)

        [varargout] = subsrefParens(t,s)

        [varargout] = subsrefBraces(t,s)

        [varargout] = subsrefDot(t,s)

        t = subsasgnParens(t,s,b,creating,deleting)

        t = subsasgnBraces(t,s,b)

        t = subsasgnDot(t,s,b,deleting)

        b = extractData(t,vars,like,a)

        t = replaceData(t,x,vars)

        varIndices = getVarOrRowLabelIndices(t,varSubscripts,allowEmptyRowLabels)

        varData = getVarOrRowLabelData(t,varIndices,warnMsg)

        [group,glabels,glocs] = table2gidx(a,avars,reduce)

        varIndex = subs2indsErrorHandler(a,varName,ME,callerID)

        function errID = throwSubclassSpecificError(~,msgid,varargin)

            % THROWSUBCLASSSPECIFICERROR is called by overloads in the subclasses and returns an

            % MException that is specific to the subclass which can then be returned to the

            % caller or thrown.

            try

                errID = MException(message(['MATLAB:' msgid],varargin{:}));

            catch ME

                if strcmp(ME.identifier,'MATLAB:builtins:MessageNotFound')

                    % This function should never be called with a non-existent ID

                    assert(false);

                else

                    rethrow(ME);

                end

            end

        end

        function t = initInternals(t, vars, nrows, rowLabels, nvars, varnames)

            % INITINTERNALS Fills an empty tabular object with data and dimension objects. This

            % function is for internal use only and will change in a future release.  Do not use

            % this function.

            try

                t.rowDim = t.rowDim.createLike(nrows,rowLabels);

                t.varDim = t.varDim.createLike(nvars,varnames); % error if invalid, duplicate, or empty

                t.data(1,1:nvars) = vars; % force 1xN, and hard error if vars is the wrong length

            catch ME

                throwAsCaller(ME)

            end

        end

        function t = rmPerTableProperty(t, names)

            t.arrayProps.TableCustomProperties = rmfield(t.arrayProps.TableCustomProperties, names);

        end

        function t = setPerTableProperty(t, newProps,name)

            t.arrayProps.TableCustomProperties.(name) = newProps;

        end

    end % protected methods block

    methods(Abstract, Access = 'protected')

        b = cloneAsEmpty(a)

        % Used by summary method

        rowLabelsStruct = summarizeRowLabels(t);

        printRowLabelsSummary(t,rowLabelsStruct);

        % Used by varfun and rowfun

        id = specifyInvalidOutputFormatID(t,funName);

    end % abstract protected methods block

    methods(Access = 'private')

        varIndex = getGroupingVarOrTime(t,varName)

        [varargout] = getProperty(t,name,createIfEmpty)

        t = setProperty(t,name,p) 

        t = lengthenTo(t,newLen)

    end

    methods (Static, Hidden)

        vars = container2vars(c)

        t = primitiveHorzcat(t,varargin)

        b = lengthenVar(a,n)

        function name = matlabCodegenRedirect(~)

            % Use the implementation in the class below when generating

            % code.

            name = 'matlab.internal.coder.tabular';

        end

    end % static hidden methods block

    methods(Static, Access = 'protected')

        [ainds,binds] = table2midx(a,b)

        [leftKeys,rightKeys] = joinKeys(a,b,keys,leftKeys,rightKeys,supplied)

        [leftVars,rightVars,leftVarDim,rightVarDim,leftKeyVals,rightKeyVals,leftKeys,rightKeys] ...

                = joinUtil(a,b,type,leftTableName,rightTableName, ...

                           keys,leftKeys,rightKeys,leftVars,rightVars,keepOneCopy,supplied,merge)

        [c,il,ir] = joinInnerOuter(a,b,leftOuter,rightOuter,leftKeyvals,rightKeyvals, ...

                                   leftVars,rightVars,leftKeys,rightKeys,leftVarnames,rightVarnames, ...

                                   mergeKeyProps)

        a_arrayProps = mergeArrayProps(a_arrayProps,b_arrayProps) % Used by both table and timetable

        function [numVars, numRows] = countVarInputs(args,StringParamNameNotSupportedErrID)

        %COUNTVARINPUTS Count the number of data vars from a tabular input arg list

            import matlab.internal.datatypes.isCharString

            argCnt = 0;

            numVars = 0;

            numRows = 0;

            while argCnt < length(args)

                argCnt = argCnt + 1;

                arg = args{argCnt};

                if isCharString(arg) % Matches any character row vector (including ''), not just a parameter name

                    % Put that one back and start processing param name/value pairs

                    argCnt = argCnt - 1; %#ok<NASGU>

                    break

                elseif isa(arg,'function_handle')

                    throwAsCaller(MException(message('MATLAB:table:FunAsVariable')));

                else % an array that will become a variable in t

                    numVars = numVars + 1;

                end

                numRows_j = size(arg,1);

                if argCnt == 1

                    numRows = numRows_j;

                elseif ~isequal(numRows_j,numRows)

                    ME = MException(message('MATLAB:table:UnequalVarLengths'));

                    if isstring(arg) && isscalar(arg) && numRows > 1

                        % A scalar string following inputs with more than one row

                        % is likely intended as a parameter name, give a helpful

                        % error.

                        cause = MException(message(StringParamNameNotSupportedErrID,arg));

                        ME = ME.addCause(cause);

                    end

                    throwAsCaller(ME);

                end

            end % while argCnt < numArgs, processing individual vars

        end

        function [nrows,nvars] = validateVarHeights(vars)

        %VALIDATEVARROWS Validate a cell array of prospective table variables

            nvars = length(vars);

            if nvars > 0

                % Check that variables are the same height.

                nrows = size(vars{1},1);

                for i = 1:nvars

                    if size(vars{i},1) ~= nrows

                        error(message('MATLAB:table:UnequalFieldLengths'));

                    end

                end

            else

                nrows = 0;

            end

        end

        function vars = createVariables(types,sz)

            % Create variables of the specified types, of the specified height,

            % for a preallocated table, filled with each type's default value.

            nrows = sz(1);

            nvars = sz(2);

            vars = cell(1,nvars); % a row vector

            for ii = 1:nvars

                type = types{ii};

                switch type

                case {'double' 'single' 'logical'}

                    vars{ii} = zeros(nrows,1,type);

                case {'doublenan' 'doubleNaN' 'singlenan' 'singleNaN'}

                    vars{ii} = NaN(nrows,1,extractBefore(lower(type),'nan'));

                case 'string'

                    vars{ii} = repmat(string(missing),nrows,1);

                case 'cell'

                    vars{ii} = cell(nrows,1);

                case 'datetime'

                    vars{ii} = datetime.fromMillis(NaN(nrows,1));

                case 'duration'

                    vars{ii} = duration.fromMillis(zeros(nrows,1));

                case 'calendarDuration'

                    vars{ii} = calendarDuration(zeros(nrows,1),0,0);

                case 'categorical'

                    vars{ii} = categorical(NaN(nrows,1));

                case {'int8' 'int16' 'int32' 'int64' 'uint8' 'uint16' 'uint32' 'uint64'}

                    vars{ii} = zeros(nrows,1,type);

                case {'cellstr' 'char'}

                    if strcmp(type,'char')

                        % Special case: replace 'char' with 'cellstr', with a warning. A char

                        % array is tempting but not a good choice for text data in a table.

                        matlab.internal.datatypes.warningWithoutTrace(message('MATLAB:table:PreallocateCharWarning'));

                    end

                    % cellstr is a special case that's not actually a type name.

                    vars{ii} = repmat({''},nrows,1);

                otherwise

                    if nrows > 0 % lengthenVar requires n > 0

                        % Use lengthenVar to create a var of the correct height. Not

                        % all types have their name as a constructor, e.g. double.

                        % So instead of creating a scalar instance to lengthen,

                        % create an empty instance.

                        try

                            % Create 0x0, lengthenVar will turn it into an Nx1, but

                            % would turn a 1x0 into an  Nx0 empty.

                            emptyVar = eval([type '.empty(0,0)']);

                        catch ME

                            throwAsCaller(preallocationClassErrorException(ME,type));

                        end

                        % lengthenVar creates an instance of var_ii that is nrows-by-1,

                        % filled in with the default (not necessarily "missing") value.

                        try

                            vars{ii} = tabular.lengthenVar(emptyVar,nrows);

                        catch

                            % lengthenVar failed, but we can still create an nrows-by-0 instance.

                            vars{ii} = eval([type '.empty(nrows,0)']); % don't use reshape, may not be one

                        end

                    else

                        try

                            vars{ii} = eval([type '.empty(0,1)']);

                        catch ME

                            throwAsCaller(preallocationClassErrorException(ME,type));

                        end

                    end

                end

            end

        end

        function s = handleFailedToLoadVars(s,numRows,numVars,varNames)

            % Detect if some variables failed to load and replace those

            % variables with numRows-by-0 empty double

            % Tabular variables always have the same consistent number of

            % rows. When a variable's number of rows is inconsistent with

            % numRows, the variable _must_ have failed to load properly --

            % likely because the class is not defined in loading session.

            % Replace data in failed-to-load variables with numRows-by-0

            % empty double to maintain integrity of the tabular instance

            isVarNumRowsMismatch = false(1,numVars);

            for i = 1:numVars

                isVarNumRowsMismatch(i) = (size(s.data{i},1)~=numRows);

            end

            if any(isVarNumRowsMismatch)

                s.data(isVarNumRowsMismatch) = {zeros(numRows,0)};

                if (nnz(isVarNumRowsMismatch)==1)

                    matlab.internal.datatypes.warningWithoutTrace(message('MATLAB:tabular:CannotLoadVariable',varNames{isVarNumRowsMismatch}));

                else

                    matlab.internal.datatypes.warningWithoutTrace(message('MATLAB:tabular:CannotLoadVariables'));

                end

            end

        end

    end % static protected methods block

    methods(Static, Access = 'private')

        name = matchPropertyName(name,propertyNames,exact)

        flag = setmembershipFlagChecks(varargin)

        args = processSetMembershipFlags(varargin)

        var = writetableMatricize(var)

    end % static private methods block

    %%%%% TEST HOOKS BLOCK allows unit testing for protected methods. %%%%%

    %%%%% Methods in this block are for internal use only and will change %

    %%%%% in a future release. Do not use these methods. %%%%%%%%%%%%%%%%%%

    methods(Access = ?matlab.unittest.TestCase)

        function b = extractDataTestHook(t,vars)

            b = extractData(t,vars);

        end

        function [group,glabels,glocs] = table2gidxTestHook(a, avars, reduce)

            if nargin < 3, reduce = true; end

            [group,glabels,glocs] = table2gidx(a,avars,reduce);

        end

    end

    methods(Static, Access = ?matlab.unittest.TestCase)

        function methodList = methodsWithNonTabularFirstArgument, methodList = {'cat','rowfun','varfun'}; end

    end % test hooks block

    %%%%% PERSISTENCE BLOCK ensures correct save/load across releases %%%%%

    %%%%% Properties and methods in this block maintain the exact class %%%

    %%%%% schema required for TABULAR to persist through MATLAB releases %%

    methods (Hidden)

        function s = saveobj(t,s)

            if (nargin == 1), s = struct; end

            s.CustomProps         = t.arrayProps.TableCustomProperties;

            s.VariableCustomProps = t.varDim.customProps;

        end

    end

end % classdef

%-----------------------------------------------------------------------------

function throwUndefinedError(obj,varargin)

st = dbstack;

name = regexp(st(2).name,'\.','split');

throwAsCaller(MException(message('MATLAB:table:UndefinedFunction',name{2},class(obj))));

end % function

%-----------------------------------------------------------------------------

function throwUndefinedTransposeError(obj)

import matlab.lang.correction.ReplaceIdentifierCorrection

st = dbstack;

name = regexp(st(2).name,'\.','split');

throwAsCaller(MException(message('MATLAB:table:UndefinedTransposeFunction',name{2},class(obj))) ...

	.addCorrection(ReplaceIdentifierCorrection(name{2},'rows2vars')));

end % function

%-----------------------------------------------------------------------------

function throwInvalidNumericConversion(obj,varargin)

import matlab.lang.correction.ReplaceIdentifierCorrection

st = dbstack;

name = regexp(st(2).name,'\.','split');

throwAsCaller(MException(message('MATLAB:table:InvalidNumericConversion',name{2},class(obj))) ...

    .addCorrection(ReplaceIdentifierCorrection(name{2},'table2array')));

end % function

%-----------------------------------------------------------------------------

function ME = preallocationClassErrorException(ME,type)

if strcmp(ME.identifier,'MATLAB:undefinedVarOrClass')

    theMatch = matlab.internal.language.introspective.safeWhich(type,false);

    if isempty(theMatch)

        ME = MException(message('MATLAB:table:PreAllocationUndefinedClass',type));

    else

        [~,theMatch,~] = fileparts(theMatch);

        ME = MException(message('MATLAB:table:PreAllocationClassnameCase',type,theMatch));

    end

else

    ME = MException(message('MATLAB:table:InvalidPreallocationVariableType',type,ME.message));

end

end % function