MATLAB®

Programming Fundamentals

R2020a
How to Contact MathWorks

Latest news: www.mathworks.com

Sales and services: www.mathworks.com/sales_and_services

User community: www.mathworks.com/matlabcentral

Technical support: www.mathworks.com/support/contact_us

Phone: 508-647-7000

The MathWorks, Inc.

1 Apple Hill Drive
Natick, MA 01760-2098
MATLAB Programming Fundamentals
© COPYRIGHT 1984–2020 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 reproduced in any form
without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through
the federal government of the United States. By accepting delivery of the Program or Documentation, the government
hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer
software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014.
Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain
to and govern the use, modification, reproduction, release, performance, display, and disclosure of the Program and
Documentation by the federal government (or other entity acquiring for or through the federal government) and shall
supersede any conflicting contractual terms or conditions. If this License fails to meet the government's needs or is
inconsistent in any respect with federal procurement law, the government agrees to return the Program and
Documentation, unused, to The MathWorks, Inc.
Trademarks
MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See
www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be
trademarks or registered trademarks of their respective holders.
Patents
MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for
more information.
Revision History
June 2004 First printing New for MATLAB 7.0 (Release 14)
October 2004 Online only Revised for MATLAB 7.0.1 (Release 14SP1)
March 2005 Online only Revised for MATLAB 7.0.4 (Release 14SP2)
June 2005 Second printing Minor revision for MATLAB 7.0.4
September 2005 Online only Revised for MATLAB 7.1 (Release 14SP3)
March 2006 Online only Revised for MATLAB 7.2 (Release 2006a)
September 2006 Online only Revised for MATLAB 7.3 (Release 2006b)
March 2007 Online only Revised for MATLAB 7.4 (Release 2007a)
September 2007 Online only Revised for Version 7.5 (Release 2007b)
March 2008 Online only Revised for Version 7.6 (Release 2008a)
October 2008 Online only Revised for Version 7.7 (Release 2008b)
March 2009 Online only Revised for Version 7.8 (Release 2009a)
September 2009 Online only Revised for Version 7.9 (Release 2009b)
March 2010 Online only Revised for Version 7.10 (Release 2010a)
September 2010 Online only Revised for Version 7.11 (Release 2010b)
April 2011 Online only Revised for Version 7.12 (Release 2011a)
September 2011 Online only Revised for Version 7.13 (Release 2011b)
March 2012 Online only Revised for Version 7.14 (Release 2012a)
September 2012 Online only Revised for Version 8.0 (Release 2012b)
March 2013 Online only Revised for Version 8.1 (Release 2013a)
September 2013 Online only Revised for Version 8.2 (Release 2013b)
March 2014 Online only Revised for Version 8.3 (Release 2014a)
October 2014 Online only Revised for Version 8.4 (Release 2014b)
March 2015 Online only Revised for Version 8.5 (Release 2015a)
September 2015 Online only Revised for Version 8.6 (Release 2015b)
October 2015 Online only Rereleased for Version 8.5.1 (Release 2015aSP1)
March 2016 Online only Revised for Version 9.0 (Release 2016a)
September 2016 Online only Revised for Version 9.1 (Release 2016b)
March 2017 Online only Revised for Version 9.2 (Release 2017a)
September 2017 Online only Revised for Version 9.3 (Release 2017b)
March 2018 Online only Revised for Version 9.4 (Release 2018a)
September 2018 Online only Revised for Version 9.5 (Release 2018b)
March 2019 Online only Revised for MATLAB 9.6 (Release 2019a)
September 2019 Online only Revised for MATLAB 9.7 (Release 2019b)
March 2020 Online only Revised for MATLAB 9.8 (Release 2020a)
 Contents

Language

Syntax Basics
1
Continue Long Statements on Multiple Lines . . . . . . . . . . . . . . . . . . . 1-2

Ignore Function Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Valid Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Conflicts with Function Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Case and Space Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

Command vs. Function Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Command and Function Syntaxes . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Avoid Common Syntax Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
How MATLAB Recognizes Command Syntax . . . . . . . . . . . . . . . . . . . 1-7

Common Errors When Calling Functions . . . . . . . . . . . . . . . . . . . . . . 1-9

Conflicting Function and Variable Names . . . . . . . . . . . . . . . . . . . . . 1-9
Undefined Functions or Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Program Components
2
MATLAB Operators and Special Characters . . . . . . . . . . . . . . . . . . . . 2-2
Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Logical Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
String and Character Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

Array vs. Matrix Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20
Matrix Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22

Compatible Array Sizes for Basic Operations . . . . . . . . . . . . . . . . . . 2-25

Inputs with Compatible Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25

v
 Inputs with Incompatible Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

Array Comparison with Relational Operators . . . . . . . . . . . . . . . . . . 2-29

Array Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29
Logic Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-31

Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

Precedence of AND and OR Operators . . . . . . . . . . . . . . . . . . . . . . 2-32
Overriding Default Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

Average Similar Data Points Using a Tolerance . . . . . . . . . . . . . . . . 2-34

Group Scattered Data Using a Tolerance . . . . . . . . . . . . . . . . . . . . . . 2-36

Bit-Wise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-38

Perform Cyclic Redundancy Check . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44

Conditional Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47

Loop Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-49

Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51

What Is a Regular Expression? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-51
Steps for Building Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52
Operators and Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-54

Lookahead Assertions in Regular Expressions . . . . . . . . . . . . . . . . . 2-63

Lookahead Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63
Overlapping Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-63
Logical AND Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-64

Tokens in Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-66
Multiple Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-68
Unmatched Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69
Tokens in Replacement Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69
Named Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-70

Dynamic Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-72
Dynamic Match Expressions — (??expr) . . . . . . . . . . . . . . . . . . . . . 2-73
Commands That Modify the Match Expression — (??@cmd) . . . . . . 2-73
Commands That Serve a Functional Purpose — (?@cmd) . . . . . . . . 2-74
Commands in Replacement Expressions — ${cmd} . . . . . . . . . . . . 2-76

Comma-Separated Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-79

What Is a Comma-Separated List? . . . . . . . . . . . . . . . . . . . . . . . . . 2-79
Generating a Comma-Separated List . . . . . . . . . . . . . . . . . . . . . . . . 2-79
Assigning Output from a Comma-Separated List . . . . . . . . . . . . . . . 2-81
Assigning to a Comma-Separated List . . . . . . . . . . . . . . . . . . . . . . . 2-81
How to Use the Comma-Separated Lists . . . . . . . . . . . . . . . . . . . . . 2-82
Fast Fourier Transform Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-84

vi Contents
 Alternatives to the eval Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86
Why Avoid the eval Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86
Variables with Sequential Names . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86
Files with Sequential Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87
Function Names in Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-87
Field Names in Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-88
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-88

Classes (Data Types)

Overview of MATLAB Classes

3
Fundamental MATLAB Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Numeric Classes
4
Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Integer Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Creating Integer Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Arithmetic Operations on Integer Classes . . . . . . . . . . . . . . . . . . . . . 4-4
Largest and Smallest Values for Integer Classes . . . . . . . . . . . . . . . . 4-4

Floating-Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6

Double-Precision Floating Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Single-Precision Floating Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Creating Floating-Point Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Arithmetic Operations on Floating-Point Numbers . . . . . . . . . . . . . . 4-8
Largest and Smallest Values for Floating-Point Classes . . . . . . . . . . . 4-9
Accuracy of Floating-Point Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
Avoiding Common Problems with Floating-Point Arithmetic . . . . . . 4-11

Create Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13

Infinity and NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Infinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14
NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14

Identifying Numeric Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16

Display Format for Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

Integer Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19

Single Precision Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-26

vii
 The Logical Class
5
Find Array Elements That Meet a Condition . . . . . . . . . . . . . . . . . . . . 5-2

Reduce Logical Arrays to Single Value . . . . . . . . . . . . . . . . . . . . . . . . 5-6

Characters and Strings

6
Text in String and Character Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Create String Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5

Cell Arrays of Character Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12

Create Cell Array of Character Vectors . . . . . . . . . . . . . . . . . . . . . . 6-12
Access Character Vectors in Cell Array . . . . . . . . . . . . . . . . . . . . . . 6-12
Convert Cell Arrays to String Arrays . . . . . . . . . . . . . . . . . . . . . . . . 6-13

Analyze Text Data with String Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 6-15

Test for Empty Strings and Missing Values . . . . . . . . . . . . . . . . . . . . 6-20

Formatting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24

Fields of the Formatting Operator . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
Setting Field Width and Precision . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28
Restrictions on Using Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30

Compare Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32

Search and Replace Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37

Convert Numeric Values to Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42

Convert Text to Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46

Unicode and ASCII Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50

Hexadecimal and Binary Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52

Frequently Asked Questions About String Arrays . . . . . . . . . . . . . . . 6-56

Why Does Using Command Form With Strings Return An Error? . . 6-56
Why Do Strings in Cell Arrays Return an Error? . . . . . . . . . . . . . . . 6-57
Why Does length() of String Return 1? . . . . . . . . . . . . . . . . . . . . . . 6-57
Why Does isempty("") Return 0? . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-58
Why Does Appending Strings Using Square Brackets Return Multiple
Strings? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59

Update Your Code to Accept Strings . . . . . . . . . . . . . . . . . . . . . . . . . 6-61

What Are String Arrays? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61
Recommended Approaches for String Adoption in Old APIs . . . . . . 6-61

viii Contents
 How to Adopt String Arrays in Old APIs . . . . . . . . . . . . . . . . . . . . . 6-63
Recommended Approaches for String Adoption in New Code . . . . . 6-63
How to Maintain Compatibility in New Code . . . . . . . . . . . . . . . . . . 6-64
How to Manually Convert Input Arguments . . . . . . . . . . . . . . . . . . 6-65
How to Check Argument Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6-65
Terminology for Character and String Arrays . . . . . . . . . . . . . . . . . 6-67

Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69

Dates and Time

7
Represent Dates and Times in MATLAB . . . . . . . . . . . . . . . . . . . . . . . 7-2

Specify Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5

Convert Date and Time to Julian Date or POSIX Time . . . . . . . . . . . . 7-7

Set Date and Time Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10

Formats for Individual Date and Duration Arrays . . . . . . . . . . . . . . 7-10
datetime Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
duration Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
calendarDuration Display Format . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Default datetime Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12

Generate Sequence of Dates and Time . . . . . . . . . . . . . . . . . . . . . . . 7-14

Sequence of Datetime or Duration Values Between Endpoints with
Step Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-14
Add Duration or Calendar Duration to Create Sequence of Dates . . 7-16
Specify Length and Endpoints of Date or Duration Sequence . . . . . 7-17
Sequence of Datetime Values Using Calendar Rules . . . . . . . . . . . . 7-17

Share Code and Data Across Locales . . . . . . . . . . . . . . . . . . . . . . . . . 7-20

Write Locale-Independent Date and Time Code . . . . . . . . . . . . . . . . 7-20
Write Dates in Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21
Read Dates in Other Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-21

Extract or Assign Date and Time Components of Datetime Array . . 7-23

Combine Date and Time from Separate Variables . . . . . . . . . . . . . . 7-26

Date and Time Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-28

Compare Dates and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-33

Plot Dates and Durations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36

Line Plot with Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36
Line Plot with Durations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-37
Scatter Plot with Dates and Durations . . . . . . . . . . . . . . . . . . . . . . 7-39
Plots that Support Dates and Durations . . . . . . . . . . . . . . . . . . . . . 7-40

Core Functions Supporting Date and Time Arrays . . . . . . . . . . . . . . 7-41

ix
 Convert Between Datetime Arrays, Numbers, and Text . . . . . . . . . . 7-42
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-42
Convert Between Datetime and Character Vectors . . . . . . . . . . . . . 7-42
Convert Between Datetime and String Arrays . . . . . . . . . . . . . . . . . 7-44
Convert Between Datetime and Date Vectors . . . . . . . . . . . . . . . . . 7-44
Convert Serial Date Numbers to Datetime . . . . . . . . . . . . . . . . . . . 7-45
Convert Datetime Arrays to Numeric Values . . . . . . . . . . . . . . . . . . 7-45

Carryover in Date Vectors and Strings . . . . . . . . . . . . . . . . . . . . . . . . 7-47

Converting Date Vector Returns Unexpected Output . . . . . . . . . . . . 7-48

Categorical Arrays
8
Create Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Convert Text in Table Variables to Categorical . . . . . . . . . . . . . . . . . . 8-6

Plot Categorical Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

Compare Categorical Array Elements . . . . . . . . . . . . . . . . . . . . . . . . 8-16

Combine Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19

Combine Categorical Arrays Using Multiplication . . . . . . . . . . . . . . 8-22

Access Data Using Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . . . 8-24

Select Data By Category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Common Ways to Access Data Using Categorical Arrays . . . . . . . . . 8-24

Work with Protected Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . 8-30

Advantages of Using Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . 8-34

Natural Representation of Categorical Data . . . . . . . . . . . . . . . . . . 8-34
Mathematical Ordering for Character Vectors . . . . . . . . . . . . . . . . . 8-34
Reduce Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-34

Ordinal Categorical Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-36

Order of Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-36
How to Create Ordinal Categorical Arrays . . . . . . . . . . . . . . . . . . . 8-36
Working with Ordinal Categorical Arrays . . . . . . . . . . . . . . . . . . . . 8-38

Core Functions Supporting Categorical Arrays . . . . . . . . . . . . . . . . 8-39

x Contents
 Tables
9
Create and Work with Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Add and Delete Table Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11

Add, Delete, and Rearrange Table Variables . . . . . . . . . . . . . . . . . . . 9-14

Clean Messy and Missing Data in Tables . . . . . . . . . . . . . . . . . . . . . . 9-21

Modify Units, Descriptions, and Table Variable Names . . . . . . . . . . 9-26

Add Custom Properties to Tables and Timetables . . . . . . . . . . . . . . 9-29

Access Data in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-34

Summary of Table Indexing Syntaxes . . . . . . . . . . . . . . . . . . . . . . . 9-34
Tables Containing Specified Rows and Variables . . . . . . . . . . . . . . . 9-37
Extract Data Using Dot Notation and Logical Values . . . . . . . . . . . . 9-40
Dot Notation with Any Variable Name or Expression . . . . . . . . . . . . 9-42
Extract Data from Specified Rows and Variables . . . . . . . . . . . . . . . 9-44

Calculations on Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-47

Split Data into Groups and Calculate Statistics . . . . . . . . . . . . . . . . 9-50

Split Table Data Variables and Apply Functions . . . . . . . . . . . . . . . . 9-53

Advantages of Using Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-57

Grouping Variables To Split Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-62

Grouping Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-62
Group Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-62
The Split-Apply-Combine Workflow . . . . . . . . . . . . . . . . . . . . . . . . . 9-63
Missing Group Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-63

Changes to DimensionNames Property in R2016b . . . . . . . . . . . . . . 9-65

Timetables
10
Create Timetables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

Resample and Aggregate Data in Timetable . . . . . . . . . . . . . . . . . . . 10-5

Combine Timetables and Synchronize Their Data . . . . . . . . . . . . . . 10-8

Retime and Synchronize Timetable Variables Using Different

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14

xi
 Select Timetable Data by Row Time and Variable Type . . . . . . . . . 10-19

Clean Timetable with Missing, Duplicate, or Nonuniform Times

.................................................... 10-25

Using Row Labels in Table and Timetable Operations . . . . . . . . . . 10-33

Loma Prieta Earthquake Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 10-38

Preprocess and Explore Time-stamped Data Using timetable . . . . 10-48

Structures
11
Create Structure Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2

Access Data in Structure Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5

Access Data in Scalar Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Access Data by Indexing into Structure Array . . . . . . . . . . . . . . . . . 11-6

Concatenate Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-9

Generate Field Names from Variables . . . . . . . . . . . . . . . . . . . . . . . 11-11

Access Data in Nested Structures . . . . . . . . . . . . . . . . . . . . . . . . . . 11-12

Access Elements of a Nonscalar Struct Array . . . . . . . . . . . . . . . . . 11-14

Ways to Organize Data in Structure Arrays . . . . . . . . . . . . . . . . . . . 11-16

Plane Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-16
Element-by-Element Organization . . . . . . . . . . . . . . . . . . . . . . . . 11-17

Memory Requirements for Structure Array . . . . . . . . . . . . . . . . . . 11-19

Cell Arrays
12
What Is a Cell Array? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2

Create Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3

Access Data in Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5

Add Cells to Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-8

Delete Data from Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-9

Combine Cell Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-10

xii Contents
 Pass Contents of Cell Arrays to Functions . . . . . . . . . . . . . . . . . . . . 12-11

Preallocate Memory for Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . 12-15

Cell vs. Structure Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-16

Multilevel Indexing to Access Parts of Cells . . . . . . . . . . . . . . . . . . 12-20

Function Handles
13
Create Function Handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
What Is a Function Handle? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Creating Function Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Arrays of Function Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Saving and Loading Function Handles . . . . . . . . . . . . . . . . . . . . . . 13-4

Pass Function to Another Function . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5

Call Local Functions Using Function Handles . . . . . . . . . . . . . . . . . 13-6

Compare Function Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-8

Map Containers
14
Overview of Map Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

Description of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Properties of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Methods of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4

Create Map Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6

Construct Empty Map Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Construct Initialized Map Object . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Combine Map Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7

Examine Contents of Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-8

Read and Write Using Key Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9

Read From Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Add Key/Value Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
Build Map with Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10

Modify Keys and Values in Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13

Remove Keys and Values from Map . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Modify Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Modify Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14

xiii
 Modify Copy of Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14

Map to Different Value Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15

Map to Structure Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15
Map to Cell Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16

Combining Unlike Classes

15
Valid Combinations of Unlike Classes . . . . . . . . . . . . . . . . . . . . . . . . 15-2

Combining Unlike Integer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Example of Combining Unlike Integer Sizes . . . . . . . . . . . . . . . . . . 15-3
Example of Combining Signed with Unsigned . . . . . . . . . . . . . . . . . 15-3

Combining Integer and Noninteger Data . . . . . . . . . . . . . . . . . . . . . 15-5

Combining Cell Arrays with Non-Cell Arrays . . . . . . . . . . . . . . . . . . 15-6

Empty Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7

Concatenation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8

Combining Single and Double Types . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Combining Integer and Double Types . . . . . . . . . . . . . . . . . . . . . . . 15-8
Combining Character and Double Types . . . . . . . . . . . . . . . . . . . . . 15-8
Combining Logical and Double Types . . . . . . . . . . . . . . . . . . . . . . . 15-8

Using Objects
16
Object Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Two Copy Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Handle Object Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Value Object Copy Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Handle Object Copy Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Testing for Handle or Value Class . . . . . . . . . . . . . . . . . . . . . . . . . . 16-5

xiv Contents
 Defining Your Own Classes
17

Scripts and Functions

Scripts
18
Create Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2

Add Comments to Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3

Code Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5

Divide Your File into Code Sections . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Evaluate Code Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Navigate Among Code Sections in a File . . . . . . . . . . . . . . . . . . . . . 18-6
Example of Evaluating Code Sections . . . . . . . . . . . . . . . . . . . . . . . 18-6
Change the Appearance of Code Sections . . . . . . . . . . . . . . . . . . . . 18-9
Use Code Sections with Control Statements and Functions . . . . . . . 18-9

Scripts vs. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-12

Add Functions to Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-14

Create a Script with Local Functions . . . . . . . . . . . . . . . . . . . . . . 18-14
Run Scripts with Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . 18-14
Restrictions for Local Functions and Variables . . . . . . . . . . . . . . . 18-15
Access Help for Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 18-15

Live Scripts and Functions

19
What Is a Live Script or Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Differences with Plain Code Scripts and Functions . . . . . . . . . . . . . 19-3
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5

Create Live Scripts in the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . 19-6

Create Live Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Add Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Run Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-8
Display Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-8
Format Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-9
Save Live Scripts as Plain Code . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10

xv
 Run Sections in Live Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-12
Divide Your File Into Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-12
Evaluate Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-12

Debug Code in the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14

Show Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-14
Debug Using Run to Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-15
View Variable Value While Debugging . . . . . . . . . . . . . . . . . . . . . . 19-17
Pause a Running File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-17
End Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-17
Step Into Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-18
Add Breakpoints and Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-18

Modify Figures in Live Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22

Explore Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-22
Update Code with Figure Changes . . . . . . . . . . . . . . . . . . . . . . . . 19-24
Add Formatting and Annotations . . . . . . . . . . . . . . . . . . . . . . . . . 19-24
Add and Modify Multiple Subplots . . . . . . . . . . . . . . . . . . . . . . . . 19-26
Save and Print Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-30

Format Files in the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-31

Autoformatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-33

Insert Equations into the Live Editor . . . . . . . . . . . . . . . . . . . . . . . 19-35

Insert Equation Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-35
Insert LaTeX Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-37

Add Interactive Controls to a Live Script . . . . . . . . . . . . . . . . . . . . 19-44

Insert Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-44
Modify Control Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-45
Modify Control Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-46
Create Live Script with Multiple Interactive Controls . . . . . . . . . . 19-46
Share Live Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-48

Add Interactive Tasks to a Live Script . . . . . . . . . . . . . . . . . . . . . . . 19-49

What Are Live Editor Tasks? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-49
Insert Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-49
Run Tasks and Surrounding Code . . . . . . . . . . . . . . . . . . . . . . . . . 19-52
Modify Output Argument Name . . . . . . . . . . . . . . . . . . . . . . . . . . 19-53
View and Edit Generated Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-53

Create Live Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-55

Create Live Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-55
Add Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-55
Add Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-56
Run Live Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-56
Save Live Functions as Plain Code . . . . . . . . . . . . . . . . . . . . . . . . 19-57

Add Help for Live Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-58

Share Live Scripts and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-62

Hide Code Before Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-63

Live Code File Format (.mlx) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-64

Benefits of Live Code File Format . . . . . . . . . . . . . . . . . . . . . . . . . 19-64

xvi Contents
 Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-64

Introduction to the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-65

Accelerate Exploratory Programming Using the Live Editor . . . . . 19-70

Create an Interactive Narrative with the Live Editor . . . . . . . . . . . 19-74

Create Interactive Course Materials Using the Live Editor . . . . . . 19-81

Create Examples Using the Live Editor . . . . . . . . . . . . . . . . . . . . . . 19-87

Create an Interactive Form Using the Live Editor . . . . . . . . . . . . . 19-88

Create a Real-time Dashboard Using the Live Editor . . . . . . . . . . . 19-91

Function Basics
20
Create Functions in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Syntax for Function Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Contents of Functions and Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
End Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4

Add Help for Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5

Configure the Run Button for Functions . . . . . . . . . . . . . . . . . . . . . . 20-7

Base and Function Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9

Share Data Between Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Best Practice: Passing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Nested Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Persistent Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11
Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-12
Evaluating in Another Workspace . . . . . . . . . . . . . . . . . . . . . . . . . 20-12

Check Variable Scope in Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-14

Use Automatic Function and Variable Highlighting . . . . . . . . . . . . 20-14
Example of Using Automatic Function and Variable Highlighting . 20-14

Types of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-17

Local and Nested Functions in a File . . . . . . . . . . . . . . . . . . . . . . 20-17
Private Functions in a Subfolder . . . . . . . . . . . . . . . . . . . . . . . . . . 20-18
Anonymous Functions Without a File . . . . . . . . . . . . . . . . . . . . . . 20-18

Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20

What Are Anonymous Functions? . . . . . . . . . . . . . . . . . . . . . . . . . 20-20
Variables in the Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21
Multiple Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21

xvii
 Functions with No Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-22
Functions with Multiple Inputs or Outputs . . . . . . . . . . . . . . . . . . 20-22
Arrays of Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 20-23

Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-25

Nested Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27

What Are Nested Functions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27
Requirements for Nested Functions . . . . . . . . . . . . . . . . . . . . . . . 20-27
Sharing Variables Between Parent and Nested Functions . . . . . . . 20-28
Using Handles to Store Function Parameters . . . . . . . . . . . . . . . . 20-29
Visibility of Nested Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-31

Variables in Nested and Anonymous Functions . . . . . . . . . . . . . . . 20-33

Private Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-34

Function Precedence Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-35

Change in Rules For Function Precedence Order . . . . . . . . . . . . . 20-36

Update Code for R2019b Changes to Function Precedence Order

.................................................... 20-38
Identifiers cannot be used for two purposes inside a function . . . . 20-38
Identifiers without explicit declarations might not be treated as
variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-38
Variables cannot be implicitly shared between parent and nested
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-39
Change in precedence of wildcard-based imports . . . . . . . . . . . . . 20-40
Fully qualified import functions cannot have the same name as nested
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-40
Fully qualified imports shadow outer scope definitions of the same
name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-41
Error handling when import not found . . . . . . . . . . . . . . . . . . . . . 20-41
Nested functions inherit import statements from parent functions
................................................ 20-42
Change in precedence of compound name resolution . . . . . . . . . . 20-42
Anonymous functions can include resolved and unresolved identifiers
................................................ 20-43

Indexing into Function Call Results . . . . . . . . . . . . . . . . . . . . . . . . 20-44

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-44
Supported Syntaxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-44

Function Arguments
21
Find Number of Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . 21-2

Support Variable Number of Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4

Support Variable Number of Outputs . . . . . . . . . . . . . . . . . . . . . . . . 21-5

xviii Contents
 Validate Number of Function Arguments . . . . . . . . . . . . . . . . . . . . . 21-6

Argument Checking in Nested Functions . . . . . . . . . . . . . . . . . . . . . 21-8

Ignore Function Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10

Check Function Inputs with validateattributes . . . . . . . . . . . . . . . 21-11

Parse Function Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-13

Input Parser Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16

Debugging MATLAB Code

22
Debug a MATLAB Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Set Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Run File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Pause a Running File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Find and Fix a Problem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Step Through File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
End Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-6

Set Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7

Standard Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7
Conditional Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-8
Error Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9
Breakpoints in Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . 22-10
Invalid Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-10
Disable Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-10
Clear Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-11

Examine Values While Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . 22-12

Select Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-12
View Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-12

Presenting MATLAB Code

23
Publish and Share MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Create and Share Live Scripts in the Live Editor . . . . . . . . . . . . . . . 23-2
Publish MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Add Help and Create Documentation . . . . . . . . . . . . . . . . . . . . . . . 23-4

Publishing Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5

Markup Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Sections and Section Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7
Text Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Bulleted and Numbered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9

xix
 Text and Code Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9
External File Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
External Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
Image Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13
LaTeX Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13
Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15
HTML Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-17
LaTeX Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-18

Output Preferences for Publishing . . . . . . . . . . . . . . . . . . . . . . . . . 23-20

How to Edit Publishing Options . . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Specify Output File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-21
Run Code During Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-21
Manipulate Graphics in Publishing Output . . . . . . . . . . . . . . . . . . 23-23
Save a Publish Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-26
Manage a Publish Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 23-27

Coding and Productivity Tips

24
Open and Save Files in the Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Open Existing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Save Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-3

Check Code for Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . 24-5

Automatically Check Code in the Editor and Live Editor — Code
Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5
Create a Code Analyzer Message Report . . . . . . . . . . . . . . . . . . . . . 24-8
Adjust Code Analyzer Message Indicators and Messages . . . . . . . . 24-8
Understand Code Containing Suppressed Messages . . . . . . . . . . . 24-11
Understand the Limitations of Code Analysis . . . . . . . . . . . . . . . . 24-12
Enable MATLAB Compiler Deployment Messages . . . . . . . . . . . . . 24-14

Improve Code Readability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-16

Indenting Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-16
Right-Side Text Limit Indicator . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-17
Code Folding — Expand and Collapse Code Constructs . . . . . . . . . 24-18
Code Refactoring — Automatically convert selected code to a function
................................................ 24-20

Find and Replace Text in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-22

Find Any Text in the Current File . . . . . . . . . . . . . . . . . . . . . . . . . 24-22
Find and Replace Functions or Variables in the Current File . . . . . 24-22
Automatically Rename All Functions or Variables in a File . . . . . . 24-23
Find and Replace Any Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-24
Find Text in Multiple File Names or Files . . . . . . . . . . . . . . . . . . . 24-24
Function Alternative for Finding Text . . . . . . . . . . . . . . . . . . . . . . 24-25
Perform an Incremental Search in the Editor . . . . . . . . . . . . . . . . 24-25
Go To Location in File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-25

Add Reminders to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-29

Working with TODO/FIXME Reports . . . . . . . . . . . . . . . . . . . . . . . 24-29

xx Contents
 MATLAB Code Analyzer Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-31
Running the Code Analyzer Report . . . . . . . . . . . . . . . . . . . . . . . . 24-31
Changing Code Based on Code Analyzer Messages . . . . . . . . . . . . 24-32
Other Ways to Access Code Analyzer Messages . . . . . . . . . . . . . . 24-32

MATLAB Code Compatibility Report . . . . . . . . . . . . . . . . . . . . . . . . 24-34

Generate the Code Compatibility Report . . . . . . . . . . . . . . . . . . . . 24-34
Programmatic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-36

Programming Utilities
25
Identify Program Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Simple Display of Program File Dependencies . . . . . . . . . . . . . . . . 25-2
Detailed Display of Program File Dependencies . . . . . . . . . . . . . . . 25-2
Dependencies Within a Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2

Protect Your Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-6

Building a Content Obscured Format with P-Code . . . . . . . . . . . . . . 25-6
Building a Standalone Executable . . . . . . . . . . . . . . . . . . . . . . . . . . 25-7

Create Hyperlinks that Run Functions . . . . . . . . . . . . . . . . . . . . . . . 25-8

Run a Single Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-8
Run Multiple Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-9
Provide Command Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-9
Include Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-9

Create and Share Toolboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-11

Create Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-11
Share Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-15

Function Argument Validation

