ECE 201 - Lesson Plan - Class #4

Fall, 2002

Function M-Files

< TYPE="text/css"><!-- // hide this stuff from old browsers

.blue {font-size: 10pt;

color: #0000FF;

text-decoration: underline;

font-family: Arial,Helvetica}

.white {font-size: 10pt;

color: #FFFFFF;

text-decoration: underline;

font-family: Arial,Helvetica}

MATLAB allows M-files to be written as functions so that programs can call them functions just like a built-in MATLAB function.

There are a couple of differences between Script M-Files and Function M-Files and they are provided below:

Script M-Files Function M-Files

Do not accept input arguments or return output arguments.	Accept input arguments and can (when prompted) return output arguments.
Operate on data in the workspace.	Internal variables are local to the function by default.
Useful for automating a series of steps you need to perform many times.	Useful for passing MATLAB variables from one MATLAB function to another.

This first line is known as the function definition line and must begin with the word function. This is then followed by the assignment of the variables for the output (if required), an equal sign, the name of the function, and the assignment of the variables for the input. The order of the input and output variables are important. FYI - The only information returned from this function is what is assigned as the output. An example:

function [OUTPUT1, OUTPUT2] = function_name(INPUT1, INPUT2)

The first word function is a MATLAB 'keyword' and function_name is the function's name. Assume that function_name has two inputs, entering

>> function_name(INPUT1, INPUT2);

on the MATLAB command line will execute this function and will return whatever outputs requested. Notice that a semicolon has been added to suppress the output, just like a MATLAB built-in function.

The next lines are comments that will represent the function's help file. The first line of this section is called the H1 line. MATLAB searches for a particular word in the H1 line when the lookfor command is executed. As an example:

>> lookfor autocorrelation

will search through all of the H1 lines in all MATLAB functions for this word and will return information on that function if autocorrelation is found.

After the help text (or comments) is the part of the function that is called the function body. This is the part of the function that contains the executable lines of code. Any comments inside of the function body will not be a part of the help file will serve the same purpose as comments in a Script M-File.

If the programmer wants to have a particular variable recognized by particular functions, using the global command will allow this to occur. An example is:

>> global variable_name

fclose

Close one or more open files

Syntax

status = fclose(fid)

status = fclose('all')

Description

status = fclose(fid) closes the specified file, if it is open, returning 0 if successful and -1 if unsuccessful. Argument fid is a file identifier associated with an open file (See fopen for a complete description).

status = fclose('all') closes all open files, (except standard input, output, and error), returning 0 if successful and -1 if unsuccessful.

fopen

Open a file or obtain information about open files

Syntax

fid = fopen(filename,permission)

[fid,message] = fopen(filename,permission,format)

fids = fopen('all')

[filename,permission, format] = fopen(fid)

Description

If fopen successfully opens a file, it returns a file identifier fid, and the value of message is empty. The file identifier can be used as the first argument to other file input/output routines. If fopen does not successfully open the file, it returns a -1 value for fid. In that case, the value of message is a string that helps you determine the type of error that occurred.

Two fids are predefined and cannot be explicitly opened or closed:

· 1-- Standard output, which is always open for appending (permission set to 'a'), and

· 2 -- Standard error, which is always open for appending (permission set to 'a').

fid = fopen(filename,permission) opens the file filename in the mode specified by permission and returns fid, the file identifier. filename may a MATLABPATH relative partial pathname. If the file is opened for reading and it is not found in the current working directory, fopen searches down MATLAB's search path.

permission is one of the strings:

'r'	Open the file for reading (default).
'r+'	Open the file for reading and writing.
'w'	Delete the contents of an existing file or create a new file, and open it for writing.
'w+'	Delete the contents of an existing file or create new file, and open it for reading and writing.
'W'	Write without automatic flushing; used with tape drives
'a'	Create and open a new file or open an existing file for writing, appending to the end of the file.
'a+'	Create and open new file or open an existing file for reading and writing, appending to the end of the file.
'A'	Append without automatic flushing; used with tape drives

