time | Calls | line |
---|
| | 1 | function [varargout] = parseArgsTabularConstructors(pnames,dflts,priority,StringParamNameNotSupportedErrID,varargin)
|
| | 2 | %PARSEARGSTABULARCONSTRUCTORS Process parameter name/value pairs for table/timetable constructors
|
| | 3 | % [A,B,...] = PARSEARGSTABULARCONSTRUCTORS(PNAMES,DFLTS,PRIORITY,ERRID,'NAME1',VAL1,'NAME2',VAL2,...)
|
| | 4 | % In typical use there are N output values, where PNAMES is a cell array of N
|
| | 5 | % valid parameter names, DFLTS is a cell array of N default values for these
|
| | 6 | % parameters, and PRIORITY is a vector of N integer priorities. The remaining
|
| | 7 | % arguments are parameter name/value pairs that were passed into the caller.
|
| | 8 | % The N outputs [A,B,...] are assigned in the same order as the names in
|
| | 9 | % PNAMES. Outputs corresponding to entries in PNAMES that are not specified in
|
| | 10 | % the name/value pairs are set to the corresponding value from DFLTS.
|
| | 11 | % Unrecognized name/value pairs are an error.
|
| | 12 | %
|
| | 13 | % PRIORITY is used for backwards compatibility to resolve ambiguous partial
|
| | 14 | % parameter name matches. Normally, PRIORITY is a vector of zeros. However, a
|
| | 15 | % caller may need to add a new parameter that creates the potential for a
|
| | 16 | % partial match against multiple parameter names. In that case, set PRIORITY
|
| | 17 | % to 1 for the existing parameter, and to 0 for the new parameter.
|
| | 18 | % PARSEARGSTABULARCONSTRUCTORS will resolve a partial match in favor of the
|
| | 19 | % existing parameter, preserving behavior of existing code that relied on
|
| | 20 | % artial matching. When adding two new parameters that create a partial match
|
| | 21 | % ambiguity among themselves, best practice would be to set their priority to
|
| | 22 | % zero to force a caller to specify parameter names unambiguously.
|
| | 23 | %
|
| | 24 | % ERRID is the caller-specific matlab:***:StringParamNameNotSupported error ID
|
| | 25 | % to be thrown when a string param name is found.
|
| | 26 | %
|
| | 27 | % [A,B,...,SETFLAG] = PARSEARGSTABULARCONSTRUCTORS(...), where SETFLAG is the
|
| | 28 | % N+1 output argument, also returns a structure with a field for each
|
| | 29 | % parameter name. The value of the field indicates whether that parameter was
|
| | 30 | % specified in the name/value pairs (true) or taken from the defaults (false).
|
| | 31 | %
|
| | 32 | % Example:
|
| | 33 | % args = {'Var' {'x' 'y'} 'Row' };
|
| | 34 | % pnames = {'Size' 'VariableTypes' 'VariableNames' 'RowNames' };
|
| | 35 | % dflts = { [] {} {} {} };
|
| | 36 | % partialMatchPriority = [0 0 1 0]; % prioritize VariableNames when partial matching, for backwards compatibility
|
| | 37 | % [sz, vartypes, varnames,rownames,supplied] ...
|
| | 38 | % = parseArgsTabularConstructors(pnames, dflts, partialMatchPriority, args{:});
|
| | 39 | % % On return, sz==[], vartypes=={}, varnames=={'x' 'y'}, rownames=={'a' 'b' 'c'},
|
| | 40 | % % supplied.VariableNames=true, and all other fields in supplied are set to false.
|
| | 41 |
|
| | 42 | % Copyright 2018-2019 The MathWorks, Inc.
|
| | 43 |
|
| | 44 | % Initialize some variables
|
< 0.001 | 2 | 45 | nparams = length(pnames);
|
< 0.001 | 2 | 46 | varargout = dflts;
|
< 0.001 | 2 | 47 | setflag = false(1,nparams);
|
< 0.001 | 2 | 48 | nargs = length(varargin);
|
| | 49 |
|
< 0.001 | 2 | 50 | SuppliedRequested = nargout > nparams;
|
| | 51 |
|
| | 52 | % Must have name/value pairs
|
< 0.001 | 2 | 53 | if mod(nargs,2)~=0
|
| | 54 | % This may have been caused by a char row intended as data. The caller can
|
| | 55 | % make a suggestion.
|
| | 56 | throwAsCaller(MException(message('MATLAB:table:parseArgs:WrongNumberArgs')));
|
< 0.001 | 2 | 57 | end
|
| | 58 |
|
| | 59 | % Process name/value pairs
|
< 0.001 | 2 | 60 | for j=1:2:nargs
|
< 0.001 | 6 | 61 | pname = varargin{j};
|
< 0.001 | 6 | 62 | if ischar(pname) && isrow(pname) && (numel(pname) > 0) % don't match ''
|
| | 63 | % OK
|
| | 64 | elseif isstring(pname) && isscalar(pname) && ~ismissing(pname)
|
| | 65 | throwAsCaller(MException(message(StringParamNameNotSupportedErrID,pname)));
|
| | 66 | else
|
| | 67 | throwAsCaller(MException(message('MATLAB:table:parseArgs:IllegalParamName')));
|
< 0.001 | 6 | 68 | end
|
| | 69 |
|
< 0.001 | 6 | 70 | mask = startsWith(pnames,pname,'IgnoreCase',true); % look for partial match
|
< 0.001 | 6 | 71 | if ~any(mask)
|
| | 72 | if j == 1
|
| | 73 | % If the unrecognized char row was the first thing, it may have
|
| | 74 | % been intended as data. Throw a more specific error to let the
|
| | 75 | % caller recognize this case and make a suggestion.
|
| | 76 | ME = MException(message('MATLAB:table:parseArgs:BadParamNamePossibleCharRowData',pname));
|
| | 77 | else
|
| | 78 | ME = MException(message('MATLAB:table:parseArgs:BadParamName',pname));
|
| | 79 | end
|
| | 80 | throwAsCaller(ME);
|
< 0.001 | 6 | 81 | elseif sum(mask) > 1
|
| | 82 | % Ambiguous partial match, check the priorities of the matches
|
| | 83 | matchPriority = priority(mask);
|
| | 84 | maxPriority = max(matchPriority);
|
| | 85 | if sum(matchPriority == maxPriority) > 1
|
| | 86 | % Multiple matches all have the highest priority, throw an error
|
| | 87 | throwAsCaller(MException(message('MATLAB:table:parseArgs:AmbiguousParamName',pname)));
|
| | 88 | else
|
| | 89 | % One of the partial matches has the unique highest priority,
|
| | 90 | % solving the ambiguity. Remove the other partial matches.
|
| | 91 | mask(mask & (priority ~= maxPriority)) = 0;
|
| | 92 | end
|
< 0.001 | 6 | 93 | end
|
< 0.001 | 6 | 94 | varargout{mask} = varargin{j+1};
|
< 0.001 | 6 | 95 | setflag(mask) = true;
|
< 0.001 | 6 | 96 | end
|
| | 97 |
|
| | 98 | % Return extra stuff if requested
|
< 0.001 | 2 | 99 | if SuppliedRequested
|
< 0.001 | 2 | 100 | for kk = 1:numel(pnames)
|
< 0.001 | 8 | 101 | supplied.(pnames{kk}) = setflag(kk);
|
< 0.001 | 8 | 102 | end
|
< 0.001 | 2 | 103 | varargout{nparams+1} = supplied;
|
< 0.001 | 2 | 104 | end
|
Other subfunctions in this file are not included in this listing.