26
Function Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Introduction to Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . 26-2
Where to Use Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . 26-2
arguments Block Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-3
Examples of Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . 26-5
Kinds of Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7
Required and Optional Positional Arguments . . . . . . . . . . . . . . . . . 26-7
Repeating Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-8
Name-Value Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11
Name-Value Arguments from Class Properties . . . . . . . . . . . . . . . 26-13
Argument Validation in Class Methods . . . . . . . . . . . . . . . . . . . . . 26-15
Order of Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-15
Avoiding Class and Size Conversions . . . . . . . . . . . . . . . . . . . . . . 26-16
nargin in Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-18
Restrictions on Variable and Function Access . . . . . . . . . . . . . . . . 26-19

xxi
 Argument Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-21
Define Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-22

Parsing Function Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-24

Function Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-24
validateattributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-24
inputParser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-24

Transparency in MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-25

Writing Transparent Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-25

Software Development

Error Handling
27
Exception Handling in a MATLAB Application . . . . . . . . . . . . . . . . . 27-2
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Getting an Exception at the Command Line . . . . . . . . . . . . . . . . . . 27-2
Getting an Exception in Your Program Code . . . . . . . . . . . . . . . . . . 27-3
Generating a New Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-3

Throw an Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-4

Suggestions on How to Throw an Exception . . . . . . . . . . . . . . . . . . 27-4

Respond to an Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
The try/catch Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Suggestions on How to Handle an Exception . . . . . . . . . . . . . . . . . 27-7

Clean Up When Functions Complete . . . . . . . . . . . . . . . . . . . . . . . . . 27-9

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-9
Examples of Cleaning Up a Program Upon Exit . . . . . . . . . . . . . . . 27-10
Retrieving Information About the Cleanup Routine . . . . . . . . . . . . 27-11
Using onCleanup Versus try/catch . . . . . . . . . . . . . . . . . . . . . . . . 27-12
onCleanup in Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-12

Issue Warnings and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-13

Issue Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-13
Throw Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-13
Add Run-Time Parameters to Your Warnings and Errors . . . . . . . . 27-14
Add Identifiers to Warnings and Errors . . . . . . . . . . . . . . . . . . . . . 27-14

Suppress Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-16

Turn Warnings On and Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-16

Restore Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-18

Disable and Restore a Particular Warning . . . . . . . . . . . . . . . . . . . 27-18
Disable and Restore Multiple Warnings . . . . . . . . . . . . . . . . . . . . . 27-19

xxii Contents
 Change How Warnings Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-20
Enable Verbose Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-20
Display a Stack Trace on a Specific Warning . . . . . . . . . . . . . . . . . 27-20

Use try/catch to Handle Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-21

Program Scheduling
28
Schedule Command Execution Using Timer . . . . . . . . . . . . . . . . . . . 28-2
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-2
Example: Displaying a Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-2

Timer Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-4

Associating Commands with Timer Object Events . . . . . . . . . . . . . . 28-4
Creating Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-5
Specifying the Value of Callback Function Properties . . . . . . . . . . . 28-6

Handling Timer Queuing Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 28-8

Drop Mode (Default) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-8
Error Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-9
Queue Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-10

Performance
29
Measure the Performance of Your Code . . . . . . . . . . . . . . . . . . . . . . 29-2
Overview of Performance Timing Functions . . . . . . . . . . . . . . . . . . 29-2
Time Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
Time Portions of Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
The cputime Function vs. tic/toc and timeit . . . . . . . . . . . . . . . . . . . 29-2
Tips for Measuring Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-3

Profile Your Code to Improve Performance . . . . . . . . . . . . . . . . . . . . 29-4

What Is Profiling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4
Profile Your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4
Profile Multiple Statements in Command Window . . . . . . . . . . . . . 29-10
Profile an App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-11

Determine Code Coverage Using the Profiler . . . . . . . . . . . . . . . . . 29-12

Techniques to Improve Performance . . . . . . . . . . . . . . . . . . . . . . . . 29-14

Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-14
Code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-14
Programming Practices for Performance . . . . . . . . . . . . . . . . . . . . 29-14
Tips on Specific MATLAB Functions . . . . . . . . . . . . . . . . . . . . . . . 29-15

Preallocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-16
Preallocating a Nondouble Matrix . . . . . . . . . . . . . . . . . . . . . . . . 29-16

xxiii
 Vectorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-18
Using Vectorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-18
Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-19
Logical Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-20
Matrix Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-21
Ordering, Setting, and Counting Operations . . . . . . . . . . . . . . . . . 29-22
Functions Commonly Used in Vectorization . . . . . . . . . . . . . . . . . 29-23

Memory Usage
30
Strategies for Efficient Use of Memory . . . . . . . . . . . . . . . . . . . . . . . 30-2
Use Appropriate Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-2
Avoid Temporary Copies of Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-3
Reclaim Used Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-4

Resolve “Out of Memory” Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-6

Leverage tall Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-6
Leverage the Memory of Multiple Machines . . . . . . . . . . . . . . . . . . 30-7
Load Only as Much Data as You Need . . . . . . . . . . . . . . . . . . . . . . . 30-7
Increase System Swap Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-8
Set the Process Limit on Linux Systems . . . . . . . . . . . . . . . . . . . . . 30-8
Disable Java VM on Linux Systems . . . . . . . . . . . . . . . . . . . . . . . . . 30-9

How MATLAB Allocates Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-10

Memory Allocation for Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-10
Data Structures and Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-13

Avoid Unnecessary Copies of Data . . . . . . . . . . . . . . . . . . . . . . . . . . 30-17

Passing Values to Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-17
Why Pass-by-Value Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-19
Handle Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-19

Custom Help and Documentation

31
Create Help for Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2
Help Text from the doc Command . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2
Custom Help Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-3

Check Which Programs Have Help . . . . . . . . . . . . . . . . . . . . . . . . . . 31-8

Create Help Summary Files — Contents.m . . . . . . . . . . . . . . . . . . . 31-10

What Is a Contents.m File? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-10
Create a Contents.m File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-10
Check an Existing Contents.m File . . . . . . . . . . . . . . . . . . . . . . . . 31-11

Customize Code Suggestions and Completions . . . . . . . . . . . . . . . 31-12

Function Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-13

xxiv Contents
 Signature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-13
Argument Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-14
Create Function Signature File . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-17
How Function Signature Information is Used . . . . . . . . . . . . . . . . 31-18
Multiple Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-19

Display Custom Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-21
Create HTML Help Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-22
Create info.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-23
Create helptoc.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-24
Build a Search Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-26
Address Validation Errors for info.xml Files . . . . . . . . . . . . . . . . . 31-27

Display Custom Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-29

How to Display Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-29
Elements of the demos.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . 31-30

Projects
32
Create Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
What Are Projects? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Create Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Open Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Set up Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-3
Add Files to Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-5
Other Ways to Create Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-6

Automate Startup and Shutdown Tasks . . . . . . . . . . . . . . . . . . . . . . . 32-8

Specify Project Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-8
Set Startup Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-8
Specify Startup and Shutdown Files . . . . . . . . . . . . . . . . . . . . . . . . 32-8

Manage Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-10

Automatic Updates When Renaming, Deleting, or Removing Files
................................................ 32-11

Find Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-12

Group and Sort Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-12
Search for and Filter Project Files . . . . . . . . . . . . . . . . . . . . . . . . 32-12
Search the Content in Project Files . . . . . . . . . . . . . . . . . . . . . . . . 32-12

Create Shortcuts to Frequent Tasks . . . . . . . . . . . . . . . . . . . . . . . . 32-14

Run Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-14
Create Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-14
Organize Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-14

Add Labels to Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-16

Add Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-16
View and Edit Label Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-16
Create Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-17

xxv
 Create Custom Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-18
Create a Custom Task Function . . . . . . . . . . . . . . . . . . . . . . . . . . 32-18
Run a Custom Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-18
Save Custom Task Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-19

Componentize Large Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-20

Add or Remove Reference to a Project . . . . . . . . . . . . . . . . . . . . . 32-20
View, Edit, or Run Referenced Project Files . . . . . . . . . . . . . . . . . 32-20
Extract Folder to Create a Referenced Project . . . . . . . . . . . . . . . 32-21
Manage Changes in Referenced Project Using Checkpoints . . . . . 32-21

Share Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-23

Create an Export Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-26

Upgrade Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-27

Run Upgrade Project Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-27
Examine Upgrade Project Report . . . . . . . . . . . . . . . . . . . . . . . . . 32-28

Analyze Project Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-30

Run a Dependency Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-30
Explore the Dependency Graph, Views, and Filters . . . . . . . . . . . . 32-32
Investigate and Resolve Problems . . . . . . . . . . . . . . . . . . . . . . . . . 32-37
Find Required Products and Toolboxes . . . . . . . . . . . . . . . . . . . . . 32-39
Find File Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-40
Save and Compare Dependency Graphs . . . . . . . . . . . . . . . . . . . . 32-42

Use Source Control with Projects . . . . . . . . . . . . . . . . . . . . . . . . . . 32-44

Setup Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-44
Perform Source Control Operations . . . . . . . . . . . . . . . . . . . . . . . 32-46
Work with Derived Files in Projects . . . . . . . . . . . . . . . . . . . . . . . 32-53
Find Project Files With Unsaved Changes . . . . . . . . . . . . . . . . . . . 32-54
Manage Open Files When Closing a Project . . . . . . . . . . . . . . . . . 32-54

Create and Edit Projects Programmatically . . . . . . . . . . . . . . . . . . 32-55

Explore an Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-62

Source Control Interface

33
About MathWorks Source Control Integration . . . . . . . . . . . . . . . . . 33-2
Classic and Distributed Source Control . . . . . . . . . . . . . . . . . . . . . . 33-2

Select or Disable Source Control System . . . . . . . . . . . . . . . . . . . . . 33-4

Select Source Control System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-4
Disable Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-4

Create New Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-5

Create Git Repository on Your Local System . . . . . . . . . . . . . . . . . . 33-5
Create SVN Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-5

Review Changes in Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . 33-7

xxvi Contents
Mark Files for Addition to Source Control . . . . . . . . . . . . . . . . . . . . 33-8

Resolve Source Control Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-9

Examining and Resolving Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . 33-9
Resolve Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-9
Merge Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-10
Extract Conflict Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-10

Commit Modified Files to Source Control . . . . . . . . . . . . . . . . . . . . 33-12

Revert Changes in Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . 33-13

Revert Local Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-13
Revert a File to a Specified Revision . . . . . . . . . . . . . . . . . . . . . . . 33-13

Set Up SVN Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-14

SVN Source Control Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-14
Register Binary Files with SVN . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-14
Standard Repository Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-17
Tag Versions of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-17
Enforce Locking Files Before Editing . . . . . . . . . . . . . . . . . . . . . . 33-17
Share a Subversion Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-18

Check Out from SVN Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-19

Retrieve Tagged Version of Repository . . . . . . . . . . . . . . . . . . . . . 33-20

Update SVN File Status and Revision . . . . . . . . . . . . . . . . . . . . . . . 33-21

Refresh Status of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-21
Update Revisions of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-21

Get SVN File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-22

Manage SVN Repository Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-22

Set Up Git Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-23

Install Command-Line Git Client and Configure MATLAB Installation
................................................ 33-23
Use SSH Authentication with MATLAB . . . . . . . . . . . . . . . . . . . . . 33-24
Register Binary Files with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-25
Add Git Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-26

Clone from Git Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-28

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-28

Update Git File Status and Revision . . . . . . . . . . . . . . . . . . . . . . . . 33-29

Refresh Status of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-29
Update Revisions of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-29

Branch and Merge with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-30

Create Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-30
Switch Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-31
Compare Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-32
Merge Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-32
Revert to Head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-33
Delete Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-33

xxvii
 Pull, Push and Fetch Files with Git . . . . . . . . . . . . . . . . . . . . . . . . . 33-34
Pull and Push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-34
Fetch and Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-35
Use Git Stashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-35

Move, Rename, or Delete Files Under Source Control . . . . . . . . . . 33-37

Customize External Source Control to Use MATLAB for Diff and

Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-38
Finding the Full Paths for MATLAB Diff and Merge . . . . . . . . . . . . 33-38
Integration with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-39
Integration with SVN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-40
Integration with Other Source Control Tools . . . . . . . . . . . . . . . . . 33-40

MSSCCI Source Control Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 33-42

Set Up MSSCCI Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-43

Create Projects in Source Control System . . . . . . . . . . . . . . . . . . . 33-43
Specify Source Control System with MATLAB Software . . . . . . . . 33-44
Register Source Control Project with MATLAB Software . . . . . . . . 33-45
Add Files to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-47

Check Files In and Out from MSSCCI Source Control . . . . . . . . . . 33-48

Check Files Into Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . 33-48
Check Files Out of Source Control . . . . . . . . . . . . . . . . . . . . . . . . 33-48
Undoing the Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-49

Additional MSSCCI Source Control Actions . . . . . . . . . . . . . . . . . . 33-50

Getting the Latest Version of Files for Viewing or Compiling . . . . . 33-50
Removing Files from the Source Control System . . . . . . . . . . . . . . 33-51
Showing File History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-51
Comparing the Working Copy of a File to the Latest Version in Source
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-52
Viewing Source Control Properties of a File . . . . . . . . . . . . . . . . . 33-53
Starting the Source Control System . . . . . . . . . . . . . . . . . . . . . . . 33-54

Access MSSCCI Source Control from Editors . . . . . . . . . . . . . . . . . 33-56

Troubleshoot MSSCCI Source Control Problems . . . . . . . . . . . . . . 33-57

Source Control Error: Provider Not Present or Not Installed Properly
................................................ 33-57
Restriction Against @ Character . . . . . . . . . . . . . . . . . . . . . . . . . . 33-58
Add to Source Control Is the Only Action Available . . . . . . . . . . . . 33-58
More Solutions for Source Control Problems . . . . . . . . . . . . . . . . 33-58

Unit Testing
34
Write Test Using Live Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-3

Write Script-Based Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6

xxviii Contents
Write Script-Based Test Using Local Functions . . . . . . . . . . . . . . . 34-11

Extending Script-Based Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-14

Test Suite Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-14
Test Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-14
Programmatic Access of Test Diagnostics . . . . . . . . . . . . . . . . . . . 34-15
Test Runner Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-15

Run Tests in Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17

Write Function-Based Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-20

Create Test Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-20
Run the Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-22
Analyze the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-22

Write Simple Test Case Using Functions . . . . . . . . . . . . . . . . . . . . . 34-24

Write Test Using Setup and Teardown Functions . . . . . . . . . . . . . . 34-28

Extending Function-Based Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-33

Fixtures for Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . 34-33
Test Logging and Verbosity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-34
Test Suite Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-34
Test Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-34
Test Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-35
Programmatic Access of Test Diagnostics . . . . . . . . . . . . . . . . . . . 34-35
Test Runner Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-36

Author Class-Based Unit Tests in MATLAB . . . . . . . . . . . . . . . . . . . 34-37

The Test Class Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-37
The Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-37
Additional Features for Advanced Test Classes . . . . . . . . . . . . . . . 34-38

Write Simple Test Case Using Classes . . . . . . . . . . . . . . . . . . . . . . . 34-40

Write Setup and Teardown Code Using Classes . . . . . . . . . . . . . . . 34-44

Test Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-44
Test Case with Method-Level Setup Code . . . . . . . . . . . . . . . . . . . 34-44
Test Case with Class-Level Setup Code . . . . . . . . . . . . . . . . . . . . . 34-45

Table of Verifications, Assertions, and Other Qualifications . . . . . 34-47

Tag Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-49

Tag Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-49
Select and Run Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-50

Write Tests Using Shared Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . 34-53

Create Basic Custom Fixture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-56

Create Advanced Custom Fixture . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-58

Create Basic Parameterized Test . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-63

Create Advanced Parameterized Test . . . . . . . . . . . . . . . . . . . . . . . . 34-68

xxix
 Use External Parameters in Parameterized Test . . . . . . . . . . . . . . . 34-75

Create Simple Test Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-79

Run Tests for Various Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-81

Set Up Example Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-81
Run All Tests in Class or Function . . . . . . . . . . . . . . . . . . . . . . . . . 34-81
Run Single Test in Class or Function . . . . . . . . . . . . . . . . . . . . . . . 34-81
Run Test Suites by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-82
Run Test Suites from Test Array . . . . . . . . . . . . . . . . . . . . . . . . . . 34-82
Run Tests with Customized Test Runner . . . . . . . . . . . . . . . . . . . . 34-83

Programmatically Access Test Diagnostics . . . . . . . . . . . . . . . . . . . 34-84

Add Plugin to Test Runner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-85

Write Plugins to Extend TestRunner . . . . . . . . . . . . . . . . . . . . . . . . 34-87

Custom Plugins Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-87
Extending Test Session Level Plugin Methods . . . . . . . . . . . . . . . . 34-87
Extending Test Suite Level Plugin Methods . . . . . . . . . . . . . . . . . . 34-88
Extending Test Class Level Plugin Methods . . . . . . . . . . . . . . . . . 34-88
Extending Test Level Plugin Methods . . . . . . . . . . . . . . . . . . . . . . 34-89

Create Custom Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-90

Run Tests in Parallel with Custom Plugin . . . . . . . . . . . . . . . . . . . . 34-95

Write Plugin to Add Data to Test Results . . . . . . . . . . . . . . . . . . . 34-103

Write Plugin to Save Diagnostic Details . . . . . . . . . . . . . . . . . . . . 34-108

Plugin to Generate Custom Test Output Format . . . . . . . . . . . . . . 34-112

Analyze Test Case Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-115

Analyze Failed Test Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-118

Rerun Failed Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-120

Dynamically Filtered Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-123

Test Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-123
Method Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . . . 34-125
Class Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . . . . . 34-127

Create Custom Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-129

Create Custom Boolean Constraint . . . . . . . . . . . . . . . . . . . . . . . . 34-132

Create Custom Tolerance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-136

Overview of App Testing Framework . . . . . . . . . . . . . . . . . . . . . . . 34-140

App Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-140
Gesture Support of UI Components . . . . . . . . . . . . . . . . . . . . . . 34-140
Write a Test for an App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-141

xxx Contents
 Write Test for App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-144

Write Test That Uses App Testing and Mocking Frameworks . . . 34-148
Create App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-148
Test App With Manual Intervention . . . . . . . . . . . . . . . . . . . . . . . 34-149
Create Fully Automated Test . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-150

Overview of Performance Testing Framework . . . . . . . . . . . . . . . . 34-153

Determine Bounds of Measured Code . . . . . . . . . . . . . . . . . . . . . 34-153
Types of Time Experiments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-154
Write Performance Tests with Measurement Boundaries . . . . . . . 34-154
Run Performance Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-155
Understand Invalid Test Results . . . . . . . . . . . . . . . . . . . . . . . . . 34-155

Test Performance Using Scripts or Functions . . . . . . . . . . . . . . . . 34-157

Test Performance Using Classes . . . . . . . . . . . . . . . . . . . . . . . . . . 34-161

Measure Fast Executing Test Code . . . . . . . . . . . . . . . . . . . . . . . . 34-167

Create Mock Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-170

Specify Mock Object Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-177

Define Mock Method Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . 34-177
Define Mock Property Behavior . . . . . . . . . . . . . . . . . . . . . . . . . 34-178
Define Repeating and Subsequent Behavior . . . . . . . . . . . . . . . . 34-179
Summary of Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-181

Qualify Mock Object Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . 34-182

Qualify Mock Method Interaction . . . . . . . . . . . . . . . . . . . . . . . . 34-182
Qualify Mock Property Interaction . . . . . . . . . . . . . . . . . . . . . . . 34-183
Use Mock Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-184
Summary of Qualifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-186

Develop and Integrate Software with Continuous Integration . . 34-188

Continuous Integration Workflow . . . . . . . . . . . . . . . . . . . . . . . . 34-188
Continuous Integration with MathWorks Products . . . . . . . . . . . 34-190

System object Usage and Authoring

35
What Are System Objects? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-2
Running a System Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-3
System Object Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-3

System Objects vs MATLAB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-5

System Objects vs. MATLAB Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 35-5
Process Audio Data Using Only MATLAB Functions Code . . . . . . . . . . . . 35-5
Process Audio Data Using System Objects . . . . . . . . . . . . . . . . . . . . . . . 35-6

System Design in MATLAB Using System Objects . . . . . . . . . . . . . . . . . . 35-7

System Design and Simulation in MATLAB . . . . . . . . . . . . . . . . . . . . . . . 35-7

xxxi
 Create Individual Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-7
Configure Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-8
Create and Configure Components at the Same Time . . . . . . . . . . . . . . . 35-8
Assemble Components Into System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-9
Run Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-9
Reconfiguring Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-10

Define Basic System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-11

Create System Object Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-11
Define Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-11

Change the Number of Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-13

Validate Property and Input Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-16

Validate a Single Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-16
Validate Interdependent Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-16
Validate Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-16
Complete Class Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-16

Initialize Properties and Setup One-Time Calculations . . . . . . . . . . . . . 35-18

Set Property Values at Construction Time . . . . . . . . . . . . . . . . . . . . . . . 35-20

Reset Algorithm and Release Resources . . . . . . . . . . . . . . . . . . . . . . . . . 35-22

Reset Algorithm State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-22
Release System Object Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-22

Define Property Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-24

Specify Property as Nontunable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-24
Specify Property as DiscreteState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-24
Example Class with Various Property Attributes . . . . . . . . . . . . . . . . . . 35-24

Hide Inactive Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-26

Specify Inactive Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-26
Complete Class Definition File with Inactive Properties Method . . . . . . 35-26

Limit Property Values to Finite List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-28

Property Validation with mustBeMember . . . . . . . . . . . . . . . . . . . . . . . 35-28
Enumeration Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-28
Create a Whiteboard System object . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-29

Process Tuned Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-32

Define Composite System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-34

Define Finite Source Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-36

Use the FiniteSource Class and Specify End of the Source . . . . . . . . . . 35-36
Complete Class Definition File with Finite Source . . . . . . . . . . . . . . . . . 35-36

Save and Load System Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-38

Save System Object and Child Object . . . . . . . . . . . . . . . . . . . . . . . . . . 35-38
Load System Object and Child Object . . . . . . . . . . . . . . . . . . . . . . . . . . 35-38
Complete Class Definition Files with Save and Load . . . . . . . . . . . . . . . 35-38

Define System Object Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-41

xxxii Contents
Handle Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-43
React to Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 35-43
Restrict Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 35-43

Summary of Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-45

Setup Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-45
Running the Object or Step Call Sequence . . . . . . . . . . . . . . . . . . . . . . 35-45
Reset Method Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-46
Release Method Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-47

Detailed Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-48

setup Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-48
Running the Object or step Call Sequence . . . . . . . . . . . . . . . . . . . . . . 35-48
reset Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-49
release Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-49

Tips for Defining System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-50

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-50
Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-50
Using ~ as an Input Argument in Method Definitions . . . . . . . . . . . . . . 35-50
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-50
Text Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-51
Simulink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-51
Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-52

Insert System Object Code Using MATLAB Editor . . . . . . . . . . . . . . . . . 35-53

Define System Objects with Code Insertion . . . . . . . . . . . . . . . . . . . . . . 35-53
Create a Temperature Enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-55
Create Custom Property for Freezing Point . . . . . . . . . . . . . . . . . . . . . . 35-56
Add Method to Validate Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-57

Analyze System Object Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-58

View and Navigate System object Code . . . . . . . . . . . . . . . . . . . . . . . . 35-58
Example: Go to StepImpl Method Using Analyzer . . . . . . . . . . . . . . . . . 35-58

Use Global Variables in System Objects . . . . . . . . . . . . . . . . . . . . . . . . . 35-60

System Object Global Variables in MATLAB . . . . . . . . . . . . . . . . . . . . . 35-60
System Object Global Variables in Simulink . . . . . . . . . . . . . . . . . . . . . 35-60

Create Moving Average System object . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-64

Create New System Objects for File Input and Output . . . . . . . . . . . . . 35-69

xxxiii
Language

35
 1

Syntax Basics

• “Continue Long Statements on Multiple Lines” on page 1-2

• “Ignore Function Outputs” on page 1-3
• “Variable Names” on page 1-4
• “Case and Space Sensitivity” on page 1-5
• “Command vs. Function Syntax” on page 1-6
• “Common Errors When Calling Functions” on page 1-9
1 Syntax Basics

Continue Long Statements on Multiple Lines

This example shows how to continue a statement to the next line using ellipsis (...).

s = 1 - 1/2 + 1/3 - 1/4 + 1/5 ...

- 1/6 + 1/7 - 1/8 + 1/9;

Build a long character vector by concatenating shorter vectors together:

mytext = ['Accelerating the pace of ' ...

'engineering and science'];

The start and end quotation marks for a character vector must appear on the same line. For example,
this code returns an error, because each line contains only one quotation mark:

mytext = 'Accelerating the pace of ...

engineering and science'

An ellipsis outside a quoted text is equivalent to a space. For example,

x = [1.23...
4.56];

is the same as

x = [1.23 4.56];

1-2
 Ignore Function Outputs

Ignore Function Outputs

This example shows how to ignore specific outputs from a function using the tilde (~) operator.

Request all three possible outputs from the fileparts function.

helpFile = which('help');
[helpPath,name,ext] = fileparts(helpFile);

The current workspace now contains three variables from fileparts: helpPath, name, and ext. In
this case, the variables are small. However, some functions return results that use much more
memory. If you do not need those variables, they waste space on your system.

If you do not use the tilde operator, you can request only the first N outputs of a function (where N is
less than or equal to the number of possible outputs) and ignore any remaining outputs. For example,
request only the first output, ignoring the second and third.

helpPath = fileparts(helpFile);

If you request more than one output, enclose the variable names in square brackets, []. The
following code ignores the output argument ext.

[helpPath,name] = fileparts(helpFile);

To ignore function outputs in any position in the argument list, use the tilde operator. For example,
ignore the first output using a tilde.

[~,name,ext] = fileparts(helpFile);

You can ignore any number of function outputs using the tilde operator. Separate consecutive tildes
with a comma. For example, this code ignores the first two output arguments.

[~,~,ext] = fileparts(helpFile);

See Also

More About
• “Ignore Function Inputs” on page 21-10

1-3
1 Syntax Basics

Variable Names
In this section...
“Valid Names” on page 1-4
“Conflicts with Function Names” on page 1-4

Valid Names
A valid variable name starts with a letter, followed by letters, digits, or underscores. MATLAB is case
sensitive, so A and a are not the same variable. The maximum length of a variable name is the value
that the namelengthmax command returns.

You cannot define variables with the same names as MATLAB keywords, such as if or end. For a
complete list, run the iskeyword command.

Examples of valid names: Invalid names:

x6 6x
lastValue end
n_factorial n!

Conflicts with Function Names

Avoid creating variables with the same name as a function (such as i, j, mode, char, size, and
path). In general, variable names take precedence over function names. If you create a variable that
uses the name of a function, you sometimes get unexpected results.

Check whether a proposed name is already in use with the exist or which function. exist returns
0 if there are no existing variables, functions, or other artifacts with the proposed name. For example:

exist checkname

ans =
0

If you inadvertently create a variable with a name conflict, remove the variable from memory with the
clear function.

Another potential source of name conflicts occurs when you define a function that calls load or eval
(or similar functions) to add variables to the workspace. In some cases, load or eval add variables
that have the same names as functions. Unless these variables are in the function workspace before
the call to load or eval, the MATLAB parser interprets the variable names as function names. For
more information, see:

• “Unexpected Results When Loading Variables Within a Function”

• “Alternatives to the eval Function” on page 2-86

See Also
clear | exist | iskeyword | isvarname | namelengthmax | which

1-4
 Case and Space Sensitivity

Case and Space Sensitivity

MATLAB code is sensitive to casing, and insensitive to blank spaces except when defining arrays.

Uppercase and Lowercase

In MATLAB code, use an exact match with regard to case for variables, files, and functions. For
example, if you have a variable, a, you cannot refer to that variable as A. It is a best practice to use
lowercase only when naming functions. This is especially useful when you use both Microsoft®
Windows® and UNIX®1 platforms because their file systems behave differently with regard to case.

When you use the help function, the help displays some function names in all uppercase, for
example, PLOT, solely to distinguish the function name from the rest of the text. Some functions for
interfacing to Oracle® Java® software do use mixed case and the command-line help and the
documentation accurately reflect that.

Spaces

Blank spaces around operators such as -, :, and ( ), are optional, but they can improve readability.
For example, MATLAB interprets the following statements the same way.

y = sin (3 * pi) / 2
y=sin(3*pi)/2

However, blank spaces act as delimiters in horizontal concatenation. When defining row vectors, you
can use spaces and commas interchangeably to separate elements:

A = [1, 0 2, 3 3]

A =

1 0 2 3 3

Because of this flexibility, check to ensure that MATLAB stores the correct values. For example, the
statement [1 sin (pi) 3] produces a much different result than [1 sin(pi) 3] does.

[1 sin (pi) 3]

Error using sin

Not enough input arguments.

[1 sin(pi) 3]

ans =

1.0000 0.0000 3.0000

1. UNIX is a registered trademark of The Open Group in the United States and other countries.

1-5
1 Syntax Basics

Command vs. Function Syntax

Command and Function Syntaxes

In MATLAB, these statements are equivalent:

load durer.mat % Command syntax

load('durer.mat') % Function syntax

This equivalence is sometimes referred to as command-function duality.

All functions support this standard function syntax:

[output1, ..., outputM] = functionName(input1, ..., inputN)

If you do not require any outputs from the function, and all of the inputs are character vectors (that
is, text enclosed in single quotation marks), you can use this simpler command syntax:

functionName input1 ... inputN

With command syntax, you separate inputs with spaces rather than commas, and do not enclose input
arguments in parentheses. Command syntax always passes inputs as character vectors. To use strings
as inputs, use the function syntax. If a character vector contains a space, use the function syntax.

When a function input is a variable, you must use function syntax to pass the value to the function.
Command syntax always passes inputs as character vectors and cannot pass variable values. For
example, create a variable and call the disp function with function syntax to pass the value of the
variable:

A = 123;
disp(A)

