Using the C Math Library

Getting Started

Introduction

Who Should Read This Book

MATLAB C Math Library Features

Unsupported MATLAB Features

Library Routine Naming Convention

MATLAB C Math Library Documentation

How This Book Is Organized

Accessing Online Reference Documentation

Additional Sources of Information

Installing the MATLAB C Math Library

Installation with MATLAB

Installation Without MATLAB

Verifying a UNIX Installation

Verifying a PC Installation

Writing and Building Programs

Introduction 

Example - Writing a Simple Program

Output

Building Stand-Alone C Applications 

Packaging Stand-Alone Applications

Overview 

Compiler Options Files

Building UNIX Applications  

Configuring the Build Environment 

Locating Options Files

Using the System Compiler

Changing the Default Compiler

Modifying the Options File

Temporarily Changing the Compiler

Building an Application 

Locating Shared Libraries

Running Your Application

mbuild Options

Building Microsoft Windows Applications  

Configuring the Build Environment 

Locating Options Files

Systems with Exactly One C/C++ Compiler

Systems with More than One Compiler

Changing the Default Compiler

Modifying the Options File

Combining Customized C and C++ Options Files

Temporarily Changing the Compiler

Building an Application 

Shared Libraries (DLLs)

Running Your Application

mbuild Options

Distributing Stand-Alone Applications

Packaging the MATLAB Math Run-Time Libraries

Installing Your Application

On UNIX Systems

On PCs

Problem Starting Stand-Alone Application

Building Shared Libraries  

Troubleshooting mbuild 

Options File Not Writable

Directory or File Not Writable

mbuild Generates Errors

Compiler and/or Linker Not Found

mbuild Not a Recognized Command

Cannot Locate Your Compiler (PC)

Internal Error When Using mbuild -setup (PC)

Verification of mbuild Fails

Linking Applications Without mbuild 

Working with MATLAB Arrays

Introduction

Supported MATLAB Array Types

MATLAB Array C Data Type

Numeric Arrays

Creating Numeric Arrays

Using Numeric Array Creation Routines

Creating Numeric Arrays by Calling Arithmetic Routines

Creating Numeric Arrays by Concatenation

Creating Numeric Arrays by Assignment

Initializing a Numeric Array with Data

Column-Major Storage versus Row-Major Storage

Example Program: Creating Numeric Arrays (ex1.c)

Sparse Matrices

Creating a Sparse Matrix

Converting an Existing Matrix into Sparse Format

Creating a Sparse Matrix from Data

Converting a Sparse Matrix to Full Matrix Format

Evaluating Arrays for Sparse Storage

Character Arrays

Creating MATLAB Character Arrays

Using Explicit Character Array Creation Routines

Converting Numeric Arrays to Character Arrays

Creating Multidimensional Arrays of Strings

Accessing Individual Strings in an Array of Strings

Cell Arrays

Creating Cell Arrays

Using the Cell Array Creation Routine

Using Cell Array Conversion Routines

Using Concatenation to Create Cell Arrays

Using Assignment to Create Cell Arrays

Displaying the Contents of a Cell Array

MATLAB Structures

Creating Structures

Using a Structure Creation Routine

Creating Multidimensional Arrays of Structures

Using a Structure Conversion Routine

Using Assignment to Create Structures

Performing Common Array Programming Tasks

Allocating and Freeing MATLAB Arrays

Displaying MATLAB Arrays

Formatting Output

Determining Array Type

Determining Array Size

Length of a Single Dimension

Dimension Return Values

Determining Array Shape

Managing Array Memory

Introduction

Automated Versus Explicit Memory Management 

Explicit Memory Management 

Automated Memory Management

Temporary and Bound Arrays

Comparison of Memory Management Schemes

Benefits of Automated Memory Management

Compatibility Between Memory Management Schemes

Avoiding Memory Leaks in Your Functions

Using Automated Memory Management

Function Template

Main Routine Template

Enabling Memory Management 

Creating Bound Arrays

Assigning Arrays to mxArray* Variables 

Assigning a Value to an Array Destroys Its Previous Value

Assignment by Value

Nesting Calls to Functions that Return Arrays

Deleting Bound Arrays 

Restoring the Previous Context 

Arguments to mlfRestorePreviousContext( )

What Happens to the Array Arguments?

Purpose of mlfRestorePreviousContext( )

Returning an Array 

Argument and Return for mlfReturnValue( )

Changing Bound Arrays to Temporary Arrays

Handling Return Values

Example - Managing Array Memory (ex2.c) 

Example Without Automated Memory Management

Restrictions 

Recommendation

Replacing Allocation and Deallocation Routines

Indexing into Arrays

Introduction

Terminology

Indexing Functions

Array Storage

Calling the Indexing Functions 

Specifying the Target Array

Specifying the Index String

What an Indexing String Specifies

Complex Indexing Expressions

Nesting Indexing Operations

Specifying the Values for Indices

Specifying a Source Array for Assignments

Assumptions for the Code Examples

One-Dimensional Indexing