Add a 't' to these strings, for example, 'rt', on systems that distinguish between text and binary files, to force the file to be opened in text mode. Under DOS and VMS, for example, you cannot read a text file unless you set the permission to 'rt'. Similarly, use a 'b' to force the file to be opened in binary mode (the default).

[fid,message] = fopen(filename,permission,format) opens a file as above, returning file identifier and message. In addition, you specify the numeric format with format, a string defining the numeric format of the file, allowing you to share files between machines of different formats. If you omit the format argument, the numeric format of the local machine is used. Individual calls to fread or fwrite can override the numeric format specified in a call to fopen. Permitted format strings are:

'native' or 'n'	The numeric format of the machine you are currently running
'ieee-le' or 'l'	IEEE floating point with little-endian byte ordering
'ieee-be' or 'b'	IEEE floating point with big-endian byte ordering
'vaxd' or 'd'	VAX D floating point and VAX ordering
'vaxg' or 'g'	VAX G floating point and VAX ordering
'cray' or 'c'	Cray floating point with big-endian byte ordering
'ieee-le.l64' or 'a'	IEEE floating point with little-endian byte ordering and 64-bit long data type
'ieee-be.l64' or 's'	IEEE floating point with big-endian byte ordering and 64-bit long data type

fids = fopen('all') returns a row vector containing the file identifiers of all open files, not including 1 and 2 (standard output and standard error). The number of elements in the vector is equal to the number of open files.

[filename,permission,format] = fopen(fid) returns the full filename string, the permission string, and the format string associated with the specified file. An invalid fid returns empty strings for all output arguments. Both permission and format are optional.

fread

Read binary data from file

Syntax

[A,count] = fread(fid,size,precision)

[A,count] = fread(fid,size,precision,skip)

Description

[A,count] = fread(fid,size,precision) reads binary data from the specified file and writes it into matrix A. Optional output argument count returns the number of elements successfully read. fid is an integer file identifier obtained from fopen.

size is an optional argument that determines how much data is read. If size is not specified, fread reads to the end of the file. Valid options are:

n	Reads n elements into a column vector.
inf	Reads to the end of the file, resulting in a column vector containing the same number of elements as are in the file.
[m,n]	Reads enough elements to fill an m-by-n matrix, filling in elements in column order, padding with zeros if the file is too small to fill the matrix.

If fread reaches the end of the file and the current input stream does not contain enough bits to write out a complete matrix element of the specified precision, fread pads the last byte or element with zero bits until the full value is obtained. If an error occurs, reading is done up to the last full value.

precision is a string representing the numeric precision of the values read, precision controls the number of bits read for each value and the interpretation of those bits as an integer, a floating-point value, or a character. The precision string may contain a positive integer repetition factor of the form 'n*' which prepends one of the strings above, like '40*uchar'. If precision is not specified, the default is 'uchar' (8-bit unsigned character) is assumed. See "Remarks" for more information.

[A,count] = fread(fid,size,precision,skip) includes an optional skip argument that specifies the number of bytes to skip after each precision value is read. With the skip argument present, fread reads in one value and does a skip of input, reads in another value and does a skip of input, etc. for at most size times. This is useful for extracting data in noncontiguous fields from fixed length records. If precision is a bit format like 'bitN' or 'ubitN', skip is specified in bits.

Remarks

Numeric precisions can differ depending on how numbers are represented in your computer's architecture, as well as by the type of compiler used to produce executable code for your computer.

The tables below give C-compliant, platform-independent numeric precision string formats that you should use whenever you want your code to be portable.

For convenience, MATLAB accepts some C and Fortran data type equivalents for the MATLAB precisions listed. If you are a C or Fortran programmer, you may find it more convenient to use the names of the data types in the language with which you are most familiar