This code returns the expected result,

123

You cannot use command syntax to pass the value of A, because this call

disp A

is equivalent to

disp('A')

and returns

Avoid Common Syntax Mistakes

Suppose that your workspace contains these variables:

filename = 'accounts.txt';
A = int8(1:8);
B = A;

1-6
 Command vs. Function Syntax

The following table illustrates common misapplications of command syntax.

This Command... Is Equivalent to... Correct Syntax for Passing Value

open filename open('filename') open(filename)
isequal A B isequal('A','B') isequal(A,B)
strcmp class(A) int8 strcmp('class(A)','int8') strcmp(class(A),'int8')
cd matlabroot cd('matlabroot') cd(matlabroot)
isnumeric 500 isnumeric('500') isnumeric(500)
round 3.499 round('3.499'), which is round(3.499)
equivalent to round([51 46 52
57 57])
disp hello world disp('hello','world') disp('hello world')
disp "string" disp('"string"') disp("string")

Passing Variable Names

Some functions expect character vectors for variable names, such as save, load, clear, and whos.
For example,

whos -file durer.mat X

requests information about variable X in the example file durer.mat. This command is equivalent to

whos('-file','durer.mat','X')

How MATLAB Recognizes Command Syntax

Consider the potentially ambiguous statement

ls ./d

This could be a call to the ls function with the folder ./d as its argument. It also could request
element-wise division on the array ls, using the variable d as the divisor.

If you issue such a statement at the command line, MATLAB can access the current workspace and
path to determine whether ls and d are functions or variables. However, some components, such as
the Code Analyzer and the Editor/Debugger, operate without reference to the path or workspace. In
those cases, MATLAB uses syntactic rules to determine whether an expression is a function call using
command syntax.

In general, when MATLAB recognizes an identifier (which might name a function or a variable), it
analyzes the characters that follow the identifier to determine the type of expression, as follows:

• An equal sign (=) implies assignment. For example:

ls =d
• An open parenthesis after an identifier implies a function call. For example:

ls('./d')
• Space after an identifier, but not after a potential operator, implies a function call using command
syntax. For example:

1-7
1 Syntax Basics

ls ./d
• Spaces on both sides of a potential operator, or no spaces on either side of the operator, imply an
operation on variables. For example, these statements are equivalent:

ls ./ d

ls./d

Therefore, the potentially ambiguous statement ls ./d is a call to the ls function using command
syntax.

The best practice is to avoid defining variable names that conflict with common functions, to prevent
any ambiguity.

1-8
 Common Errors When Calling Functions

Common Errors When Calling Functions

In this section...
“Conflicting Function and Variable Names” on page 1-9
“Undefined Functions or Variables” on page 1-9

Conflicting Function and Variable Names

MATLAB throws an error if a variable and function have been given the same name and there is
insufficient information available for MATLAB to resolve the conflict. You may see an error message
something like the following:
Error: <functionName> was previously used as a variable,
conflicting with its use here as the name of a function
or command.

where <functionName> is the name of the function.

Certain uses of the eval and load functions can also result in a similar conflict between variable and
function names. For more information, see:

• “Conflicts with Function Names” on page 1-4

• “Unexpected Results When Loading Variables Within a Function”
• “Alternatives to the eval Function” on page 2-86

Undefined Functions or Variables

You may encounter the following error message, or something similar, while working with functions
or variables in MATLAB:
Undefined function or variable 'x'.

These errors usually indicate that MATLAB cannot find a particular variable or MATLAB program file
in the current directory or on the search path. The root cause is likely to be one of the following:

• The name of the function has been misspelled.

• The function name and name of the file containing the function are not the same.
• The toolbox to which the function belongs is not installed.
• The search path to the function has been changed.
• The function is part of a toolbox that you do not have a license for.

Follow the steps described in this section to resolve this situation.

Verify the Spelling of the Function Name

One of the most common errors is misspelling the function name. Especially with longer function
names or names containing similar characters (e.g., letter l and numeral one), it is easy to make an
error that is not easily detected.

If you misspell a MATLAB function, a suggested function name appears in the Command Window. For
example, this command fails because it includes an uppercase letter in the function name:

1-9
1 Syntax Basics

accumArray

Undefined function or variable 'accumArray'.

Did you mean:

>> accumarray

Press Enter to execute the suggested command or Esc to dismiss it.

Make Sure the Function Name Matches the File Name

You establish the name for a function when you write its function definition line. This name should
always match the name of the file you save it to. For example, if you create a function named
curveplot,

function curveplot(xVal, yVal)

- program code -

then you should name the file containing that function curveplot.m. If you create a pcode file for
the function, then name that file curveplot.p. In the case of conflicting function and file names, the
file name overrides the name given to the function. In this example, if you save the curveplot
function to a file named curveplotfunction.m, then attempts to invoke the function using the
function name will fail:

curveplot
Undefined function or variable 'curveplot'.

If you encounter this problem, change either the function name or file name so that they are the
same. If you have difficulty locating the file that uses this function, use the MATLAB Find Files utility
as follows:

1
On the Home tab, in the File section, click Find Files.
2 Under Find files named: enter *.m
3 Under Find files containing text: enter the function name.
4 Click the Find button

1-10
 Common Errors When Calling Functions

Make Sure the Toolbox Is Installed

If you are unable to use a built-in function from MATLAB or its toolboxes, make sure that the function
is installed.

If you do not know which toolbox supports the function you need, search for the function
documentation at https://www.mathworks.com/help. The toolbox name appears at the top of the
function reference page.

Once you know which toolbox the function belongs to, use the ver function to see which toolboxes
are installed on the system from which you run MATLAB. The ver function displays a list of all
currently installed MathWorks® products. If you can locate the toolbox you need in the output
displayed by ver, then the toolbox is installed. For help with installing MathWorks products, see the
Installation Guide documentation.

If you do not see the toolbox and you believe that it is installed, then perhaps the MATLAB path has
been set incorrectly. Go on to the next section.

Verify the Path Used to Access the Function

This step resets the path to the default.

Because MATLAB stores the toolbox information in a cache file, you will need to first update this
cache and then reset the path. To do this,

1
On the Home tab, in the Environment section, click Preferences.

The Preference dialog box appears.

2 Under the MATLAB > General node, click the Update Toolbox Path Cache button.
3
On the Home tab, in the Environment section, click Set Path....

1-11
1 Syntax Basics

The Set Path dialog box opens.

4 Click Default.

A small dialog box opens warning that you will lose your current path settings if you proceed.
Click Yes if you decide to proceed.

(If you have added any custom paths to MATLAB, you will need to restore those later)

Run ver again to see if the toolbox is installed. If not, you may need to reinstall this toolbox to use
this function. For more information about installing a toolbox, see How do I install additional
toolboxes into an existing installation of MATLAB.

Once ver shows your toolbox, run the following command to see if you can find the function:

which -all <functionname>

replacing <functionname> with the name of the function. You should be presented with the path(s)
of the function file. If you get a message indicating that the function name was not found, you may
need to reinstall that toolbox to make the function active.

1-12
 2

Program Components

• “MATLAB Operators and Special Characters” on page 2-2

• “Array vs. Matrix Operations” on page 2-20
• “Compatible Array Sizes for Basic Operations” on page 2-25
• “Array Comparison with Relational Operators” on page 2-29
• “Operator Precedence” on page 2-32
• “Average Similar Data Points Using a Tolerance” on page 2-34
• “Group Scattered Data Using a Tolerance” on page 2-36
• “Bit-Wise Operations” on page 2-38
• “Perform Cyclic Redundancy Check” on page 2-44
• “Conditional Statements” on page 2-47
• “Loop Control Statements” on page 2-49
• “Regular Expressions” on page 2-51
• “Lookahead Assertions in Regular Expressions” on page 2-63
• “Tokens in Regular Expressions” on page 2-66
• “Dynamic Regular Expressions” on page 2-72
• “Comma-Separated Lists” on page 2-79
• “Alternatives to the eval Function” on page 2-86
2 Program Components

MATLAB Operators and Special Characters

This page contains a comprehensive listing of all MATLAB operators, symbols, and special characters.

Arithmetic Operators
Symbol Role More Information
+ Addition plus
+ Unary plus uplus
- Subtraction minus
- Unary minus uminus
.* Element-wise multiplication times
* Matrix multiplication mtimes
./ Element-wise right division rdivide
/ Matrix right division mrdivide
.\ Element-wise left division ldivide
\ Matrix left division mldivide

(also known as backslash)

.^ Element-wise power power
^ Matrix power mpower
.' Transpose transpose
' Complex conjugate transpose ctranspose

Relational Operators
Symbol Role More Information
== Equal to eq
~= Not equal to ne
> Greater than gt
>= Greater than or equal to ge
< Less than lt
<= Less than or equal to le

Logical Operators
Symbol Role More Information
& Logical AND and
| Logical OR or
&& Logical AND (with short- Logical Operators: Short-
circuiting) Circuit && ||

2-2
 MATLAB Operators and Special Characters

Symbol Role More Information

|| Logical OR (with short-circuiting)
~ Logical NOT not

Special Characters
@ Name: At symbol

Uses:

• Function handle construction and reference

• Calling superclass methods

Description: The @ symbol forms a handle to either the named function that follows the @
sign, or to the anonymous function that follows the @ sign. You can also use @ to call
superclass methods from subclasses.

Examples

Create a function handle to a named function:

fhandle = @myfun

Create a function handle to an anonymous function:

fhandle = @(x,y) x.^2 + y.^2;

Call the disp method of MySuper from a subclass:

disp@MySuper(obj)

Call the superclass constructor from a subclass using the object being constructed:

obj = obj@MySuper(arg1,arg2,...)

More Information:

• “Create Function Handle” on page 13-2

• “Call Superclass Methods on Subclass Objects”

2-3
2 Program Components

. Name: Period or dot

Uses:

• Decimal point
• Element-wise operations
• Structure field access
• Object property or method specifier

Description: The period character separates the integral and fractional parts of a
number, such as 3.1415. MATLAB operators that contain a period always work element-
wise. The period character also enables you to access the fields in a structure, as well as
the properties and methods of an object.

Examples

Decimal point:

102.5543

Element-wise operations:

A.*B
A.^2

Structure field access:

myStruct.f1

Object property specifier:

myObj.PropertyName

More Information

• “Array vs. Matrix Operations” on page 2-20

• “Structures”
• “Access Property Values”

2-4
 MATLAB Operators and Special Characters

... Name: Dot dot dot or ellipsis

Uses: Line continuation

Description: Three or more periods at the end of a line continues the current command
on the next line. If three or more periods occur before the end of a line, then MATLAB
ignores the rest of the line and continues to the next line. This effectively makes a
comment out of anything on the current line that follows the three periods.

Note MATLAB interprets the ellipsis as a space character. Therefore, multi-line

commands must be valid as a single line with the ellipsis replaced by a space character.

Examples

Continue a function call on the next line:

sprintf(['The current value '...

'of %s is %d'],vname,value)

Break a character vector up on multiple lines and concatenate the lines together:

S = ['If three or more periods occur before the '...

'end of a line, then the rest of that line is ' ...
'ignored and MATLAB continues to the next line']

To comment out one line in a multiline command, use ... at the beginning of the line to
ensure that the command remains complete. If you use % to comment out a line it
produces an error:

y = 1 +...
2 +...
% 3 +...
4;

However, this code runs properly since the third line does not produce a gap in the
command:

y = 1 +...
2 +...
... 3 +...
4;

More Information

• “Continue Long Statements on Multiple Lines” on page 1-2

2-5
2 Program Components

, Name: Comma

Uses: Separator

Description: Use commas to separate row elements in an array, array subscripts,

function input and output arguments, and commands entered on the same line.

Examples

Separate row elements to create an array:

A = [12,13; 14,15]

Separate subscripts:

A(1,2)

Separate input and output arguments in function calls:

[Y,I] = max(A,[],2)

Separate multiple commands on the same line (showing output):

figure, plot(sin(-pi:0.1:pi)), grid on

More Information

• horzcat

2-6
 MATLAB Operators and Special Characters

: Name: Colon

Uses:

• Vector creation
• Indexing
• For-loop iteration

Description: Use the colon operator to create regularly spaced vectors, index into
arrays, and define the bounds of a for loop.

Examples

Create a vector:

x = 1:10

Create a vector that increments by 3:

x = 1:3:19

Reshape a matrix into a column vector:

A(:)

Assign new elements without changing the shape of an array:

A = rand(3,4);
A(:) = 1:12;

Index a range of elements in a particular dimension:

A(2:5,3)

Index all elements in a particular dimension:

A(:,3)

for loop bounds:

x = 1;
for k = 1:25
x = x + x^2;
end

More Information

• colon
• “Creating, Concatenating, and Expanding Matrices”

2-7
2 Program Components

; Name: Semicolon

Uses:

• Signify end of row

• Suppress output of code line

Description: Use semicolons to separate rows in an array creation command, or to

suppress the output display of a line of code.

Examples

Separate rows to create an array:

A = [12,13; 14,15]

Suppress code output:

Y = max(A);

Separate multiple commands on a single line (suppressing output):

A = 12.5; B = 42.7, C = 1.25;

B =
42.7000

More Information

• vertcat

2-8
 MATLAB Operators and Special Characters

( ) Name: Parentheses

Uses:

• Operator precedence
• Function argument enclosure
• Indexing

Description: Use parentheses to specify precedence of operations, enclose function input

arguments, and index into an array.

Examples

Precedence of operations:

(A.*(B./C)) - D

Function argument enclosure:

plot(X,Y,'r*')
C = union(A,B)

Indexing:

A(3,:)
A(1,2)
A(1:5,1)

More Information

• “Operator Precedence” on page 2-32

• “Array Indexing”

2-9
2 Program Components

[ ] Name: Square brackets

Uses:

• Array construction
• Array concatenation
• Empty matrix and array element deletion
• Multiple output argument assignment

Description: Square brackets enable array construction and concatenation, creation of

empty matrices, deletion of array elements, and capturing values returned by a function.

Examples

Construct a three-element vector:

X = [10 12 -3]

Add a new bottom row to a matrix:

A = rand(3);
A = [A; 10 20 30]

Create an empty matrix:

A = []

Delete a matrix column:

A(:,1) = []

Capture three output arguments from a function:

[C,iA,iB] = union(A,B)

More Information

• “Creating, Concatenating, and Expanding Matrices”

• horzcat
• vertcat

2-10
 MATLAB Operators and Special Characters

{ } Name: Curly brackets

Uses: Cell array assignment and contents

Description: Use curly braces to construct a cell array, or to access the contents of a
particular cell in a cell array.

Examples

To construct a cell array, enclose all elements of the array in curly braces:

C = {[2.6 4.7 3.9], rand(8)*6, 'C. Coolidge'}

Index to a specific cell array element by enclosing all indices in curly braces:

A = C{4,7,2}

More Information

• “Cell Arrays”
% Name: Percent

Uses:

• Comment
• Conversion specifier

Description: The percent sign is most commonly used to indicate nonexecutable text
within the body of a program. This text is normally used to include comments in your
code.

Some functions also interpret the percent sign as a conversion specifier.

Two percent signs, %%, serve as a cell delimiter as described in “Code Sections” on page
18-5.

Examples

Add a comment to a block of code:

% The purpose of this loop is to compute

% the value of ...

Use conversion specifier with sprintf:

sprintf('%s = %d', name, value)

More Information

• “Add Comments to Programs” on page 18-3

2-11
2 Program Components

%{ %} Name: Percent curly bracket

Uses: Block comments

Description: The %{ and %} symbols enclose a block of comments that extend beyond
one line.

Note With the exception of whitespace characters, the %{ and %} operators must appear
alone on the lines that immediately precede and follow the block of help text. Do not
include any other text on these lines.

Examples

Enclose any multiline comments with percent followed by an opening or closing brace:

%{
The purpose of this routine is to compute
the value of ...
%}

More Information

• “Add Comments to Programs” on page 18-3

! Name: Exclamation point

Uses: Operating system command

Description: The exclamation point precedes operating system commands that you want
to execute from within MATLAB.

Not available in MATLAB Online™.

Examples

The exclamation point initiates a shell escape function. Such a function is to be performed
directly by the operating system:

!rmdir oldtests

More Information

• “Shell Escape Function Example”

2-12
 MATLAB Operators and Special Characters

? Name: Question mark

Uses: Metaclass for MATLAB class

Description: The question mark retrieves the meta.class object for a particular class
name. The ? operator works only with a class name, not an object.

Examples

Retrieve the meta.class object for class inputParser:

?inputParser

More Information

• metaclass
'' Name: Single quotes

Uses: Character array constructor

Description: Use single quotes to create character vectors that have class char.

Examples

Create a character vector:

chr = 'Hello, world'

More Information

• “Text in String and Character Arrays” on page 6-2

"" Name: Double quotes

Uses: String constructor

Description: Use double quotes to create string scalars that have class string.

Examples

Create a string scalar:

S = "Hello, world"

More Information

• “Text in String and Character Arrays” on page 6-2

2-13
2 Program Components

N/A Name: Space character

Uses: Separator

Description: Use the space character to separate row elements in an array constructor,
or the values returned by a function. In these contexts, the space character and comma
are equivalent.

Examples

Separate row elements to create an array:

% These statements are equivalent

A = [12 13; 14 15]
A = [12,13; 14,15]

Separate output arguments in function calls:

% These statements are equivalent

[Y I] = max(A)
[Y,I] = max(A)
N/A Name: Newline character

Uses: Separator

Description: Use the newline character to separate rows in an array construction

statement. In that context, the newline character and semicolon are equivalent.

Examples

Separate rows in an array creation command:

% These statements are equivalent

A = [12 13
14 15]
A = [12 13; 14 15]

2-14
 MATLAB Operators and Special Characters

~ Name: Tilde

Uses:

• Logical NOT
• Argument placeholder

Description: Use the tilde symbol to represent logical NOT or to suppress specific input
or output arguments.

Examples

Calculate the logical NOT of a matrix:

A = eye(3);
~A

Determine where the elements of A are not equal to those of B:

A = [1 -1; 0 1]
B = [1 -2; 3 2]
A~=B

Return only the third output value of union:

[~,~,iB] = union(A,B)

More Information

• not
• “Ignore Function Inputs” on page 21-10
• “Ignore Function Outputs” on page 1-3
= Name: Equal sign

Uses: Assignment

Description: Use the equal sign to assign values to a variable. The syntax B = A stores
the elements of A in variable B.

Note The = character is for assignment, whereas the == character is for comparing the
elements in two arrays. See eq for more information.

Examples

Create a matrix A. Assign the values in A to a new variable, B. Lastly, assign a new value
to the first element in B.

A = [1 0; -1 0];
B = A;
B(1) = 200;

2-15
2 Program Components

< & Name: Left angle bracket and ampersand

Uses: Specify superclasses

Description: Specify one or more superclasses in a class definition

Examples

Define a class that derives from one superclass:

classdef MyClass < MySuperclass

…
end

Define a class that derives from multiple superclasses:

classdef MyClass < Superclass1 & Superclass2 & …

…
end

More Information:

• “Subclass Syntax”
.? Name: Dot question mark

Uses: Specify fields of name-value structure

Description:

When using function argument validation, you can define the fields of the name-value
structure as the names of all writeable properties of the class.

Examples

Specify the field names of the propArgs structure as the writeable properties of the
matlab.graphics.primitive.Line class.

function f(propArgs)
arguments
propArgs.?matlab.graphics.primitive.Line
end
% Function code
...
end

More Information:

• “Name-Value Arguments from Class Properties” on page 26-13

String and Character Formatting

Some special characters can only be used in the text of a character vector or string. You can use
these special characters to insert new lines or carriage returns, specify folder paths, and more.

Use the special characters in this table to specify a folder path using a character vector or string.

2-16
 MATLAB Operators and Special Characters

/ Name: Slash and Backslash

\ Uses: File or folder path separation

Description: In addition to their use as mathematical operators, the slash and backslash
characters separate the elements of a path or folder. On Microsoft Windows based
systems, both slash and backslash have the same effect. On The Open Group UNIX based
systems, you must use slash only.

Examples

On a Windows system, you can use either backslash or slash:

dir([matlabroot '\toolbox\matlab\elmat\shiftdim.m'])
dir([matlabroot '/toolbox/matlab/elmat/shiftdim.m'])

On a UNIX system, use only the forward slash:

dir([matlabroot '/toolbox/matlab/elmat/shiftdim.m'])
.. Name: Dot dot

Uses: Parent folder

Description: Two dots in succession refers to the parent of the current folder. Use this
character to specify folder paths relative to the current folder.

Examples

To go up two levels in the folder tree and down into the test folder, use:

cd ..\..\test

More Information

• cd
* Name: Asterisk

Uses: Wildcard character

Description: In addition to being the symbol for matrix multiplication, the asterisk * is
used as a wildcard character.

Wildcards are generally used in file operations that act on multiple files or folders.
MATLAB matches all characters in the name exactly except for the wildcard character *,
which can match any one or more characters.

Examples

Locate all files with names that start with january_ and have a .mat file extension:

dir('january_*.mat')

2-17
2 Program Components

@ Name: At symbol

Uses: Class folder indicator

Description: An @ sign indicates the name of a class folder.

Examples

Refer to a class folder:

\@myClass\get.m

More Information

• “Class and Path Folders”

+ Name: Plus

Uses: Package directory indicator

Description: A + sign indicates the name of a package folder.

Examples

Package folders always begin with the + character:

+mypack
+mypack/pkfcn.m % a package function
+mypack/@myClass % class folder in a package

More Information

• “Packages Create Namespaces”

There are certain special characters that you cannot enter as ordinary text. Instead, you must use
unique character sequences to represent them. Use the symbols in this table to format strings and
character vectors on their own or in conjunction with formatting functions like compose, sprintf,
and error. For more information, see “Formatting Text” on page 6-24.

Symbol Effect on Text

'' Single quotation mark
%% Single percent sign
\\ Single backslash
\a Alarm
\b Backspace
\f Form feed
\n New line
\r Carriage return
\t Horizontal tab
\v Vertical tab
\xN Hexadecimal number, N

2-18
 MATLAB Operators and Special Characters

Symbol Effect on Text

\N Octal number, N

See Also

More About
• “Array vs. Matrix Operations” on page 2-20
• “Array Comparison with Relational Operators” on page 2-29
• “Compatible Array Sizes for Basic Operations” on page 2-25
• “Operator Precedence” on page 2-32
• “Find Array Elements That Meet a Condition” on page 5-2
• “Greek Letters and Special Characters in Chart Text”

2-19
2 Program Components

Array vs. Matrix Operations

In this section...
“Introduction” on page 2-20
“Array Operations” on page 2-20
“Matrix Operations” on page 2-22

Introduction
MATLAB has two different types of arithmetic operations: array operations and matrix operations.
You can use these arithmetic operations to perform numeric computations, for example, adding two
numbers, raising the elements of an array to a given power, or multiplying two matrices.

Matrix operations follow the rules of linear algebra. By contrast, array operations execute element by
element operations and support multidimensional arrays. The period character (.) distinguishes the
array operations from the matrix operations. However, since the matrix and array operations are the
same for addition and subtraction, the character pairs .+ and .- are unnecessary.

Array Operations
Array operations execute element by element operations on corresponding elements of vectors,
matrices, and multidimensional arrays. If the operands have the same size, then each element in the
first operand gets matched up with the element in the same location in the second operand. If the
operands have compatible sizes, then each input is implicitly expanded as needed to match the size of
the other. For more information, see “Compatible Array Sizes for Basic Operations” on page 2-25.

As a simple example, you can add two vectors with the same size.
A = [1 1 1]

A =

1 1 1

B = [1 2 3]

B =

1 2 3

A+B

ans =

2 3 4

If one operand is a scalar and the other is not, then MATLAB implicitly expands the scalar to be the
same size as the other operand. For example, you can compute the element-wise product of a scalar
and a matrix.
A = [1 2 3; 1 2 3]

A =

2-20
 Array vs. Matrix Operations

1 2 3
1 2 3

3.*A

ans =

3 6 9
3 6 9

Implicit expansion also works if you subtract a 1-by-3 vector from a 3-by-3 matrix because the two
sizes are compatible. When you perform the subtraction, the vector is implicitly expanded to become
a 3-by-3 matrix.

A = [1 1 1; 2 2 2; 3 3 3]

A =

1 1 1
2 2 2
3 3 3

m = [2 4 6]

m =

2 4 6

A - m

ans =

-1 -3 -5
0 -2 -4
1 -1 -3

A row vector and a column vector have compatible sizes. If you add a 1-by-3 vector to a 2-by-1 vector,
then each vector implicitly expands into a 2-by-3 matrix before MATLAB executes the element-wise
addition.

x = [1 2 3]

x =

1 2 3

y = [10; 15]

y =

10
15

x + y

ans =

11 12 13
16 17 18

2-21
2 Program Components

If the sizes of the two operands are incompatible, then you get an error.
A = [8 1 6; 3 5 7; 4 9 2]

A =

8 1 6
3 5 7
4 9 2

m = [2 4]

m =

2 4

A - m

Matrix dimensions must agree.

The following table provides a summary of arithmetic array operators in MATLAB. For function-
specific information, click the link to the function reference page in the last column.

Operator Purpose Description Reference

Page
+ Addition A+B adds A and B. plus
+ Unary plus +A returns A. uplus
- Subtraction A-B subtracts B from A minus
- Unary minus -A negates the elements of A. uminus
.* Element-wise A.*B is the element-by-element product of A and times
multiplication B.
.^ Element-wise A.^B is the matrix with elements A(i,j) to the power
power B(i,j) power.
./ Right array A./B is the matrix with elements A(i,j)/ rdivide
division B(i,j).
.\ Left array A.\B is the matrix with elements B(i,j)/ ldivide
division A(i,j).
.' Array transpose A.' is the array transpose of A. For complex transpose
matrices, this does not involve conjugation.

Matrix Operations
Matrix operations follow the rules of linear algebra and are not compatible with multidimensional
arrays. The required size and shape of the inputs in relation to one another depends on the operation.
For nonscalar inputs, the matrix operators generally calculate different answers than their array
operator counterparts.

For example, if you use the matrix right division operator, /, to divide two matrices, the matrices
must have the same number of columns. But if you use the matrix multiplication operator, *, to
multiply two matrices, then the matrices must have a common inner dimension. That is, the number
of columns in the first input must be equal to the number of rows in the second input. The matrix
multiplication operator calculates the product of two matrices with the formula,

2-22
 Array vs. Matrix Operations

n
C(i, j) = ∑ A(i, k)B(k, j) .
k=1

To see this, you can calculate the product of two matrices.

A = [1 3;2 4]

A =

1 3
2 4

B = [3 0;1 5]

B =

3 0
1 5

A*B

ans =

6 15
10 20

The previous matrix product is not equal to the following element-wise product.

A.*B

ans =

3 0
2 20

The following table provides a summary of matrix arithmetic operators in MATLAB. For function-
specific information, click the link to the function reference page in the last column.

Operator Purpose Description Reference

Page
* Matrix C = A*B is the linear algebraic product of the mtimes
multiplication matrices A and B. The number of columns of A
must equal the number of rows of B.
\ Matrix left x = A\B is the solution to the equation Ax = B. mldivide
division Matrices A and B must have the same number of
rows.
/ Matrix right x = B/A is the solution to the equation xA = B. mrdivide
division Matrices A and B must have the same number of
columns. In terms of the left division operator,
B/A = (A'\B')'.
^ Matrix power A^B is A to the power B, if B is a scalar. For other mpower
values of B, the calculation involves eigenvalues
and eigenvectors.

2-23
2 Program Components

Operator Purpose Description Reference

Page
' Complex A' is the linear algebraic transpose of A. For ctranspose
conjugate complex matrices, this is the complex conjugate
transpose transpose.

See Also

More About
• “Compatible Array Sizes for Basic Operations” on page 2-25
• “MATLAB Operators and Special Characters” on page 2-2
• “Operator Precedence” on page 2-32

2-24
 Compatible Array Sizes for Basic Operations

Compatible Array Sizes for Basic Operations

Most binary (two-input) operators and functions in MATLAB support numeric arrays that have
compatible sizes. Two inputs have compatible sizes if, for every dimension, the dimension sizes of the
inputs are either the same or one of them is 1. In the simplest cases, two array sizes are compatible if
they are exactly the same or if one is a scalar. MATLAB implicitly expands arrays with compatible
sizes to be the same size during the execution of the element-wise operation or function.

Inputs with Compatible Sizes

2-D Inputs

These are some combinations of scalars, vectors, and matrices that have compatible sizes:

• Two inputs which are exactly the same size.

• One input is a scalar.

• One input is a matrix, and the other is a column vector with the same number of rows.

• One input is a column vector, and the other is a row vector.

2-25
2 Program Components

Multidimensional Arrays

Every array in MATLAB has trailing dimensions of size 1. For multidimensional arrays, this means
that a 3-by-4 matrix is the same as a matrix of size 3-by-4-by-1-by-1-by-1. Examples of
multidimensional arrays with compatible sizes are:

• One input is a matrix, and the other is a 3-D array with the same number of rows and columns.

• One input is a matrix, and the other is a 3-D array. The dimensions are all either the same or one
of them is 1.

Empty Arrays

The rules are the same for empty arrays or arrays that have a dimension size of zero. The size of the
dimension that is not equal to 1 determines the size of the output. This means that dimensions with a

2-26
 Compatible Array Sizes for Basic Operations

