{"id":280,"date":"2011-06-30T17:09:53","date_gmt":"2011-06-30T17:09:53","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/2011\/06\/30\/multiple-inputs-and-outputs-in-builder-ne-type-safe-apis\/"},"modified":"2011-06-20T17:11:04","modified_gmt":"2011-06-20T17:11:04","slug":"multiple-inputs-and-outputs-in-builder-ne-type-safe-apis","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2011\/06\/30\/multiple-inputs-and-outputs-in-builder-ne-type-safe-apis\/","title":{"rendered":"Multiple Inputs and Outputs in Builder NE Type Safe APIs"},"content":{"rendered":"<div xmlns:mwsh=\"https:\/\/www.mathworks.com\/namespace\/mcode\/v1\/syntaxhighlight.dtd\" class=\"content\">\r\n   <introduction>\r\n      <p>Guest blogger <a href=\"https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/4660\">Peter Webb<\/a> returns with another in an <a href=\"https:\/\/blogs.mathworks.com\/loren\/category\/deployment\/\">occasional series<\/a> of postings about application deployment.\r\n      <\/p>\r\n   <\/introduction>\r\n   <h3>Contents<\/h3>\r\n   <div>\r\n      <ul>\r\n         <li><a href=\"#1\">Multiple Arguments with Varying Types<\/a><\/li>\r\n         <li><a href=\"#2\">Overloaded Functions and Parameter Order in a C# Interface<\/a><\/li>\r\n         <li><a href=\"#3\">Building and Running the Example<\/a><\/li>\r\n         <li><a href=\"#4\">Flexibile or Complicated?<\/a><\/li>\r\n      <\/ul>\r\n   <\/div>\r\n   <h3>Multiple Arguments with Varying Types<a name=\"1\"><\/a><\/h3>\r\n   <p>I've got a <a href=\"https:\/\/www.mathworks.com\/products\/matlab\/\">MATLAB<\/a> <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2011a\/techdoc\/\/ref\/function.html\">function<\/a> with multiple inputs and outputs that I'd like to call from <a href=\"http:\/\/en.wikipedia.org\/wiki\/C_Sharp_%28programming_language%29\">C#<\/a>. Though that may not seem like much of a challange, MATLAB processes function arguments very differently from C#, particularly\r\n      optional arguments and multiple return values.\r\n   <\/p>\r\n   <p>The behavior of my MATLAB function, <tt>polygonal<\/tt>, depends on both the number and types of the inputs. <tt>polygonal<\/tt> computes <a href=\"http:\/\/en.wikipedia.org\/wiki\/Polygonal_number\">three different number<\/a> sequences. Given an integer N for each sequence, it returns the Nth entry in each sequence. Only the first input (<tt>tN<\/tt>) is required; the other two are optional.\r\n   <\/p><pre>function [t, p, h] = polygonal(tN, pN, hN)<\/pre><p>In typical MATLAB fashion, if any input is a vector of length K, <tt>polygonal<\/tt> returns K elements of that sequence. For each sequence, the numeric type of the input determines the numeric type of the\r\n      output. If <tt>tN<\/tt> is <tt>int32<\/tt>, for example, <tt>polygonal<\/tt> returns an <tt>int32<\/tt> <tt>t<\/tt>.\r\n   <\/p>\r\n   <p>That's a lot of complexity wrapped up in a single function line. I count at least 36 different ways to call <tt>polygonal<\/tt>. How do we manage this complexity in C#? In a word: <a href=\"http:\/\/en.wikipedia.org\/wiki\/Method_overloading\"><i>overloading<\/i><\/a>.\r\n   <\/p>\r\n   <h3>Overloaded Functions and Parameter Order in a C# Interface<a name=\"2\"><\/a><\/h3>\r\n   <p>Generally speaking, a function is <i>overloaded<\/i> if you can call it with different numbers or types of inputs and outputs. In C#, you must write a new function for each set\r\n      of inputs and outputs. I've implemented five of <tt>polygonal<\/tt>'s 36 overloads in C# to demonstrate how Builder NE matches C# function declarations to MATLAB functions.\r\n   <\/p>\r\n   <p>The simplest of <tt>polygonal<\/tt>'s overloads consists of one scalar double input and one scalar double output. In C#:\r\n   <\/p><pre>  double polygonal(double t);<\/pre><p><a href=\"https:\/\/www.mathworks.com\/products\/netbuilder\/\">Builder NE<\/a> maps the first C# input, <tt>t<\/tt> to the first MATLAB input (<tt>tN<\/tt>, and note the names of the arguments are not considered in the matching process), and the first MATLAB output (<tt>t<\/tt>) to the C# function's return value.\r\n   <\/p>\r\n   <p>Next, I'll declare a function to call <tt>polygonal<\/tt> with three scalar inputs, which produces three scalar outputs. Since C# does not permit multiple return values, Builder NE\r\n      supports C# <a href=\"http:\/\/msdn.microsoft.com\/en-us\/library\/t3c3bfhx%28v=vs.80%29.aspx\"><tt>out<\/tt> parameters<\/a> in their place.\r\n   <\/p><pre> void polygonal(out double t, out double p, out double h,\r\n                double tN, double pN, double hN);<\/pre><p>In this function, the outputs appear first, followed by the inputs, and the return type is void. This form is perhaps closest\r\n      to the structure of the MATLAB function, but Builder NE supports many others. You may map the first MATLAB output to the C#\r\n      function's return value:\r\n   <\/p><pre> double polygonal(out double p, out double h,\r\n                  double tN, double pN, double hN);<\/pre><p><tt>out t<\/tt> has vanished, and the return type changed from <tt>void<\/tt> to <tt>double<\/tt>.\r\n   <\/p>\r\n   <p>You may also interleave (mix) inputs and outputs. Here, I've placed each input before the output it produces:<\/p><pre> void polygonal(double tN, out double t, double pN, out double p,\r\n                double hN, out double h);<\/pre><p>Finally, remember that <tt>polygonal<\/tt> supports vector inputs and and outputs; here I've requested <tt>double[]<\/tt> vector outputs from from <tt>double[]<\/tt> vector inputs. In this function the outputs again appear before the inputs, as that's the style I prefer.\r\n   <\/p><pre>   void polygonal(out double[] t, out double[] p, out double[] h,\r\n                  double[] tN, double[] pN, double[] hN);<\/pre><h3>Building and Running the Example<a name=\"3\"><\/a><\/h3>\r\n   <p>First, <a href=\"https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/31292-multiple-inputs-and-outputs-in-builder-ne-type-safe-apis\">download the source code<\/a> for this article from MATLAB Central.\r\n   <\/p>\r\n   <p>As usual, the process of invoking <tt>polygonal<\/tt> through a type safe API consists of three steps:\r\n   <\/p>\r\n   <li>Build the <tt>IFigurate<\/tt> interface DLL.\r\n   <\/li>\r\n   <li>Create the <tt>Generator<\/tt> .NET assembly and the <tt>GeneratorIFigurate<\/tt> type safe interface.\r\n   <\/li>\r\n   <li>Compile the main program, <tt>PolySeq<\/tt>, after referencing <tt>IFigurate<\/tt> and <tt>GenerateIFigurate<\/tt> in the <tt>PolySeq<\/tt> project.\r\n   <\/li>\r\n   <p>The file <tt>ReadmeParameters.txt<\/tt> contains detailed instructions.\r\n   <\/p>\r\n   <p>Make sure your <a href=\"https:\/\/www.mathworks.com\/help\/releases\/R2011a\/toolbox\/dotnetbuilder\/ug\/bsm79a4.html#bskp1yb\">runtime environment<\/a> is set up correctly, and then run <tt>PolySeq\\PolySeq\\bin\\Debug\\PolySeq.exe<\/tt>. It calls <tt>polygonal<\/tt> through several of the C# interfaces described above and produces the following output:\r\n   <\/p><pre>The 17th triangular number:  153<\/pre><pre>The 13th triangular number:   91\r\nThe 11th pentagonal number:  176\r\nThe 19th hexagonal number :  703<\/pre><pre>   Polygonal Numbers\r\nN:            3   6   9\r\n-----------------------\r\nTriangular:   6  21  45\r\nPentagonal:  12  51 117\r\nHexagonal :  15  66 153<\/pre><p>You can generate the same numbers in MATLAB with three calls to <tt>polygonal<\/tt>:\r\n   <\/p><pre> % 17th triangular number\r\n t = polygonal(17);<\/pre><pre> % 13th triangular, 11th pentagonal and 19th hexagonal numbers\r\n [t, p, h] = polygonal(13, 11, 19);<\/pre><pre> % 3rd, 6th, and 9th triangular, pentagonal and hexagonal numbers\r\n order = [3, 6, 9];\r\n [t, p, h] = polygonal(order, order, order);<\/pre><h3>Flexibile or Complicated?<a name=\"4\"><\/a><\/h3>\r\n   <p>What do you think of the parameter ordering and function overloading rules? Some of them were dictated by the structure of\r\n      C# and MATLAB, but some resulted from usability testing and our design judgement. Are they too complicated, or just flexible\r\n      enough? Let me know <a href=\"https:\/\/blogs.mathworks.com\/loren\/?p=280#respond\">here<\/a>.\r\n   <\/p><script language=\"JavaScript\">\r\n<!--\r\n\r\n    function grabCode_d31832440d67473d8bc661668f81ff71() {\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='d31832440d67473d8bc661668f81ff71 ' + '##### ' + 'SOURCE BEGIN' + ' #####';\r\n        t2='##### ' + 'SOURCE END' + ' #####' + ' d31832440d67473d8bc661668f81ff71';\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        author = 'Peter Webb';\r\n        copyright = 'Copyright 2011 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 author and copyright lines at the bottom if specified.\r\n        if ((author.length > 0) || (copyright.length > 0)) {\r\n            d.writeln('');\r\n            d.writeln('%%');\r\n            if (author.length > 0) {\r\n                d.writeln('% _' + author + '_');\r\n            }\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      \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_d31832440d67473d8bc661668f81ff71()\"><span style=\"font-size: x-small;        font-style: italic;\">Get \r\n            the MATLAB code \r\n            <noscript>(requires JavaScript)<\/noscript><\/span><\/a><br><br>\r\n      Published with MATLAB&reg; 7.12<br><\/p>\r\n<\/div>\r\n<!--\r\nd31832440d67473d8bc661668f81ff71 ##### SOURCE BEGIN #####\r\n%% Multiple Inputs and Outputs in Builder NE Type Safe APIs\r\n% Guest blogger \r\n% <https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/authors\/4660 \r\n% Peter Webb> returns with another in an \r\n% <https:\/\/blogs.mathworks.com\/loren\/category\/deployment\/ occasional \r\n% series> of postings about application deployment. \r\n\r\n%% Multiple Arguments with Varying Types\r\n% I've got a <https:\/\/www.mathworks.com\/products\/matlab\/ MATLAB>\r\n% <https:\/\/www.mathworks.com\/help\/releases\/R2011a\/techdoc\/\/ref\/function.html \r\n% function> with multiple inputs and outputs that I'd like\r\n% to call from <http:\/\/en.wikipedia.org\/wiki\/C_Sharp_%28programming_language%29 \r\n% C#>. Though that may not seem like much of a challange,\r\n% MATLAB processes function arguments very differently from C#, particularly\r\n% optional arguments and multiple return values. \r\n%\r\n% The behavior of my MATLAB function, |polygonal|, depends on both the number\r\n% and types of the inputs. |polygonal| computes \r\n% <http:\/\/en.wikipedia.org\/wiki\/Polygonal_number three different number> \r\n% sequences. Given an integer N for each sequence, it returns the Nth \r\n% entry in each sequence. Only the first input (|tN|) is required; the other\r\n% two are optional.\r\n% \r\n%  function [t, p, h] = polygonal(tN, pN, hN)\r\n%\r\n% In typical MATLAB fashion, if any input is a vector of length K,\r\n% |polygonal| returns K elements of that sequence. For each sequence, the \r\n% numeric type of the input determines the numeric type of the output. If \r\n% |tN| is |int32|, for example, |polygonal| returns an |int32| |t|. \r\n%\r\n% That's a lot of complexity wrapped up in a single function line. I count\r\n% at least 36 different ways to call |polygonal|. How do we manage this \r\n% complexity in C#? In a word: <http:\/\/en.wikipedia.org\/wiki\/Method_overloading\r\n% _overloading_>.\r\n\r\n%% Overloaded Functions and Parameter Order in a C# Interface\r\n% Generally speaking, a function is _overloaded_ if you can call it with\r\n% different numbers or types of inputs and outputs. In C#,\r\n% you must write a new function for each set of inputs and outputs. \r\n% I've implemented five of |polygonal|'s 36 overloads in C# to demonstrate \r\n% how Builder NE matches C# function declarations to MATLAB functions. \r\n%\r\n% The simplest of |polygonal|'s overloads consists of one scalar double\r\n% input and one scalar double output. In C#:\r\n%\r\n%    double polygonal(double t);\r\n%\r\n% <https:\/\/www.mathworks.com\/products\/netbuilder\/ Builder NE>\r\n% maps the first C# input, |t| to the first MATLAB input (|tN|, \r\n% and note the names of the arguments are not considered in the matching\r\n% process), and the first MATLAB output (|t|) to the C# function's return\r\n% value. \r\n%\r\n% Next, I'll declare a function to call |polygonal| with three scalar\r\n% inputs, which produces three scalar outputs. Since C# does not permit \r\n% multiple return values, Builder NE supports C# \r\n% <http:\/\/msdn.microsoft.com\/en-us\/library\/t3c3bfhx%28v=vs.80%29.aspx\r\n% |out| parameters> in their place.\r\n%\r\n%   void polygonal(out double t, out double p, out double h, \r\n%                  double tN, double pN, double hN);\r\n%\r\n% In this function, the outputs appear first, followed by the inputs, and\r\n% the return type is void. This form is perhaps closest to the structure of\r\n% the MATLAB function, but Builder NE supports many others. You may map\r\n% the first MATLAB output to the C# function's return value:\r\n%\r\n%   double polygonal(out double p, out double h, \r\n%                    double tN, double pN, double hN);\r\n%\r\n% |out t| has vanished, and the return type changed from |void| to |double|.\r\n%\r\n% You may also interleave (mix) inputs and outputs.\r\n% Here, I've placed each input before the output it produces:\r\n%\r\n%   void polygonal(double tN, out double t, double pN, out double p,\r\n%                  double hN, out double h);\r\n%\r\n% Finally, remember that |polygonal| supports vector inputs and and\r\n% outputs; here I've requested |double[]| vector outputs from from\r\n% |double[]| vector inputs. In this function the outputs again appear\r\n% before the inputs, as that's the style I prefer.\r\n%\r\n%     void polygonal(out double[] t, out double[] p, out double[] h,\r\n%                    double[] tN, double[] pN, double[] hN);\r\n\r\n\r\n%% Building and Running the Example\r\n% First,\r\n% <https:\/\/www.mathworks.com\/matlabcentral\/fileexchange\/31292-multiple-inputs-and-outputs-in-builder-ne-type-safe-apis \r\n% download the source code> for this article from MATLAB Central.\r\n% \r\n% As usual, the process of invoking |polygonal| through a type safe API \r\n% consists of three steps:\r\n%\r\n% # Build the |IFigurate| interface DLL.\r\n% # Create the |Generator| .NET assembly and the |GeneratorIFigurate| type\r\n% safe interface.\r\n% # Compile the main program, |PolySeq|, after referencing |IFigurate| and\r\n% |GenerateIFigurate| in the |PolySeq| project.\r\n%\r\n% The file |ReadmeParameters.txt| contains detailed instructions.\r\n%\r\n% Make sure your \r\n% <https:\/\/www.mathworks.com\/help\/releases\/R2011a\/toolbox\/dotnetbuilder\/ug\/bsm79a4.html#bskp1yb \r\n% runtime environment> is set up correctly, and then run\r\n% |PolySeq\\PolySeq\\bin\\Debug\\PolySeq.exe|. It calls |polygonal| through\r\n% several of the C# interfaces described above and produces the following\r\n% output:\r\n%\r\n%  The 17th triangular number:  153\r\n%  \r\n%  The 13th triangular number:   91\r\n%  The 11th pentagonal number:  176\r\n%  The 19th hexagonal number :  703\r\n%  \r\n%     Polygonal Numbers\r\n%  N:            3   6   9\r\n%  REPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASHREPLACE_WITH_DASH_DASH-\r\n%  Triangular:   6  21  45\r\n%  Pentagonal:  12  51 117\r\n%  Hexagonal :  15  66 153\r\n% \r\n% You can generate the same numbers in MATLAB with three calls to\r\n% |polygonal|:\r\n%\r\n%   % 17th triangular number\r\n%   t = polygonal(17);    \r\n%\r\n%   % 13th triangular, 11th pentagonal and 19th hexagonal numbers\r\n%   [t, p, h] = polygonal(13, 11, 19);   \r\n%\r\n%   % 3rd, 6th, and 9th triangular, pentagonal and hexagonal numbers\r\n%   order = [3, 6, 9];\r\n%   [t, p, h] = polygonal(order, order, order);\r\n\r\n%% Flexibile or Complicated?\r\n% What do you think of the parameter ordering and function overloading \r\n% rules? Some of them were dictated by the structure of C# and MATLAB, but\r\n% some resulted from usability testing and our design judgement. Are they\r\n% too complicated, or just flexible enough? Let me know\r\n% <https:\/\/blogs.mathworks.com\/loren\/?p=280#respond here>.\r\n\r\n##### SOURCE END ##### d31832440d67473d8bc661668f81ff71\r\n-->","protected":false},"excerpt":{"rendered":"<p>\r\n   \r\n      Guest blogger Peter Webb returns with another in an occasional series of postings about application deployment.\r\n      \r\n   \r\n   Contents\r\n   \r\n      \r\n   ... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2011\/06\/30\/multiple-inputs-and-outputs-in-builder-ne-type-safe-apis\/\">read more >><\/a><\/p>","protected":false},"author":39,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[24],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/280"}],"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=280"}],"version-history":[{"count":0,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/280\/revisions"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=280"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=280"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=280"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}