MATLAB	C or Fortran	Interpretation
'char'	'char*1'	Character; 8 bits
'schar'	'signed char'	Signed character; 8 bits
'uchar'	'unsigned char'	Unsigned character; 8 bits
'int8'	'integer*1'	Integer; 8 bits
'int16'	'integer*2'	Integer; 16 bits
'int32'	'integer*4'	Integer; 32 bits
'int64'	'integer*8'	Integer; 64 bits
'uint8'	'integer*1'	Unsigned integer; 8 bits
'uint16'	'integer*2'	Unsigned integer; 16 bits
'uint32'	'integer*4'	Unsigned integer; 32 bits
'uint64'	'integer*8'	Unsigned integer; 64 bits
'float32'	'real*4'	Floating-point; 32 bits
'float64'	'real*8'	Floating-point; 64 bits

If you always work on the same platform and don't care about portability, these platform-dependent numeric precision string formats are also available:

MATLAB	C or Fortran	Interpretation
'short'	'short'	Integer; 16 bits
'int'	'int'	Integer; 32 bits
'long'	'long'	Integer; 32 or 64 bits
'ushort'	'usigned short'	Unsigned integer; 16 bits
'uint'	'unsigned int'	Unsigned integer; 32 bits
'ulong'	'unsigned long'	Unsigned integer; 32 or 64 bits
'float'	'float'	Floating-point; 32 bits
'double'	'double'	Floating-point; 64 bits

fscanf

Read formatted data from file

Syntax

A = fscanf(fid,format)

[A,count] = fscanf(fid,format,size)

Description

A = fscanf(fid,format) reads all the data from the file specified by fid, converts it according to the specified format string, and returns it in matrix A. Argument fid is an integer file identifier obtained from fopen. format is a string specifying the format of the data to be read. See "Remarks" for details.

[A,count] = fscanf(fid,format,size) reads the amount of data specified by size, converts it according to the specified format string, and returns it along with a count of elements successfully read. size is an argument that determines how much data is read. Valid options are:

n	Read n elements into a column vector.
inf	Read to the end of the file, resulting in a column vector containing the same number of elements as are in the file.
[m,n]	Read enough elements to fill an m-by-n matrix, filling the matrix in column order. n can be Inf, but not m.

Remarks

When MATLAB reads a specified file, it attempts to match the data in the file to the format string. If a match occurs, the data is written into the matrix in column order. If a partial match occurs, only the matching data is written to the matrix, and the read operation stops.

The format string consists of ordinary characters and/or conversion specifications. Conversion specifications indicate the type of data to be matched and involve the character %, optional width fields, and conversion characters, organized as shown below:

Add one or more of these characters between the % and the conversion character:

An asterisk (*)	Skip over the matched value, if the value is matched but not stored in the output matrix.
A digit string	Maximum field width.
A letter	The size of the receiving object; for example, h for short as in %hd for a short integer, or l for long as in %ld for a long integer or %lg for a double floating-point number.

Valid conversion characters are:

%c	Sequence of characters; number specified by field width
%d	Decimal numbers
%e, %f, %g	Floating-point numbers
%I	Signed integer
%o	Signed octal integer
%s	A series of non-white-space characters
%u	Signed decimal integer
%x	Signed hexadecimal integer
[...]	Sequence of characters (scanlist)

If %s is used, an element read may use several MATLAB matrix elements, each holding one character. Use %c to read space characters; the format %s skips all white space.

Mixing character and numeric conversion specifications cause the resulting matrix to be numeric and any characters read to appear as their ASCII values, one character per MATLAB matrix element.

For more information about format strings, refer to the scanf() and fscanf() routines in a C language reference manual.

Examples

The example in fprintf generates an ASCII text file called exp.txt that looks like:

0.00 1.00000000

0.10 1.10517092

...

1.00 2.71828183

Read this ASCII file back into a two-column MATLAB matrix:

>>fid = fopen('exp.txt');

>>a = fscanf(fid,'%g %g',[2 inf]) % It has two rows now.

>>a = a';

>>fclose(fid)

fwrite

Write binary data to a file

Syntax

count = fwrite(fid,A,precision)

count = fwrite(fid,A,precision,skip)

Description