size of zero must be paired with a dimension of size 1 or 0 in the other array, and that the output has
a dimension size of 0.

A: 1-by-0
B: 3-by-1
Result: 3-by-0

Inputs with Incompatible Sizes

Incompatible inputs have sizes that cannot be implicitly expanded to be the same size. For example:

• One of the dimension sizes are not equal, and neither is 1.

A: 3-by-2
B: 4-by-2
• Two nonscalar row vectors with lengths that are not the same.

A: 1-by-3
B: 1-by-4

Examples
Subtract Vector from Matrix

To simplify vector-matrix operations, use implicit expansion with dimensional functions such as sum,
mean, min, and others.

For example, calculate the mean value of each column in a matrix, then subtract the mean value from
each element.

A = magic(3)

A =

8 1 6
3 5 7
4 9 2

C = mean(A)

C =

5 5 5

A - C

ans =

3 -4 1
-2 0 2
-1 4 -3

Add Row and Column Vector

Row and column vectors have compatible sizes, and when you perform an operation on them the
result is a matrix.

2-27
2 Program Components

For example, add a row and column vector. The result is the same as bsxfun(@plus,a,b).

a = [1 2 3 4]

ans =

1 2 3 4

b = [5; 6; 7]

ans =

5
6
7

a + b

ans =

6 7 8 9
7 8 9 10
8 9 10 11

See Also
bsxfun

More About
• “Array vs. Matrix Operations” on page 2-20
• “MATLAB Operators and Special Characters” on page 2-2

2-28
 Array Comparison with Relational Operators

Array Comparison with Relational Operators

In this section...
“Array Comparison” on page 2-29
“Logic Statements” on page 2-31

Relational operators compare operands quantitatively, using operators like “less than”, “greater
than”, and “not equal to.” The result of a relational comparison is a logical array indicating the
locations where the relation is true.

These are the relational operators in MATLAB.

Symbol Function Equivalent Description

< lt Less than
<= le Less than or equal to
> gt Greater than
>= ge Greater than or equal to
== eq Equal to
~= ne Not equal to

Array Comparison
Numeric Arrays

The relational operators perform element-wise comparisons between two arrays. The arrays must
have compatible sizes to facilitate the operation. Arrays with compatible sizes are implicitly expanded
to be the same size during execution of the calculation. In the simplest cases, the two operands are
arrays of the same size, or one is a scalar. For more information, see “Compatible Array Sizes for
Basic Operations” on page 2-25.

For example, if you compare two matrices of the same size, then the result is a logical matrix of the
same size with elements indicating where the relation is true.

A = [2 4 6; 8 10 12]

A =

2 4 6
8 10 12

B = [5 5 5; 9 9 9]

B =

5 5 5
9 9 9

A < B

ans =

2-29
2 Program Components

1 1 0
1 0 0

Similarly, you can compare one of the arrays to a scalar.

A > 7

ans =

0 0 0
1 1 1

If you compare a 1-by-N row vector to an M-by-1 column vector, then MATLAB expands each vector
into an M-by-N matrix before performing the comparison. The resulting matrix contains the
comparison result for each combination of elements in the vectors.

A = 1:3

A =

1 2 3

B = [2; 3]

B =

2
3

A >= B

ans =

0 1 1
0 0 1

Empty Arrays

The relational operators work with arrays for which any dimension has size zero, as long as both
arrays have compatible sizes. This means that if one array has a dimension size of zero, then the size
of the corresponding dimension in the other array must be 1 or zero, and the size of that dimension in
the output is zero.

A = ones(3,0);
B = ones(3,1);
A == B

ans =

Empty matrix: 3-by-0

However, expressions such as

A == []

return an error if A is not 0-by-0 or 1-by-1. This behavior is consistent with that of all other binary
operators, such as +, -, >, <, &, |, and so on.

To test for empty arrays, use isempty(A).

2-30
 Array Comparison with Relational Operators

Complex Numbers

• The operators >, <, >=, and <= use only the real part of the operands in performing comparisons.
• The operators == and ~= test both real and imaginary parts of the operands.

Inf, NaN, NaT, and undefined Element Comparisons

• Inf values are equal to other Inf values.

• NaN values are not equal to any other numeric value, including other NaN values.
• NaT values are not equal to any other datetime value, including other NaT values.
• Undefined categorical elements are not equal to any other categorical value, including other
undefined elements.

Logic Statements
Use relational operators in conjunction with the logical operators A & B (AND), A | B (OR),
xor(A,B) (XOR), and ~A (NOT), to string together more complex logical statements.

For example, you can locate where negative elements occur in two arrays.

A = [2 -1; -3 10]

A =

2 -1
-3 10

B = [0 -2; -3 -1]

B =

0 -2
-3 -1

A<0 & B<0

ans =

0 1
1 0

For more examples, see “Find Array Elements That Meet a Condition” on page 5-2.

See Also
eq | ge | gt | le | lt | ne

More About
• “Array vs. Matrix Operations” on page 2-20
• “Compatible Array Sizes for Basic Operations” on page 2-25
• “MATLAB Operators and Special Characters” on page 2-2

2-31
2 Program Components

Operator Precedence
You can build expressions that use any combination of arithmetic, relational, and logical operators.
Precedence levels determine the order in which MATLAB evaluates an expression. Within each
precedence level, operators have equal precedence and are evaluated from left to right. The
precedence rules for MATLAB operators are shown in this list, ordered from highest precedence level
to lowest precedence level:

1 Parentheses ()
2 Transpose (.'), power (.^), complex conjugate transpose ('), matrix power (^)
3 Power with unary minus (.^-), unary plus (.^+), or logical negation (.^~) as well as matrix
power with unary minus (^-), unary plus (^+), or logical negation (^~).

Note Although most operators work from left to right, the operators (^-), (.^-), (^+), (.^+),
(^~), and (.^~) work from second from the right to left. It is recommended that you use
parentheses to explicitly specify the intended precedence of statements containing these
operator combinations.
4 Unary plus (+), unary minus (-), logical negation (~)
5 Multiplication (.*), right division (./), left division (.\), matrix multiplication (*), matrix
right division (/), matrix left division (\)
6 Addition (+), subtraction (-)
7 Colon operator (:)
8 Less than (<), less than or equal to (<=), greater than (>), greater than or equal to (>=),
equal to (==), not equal to (~=)
9 Element-wise AND (&)
10 Element-wise OR (|)
11 Short-circuit AND (&&)
12 Short-circuit OR (||)

Precedence of AND and OR Operators

MATLAB always gives the & operator precedence over the | operator. Although MATLAB typically
evaluates expressions from left to right, the expression a|b&c is evaluated as a|(b&c). It is a good
idea to use parentheses to explicitly specify the intended precedence of statements containing
combinations of & and |.

The same precedence rule holds true for the && and || operators.

Overriding Default Precedence

The default precedence can be overridden using parentheses, as shown in this example:
A = [3 9 5];
B = [2 1 5];
C = A./B.^2
C =
0.7500 9.0000 0.2000

2-32
 Operator Precedence

C = (A./B).^2
C =
2.2500 81.0000 1.0000

See Also

More About
• “Array vs. Matrix Operations” on page 2-20
• “Compatible Array Sizes for Basic Operations” on page 2-25
• “Array Comparison with Relational Operators” on page 2-29
• “MATLAB Operators and Special Characters” on page 2-2

2-33
2 Program Components

Average Similar Data Points Using a Tolerance

This example shows how to use uniquetol to find the average z-coordinate of 3-D points that have
similar (within tolerance) x and y coordinates.

Use random points picked from the peaks function in the domain [ − 3, 3] × [ − 3, 3] as the data set.
Add a small amount of noise to the data.

xy = rand(10000,2)*6-3;
z = peaks(xy(:,1),xy(:,2)) + 0.5-rand(10000,1);
A = [xy z];
plot3(A(:,1), A(:,2), A(:,3), '.')
view(-28,32)

Find points that have similar x and y coordinates using uniquetol with these options:

• Specify ByRows as true, since the rows of A contain the point coordinates.
• Specify OutputAllIndices as true to return the indices for all points that are within tolerance
of each other.
• Specify DataScale as [1 1 Inf] to use an absolute tolerance for the x and y coordinates, while
ignoring the z-coordinate.

DS = [1 1 Inf];
[C,ia] = uniquetol(A, 0.3, 'ByRows', true, ...
'OutputAllIndices', true, 'DataScale', DS);

2-34
 Average Similar Data Points Using a Tolerance

Average each group of points that are within tolerance (including the z-coordinates), producing a
reduced data set that still holds the general shape of the original data.

for k = 1:length(ia)
aveA(k,:) = mean(A(ia{k},:),1);
end

Plot the resulting averaged-out points on top of the original data.

hold on
plot3(aveA(:,1), aveA(:,2), aveA(:,3), '.r', 'MarkerSize', 15)

See Also
uniquetol

More About
• “Group Scattered Data Using a Tolerance” on page 2-36

2-35
2 Program Components

Group Scattered Data Using a Tolerance

This example shows how to group scattered data points based on their proximity to points of interest.

Create a set of random 2-D points. Then create and plot a grid of equally spaced points on top of the
random data.

x = rand(10000,2);
[a,b] = meshgrid(0:0.1:1);
gridPoints = [a(:), b(:)];
plot(x(:,1), x(:,2), '.')
hold on
plot(gridPoints(:,1), gridPoints(:,2), 'xr', 'Markersize', 6)

Use ismembertol to locate the data points in x that are within tolerance of the grid points in
gridPoints. Use these options with ismembertol:

• Specify ByRows as true, since the point coordinates are in the rows of x.
• Specify OutputAllIndices as true to return all of the indices for rows in x that are within
tolerance of the corresponding row in gridPoints.

[LIA,LocB] = ismembertol(gridPoints, x, 0.05, ...

'ByRows', true, 'OutputAllIndices', true);

For each grid point, plot the points in x that are within tolerance of that grid point.

2-36
 Group Scattered Data Using a Tolerance

figure
hold on
for k = 1:length(LocB)
plot(x(LocB{k},1), x(LocB{k},2), '.')
end
plot(gridPoints(:,1), gridPoints(:,2), 'xr', 'Markersize', 6)

See Also
ismembertol

More About
• “Average Similar Data Points Using a Tolerance” on page 2-34

2-37
2 Program Components

Bit-Wise Operations
This topic shows how to use bit-wise operations in MATLAB® to manipulate the bits of numbers.
Operating on bits is directly supported by most modern CPUs. In many cases, manipulating the bits of
a number in this way is quicker than performing arithmetic operations like division or multiplication.

Number Representations

Any number can be represented with bits (also known as binary digits). The binary, or base 2, form of
a number contains 1s and 0s to indicate which powers of 2 are present in the number. For example,
the 8-bit binary form of 7 is

00000111

A collection of 8 bits is also called 1 byte. In binary representations, the bits are counted from the
right to the left, so the first bit in this representation is a 1. This number represents 7 because

2 1 0
2 + 2 + 2 = 7.

When you type numbers into MATLAB, it assumes the numbers are double precision (a 64-bit binary
representation). However, you can also specify single-precision numbers (32-bit binary
representation) and integers (signed or unsigned, from 8 to 64 bits). For example, the most memory
efficient way to store the number 7 is with an 8-bit unsigned integer:

a = uint8(7)

a = uint8
7

You can even specify the binary form directly using the prefix 0b followed by the binary digits (for
more information, see “Hexadecimal and Binary Values” on page 6-52). MATLAB stores the number
in an integer format with the fewest number of bits. Instead of specifying all the bits, you need to
specify only the left-most 1 and all the digits to the right of it. The bits to the left of that bit are
trivially zero. So the number 7 is:

b = 0b111

b = uint8
7

MATLAB stores negative integers using two's complement. For example, consider the 8-bit signed
integer -8. To find the two's complement bit pattern for this number:

1 Start with the bit pattern of the positive version of the number, 8: 00001000.
2 Next, flip all of the bits: 11110111.
3 Finally, add 1 to the result: 11111000.

The result, 11111000, is the bit pattern for -8:

n = 0b11111000s8

n = int8
-8

2-38
 Bit-Wise Operations

MATLAB does not natively display the binary format of numbers. For that, you can use the dec2bin
function, which returns a character vector of binary digits for positive integers. Again, this function
returns only the digits that are not trivially zero.
dec2bin(b)

ans =
'111'

You can use bin2dec to switch between the two formats. For example, you can convert the binary
digits 10110101 to decimal format with the commands
data = [1 0 1 1 0 1 0 1];
dec = bin2dec(num2str(data))

dec = 181

The cast and typecast functions are also useful to switch among different data types. These
functions are similar, but they differ in how they treat the underlying storage of the number:

• cast — Changes the underlying data type of a variable.

• typecast — Converts data types without changing the underlying bits.

Because MATLAB does not display the digits of a binary number directly, you must pay attention to
data types when you work with bit-wise operations. Some functions return binary digits as a
character vector (dec2bin), some return the decimal number (bitand), and others return a vector of
the bits themselves (bitget).

Bit Masking with Logical Operators

MATLAB has several functions that enable you to perform logical operations on the bits of two equal-
length binary representations of numbers, known as bit masking:

• bitand — If both digits are 1, then the resulting digit is also a 1. Otherwise, the resulting digit is
0.
• bitor — If either digit is 1, then the resulting digit is also a 1. Otherwise, the resulting digit is 0.
• bitxor — If the digits are different, then the resulting digit is a 1. Otherwise, the resulting digit
is 0.

In addition to these functions, the bit-wise complement is available with bitcmp, but this is a unary
operation that flips the bits in only one number at a time.

One use of bit masking is to query the status of a particular bit. For example, if you use a bit-wise
AND operation with the binary number 00001000, you can query the status of the fourth bit. You can
then shift that bit to the first position so that MATLAB returns a 0 or 1 (the next section describes bit
shifting in more detail).
n = 0b10111001;
n4 = bitand(n,0b1000);
n4 = bitshift(n4,-3)

n4 = uint8
1

Bit-wise operations can have surprising applications. For example, consider the 8-bit binary
representation of the number n = 8:

2-39
2 Program Components

00001000

8 is a power of 2, so its binary representation contains a single 1. Now consider the number
n − 1 = 7:

00000111

By subtracting 1, all of the bits starting at the right-most 1 are flipped. As a result, when n is a power
of 2, corresponding digits of n and n − 1 are always different, and the bit-wise AND returns zero.

n = 0b1000;
bitand(n,n-1)

ans = uint8
0

0
However, when n is not a power of 2, then the right-most 1 is for the 2 bit, so n and n − 1 have all
0
the same bits except for the 2 bit. For this case, the bit-wise AND returns a nonzero number.

n = 0b101;
bitand(n,n-1)

ans = uint8
4

This operation suggests a simple function that operates on the bits of a given input number to check
whether the number is a power of 2:

function tf = isPowerOfTwo(n)
tf = n && ~bitand(n,n-1);
end

The use of the short-circuit AND operator && checks to make sure that n is not zero. If it is, then the
function does not need to calculate bitand(n,n-1) to know that the correct answer is false.

Shifting Bits

Because bit-wise logical operations compare corresponding bits in two numbers, it is useful to be able
to move the bits around to change which bits are compared. You can use bitshift to perform this
operation:

• bitshift(A,N) shifts the bits of A to the left by N digits. This is equivalent to multiplying A by
N
2 .
• bitshift(A,-N) shifts the bits of A to the right by N digits. This is equivalent to dividing A by
N
2 .

These operations are sometimes written A<<N (left shift) and A>>N (right shift), but MATLAB does not
use << and >> operators for this purpose.

When the bits of a number are shifted, some bits fall off the end of the number, and 0s or 1s are
introduced to fill in the newly created space. When you shift bits to the left, the bits are filled in on
the right; when you shift bits to the right, the bits are filled in on the left.

For example, if you shift the bits of the number 8 (binary: 1000) to the right by one digit, you get 4
(binary: 100).

2-40
 Bit-Wise Operations

n = 0b1000;
bitshift(n,-1)

ans = uint8
4

Similarly, if you shift the number 15 (binary: 1111) to the left by two digits, you get 60 (binary:
111100).

n = 0b1111;
bitshift(15,2)

ans = 60

When you shift the bits of a negative number, bitshift preserves the signed bit. For example, if you
shift the signed integer -3 (binary: 11111101) to the right by 2 digits, you get -1 (binary: 11111111).
In these cases, bitshift fills in on the left with 1s rather than 0s.

n = 0b11111101s8;
bitshift(n,-2)

ans = int8
-1

Writing Bits

You can use the bitset function to change the bits in a number. For example, change the first bit of
the number 8 to a 1 (which adds 1 to the number):

bitset(8,1)

ans = 9

By default, bitset flips bits to on or 1. You can optionally use the third input argument to specify the
bit value.

bitset does not change multiple bits at once, so you need to use a for loop to change multiple bits.
Therefore, the bits you change can be either consecutive or nonconsecutive. For example, change the
first two bits of the binary number 1000:

bits = [1 2];
c = 0b1000;
for k = 1:numel(bits)
c = bitset(c,bits(k));
end
dec2bin(c)

ans =
'1011'

Another common use of bitset is to convert a vector of binary digits into decimal format. For
example, use a loop to set the individual bits of the integer 11001101.

data = [1 1 0 0 1 1 0 1];
n = length(data);
dec = 0b0u8;
for k = 1:n
dec = bitset(dec,n+1-k,data(k));

2-41
2 Program Components

end
dec

dec = uint8
205

dec2bin(dec)

ans =
'11001101'

Reading Consecutive Bits

Another use of bit shifting is to isolate consecutive sections of bits. For example, read the last four
bits in the 16-bit number 0110000010100000. Recall that the last four bits are on the left of the
binary representation.

n = 0b0110000010100000;
dec2bin(bitshift(n,-12))

ans =
'110'

To isolate consecutive bits in the middle of the number, you can combine the use of bit shifting with
logical masking. For example, to extract the 13th and 14th bits, you can shift the bits to the right by
12 and then mask the resulting four bits with 0011. Because the inputs to bitand must be the same
integer data type, you can specify 0011 as an unsigned 16-bit integer with 0b11u16. Without the -
u16 suffix, MATLAB stores the number as an unsigned 8-bit integer.

m = 0b11u16;
dec2bin(bitand(bitshift(n,-12),m))

ans =
'10'

Another way to read consecutive bits is with bitget, which reads specified bits from a number. You
can use colon notation to specify several consecutive bits to read. For example, read the last 8 bits of
n.

bitget(n,16:-1:8)

ans = 1x9 uint16 row vector

0 1 1 0 0 0 0 0 1

Reading Nonconsecutive Bits

You can also use bitget to read bits from a number when the bits are not next to each other. For
example, read the 5th, 8th, and 14th bits from n.

bits = [14 8 5];

bitget(n,bits)

ans = 1x3 uint16 row vector

2-42
 Bit-Wise Operations

1 1 0

See Also
bitand | bitcmp | bitget | bitor | bitset | bitshift | bitxor

More About
• “Integers” on page 4-2
• “Perform Cyclic Redundancy Check” on page 2-44
• “Hexadecimal and Binary Values” on page 6-52

2-43
2 Program Components

Perform Cyclic Redundancy Check

This example shows how to perform a cyclic redundancy check (CRC) on the bits of a number. CRCs
are used to detect errors in the transmission of data in digital systems. When a piece of data is sent, a
short check value is attached to it. The check value is obtained by polynomial division with the bits in
the data. When the data is received, the polynomial division is repeated, and the result is compared
with the check value. If the results differ, then the data was corrupted during transmission.

Calculate Check Value by Hand

Start with a 16-bit binary number, which is the message to be transmitted:

1101100111011010

To obtain the check value, divide this number by the polynomial x3 + x2 + x + 1. You can represent
this polynomial with its coefficients: 1111.

The division is performed in steps, and after each step the polynomial divisor is aligned with the left-
most 1 in the number. Because the result of dividing by the four term polynomial has three bits (in
general dividing by a polynomial of length n + 1 produces a check value of length n), append the
number with 000 to calculate the remainder. At each step, the result uses the bit-wise XOR of the four
bits being operated on, and all other bits are unchanged.

The first division is

1101100111011010 000
1111
----------------
0010100111011010 000

Each successive division operates on the result of the previous step, so the second division is

0010100111011010 000
1111
----------------
0001010111011010 000

The division is completed once the dividend is all zeros. The complete division, including the above
two steps, is

1101100111011010 000
1111
0010100111011010 000
1111
0001010111011010 000
1111
0000101111011010 000
1111
0000010011011010 000
1111
0000001101011010 000
1111
0000000010011010 000
1111
0000000001101010 000
1111

2-44
 Perform Cyclic Redundancy Check

0000000000010010 000
1111
0000000000001100 000
1111
0000000000000011 000
11 11
0000000000000000 110

The remainder bits, 110, are the check value for this message.

Calculate Check Value Programmatically

In MATLAB®, you can perform this same operation to obtain the check value using bit-wise
operations. First, define variables for the message and polynomial divisor. Use unsigned 32-bit
integers so that extra bits are available for the remainder.
message = 0b1101100111011010u32;
messageLength = 16;
divisor = 0b1111u32;
divisorDegree = 3;

Next, initialize the polynomial divisor. Use dec2bin to display the bits of the result.
divisor = bitshift(divisor,messageLength-divisorDegree-1);
dec2bin(divisor)

ans =
'1111000000000000'

Now, shift the divisor and message so that they have the correct number of bits (16 bits for the
message and 3 bits for the remainder).
divisor = bitshift(divisor,divisorDegree);
remainder = bitshift(message,divisorDegree);
dec2bin(divisor)

ans =
'1111000000000000000'

dec2bin(remainder)

ans =
'1101100111011010000'

Perform the division steps of the CRC using a for loop. The for loop always advances a single bit
each step, so include a check to see if the current digit is a 1. If the current digit is a 1, then the
division step is performed; otherwise, the loop advances a bit and continues.
for k = 1:messageLength
if bitget(remainder,messageLength+divisorDegree)
remainder = bitxor(remainder,divisor);
end
remainder = bitshift(remainder,1);
end

Shift the bits of the remainder to the right to get the check value for the operation.
CRC_check_value = bitshift(remainder,-messageLength);
dec2bin(CRC_check_value)

2-45
2 Program Components

ans =
'110'

Check Message Integrity

You can use the check value to verify the integrity of a message by repeating the same division
operation. However, instead of using a remainder of 000 to start, use the check value 110. If the
message is error free, then the result of the division will be zero.

Reset the remainder variable, and add the CRC check value to the remainder bits using a bit-wise OR.
Introduce an error into the message by flipping one of the bit values with bitset.

remainder = bitshift(message,divisorDegree);
remainder = bitor(remainder,CRC_check_value);
remainder = bitset(remainder,6);
dec2bin(remainder)

ans =
'1101100111011110110'

Perform the CRC division operation and then check if the result is zero.

for k = 1:messageLength
if bitget(remainder,messageLength+divisorDegree)
remainder = bitxor(remainder,divisor);
end
remainder = bitshift(remainder,1);
end
if remainder == 0
disp('Message is error free.')
else
disp('Message contains errors.')
end

Message contains errors.

References
[1] Sklar, Bernard. Digital Communications: Fundamentals and Applications. Englewood Cliffs, NJ:
Prentice Hall, 1988.

[2] Wicker, Stephen B. Error Control Systems for Digital Communication and Storage. Upper Saddle
River, NJ: Prentice Hall, 1995.

See Also
bitshift | bitxor

More About
• “Bit-Wise Operations” on page 2-38
• “Hexadecimal and Binary Values” on page 6-52

2-46
 Conditional Statements

Conditional Statements
Conditional statements enable you to select at run time which block of code to execute. The simplest
conditional statement is an if statement. For example:

% Generate a random number

a = randi(100, 1);

% If it is even, divide by 2
if rem(a, 2) == 0
disp('a is even')
b = a/2;
end

if statements can include alternate choices, using the optional keywords elseif or else. For
example:

a = randi(100, 1);

if a < 30
disp('small')
elseif a < 80
disp('medium')
else
disp('large')
end

Alternatively, when you want to test for equality against a set of known values, use a switch
statement. For example:

[dayNum, dayString] = weekday(date, 'long', 'en_US');

switch dayString
case 'Monday'
disp('Start of the work week')
case 'Tuesday'
disp('Day 2')
case 'Wednesday'
disp('Day 3')
case 'Thursday'
disp('Day 4')
case 'Friday'
disp('Last day of the work week')
otherwise
disp('Weekend!')
end

For both if and switch, MATLAB executes the code corresponding to the first true condition, and
then exits the code block. Each conditional statement requires the end keyword.

In general, when you have many possible discrete, known values, switch statements are easier to
read than if statements. However, you cannot test for inequality between switch and case values.
For example, you cannot implement this type of condition with a switch:

yourNumber = input('Enter a number: ');

if yourNumber < 0

2-47
2 Program Components

disp('Negative')
elseif yourNumber > 0
disp('Positive')
else
disp('Zero')
end

See Also
end | if | return | switch

2-48
 Loop Control Statements

Loop Control Statements

With loop control statements, you can repeatedly execute a block of code. There are two types of
loops:

• for statements loop a specific number of times, and keep track of each iteration with an
incrementing index variable.

For example, preallocate a 10-element vector, and calculate five values:

x = ones(1,10);
for n = 2:6
x(n) = 2 * x(n - 1);
end
• while statements loop as long as a condition remains true.

For example, find the first integer n for which factorial(n) is a 100-digit number:

n = 1;
nFactorial = 1;
while nFactorial < 1e100
n = n + 1;
nFactorial = nFactorial * n;
end

Each loop requires the end keyword.

It is a good idea to indent the loops for readability, especially when they are nested (that is, when one
loop contains another loop):

A = zeros(5,100);
for m = 1:5
for n = 1:100
A(m, n) = 1/(m + n - 1);
end
end

You can programmatically exit a loop using a break statement, or skip to the next iteration of a loop
using a continue statement. For example, count the number of lines in the help for the magic
function (that is, all comment lines until a blank line):

fid = fopen('magic.m','r');
count = 0;
while ~feof(fid)
line = fgetl(fid);
if isempty(line)
break
elseif ~strncmp(line,'%',1)
continue
end
count = count + 1;
end
fprintf('%d lines in MAGIC help\n',count);
fclose(fid);

2-49
2 Program Components

Tip If you inadvertently create an infinite loop (a loop that never ends on its own), stop execution of
the loop by pressing Ctrl+C.

See Also
break | continue | end | for | while

2-50
 Regular Expressions

Regular Expressions
In this section...
“What Is a Regular Expression?” on page 2-51
“Steps for Building Expressions” on page 2-52
“Operators and Characters” on page 2-54

What Is a Regular Expression?

A regular expression is a sequence of characters that defines a certain pattern. You normally use a
regular expression to search text for a group of words that matches the pattern, for example, while
parsing program input or while processing a block of text.

The character vector 'Joh?n\w*' is an example of a regular expression. It defines a pattern that
starts with the letters Jo, is optionally followed by the letter h (indicated by 'h?'), is then followed
by the letter n, and ends with any number of word characters, that is, characters that are alphabetic,
numeric, or underscore (indicated by '\w*'). This pattern matches any of the following:

Jon, John, Jonathan, Johnny

Regular expressions provide a unique way to search a volume of text for a particular subset of
characters within that text. Instead of looking for an exact character match as you would do with a
function like strfind, regular expressions give you the ability to look for a particular pattern of
characters.

For example, several ways of expressing a metric rate of speed are:

km/h
km/hr
km/hour
kilometers/hour
kilometers per hour

You could locate any of the above terms in your text by issuing five separate search commands:

strfind(text, 'km/h');
strfind(text, 'km/hour');
% etc.

To be more efficient, however, you can build a single phrase that applies to all of these search terms:

Translate this phrase into a regular expression (to be explained later in this section) and you have:

2-51
2 Program Components

pattern = 'k(ilo)?m(eters)?(/|\sper\s)h(r|our)?';

Now locate one or more of the terms using just a single command:
text = ['The high-speed train traveled at 250 ', ...
'kilometers per hour alongside the automobile ', ...
'travelling at 120 km/h.'];
regexp(text, pattern, 'match')

ans =

1×2 cell array

{'kilometers per hour'} {'km/h'}

There are four MATLAB functions that support searching and replacing characters using regular
expressions. The first three are similar in the input values they accept and the output values they
return. For details, click the links to the function reference pages.

Function Description
regexp Match regular expression.
regexpi Match regular expression, ignoring case.
regexprep Replace part of text using regular expression.
regexptranslate Translate text into regular expression.

When calling any of the first three functions, pass the text to be parsed and the regular expression in
the first two input arguments. When calling regexprep, pass an additional input that is an
expression that specifies a pattern for the replacement.

Steps for Building Expressions

There are three steps involved in using regular expressions to search text for a particular term:
1 Identify unique patterns in the string on page 2-53

This entails breaking up the text you want to search for into groups of like character types. These
character types could be a series of lowercase letters, a dollar sign followed by three numbers
and then a decimal point, etc.
2 Express each pattern as a regular expression on page 2-53

Use the metacharacters and operators described in this documentation to express each segment
of your search pattern as a regular expression. Then combine these expression segments into the
single expression to use in the search.
3 Call the appropriate search function on page 2-54

Pass the text you want to parse to one of the search functions, such as regexp or regexpi, or to
the text replacement function, regexprep.

