Multiple Inputs and Outputs in Builder NE Type Safe APIs

Guest blogger Peter Webb returns with another in an occasional series of postings about application deployment.

Contents

Multiple Arguments with Varying Types

I've got a MATLAB function with multiple inputs and outputs that I'd like to call from C#. Though that may not seem like much of a challange, MATLAB processes function arguments very differently from C#, particularly optional arguments and multiple return values.

The behavior of my MATLAB function, polygonal, depends on both the number and types of the inputs. polygonal computes three different number sequences. Given an integer N for each sequence, it returns the Nth entry in each sequence. Only the first input (tN) is required; the other two are optional.

function [t, p, h] = polygonal(tN, pN, hN)

In typical MATLAB fashion, if any input is a vector of length K, polygonal returns K elements of that sequence. For each sequence, the numeric type of the input determines the numeric type of the output. If tN is int32, for example, polygonal returns an int32 t.

That's a lot of complexity wrapped up in a single function line. I count at least 36 different ways to call polygonal. How do we manage this complexity in C#? In a word: overloading.

Overloaded Functions and Parameter Order in a C# Interface

Generally speaking, a function is overloaded 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 of inputs and outputs. I've implemented five of polygonal's 36 overloads in C# to demonstrate how Builder NE matches C# function declarations to MATLAB functions.

The simplest of polygonal's overloads consists of one scalar double input and one scalar double output. In C#:

  double polygonal(double t);

Builder NE maps the first C# input, t to the first MATLAB input (tN, and note the names of the arguments are not considered in the matching process), and the first MATLAB output (t) to the C# function's return value.

Next, I'll declare a function to call polygonal with three scalar inputs, which produces three scalar outputs. Since C# does not permit multiple return values, Builder NE supports C# out parameters in their place.

 void polygonal(out double t, out double p, out double h,
                double tN, double pN, double hN);

In this function, the outputs appear first, followed by the inputs, and the return type is void. This form is perhaps closest to the structure of the MATLAB function, but Builder NE supports many others. You may map the first MATLAB output to the C# function's return value:

 double polygonal(out double p, out double h,
                  double tN, double pN, double hN);

out t has vanished, and the return type changed from void to double.

You may also interleave (mix) inputs and outputs. Here, I've placed each input before the output it produces:

 void polygonal(double tN, out double t, double pN, out double p,
                double hN, out double h);

Finally, remember that polygonal supports vector inputs and and outputs; here I've requested double[] vector outputs from from double[] vector inputs. In this function the outputs again appear before the inputs, as that's the style I prefer.

   void polygonal(out double[] t, out double[] p, out double[] h,
                  double[] tN, double[] pN, double[] hN);

Building and Running the Example

First, download the source code for this article from MATLAB Central.

As usual, the process of invoking polygonal through a type safe API consists of three steps:

Build the IFigurate interface DLL.

Create the Generator .NET assembly and the GeneratorIFigurate type safe interface.

Compile the main program, PolySeq, after referencing IFigurate and GenerateIFigurate in the PolySeq project.

The file ReadmeParameters.txt contains detailed instructions.

Make sure your runtime environment is set up correctly, and then run PolySeq\PolySeq\bin\Debug\PolySeq.exe. It calls polygonal through several of the C# interfaces described above and produces the following output:

The 17th triangular number:  153

The 13th triangular number:   91
The 11th pentagonal number:  176
The 19th hexagonal number :  703

   Polygonal Numbers
N:            3   6   9
-----------------------
Triangular:   6  21  45
Pentagonal:  12  51 117
Hexagonal :  15  66 153

You can generate the same numbers in MATLAB with three calls to polygonal:

 % 17th triangular number
 t = polygonal(17);

 % 13th triangular, 11th pentagonal and 19th hexagonal numbers
 [t, p, h] = polygonal(13, 11, 19);

 % 3rd, 6th, and 9th triangular, pentagonal and hexagonal numbers
 order = [3, 6, 9];
 [t, p, h] = polygonal(order, order, order);

Flexibile or Complicated?

What do you think of the parameter ordering and function overloading rules? Some of them were dictated by the structure of C# and MATLAB, but some resulted from usability testing and our design judgement. Are they too complicated, or just flexible enough? Let me know here.

Get the MATLAB code

Published with MATLAB® 7.12