count = fwrite(fid,A,precision) writes the elements of matrix A to the specified file, translating MATLAB values to the specified numeric precision. (See "Remarks" for more information.)

The data are written to the file in column order, and a count is kept of the number of elements written successfully. Argument fid is an integer file identifier obtained from fopen.

count = fwrite(fid,A,precision,skip) includes an optional skip argument that specifies the number of bytes to skip before each precision value is written. With the skip argument present, fwrite skips and writes one value, skips and writes another value, etc. until all of A is written. This is useful for inserting data into noncontiguous fields in fixed-length records. If precision is a bit format like 'bitN' or 'ubitN', skip is specified in bits.

Remarks

Numeric precisions can differ depending on how numbers are represented in your computer's architecture, as well as by the type of compiler used to produce executable code for your computer.

The tables below give C-compliant, platform-independent numeric precision string formats that you should use whenever you want your code to be portable.

MATLAB	C or Fortran	Interpretation
'char'	'char*1'	Character; 8 bits
'schar'	'signed char'	Signed character; 8 bits
'uchar'	'unsigned char'	Unsigned character; 8 bits
'int8'	'integer*1'	Integer; 8 bits
'int16'	'integer*2'	Integer; 16 bits
'int32'	'integer*4'	Integer; 32 bits
'int64'	'integer*8'	Integer; 64 bits
'uint8'	'integer*1'	Unsigned integer; 8 bits
'uint16'	'integer*2'	Unsigned integer; 16 bits
'uint32'	'integer*4'	Unsigned integer; 32 bits
'uint64'	'integer*8'	Unsigned integer; 64 bits
'float32'	'real*4'	Floating-point; 32 bits
'float64'	'real*8'	Floating-point; 64 bits

If you always work on the same platform and don't care about portability, these platform-dependent numeric precision string formats are also available:

MATLAB	C or Fortran	Interpretation
'short'	'short'	Integer; 16 bits
'int'	'int'	Integer; 32 bits
'long'	'long'	Integer; 32 or 64 bits
'ushort'	'usigned short'	Unsigned integer; 16 bits
'uint'	'unsigned int'	Unsigned integer; 32 bits
'ulong'	'unsigned long'	Unsigned integer; 32 or 64 bits
'float'	'float'	Floating-point; 32 bits
'double'	'double'	Floating-point; 64 bits

Two formats map to an input steam of bits rather than bytes:

Examples

>>fid = fopen('magic5.bin','wb');

>>fwrite(fid,magic(5),'integer*4')

creates a 100-byte binary file, containing the 25 elements of the 5-by-5 magic square, stored as 4-byte integers.

sprintf

Write formatted data to a string

Syntax

s = sprintf(format,A,...)

[s,errrmsg] = sprintf(format,A,...)

Description

s = sprintf(format,A,...) formats the data in matrix A (and in any additional matrix arguments) under control of the specified format string, and returns it in the MATLAB string variable s. sprintf is the same as fprintf except that it returns the data in a MATLAB string variable rather than writing it to a file.

The format string specifies notation, alignment, significant digits, field width, and other aspects of output format. It can contain ordinary alphanumeric characters; along with escape characters, conversion specifiers, and other characters, organized as shown below:
For more information see "Tables" and "References."

[s,errrmsg] = sprintf(format,A,...) returns an error message string errmsg if an error occurred or an empty matrix if an error did not occur.

Remarks

The sprintf function behaves like its ANSI C language sprintf() namesake with certain exceptions and extensions. These include:

1.The following nonstandard subtype specifiers are supported for conversion specifiers %o, %u, %x, and %X.
For example, to print a double-precision value in hexadecimal, use a format like '%bx'.

2. sprintf is vectorized for the case when input matrix A is nonscalar. The format string is cycled through the elements of A (columnwise) until all the elements are used up. It is then cycled in a similar manner, without reinitializing, through any additional matrix arguments.

Tables

The following tables describe the nonalphanumeric characters found in format specification strings.

Escape Characters