The example shown in this section searches a record containing contact information belonging to a
group of five friends. This information includes each person's name, telephone number, place of
residence, and email address. The goal is to extract specific information from the text..
contacts = { ...
'Harry 287-625-7315 Columbus, OH hparker@hmail.com'; ...

2-52
 Regular Expressions

'Janice 529-882-1759 Fresno, CA jan_stephens@horizon.net'; ...

'Mike 793-136-0975 Richmond, VA sue_and_mike@hmail.net'; ...
'Nadine 648-427-9947 Tampa, FL nadine_berry@horizon.net'; ...
'Jason 697-336-7728 Montrose, CO jason_blake@mymail.com'};

The first part of the example builds a regular expression that represents the format of a standard
email address. Using that expression, the example then searches the information for the email
address of one of the group of friends. Contact information for Janice is in row 2 of the contacts cell
array:

contacts{2}

ans =

'Janice 529-882-1759 Fresno, CA jan_stephens@horizon.net'

Step 1 — Identify Unique Patterns in the Text

A typical email address is made up of standard components: the user's account name, followed by an
@ sign, the name of the user's internet service provider (ISP), a dot (period), and the domain to which
the ISP belongs. The table below lists these components in the left column, and generalizes the
format of each component in the right column.

Unique patterns of an email address General description of each pattern

Start with the account name One or more lowercase letters and underscores
jan_stephens . . .
Add '@' @ sign
jan_stephens@ . . .
Add the ISP One or more lowercase letters, no underscores
jan_stephens@horizon . . .
Add a dot (period) Dot (period) character
jan_stephens@horizon. . . .
Finish with the domain com or net
jan_stephens@horizon.net

Step 2 — Express Each Pattern as a Regular Expression

In this step, you translate the general formats derived in Step 1 into segments of a regular
expression. You then add these segments together to form the entire expression.

The table below shows the generalized format descriptions of each character pattern in the left-most
column. (This was carried forward from the right column of the table in Step 1.) The second column
shows the operators or metacharacters that represent the character pattern.

Description of each segment Pattern

One or more lowercase letters and underscores [a-z_]+
@ sign @
One or more lowercase letters, no underscores [a-z]+
Dot (period) character \.
com or net (com|net)

2-53
2 Program Components

Assembling these patterns into one character vector gives you the complete expression:

email = '[a-z_]+@[a-z]+\.(com|net)';

Step 3 — Call the Appropriate Search Function

In this step, you use the regular expression derived in Step 2 to match an email address for one of the
friends in the group. Use the regexp function to perform the search.

Here is the list of contact information shown earlier in this section. Each person's record occupies a
row of the contacts cell array:

contacts = { ...
'Harry 287-625-7315 Columbus, OH hparker@hmail.com'; ...
'Janice 529-882-1759 Fresno, CA jan_stephens@horizon.net'; ...
'Mike 793-136-0975 Richmond, VA sue_and_mike@hmail.net'; ...
'Nadine 648-427-9947 Tampa, FL nadine_berry@horizon.net'; ...
'Jason 697-336-7728 Montrose, CO jason_blake@mymail.com'};

This is the regular expression that represents an email address, as derived in Step 2:

email = '[a-z_]+@[a-z]+\.(com|net)';

Call the regexp function, passing row 2 of the contacts cell array and the email regular
expression. This returns the email address for Janice.

regexp(contacts{2}, email, 'match')

ans =

1×1 cell array

{'jan_stephens@horizon.net'}

MATLAB parses a character vector from left to right, “consuming” the vector as it goes. If matching
characters are found, regexp records the location and resumes parsing the character vector, starting
just after the end of the most recent match.

Make the same call, but this time for the fifth person in the list:

regexp(contacts{5}, email, 'match')

ans =

1×1 cell array

{'jason_blake@mymail.com'}

You can also search for the email address of everyone in the list by using the entire cell array for the
input argument:

regexp(contacts, email, 'match');

Operators and Characters

Regular expressions can contain characters, metacharacters, operators, tokens, and flags that specify
patterns to match, as described in these sections:

2-54
 Regular Expressions

• “Metacharacters” on page 2-55

• “Character Representation” on page 2-56
• “Quantifiers” on page 2-56
• “Grouping Operators” on page 2-57
• “Anchors” on page 2-58
• “Lookaround Assertions” on page 2-58
• “Logical and Conditional Operators” on page 2-59
• “Token Operators” on page 2-59
• “Dynamic Expressions” on page 2-60
• “Comments” on page 2-61
• “Search Flags” on page 2-61

Metacharacters

Metacharacters represent letters, letter ranges, digits, and space characters. Use them to construct a
generalized pattern of characters.

Metacharacter Description Example

. Any single character, including white '..ain' matches sequences of five
space consecutive characters that end with 'ain'.
[c1c2c3] Any character contained within the '[rp.]ain' matches 'rain' or 'pain' or
square brackets. The following '.ain'.
characters are treated literally: $ | . *
+ ? and - when not used to indicate a
range.
[^c1c2c3] Any character not contained within the '[^*rp]ain' matches all four-letter
square brackets. The following sequences that end in 'ain', except 'rain'
characters are treated literally: $ | . * and 'pain' and '*ain'. For example, it
+ ? and - when not used to indicate a matches 'gain', 'lain', or 'vain'.
range.
[c1-c2] Any character in the range of c1 through '[A-G]' matches a single character in the
c2 range of A through G.
\w Any alphabetic, numeric, or underscore '\w*' identifies a word.
character. For English character sets, \w
is equivalent to [a-zA-Z_0-9]
\W Any character that is not alphabetic, '\W*' identifies a term that is not a word.
numeric, or underscore. For English
character sets, \W is equivalent to [^a-
zA-Z_0-9]
\s Any white-space character; equivalent to '\w*n\s' matches words that end with the
[ \f\n\r\t\v] letter n, followed by a white-space character.
\S Any non-white-space character; '\d\S' matches a numeric digit followed by
equivalent to [^ \f\n\r\t\v] any non-white-space character.
\d Any numeric digit; equivalent to [0-9] '\d*' matches any number of consecutive
digits.

2-55
2 Program Components

Metacharacter Description Example

\D Any nondigit character; equivalent to '\w*\D\>' matches words that do not end
[^0-9] with a numeric digit.
\oN or \o{N} Character of octal value N '\o{40}' matches the space character,
defined by octal 40.
\xN or \x{N} Character of hexadecimal value N '\x2C' matches the comma character, defined
by hex 2C.

Character Representation

Operator Description
\a Alarm (beep)
\b Backspace
\f Form feed
\n New line
\r Carriage return
\t Horizontal tab
\v Vertical tab
\char Any character with special meaning in regular expressions that you want to match literally
(for example, use \\ to match a single backslash)

Quantifiers

Quantifiers specify the number of times a pattern must occur in the matching text.

Quantifier Matches the expression when it Example

occurs...
expr* 0 or more times consecutively. '\w*' matches a word of any length.
expr? 0 times or 1 time. '\w*(\.m)?' matches words that optionally
end with the extension .m.
expr+ 1 or more times consecutively. '<img src="\w+\.gif">' matches an
<img> HTML tag when the file name contains
one or more characters.
expr{m,n} At least m times, but no more than n times '\S{4,8}' matches between four and eight
consecutively. non-white-space characters.

{0,1} is equivalent to ?.
expr{m,} At least m times consecutively. '<a href="\w{1,}\.html">' matches an
<a> HTML tag when the file name contains one
{0,} and {1,} are equivalent to * and +, or more characters.
respectively.
expr{n} Exactly n times consecutively. '\d{4}' matches four consecutive digits.

Equivalent to {n,n}.

Quantifiers can appear in three modes, described in the following table. q represents any of the
quantifiers in the previous table.

2-56
 Regular Expressions

Mode Description Example

exprq Greedy expression: match as many characters Given the text '<tr><td><p>text</p></
as possible. td>', the expression '</?t.*>' matches all
characters between <tr and /td>:

'<tr><td><p>text</p></td>'
exprq? Lazy expression: match as few characters as Given the text'<tr><td><p>text</p></
necessary. td>', the expression '</?t.*?>' ends each
match at the first occurrence of the closing
angle bracket (>):

'<tr>' '<td>' '</td>'

exprq+ Possessive expression: match as much as Given the text'<tr><td><p>text</p></
possible, but do not rescan any portions of the td>', the expression '</?t.*+>' does not
text. return any matches, because the closing
angle bracket is captured using .*, and is not
rescanned.

Grouping Operators

Grouping operators allow you to capture tokens, apply one operator to multiple elements, or disable
backtracking in a specific group.

Grouping Description Example

Operator
(expr) Group elements of the expression and capture 'Joh?n\s(\w*)' captures a token that
tokens. contains the last name of any person with the
first name John or Jon.
(?:expr) Group, but do not capture tokens. '(?:[aeiou][^aeiou]){2}' matches two
consecutive patterns of a vowel followed by a
nonvowel, such as 'anon'.

Without grouping, '[aeiou][^aeiou]

{2}'matches a vowel followed by two
nonvowels.
(?>expr) Group atomically. Do not backtrack within the 'A(?>.*)Z' does not match 'AtoZ',
group to complete the match, and do not although 'A(?:.*)Z' does. Using the atomic
capture tokens. group, Z is captured using .* and is not
rescanned.
(expr1|expr2) Match expression expr1 or expression '(let|tel)\w+' matches words that start
expr2. with let or tel.

If there is a match with expr1, then expr2 is

ignored.

You can include ?: or ?> after the opening

parenthesis to suppress tokens or group
atomically.

2-57
2 Program Components

Anchors

Anchors in the expression match the beginning or end of a character vector or word.

Anchor Matches the... Example

^expr Beginning of the input text. '^M\w*' matches a word starting with M at
the beginning of the text.
expr$ End of the input text. '\w*m$' matches words ending with m at the
end of the text.
\<expr Beginning of a word. '\<n\w*' matches any words starting with
n.
expr\> End of a word. '\w*e\>' matches any words ending with e.

Lookaround Assertions

Lookaround assertions look for patterns that immediately precede or follow the intended match, but
are not part of the match.

The pointer remains at the current location, and characters that correspond to the test expression
are not captured or discarded. Therefore, lookahead assertions can match overlapping character
groups.

Lookaround Description Example

Assertion
expr(?=test) Look ahead for characters that match test. '\w*(?=ing)' matches terms that are
followed by ing, such as 'Fly' and 'fall'
in the input text 'Flying, not falling.'
expr(?!test) Look ahead for characters that do not 'i(?!ng)' matches instances of the letter i
match test. that are not followed by ng.
(?<=test)expr Look behind for characters that match '(?<=re)\w*' matches terms that follow
test. 're', such as 'new', 'use', and 'cycle'
in the input text 'renew, reuse,
recycle'
(?<!test)expr Look behind for characters that do not '(?<!\d)(\d)(?!\d)' matches single-
match test. digit numbers (digits that do not precede or
follow other digits).

If you specify a lookahead assertion before an expression, the operation is equivalent to a logical AND.

Operation Description Example

(?=test)expr Match both test and expr. '(?=[a-z])[^aeiou]' matches
consonants.
(?!test)expr Match expr and do not match test. '(?![aeiou])[a-z]' matches consonants.

For more information, see “Lookahead Assertions in Regular Expressions” on page 2-63.

2-58
 Regular Expressions

Logical and Conditional Operators

Logical and conditional operators allow you to test the state of a given condition, and then use the
outcome to determine which pattern, if any, to match next. These operators support logical OR and if
or if/else conditions. (For AND conditions, see “Lookaround Assertions” on page 2-58.)

Conditions can be tokens on page 2-59, lookaround assertions on page 2-58, or dynamic expressions
on page 2-60 of the form (?@cmd). Dynamic expressions must return a logical or numeric value.

Conditional Operator Description Example

expr1|expr2 Match expression expr1 or expression '(let|tel)\w+' matches words that
expr2. start with let or tel.

If there is a match with expr1, then

expr2 is ignored.
(?(cond)expr) If condition cond is true, then match '(?(?@ispc)[A-Z]:\\)' matches a
expr. drive name, such as C:\, when run on a
Windows system.
(?(cond)expr1|expr2) If condition cond is true, then match 'Mr(s?)\..*?(?(1)her|his) \w*'
expr1. Otherwise, match expr2. matches text that includes her when
the text begins with Mrs, or that
includes his when the text begins with
Mr.

Token Operators

Tokens are portions of the matched text that you define by enclosing part of the regular expression in
parentheses. You can refer to a token by its sequence in the text (an ordinal token), or assign names
to tokens for easier code maintenance and readable output.

Ordinal Token Operator Description Example

(expr) Capture in a token the characters that 'Joh?n\s(\w*)' captures a token that
match the enclosed expression. contains the last name of any person
with the first name John or Jon.
\N Match the Nth token. '<(\w+).*>.*</\1>' captures tokens
for HTML tags, such as 'title' from
the text '<title>Some text</
title>'.
(?(N)expr1|expr2) If the Nth token is found, then match 'Mr(s?)\..*?(?(1)her|his) \w*'
expr1. Otherwise, match expr2. matches text that includes her when
the text begins with Mrs, or that
includes his when the text begins with
Mr.

Named Token Operator Description Example

(?<name>expr) Capture in a named token the '(?<month>\d+)-(?<day>\d+)-(?
characters that match the enclosed <yr>\d+)' creates named tokens for
expression. the month, day, and year in an input
date of the form mm-dd-yy.

2-59
2 Program Components

Named Token Operator Description Example

\k<name> Match the token referred to by name. '<(?<tag>\w+).*>.*</\k<tag>>'
captures tokens for HTML tags, such as
'title' from the text '<title>Some
text</title>'.
(?(name)expr1|expr2) If the named token is found, then 'Mr(?<sex>s?)\..*?(?(sex)her|
match expr1. Otherwise, match his) \w*' matches text that includes
expr2. her when the text begins with Mrs, or
that includes his when the text begins
with Mr.

Note If an expression has nested parentheses, MATLAB captures tokens that correspond to the
outermost set of parentheses. For example, given the search pattern '(and(y|rew))', MATLAB
creates a token for 'andrew' but not for 'y' or 'rew'.

For more information, see “Tokens in Regular Expressions” on page 2-66.

Dynamic Expressions

Dynamic expressions allow you to execute a MATLAB command or a regular expression to determine
the text to match.

The parentheses that enclose dynamic expressions do not create a capturing group.

Operator Description Example

(??expr) Parse expr and include the resulting term '^(\d+)((??\\w{$1}))' determines
in the match expression. how many characters to match by reading
a digit at the beginning of the match. The
When parsed, expr must correspond to a dynamic expression is enclosed in a
complete, valid regular expression. second set of parentheses so that the
Dynamic expressions that use the backslash resulting match is captured in a token. For
escape character (\) require two instance, matching '5XXXXX' captures
backslashes: one for the initial parsing of tokens for '5' and 'XXXXX'.
expr, and one for the complete match.
(??@cmd) Execute the MATLAB command '(.{2,}).?(??@fliplr($1))' finds
represented by cmd, and include the output palindromes that are at least four
returned by the command in the match characters long, such as 'abba'.
expression.
(?@cmd) Execute the MATLAB command '\w*?(\w)(?@disp($1))\1\w*'
represented by cmd, but discard any output matches words that include double letters
the command returns. (Helpful for (such as pp), and displays intermediate
diagnosing regular expressions.) results.

Within dynamic expressions, use the following operators to define replacement terms.

Replacement Operator Description

$& or $0 Portion of the input text that is currently a match
$` Portion of the input text that precedes the current match

2-60
 Regular Expressions

Replacement Operator Description

$' Portion of the input text that follows the current match (use $'' to represent $')
$N Nth token
$<name> Named token
${cmd} Output returned when MATLAB executes the command, cmd

For more information, see “Dynamic Regular Expressions” on page 2-72.

Comments

The comment operator enables you to insert comments into your code to make it more maintainable.
The text of the comment is ignored by MATLAB when matching against the input text.

Characters Description Example

(?#comment) Insert a comment in the regular expression. '(?# Initial digit)\<\d\w+'
The comment text is ignored when includes a comment, and matches words
matching the input. that begin with a number.

Search Flags

Search flags modify the behavior for matching expressions.

Flag Description
(?-i) Match letter case (default for regexp and regexprep).
(?i) Do not match letter case (default for regexpi).
(?s) Match dot (.) in the pattern with any character (default).
(?-s) Match dot in the pattern with any character that is not a newline character.
(?-m) Match the ^ and $ metacharacters at the beginning and end of text (default).
(?m) Match the ^ and $ metacharacters at the beginning and end of a line.
(?-x) Include space characters and comments when matching (default).
(?x) Ignore space characters and comments when matching. Use '\ ' and '\#' to
match space and # characters.

The expression that the flag modifies can appear either after the parentheses, such as

(?i)\w*

or inside the parentheses and separated from the flag with a colon (:), such as

(?i:\w*)

The latter syntax allows you to change the behavior for part of a larger expression.

See Also
regexp | regexpi | regexprep | regexptranslate

2-61
2 Program Components

More About
• “Lookahead Assertions in Regular Expressions” on page 2-63
• “Tokens in Regular Expressions” on page 2-66
• “Dynamic Regular Expressions” on page 2-72

2-62
 Lookahead Assertions in Regular Expressions

Lookahead Assertions in Regular Expressions

In this section...
“Lookahead Assertions” on page 2-63
“Overlapping Matches” on page 2-63
“Logical AND Conditions” on page 2-64

Lookahead Assertions
There are two types of lookaround assertions for regular expressions: lookahead and lookbehind. In
both cases, the assertion is a condition that must be satisfied to return a match to the expression.

A lookahead assertion has the form (?=test) and can appear anywhere in a regular expression.
MATLAB looks ahead of the current location in the text for the test condition. If MATLAB matches the
test condition, it continues processing the rest of the expression to find a match.

For example, look ahead in a character vector specifying a path to find the name of the folder that
contains a program file (in this case, fileread.m).

chr = which('fileread')

chr =

'matlabroot\toolbox\matlab\iofun\fileread.m'

regexp(chr,'\w+(?=\\\w+\.[mp])','match')

ans =

1×1 cell array

{'iofun'}

The match expression, \w+, searches for one or more alphanumeric or underscore characters. Each
time regexp finds a term that matches this condition, it looks ahead for a backslash (specified with
two backslashes, \\), followed by a file name (\w+) with an .m or .p extension (\.[mp]). The
regexp function returns the match that satisfies the lookahead condition, which is the folder name
iofun.

Overlapping Matches
Lookahead assertions do not consume any characters in the text. As a result, you can use them to find
overlapping character sequences.

For example, use lookahead to find every sequence of six nonwhitespace characters in a character
vector by matching initial characters that precede five additional characters:

chr = 'Locate several 6-char. phrases';

startIndex = regexpi(chr,'\S(?=\S{5})')

startIndex =

1 8 9 16 17 24 25

2-63
2 Program Components

The starting indices correspond to these phrases:

Locate severa everal 6-char -char. phrase hrases

Without the lookahead operator, MATLAB parses a character vector from left to right, consuming the
vector as it goes. If matching characters are found, regexp records the location and resumes parsing
the character vector from the location of the most recent match. There is no overlapping of
characters in this process.
chr = 'Locate several 6-char. phrases';
startIndex = regexpi(chr,'\S{6}')

startIndex =

1 8 16 24

The starting indices correspond to these phrases:

Locate severa 6-char phrase

Logical AND Conditions

Another way to use a lookahead operation is to perform a logical AND between two conditions. This
example initially attempts to locate all lowercase consonants in a character array consisting of the
first 50 characters of the help for the normest function:
helptext = help('normest');
chr = helptext(1:50)

chr =

' NORMEST Estimate the matrix 2-norm.

NORMEST(S'

Merely searching for non-vowels ([^aeiou]) does not return the expected answer, as the output
includes capital letters, space characters, and punctuation:
c = regexp(chr,'[^aeiou]','match')

c =

1×43 cell array

Columns 1 through 14

{' '} {'N'} {'O'} {'R'} {'M'} {'E'} {'S'} {'T'} {' '} {'E'} {'s

Columns 15 through 28

{' '} {'t'} {'h'} {' '} {'m'} {'t'} {'r'} {'x'} {' '} {'2'} {'-

Columns 29 through 42

{'.'} {'↵'} {' '} {' '} {' '} {' '} {'N'} {'O'} {'R'} {'M'} {'E

Column 43

{'S'}

2-64
 Lookahead Assertions in Regular Expressions

Try this again, using a lookahead operator to create the following AND condition:

(lowercase letter) AND (not a vowel)

This time, the result is correct:

c = regexp(chr,'(?=[a-z])[^aeiou]','match')

c =

1×13 cell array

{'s'} {'t'} {'m'} {'t'} {'t'} {'h'} {'m'} {'t'} {'r'} {'x'} {'n

Note that when using a lookahead operator to perform an AND, you need to place the match
expression expr after the test expression test:

(?=test)expr or (?!test)expr

See Also
regexp | regexpi | regexprep

More About
• “Regular Expressions” on page 2-51

2-65
2 Program Components

Tokens in Regular Expressions

In this section...
“Introduction” on page 2-66
“Multiple Tokens” on page 2-68
“Unmatched Tokens” on page 2-69
“Tokens in Replacement Text” on page 2-69
“Named Capture” on page 2-70

Introduction
Parentheses used in a regular expression not only group elements of that expression together, but
also designate any matches found for that group as tokens. You can use tokens to match other parts
of the same text. One advantage of using tokens is that they remember what they matched, so you
can recall and reuse matched text in the process of searching or replacing.

Each token in the expression is assigned a number, starting from 1, going from left to right. To make
a reference to a token later in the expression, refer to it using a backslash followed by the token
number. For example, when referencing a token generated by the third set of parentheses in the
expression, use \3.

As a simple example, if you wanted to search for identical sequential letters in a character array, you
could capture the first letter as a token and then search for a matching character immediately
afterwards. In the expression shown below, the (\S) phrase creates a token whenever regexp
matches any nonwhitespace character in the character array. The second part of the expression,
'\1', looks for a second instance of the same character immediately following the first.
poe = ['While I nodded, nearly napping, ' ...
'suddenly there came a tapping,'];

[mat,tok,ext] = regexp(poe, '(\S)\1', 'match', ...

'tokens', 'tokenExtents');
mat

mat =

1×4 cell array

{'dd'} {'pp'} {'dd'} {'pp'}

The cell array tok contains cell arrays that each contain a token.
tok{:}

ans =

1×1 cell array

{'d'}

ans =

2-66
 Tokens in Regular Expressions

1×1 cell array

{'p'}

ans =

1×1 cell array

{'d'}

ans =

1×1 cell array

{'p'}

The cell array ext contains numeric arrays that each contain starting and ending indices for a token.

ext{:}

ans =

11 11

ans =

26 26

ans =

35 35

ans =

57 57

For another example, capture pairs of matching HTML tags (e.g., <a> and </a>) and the text
between them. The expression used for this example is

expr = '<(\w+).*?>.*?</\1>';

The first part of the expression, '<(\w+)', matches an opening angle bracket (<) followed by one or
more alphabetic, numeric, or underscore characters. The enclosing parentheses capture token
characters following the opening angle bracket.

The second part of the expression, '.*?>.*?', matches the remainder of this HTML tag (characters
up to the >), and any characters that may precede the next opening angle bracket.

The last part, '</\1>', matches all characters in the ending HTML tag. This tag is composed of the
sequence </tag>, where tag is whatever characters were captured as a token.

hstr = '<!comment><a name="752507"></a><b>Default</b><br>';

expr = '<(\w+).*?>.*?</\1>';

2-67
2 Program Components

[mat,tok] = regexp(hstr, expr, 'match', 'tokens');

mat{:}

ans =

'<a name="752507"></a>'

ans =

'<b>Default</b>'

tok{:}

ans =

1×1 cell array

{'a'}

ans =

1×1 cell array

{'b'}

Multiple Tokens
Here is an example of how tokens are assigned values. Suppose that you are going to search the
following text:

andy ted bob jim andrew andy ted mark

You choose to search the above text with the following search pattern:

and(y|rew)|(t)e(d)

This pattern has three parenthetical expressions that generate tokens. When you finally perform the
search, the following tokens are generated for each match.

Match Token 1 Token 2

andy y
ted t d
andrew rew
andy y
ted t d

Only the highest level parentheses are used. For example, if the search pattern and(y|rew) finds the
text andrew, token 1 is assigned the value rew. However, if the search pattern (and(y|rew)) is
used, token 1 is assigned the value andrew.

2-68
 Tokens in Regular Expressions

Unmatched Tokens
For those tokens specified in the regular expression that have no match in the text being evaluated,
regexp and regexpi return an empty character vector ('') as the token output, and an extent that
marks the position in the string where the token was expected.

The example shown here executes regexp on a character vector specifying the path returned from
the MATLAB tempdir function. The regular expression expr includes six token specifiers, one for
each piece of the path. The third specifier [a-z]+ has no match in the character vector because this
part of the path, Profiles, begins with an uppercase letter:
chr = tempdir

chr =

'C:\WINNT\Profiles\bpascal\LOCALS~1\Temp\'

expr = ['([A-Z]:)\\(WINNT)\\([a-z]+)?.*\\' ...

'([a-z]+)\\([A-Z]+~\d)\\(Temp)\\'];

[tok, ext] = regexp(chr, expr, 'tokens', 'tokenExtents');

When a token is not found in the text, regexp returns an empty character vector ('') as the token
and a numeric array with the token extent. The first number of the extent is the string index that
marks where the token was expected, and the second number of the extent is equal to one less than
the first.

In the case of this example, the empty token is the third specified in the expression, so the third token
returned is empty:
tok{:}

ans =

1×6 cell array

{'C:'} {'WINNT'} {0×0 char} {'bpascal'} {'LOCALS~1'} {'Temp'}

The third token extent returned in the variable ext has the starting index set to 10, which is where
the nonmatching term, Profiles, begins in the path. The ending extent index is set to one less than
the starting index, or 9:
ext{:}

ans =

1 2
4 8
10 9
19 25
27 34
36 39

Tokens in Replacement Text

When using tokens in replacement text, reference them using $1, $2, etc. instead of \1, \2, etc. This
example captures two tokens and reverses their order. The first, $1, is 'Norma Jean' and the

2-69
2 Program Components

second, $2, is 'Baker'. Note that regexprep returns the modified text, not a vector of starting
indices.
regexprep('Norma Jean Baker', '(\w+\s\w+)\s(\w+)', '$2, $1')

ans =

'Baker, Norma Jean'

Named Capture
If you use a lot of tokens in your expressions, it may be helpful to assign them names rather than
having to keep track of which token number is assigned to which token.

When referencing a named token within the expression, use the syntax \k<name> instead of the
numeric \1, \2, etc.:
poe = ['While I nodded, nearly napping, ' ...
'suddenly there came a tapping,'];

regexp(poe, '(?<anychar>.)\k<anychar>', 'match')

ans =

1×4 cell array

{'dd'} {'pp'} {'dd'} {'pp'}

Named tokens can also be useful in labeling the output from the MATLAB regular expression
functions. This is especially true when you are processing many pieces of text.

For example, parse different parts of street addresses from several character vectors. A short name is
assigned to each token in the expression:
chr1 = '134 Main Street, Boulder, CO, 14923';
chr2 = '26 Walnut Road, Topeka, KA, 25384';
chr3 = '847 Industrial Drive, Elizabeth, NJ, 73548';

p1 = '(?<adrs>\d+\s\S+\s(Road|Street|Avenue|Drive))';
p2 = '(?<city>[A-Z][a-z]+)';
p3 = '(?<state>[A-Z]{2})';
p4 = '(?<zip>\d{5})';

expr = [p1 ', ' p2 ', ' p3 ', ' p4];

As the following results demonstrate, you can make your output easier to work with by using named
tokens:
loc1 = regexp(chr1, expr, 'names')

loc1 =

struct with fields:

adrs: '134 Main Street'

city: 'Boulder'
state: 'CO'
zip: '14923'

2-70
 Tokens in Regular Expressions

loc2 = regexp(chr2, expr, 'names')

loc2 =

struct with fields:

adrs: '26 Walnut Road'

city: 'Topeka'
state: 'KA'
zip: '25384'

loc3 = regexp(chr3, expr, 'names')

loc3 =

struct with fields:

adrs: '847 Industrial Drive'

city: 'Elizabeth'
state: 'NJ'
zip: '73548'

See Also
regexp | regexpi | regexprep

More About
• “Regular Expressions” on page 2-51

2-71
2 Program Components

Dynamic Regular Expressions

In this section...
“Introduction” on page 2-72
“Dynamic Match Expressions — (??expr)” on page 2-73
“Commands That Modify the Match Expression — (??@cmd)” on page 2-73
“Commands That Serve a Functional Purpose — (?@cmd)” on page 2-74
“Commands in Replacement Expressions — ${cmd}” on page 2-76

Introduction
In a dynamic expression, you can make the pattern that you want regexp to match dependent on the
content of the input text. In this way, you can more closely match varying input patterns in the text
being parsed. You can also use dynamic expressions in replacement terms for use with the
regexprep function. This gives you the ability to adapt the replacement text to the parsed input.

You can include any number of dynamic expressions in the match_expr or replace_expr
arguments of these commands:

regexp(text, match_expr)
regexpi(text, match_expr)
regexprep(text, match_expr, replace_expr)

As an example of a dynamic expression, the following regexprep command correctly replaces the
term internationalization with its abbreviated form, i18n. However, to use it on a different
term such as globalization, you have to use a different replacement expression:

match_expr = '(^\w)(\w*)(\w$)';

replace_expr1 = '$118$3';
regexprep('internationalization', match_expr, replace_expr1)

ans =

'i18n'

replace_expr2 = '$111$3';
regexprep('globalization', match_expr, replace_expr2)

ans =

'g11n'

Using a dynamic expression ${num2str(length($2))} enables you to base the replacement

expression on the input text so that you do not have to change the expression each time. This
example uses the dynamic replacement syntax ${cmd}.

match_expr = '(^\w)(\w*)(\w$)';
replace_expr = '$1${num2str(length($2))}$3';

regexprep('internationalization', match_expr, replace_expr)

2-72
 Dynamic Regular Expressions

ans =

'i18n'

regexprep('globalization', match_expr, replace_expr)

ans =

'g11n'

When parsed, a dynamic expression must correspond to a complete, valid regular expression. In
addition, dynamic match expressions that use the backslash escape character (\) require two
backslashes: one for the initial parsing of the expression, and one for the complete match. The
parentheses that enclose dynamic expressions do not create a capturing group.

There are three forms of dynamic expressions that you can use in match expressions, and one form
for replacement expressions, as described in the following sections

Dynamic Match Expressions — (??expr)

The (??expr) operator parses expression expr, and inserts the results back into the match
expression. MATLAB then evaluates the modified match expression.

Here is an example of the type of expression that you can use with this operator:
chr = {'5XXXXX', '8XXXXXXXX', '1X'};
regexp(chr, '^(\d+)(??X{$1})$', 'match', 'once');

The purpose of this particular command is to locate a series of X characters in each of the character
vectors stored in the input cell array. Note however that the number of Xs varies in each character
vector. If the count did not vary, you could use the expression X{n} to indicate that you want to match
n of these characters. But, a constant value of n does not work in this case.

The solution used here is to capture the leading count number (e.g., the 5 in the first character vector
of the cell array) in a token, and then to use that count in a dynamic expression. The dynamic
expression in this example is (??X{$1}), where $1 is the value captured by the token \d+. The
operator {$1} makes a quantifier of that token value. Because the expression is dynamic, the same
pattern works on all three of the input vectors in the cell array. With the first input character vector,
regexp looks for five X characters; with the second, it looks for eight, and with the third, it looks for
just one:
regexp(chr, '^(\d+)(??X{$1})$', 'match', 'once')

ans =

1×3 cell array

{'5XXXXX'} {'8XXXXXXXX'} {'1X'}

Commands That Modify the Match Expression — (??@cmd)

MATLAB uses the (??@cmd) operator to include the results of a MATLAB command in the match
expression. This command must return a term that can be used within the match expression.

For example, use the dynamic expression (??@flilplr($1)) to locate a palindrome, “Never Odd or
Even”, that has been embedded into a larger character vector.

2-73
2 Program Components

First, create the input string. Make sure that all letters are lowercase, and remove all nonword
characters.

chr = lower(...
'Find the palindrome Never Odd or Even in this string');

chr = regexprep(chr, '\W*', '')

chr =

'findthepalindromeneveroddoreveninthisstring'

Locate the palindrome within the character vector using the dynamic expression:

palindrome = regexp(chr, '(.{3,}).?(??@fliplr($1))', 'match')

palindrome =

1×1 cell array

{'neveroddoreven'}

The dynamic expression reverses the order of the letters that make up the character vector, and then
attempts to match as much of the reversed-order vector as possible. This requires a dynamic
expression because the value for $1 relies on the value of the token (.{3,}).

Dynamic expressions in MATLAB have access to the currently active workspace. This means that you
can change any of the functions or variables used in a dynamic expression just by changing variables
in the workspace. Repeat the last command of the example above, but this time define the function to
be called within the expression using a function handle stored in the base workspace:

fun = @fliplr;

palindrome = regexp(chr, '(.{3,}).?(??@fun($1))', 'match')

palindrome =

1×1 cell array

{'neveroddoreven'}

Commands That Serve a Functional Purpose — (?@cmd)

The (?@cmd) operator specifies a MATLAB command that regexp or regexprep is to run while
parsing the overall match expression. Unlike the other dynamic expressions in MATLAB, this operator
does not alter the contents of the expression it is used in. Instead, you can use this functionality to
get MATLAB to report just what steps it is taking as it parses the contents of one of your regular
expressions. This functionality can be useful in diagnosing your regular expressions.

The following example parses a word for zero or more characters followed by two identical
characters followed again by zero or more characters:

regexp('mississippi', '\w*(\w)\1\w*', 'match')

ans =

1×1 cell array

2-74
 Dynamic Regular Expressions

{'mississippi'}

To track the exact steps that MATLAB takes in determining the match, the example inserts a short
script (?@disp($1)) in the expression to display the characters that finally constitute the match.
Because the example uses greedy quantifiers, MATLAB attempts to match as much of the character
vector as possible. So, even though MATLAB finds a match toward the beginning of the string, it
continues to look for more matches until it arrives at the very end of the string. From there, it backs
up through the letters i then p and the next p, stopping at that point because the match is finally
satisfied:
regexp('mississippi', '\w*(\w)(?@disp($1))\1\w*', 'match')

i
p
p

ans =

1×1 cell array

{'mississippi'}

Now try the same example again, this time making the first quantifier lazy (*?). Again, MATLAB
makes the same match:
regexp('mississippi', '\w*?(\w)\1\w*', 'match')

ans =

1×1 cell array

{'mississippi'}

But by inserting a dynamic script, you can see that this time, MATLAB has matched the text quite
differently. In this case, MATLAB uses the very first match it can find, and does not even consider the
rest of the text:
regexp('mississippi', '\w*?(\w)(?@disp($1))\1\w*', 'match')

m
i
s

ans =

1×1 cell array

{'mississippi'}

To demonstrate how versatile this type of dynamic expression can be, consider the next example that
progressively assembles a cell array as MATLAB iteratively parses the input text. The (?!) operator
found at the end of the expression is actually an empty lookahead operator, and forces a failure at
each iteration. This forced failure is necessary if you want to trace the steps that MATLAB is taking to
resolve the expression.

MATLAB makes a number of passes through the input text, each time trying another combination of
letters to see if a fit better than last match can be found. On any passes in which no matches are

2-75
2 Program Components

found, the test results in an empty character vector. The dynamic script (?@if(~isempty($&)))
serves to omit the empty character vectors from the matches cell array:

matches = {};
expr = ['(Euler\s)?(Cauchy\s)?(Boole)?(?@if(~isempty($&)),' ...
'matches{end+1}=$&;end)(?!)'];

regexp('Euler Cauchy Boole', expr);

matches

matches =

1×6 cell array

{'Euler Cauchy Bo…'} {'Euler Cauchy '} {'Euler '} {'Cauchy Boole'} {'Cauchy '}

The operators $& (or the equivalent $0), $`, and $' refer to that part of the input text that is
currently a match, all characters that precede the current match, and all characters to follow the
current match, respectively. These operators are sometimes useful when working with dynamic
expressions, particularly those that employ the (?@cmd) operator.

