MATLAB New Features Guide

Upgrading to MATLAB 5

MATLAB 5 is a major upgrade to MATLAB. Although The MathWorks endeavors to maintain full upwards compatibility between subsequent releases of MATLAB, inevitably there are situations where this is not possible. In the case of MATLAB 5, there are a number of changes that you need to know about in order to migrate your code from MATLAB 4 to MATLAB 5.

It is useful to introduce two terms in discussing this migration. The first step in converting your code to MATLAB 5 is to make it MATLAB 5 compatible. This involves a rather short list of possible changes that let your M-files run under MATLAB 5. The second step is to make it MATLAB 5 compliant. This means making further changes so that your M-file is not using obsolete, but temporarily supported, features of MATLAB. It also can mean taking advantage of MATLAB 5 features like the new data constructs, graphics, and so on.

There are a relatively small number of things that are likely to be in your code that you will have to change to make your M-files MATLAB 5 compatible. Most of these are in the graphics area.

There are a somewhat larger number of things you can do (but don't have to) to make your M-files fully MATLAB 5 compliant. To help you gradually make your code compliant, MATLAB 5 displays warning messages when you use functions that are obsolete, even though they still work correctly.

Converting M-Files from MATLAB 4 to MATLAB 5

Language Changes
`Function`	`Change`	`Action`
`bessel`	The `bessel` functions no longer produce a table for vector arguments of the same orientation.	In `besselj(nu,x)`, specify `nu` as a row and `x` as a column to produce a table.
`case`, `otherwise`, `switch`, `default`	`case`, `otherwise`, `switch`, and `default` cannot be used as variable names.	Rename your variables.
`dialog`	`dialog.m` now creates a modal dialog.	Use the `msgbox` function instead.
`end`	extra `end` statements	Remove redundant `end` statements.
`eps`	`eps` is a function	`eps = 0` no longer redefines `eps` for other functions (it makes a local variable called `eps` in the current workspace). Functions that base their tolerance on externally defined `eps` won't work. Change code accordingly.
`global`	Undefined globals	Define globals before they are used. Always put the `global` statement at the top of the M-file (just below the help comments).
`gradient`	`gradient` no longer produces complex output.	Use two outputs in the two-dimensional case.
`input`	`input('prompt','s')` no longer outputs an initial line feed. Prompts now show up on the same line.	Update code accordingly if this causes a display problem. Add `\n` in the prompt string to force a line feed.
`interp1`	The old `interp1` syntax (`interp1(x,n)`) no longer calls `interpft`. A warning was in place in MATLAB 4.	Update code accordingly.
`interp1` now returns a row vector when given a row vector. It used to return a column vector.	Transpose the output of `interp1` to produce the MATLAB 4 result when `xi` is a row vector.
`interp1('spline')` returns `NaN's for out of range values.`	Use `spline` directly.
`interp2`	The old `interp2` syntax (`interp2(x,y,xi)`) no longer calls `interp1`. A warning was in place in MATLAB 4.	Update code accordingly.
`interp3`	The old `interp3` syntax (`interp3(z,m,n)` or `interp3(x,y,z,xi,yi)`) no longer calls `griddata` (users were warned in 4.0). `interp3` is now three-dimensional interpolation.	Update code accordingly.
`isempty`	`A == []` and A ~= [] as a check for an empty matrix produce warning messages.	Use `isempty(A)` or `~isempty(A)`. In a future version `A == []` will produce an empty result.
`isspace`	`isspace` only returns `true` (`1`) on strings. `isspace(32)` is `0` (it was `1` in MATLAB 4).	Wrap your calls to `isspace` with `char`.
`logical`	Some masking operations where the mask isn't defined using a logical expression now produce an out of range index error.	Wrap the subscript with a call to `logical` or use the logical expression `A~=0` to produce MATLAB 4 behavior.
	Boolean indexing is no longer directly supported.	Use `logical` to create the index array.
`matlabrc`	On the PC, MATLAB no longer stores the path in `matlabrc`.	All platforms except the Macintosh now use `pathdef.m`. The Macintosh still stores its path in the MATLAB `Settings` file (usually in the `Preferences` folder).
`max`	`max(size(v))`, as a means to determine the number of elements in a vector `v`, fails when `v` is empty.	Use `length(v)` in place of `max(size(v))` as the upper limit on loops over the elements of any vector.
`nargin`,`nargout`	`nargin` and `nargout` are functions.	`nargout = nargout-1` (and any similar construction) is an error. To work around this change, assign `nargin` to a local variable and increment that variable. Rename all occurrences of `nargin` to the new variable. The same holds true for all functions.
`ones`	`A(ones(size(A)))` no longer produces `A`.	This statement produces copies of the first element of `A`. Use `A(ones(size(A))~=0)` or just `A` to produce the MATLAB 4 behavior.
	Functions such as `ones`, `eye`, `rand`, and `zeros` give an error if supplied with a matrix argument (such as `zeros(A)`).	Use the syntax `ones(size(A))` instead.
`rand`	`rand('normal')` and `rand('uniform')` no longer supported.	Use `randn` for normally distributed and `rand` for uniformly distributed random numbers.
`round`	Subscripts must be integers.	To reproduce MATLAB 4 behavior, wrap noninteger subscripts with `round()`. Strings are no longer valid subscripts (since they are not integers in the strict sense).
`slice`	`slice` no longer requires the number of columns (`ncols`) argument.	Update code accordingly.
`strcmp strncmp`	`strcmp` and `strncmp` now return `false` (`0`) when any argument is numeric. They used to perform an `isequal`.	Call `isequal` for all nonstrings you want to compare.
	`a(:) = b` where `a` doesn't exist creates an error. This used to do the same thing as `a = b(:)` when `a` didn't exist.	Either initialize `a` or use `a = b(:)` instead.
	Must use an explicitly empty matrix to delete elements of an array, as in `a(i) = []` or `a(i,:) = []`.	This syntax works for all built-in data types (including cell arrays and structures).
	The syntax `a(i) = B`, when `B` is empty, no longer deletes elements.	An empty assignment is attempted. Using the empty cell array `{}` in place of `[]` is not valid for deleting elements of a cell array.
	An attempt to delete elements of an array outside its range is no longer (incorrectly) ignored.	An error is generated.
	Undefined variables	To reproduce MATLAB 4 behavior, initialize your variable to the empty matrix (`[]`) or empty string (`''`).
	Undefined outputs	To reproduce MATLAB 4 behavior, initialize your outputs to the empty matrix (`[]`).

This section describes some changes you can make to your MATLAB 4 code to eliminate error messages and warnings due to incompatible and noncompliant statements.

Language Changes
Function Change Action
bessel
The bessel functions no longer produce a table for vector arguments of the same orientation.
In besselj(nu,x), specify nu as a row and x as a column to produce a table.

case,
otherwise,
switch,
default
case, otherwise, switch, and default cannot be used as variable names.
Rename your variables.

dialog
dialog.m now creates a modal dialog.
Use the msgbox function instead.

end
extra end statements
Remove redundant end statements.

eps
eps is a function
eps = 0 no longer redefines eps for other functions (it makes a local variable called eps in the current workspace). Functions that base their tolerance on externally defined eps won't work. Change code accordingly.

global
Undefined globals
Define globals before they are used. Always put the global statement at the top of the M-file (just below the help comments).

gradient
gradient no longer produces complex output.
Use two outputs in the two-dimensional case.

input
input('prompt','s') no longer outputs an initial line feed. Prompts now show up on the same line.
Update code accordingly if this causes a display problem. Add \n in the prompt string to force a line feed.

interp1
The old interp1 syntax (interp1(x,n)) no longer calls interpft. A warning was in place in MATLAB 4.
Update code accordingly.

interp1 now returns a row vector when given a row vector. It used to return a column vector.
Transpose the output of interp1 to produce the MATLAB 4 result when xi is a row vector.

interp1('spline') returns NaN's for out of range values.
Use spline directly.

interp2
The old interp2 syntax (interp2(x,y,xi)) no longer calls interp1. A warning was in place in MATLAB 4.
Update code accordingly.

interp3
The old interp3 syntax (interp3(z,m,n) or interp3(x,y,z,xi,yi)) no longer calls griddata (users were warned in 4.0). interp3 is now three-dimensional interpolation.
Update code accordingly.

isempty
A == [] and A ~= [] as a check for an empty matrix produce warning messages.
Use isempty(A) or ~isempty(A). In a future version A == [] will produce an empty result.

isspace
isspace only returns true (1) on strings. isspace(32) is 0 (it was 1 in MATLAB 4).
Wrap your calls to isspace with char.

logical

Some masking operations where the mask isn't defined using a logical expression now produce an out of range index error.
Wrap the subscript with a call to
logical or use the logical expression A~=0 to produce MATLAB 4 behavior.

Boolean indexing is no longer directly supported.
Use logical to create the index array.

matlabrc
On the PC, MATLAB no longer stores the path in matlabrc.
All platforms except the Macintosh now use pathdef.m. The Macintosh still stores its path in the MATLAB Settings file (usually in the Preferences folder).

max
max(size(v)), as a means to determine the number of elements in a vector v, fails when v is empty.
Use length(v) in place of max(size(v)) as the upper limit on loops over the elements of any vector.

nargin,nargout
nargin and nargout are functions.
nargout = nargout-1 (and any similar construction) is an error. To work around this change, assign nargin to a local variable and increment that variable. Rename all occurrences of nargin to the new variable. The same holds true for all functions.

ones
A(ones(size(A))) no longer produces A.

This statement produces copies of the first element of A. Use A(ones(size(A))~=0) or just A to produce the MATLAB 4 behavior.

Functions such as ones, eye, rand, and zeros give an error if supplied with a matrix argument (such as zeros(A)).
Use the syntax ones(size(A)) instead.

rand
rand('normal') and rand('uniform') no longer supported.
Use randn for normally distributed and rand for uniformly distributed random numbers.

round
Subscripts must be integers.
To reproduce MATLAB 4 behavior, wrap noninteger subscripts with round(). Strings are no longer valid subscripts (since they are not integers in the strict sense).

slice
slice no longer requires the number of columns (ncols) argument.
Update code accordingly.

strcmp strncmp
strcmp and strncmp now return false (0) when any argument is numeric. They used to perform an isequal.
Call isequal for all nonstrings you want to compare.

a(:) = b where a doesn't exist creates an error. This used to do the same thing as a = b(:) when a didn't exist.
Either initialize a or use a = b(:) instead.

Must use an explicitly empty matrix to delete elements of an array, as in a(i) = [] or
a(i,:) = [].
This syntax works for all built-in data types (including cell arrays and structures).

The syntax a(i) = B, when B is empty, no longer deletes elements.
An empty assignment is attempted. Using the empty cell array {} in place of [] is not valid for deleting elements of a cell array.

An attempt to delete elements of an array outside its range is no longer (incorrectly) ignored.
An error is generated.

Undefined variables
To reproduce MATLAB 4 behavior, initialize your variable to the empty matrix ([]) or empty string ('').

Undefined outputs
To reproduce MATLAB 4 behavior, initialize your outputs to the empty matrix ([]).

Obsolete Language Functions
Obsolete Function Action
csvread, csvwrite
Use dlmread(filename,',') and dlmwrite(filename,',').

ellipk
Replace with ellipke.

extent
Replaced by Extent property.

figflag
Use findobj.

finite
Rename to isfinite. finite will continue to work for MATLAB 5 but will probably be removed in a later release.

fwhich
Use which.

hthelp
hthelp works in MATLAB 5, but will not be further developed or supported.Use helpwin or doc.

htpp
Use helpwin or doc.

inquire
Use set and get to obtain the current state of an object or of MATLAB.

inverf
Rename to erfinv.

isdir
Use dir.

layout
No replacement in MATLAB 5.

loadhtml
Use helpwin or doc.

matq2ws
Replaced by assignin and evalin.

matqdlg
Replaced by assignin and evalin.

matqparse
Replaced by assignin and evalin.

matqueue
Replaced by assignin and evalin.

menulabel
Bug in Handle Graphics is now fixed.

mexdebug
Rename to dbmex.

ode23p
Use ode23 with no lefthand arguments or set an output function with odeset.

polyline, polymark
Use the line object or plot.

printmenu
No replacement in MATLAB 5.

saxis
Use soundsc.

ws2matq
Replaced by assignin and evalin.

Obsolete Language Functions
`Obsolete Function`	`Action`
`csvread, csvwrite`	Use `dlmread(filename,',')` and `dlmwrite(filename,',').`
`ellipk`	Replace with `ellipke`.
`extent`	Replaced by Extent property.
`figflag`	Use `findobj.`
`finite`	Rename to `isfinite`. `finite` will continue to work for MATLAB 5 but will probably be removed in a later release.
`fwhich`	Use `which`.
`hthelp`	`hthelp` works in MATLAB 5, but will not be further developed or supported.Use `helpwin` or `doc`.
`htpp`	Use `helpwin` or `doc`.
`inquire`	Use `set` and `get` to obtain the current state of an object or of MATLAB.
`inverf`	Rename to `erfinv.`
`isdir`	Use `dir`.
`layout`	No replacement in MATLAB 5.
`loadhtml`	Use `helpwin` or `doc`.
`matq2ws`	Replaced by `assignin` and `evalin`.
`matqdlg`	Replaced by `assignin` and `evalin`.
`matqparse`	Replaced by `assignin` and `evalin`.
`matqueue`	Replaced by `assignin` and `evalin`.
`menulabel`	Bug in Handle Graphics is now fixed.
`mexdebug`	Rename to `dbmex.`
`ode23p`	Use `ode23` with no lefthand arguments or set an output function with `odeset`.
`polyline, polymark`	Use the `line` object o`r` `plo`t.
`printmenu`	No replacement in MATLAB 5.
`saxis`	Use `soundsc`.
`ws2matq`	Replaced by `assignin` and `evalin`.

Graphics Function Changes
`Function`	`Change`	`Action`
`get`	`get(0,'currentfigure')` and `get(0,'currentaxes')` no longer create an Axes if one doesn't exist. They return `[]` in that case.	`gcf` and `gca` always return a valid handle. Use `gcf` and `gca` instead of the `get` function in this context.
	In MATLAB 4 you could determine if a graphics object had a default value set by passing its handle in a query like `get(gca,'DefaultAxesColor')`.	In MATLAB 5 make the query on the object's ancestor, e.g.: `get(gcf,'DefaultAxesColor')` or `get(0,'DefaultAxesColor')`
`plot`	MATLAB 4 plots may have elements that are the wrong color.	MATLAB 5 defaults to a white background on all platforms. (MATLAB 4 defaulted to white on the Macintosh and black everywhere else.) Use `colordef` to control your color defaults. Typically, you'll put a call to `colordef` in `startup.m` . To get the MATLAB 4 defaults, use `colordef none`.
	`plot` line styles `c1` through `c15` and `i` are no longer supported	Use a 1-by-3 RGB ColorSpec instead. `i` is the same as `get(gca,'color')` or `get(gcf,'color')` when the Axes color is `'none'`.
`uicontrol`	The default uicontrol text horizontal alignment is centered in MATLAB 5. (In MATLAB 4 we used to left align text and ignore the alignment property. )	Explicitly set the horizontal alignment when you create Uicontrol Text objects.
	In MATLAB 4, Uicontrols of style `'edit'` executed their callback routine whenever you moved the pointer out of the edit box. In MATLAB 5, edit controls execute their callbacks after you perform a specific action.	The callback is called when: <return> key is pressed (single-line edits only) focus is moved out of the edit by: clicking elsewhere in the Figure (on another Uicontrol or on another graphical object) clicking in another Figure clicking on the menubar (X Windows only)

Graphics Property Changes
Property Change Action
AspectRatio
Obsolete
Replace with
DataAspectRatio and
PlotBoxAspectRatio.

BackgroundColor
Obsolete
Do not use.

CDataScaling
Renamed
CDataMapping

CurrentMenu
Becoming obsolete. No warning message produced.
Replace with the function gcbo.

EraseMode
We now xor against the Axes color rather than the Figure color.
Modify code as appropriate.

ExpFontAngle
Obsolete
Do not use.

ExpFontName
Obsolete
Do not use.

ExpFontSize
Obsolete
Do not use.

ExpFontStrikeThrough
Obsolete
Do not use.

ExpFontUnderline
Obsolete
Do not use.

ExpFontUnits
Obsolete
Do not use.

ExpFontWeight
Obsolete
Do not use.

FontStrikeThrough
Obsolete
Do not use.

FontUnderline
Obsolete
Do not use.

FVCData
Renamed
FaceVertexCData

HiddenHandle
Obsolete
Replace with
HandleVisibility.

LineStyle
Setting the LineStyle property to a marker value (such as '+') now produces a warning.
Setting the marker style of a line now affects the
MarkerStyle property instead of the LineStyle property. Although you will be able to set a line marker using the LineStyle property (with a warning), you will not be able to get marker style information from LineStyle.
Set the MarkerStyle property instead. Note that plot will continue to take line-color-marker line styles.
If your code relies on markers in the LineStyle, you'll have to change it to use the
MarkerStyle instead.

Mode
Renamed
Style

ProjectionType
Becoming obsolete. No warning message produced.
Will be replaced in a future release.

RenderLimits
Obsolete
Do not use.

Units
Units/Position is always order dependent for all objects. In MATLAB 4, it was inconsistent.
The Units property should precede any properties that depend upon it. A command such as
axes('position',[100 200 300 100],'units','pixels') is not the same as axes('units','pixels','posi tion',[100 200 300 100]). In the first case, the default axes units are normalized; the numbers are interpreted in normalized coordinates.

WindowID
Possibly becoming obsolete.
May be removed in a future release.

XLoc2D
Becoming obsolete. No warning message produced.
Will be replaced in a future release.

XMinorTicks
Renamed
XMinorTick

XTickLabels
Renamed
XTickLabel

YLoc2D
Becoming obsolete. No warning message produced.
Will be replaced in a future release.

YMinorTicks
Renamed
YMinorTick

YTickLabels
Renamed
YTickLabel

ZMinorTicks
Renamed
ZMinorTick

ZTickLabels
Renamed
ZTickLabel

Graphics Property Changes
`Property`	`Change`	`Action`
`AspectRatio`	Obsolete	Replace with `DataAspectRatio` and `PlotBoxAspectRatio`.
`BackgroundColor`	Obsolete	Do not use.
`CDataScaling`	Renamed	`CDataMapping`
`CurrentMenu`	Becoming obsolete. No warning message produced.	Replace with the function `gcbo`.
`EraseMode`	We now `xor` against the Axes color rather than the Figure color.	Modify code as appropriate.
`ExpFontAngle`	Obsolete	Do not use.
`ExpFontName`	Obsolete	Do not use.
`ExpFontSize`	Obsolete	Do not use.
`ExpFontStrikeThrough`	Obsolete	Do not use.
`ExpFontUnderline`	Obsolete	Do not use.
`ExpFontUnits`	Obsolete	Do not use.
`ExpFontWeight`	Obsolete	Do not use.
`FontStrikeThrough`	Obsolete	Do not use.
`FontUnderline`	Obsolete	Do not use.
`FVCData`	Renamed	`FaceVertexCData`
`HiddenHandle`	Obsolete	Replace with HandleVisibility.
`LineStyle`	Setting the `LineStyle` property to a marker value (such as `'+'`) now produces a warning. Setting the marker style of a line now affects the `MarkerStyle` property instead of the `LineStyle` property. Although you will be able to set a line marker using the `LineStyle` property (with a warning), you will not be able to get marker style information from `LineStyle`.	Set the `MarkerStyle` property instead. Note that `plot` will continue to take line-color-marker line styles. If your code relies on markers in the `LineStyle`, you'll have to change it to use the `MarkerStyle` instead.
Mode	Renamed	`Style`
`ProjectionType`	Becoming obsolete. No warning message produced.	Will be replaced in a future release.
`RenderLimits`	Obsolete	Do not use.
`Units`	Units/Position is always order dependent for all objects. In MATLAB 4, it was inconsistent.	The Units property should precede any properties that depend upon it. A command such as `axes('position',[100 200 300 100],'units','pixels')` is not the same as `axes('units','pixels','posi tion',[100 200 300 100])`. In the first case, the default axes units are normalized; the numbers are interpreted in normalized coordinates.
WindowID	Possibly becoming obsolete.	May be removed in a future release.
`XLoc2D`	Becoming obsolete. No warning message produced.	Will be replaced in a future release.
`XMinorTicks`	Renamed	`XMinorTick`
`XTickLabels`	Renamed	XTickLabel
`YLoc2D`	Becoming obsolete. No warning message produced.	Will be replaced in a future release.
`YMinorTicks`	Renamed	`YMinorTick`
`YTickLabels`	Renamed	YTickLabel
`ZMinorTicks`	Renamed	`ZMinorTick`
`ZTickLabels`	Renamed	ZTickLabel

Converting MEX-Files from MATLAB 4 to MATLAB 5

MATLAB 5 may or may not run existing MATLAB 4 MEX-files and binaries. If your binaries or source files are not compatible with the MATLAB 5 API, you must convert your MATLAB 4 MEX-file source code to MATLAB 5.

MEX-File Binary Incompatibility

General Considerations

MATLAB 4 binaries will not run in MATLAB 5 if they:

directly manipulate strings.
were built with the -V3.5 compile switch.

PC-Specific Considerations

16-bit DLLs are no longer supported.

Macintosh-Specific Considerations

MEX-files compiled for MATLAB 4 for the Macintosh Power PC are not supported. You must regenerate these MEX-files from the source code before using them with MATLAB 5.

MEX-File Source Incompatibility

General Considerations

Non-ANSI MEX-files are no longer supported.
MATLAB 4 Fortran MEX-files on Sun 4, MS-Windows, and Macintosh 68K platforms that access string arrays will not work.
MATLAB 4 C and Fortran MEX-files that directly manipulate strings will not work. V4 strings were stored as double precision floating point numbers. MATLAB 5 strings are stored as 16-bit unsigned integers.
MEX-file source code that required the -V3.5 compile switch will not compile.
mexdebug is now called dbmex. Only the name has changed; in all other respects dbmex behaves exactly like mexdebug.

UNIX-Specific Considerations

The mexrc.sh file is no longer supported. The new options file, mexopts.sh, contains the same information, but in a different format.
$MATLAB/bin/mexopts.sh is the default UNIX options file.
The cmex and fmex Bourne shell scripts have been superseded by mex, a new Bourne shell script that includes both C and Fortran support, as well as additional support for C++.

PC-Specific Considerations

Existing MATLAB 4 REX MEX-files are usable but cannot be created under MATLAB 5.
The cmex and fmex batch files have been superseded by mex, a PERL script.

MEX-File Conversion Techniques

If your existing MEX-file binaries do not run, you must convert MATLAB 4 MEX-file sources to MATLAB 5 by:

Rebuilding MATLAB 4 source code by invoking mex with the -V4 option, or
Recoding MATLAB 4 source code to make it MATLAB 5 compliant.

These flowcharts help you determine what steps you should take to run your MATLAB 4 MEX-files under MATLAB 5. In particular, they help you determine if you can:

Use your MATLAB 4 MEX-file binary as is
Rebuild your MEX-file source using the -v4 option of mex
Recompile your MEX-file source using mex filename

The sections "Rebuilding with the -V4 Option" and "Recoding for MATLAB 5 Compliance" following the flowcharts provide additional porting information.

Rebuilding with the -V4 Option

The simplest strategy for converting C MEX-file programs is to rebuild them with the special -V4 option of mex. This option uses mex to include MATLAB 4 header files. Therefore, any C MEX-file source code that compiled cleanly under MATLAB 4 should compile cleanly with the -V4 option. The resulting MEX-file should run under MATLAB 5 just as it ran under MATLAB 4. For example, given C MEX-file MATLAB 4 source code in file MyEig.c, recompiling under UNIX with

mex -V4 myeig.c

yields a MEX-file that MATLAB 5 can execute. It is also possible to use cmex and fmex for compiling C and Fortran source code, but both of these functions simply call mex.

Even with the -V4 option, you need to recode if your source code manipulates string matrices. The -V4 option cannot handle the different ways in which MATLAB 4 and MATLAB 5 represent string data. The MATLAB 4 Matrix structure held each "character" in a string matrix as a double-precision, floating-point number. MATLAB 5 represents each "character" in a string matrix as an mxChar, a 16-bit unsigned integer data type.

The obvious advantage to the -V4 strategy is that it requires very little work on your part. However, this strategy provides only a temporary solution to the conversion problem; there is no guarantee that future releases of MATLAB will continue to support the -V4 option. If you have the time, recoding for MATLAB 5 compliance is a better strategy.

Recoding for MATLAB 5 Compliance

Recoding your MATLAB 4 C or Fortran code for MATLAB 5 compliance involves:

Rewriting any non-ANSI C code as ANSI C code. (For details, see an ANSI C book.)
Changing all Matrix variables to mxArray variables.
The MATLAB 4 Matrix data type is obsolete; you must change all Matrix variables to mxArray variables. For example, the mxCreateSparse function returns a Matrix pointer in MATLAB 4:

Matrix *MySparse;
MySparse = mxCreateSparse(10, 10, 110, REAL);

To be MATLAB 5 compliant, change the code to:

mxArray *MySparse;
MySparse = mxCreateSparse(10, 10, 110, mxREAL);

Rewriting all function prototypes.
The function prototype of almost every MATLAB 4 mx and mex function is different in MATLAB 5. The two primary prototype changes are
- All Matrix arguments are now mxArray arguments.
- Pointers to read only data are now declared as const *.
Changing REAL to mxREAL and COMPLEX to mxCOMPLEX.
In any function that requires the specification of real or complex data types, instead of REAL and COMPLEX, use mxREAL and mxCOMPLEX. For example, in MATLAB 4 you would write

mxCreateSparse(m,n,nzmax,REAL);

nzmax

mxCreateSparse(m,n,nzmax,mxREAL);

Translating obsolete function calls into their MATLAB 5 replacements.
A number of functions have become obsolete. However, MATLAB 5 offers replacements for nearly all of the obsolete functions. See "How to Convert Each MATLAB 4 Function" for details.
Protecting against MATLAB 5 new data types.
If your code identifies a data type by a process of elimination, you must rewrite it in MATLAB 5. For example, if your code checks a variable and finds that it is neither a double nor a sparse matrix, you can no longer assume that the variable must be a string.
Rewriting any code that assumes complex arguments.
In MATLAB 4, if one argument to a MEX-function was complex, all arguments were considered complex. This is not true in MATLAB 5. For example, consider a MEX-function myeig(A,B,C) that calculates eigenvalues of three matrices. In MATLAB 4 if matrix A is complex, B and C are assumed to be complex matrices as well. In this instance additional memory is allocated for the complex part of B and C, whether or not these matrices are complex. In MATLAB 5, B and C are assumed to be real unless otherwise specified.
Converting string matrices using API routines for access and manipulation.
In MATLAB 4, the Matrix structure held each "character" in a string matrix as a double-precision, floating-point number. If the string flag was set, then MATLAB displayed each double-precision, floating-point number as an ASCII value.
MATLAB 5 represents each "character" in a string matrix as an mxChar, a 16-bit unsigned integer data type. The mxArray does not provide a string flag; if the mxArray's class is mxCHAR_CLASS, MATLAB treats each number in the mxArray as an element from the current character set. Character sets are platform specific.
If your MATLAB 4 source code created string matrices by calling mxCreateString, you do not have to recode sections that create strings. However, if your MATLAB 4 source code called mxSetString to create string matrices, you must recode. mxSetString is obsolete in MATLAB 5; if you used mxSetString to create a two-dimensional string matrix, call mxCreateCharMatrixFromStrings instead.
If your MATLAB 4 source code used something other than mxGetString to copy string data into a C string, you must recode. As you recode, don't forget that each character in a string mxArray is now stored as a 16-bit integer rather than as a double-precision, floating-point number.

How to Convert Each MATLAB 4 Function

This table shows each MATLAB 4 function along with a description of how to port that function to MATLAB 5.

Converting MEX-Functions to MATLAB 5
MATLAB 4 Function	MATLAB 5 Conversion
`mexAtExit`	No change
`mexCallMATLAB`	Ssecond and fourth arguments are `mxArray *`
`mexErrMsgTxt`	No change
`mexEvalString`	No change
`mexFunction`	Second and fourth arguments are `mxArray *` . Fourth argument is a `const`.
`mexGetEps`	Obsolete; call `mxGetEps` instead
`mexGetFull`	Obsolete; call this sequence instead: `mexGetArray(array_ptr, "caller"); name = mxGetName(array_ptr); m = mxGetM(array_ptr); n = mxGetM(array_ptr); pr = mxGetPr(array_ptr); pi = mxGetPi(array_ptr);`
`mexGetGlobal`	Obsolete; call `mexGetArrayPtr` instead, setting the second argument to `"global".` Note: it is better programming practice to call`mexGetArray(,"global");`
`mexGetInf`	Obsolete; call `mxGetInf` instead
`mexGetMatrix`	Call `mexGetArray(name, "caller");`
`mexGetMatrixPtr`	Call `mexGetArrayPtr(name, "caller");`
`mexGetNaN`	Obsolete; call `mxGetNaN` instead.
`mexIsFinite`	Obsolete; call `mxIsFinite` instead.
`mexIsInf`	Obsolete; call `mxIsInf` instead.
`mexIsNaN`	Obsolete; call `mxIsNaN` instead.
`mexPrintf`	No change
`mexPutFull`	Obsolete; call this sequence instead: `mxArray parray;` `int retval;` `parray=mxCreateDouble(0,0,0);` `if(parray==(mxArray)0) return(1);` `mxSetM(parray,m);` `mxSetN(parray,n);` `mxSetPr(parray,pr);` `mxSetPi(parray,pi);` `mxSetName(parray,name);` `retval=mxPutArray(parray,"caller");` `mxFree(parray);` `return(retval);`
`mexPutMatrix`	Obsolete; call `mexPutArray` instead.
`mexSetTrapFlag`	No change
`mxCalloc`	No change
`mxCreateFull`	Obsolete; call `mxCreateDoubleMatrix` instead.
`mxCreateSparse`	Returns `mxArray *.`
`mxCreateString`	Returns `mxArray *.`
`mxFree`	No change
`mxFreeMatrix`	Obsolete; call `mxDestroyArray` instead.
`mxGetIr`	First argument is `mxArray *.`
`mxGetJc`	First argument is `mxArray *.`
`mxGetM`	First argument is `mxArray` *.
`mxGetN`	First argument is `mxArray *.`
`mxGetName`	First argument is `mxArray *.`
`mxGetNzmax`	First argument is `mxArray *.`
`mxGetPi`	First argument is `mxArray *.`
`mxGetPr`	First argument is `mxArray *.`
`mxGetScalar`	First argument is `mxArray *.`
`mxGetString`	First argument is `mxArray *.`
`mxIsComplex`	First argument is `mxArray *.`
`mxIsDouble`	First argument is `mxArray *.` Note that MATLAB 4 stores all data as `double`'s; MATLAB 5 stores data in a variety of integer and real formats.
`mxIsFull`	Obsolete; call `!mxIsSparse` instead.
`mxIsNumeric`	First argument is `mxArray *.`
`mxIsSparse`	First argument is `mxArray *.`
`mxIsString`	Obsolete; call `mxIsChar` instead.
`mxSetIr`	First argument is `mxArray *.`
`mxSetJc`	First argument is `mxArray *.`
`mxSetM`	First argument is `mxArray *.`
`mxSetN`	First argument is `mxArray *.`
`mxSetName`	First argument is `mxArray *.`
`mxSetNzmax`	First argument is `mxArray *.`
`mxSetPi`	First argument is `mxArray *.`
`mxSetPr`	First argument is `mxArray *.`
`mxSetString`	Obsolete; MATLAB 5 provides no equivalent call since the `mxArray` data type does not contain a string flag. Use `mxCreateCharMatrixFromStrings` to create multidimensional string `mxArray`'s.

[ Previous | Help Desk | Next ]