{"id":695,"date":"2013-05-22T10:02:36","date_gmt":"2013-05-22T15:02:36","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/?p=695"},"modified":"2013-05-22T10:02:36","modified_gmt":"2013-05-22T15:02:36","slug":"duality-between-function-and-command-syntax","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2013\/05\/22\/duality-between-function-and-command-syntax\/","title":{"rendered":"Duality Between Function and Command Syntax"},"content":{"rendered":"\r\n<div class=\"content\"><!--introduction--><p>A long time ago, I <a href=\"https:\/\/blogs.mathworks.com\/loren\/2006\/05\/03\/command-and-function-syntaxes-in-matlab\/\">covered<\/a> the topic of the <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/command-vs-function-syntax.html\">duality<\/a> between command and function syntax.<\/p><!--\/introduction--><h3>Contents<\/h3><div><ul><li><a href=\"#95e9bd41-0a2d-4841-b33b-a58702bfa68a\">What is Command-Function Duality?<\/a><\/li><li><a href=\"#ed67cca9-63fb-4e7b-9feb-e92003842b2f\">Checking Directory Contents<\/a><\/li><li><a href=\"#fa6036a0-d510-41aa-bd3e-b32fadd81cbc\">Discussion of Results<\/a><\/li><li><a href=\"#5e24fab1-aece-4f0f-80b7-fdefdfbc94ca\">Default MATLAB Behavior<\/a><\/li><li><a href=\"#a3749eef-1b2d-43ff-b5fa-ec186a5307ec\">Overriding Default Behavior<\/a><\/li><li><a href=\"#8719954b-322c-4274-9618-d7cf3d37defd\">What About You?<\/a><\/li><\/ul><\/div><h4>What is Command-Function Duality?<a name=\"95e9bd41-0a2d-4841-b33b-a58702bfa68a\"><\/a><\/h4><p>For calling functions with only literal string input values, i.e., strings delimited by the usual single quote ('), you can avoid the overhead of using parentheses and comma separators to invoke the function, especially if you want either no output or only one output. Let me show you an example.<\/p><h4>Checking Directory Contents<a name=\"ed67cca9-63fb-4e7b-9feb-e92003842b2f\"><\/a><\/h4><p>Suppose I want to see the MATLAB code files in my directory beginning with the letter 'q'.  Here are three ways to do such a query.<\/p><p>First way:<\/p><pre class=\"codeinput\">dir <span class=\"string\">q*.m<\/span>\r\n<\/pre><pre class=\"codeoutput\">\r\nqichen31.m  quadvec.m   quantum.m   \r\n\r\n<\/pre><p>Second Way:<\/p><pre class=\"codeinput\">dir(<span class=\"string\">'q*.m'<\/span>)\r\n<\/pre><pre class=\"codeoutput\">\r\nqichen31.m  quadvec.m   quantum.m   \r\n\r\n<\/pre><p>Third Way:<\/p><pre class=\"codeinput\">out = dir(<span class=\"string\">'q*.m'<\/span>)\r\n<\/pre><pre class=\"codeoutput\">out = \r\n3x1 struct array with fields:\r\n    name\r\n    date\r\n    bytes\r\n    isdir\r\n    datenum\r\n<\/pre><h4>Discussion of Results<a name=\"fa6036a0-d510-41aa-bd3e-b32fadd81cbc\"><\/a><\/h4><p>From these three methods, you can see that the first two give the same output, a list of the names of matching files.  When using the command syntax (the first way), you can't store the output in a named variable. In this case, the decision was to print something out in a useful format, but not to place the information into a variable for further programmatic use.<\/p><p>The second result is equivalent to the first.  You can see the duality looking at these two statements.  The first and second are equivalent. Simply replace the space and following string (or strings) into a comma-separated list of the same string(s) inside parentheses.  This means that the statement <tt>myfun A B c<\/tt> is equivalent <tt>myfun('A','B','c')<\/tt>.<\/p><p>And now for the third statement.  Clearly it is different than the first two.  First, you can see that something is returned in the output variable <tt>out<\/tt>.  Second, you can see that <tt>out<\/tt> is not simply a list of names, but a <tt>struct<\/tt> containing several fields with information, including <tt>name<\/tt>, <tt>date<\/tt>, etc.<\/p><h4>Default MATLAB Behavior<a name=\"5e24fab1-aece-4f0f-80b7-fdefdfbc94ca\"><\/a><\/h4><p>MATLAB functions often return at least one output, even if the user does not supply an output variable. If the function does return an output when the user does not specify one, the result goes into a variable named <tt>ans<\/tt>.<\/p><h4>Overriding Default Behavior<a name=\"a3749eef-1b2d-43ff-b5fa-ec186a5307ec\"><\/a><\/h4><p>It is possible to override default behavior for your function outputs. To do so, we take advantage of the function <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/nargout.html\"><tt>nargout<\/tt><\/a>.  This function allows us to query how many output variables the function is called with. In the case of the function <tt>dir<\/tt>, you can imagine the logic of the code goes something like this:<\/p><div><ol><li>check nargout<\/li><li>if nargout is 0, get and print the list of matching files\/directories<\/li><li>if nargout is greater than 0, collect the relevant directory information and place it into a structure<\/li><\/ol><\/div><p>With the command form for calling a MATLAB function, the value for <tt>nargout<\/tt> is 0.  Despite this, some functions are designed to return a value, though without a specified output, <tt>ans<\/tt> is created or updated.<\/p><h4>What About You?<a name=\"8719954b-322c-4274-9618-d7cf3d37defd\"><\/a><\/h4><p>Do you take advantage of command-function duality?  In functions you create?  At the MATLAB prompt or in application code your write?  Let me know <a href=\"https:\/\/blogs.mathworks.com\/loren\/?p=695#respond\">here<\/a>.<\/p><script language=\"JavaScript\"> <!-- \r\n    function grabCode_301d91d2286a45ed81a02422c6b1209a() {\r\n        \/\/ Remember the title so we can use it in the new page\r\n        title = document.title;\r\n\r\n        \/\/ Break up these strings so that their presence\r\n        \/\/ in the Javascript doesn't mess up the search for\r\n        \/\/ the MATLAB code.\r\n        t1='301d91d2286a45ed81a02422c6b1209a ' + '##### ' + 'SOURCE BEGIN' + ' #####';\r\n        t2='##### ' + 'SOURCE END' + ' #####' + ' 301d91d2286a45ed81a02422c6b1209a';\r\n    \r\n        b=document.getElementsByTagName('body')[0];\r\n        i1=b.innerHTML.indexOf(t1)+t1.length;\r\n        i2=b.innerHTML.indexOf(t2);\r\n \r\n        code_string = b.innerHTML.substring(i1, i2);\r\n        code_string = code_string.replace(\/REPLACE_WITH_DASH_DASH\/g,'--');\r\n\r\n        \/\/ Use \/x3C\/g instead of the less-than character to avoid errors \r\n        \/\/ in the XML parser.\r\n        \/\/ Use '\\x26#60;' instead of '<' so that the XML parser\r\n        \/\/ doesn't go ahead and substitute the less-than character. \r\n        code_string = code_string.replace(\/\\x3C\/g, '\\x26#60;');\r\n\r\n        copyright = 'Copyright 2013 The MathWorks, Inc.';\r\n\r\n        w = window.open();\r\n        d = w.document;\r\n        d.write('<pre>\\n');\r\n        d.write(code_string);\r\n\r\n        \/\/ Add copyright line at the bottom if specified.\r\n        if (copyright.length > 0) {\r\n            d.writeln('');\r\n            d.writeln('%%');\r\n            if (copyright.length > 0) {\r\n                d.writeln('% _' + copyright + '_');\r\n            }\r\n        }\r\n\r\n        d.write('<\/pre>\\n');\r\n\r\n        d.title = title + ' (MATLAB code)';\r\n        d.close();\r\n    }   \r\n     --> <\/script><p style=\"text-align: right; font-size: xx-small; font-weight:lighter;   font-style: italic; color: gray\"><br><a href=\"javascript:grabCode_301d91d2286a45ed81a02422c6b1209a()\"><span style=\"font-size: x-small;        font-style: italic;\">Get \r\n      the MATLAB code <noscript>(requires JavaScript)<\/noscript><\/span><\/a><br><br>\r\n      Published with MATLAB&reg; R2013a<br><\/p><p class=\"footer\"><br>\r\n      Published with MATLAB&reg; R2013a<br><\/p><\/div><!--\r\n301d91d2286a45ed81a02422c6b1209a ##### SOURCE BEGIN #####\r\n%% Duality Between Function and Command Syntax\r\n% A long time ago, I \r\n% <https:\/\/blogs.mathworks.com\/loren\/2006\/05\/03\/command-and-function-syntaxes-in-matlab\/\r\n% covered> the topic of the\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/command-vs-function-syntax.html\r\n% duality> between command and function syntax.\r\n%% What is Command-Function Duality?\r\n% For calling functions with only literal string input values, i.e.,\r\n% strings delimited by the usual single quote ('), you can avoid the\r\n% overhead of using parentheses and comma separators to invoke the\r\n% function, especially if you want either no output or only one output.\r\n% Let me show you an example.\r\n%% Checking Directory Contents\r\n% Suppose I want to see the MATLAB code files in my directory beginning\r\n% with the letter 'q'.  Here are three ways to do such a query.\r\n%\r\n% First way:\r\ndir q*.m\r\n%%\r\n% Second Way:\r\ndir('q*.m')\r\n%%\r\n% Third Way:\r\nout = dir('q*.m')\r\n%% Discussion of Results\r\n% From these three methods, you can see that the first two give the same\r\n% output, a list of the names of matching files.  When using the command\r\n% syntax (the first way), you can't store the output in a named variable.\r\n% In this case, the decision was to print something out in a useful format,\r\n% but not to place the information into a variable for further programmatic\r\n% use.\r\n%\r\n% The second result is equivalent to the first.  You can see the duality\r\n% looking at these two statements.  The first and second are equivalent.\r\n% Simply replace the space and following string (or strings) into a\r\n% comma-separated list of the same string(s) inside parentheses.  This\r\n% means that the statement |myfun A B c| is equivalent\r\n% |myfun('A','B','c')|.\r\n%\r\n% And now for the third statement.  Clearly it is different than the first\r\n% two.  First, you can see that something is returned in the output\r\n% variable |out|.  Second, you can see that |out| is not simply a list of\r\n% names, but a |struct| containing several fields with information,\r\n% including |name|, |date|, etc.\r\n%% Default MATLAB Behavior\r\n% MATLAB functions often return at least one output, even if the user does\r\n% not supply an output variable. If the function does return an output when\r\n% the user does not specify one, the result goes into a variable named\r\n% |ans|.\r\n%% Overriding Default Behavior\r\n% It is possible to override default behavior for your function outputs. To\r\n% do so, we take advantage of the function\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/nargout.html |nargout|>.  This\r\n% function allows us to query how many output variables the function is\r\n% called with. In the case of the function |dir|, you can imagine the logic\r\n% of the code goes something like this:\r\n%\r\n% # check nargout\r\n% # if nargout is 0, get and print the list of matching files\/directories\r\n% # if nargout is greater than 0, collect the relevant directory\r\n% information and place it into a structure\r\n%%\r\n% With the command form for calling a MATLAB function, the value for\r\n% |nargout| is 0.  Despite this, some functions are designed to return a\r\n% value, though without a specified output, |ans| is created or updated.\r\n%% What About You?\r\n% Do you take advantage of command-function duality?  In functions you\r\n% create?  At the MATLAB prompt or in application code your write?  Let me\r\n% know <https:\/\/blogs.mathworks.com\/loren\/?p=695#respond here>.\r\n\r\n##### SOURCE END ##### 301d91d2286a45ed81a02422c6b1209a\r\n-->","protected":false},"excerpt":{"rendered":"<!--introduction--><p>A long time ago, I <a href=\"https:\/\/blogs.mathworks.com\/loren\/2006\/05\/03\/command-and-function-syntaxes-in-matlab\/\">covered<\/a> the topic of the <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/command-vs-function-syntax.html\">duality<\/a> between command and function syntax.... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2013\/05\/22\/duality-between-function-and-command-syntax\/\">read more >><\/a><\/p>","protected":false},"author":39,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[39,15],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/695"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/users\/39"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/comments?post=695"}],"version-history":[{"count":4,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/695\/revisions"}],"predecessor-version":[{"id":699,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/695\/revisions\/699"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=695"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=695"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=695"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}