MATLAB New Features Guide Help Desk


Upgrading to MATLAB 5


Upgrading from MATLAB 4 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

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.

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

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:

PC-Specific Considerations

Macintosh-Specific Considerations

MEX-File Source Incompatibility

General Considerations

UNIX-Specific Considerations

PC-Specific Considerations

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:

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:

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

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:

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 ]