This example parses the input text looking for the letter g. At each iteration through the text, regexp
compares the current character with g, and not finding it, advances to the next character. The
example tracks the progress of scan through the text by marking the current location being parsed
with a ^ character.

(The $` and $´ operators capture that part of the text that precedes and follows the current parsing
location. You need two single-quotation marks ($'') to express the sequence $´ when it appears
within text.)

chr = 'abcdefghij';
expr = '(?@disp(sprintf(''starting match: [%s^%s]'',$`,$'')))g';

regexp(chr, expr, 'once');

starting match: [^abcdefghij]

starting match: [a^bcdefghij]
starting match: [ab^cdefghij]
starting match: [abc^defghij]
starting match: [abcd^efghij]
starting match: [abcde^fghij]
starting match: [abcdef^ghij]

Commands in Replacement Expressions — ${cmd}

The ${cmd} operator modifies the contents of a regular expression replacement pattern, making this
pattern adaptable to parameters in the input text that might vary from one use to the next. As with
the other dynamic expressions used in MATLAB, you can include any number of these expressions
within the overall replacement expression.

In the regexprep call shown here, the replacement pattern is '${convertMe($1,$2)}'. In this
case, the entire replacement pattern is a dynamic expression:

regexprep('This highway is 125 miles long', ...

'(\d+\.?\d*)\W(\w+)', '${convertMe($1,$2)}');

2-76
 Dynamic Regular Expressions

The dynamic expression tells MATLAB to execute a function named convertMe using the two tokens
(\d+\.?\d*) and (\w+), derived from the text being matched, as input arguments in the call to
convertMe. The replacement pattern requires a dynamic expression because the values of $1 and $2
are generated at runtime.

The following example defines the file named convertMe that converts measurements from imperial
units to metric.
function valout = convertMe(valin, units)
switch(units)
case 'inches'
fun = @(in)in .* 2.54;
uout = 'centimeters';
case 'miles'
fun = @(mi)mi .* 1.6093;
uout = 'kilometers';
case 'pounds'
fun = @(lb)lb .* 0.4536;
uout = 'kilograms';
case 'pints'
fun = @(pt)pt .* 0.4731;
uout = 'litres';
case 'ounces'
fun = @(oz)oz .* 28.35;
uout = 'grams';
end
val = fun(str2num(valin));
valout = [num2str(val) ' ' uout];
end

At the command line, call the convertMe function from regexprep, passing in values for the
quantity to be converted and name of the imperial unit:
regexprep('This highway is 125 miles long', ...
'(\d+\.?\d*)\W(\w+)', '${convertMe($1,$2)}')

ans =

'This highway is 201.1625 kilometers long'

regexprep('This pitcher holds 2.5 pints of water', ...

'(\d+\.?\d*)\W(\w+)', '${convertMe($1,$2)}')

ans =

'This pitcher holds 1.1828 litres of water'

regexprep('This stone weighs about 10 pounds', ...

'(\d+\.?\d*)\W(\w+)', '${convertMe($1,$2)}')

ans =

'This stone weighs about 4.536 kilograms'

As with the (??@ ) operator discussed in an earlier section, the ${ } operator has access to
variables in the currently active workspace. The following regexprep command uses the array A
defined in the base workspace:
A = magic(3)

2-77
2 Program Components

A =

8 1 6
3 5 7
4 9 2

regexprep('The columns of matrix _nam are _val', ...

{'_nam', '_val'}, ...
{'A', '${sprintf(''%d%d%d '', A)}'})

ans =

'The columns of matrix A are 834 159 672'

See Also
regexp | regexpi | regexprep

More About
• “Regular Expressions” on page 2-51

2-78
 Comma-Separated Lists

Comma-Separated Lists
In this section...
“What Is a Comma-Separated List?” on page 2-79
“Generating a Comma-Separated List” on page 2-79
“Assigning Output from a Comma-Separated List” on page 2-81
“Assigning to a Comma-Separated List” on page 2-81
“How to Use the Comma-Separated Lists” on page 2-82
“Fast Fourier Transform Example” on page 2-84

What Is a Comma-Separated List?

Typing in a series of numbers separated by commas gives you what is called a comma-separated list.
The MATLAB software returns each value individually:
1,2,3

ans =

ans =

ans =

Such a list, by itself, is not very useful. But when used with large and more complex data structures
like MATLAB structures and cell arrays, the comma-separated list can enable you to simplify your
MATLAB code.

Generating a Comma-Separated List

This section describes how to generate a comma-separated list from either a cell array or a MATLAB
structure.

Generating a List from a Cell Array

Extracting multiple elements from a cell array yields a comma-separated list. Given a 4-by-6 cell array
as shown here
C = cell(4,6);
for k = 1:24
C{k} = k*2;
end
C

C =

2-79
2 Program Components

[2] [10] [18] [26] [34] [42]

[4] [12] [20] [28] [36] [44]
[6] [14] [22] [30] [38] [46]
[8] [16] [24] [32] [40] [48]

extracting the fifth column generates the following comma-separated list:

C{:,5}

ans =

34

ans =

36

ans =

38

ans =

40

This is the same as explicitly typing

C{1,5},C{2,5},C{3,5},C{4,5}

Generating a List from a Structure

For structures, extracting a field of the structure that exists across one of its dimensions yields a
comma-separated list.

Start by converting the cell array used above into a 4-by-1 MATLAB structure with six fields: f1
through f6. Read field f5 for all rows and MATLAB returns a comma-separated list:

S = cell2struct(C,{'f1','f2','f3','f4','f5','f6'},2);
S.f5

ans =

34

ans =

36

ans =

38

2-80
 Comma-Separated Lists

ans =

40

This is the same as explicitly typing

S(1).f5,S(2).f5,S(3).f5,S(4).f5

Assigning Output from a Comma-Separated List

You can assign any or all consecutive elements of a comma-separated list to variables with a simple
assignment statement. Using the cell array C from the previous section, assign the first row to
variables c1 through c6:

C = cell(4,6);
for k = 1:24
C{k} = k*2;
end
[c1,c2,c3,c4,c5,c6] = C{1,1:6};
c5

c5 =

34

If you specify fewer output variables than the number of outputs returned by the expression, MATLAB
assigns the first N outputs to those N variables, and then discards any remaining outputs. In this next
example, MATLAB assigns C{1,1:3} to the variables c1, c2, and c3, and then discards C{1,4:6}:

[c1,c2,c3] = C{1,1:6};

You can assign structure outputs in the same manner:

S = cell2struct(C,{'f1','f2','f3','f4','f5','f6'},2);
[sf1,sf2,sf3] = S.f5;
sf3

sf3 =

38

You also can use the deal function for this purpose.

Assigning to a Comma-Separated List

The simplest way to assign multiple values to a comma-separated list is to use the deal function. This
function distributes all of its input arguments to the elements of a comma-separated list.

This example uses deal to overwrite each element in a comma-separated list. First create a list.

c{1} = [31 07];

c{2} = [03 78];
c{:}

ans =

31 7

2-81
2 Program Components

ans =

3 78

Use deal to overwrite each element in the list.

[c{:}] = deal([10 20],[14 12]);

c{:}

ans =

10 20

ans =

14 12

This example does the same as the one above, but with a comma-separated list of vectors in a
structure field:

s(1).field1 = [31 07];

s(2).field1 = [03 78];
s.field1

ans =

31 7

ans =

3 78

Use deal to overwrite the structure fields.

[s.field1] = deal([10 20],[14 12]);

s.field1

ans =

10 20

ans =

14 12

How to Use the Comma-Separated Lists

Common uses for comma-separated lists are

• “Constructing Arrays” on page 2-83

• “Displaying Arrays” on page 2-83

2-82
 Comma-Separated Lists

• “Concatenation” on page 2-83

• “Function Call Arguments” on page 2-84
• “Function Return Values” on page 2-84

The following sections provide examples of using comma-separated lists with cell arrays. Each of
these examples applies to MATLAB structures as well.

Constructing Arrays

You can use a comma-separated list to enter a series of elements when constructing a matrix or array.
Note what happens when you insert a list of elements as opposed to adding the cell itself.

When you specify a list of elements with C{:, 5}, MATLAB inserts the four individual elements:
A = {'Hello',C{:,5},magic(4)}

A =

'Hello' [34] [36] [38] [40] [4x4 double]

When you specify the C cell itself, MATLAB inserts the entire cell array:
A = {'Hello',C,magic(4)}

A =

'Hello' {4x6 cell} [4x4 double]

Displaying Arrays

Use a list to display all or part of a structure or cell array:

A{:}

ans =

Hello

ans =

[2] [10] [18] [26] [34] [42]

[4] [12] [20] [28] [36] [44]
[6] [14] [22] [30] [38] [46]
[8] [16] [24] [32] [40] [48]

ans =

16 2 3 13
5 11 10 8
9 7 6 12
4 14 15 1

Concatenation

Putting a comma-separated list inside square brackets extracts the specified elements from the list
and concatenates them:

2-83
2 Program Components

A = [C{:,5:6}]

A =

34 36 38 40 42 44 46 48

Function Call Arguments

When writing the code for a function call, you enter the input arguments as a list with each argument
separated by a comma. If you have these arguments stored in a structure or cell array, then you can
generate all or part of the argument list from the structure or cell array instead. This can be
especially useful when passing in variable numbers of arguments.

This example passes several attribute-value arguments to the plot function:

X = -pi:pi/10:pi;
Y = tan(sin(X)) - sin(tan(X));
C = cell(2,3);
C{1,1} = 'LineWidth';
C{2,1} = 2;
C{1,2} = 'MarkerEdgeColor';
C{2,2} = 'k';
C{1,3} = 'MarkerFaceColor';
C{2,3} = 'g';
figure
plot(X,Y,'--rs',C{:})

Function Return Values

MATLAB functions can also return more than one value to the caller. These values are returned in a
list with each value separated by a comma. Instead of listing each return value, you can use a comma-
separated list with a structure or cell array. This becomes more useful for those functions that have
variable numbers of return values.

This example returns three values to a cell array:

C = cell(1,3);
[C{:}] = fileparts('work/mytests/strArrays.mat')

C =

'work/mytests' 'strArrays' '.mat'

Fast Fourier Transform Example

The fftshift function swaps the left and right halves of each dimension of an array. For a simple
vector such as [0 2 4 6 8 10] the output would be [6 8 10 0 2 4]. For a multidimensional
array, fftshift performs this swap along each dimension.

fftshift uses vectors of indices to perform the swap. For the vector shown above, the index [1 2
3 4 5 6] is rearranged to form a new index [4 5 6 1 2 3]. The function then uses this index
vector to reposition the elements. For a multidimensional array, fftshift must construct an index
vector for each dimension. A comma-separated list makes this task much simpler.

Here is the fftshift function:

2-84
 Comma-Separated Lists

function y = fftshift(x)
numDims = ndims(x);
idx = cell(1,numDims);
for k = 1:numDims
m = size(x,k);
p = ceil(m/2);
idx{k} = [p+1:m 1:p];
end
y = x(idx{:});
end

The function stores the index vectors in cell array idx. Building this cell array is relatively simple.
For each of the N dimensions, determine the size of that dimension and find the integer index nearest
the midpoint. Then, construct a vector that swaps the two halves of that dimension.

By using a cell array to store the index vectors and a comma-separated list for the indexing operation,
fftshift shifts arrays of any dimension using just a single operation: y = x(idx{:}). If you were
to use explicit indexing, you would need to write one if statement for each dimension you want the
function to handle:

if ndims(x) == 1
y = x(index1);
else if ndims(x) == 2
y = x(index1,index2);
end
end

Another way to handle this without a comma-separated list would be to loop over each dimension,
converting one dimension at a time and moving data each time. With a comma-separated list, you
move the data just once. A comma-separated list makes it very easy to generalize the swapping
operation to an arbitrary number of dimensions.

2-85
2 Program Components

Alternatives to the eval Function

In this section...
“Why Avoid the eval Function?” on page 2-86
“Variables with Sequential Names” on page 2-86
“Files with Sequential Names” on page 2-87
“Function Names in Variables” on page 2-87
“Field Names in Variables” on page 2-88
“Error Handling” on page 2-88

Why Avoid the eval Function?

Although the eval function is very powerful and flexible, it is not always the best solution to a
programming problem. Code that calls eval is often less efficient and more difficult to read and
debug than code that uses other functions or language constructs. For example:

• MATLAB compiles code the first time you run it to enhance performance for future runs. However,
because code in an eval statement can change at run time, it is not compiled.
• Code within an eval statement can unexpectedly create or assign to a variable already in the
current workspace, overwriting existing data.
• Concatenated character vectors within an eval statement are often difficult to read. Other
language constructs can simplify the syntax in your code.

For many common uses of eval, there are preferred alternate approaches, as shown in the following
examples.

Variables with Sequential Names

A frequent use of the eval function is to create sets of variables such as A1, A2, ..., An, but this
approach does not use the array processing power of MATLAB and is not recommended. The
preferred method is to store related data in a single array. If the data sets are of different types or
sizes, use a structure or cell array.

For example, create a cell array that contains 10 elements, where each element is a numeric array:

numArrays = 10;
A = cell(numArrays,1);
for n = 1:numArrays
A{n} = magic(n);
end

Access the data in the cell array by indexing with curly braces. For example, display the fifth element
of A:

A{5}

ans =
17 24 1 8 15
23 5 7 14 16
4 6 13 20 22

2-86
 Alternatives to the eval Function

10 12 19 21 3
11 18 25 2 9

The assignment statement A{n} = magic(n) is more elegant and efficient than this call to eval:
eval(['A', int2str(n),' = magic(n)']) % Not recommended

For more information, see:

• “Create Cell Array” on page 12-3

• “Create Structure Array” on page 11-2

Files with Sequential Names

Related data files often have a common root name with an integer index, such as myfile1.mat
through myfileN.mat. A common (but not recommended) use of the eval function is to construct
and pass each file name to a function using command syntax, such as
eval(['save myfile',int2str(n),'.mat']) % Not recommended

The best practice is to use function syntax, which allows you to pass variables as inputs. For example:
currentFile = 'myfile1.mat';
save(currentFile)

You can construct file names within a loop using the sprintf function (which is usually more
efficient than int2str), and then call the save function without eval. This code creates 10 files in
the current folder:
numFiles = 10;
for n = 1:numFiles
randomData = rand(n);
currentFile = sprintf('myfile%d.mat',n);
save(currentFile,'randomData')
end

For more information, see:

• “Command vs. Function Syntax” on page 1-6

• “Import or Export a Sequence of Files”

Function Names in Variables

A common use of eval is to execute a function when the name of the function is in a variable
character vector. There are two ways to evaluate functions from variables that are more efficient than
using eval:

• Create function handles with the @ symbol or with the str2func function. For example, run a
function from a list stored in a cell array:
examples = {@odedemo,@sunspots,@fitdemo};
n = input('Select an example (1, 2, or 3): ');
examples{n}()
• Use the feval function. For example, call a plot function (such as plot, bar, or pie) with data
that you specify at run time:

2-87
2 Program Components

plotFunction = input('Specify a plotting function: ','s');

data = input('Enter data to plot: ');
feval(plotFunction,data)

Field Names in Variables

Access data in a structure with a variable field name by enclosing the expression for the field in
parentheses. For example:

myData.height = [67, 72, 58];

myData.weight = [140, 205, 90];

fieldName = input('Select data (height or weight): ','s');

dataToUse = myData.(fieldName);

If you enter weight at the input prompt, then you can find the minimum weight value with the
following command.

min(dataToUse)

ans =
90

For an additional example, see “Generate Field Names from Variables” on page 11-11.

Error Handling
The preferred method for error handling in MATLAB is to use a try, catch statement. For example:

try
B = A;
catch exception
disp('A is undefined')
end

If your workspace does not contain variable A, then this code returns:

A is undefined

Previous versions of the documentation for the eval function include the syntax
eval(expression,catch_expr). If evaluating the expression input returns an error, then eval
evaluates catch_expr. However, an explicit try/catch is significantly clearer than an implicit
catch in an eval statement. Using the implicit catch is not recommended.

2-88
Classes (Data Types)

89
 3

Overview of MATLAB Classes

3 Overview of MATLAB Classes

Fundamental MATLAB Classes

There are many different data types, or classes, that you can work with in the MATLAB software. You
can build matrices and arrays of floating-point and integer data, characters and strings, and logical
true and false states. Function handles connect your code with any MATLAB function regardless of
the current scope. Tables, structures, and cell arrays provide a way to store dissimilar types of data in
the same container.

There are 16 fundamental classes in MATLAB. Each of these classes is in the form of a matrix or
array. With the exception of function handles, this matrix or array is a minimum of 0-by-0 in size and
can grow to an n-dimensional array of any size. A function handle is always scalar (1-by-1).

All of the fundamental MATLAB classes are shown in the diagram below:

Numeric classes in the MATLAB software include signed and unsigned integers, and single- and
double-precision floating-point numbers. By default, MATLAB stores all numeric values as double-
precision floating point. (You cannot change the default type and precision.) You can choose to store
any number, or array of numbers, as integers or as single-precision. Integer and single-precision
arrays offer more memory-efficient storage than double-precision.

All numeric types support basic array operations, such as subscripting, reshaping, and mathematical
operations.

You can create two-dimensional double and logical matrices using one of two storage formats:
full or sparse. For matrices with mostly zero-valued elements, a sparse matrix requires a fraction
of the storage space required for an equivalent full matrix. Sparse matrices invoke methods
especially tailored to solve sparse problems.

These classes require different amounts of storage, the smallest being a logical value or 8-bit
integer which requires only 1 byte. It is important to keep this minimum size in mind if you work on
data in files that were written using a precision smaller than 8 bits.

The following table describes the fundamental classes in more detail.

3-2
 Fundamental MATLAB Classes

Class Name Documentation Intended Use

double, single Floating-Point • Required for fractional numeric data.
Numbers on page 4- • Double on page 4-6 and Single on page 4-6 precision.
6
• Use realmin and realmax to show range of values on page 4-
9.
• Two-dimensional arrays can be sparse.
• Default numeric type in MATLAB.
int8, uint8, Integers on page 4- • Use for signed and unsigned whole numbers.
int16, uint16, 2 • More efficient use of memory. on page 30-2
int32, uint32,
int64, uint64 • Use intmin and intmax to show range of values on page 4-
4.
• Choose from 4 sizes (8, 16, 32, and 64 bits).
char, string “Characters and • Data type for text.
Strings” • Native or Unicode®.
• Converts to/from numeric.
• Use with regular expressions on page 2-51.
• For multiple character arrays, use cell arrays.
• Starting in R2016b, you also can store text in string arrays. For
more information, see string.
logical “Logical Operations” • Use in relational conditions or to test state.
• Can have one of two values: true or false.
• Also useful in array indexing.
• Two-dimensional arrays can be sparse.
function_handle “Function Handles” • Pointer to a function.
• Enables passing a function to another function
• Can also call functions outside usual scope.
• Use to specify graphics callback functions.
• Save to MAT-file and restore later.
table, timetable “Tables”, • Tables are rectangular containers for mixed-type, column-
“Timetables” oriented data.
• Tables have row and variable names identify contents.
• Timetables also provide storage for data in a table with rows
labeled by time. Timetable functions can synchronize, resample,
or aggregate timestamped data.
• Use the properties of a table or timetable to store metadata
such as variable units.
• Manipulation of elements similar to numeric or logical arrays.
• Access data by numeric or named index.
• Can select a subset of data and preserve the table container or
can extract the data from a table.

3-3
3 Overview of MATLAB Classes

Class Name Documentation Intended Use

struct “Structures” • Fields store arrays of varying classes and sizes.
• Access one or all fields/indices in single operation.
• Field names identify contents.
• Method of passing function arguments.
• Use in comma-separated lists on page 2-79.
• More memory required for overhead
cell “Cell Arrays” • Cells store arrays of varying classes and sizes.
• Allows freedom to package data as you want.
• Manipulation of elements is similar to numeric or logical arrays.
• Method of passing function arguments.
• Use in comma-separated lists.
• More memory required for overhead

See Also

More About
• “Valid Combinations of Unlike Classes” on page 15-2

3-4
 4

Numeric Classes

• “Integers” on page 4-2

• “Floating-Point Numbers” on page 4-6
• “Create Complex Numbers” on page 4-13
• “Infinity and NaN” on page 4-14
• “Identifying Numeric Classes” on page 4-16
• “Display Format for Numeric Values” on page 4-17
• “Integer Arithmetic” on page 4-19
• “Single Precision Math” on page 4-26
4 Numeric Classes

Integers
In this section...
“Integer Classes” on page 4-2
“Creating Integer Data” on page 4-2
“Arithmetic Operations on Integer Classes” on page 4-4
“Largest and Smallest Values for Integer Classes” on page 4-4

Integer Classes
MATLAB has four signed and four unsigned integer classes. Signed types enable you to work with
negative integers as well as positive, but cannot represent as wide a range of numbers as the
unsigned types because one bit is used to designate a positive or negative sign for the number.
Unsigned types give you a wider range of numbers, but these numbers can only be zero or positive.

MATLAB supports 1-, 2-, 4-, and 8-byte storage for integer data. You can save memory and execution
time for your programs if you use the smallest integer type that accommodates your data. For
example, you do not need a 32-bit integer to store the value 100.

Here are the eight integer classes, the range of values you can store with each type, and the MATLAB
conversion function required to create that type:

Class Range of Values Conversion Function

7 7
Signed 8-bit integer -2 to 2 -1 int8
15 15
Signed 16-bit integer -2 to 2 -1 int16
31 31
Signed 32-bit integer -2 to 2 -1 int32
Signed 64-bit integer -263 to 263-1 int64
Unsigned 8-bit integer 0 to 28-1 uint8
16
Unsigned 16-bit integer 0 to 2 -1 uint16
32
Unsigned 32-bit integer 0 to 2 -1 uint32
64
Unsigned 64-bit integer 0 to 2 -1 uint64

Creating Integer Data

MATLAB stores numeric data as double-precision floating point (double) by default. To store data as
an integer, you need to convert from double to the desired integer type. Use one of the conversion
functions shown in the table above.

For example, to store 325 as a 16-bit signed integer assigned to variable x, type
x = int16(325);

If the number being converted to an integer has a fractional part, MATLAB rounds to the nearest
integer. If the fractional part is exactly 0.5, then from the two equally nearby integers, MATLAB
chooses the one for which the absolute value is larger in magnitude:
x = 325.499;
int16(x)

4-2
 Integers

ans =

int16

325

x = x + .001;
int16(x)
ans =

int16

326

