® MATLAB C Math Library The Language of Technical Computing Computation Visualization Programming User’s Guide Version 2 How to Contact The MathWorks: ☎ 508-647-7000 Phone PHONE 508-647-7001 Fax FAX ✉ The MathWorks, Inc. Mail MAIL 24 Prime Park Way Natick, MA 01760-1500 http://www.mathworks.com Web INTERNET ftp.mathworks.com Anonymous FTP server comp.soft-sys.matlab Newsgroup @ [email protected] Technical support [email protected] Product enhancement suggestions [email protected] Bug reports [email protected] Documentation error reports [email protected] Subscribing user registration [email protected] Order status, license renewals, passcodes [email protected] Sales, pricing, and general information MATLAB C Math Library User’s Guide COPYRIGHT 1984 - 1999 by The MathWorks, Inc. The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or repro- duced in any form without prior written consent from The MathWorks, Inc. U.S. GOVERNMENT: If Licensee is acquiring the Programs on behalf of any unit or agency of the U.S. Government, the following shall apply: (a) For units of the Department of Defense: the Government shall have only the rights specified in the license under which the commercial computer software or commercial software documentation was obtained, as set forth in subparagraph (a) of the Rights in Commercial Computer Software or Commercial Software Documentation Clause at DFARS 227.7202-3, therefore the rights set forth herein shall apply; and (b) For any other unit or agency: NOTICE: Notwithstanding any other lease or license agreement that may pertain to, or accompany the delivery of, the computer software and accompanying documentation, the rights of the Government regarding its use, reproduction, and disclo- sure are as set forth in Clause 52.227-19 (c)(2) of the FAR. MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and Target Language Compiler is a trademark of The MathWorks, Inc. Other product or brand names are trademarks or registered trademarks of their respective holders. Printing History: October 1995 First printing January 1998 Revised for Version 1.2 January 1999 Revised for Version 2.0 (Release 11) Contents Getting Ready 1 Introduction . 1-2 Who Should Read This Book . 1-2 New MATLAB C Math Library Features . 1-2 Unsupported MATLAB Features . 1-3 Library Routine Naming Convention . 1-3 MATLAB C Math Library Documentation . 1-3 How This Book Is Organized . 1-3 Accessing Online Reference Documentation . 1-4 Additional Sources of Information . 1-5 MATLAB C Math Library 1.2 Users . 1-6 MATLAB C Math Library Version 1.2 Documentation . 1-6 Migrating Your Code to Version 2.0 . 1-6 Installing the MATLAB C Math Library . 1-9 Installation with MATLAB . 1-9 Installation Without MATLAB . 1-9 Verifying a UNIX Workstation Installation . 1-10 Verifying a PC Installation . 1-10 Building C Applications . 1-11 Packaging Stand-Alone Applications . 1-11 Overview . 1-11 Compiler Options Files . 1-12 Building a Stand-Alone Application on UNIX . 1-13 Configuring for C or C++ . 1-13 Locating Options Files . 1-13 Using the System Compiler . 1-14 Changing the Default Compiler . 1-14 Modifying the Options File . 1-15 Temporarily Changing the Compiler . 1-16 i Verifying mbuild . 1-16 Locating Shared Libraries . 1-17 Running Your Application . 1-18 mbuild Options . 1-18 Distributing Stand-Alone UNIX Applications . 1-21 Building a Stand-Alone Application on Microsoft Windows . 1-22 Configuring for C or C++ . 1-22 Locating Options Files . 1-22 Systems with Exactly One C/C++ Compiler . 1-23 Systems with More than One Compiler . 1-23 Changing the Default Compiler . 1-24 Modifying the Options File . 1-26 Combining Customized C and C++ Options Files . 1-27 Temporarily Changing the Compiler . 1-28 Verifying mbuild . 1-28 Shared Libraries (DLLs) . 1-28 Running Your Application . 1-29 mbuild Options . 1-29 Distributing Stand-Alone Microsoft Windows Applications . 1-32 Building Shared Libraries . 1-33 Troubleshooting mbuild . 1-34 Options File Not Writable . 1-34 Directory or File Not Writable . 1-34 mbuild Generates Errors . 1-34 Compiler and/or Linker Not Found . 1-34 mbuild Not a Recognized Command . 1-34 Cannot Locate Your Compiler (PC) . 1-34 Internal Error When Using mbuild -setup (PC) . 1-35 Verification of mbuild Fails . 1-35 Building on Your Own . 1-36 ii Contents Writing Programs 2 Overview . 2-2 A Simple Example Program . 2-2 Working with MATLAB Arrays 3 Overview . 3-2 Supported MATLAB Array Types . 3-2 MATLAB Array C Data Type . 3-3 Working with MATLAB Numeric Arrays . 3-4 Creating Numeric Arrays . 3-5 Using Numeric Array Creation Routines . 3-5 Creating Numeric Arrays by Calling Arithmetic Routines . 3-9 Creating Numeric Arrays by Concatenation . 3-9 Creating Numeric Arrays by Assignment . 3-11 Initializing a Numeric Array with Data . 3-12 Column-Major Storage versus Row-Major Storage . 3-14 Example Program: Creating Numeric Arrays (ex1.c) . 3-15 Working with MATLAB Sparse Matrices . 3-18 Creating a Sparse Matrix . 3-19 Converting an Existing Matrix into Sparse Format . 3-19 Creating a Sparse Matrix from Data . 3-21 Converting a Sparse Matrix to Full Matrix Format . 3-23 Evaluating Arrays for Sparse Storage . 3-23 Working with MATLAB Character Arrays . 3-25 Creating MATLAB Character Arrays . 3-26 Using Explicit Character Array Creation Routines . 3-26 Converting Numeric Arrays to Character Arrays . 3-27 Creating Multidimensional Arrays of Strings . 3-27 Accessing Individual Strings in an Array of Strings . 3-29 iii Working with MATLAB Cell Arrays . 3-30 Creating Cell Arrays . 3-30 Using the Cell Array Creation Routine . 3-31 Using Cell Array Conversion Routines . 3-31 Using Concatenation to Create Cell Arrays . 3-32 Using Assignment to Create Cell Arrays . 3-34 Displaying the Contents of a Cell Array . 3-34 Working with MATLAB Structures . 3-37 Creating Structures . 3-38 Using a Structure Creation Routine . 3-38 Creating Multidimensional Arrays of Structures . 3-38 Using a Structure Conversion Routine . 3-39 Using Assignment to Create Structures . 3-40 Performing Common Array Programming Tasks . 3-41 Allocating and Freeing MATLAB Arrays . 3-41 Displaying MATLAB Arrays . 3-41 Formatting Output . 3-42 Determining Array Type . 3-43 Determining the Size of an Array . 3-44 Obtaining the Length of a Single Dimension . 3-45 Returning the Dimensions in Separate Arrays . 3-45 Determining the Shape of an Array . 3-46 Managing Array Memory 4 Overview . 4-2 Why Choose Automated Memory Management? . 4-3 Using Explicit Memory Management . 4-4 Using Arrays Under Automated Memory Management . 4-6 Definitions . 4-6 Rules for Array Usage . 4-8 Paradigm for Working with Local Array Variables . 4-8 iv Contents Assigning Arrays to mxArray* Variables . 4-9 Assigning a Value to an Array Destroys Its Previous Value 4-10 Assignment by Value . 4-11 Nesting Calls to Functions that Return Arrays . 4-11 Deleting Your Arrays . 4-11 Avoiding Memory Leaks in.