Using the C Math Library

Example - Writing a Simple Program

This example application determines if two numbers are relatively prime; that is, the numbers share no common factors. While its function is trivial, the application serves well as an introduction to programming in C with the MATLAB C Math Library. The notes following the example highlight points of particular interest in the example and provide pointers to other sections in the documentation where specific topics are covered in more detail.

The source code for this example, named intro.c, is in the
<matlab>/extern/examples/cmath directory on UNIX systems, and in the <matlab>\extern\examples\cmath directory on PCs, where <matlab> represents the top-level directory of your installation. See Building Stand-Alone C Applications for information on building the examples.

/* intro.c*/

#include <stdio.h>
#include <stdlib.h> 
#include <string.h>
#include "matlab.h"                                      /* 1 */

int main()
{   
    double num1, num2;
    mxArray *volatile factors1 = NULL;                   /* 2 */
    mxArray *volatile factors2 = NULL;
    mxArray *volatile common_factors = NULL;

    mlfEnterNewContext(0,0);                             /* 3 */

    printf("Enter a number: ");                          /* 4 */
    scanf("%lf", &num1);
    printf("Enter a second number: ");
    scanf("%lf", &num2);

    mlfTry                                               /* 5 */
    {   
       mlfAssign(&factors1, mlfFactor(mlfScalar(num1))); /* 6 */
       mlfAssign(&factors2, mlfFactor(mlfScalar(num2)));

       mlfAssign(&common_factors,                        /* 7 */
          mlfIntersect(NULL, NULL, factors1, factors2, NULL));

       if (mlfTobool(mlfIsempty(common_factors)))        /* 8 */
          printf("%0.0lf and %0.0lf are relatively prime\n",
                   num1, num2);
       else
       {
          printf("%0.0lf and %0.0lf share common factor(s):", 
                   num1, num2);
          mlfPrintMatrix(common_factors);
       }
    } /* end mlfTry */
    mlfCatch                                             /* 9 */
    {
       mlfPrintf("In catch block: \n");
       mlfPrintMatrix(mlfLasterr(NULL)); 
    }
    mlfEndCatch 

    mxDestroyArray(factors1);                           /* 10 */
    mxDestroyArray(factors2);
    mxDestroyArray(common_factors);

    mlfRestorePreviousContext(0,0);                     /* 11 */
    return(EXIT_SUCCESS);
}

The numbered items in the list below correspond to the numbered comments in the code example:

1. Applications must include the file"matlab.h" which contains the declaration of the mxArray data structure and the prototypes for all the functions in the library. stdlib.h contains the definition of EXIT_SUCCESS.
2. Applications must declare pointers to any MATLAB arrays (mxArray *) explicitly used as variables. All arguments to MATLAB routines must be MATLAB arrays. In addition, the routines return newly allocated MATLAB arrays as output. These pointers are declared as volatile pointers because they are assigned values within a try block and so may change without warning due to an error. For more information about working with MATLAB arrays in C programs, see Chapter 3.
3. Applications must enable MATLAB C Math Library automated memory management by calling mlfEnterNewContext(). With the library memory management facility enabled, the library can delete the arrays it creates automatically. This allows you to compose functions; that is, nest one function call within another. For more information about automated memory management, see Chapter 4.
4. Applications can define a try block using the MATLAB C Math library macro, mlfTry. When a library function included in a try block encounters a run-time error, it outputs an error message and then passes control to a catch block in the program. In a catch block, an application can free arrays that have been assigned to variables or perform other processing before exiting. For more information about defining try and catch blocks, see Error Handling Overview.
5. This call to mlfScalar(), which converts the number input by the user from an integer to a MATLAB array, illustrates routine nesting. The application can use nesting because it only uses the array returned by mlfScalar() as input to mlfFactor(). With automated memory management enabled, the library frees the array after mlfFactor() is finished using it.

In contrast, because the example uses the array returned by mlfFactor() several times, it assigns this array to a variable, factors1, using the mlfAssign() routine. Any array that you assign to a variable, you must also free, using mxDestroyArray(). (Arrays returned as output arguments by library routines are implicitly assigned to the variables by the library and must also be destroyed.) For more information about assigning arrays to variables, see Chapter 4.

6. This call to mlfIntersect() illustrates how to call library routines that optional input arguments. The C Math library version of these functions include in their signatures all optional input and output arguments. If you do not use these optional arguments, you must pass NULL in their place. For more information about calling MATLAB C Math library routines, see Chapter 6.
7. The routine mlfIsempty() returns an array containing the value 1 (TRUE) if the array is empty and zero (FALSE) if the array contains data. However, because mlfIsempty() returns these values as MATLAB arrays, you cannot use the return value directly in the if statement. Instead, pass this return value to the mlfTobool() routine, which converts the return value to a standard C Boolean value.

You can also access individual elements in an array using standard MATLAB indexing syntax; however, the values returned by indexing are MATLAB arrays, not scalar values. For more information about indexing into arrays, see Chapter 5.

8. This call to the mlfCatch macro defines the start of the application's catch block. The call to the mlfEndCatch macro defines the end of the catch block. Catch blocks contain error handling code. This sample catch block calls the mlfLasterr() routine to retrieve the text of the error message associated with the last error and then outputs the message to the user. For more information about handling errors with try and catch blocks, see Chapter 8.
9. The application frees the MATLAB arrays that were assigned to variables using mlfAssign(). The library automatically frees arrays that were not assigned to variables. For example, the arrays returned by the nested calls to mlfScalar() are deleted automatically. The arrays assigned to factors1 and factors2 are not deleted automatically. For more information about assigning an array to a variable using the mlfAssign() routine, see Chapter 4.
10. The sample application ends by disabling automated memory management using the mlfRestorePreviousContext(). For more information about enabling automated memory management, see Chapter 4.

Output

This sample program, when run in a DOS Command Prompt window, produces the following output:

Enter a number: 333

Enter a second number: 444
333 and 444 share common factor(s): 3     37

A second run illustrates the alternate output:

Enter a number: 11

Enter a second number: 4
11 and 4 are relatively prime

Writing and Building Programs

Building Stand-Alone C Applications