Character	Description
\n	New line
\t	Horizontal tab
\b	Backspace
\r	Carriage return
\f	Form feed
\\	Backslash
\'' or '' (two single quotes)	Single quotation mark
%%	Percent character

Conversion characters specify the notation of the output.

Conversion Specifiers:

Specifier	Description
%c	Single character
%d	Decimal notation (signed)
%e	Exponential notation (using a lowercase e as in 3.1415e+00)
%E	Exponential notation (using an uppercase E as in 3.1415E+00)
%f	Fixed-point notation
%g	The more compact of %e or %f, as defined in [2]. Insignificant zeros do not print.
%G	Same as %g, but using an uppercase E
%o	Octal notation (unsigned)
%s	String of characters
%u	Decimal notation (unsigned)
%x	Hexadecimal notation (using lowercase letters a-f)
%X	Hexadecimal notation (using uppercase letters A-F)

Other characters can be inserted into the conversion specifier between the % and the conversion character.

Other Characters:

Character	Description	Example
A minus sign (-)	Left-justifies the converted argument in its field.	%-5.2d
A plus sign (+)	Always prints a sign character (+ or -).	%+5.2d
Zero (0)	Pad with zeros rather than spaces.	%05.2d
Digits (field width)	A digit string specifying the minimum number of digits to be printed.	%6f
Digits (precision)	A digit string including a period (.) specifying the number of digits to be printed to the right of the decimal point.	%6.2f

Examples

Command	Result
>>sprintf('%0.5g',(1+sqrt(5))/2)	1.618
>>sprintf('%0.5g',1/eps)	4.5036e+15
>>sprintf('%15.5f',1/eps)	4503599627370496.00000
>>sprintf('%d',round(pi))	3
>>sprintf('%s','hello')	Hello
>>sprintf('The array is %dx%d.',2,3)	The array is 2x3
>>sprintf('\n')	Line termination character on all platforms

sscanf

Read string under format control

Syntax

A = sscanf(s,format)

A = sscanf(s,format,size)

[A,count,errmsg,nextindex] = sscanf(...)

Description

A = sscanf(s,format) reads data from the MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. format is a string specifying the format of the data to be read. See "Remarks" for details. sscanf is the same as fscanf except that it reads the data from a MATLAB string variable rather than reading it from a file.

A = sscanf(s,format,size) reads the amount of data specified by size and converts it according to the specified format string. size is an argument that determines how much data is read. Valid options are:

n	Read n elements into a column vector.
inf	Read to the end of the file, resulting in a column vector containing the same number of elements as are in the file.
[m,n]	Read enough elements to fill an m-by-n matrix, filling the matrix in column order. n can be Inf, but not m.

If the matrix A results from using character conversions only and size is not of the form [M,N], a row vector is returned.

sscanf differs from its C language namesakes scanf() and fscanf() in an important respect -- it is vectorized in order to return a matrix argument. The format string is cycled through the file until an end-of-file is reached or the amount of data specified by size is read in.

[A,count,errmsg,nextindex] = sscanf(...) reads data from MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. count is an optional output argument that returns the number of elements successfully read. errmsg is an optional output argument that returns an error message string if an error occurred or an empty matrix if an error did not occur. nextindex is an optional output argument specifying one more than the number of characters scanned in s.

Remarks

An asterisk (*)	Skip over the matched value, if the value is matched but not stored in the output matrix.
A digit string	Maximum field width.
A letter	The size of the receiving object; for example, h for short as in %hd for a short integer, or l for long as in %ld for a long integer or %lg for a double floating-point number.

Valid conversion characters are:

%c	Sequence of characters; number specified by field width
%d	Decimal numbers
%e, %f, %g	Floating-point numbers
%I	Signed integer
%o	Signed octal integer
%s	A series of non-whitespace characters
%u	Signed decimal integer
%x	Signed hexadecimal integer
[...]	Sequence of characters (scanlist)

If %s is used, an element read may use several MATLAB matrix elements, each holding one character. Use %c to read space characters; the format %s skips all white space.