Overview 

Selecting a Single Element 

Selecting a Vector 

Specifying a Vector Index with mlfEnd()

Selecting a Matrix 

Selecting the Entire Matrix As a Column Vector 

N-Dimensional Indexing

Overview 

Selecting a Single Element 

Selecting a Vector of Elements 

Specifying a Vector Index with mlfEnd( )

Selecting a Row or Column

Selecting a Matrix 

Selecting Entire Rows or Columns

Selecting an Entire Matrix

Extending Two-Dimensional Indexing to N Dimensions 

Logical Indexing

Overview 

Using a Logical Matrix as a One-Dimensional Index

Using Two Logical Vectors as Indices

Using One Colon Index and One Logical Vector as Indices

Using a Scalar and a Logical Vector

Extending Logical Indexing to N Dimensions

Assigning Values to Array Elements

Overview

Assigning to a Single Element 

Assigning to Multiple Elements 

Assigning to a Subarray 

Assigning to All Elements 

Extending Two-Dimensional Assignment to N Dimensions 

Deleting Array Elements

Deleting Multiple Elements

Cell Array Indexing

Overview

Tips for Working with Cell Arrays

Referencing a Cell in a Cell Array 

Referencing a Subset of a Cell Array 

Referencing the Contents of a Cell 

Referencing a Subset of the Contents of a Cell 

Indexing Nested Cell Arrays

Indexing the First Level

Indexing the Second Level

Assigning Values to a Cell Array  

Deleting Elements from a Cell Array

Deleting a Single Element

Deleting an Entire Dimension

Structure Array Indexing

Overview 

Tips for Working with Structure Arrays

Accessing a Field 

Accessing the Contents of a Structure Field 

Assigning Values to a Structure Field 

Assigning Values to Elements in a Field 

Referencing a Single Structure in a Structure Array

Referencing into Nested Structures

Accessing the Contents of Structures Within Cells

Deleting Elements from a Structure Array

Deleting a Structure from the Array

Deleting a Field from All the Structures in an Array

Deleting an Element from an Array Contained by a Field

Comparison of C and MATLAB Indexing Syntax 

Calling Library Routines

Introduction 

How to Call MATLAB Functions  

One Output Argument and Only Required Input Arguments

Optional Input Arguments

Optional Output Arguments

Optional Input and Output Arguments

Variable Input Arguments

Pure Varargin Functions

Variable Output Arguments

Constructing an mlfVarargoutList

Pure Varargout Functions

Summary of Library Calling Conventions

Exceptions to the Calling Conventions

Example - Calling Library Routines (ex3.c)

Calling Operators   

Passing Functions As Arguments to Library Routines

How Function-Functions Use mlfFeval( )

How mlfFeval() Works

Extending the mlfFeval() Table

Writing a Thunk Function

Example - Passing Functions As Arguments (ex4.c)

Output

Replacing Argument Lists with a Cell Array

Positioning the Indexed Cell Array

Exception for Built-In Library Functions

Importing and Exporting Array Data

Introduction

Writing Data to a MAT-File

Reading Data from a MAT-File 

Example - Saving and Loading Data (ex5.c)

Handling Errors and Writing a Print Handler

Introduction

Error Handling Overview 

Customizing Error Handling 

Continuing Processing After Errors

Example - Defining Try/Catch Blocks (ex6.c)

Replacing the Default Library Error Handler 

Writing an Error Handler

Registering Your Error Handler

Example - Adding an Error Handler

Defining a Print Handler  

Providing Your Own Print Handler

Sending Output to a GUI

Example - Writing Output to X Windows/Motif

Example - Writing Output to Microsoft Windows

Library Routines

Introduction

Organization of the MATLAB Math Libraries

The MATLAB Built-In Library

General Purpose Commands

Operators and Special Functions

Elementary Matrices and Matrix Manipulation

Elementary Math Functions

Numerical Linear Algebra

Data Analysis and Fourier Transform Functions

Character String Functions

File I/O Functions

Data Types

Time and Dates

Multidimensional Array Functions

Cell Array Functions

Structure Functions

Sparse Matrix Functions

Utility Routines

MATLAB M-File Math Library

Operators and Special Functions

Elementary Matrices and Matrix Manipulation

Elementary Math Functions

Specialized Math Functions

Numerical Linear Algebra

Data Analysis and Fourier Transform Functions

Polynomial and Interpolation Functions

Function-Functions and ODE Solvers

Character String Functions

File I/O Functions

Time and Dates

Multidimensional Array Functions

Cell Array Functions

Structure Functions

Sparse Matrix Functions

Array Access and Creation Library

Directory Organization

Directory Organization on UNIX

<matlab>/bin

<matlab>/extern/lib/$ARCH

<matlab>/extern/include

<matlab>/extern/examples/cmath

Directory Organization on Microsoft Windows

<matlab>\bin

<matlab>\extern\include

<matlab>\extern\examples\cmath

Errors and Warnings

Introduction

Error Messages 

Warning Messages

Getting Started