If you need to round a number using a rounding scheme other than the default, MATLAB provides
four rounding functions: round, fix, floor, and ceil. The fix function enables you to override the
default and round towards zero when there is a nonzero fractional part:
x = 325.9;

int16(fix(x))
ans =

int16

325

Arithmetic operations that involve both integers and floating-point always result in an integer data
type. MATLAB rounds the result, when necessary, according to the default rounding algorithm. The
example below yields an exact answer of 1426.75 which MATLAB then rounds to the next highest
integer:
int16(325) * 4.39
ans =

int16

1427

The integer conversion functions are also useful when converting other classes, such as strings, to
integers:
str = 'Hello World';

int8(str)
ans =

1×11 int8 row vector

72 101 108 108 111 32 87 111 114 108 100

If you convert a NaN value into an integer class, the result is a value of 0 in that integer class. For
example,
int32(NaN)
ans =

int32

4-3
4 Numeric Classes

Arithmetic Operations on Integer Classes

MATLAB can perform integer arithmetic on the following types of data:

• Integers or integer arrays of the same integer data type. This yields a result that has the same
data type as the operands:

x = uint32([132 347 528]) .* uint32(75);

class(x)
ans =
uint32
• Integers or integer arrays and scalar double-precision floating-point numbers. This yields a result
that has the same data type as the integer operands:

x = uint32([132 347 528]) .* 75.49;

class(x)
ans =
uint32

For all binary operations in which one operand is an array of integer data type (except 64-bit
integers) and the other is a scalar double, MATLAB computes the operation using element-wise
double-precision arithmetic, and then converts the result back to the original integer data type. For
binary operations involving a 64-bit integer array and a scalar double, MATLAB computes the
operation as if 80-bit extended-precision arithmetic were used, to prevent loss of precision.

Operations involving complex numbers with integer types is not supported.

Largest and Smallest Values for Integer Classes

For each integer data type, there is a largest and smallest number that you can represent with that
type. The table shown under “Integers” on page 4-2 lists the largest and smallest values for each
integer data type in the “Range of Values” column.

You can also obtain these values with the intmax and intmin functions:

intmax('int8')
ans =

int8

127

intmin('int8')
ans =

int8

-128

If you convert a number that is larger than the maximum value of an integer data type to that type,
MATLAB sets it to the maximum value. Similarly, if you convert a number that is smaller than the
minimum value of the integer data type, MATLAB sets it to the minimum value. For example,

4-4
 Integers

x = int8(300)
x =

int8

127

x = int8(-300)
x =

int8

-128

Also, when the result of an arithmetic operation involving integers exceeds the maximum (or
minimum) value of the data type, MATLAB sets it to the maximum (or minimum) value:

x = int8(100) * 3
x =

int8

127

x = int8(-100) * 3
x =

int8

-128

4-5
4 Numeric Classes

Floating-Point Numbers
In this section...
“Double-Precision Floating Point” on page 4-6
“Single-Precision Floating Point” on page 4-6
“Creating Floating-Point Data” on page 4-6
“Arithmetic Operations on Floating-Point Numbers” on page 4-8
“Largest and Smallest Values for Floating-Point Classes” on page 4-9
“Accuracy of Floating-Point Data” on page 4-10
“Avoiding Common Problems with Floating-Point Arithmetic” on page 4-11

MATLAB represents floating-point numbers in either double-precision or single-precision format. The

default is double precision, but you can make any number single precision with a simple conversion
function.

Double-Precision Floating Point

MATLAB constructs the double-precision (or double) data type according to IEEE® Standard 754 for
double precision. Any value stored as a double requires 64 bits, formatted as shown in the table
below:

Bits Usage
63 Sign (0 = positive, 1 = negative)
62 to 52 Exponent, biased by 1023
51 to 0 Fraction f of the number 1.f

Single-Precision Floating Point

MATLAB constructs the single-precision (or single) data type according to IEEE Standard 754 for
single precision. Any value stored as a single requires 32 bits, formatted as shown in the table
below:

Bits Usage
31 Sign (0 = positive, 1 = negative)
30 to 23 Exponent, biased by 127
22 to 0 Fraction f of the number 1.f

Because MATLAB stores numbers of type single using 32 bits, they require less memory than
numbers of type double, which use 64 bits. However, because they are stored with fewer bits,
numbers of type single are represented to less precision than numbers of type double.

Creating Floating-Point Data

Use double-precision to store values greater than approximately 3.4 x 1038 or less than approximately
-3.4 x 1038. For numbers that lie between these two limits, you can use either double- or single-
precision, but single requires less memory.

4-6
 Floating-Point Numbers

Creating Double-Precision Data

Because the default numeric type for MATLAB is double, you can create a double with a simple
assignment statement:
x = 25.783;

The whos function shows that MATLAB has created a 1-by-1 array of type double for the value you
just stored in x:
whos x
Name Size Bytes Class

x 1x1 8 double

Use isfloat if you just want to verify that x is a floating-point number. This function returns logical
1 (true) if the input is a floating-point number, and logical 0 (false) otherwise:
isfloat(x)
ans =

logical

You can convert other numeric data, characters or strings, and logical data to double precision using
the MATLAB function, double. This example converts a signed integer to double-precision floating
point:
y = int64(-589324077574); % Create a 64-bit integer

x = double(y) % Convert to double

x =
-5.8932e+11

Creating Single-Precision Data

Because MATLAB stores numeric data as a double by default, you need to use the single
conversion function to create a single-precision number:
x = single(25.783);

The whos function returns the attributes of variable x in a structure. The bytes field of this structure
shows that when x is stored as a single, it requires just 4 bytes compared with the 8 bytes to store it
as a double:
xAttrib = whos('x');
xAttrib.bytes
ans =
4

You can convert other numeric data, characters or strings, and logical data to single precision using
the single function. This example converts a signed integer to single-precision floating point:
y = int64(-589324077574); % Create a 64-bit integer

x = single(y) % Convert to single

x =

4-7
4 Numeric Classes

single

-5.8932e+11

Arithmetic Operations on Floating-Point Numbers

This section describes which classes you can use in arithmetic operations with floating-point
numbers.

Double-Precision Operations

You can perform basic arithmetic operations with double and any of the following other classes.
When one or more operands is an integer (scalar or array), the double operand must be a scalar. The
result is of type double, except where noted otherwise:

• single — The result is of type single

• double
• int* or uint* — The result has the same data type as the integer operand
• char
• logical

This example performs arithmetic on data of types char and double. The result is of type double:

c = 'uppercase' - 32;

class(c)
ans =
double

char(c)
ans =
UPPERCASE

Single-Precision Operations

You can perform basic arithmetic operations with single and any of the following other classes. The
result is always single:

• single
• double
• char
• logical

In this example, 7.5 defaults to type double, and the result is of type single:

x = single([1.32 3.47 5.28]) .* 7.5;

class(x)
ans =
single

4-8
 Floating-Point Numbers

Largest and Smallest Values for Floating-Point Classes

For the double and single classes, there is a largest and smallest number that you can represent
with that type.

Largest and Smallest Double-Precision Values

The MATLAB functions realmax and realmin return the maximum and minimum values that you
can represent with the double data type:

str = 'The range for double is:\n\t%g to %g and\n\t %g to %g';

sprintf(str, -realmax, -realmin, realmin, realmax)

ans =
The range for double is:
-1.79769e+308 to -2.22507e-308 and
2.22507e-308 to 1.79769e+308

Numbers larger than realmax or smaller than -realmax are assigned the values of positive and
negative infinity, respectively:

realmax + .0001e+308
ans =
Inf

-realmax - .0001e+308
ans =
-Inf

Largest and Smallest Single-Precision Values

The MATLAB functions realmax and realmin, when called with the argument 'single', return the
maximum and minimum values that you can represent with the single data type:

str = 'The range for single is:\n\t%g to %g and\n\t %g to %g';

sprintf(str, -realmax('single'), -realmin('single'), ...
realmin('single'), realmax('single'))

ans =
The range for single is:
-3.40282e+38 to -1.17549e-38 and
1.17549e-38 to 3.40282e+38

Numbers larger than realmax('single') or smaller than -realmax('single') are assigned the
values of positive and negative infinity, respectively:

realmax('single') + .0001e+038
ans =

single

Inf

-realmax('single') - .0001e+038
ans =

single

4-9
4 Numeric Classes

-Inf

Accuracy of Floating-Point Data

If the result of a floating-point arithmetic computation is not as precise as you had expected, it is
likely caused by the limitations of your computer's hardware. Probably, your result was a little less
exact because the hardware had insufficient bits to represent the result with perfect accuracy;
therefore, it truncated the resulting value.

Double-Precision Accuracy

Because there are only a finite number of double-precision numbers, you cannot represent all
numbers in double-precision storage. On any computer, there is a small gap between each double-
precision number and the next larger double-precision number. You can determine the size of this
gap, which limits the precision of your results, using the eps function. For example, to find the
distance between 5 and the next larger double-precision number, enter

format long

eps(5)
ans =
8.881784197001252e-16

This tells you that there are no double-precision numbers between 5 and 5 + eps(5). If a double-
precision computation returns the answer 5, the result is only accurate to within eps(5).

The value of eps(x) depends on x. This example shows that, as x gets larger, so does eps(x):

eps(50)
ans =
7.105427357601002e-15

If you enter eps with no input argument, MATLAB returns the value of eps(1), the distance from 1
to the next larger double-precision number.

Single-Precision Accuracy

Similarly, there are gaps between any two single-precision numbers. If x has type single, eps(x)
returns the distance between x and the next larger single-precision number. For example,

x = single(5);
eps(x)

returns

ans =

single

4.7684e-07

Note that this result is larger than eps(5). Because there are fewer single-precision numbers than
double-precision numbers, the gaps between the single-precision numbers are larger than the gaps
between double-precision numbers. This means that results in single-precision arithmetic are less
precise than in double-precision arithmetic.

4-10
 Floating-Point Numbers

For a number x of type double, eps(single(x)) gives you an upper bound for the amount that x is
rounded when you convert it from double to single. For example, when you convert the double-
precision number 3.14 to single, it is rounded by
double(single(3.14) - 3.14)
ans =
1.0490e-07

The amount that 3.14 is rounded is less than

eps(single(3.14))
ans =

single

2.3842e-07

Avoiding Common Problems with Floating-Point Arithmetic

Almost all operations in MATLAB are performed in double-precision arithmetic conforming to the
IEEE standard 754. Because computers only represent numbers to a finite precision (double precision
calls for 52 mantissa bits), computations sometimes yield mathematically nonintuitive results. It is
important to note that these results are not bugs in MATLAB.

Use the following examples to help you identify these cases:

Example 1 — Round-Off or What You Get Is Not What You Expect

The decimal number 4/3 is not exactly representable as a binary fraction. For this reason, the
following calculation does not give zero, but rather reveals the quantity eps.
e = 1 - 3*(4/3 - 1)

e =
2.2204e-16

Similarly, 0.1 is not exactly representable as a binary number. Thus, you get the following
nonintuitive behavior:
a = 0.0;
for i = 1:10
a = a + 0.1;
end
a == 1
ans =

logical

Note that the order of operations can matter in the computation:

b = 1e-16 + 1 - 1e-16;
c = 1e-16 - 1e-16 + 1;
b == c
ans =

4-11
4 Numeric Classes

logical

There are gaps between floating-point numbers. As the numbers get larger, so do the gaps, as
evidenced by:

(2^53 + 1) - 2^53

ans =
0

Since pi is not really π, it is not surprising that sin(pi) is not exactly zero:

sin(pi)

ans =
1.224646799147353e-16

Example 2 — Catastrophic Cancellation

When subtractions are performed with nearly equal operands, sometimes cancellation can occur
unexpectedly. The following is an example of a cancellation caused by swamping (loss of precision
that makes the addition insignificant).

sqrt(1e-16 + 1) - 1

ans =
0

Some functions in MATLAB, such as expm1 and log1p, may be used to compensate for the effects of
catastrophic cancellation.

Example 3 — Floating-Point Operations and Linear Algebra

Round-off, cancellation, and other traits of floating-point arithmetic combine to produce startling
computations when solving the problems of linear algebra. MATLAB warns that the following matrix A
is ill-conditioned, and therefore the system Ax = b may be sensitive to small perturbations:

A = diag([2 eps]);
b = [2; eps];
y = A\b;
Warning: Matrix is close to singular or badly scaled.
Results may be inaccurate. RCOND = 1.110223e-16.

These are only a few of the examples showing how IEEE floating-point arithmetic affects
computations in MATLAB. Note that all computations performed in IEEE 754 arithmetic are affected,
this includes applications written in C or FORTRAN, as well as MATLAB.

References
[1] Moler, Cleve. “Floating Points.” MATLAB News and Notes. Fall, 1996.

[2] Moler, Cleve. Numerical Computing with MATLAB. Natick, MA: The MathWorks, Inc., 2004.

4-12
 Create Complex Numbers

Create Complex Numbers

Complex numbers consist of two separate parts: a real part and an imaginary part. The basic
imaginary unit is equal to the square root of -1. This is represented in MATLAB by either of two
letters: i or j.

The following statement shows one way of creating a complex value in MATLAB. The variable x is
assigned a complex number with a real part of 2 and an imaginary part of 3:

x = 2 + 3i;

Another way to create a complex number is using the complex function. This function combines two
numeric inputs into a complex output, making the first input real and the second imaginary:

x = rand(3) * 5;
y = rand(3) * -8;

z = complex(x, y)
z =
4.7842 -1.0921i 0.8648 -1.5931i 1.2616 -2.2753i
2.6130 -0.0941i 4.8987 -2.3898i 4.3787 -3.7538i
4.4007 -7.1512i 1.3572 -5.2915i 3.6865 -0.5182i

You can separate a complex number into its real and imaginary parts using the real and imag
functions:

zr = real(z)
zr =
4.7842 0.8648 1.2616
2.6130 4.8987 4.3787
4.4007 1.3572 3.6865

zi = imag(z)
zi =
-1.0921 -1.5931 -2.2753
-0.0941 -2.3898 -3.7538
-7.1512 -5.2915 -0.5182

4-13
4 Numeric Classes

Infinity and NaN

In this section...
“Infinity” on page 4-14
“NaN” on page 4-14

Infinity
MATLAB represents infinity by the special value inf. Infinity results from operations like division by
zero and overflow, which lead to results too large to represent as conventional floating-point values.
MATLAB also provides a function called inf that returns the IEEE arithmetic representation for
positive infinity as a double scalar value.

Several examples of statements that return positive or negative infinity in MATLAB are shown here.

x = 1/0 x = 1.e1000
x = x =
Inf Inf
x = exp(1000) x = log(0)
x = x =
Inf -Inf

Use the isinf function to verify that x is positive or negative infinity:

x = log(0);

isinf(x)
ans =
1

NaN
MATLAB represents values that are not real or complex numbers with a special value called NaN,
which stands for “Not a Number”. Expressions like 0/0 and inf/inf result in NaN, as do any
arithmetic operations involving a NaN:

x = 0/0
x =

NaN

You can also create NaNs by:

x = NaN;

whos x
Name Size Bytes Class

x 1x1 8 double

The NaN function returns one of the IEEE arithmetic representations for NaN as a double scalar
value. The exact bit-wise hexadecimal representation of this NaN value is,

4-14
 Infinity and NaN

format hex
x = NaN

x =

fff8000000000000

Always use the isnan function to verify that the elements in an array are NaN:

isnan(x)
ans =

MATLAB preserves the “Not a Number” status of alternate NaN representations and treats all of the
different representations of NaN equivalently. However, in some special cases (perhaps due to
hardware limitations), MATLAB does not preserve the exact bit pattern of alternate NaN
representations throughout an entire calculation, and instead uses the canonical NaN bit pattern
defined above.

Logical Operations on NaN

Because two NaNs are not equal to each other, logical operations involving NaN always return false,
except for a test for inequality, (NaN ~= NaN):

NaN > NaN

ans =
0

NaN ~= NaN
ans =
1

4-15
4 Numeric Classes

Identifying Numeric Classes

You can check the data type of a variable x using any of these commands.

Command Operation
whos x Display the data type of x.
xType = class(x); Assign the data type of x to a variable.
isnumeric(x) Determine if x is a numeric type.
isa(x, 'integer') Determine if x is the specified numeric type. (Examples for any
isa(x, 'uint64') integer, unsigned 64-bit integer, any floating point, double precision,
isa(x, 'float') and single precision are shown here).
isa(x, 'double')
isa(x, 'single')
isreal(x) Determine if x is real or complex.
isnan(x) Determine if x is Not a Number (NaN).
isinf(x) Determine if x is infinite.
isfinite(x) Determine if x is finite.

4-16
 Display Format for Numeric Values

Display Format for Numeric Values

By default, MATLAB uses a 5-digit short format to display numbers. For example,

x = 4/3

x =

1.3333

You can change the display in the Command Window or Editor using the format function.

format long
x

x =

1.333333333333333

Using the format function only sets the format for the current MATLAB session. To set the format for
subsequent sessions, click Preferences on the Home tab in the Environment section. Select
MATLAB > Command Window, and then choose a Numeric format option.

The following table summarizes the numeric output format options.

Style Result Example

short Short, fixed-decimal format with 4 digits after the 3.1416
(default) decimal point.
long Long, fixed-decimal format with 15 digits after the 3.141592653589793
decimal point for double values, and 7 digits after
the decimal point for single values.
shortE Short scientific notation with 4 digits after the 3.1416e+00
decimal point.
longE Long scientific notation with 15 digits after the 3.141592653589793e+00
decimal point for double values, and 7 digits after
the decimal point for single values.
shortG Short, fixed-decimal format or scientific notation, 3.1416
whichever is more compact, with a total of 5
digits.
longG Long, fixed-decimal format or scientific notation, 3.14159265358979
whichever is more compact, with a total of 15
digits for double values, and 7 digits for single
values.
shortEng Short engineering notation (exponent is a multiple 3.1416e+000
of 3) with 4 digits after the decimal point.
longEng Long engineering notation (exponent is a multiple 3.14159265358979e+000
of 3) with 15 significant digits.
+ Positive/Negative format with +, -, and blank +
characters displayed for positive, negative, and
zero elements.

4-17
4 Numeric Classes

Style Result Example

bank Currency format with 2 digits after the decimal 3.14
point.
hex Hexadecimal representation of a binary double- 400921fb54442d18
precision number.
rat Ratio of small integers. 355/113

The display format only affects how numbers are displayed, not how they are stored in MATLAB.

See Also
format

Related Examples
• “Format Output”

4-18
 Integer Arithmetic

Integer Arithmetic
This example shows how to perform arithmetic on integer data representing signals and images.

Load Integer Signal Data

Load measurement datasets comprising signals from four instruments using 8 and 16-bit A-to-D's
resulting in data saved as int8, int16 and uint16. Time is stored as uint16.

load integersignal

% Look at variables
whos Signal1 Signal2 Signal3 Signal4 Time1

Name Size Bytes Class Attributes

Signal1 7550x1 7550 int8

Signal2 7550x1 7550 int8
Signal3 7550x1 15100 int16
Signal4 7550x1 15100 uint16
Time1 7550x1 15100 uint16

Plot Data

First we will plot two of the signals to see the signal ranges.

plot(Time1, Signal1, Time1, Signal2);

grid;
legend('Signal1','Signal2');

4-19
4 Numeric Classes

Here we see the values for int8. It is likely that these values would need to be scaled to calculate the
actual physical value that the signal represents e.g. Volts.

Process Data

We can perform standard arithmetic on integers such as +, -, *, and /. Let's say we wished to find the
sum of Signal1 and Signal2.

SumSig = Signal1 + Signal2; % Here we sum the integer signals.

Now let's plot the sum signal and see where it saturates.

cla;
plot(Time1, SumSig);
hold on
Saturated = (SumSig == intmin('int8')) | (SumSig == intmax('int8')); % Find where it has saturate
plot(Time1(Saturated),SumSig(Saturated),'rd')
grid
hold off

4-20
 Integer Arithmetic

The markers show where the signal has saturated.

Load Integer Image Data

Next we will look at arithmetic on some image data.

street1 = imread('street1.jpg'); % Load image data

street2 = imread('street2.jpg');
whos street1 street2

Name Size Bytes Class Attributes

street1 480x640x3 921600 uint8

street2 480x640x3 921600 uint8

Here we see the images are 24-bit color, stored as three planes of uint8 data.

Display Images

Display first image.

cla;
image(street1); % Display image
axis equal
axis off

4-21
4 Numeric Classes

Display second image

image(street2); % Display image

axis equal
axis off

4-22
 Integer Arithmetic

Scale an Image

We can scale the image by a double precision constant but keep the image stored as integers. For
example,

duller = 0.5 * street2; % Scale image with a double constant but create an integer
whos duller

Name Size Bytes Class Attributes

duller 480x640x3 921600 uint8

subplot(1,2,1);
image(street2);
axis off equal tight
title('Original'); % Display image

subplot(1,2,2);
image(duller);
axis off equal tight
title('Duller'); % Display image

4-23
4 Numeric Classes

Add the Images

We can add the two street images together and plot the ghostly result.

combined = street1 + duller; % Add |uint8| images

subplot(1,1,1)
cla;
image(combined); % Display image
title('Combined');
axis equal
axis off

4-24
Integer Arithmetic

4-25
4 Numeric Classes

Single Precision Math

This example shows how to perform arithmetic and linear algebra with single precision data. It also
shows how the results are computed appropriately in single-precision or double-precision, depending
on the input.

Create Double Precision Data

Let's first create some data, which is double precision by default.

Ad = [1 2 0; 2 5 -1; 4 10 -1]

Ad = 3×3

1 2 0
2 5 -1
4 10 -1

Convert to Single Precision

We can convert data to single precision with the single function.

A = single(Ad); % or A = cast(Ad,'single');

Create Single Precision Zeros and Ones

We can also create single precision zeros and ones with their respective functions.

n = 1000;
Z = zeros(n,1,'single');
O = ones(n,1,'single');

Let's look at the variables in the workspace.

whos A Ad O Z n

Name Size Bytes Class Attributes

A 3x3 36 single
Ad 3x3 72 double
O 1000x1 4000 single
Z 1000x1 4000 single
n 1x1 8 double

We can see that some of the variables are of type single and that the variable A (the single precision
version of Ad) takes half the number of bytes of memory to store because singles require just four
bytes (32-bits), whereas doubles require 8 bytes (64-bits).

Arithmetic and Linear Algebra

We can perform standard arithmetic and linear algebra on singles.

B = A' % Matrix Transpose

B = 3x3 single matrix

1 2 4

4-26
 Single Precision Math

2 5 10
0 -1 -1

whos B

Name Size Bytes Class Attributes

B 3x3 36 single

We see the result of this operation, B, is a single.

C = A * B % Matrix multiplication

C = 3x3 single matrix

5 12 24
12 30 59
24 59 117

C = A .* B % Elementwise arithmetic

C = 3x3 single matrix

1 4 0
4 25 -10
0 -10 1

X = inv(A) % Matrix inverse

X = 3x3 single matrix

5 2 -2
-2 -1 1
0 -2 1

I = inv(A) * A % Confirm result is identity matrix

I = 3x3 single matrix

1 0 0
0 1 0
0 0 1

I = A \ A % Better way to do matrix division than inv

I = 3x3 single matrix

1 0 0
0 1 0
0 0 1

E = eig(A) % Eigenvalues

E = 3x1 single column vector

4-27
4 Numeric Classes

3.7321
0.2679
1.0000

F = fft(A(:,1)) % FFT

F = 3x1 single column vector

7.0000 + 0.0000i
-2.0000 + 1.7321i
-2.0000 - 1.7321i

S = svd(A) % Singular value decomposition

S = 3x1 single column vector

12.3171
0.5149
0.1577

P = round(poly(A)) % The characteristic polynomial of a matrix

P = 1x4 single row vector

1 -5 5 -1

R = roots(P) % Roots of a polynomial

R = 3x1 single column vector

3.7321
1.0000
0.2679

Q = conv(P,P) % Convolve two vectors

Q = 1x7 single row vector

1 -10 35 -52 35 -10 1

R = conv(P,Q)

R = 1x10 single row vector

1 -15 90 -278 480 -480 278 -90 15 -1

stem(R); % Plot the result

4-28
 Single Precision Math

A Program that Works for Either Single or Double Precision

Now let's look at a function to compute enough terms in the Fibonacci sequence so the ratio is less
than the correct machine epsilon (eps) for datatype single or double.

% How many terms needed to get single precision results?

fibodemo('single')

ans = 19

% How many terms needed to get double precision results?

fibodemo('double')

ans = 41

% Now let's look at the working code.

type fibodemo

function nterms = fibodemo(dtype)

%FIBODEMO Used by SINGLEMATH demo.
% Calculate number of terms in Fibonacci sequence.

% Copyright 1984-2014 The MathWorks, Inc.

fcurrent = ones(dtype);
fnext = fcurrent;

4-29
4 Numeric Classes

goldenMean = (ones(dtype)+sqrt(5))/2;
tol = eps(goldenMean);
nterms = 2;
while abs(fnext/fcurrent - goldenMean) >= tol
nterms = nterms + 1;
temp = fnext;
fnext = fnext + fcurrent;
fcurrent = temp;
end

Notice that we initialize several of our variables, fcurrent, fnext, and goldenMean, with values
that are dependent on the input datatype, and the tolerance tol depends on that type as well. Single
precision requires that we calculate fewer terms than the equivalent double precision calculation.

4-30
 5

The Logical Class

• “Find Array Elements That Meet a Condition” on page 5-2

• “Reduce Logical Arrays to Single Value” on page 5-6
5 The Logical Class

Find Array Elements That Meet a Condition

This example shows how to filter the elements of an array by applying conditions to the array. For
instance, you can examine the even elements in a matrix, find the location of all 0s in a
multidimensional array, or replace NaN values in data. You can perform these tasks using a
combination of the relational and logical operators. The relational operators (>, <, >=, <=, ==, ~=)
impose conditions on the array, and you can apply multiple conditions by connecting them with the
logical operators and, or, and not, respectively denoted by the symbols &, |, and ~.

Apply a Single Condition

To apply a single condition, start by creating a 5-by-5 matrix that contains random integers between 1
and 15. Reset the random number generator to the default state for reproducibility.

rng default
A = randi(15,5)

A = 5×5

13 2 3 3 10
14 5 15 7 1
2 9 15 14 13
14 15 8 12 15
10 15 13 15 11

Use the relational less than operator, <, to determine which elements of A are less than 9. Store the
result in B.

B = A < 9

B = 5x5 logical array

0 1 1 1 0
0 1 0 1 1
1 0 0 0 0
0 0 1 0 0
0 0 0 0 0

The result is a logical matrix. Each value in B represents a logical 1 (true) or logical 0 (false) state
to indicate whether the corresponding element of A fulfills the condition A < 9. For example, A(1,1)
is 13, so B(1,1) is logical 0 (false). However, A(1,2) is 2, so B(1,2) is logical 1 (true).

Although B contains information about which elements in A are less than 9, it doesn’t tell you what
their values are. Rather than comparing the two matrices element by element, you can use B to index
into A.

A(B)

ans = 8×1

2
2
5
3
8

5-2
 Find Array Elements That Meet a Condition

3
7
1

The result is a column vector of the elements in A that are less than 9. Since B is a logical matrix, this
operation is called logical indexing. In this case, the logical array being used as an index is the
same size as the other array, but this is not a requirement. For more information, see “Array
Indexing”.

Some problems require information about the locations of the array elements that meet a condition
rather than their actual values. In this example, you can use the find function to locate all of the
elements in A less than 9.

I = find(A < 9)

I = 8×1

3
6
7
11
14
16
17
22

The result is a column vector of linear indices. Each index describes the location of an element in A
that is less than 9, so in practice A(I) returns the same result as A(B). The difference is that A(B)
uses logical indexing, whereas A(I) uses linear indexing.

Apply Multiple Conditions

You can use the logical and, or, and not operators to apply any number of conditions to an array; the
number of conditions is not limited to one or two.

First, use the logical and operator, denoted &, to specify two conditions: the elements must be less
than 9 and greater than 2. Specify the conditions as a logical index to view the elements that
satisfy both conditions.

A(A<9 & A>2)

ans = 5×1

5
3
8
3
7

The result is a list of the elements in A that satisfy both conditions. Be sure to specify each condition
with a separate statement connected by a logical operator. For example, you cannot specify the
conditions above by A(2<A<9), since it evaluates to A(2<A | A<9).

Next, find the elements in A that are less than 9 and even numbered.

5-3
5 The Logical Class

A(A<9 & ~mod(A,2))

ans = 3×1

2
2
8

The result is a list of all even elements in A that are less than 9. The use of the logical NOT operator,
~, converts the matrix mod(A,2) into a logical matrix, with a value of logical 1 (true) located where
an element is evenly divisible by 2.

Finally, find the elements in A that are less than 9 and even numbered and not equal to 2.
A(A<9 & ~mod(A,2) & A~=2)

ans = 8

The result, 8, is even, less than 9, and not equal to 2. It is the only element in A that satisfies all three
conditions.

Use the find function to get the index of the element equal to 8 that satisfies the conditions.
find(A<9 & ~mod(A,2) & A~=2)

ans = 14

The result indicates that A(14) = 8.

Replace Values That Meet a Condition

Sometimes it is useful to simultaneously change the values of several existing array elements. Use
logical indexing with a simple assignment statement to replace the values in an array that meet a
condition.

Replace all values in A that are greater than 10 with the number 10.
A(A>10) = 10