Mixing character and numeric conversion specifications cause the resulting matrix to be numeric and any characters read to appear as their ASCII values, one character per MATLAB matrix element.

Examples

The statements

>>s = '2.7183 3.1416';

>>A = sscanf(s,'%f')

create a two-element vector containing poor approximations to e and pi.

tic, toc

Stopwatch timer

Syntax

tic

any statements

toc

t = toc

Description

tic starts a stopwatch timer.

toc prints the elapsed time since tic was used.

t = toc returns the elapsed time in t.

Examples

This example measures how the time required to solve a linear system varies with the order of a matrix.

>> for n = 1:100

>> A = rand(n);

>> b = rand(n);

>> tic

>> x = A\b;

>> t(n) = toc;

>> end

>> plot(t)

min

Minimum elements of an array

Syntax

C = min(A)

[C,I] = min(...)

Description

C = min(A) returns the smallest elements along different dimensions of an array.

If A is a vector, min(A) returns the smallest element in A.

If A is a matrix, min(A) treats the columns of A as vectors, returning a row vector containing the minimum element from each column.

[C,I] = min(...) finds the indices of the minimum values of A, and returns them in output vector I. If there are several identical minimum values, the index of the first one found is returned.

Examples

>> X = [1 2 3 4 5];

>> min(X)

>> Y = [1 2 3 4; 5 6 7 8; 9 10 11 12];

>> min(Y)

>> [C,I] = min(X)

>> [C,I] = min(Y)

max

Maximum elements of an array

Syntax

C = max(A)

[C,I] = max(...)

Description

C = max(A) returns the largest elements along different dimensions of an array.

If A is a vector, max(A) returns the largest element in A.

If A is a matrix, max(A) treats the columns of A as vectors, returning a row vector containing the maximum element from each column.

[C,I] = max(...) finds the indices of the maximum values of A, and returns them in output vector I. If there are several identical maximum values, the index of the first one found is returned.

Example

>> X = [1 2 3 4 5];

>> max(X)

>> Y = [1 2 3 4; 5 6 7 8; 9 10 11 12]

>> max(Y)

>> [C,I] = max(X)

>> [C,I] = max(Y)

mean

Average or mean value of arrays

Syntax

M = mean(A)

Description

If A is a vector, mean(A) returns the mean value of A.

If A is a matrix, mean(A) treats the columns of A as vectors, returning a row vector of mean values.

Examples

>> A = [1 2 4 4; 3 4 6 6; 5 6 8 8; 5 6 8 9];

>> mean(A)

>> B = [1 2 3 4 5 6 7 8 9];

>> mean(B)

median

Median value of arrays

Syntax

M = median(A)

Description

M = median(A) returns the median values of the elements along different dimensions of an array.

If A is a vector, median(A) returns the median value of A.

If A is a matrix, median(A) treats the columns of A as vectors, returning a row vector of median values.

Examples

>> median(A)

>> median(B)

Notice how an odd number of elements has the middle value selected and an even number of elements has the two middle values averaged.

sort

Sort elements in ascending order

Syntax

B = sort(A)

[B,INDEX] = sort(A)

Description

B = sort(A) sorts the elements along different dimensions of an array, and arranges those elements in ascending order. For identical values in A, the location in the input array determines location in the sorted list. If A includes any NaN elements, sort places these at the end.

If A is a vector, sort(A) arranges those elements in ascending order.

If A is a matrix, sort(A) treats the columns of A as vectors, returning sorted columns.

[B,INDEX] = sort(A) also returns an array of indices. INDEX is an array of size(A), each column of which is a permutation vector of the corresponding column of A. If A has repeated elements of equal value, indices are returned that preserve the original relative ordering.

Examples

>> W = [1 2 3 7 6 5 8 9 0 999 333 444];

>> [B, INDEX] = sort(W)

References:

- The MathWorks, Inc. Online (Helpdesk) Documentation

by The MathWorks, Inc.

- Mastering MATLAB 5

by Duane Hanselman and Bruce Littlefield

- Engineering Problem Solving with MATLAB

by D.M. Etter