A = 5×5

10 2 3 3 10
10 5 10 7 1
2 9 10 10 10
10 10 8 10 10
10 10 10 10 10

Next, replace all values in A that are not equal to 10 with a NaN value.
A(A~=10) = NaN

A = 5×5

10 NaN NaN NaN 10

10 NaN 10 NaN NaN
NaN NaN 10 10 10
10 10 NaN 10 10

5-4
 Find Array Elements That Meet a Condition

10 10 10 10 10

Lastly, replace all of the NaN values in A with zeros and apply the logical NOT operator, ~A.

A(isnan(A)) = 0;
C = ~A

C = 5x5 logical array

0 1 1 1 0
0 1 0 1 1
1 1 0 0 0
0 0 1 0 0
0 0 0 0 0

The resulting matrix has values of logical 1 (true) in place of the NaN values, and logical 0 (false)
in place of the 10s. The logical NOT operation, ~A, converts the numeric array into a logical array
such that A&C returns a matrix of logical 0 (false) values and A|C returns a matrix of logical 1
(true) values.

See Also
Logical Operators: Short Circuit | and | find | isnan | nan | not | or | xor

5-5
5 The Logical Class

Reduce Logical Arrays to Single Value

This example shows how to use the any and all functions to reduce an entire array to a single
logical value.

The any and all functions are natural extensions of the logical | (OR) and & (AND) operators,
respectively. However, rather than comparing just two elements, the any and all functions compare
all of the elements in a particular dimension of an array. It is as if all of those elements are connected
by & or | operators and the any or all functions evaluate the resulting long logical expressions.
Therefore, unlike the core logical operators, the any and all functions reduce the size of the array
dimension that they operate on so that it has size 1. This enables the reduction of many logical values
into a single logical condition.

First, create a matrix A that contains random integers between 1 and 25. Reset the random number
generator to the default state for reproducibility.

rng default
A = randi(25,5)

A = 5×5

21 3 4 4 17
23 7 25 11 1
4 14 24 23 22
23 24 13 20 24
16 25 21 24 17

Next, use the mod function along with the logical NOT operator, ~, to determine which elements in A
are even.

A = ~mod(A,2)

A = 5x5 logical array

0 0 1 1 0
0 0 0 0 0
1 1 1 0 1
0 1 0 1 1
1 0 0 1 0

The resulting matrices have values of logical 1 (true) where an element is even, and logical 0
(false) where an element is odd.

Since the any and all functions reduce the dimension that they operate on to size 1, it normally
takes two applications of one of the functions to reduce a 2–D matrix into a single logical condition,
such as any(any(A)). However, if you use the notation A(:) to regard all of the elements of A as a
single column vector, you can use any(A(:)) to get the same logical information without nesting the
function calls.

Determine if any elements in A are even.

any(A(:))

5-6
 Reduce Logical Arrays to Single Value

ans = logical
1

You can perform logical and relational comparisons within the function call to any or all. This makes
it easy to quickly test an array for a variety of properties.

Determine if all elements in A are odd.

all(~A(:))

ans = logical
0

Determine whether any main or super diagonal elements in A are even. Since the vectors returned by
diag(A) and diag(A,1) are not the same size, you first need to reduce each diagonal to a single
scalar logical condition before comparing them. You can use the short-circuit OR operator || to
perform the comparison, since if any elements in the first diagonal are even then the entire
expression evaluates to true regardless of what appears on the right-hand side of the operator.

any(diag(A)) || any(diag(A,1))

ans = logical
1

See Also
Logical Operators: Short Circuit | all | and | any | or | xor

5-7
 6

Characters and Strings

• “Text in String and Character Arrays” on page 6-2

• “Create String Arrays” on page 6-5
• “Cell Arrays of Character Vectors” on page 6-12
• “Analyze Text Data with String Arrays” on page 6-15
• “Test for Empty Strings and Missing Values” on page 6-20
• “Formatting Text” on page 6-24
• “Compare Text” on page 6-32
• “Search and Replace Text” on page 6-37
• “Convert Numeric Values to Text” on page 6-42
• “Convert Text to Numeric Values” on page 6-46
• “Unicode and ASCII Values” on page 6-50
• “Hexadecimal and Binary Values” on page 6-52
• “Frequently Asked Questions About String Arrays” on page 6-56
• “Update Your Code to Accept Strings” on page 6-61
• “Function Summary” on page 6-69
6 Characters and Strings

Text in String and Character Arrays

There are two ways to represent text in MATLAB®. Starting in R2016b, you can store text in string
arrays. And in any version of MATLAB, you can store text in character arrays. A typical use for
character arrays is to store pieces of text as character vectors. MATLAB displays strings with double
quotes and character vectors with single quotes.

Represent Text with String Arrays

You can store any 1-by-n sequence of characters as a string, using the string data type. Starting in
R2017a, enclose text in double quotes to create a string.

str = "Hello, world"

str =
"Hello, world"

Though the text "Hello, world" is 12 characters long, str itself is a 1-by-1 string, or string scalar.
You can use a string scalar to specify a file name, plot label, or any other piece of textual information.

To find the number of characters in a string, use the strlength function.

n = strlength(str)

n = 12

If the text includes double quotes, use two double quotes within the definition.

str = "They said, ""Welcome!"" and waved."

str =
"They said, "Welcome!" and waved."

To add text to the end of a string, use the plus operator, +. If a variable can be converted to a string,
then plus converts it and appends it.

fahrenheit = 71;
celsius = (fahrenheit-32)/1.8;
tempText = "temperature is " + celsius + "C"

tempText =
"temperature is 21.6667C"

Starting in R2019a, you can also concatenate text using the append function.

tempText2 = append("Today's ",tempText)

tempText2 =
"Today's temperature is 21.6667C"

The string function can convert different types of inputs, such as numeric, datetime, duration, and
categorical values. For example, convert the output of pi to a string.

ps = string(pi)

ps =
"3.1416"

6-2
 Text in String and Character Arrays

You can store multiple pieces of text in a string array. Each element of the array can contain a string
having a different number of characters, without padding.

str = ["Mercury","Gemini","Apollo";...
"Skylab","Skylab B","ISS"]

str = 2x3 string

"Mercury" "Gemini" "Apollo"
"Skylab" "Skylab B" "ISS"

str is a 2-by-3 string array. You can find the lengths of the strings with the strlength function.

N = strlength(str)

N = 2×3

7 6 6
6 8 3

As of R2018b, string arrays are supported throughout MATLAB and MathWorks® products. Functions
that accept character arrays (and cell arrays of character vectors) as inputs also accept string arrays.

Represent Text with Character Vectors

To store a 1-by-n sequence of characters as a character vector, using the char data type, enclose it in
single quotes.

chr = 'Hello, world'

chr =
'Hello, world'

The text 'Hello, world' is 12 characters long, and chr stores it as a 1-by-12 character vector.

whos chr

Name Size Bytes Class Attributes

chr 1x12 24 char

If the text includes single quotes, use two single quotes within the definition.

chr = 'They said, ''Welcome!'' and waved.'

chr =
'They said, 'Welcome!' and waved.'

Character vectors have two principal uses:

• To specify single pieces of text, such as file names and plot labels.
• To represent data that is encoded using characters. In such cases, you might need easy access to
individual characters.

For example, you can store a DNA sequence as a character vector.

seq = 'GCTAGAATCC';

6-3
6 Characters and Strings

You can access individual characters or subsets of characters by indexing, just as you would index
into a numeric array.

seq(4:6)

ans =
'AGA'

Concatenate character vector with square brackets, just as you concatenate other types of arrays.

seq2 = [seq 'ATTAGAAACC']

seq2 =
'GCTAGAATCCATTAGAAACC'

Starting in R2019a, you also can concatenate text using append. The append function is
recommended because it treats string arrays, character vectors, and cell arrays of character vectors
consistently.

seq2 = append(seq,'ATTAGAAACC')

seq2 =
'GCTAGAATCCATTAGAAACC'

MATLAB functions that accept string arrays as inputs also accept character vectors and cell arrays of
character vectors.

See Also
append | cellstr | char | horzcat | plus | string | strlength

Related Examples
• “Create String Arrays” on page 6-5
• “Analyze Text Data with String Arrays” on page 6-15
• “Frequently Asked Questions About String Arrays” on page 6-56
• “Update Your Code to Accept Strings” on page 6-61
• “Cell Arrays of Character Vectors” on page 6-12

6-4
 Create String Arrays

Create String Arrays

String arrays were introduced in R2016b. String arrays store pieces of text and provide a set of
functions for working with text as data. You can index into, reshape, and concatenate strings arrays
just as you can with arrays of any other type. You also can access the characters in a string and
append text to strings using the plus operator. To rearrange strings within a string array, use
functions such as split, join, and sort.

Create String Arrays from Variables

MATLAB® provides string arrays to store pieces of text. Each element of a string array contains a 1-
by-n sequence of characters.

Starting in R2017a, you can create a string using double quotes.

str = "Hello, world"

str =
"Hello, world"

As an alternative, you can convert a character vector to a string using the string function. chr is a
1-by-17 character vector. str is a 1-by-1 string that has the same text as the character vector.
chr = 'Greetings, friend'

chr =
'Greetings, friend'

str = string(chr)

str =
"Greetings, friend"

Create a string array containing multiple strings using the [] operator. str is a 2-by-3 string array
that contains six strings.
str = ["Mercury","Gemini","Apollo";
"Skylab","Skylab B","ISS"]

str = 2x3 string

"Mercury" "Gemini" "Apollo"
"Skylab" "Skylab B" "ISS"

Find the length of each string in str with the strlength function. Use strlength, not length, to
determine the number of characters in strings.
L = strlength(str)

L = 2×3

7 6 6
6 8 3

As an alternative, you can convert a cell array of character vectors to a string array using the string
function. MATLAB displays strings in string arrays with double quotes, and displays characters
vectors in cell arrays with single quotes.

6-5
6 Characters and Strings

C = {'Mercury','Venus','Earth'}

C = 1x3 cell
{'Mercury'} {'Venus'} {'Earth'}

str = string(C)

str = 1x3 string

"Mercury" "Venus" "Earth"

In addition to character vectors, you can convert numeric, datetime, duration, and categorical values
to strings using the string function.

Convert a numeric array to a string array.

X = [5 10 20 3.1416];
string(X)

ans = 1x4 string

"5" "10" "20" "3.1416"

Convert a datetime value to a string.

d = datetime('now');
string(d)

ans =
"29-Feb-2020 03:25:21"

Also, you can read text from files into string arrays using the readtable, textscan, and fscanf
functions.

Create Empty and Missing Strings

String arrays can contain both empty and missing values. An empty string contains zero characters.
When you display an empty string, the result is a pair of double quotes with nothing between them
(""). The missing string is the string equivalent to NaN for numeric arrays. It indicates where a string
array has missing values. When you display a missing string, the result is <missing>, with no
quotation marks.

Create an empty string array using the strings function. When you call strings with no
arguments, it returns an empty string. Note that the size of str is 1-by-1, not 0-by-0. However, str
contains zero characters.
str = strings

str =
""

Create an empty character vector using single quotes. Note that the size of chr is 0-by-0.
chr = ''

chr =

0x0 empty char array

6-6
 Create String Arrays

Create a string array where every element is an empty string. You can preallocate a string array with
the strings function.

str = strings(2,3)

str = 2x3 string

"" "" ""
"" "" ""

To create a missing string, convert a missing value using the string function. The missing string
displays as <missing>.

str = string(missing)

str =
<missing>

You can create a string array with both empty and missing strings. Use the ismissing function to
determine which elements are strings with missing values. Note that the empty string is not a
missing string.

str(1) = "";
str(2) = "Gemini";
str(3) = string(missing)

str = 1x3 string

"" "Gemini" <missing>

ismissing(str)

ans = 1x3 logical array

0 0 1

Compare a missing string to another string. The result is always 0 (false), even when you compare a
missing string to another missing string.

str = string(missing);
str == "Gemini"

ans = logical
0

str == string(missing)

ans = logical
0

Access Elements of String Array

String arrays support array operations such as indexing and reshaping. Use array indexing to access
the first row of str and all the columns.

6-7
6 Characters and Strings

str = ["Mercury","Gemini","Apollo";
"Skylab","Skylab B","ISS"];
str(1,:)

ans = 1x3 string

"Mercury" "Gemini" "Apollo"

Access the second element in the second row of str.

str(2,2)

ans =
"Skylab B"

Assign a new string outside the bounds of str. MATLAB expands the array and fills unallocated
elements with missing values.

str(3,4) = "Mir"

str = 3x4 string

"Mercury" "Gemini" "Apollo" <missing>
"Skylab" "Skylab B" "ISS" <missing>
<missing> <missing> <missing> "Mir"

Access Characters Within Strings

You can index into a string array using curly braces, {}, to access characters directly. Use curly
braces when you need to access and modify characters within a string element. Indexing with curly
braces provides compatibility for code that could work with either string arrays or cell arrays of
character vectors. But whenever possible, use string functions to work with the characters in strings.

Access the second element in the second row with curly braces. chr is a character vector, not a
string.

str = ["Mercury","Gemini","Apollo";
"Skylab","Skylab B","ISS"];
chr = str{2,2}

chr =
'Skylab B'

Access the character vector and return the first three characters.

str{2,2}(1:3)

ans =
'Sky'

Find the space characters in a string and replace them with dashes. Use the isspace function to
inspect individual characters within the string. isspace returns a logical vector that contains a true
value wherever there is a space character. Finally, display the modified string element, str(2,2).

TF = isspace(str{2,2})

TF = 1x8 logical array

6-8
 Create String Arrays

0 0 0 0 0 0 1 0

str{2,2}(TF) = "-";
str(2,2)

ans =
"Skylab-B"

Note that in this case, you can also replace spaces using the replace function, without resorting to
curly brace indexing.
replace(str(2,2)," ","-")

ans =
"Skylab-B"

Concatenate Strings into String Array

Concatenate strings into a string array just as you would concatenate arrays of any other kind.

Concatenate two string arrays using square brackets, [].

str1 = ["Mercury","Gemini","Apollo"];
str2 = ["Skylab","Skylab B","ISS"];
str = [str1 str2]

str = 1x6 string

"Mercury" "Gemini" "Apollo" "Skylab" "Skylab B" "ISS"

Transpose str1 and str2. Concatenate them and then vertically concatenate column headings onto
the string array. When you concatenate character vectors into a string array, the character vectors
are automatically converted to strings.
str1 = str1';
str2 = str2';
str = [str1 str2];
str = [["Mission:","Station:"] ; str]

str = 4x2 string

"Mission:" "Station:"
"Mercury" "Skylab"
"Gemini" "Skylab B"
"Apollo" "ISS"

Append Text to Strings

To append text to strings, use the plus operator, +. The plus operator appends text to strings but
does not change the size of a string array.

Append a last name to an array of names. If you append a character vector to strings, then the
character vector is automatically converted to a string.
names = ["Mary";"John";"Elizabeth";"Paul";"Ann"];
names = names + ' Smith'

names = 5x1 string

"Mary Smith"

6-9
6 Characters and Strings

"John Smith"
"Elizabeth Smith"
"Paul Smith"
"Ann Smith"

Append different last names. You can append text to a string array from a string array or from a cell
array of character vectors. When you add nonscalar arrays, they must be the same size.
names = ["Mary";"John";"Elizabeth";"Paul";"Ann"];
lastnames = ["Jones";"Adams";"Young";"Burns";"Spencer"];
names = names + " " + lastnames

names = 5x1 string

"Mary Jones"
"John Adams"
"Elizabeth Young"
"Paul Burns"
"Ann Spencer"

Append a missing string. When you append a missing string with the plus operator, the output is a
missing string.
str1 = "Jones";
str2 = string(missing);
str1 + str2

ans =
<missing>

Split, Join, and Sort String Array

MATLAB provides a rich set of functions to work with string arrays. For example, you can use the
split, join, and sort functions to rearrange the string array names so that the names are in
alphabetical order by last name.

Split names on the space characters. Splitting changes names from a 5-by-1 string array to a 5-by-2
array.
names = ["Mary Jones";"John Adams";"Elizabeth Young";"Paul Burns";"Ann Spencer"];
names = split(names)

names = 5x2 string

"Mary" "Jones"
"John" "Adams"
"Elizabeth" "Young"
"Paul" "Burns"
"Ann" "Spencer"

Switch the columns of names so that the last names are in the first column. Add a comma after each
last name.
names = [names(:,2) names(:,1)];
names(:,1) = names(:,1) + ','

names = 5x2 string

"Jones," "Mary"

6-10
 Create String Arrays

"Adams," "John"
"Young," "Elizabeth"
"Burns," "Paul"
"Spencer," "Ann"

Join the last and first names. The join function places a space character between the strings it joins.
After the join, names is a 5-by-1 string array.

names = join(names)

names = 5x1 string

"Jones, Mary"
"Adams, John"
"Young, Elizabeth"
"Burns, Paul"
"Spencer, Ann"

Sort the elements of names so that they are in alphabetical order.

names = sort(names)

names = 5x1 string

"Adams, John"
"Burns, Paul"
"Jones, Mary"
"Spencer, Ann"
"Young, Elizabeth"

See Also
ismissing | isspace | join | plus | sort | split | string | strings | strlength

Related Examples
• “Analyze Text Data with String Arrays” on page 6-15
• “Search and Replace Text” on page 6-37
• “Compare Text” on page 6-32
• “Test for Empty Strings and Missing Values” on page 6-20
• “Frequently Asked Questions About String Arrays” on page 6-56
• “Update Your Code to Accept Strings” on page 6-61

6-11
6 Characters and Strings

Cell Arrays of Character Vectors

To store text as a character vector, enclose it single quotes. Typically, a character vector has text that
you consider to be a single piece of information, such as a file name or a label for a plot. If you have
many pieces of text, such as a list of file names, then you can store them in a cell array. A cell array
whose elements are all character vectors is a cell array of character vectors.

Note

• As of R2018b, the recommended way to store text is to use string arrays. If you create variables
that have the string data type, store them in string arrays, not cell arrays. For more information,
see “Text in String and Character Arrays” on page 6-2 and “Update Your Code to Accept Strings”
on page 6-61.
• While the phrase cell array of strings frequently has been used to describe such cell arrays, the
phrase is no longer accurate because such a cell array holds character vectors, not strings.

Create Cell Array of Character Vectors

To create a cell array of character vectors, use curly braces, {}, just as you would to create any cell
array. For example, use a cell array of character vectors to store a list of names.
C = {'Li','Sanchez','Jones','Yang','Larson'}

C = 1x5 cell
{'Li'} {'Sanchez'} {'Jones'} {'Yang'} {'Larson'}

The character vectors in C can have different lengths because a cell array does not require that its
contents have the same size. To determine the lengths of the character vectors in C, use the
strlength function.
L = strlength(C)

L = 1×5

2 7 5 4 6

Access Character Vectors in Cell Array

To access character vectors in a cell array, index into it using curly braces, {}. Extract the contents of
the first cell and store it as a character vector.
C = {'Li','Sanchez','Jones','Yang','Larson'};
chr = C{1}

chr =
'Li'

Assign a different character vector to the first cell.

C{1} = 'Yang'

6-12
 Cell Arrays of Character Vectors

C = 1x5 cell
{'Yang'} {'Sanchez'} {'Jones'} {'Yang'} {'Larson'}

To refer to a subset of cells, instead of their contents, index using smooth parentheses.

C(1:3)

ans = 1x3 cell

{'Yang'} {'Sanchez'} {'Jones'}

While you can access the contents of cells by indexing, most functions that accept cell arrays as
inputs operate on the entire cell array. For example, you can use the strcmp function to compare the
contents of C to a character vector. strcmp returns 1 where there is a match and 0 otherwise.

TF = strcmp(C,'Yang')

TF = 1x5 logical array

1 0 0 1 0

You can sum over TF to find the number of matches.

num = sum(TF)

num = 2

Use TF as logical indices to return the matches in C. If you index using smooth parentheses, then the
output is a cell array containing only the matches.

M = C(TF)

M = 1x2 cell
{'Yang'} {'Yang'}

Convert Cell Arrays to String Arrays

As of R2018b, string arrays are supported throughout MATLAB® and MathWorks® products.
Therefore it is recommended that you use string arrays instead of cell arrays of character vectors.
(However, MATLAB functions that accept string arrays as inputs do accept character vectors and cell
arrays of character vectors as well.)

You can convert cell arrays of character vectors to string arrays. To convert a cell array of character
vectors, use the string function.

C = {'Li','Sanchez','Jones','Yang','Larson'}

C = 1x5 cell
{'Li'} {'Sanchez'} {'Jones'} {'Yang'} {'Larson'}

str = string(C)

6-13
6 Characters and Strings

str = 1x5 string

"Li" "Sanchez" "Jones" "Yang" "Larson"

In fact, the string function converts any cell array, so long as all of the contents can be converted to
strings.

C2 = {5, 10, 'some text', datetime('today')}

C2=1×4 cell array

{[5]} {[10]} {'some text'} {[29-Feb-2020]}

str2 = string(C2)

str2 = 1x4 string

"5" "10" "some text" "29-Feb-2020"

See Also
cellstr | char | iscellstr | strcmp | string

More About
• “Text in String and Character Arrays” on page 6-2
• “Access Data in Cell Array” on page 12-5
• “Create String Arrays” on page 6-5
• “Update Your Code to Accept Strings” on page 6-61
• “Frequently Asked Questions About String Arrays” on page 6-56

6-14
 Analyze Text Data with String Arrays

Analyze Text Data with String Arrays

This example shows how to store text from a file as a string array, sort the words by their frequency,
plot the result, and collect basic statistics for the words found in the file.

Import Text File to String Array

Read text from Shakespeare's Sonnets with the fileread function. fileread returns the text as a
1-by-100266 character vector.

sonnets = fileread('sonnets.txt');
sonnets(1:35)

ans =
'THE SONNETS

by William Shakespeare'

Convert the text to a string using the string function. Then, split it on newline characters using the
splitlines function. sonnets becomes a 2625-by-1 string array, where each string contains one
line from the poems. Display the first five lines of sonnets.

sonnets = string(sonnets);
sonnets = splitlines(sonnets);
sonnets(1:5)

ans = 5x1 string

"THE SONNETS"
""
"by William Shakespeare"
""
""

Clean String Array

To calculate the frequency of the words in sonnets, first clean it by removing empty strings and
punctuation marks. Then reshape it into a string array that contains individual words as elements.

Remove the strings with zero characters ("") from the string array. Compare each element of
sonnets to "", the empty string. Starting in R2017a, you can create strings, including an empty
string, using double quotes. TF is a logical vector that contains a true value wherever sonnets
contains a string with zero characters. Index into sonnets with TF and delete all strings with zero
characters.

TF = (sonnets == "");
sonnets(TF) = [];
sonnets(1:10)

ans = 10x1 string

"THE SONNETS"
"by William Shakespeare"
" I"
" From fairest creatures we desire increase,"
" That thereby beauty's rose might never die,"
" But as the riper should by time decease,"

6-15
6 Characters and Strings

" His tender heir might bear his memory:"

" But thou, contracted to thine own bright eyes,"
" Feed'st thy light's flame with self-substantial fuel,"
" Making a famine where abundance lies,"

Replace some punctuation marks with space characters. For example, replace periods, commas, and
semi-colons. Keep apostrophes because they can be part of some words in the Sonnets, such as
light's.
p = [".","?","!",",",";",":"];
sonnets = replace(sonnets,p," ");
sonnets(1:10)

ans = 10x1 string

"THE SONNETS"
"by William Shakespeare"
" I"
" From fairest creatures we desire increase "
" That thereby beauty's rose might never die "
" But as the riper should by time decease "
" His tender heir might bear his memory "
" But thou contracted to thine own bright eyes "
" Feed'st thy light's flame with self-substantial fuel "
" Making a famine where abundance lies "

Strip leading and trailing space characters from each element of sonnets.
sonnets = strip(sonnets);
sonnets(1:10)

ans = 10x1 string

"THE SONNETS"
"by William Shakespeare"
"I"
"From fairest creatures we desire increase"
"That thereby beauty's rose might never die"
"But as the riper should by time decease"
"His tender heir might bear his memory"
"But thou contracted to thine own bright eyes"
"Feed'st thy light's flame with self-substantial fuel"
"Making a famine where abundance lies"

Split sonnets into a string array whose elements are individual words. You can use the split
function to split elements of a string array on whitespace characters, or on delimiters that you
specify. However, split requires that every element of a string array must be divisible into an equal
number of new strings. The elements of sonnets have different numbers of spaces, and therefore are
not divisible into equal numbers of strings. To use the split function on sonnets, write a for-loop
that calls split on one element at a time.

Create the empty string array sonnetWords using the strings function. Write a for-loop that splits
each element of sonnets using the split function. Concatenate the output from split onto
sonnetWords. Each element of sonnetWords is an individual word from sonnets.
sonnetWords = strings(0);
for i = 1:length(sonnets)

6-16
 Analyze Text Data with String Arrays

sonnetWords = [sonnetWords ; split(sonnets(i))];

end
sonnetWords(1:10)

ans = 10x1 string

"THE"
"SONNETS"
"by"
"William"
"Shakespeare"
"I"
"From"
"fairest"
"creatures"
"we"

Sort Words Based on Frequency

Find the unique words in sonnetWords. Count them and sort them based on their frequency.

To count words that differ only by case as the same word, convert sonnetWords to lowercase. For
example, The and the count as the same word. Find the unique words using the unique function.
Then, count the number of times each unique word occurs using the histcounts function.

sonnetWords = lower(sonnetWords);
[words,~,idx] = unique(sonnetWords);
numOccurrences = histcounts(idx,numel(words));

Sort the words in sonnetWords by number of occurrences, from most to least common.

[rankOfOccurrences,rankIndex] = sort(numOccurrences,'descend');
wordsByFrequency = words(rankIndex);

Plot Word Frequency

Plot the occurrences of words in the Sonnets from the most to least common words. Zipf's Law states
that the distribution of occurrences of words in a large body text follows a power-law distribution.

loglog(rankOfOccurrences);
xlabel('Rank of word (most to least common)');
ylabel('Number of Occurrences');

6-17
6 Characters and Strings

Display the ten most common words in the Sonnets.

wordsByFrequency(1:10)

ans = 10x1 string

"and"
"the"
"to"
"my"
"of"
"i"
"in"
"that"
"thy"
"thou"

Collect Basic Statistics in Table

Calculate the total number of occurrences of each word in sonnetWords. Calculate the number of
occurrences as a percentage of the total number of words, and calculate the cumulative percentage
from most to least common. Write the words and the basic statistics for them to a table.
numOccurrences = numOccurrences(rankIndex);
numOccurrences = numOccurrences';
numWords = length(sonnetWords);
T = table;
T.Words = wordsByFrequency;

6-18
 Analyze Text Data with String Arrays

T.NumOccurrences = numOccurrences;
T.PercentOfText = numOccurrences / numWords * 100.0;
T.CumulativePercentOfText = cumsum(numOccurrences) / numWords * 100.0;

Display the statistics for the ten most common words.

T(1:10,:)

ans=10×4 table
Words NumOccurrences PercentOfText CumulativePercentOfText
______ ______________ _____________ _______________________

"and" 490 2.7666 2.7666

"the" 436 2.4617 5.2284
"to" 409 2.3093 7.5377
"my" 371 2.0947 9.6324
"of" 370 2.0891 11.722
"i" 341 1.9254 13.647
"in" 321 1.8124 15.459
"that" 320 1.8068 17.266
"thy" 280 1.5809 18.847
"thou" 233 1.3156 20.163

The most common word in the Sonnets, and, occurs 490 times. Together, the ten most common words
account for 20.163% of the text.

See Also
histcounts | join | lower | replace | sort | split | splitlines | string | strip | table |
unique

Related Examples
• “Create String Arrays” on page 6-5
• “Search and Replace Text” on page 6-37
• “Compare Text” on page 6-32
• “Test for Empty Strings and Missing Values” on page 6-20

6-19
6 Characters and Strings

Test for Empty Strings and Missing Values

String arrays can contain both empty strings and missing values. Empty strings contain zero
characters and display as double quotes with nothing between them (""). You can determine if a
string is an empty string using the == operator. The empty string is a substring of every other string.
Therefore, functions such as contains always find the empty string within other strings. String
arrays also can contain missing values. Missing values in string arrays display as <missing>. To find
missing values in a string array, use the ismissing function instead of the == operator.

Test for Empty Strings

You can test a string array for empty strings using the == operator.

Starting in R2017a, you can create an empty string using double quotes with nothing between them
(""). Note that the size of str is 1-by-1, not 0-by-0. However, str contains zero characters.

str = ""

str =
""

Create an empty character vector using single quotes. Note that the size of chr is 0-by-0. The
character array chr actually is an empty array, and not just an array with zero characters.

chr = ''

chr =

0x0 empty char array

Create an array of empty strings using the strings function. Each element of the array is a string
with no characters.

str2 = strings(1,3)

str2 = 1x3 string

"" "" ""

Test if str is an empty string by comparing it to an empty string.

if (str == "")
disp 'str has zero characters'
end

str has zero characters

Do not use the isempty function to test for empty strings. A string with zero characters still has a
size of 1-by-1. However, you can test if a string array has at least one dimension with a size of zero
using the isempty function.

Create an empty string array using the strings function. To be an empty array, at least one
dimension must have a size of zero.

str = strings(0,3)

6-20