Explore the full ebook collection and download it now at ebookball.

com

Programming Fundamentals Using MATLAB Analyze Data

And Develop Algorithms 1st Edition by Michael
Weeks B09NZC2XC1

https://ebookball.com/product/programming-fundamentals-
using-matlab-analyze-data-and-develop-algorithms-1st-
edition-by-michael-weeks-b09nzc2xc1-17618/

OR CLICK HERE

DOWLOAD EBOOK

Browse and Get More Ebook Downloads Instantly at https://ebookball.com

Click here to visit ebookball.com and download ebookball now
 Your digital treasures (PDF, ePub, MOBI) await
Download instantly and pick your perfect format...

Read anywhere, anytime, on any device!

Data Structures and Algorithms in Python 1st Edition by

Michael Goodrich, Roberto Tamassia, Michael Goldwasser
ISBN 9781118476734 1118476735
https://ebookball.com/product/data-structures-and-algorithms-in-
python-1st-edition-by-michael-goodrich-roberto-tamassia-michael-
goldwasser-isbn-9781118476734-1118476735-15762/

ebookball.com

Problem Solving in Data Structures and Algorithms Using C

1st Edition by Hemant Jain ISBN 9352655915 9789352655915

https://ebookball.com/product/problem-solving-in-data-structures-and-
algorithms-using-c-1st-edition-by-hemant-jain-
isbn-9352655915-9789352655915-15768/

ebookball.com

Problem Solving in Data Structures and Algorithms Using C

1st Edition by Hemant Jain ISBN 1540407306 9781540407306

https://ebookball.com/product/problem-solving-in-data-structures-and-
algorithms-using-c-1st-edition-by-hemant-jain-
isbn-1540407306-9781540407306-15866/

ebookball.com

JavaScript Data Structures and Algorithms An Introduction

to Understanding and Implementing Core Data Structure and
Algorithm Fundamentals 1st Editon by Sammie Bae ISBN
1484239873 9781484239872
https://ebookball.com/product/javascript-data-structures-and-
algorithms-an-introduction-to-understanding-and-implementing-core-
data-structure-and-algorithm-fundamentals-1st-editon-by-sammie-bae-
isbn-1484239873-9781484239872-15798/
ebookball.com
Web Animation using JavaScript Develop and Design 1st
Edition by Julian Shapiro ISBN 0134096703 9780134096704

https://ebookball.com/product/web-animation-using-javascript-develop-
and-design-1st-edition-by-julian-shapiro-
isbn-0134096703-9780134096704-16170/

ebookball.com

Signal and System Analysis Using MATLAB 1st Edition by

Luis Chaparro 0123747163 9780123747167

https://ebookball.com/product/signal-and-system-analysis-using-
matlab-1st-edition-by-luis-chaparro-0123747163-9780123747167-17604/

ebookball.com

Programming Fundamentals A Modular Structured Approach

using C++ 1st edition by Kenneth Leroy Busbee ISBN
1616100656 9781616100650
https://ebookball.com/product/programming-fundamentals-a-modular-
structured-approach-using-c-1st-edition-by-kenneth-leroy-busbee-
isbn-1616100656-9781616100650-25036/

ebookball.com

Robotics Vision and Control Fundamental Algorithms In

MATLAB 2nd Edition by Peter Corke 3319544128 9783319544120

https://ebookball.com/product/robotics-vision-and-control-fundamental-
algorithms-in-matlab-2nd-edition-by-peter-
corke-3319544128-9783319544120-25276/

ebookball.com

Data Structure Algorithms Using C A Practical

Implementation 1st edition by Sachi Nandan Mohanty,
Pabitra Kumar Tripathy 9781119752035 1119752035
https://ebookball.com/product/data-structure-algorithms-using-c-a-
practical-implementation-1st-edition-by-sachi-nandan-mohanty-pabitra-
kumar-tripathy-9781119752035-1119752035-18754/

ebookball.com
MATLAB®
Programming Fundamentals

R2022b
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–2022 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 MATLAB 7.5 (Release 2007b)
March 2008 Online only Revised for MATLAB 7.6 (Release 2008a)
October 2008 Online only Revised for MATLAB 7.7 (Release 2008b)
March 2009 Online only Revised for MATLAB 7.8 (Release 2009a)
September 2009 Online only Revised for MATLAB 7.9 (Release 2009b)
March 2010 Online only Revised for MATLAB 7.10 (Release 2010a)
September 2010 Online only Revised for MATLAB 7.11 (Release 2010b)
April 2011 Online only Revised for MATLAB 7.12 (Release 2011a)
September 2011 Online only Revised for MATLAB 7.13 (Release 2011b)
March 2012 Online only Revised for MATLAB 7.14 (Release 2012a)
September 2012 Online only Revised for MATLAB 8.0 (Release 2012b)
March 2013 Online only Revised for MATLAB 8.1 (Release 2013a)
September 2013 Online only Revised for MATLAB 8.2 (Release 2013b)
March 2014 Online only Revised for MATLAB 8.3 (Release 2014a)
October 2014 Online only Revised for MATLAB 8.4 (Release 2014b)
March 2015 Online only Revised for MATLAB 8.5 (Release 2015a)
September 2015 Online only Revised for MATLAB 8.6 (Release 2015b)
October 2015 Online only Rereleased for MATLAB 8.5.1 (Release 2015aSP1)
March 2016 Online only Revised for MATLAB 9.0 (Release 2016a)
September 2016 Online only Revised for MATLAB 9.1 (Release 2016b)
March 2017 Online only Revised for MATLAB 9.2 (Release 2017a)
September 2017 Online only Revised for MATLAB 9.3 (Release 2017b)
March 2018 Online only Revised for MATLAB 9.4 (Release 2018a)
September 2018 Online only Revised for MATLAB 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)
September 2020 Online only Revised for MATLAB 9.9 (Release 2020b)
March 2021 Online only Revised for MATLAB 9.10 (Release 2021a)
September 2021 Online only Revised for MATLAB 9.11 (Release 2021b)
March 2022 Online only Revised for MATLAB 9.12 (Release 2022a)
September 2022 Online only Revised for MATLAB 9.13 (Release 2022b)
 Contents

Language

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

Name=Value in Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3

Ignore Function Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Variable Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5

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

Case and Space Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Choose Command Syntax or Function Syntax . . . . . . . . . . . . . . . . . . . 1-8

Command Syntax and Function Syntax . . . . . . . . . . . . . . . . . . . . . . . 1-8
Avoid Common Syntax Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
How MATLAB Recognizes Command Syntax . . . . . . . . . . . . . . . . . . . 1-9

Resolve Error: Undefined Function or Variable . . . . . . . . . . . . . . . . . 1-11

Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Possible Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11

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

v
 Compatible Array Sizes for Basic Operations . . . . . . . . . . . . . . . . . . 2-25
Inputs with Compatible Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25
Inputs with Incompatible Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27

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

Array Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30
Logic Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-32

Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-33

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

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

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

Bit-Wise Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-39

Perform Cyclic Redundancy Check . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45

Conditional Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-48

Loop Control Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-50

Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-52

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

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

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

Tokens in Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-67

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-67
Multiple Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-69
Unmatched Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-70
Tokens in Replacement Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-70
Named Capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-71

Dynamic Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-73

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

Comma-Separated Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-80

What Is a Comma-Separated List? . . . . . . . . . . . . . . . . . . . . . . . . . 2-80
Generating a Comma-Separated List . . . . . . . . . . . . . . . . . . . . . . . . 2-80
Assigning Output from a Comma-Separated List . . . . . . . . . . . . . . . 2-82
Assigning to a Comma-Separated List . . . . . . . . . . . . . . . . . . . . . . . 2-82
How to Use Comma-Separated Lists . . . . . . . . . . . . . . . . . . . . . . . . 2-83

vi Contents
 Fast Fourier Transform Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-86
Troubleshooting Operations with Comma-Separated Lists . . . . . . . . 2-86

Alternatives to the eval Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91

Why Avoid the eval Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91
Variables with Sequential Names . . . . . . . . . . . . . . . . . . . . . . . . . . 2-91
Files with Sequential Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92
Function Names in Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92
Field Names in Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-93
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-93

Classes (Data Types)

Overview of MATLAB Classes

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

Detect States of Variables Using is* Functions . . . . . . . . . . . . . . . . . . 3-5

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-7
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-14

Infinity and NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Infinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15

Identifying Numeric Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-17

vii
 Display Format for Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18

Integer Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-20

Single Precision Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27

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

Build Pattern Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40

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

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

Unicode and ASCII Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52

Hexadecimal and Binary Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54

viii Contents
 Frequently Asked Questions About String Arrays . . . . . . . . . . . . . . . 6-58
Why Does Using Command Form With Strings Return An Error? . . 6-58
Why Do Strings in Cell Arrays Return an Error? . . . . . . . . . . . . . . . 6-59
Why Does length() of String Return 1? . . . . . . . . . . . . . . . . . . . . . . 6-59
Why Does isempty("") Return 0? . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-60
Why Does Appending Strings Using Square Brackets Return Multiple
Strings? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61

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

What Are String Arrays? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-63
Recommended Approaches for String Adoption in Old APIs . . . . . . 6-63
How to Adopt String Arrays in Old APIs . . . . . . . . . . . . . . . . . . . . . 6-65
Recommended Approaches for String Adoption in New Code . . . . . 6-65
How to Maintain Compatibility in New Code . . . . . . . . . . . . . . . . . . 6-66
How to Manually Convert Input Arguments . . . . . . . . . . . . . . . . . . 6-67
How to Check Argument Data Types . . . . . . . . . . . . . . . . . . . . . . . . 6-67
Terminology for Character and String Arrays . . . . . . . . . . . . . . . . . 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-12
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

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

Plot Dates and Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-36

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

Convert Between Text and datetime or duration Values . . . . . . . . . 7-48

Replace Discouraged Instances of Serial Date Numbers and Date

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-57
Convert Serial Date Numbers and Date Strings . . . . . . . . . . . . . . . 7-57
Replace Functions That Use Date Numbers . . . . . . . . . . . . . . . . . . 7-57
Discouraged Syntaxes for Date and Time Components . . . . . . . . . . 7-61
Guidelines for Updating Your Own Functions . . . . . . . . . . . . . . . . . 7-62

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

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

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 Tables and Assign Data to Them . . . . . . . . . . . . . . . . . . . . . . . 9-2

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

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

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

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

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

Access Data in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-32

Summary of Table Indexing Syntaxes . . . . . . . . . . . . . . . . . . . . . . . 9-32
Table Indexing with Specified Rows and Variables . . . . . . . . . . . . . 9-37
Find Rows Where Values Meet Logical Conditions . . . . . . . . . . . . . 9-41
Dot Notation with Any Variable Name or Expression . . . . . . . . . . . . 9-44
Extract Data from Specified Rows and Variables . . . . . . . . . . . . . . . 9-46

Calculations on Data in Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-48

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

Perform Calculations by Group in Table . . . . . . . . . . . . . . . . . . . . . . 9-59

Advantages of Using Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-71

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

Grouping Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76
Group Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-76
The Split-Apply-Combine Workflow . . . . . . . . . . . . . . . . . . . . . . . . . 9-77
Missing Group Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-77

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

Data Cleaning and Calculations in Tables . . . . . . . . . . . . . . . . . . . . . 9-81

Grouped Calculations in Tables and Timetables . . . . . . . . . . . . . . . . 9-99

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

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

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

xi
 Retime and Synchronize Timetable Variables Using Different
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14

Select Times in Timetable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19

Clean Timetable with Missing, Duplicate, or Nonuniform Times

.................................................... 10-27

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

Loma Prieta Earthquake Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 10-41

Preprocess and Explore Time-Stamped Data Using timetable . . . 10-51

Add Events from External Data to Timetable . . . . . . . . . . . . . . . . . 10-71

Find Events in Timestamped Data . . . . . . . . . . . . . . . . . . . . . . . . . . 10-83

Structures
11
Structure Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Create Scalar Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Access Values in Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Index into Nonscalar Structure Array . . . . . . . . . . . . . . . . . . . . . . . 11-4

Concatenate Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8

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

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

Access Elements of a Nonscalar Structure Array . . . . . . . . . . . . . . 11-13

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

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

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

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

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

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

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

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

Combine Cell Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11

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

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

Cell vs. Structure Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-17

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

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

Dictionaries
14
Map Data with Dictionaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2

Dictionaries and Custom Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6

Hash Equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-6
Overload keyHash and keyMatch for Custom Classes . . . . . . . . . . . 14-6

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

xiii
 Description of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Properties of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Methods of Map Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4

Create Map Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6

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

Examine Contents of Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8

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

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

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

Remove Keys and Values from Map . . . . . . . . . . . . . . . . . . . . . . . . 15-13
Modify Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-13
Modify Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-14
Modify Copy of Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-14

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

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

Combining Unlike Classes

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

Combining Unlike Integer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3

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

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

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

Empty Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7

Concatenation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-8

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

xiv Contents
 Using Objects
17
Copying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Two Copy Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Handle Object Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Value Object Copy Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Handle Object Copy Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-3
Testing for Handle or Value Class . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5

Defining Your Own Classes

18

Scripts and Functions

Scripts
19
Create Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-2

Add Comments to Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3

Create and Run Sections in Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5

Divide Your File into Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Run Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Navigate Between Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Behavior of Sections in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 19-8
Behavior of Sections in Loops and Conditional Statements . . . . . . . 19-8

Scripts vs. Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-10

Add Functions to Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-12

Create a Script with Local Functions . . . . . . . . . . . . . . . . . . . . . . 19-12
Run Scripts with Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . 19-12
Restrictions for Local Functions and Variables . . . . . . . . . . . . . . . 19-13
Access Help for Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 19-13

Live Scripts and Functions

20
What Is a Live Script or Function? . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Differences with Plain Code Scripts and Functions . . . . . . . . . . . . . 20-3

xv
 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
Unsupported Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5

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

Create Live Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
Add Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
Run Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
Display Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
Change View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8
Format Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Save Live Scripts as Plain Code . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11

Modify Figures in Live Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-12

Explore Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-12
Add Formatting and Annotations . . . . . . . . . . . . . . . . . . . . . . . . . 20-13
Update Code with Figure Changes . . . . . . . . . . . . . . . . . . . . . . . . 20-15
Save and Print Figure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-16

Format Text in the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-18

Change Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20
Autoformatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21

Insert Equations into the Live Editor . . . . . . . . . . . . . . . . . . . . . . . 20-24

Insert Equation Interactively . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-24
Insert LaTeX Equation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-26
Supported LaTeX Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-27

Add Interactive Controls to a Live Script . . . . . . . . . . . . . . . . . . . . 20-34

Insert Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-34
Modify Control Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-35
Link Variables to Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-36
Specify Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-37
Modify Control Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-37
Create Live Script with Multiple Interactive Controls . . . . . . . . . . 20-38
Share Live Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-41

Add Interactive Tasks to a Live Script . . . . . . . . . . . . . . . . . . . . . . . 20-43

What Are Live Editor Tasks? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-43
Insert Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-43
Run Tasks and Surrounding Code . . . . . . . . . . . . . . . . . . . . . . . . . 20-46
Modify Output Argument Name . . . . . . . . . . . . . . . . . . . . . . . . . . 20-47
View and Edit Generated Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-47
Custom Live Editor Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-48

Create Live Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-49

Create Live Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-49
Add Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-49
Add Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-50
Run Live Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-50
Save Live Functions as Plain Code . . . . . . . . . . . . . . . . . . . . . . . . 20-51

Add Help for Live Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-52

Share Live Scripts and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-56

Hide Code Before Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-57

xvi Contents
 Live Code File Format (.mlx) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-58
Benefits of Live Code File Format . . . . . . . . . . . . . . . . . . . . . . . . . 20-58
Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-58

Introduction to the Live Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-59

Accelerate Exploratory Programming Using the Live Editor . . . . . 20-64

Create an Interactive Narrative with the Live Editor . . . . . . . . . . . 20-69

Create Interactive Course Materials Using the Live Editor . . . . . . 20-77

Create Examples Using the Live Editor . . . . . . . . . . . . . . . . . . . . . . 20-83

Create an Interactive Form Using the Live Editor . . . . . . . . . . . . . 20-84

Create a Real-Time Dashboard Using the Live Editor . . . . . . . . . . 20-87

Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-89

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

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

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

Base and Function Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-9

Share Data Between Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10

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

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

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

Types of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-17

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

xvii
 Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
What Are Anonymous Functions? . . . . . . . . . . . . . . . . . . . . . . . . . 21-20
Variables in the Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-21
Multiple Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-21
Functions with No Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-22
Functions with Multiple Inputs or Outputs . . . . . . . . . . . . . . . . . . 21-22
Arrays of Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 21-23

Local Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-25

Nested Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-27

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

Resolve Error: Attempt to Add Variable to a Static Workspace. . . 21-33

Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-33
Possible Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-33

Private Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-36

Function Precedence Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-37

Change in Rules For Function Precedence Order . . . . . . . . . . . . . 21-38

Update Code for R2019b Changes to Function Precedence Order

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

Indexing into Function Call Results . . . . . . . . . . . . . . . . . . . . . . . . 21-46

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-46
Supported Syntaxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-46

xviii Contents
 Function Arguments
22
Find Number of Function Arguments . . . . . . . . . . . . . . . . . . . . . . . . 22-2

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

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

Validate Number of Function Arguments . . . . . . . . . . . . . . . . . . . . . 22-6

Checking Number of Arguments in Nested Functions . . . . . . . . . . . 22-8

Ignore Inputs in Function Definitions . . . . . . . . . . . . . . . . . . . . . . . 22-10

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

Parse Function Inputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-13

Input Parser Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 22-17

Debugging MATLAB Code

23
Debug MATLAB Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Display Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Debug Using Run to Here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3
View Variable Value While Debugging . . . . . . . . . . . . . . . . . . . . . . . 23-5
Pause a Running File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Step Into Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Add Breakpoints and Run Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
End Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7
Debug by Using Keyboard Shortcuts or Functions . . . . . . . . . . . . . . 23-8

Set Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9

Standard Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9
Conditional Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Error Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
Breakpoints in Anonymous Functions . . . . . . . . . . . . . . . . . . . . . . 23-11
Invalid Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12
Disable Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12
Clear Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13

Examine Values While Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14

View Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14
View Variable Value Outside Current Workspace . . . . . . . . . . . . . . 23-15

xix
 Presenting MATLAB Code
24
Publish and Share MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Create and Share Live Scripts in the Live Editor . . . . . . . . . . . . . . . 24-2
Publish MATLAB Code Files (.m) . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Add Help and Create Documentation . . . . . . . . . . . . . . . . . . . . . . . 24-4

Publishing Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-6

Markup Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-6
Sections and Section Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-8
Text Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-9
Bulleted and Numbered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-10
Text and Code Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-10
External File Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-11
External Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-12
Image Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-14
LaTeX Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-14
Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-16
HTML Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-18
LaTeX Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-19

Output Preferences for Publishing . . . . . . . . . . . . . . . . . . . . . . . . . 24-21

How to Edit Publishing Options . . . . . . . . . . . . . . . . . . . . . . . . . . 24-21
Specify Output File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-22
Run Code During Publishing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-23
Manipulate Graphics in Publishing Output . . . . . . . . . . . . . . . . . . 24-24
Save a Publish Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-28
Manage a Publish Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 24-29

Coding and Productivity Tips

25
Save and Back Up Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Save Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Back Up Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-2
Recommendations on Saving Files . . . . . . . . . . . . . . . . . . . . . . . . . 25-3
File Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-3

Check Code for Errors and Warnings Using the Code Analyzer . . . 25-5
Enable Continuous Code Checking . . . . . . . . . . . . . . . . . . . . . . . . . 25-5
View Code Analyzer Status for File . . . . . . . . . . . . . . . . . . . . . . . . . 25-5
View Code Analyzer Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-6
Fix Problems in Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-7
Create a Code Analyzer Message Report . . . . . . . . . . . . . . . . . . . . . 25-8
Adjust Code Analyzer Message Indicators and Messages . . . . . . . . 25-9
Understand Code Containing Suppressed Messages . . . . . . . . . . . 25-11
Understand the Limitations of Code Analysis . . . . . . . . . . . . . . . . 25-12
Enable MATLAB Compiler Deployment Messages . . . . . . . . . . . . . 25-14

xx Contents
 Edit and Format Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-16
Column Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-16
Change Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-16
Automatically Complete Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-16
Refactor Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-17
Indent Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-17
Fold Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-18
Change the Right-Side Text Limit Indicator . . . . . . . . . . . . . . . . . . 25-19

Find and Replace Text in Files and Go to Location . . . . . . . . . . . . . 25-21

Find and Replace Any Text in Current File . . . . . . . . . . . . . . . . . . 25-21
Find and Replace Functions or Variables in Current File . . . . . . . . 25-21
Automatically Rename All Variables or Functions in a File . . . . . . 25-22
Find Text in Multiple File Names or Files . . . . . . . . . . . . . . . . . . . 25-23
Go To Location in File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-24

Add Reminders to Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-27

Working with TODO/FIXME Reports . . . . . . . . . . . . . . . . . . . . . . . 25-27

MATLAB Code Analyzer Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-29

Run the Code Analyzer Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-29
Change Code Based on Code Analyzer Messages . . . . . . . . . . . . . 25-30
Other Ways to Access Code Analyzer Messages . . . . . . . . . . . . . . 25-30

MATLAB Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . . . 25-32

Open the Code Compatibility Analyzer . . . . . . . . . . . . . . . . . . . . . 25-32
Programmatic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-34
Unsupported Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-34

Code Generation Readiness Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-35

Issues Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-35
Files Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25-36

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

Security Considerations to Protect Your Source Code . . . . . . . . . . . 26-6

Create P-Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6
Build Standalone Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-6
Use Model Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7
Convert Code to Native Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7
Host Compiled Application on Remote Protected Server . . . . . . . . . 26-7
Utilize Secure OS Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-7

Create a Content-Obscured File with P-Code . . . . . . . . . . . . . . . . . . 26-9

Create P-Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-9
Invoke P-Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-9

xxi
 Run Older P-Code Files on Later Versions of MATLAB . . . . . . . . . . . 26-9

Create Hyperlinks that Run Functions . . . . . . . . . . . . . . . . . . . . . . 26-11

Run a Single Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-11
Run Multiple Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-12
Provide Command Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-12
Include Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-12

Create and Share Toolboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-14

Create Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-14
Share Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26-18

Run Parallel Language in MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . 26-20

Run Parallel Language in Serial . . . . . . . . . . . . . . . . . . . . . . . . . . 26-20
Use Parallel Language Without a Pool . . . . . . . . . . . . . . . . . . . . . . 26-21

Function Argument Validation

27
Function Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Introduction to Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Where to Use Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
arguments Block Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-2
Examples of Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . 27-5
Kinds of Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-7
Required and Optional Positional Arguments . . . . . . . . . . . . . . . . . 27-7
Repeating Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-9
Name-Value Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-11
Robust Handling of Name-Value Arguments . . . . . . . . . . . . . . . . . 27-14
Name-Value Arguments from Class Properties . . . . . . . . . . . . . . . 27-15
Order of Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Avoiding Class and Size Conversions . . . . . . . . . . . . . . . . . . . . . . 27-17
nargin in Argument Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-19
Restrictions on Variable and Function Access . . . . . . . . . . . . . . . . 27-20
Debugging Arguments Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-21

Argument Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-23

Numeric Value Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-23
Comparison with Other Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-24
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-24
Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-24
Membership and Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-25
Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-25
Define Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-25

Transparency in MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-27

Writing Transparent Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-27

xxii Contents
Software Development

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

Throw an Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-4

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

Respond to an Exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-6

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

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

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

Issue Warnings and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-14

Issue Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-14
Throw Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-14
Add Run-Time Parameters to Your Warnings and Errors . . . . . . . . 28-15
Add Identifiers to Warnings and Errors . . . . . . . . . . . . . . . . . . . . . 28-15

Suppress Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-17

Turn Warnings On and Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-18

Restore Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-20

Disable and Restore a Particular Warning . . . . . . . . . . . . . . . . . . . 28-20
Disable and Restore Multiple Warnings . . . . . . . . . . . . . . . . . . . . . 28-21

Change How Warnings Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-22

Enable Verbose Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-22
Display a Stack Trace on a Specific Warning . . . . . . . . . . . . . . . . . 28-22

Use try/catch to Handle Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28-23

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

Timer Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4

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

Handling Timer Queuing Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . 29-8

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

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

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

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

Techniques to Improve Performance . . . . . . . . . . . . . . . . . . . . . . . . 30-12

Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-12
Code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-12
Programming Practices for Performance . . . . . . . . . . . . . . . . . . . . 30-12
Tips on Specific MATLAB Functions . . . . . . . . . . . . . . . . . . . . . . . 30-13

Preallocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-14
Preallocating a Nondouble Matrix . . . . . . . . . . . . . . . . . . . . . . . . 30-14

Vectorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-16
Using Vectorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-16
Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-17
Logical Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-18
Matrix Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-19
Ordering, Setting, and Counting Operations . . . . . . . . . . . . . . . . . 30-20
Functions Commonly Used in Vectorization . . . . . . . . . . . . . . . . . 30-21

xxiv Contents
 Background Processing
31
Asynchronous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2
Asynchronous Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-2
Background Workers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-4

Run MATLAB Functions in Thread-Based Environment . . . . . . . . . 31-6

Run Functions in the Background . . . . . . . . . . . . . . . . . . . . . . . . . . 31-6
Run Functions on a Thread Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-6
Automatically Scale Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-6
Check Thread Supported Functions . . . . . . . . . . . . . . . . . . . . . . . . 31-6

Create Responsive Apps by Running Calculations in the Background

..................................................... 31-8
Open App Designer App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-8
Add a Future Array to the Properties . . . . . . . . . . . . . . . . . . . . . . . 31-8
Create y-axis Data in the Background . . . . . . . . . . . . . . . . . . . . . . . 31-9
Automatically Update Plot After Data Is Calculated in the Background
................................................. 31-9
Make Your App More Responsive by Canceling the Future Array . 31-10
Responsive App That Calculates and Plots Simple Curves . . . . . . . 31-11

Run Functions in Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31-13

Update Wait Bar While Functions Run in the Background . . . . . . 31-14

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

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

Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-6
Possible Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-6

How MATLAB Allocates Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-12

Avoid Unnecessary Copies of Data . . . . . . . . . . . . . . . . . . . . . . . . . . 32-16

Passing Values to Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-16
Why Pass-by-Value Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-19
Handle Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-19

xxv
 Custom Help and Documentation
33
Create Help for Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-2
Help Text from the doc Command . . . . . . . . . . . . . . . . . . . . . . . . . . 33-2
Custom Help Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-3

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

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

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

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

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

Display Custom Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-21

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

Display Custom Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33-29

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

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

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

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

Set MATLAB Projects Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . 34-10

xxvi Contents
Determine Order for Resolving Conflicts Using Dependency Analyzer
.................................................... 34-13

Manage Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-15

Automatic Updates When Renaming, Deleting, or Removing Files
................................................ 34-16

Find Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17

Group and Sort Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Search for and Filter Project Files . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Search the Content in Project Files . . . . . . . . . . . . . . . . . . . . . . . . 34-17

Create Shortcuts to Frequent Tasks . . . . . . . . . . . . . . . . . . . . . . . . 34-19

Run Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-19
Create Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-19
Organize Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-19

Add Labels to Project Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-21

Add Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-21
View and Edit Label Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-21
Create Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-22

Create Custom Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-23

Create a Custom Task Function . . . . . . . . . . . . . . . . . . . . . . . . . . 34-23
Run a Custom Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-23
Save Custom Task Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-24

Componentize Large Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-25

Add or Remove Reference to a Project . . . . . . . . . . . . . . . . . . . . . 34-25
View, Edit, or Run Referenced Project Files . . . . . . . . . . . . . . . . . 34-25
Extract Folder to Create a Referenced Project . . . . . . . . . . . . . . . 34-26
Manage Changes in Referenced Project Using Checkpoints . . . . . 34-26

Share Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-28

Create an Export Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-31

Upgrade Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-32

Run Upgrade Project Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-32
Examine Upgrade Project Report . . . . . . . . . . . . . . . . . . . . . . . . . 34-33

Analyze Project Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-35

Run a Dependency Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-35
Explore the Dependency Graph, Views, and Filters . . . . . . . . . . . . 34-37
Investigate and Resolve Problems . . . . . . . . . . . . . . . . . . . . . . . . . 34-43
Find Required Products and Add-Ons . . . . . . . . . . . . . . . . . . . . . . 34-46
Find File Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-47
Export Dependency Analysis Results . . . . . . . . . . . . . . . . . . . . . . 34-49

Clone Remote Git Repository into New Project . . . . . . . . . . . . . . . 34-51

Use Source Control with Projects . . . . . . . . . . . . . . . . . . . . . . . . . . 34-52

Setup Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-52
Perform Source Control Operations . . . . . . . . . . . . . . . . . . . . . . . 34-54
Work with Derived Files in Projects . . . . . . . . . . . . . . . . . . . . . . . 34-60
Find Project Files With Unsaved Changes . . . . . . . . . . . . . . . . . . . 34-61

xxvii
 Manage Open Files When Closing a Project . . . . . . . . . . . . . . . . . 34-61

Create and Edit Projects Programmatically . . . . . . . . . . . . . . . . . . 34-62

Explore an Example Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-69

Source Control Interface

35
Source Control Integration in MATLAB . . . . . . . . . . . . . . . . . . . . . . . 35-2
Classic and Distributed Source Control . . . . . . . . . . . . . . . . . . . . . . 35-2

Set Source Control Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-4

Set Git Preferences in MATLAB Online . . . . . . . . . . . . . . . . . . . . . . 35-4

Use Git in MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-5

Clone Remote Git Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-5
Mark Files for Addition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-6
Review Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-6
Commit Modified Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-7
Push Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-8
Resolve Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-9
Manage Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-10
Create Local Git Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-10
Store Uncommitted Changes Using Git Stashes . . . . . . . . . . . . . . 35-11

Set Up Git Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-12

Register Binary Files with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-12
Configure MATLAB for Git on Windows . . . . . . . . . . . . . . . . . . . . . 35-12
Configure MATLAB to Use Git SSH Authentication . . . . . . . . . . . . 35-13
Install Git Credential Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-17
Disable Compression for Simulink Models . . . . . . . . . . . . . . . . . . 35-17
Configure Git to Use Git LFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-17
Configure Git to use MATLAB for Diff and Merge . . . . . . . . . . . . . 35-17
Install Command-Line Git Client . . . . . . . . . . . . . . . . . . . . . . . . . . 35-18

Branch and Merge with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-19

Create Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-19
Switch Branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-20
Compare Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-21
Merge Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-21
Revert to Head . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-21
Delete Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-22

Add Git Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-23

Update Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-23
Use Fetch and Merge with Submodules . . . . . . . . . . . . . . . . . . . . 35-23
Use Push to Send Changes to the Submodule Repository . . . . . . . 35-23

Review Changes in SVN Source Control . . . . . . . . . . . . . . . . . . . . . 35-25

Mark Files for Addition to SVN Source Control . . . . . . . . . . . . . . . 35-26

xxviii Contents
Move, Rename, or Delete Files Under SVN Source Control . . . . . . 35-27

Resolve SVN Source Control Conflicts . . . . . . . . . . . . . . . . . . . . . . . 35-28

Examining and Resolving Conflicts . . . . . . . . . . . . . . . . . . . . . . . . 35-28
Resolve Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-28
Merge Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-28
Extract Conflict Markers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-29

Commit Modified Files to SVN Source Control . . . . . . . . . . . . . . . . 35-31

Revert Changes in SVN Source Control . . . . . . . . . . . . . . . . . . . . . . 35-32

Revert Local Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-32
Revert a File to a Specified Revision . . . . . . . . . . . . . . . . . . . . . . . 35-32

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

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

Check Out from SVN Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-38

Retrieve Tagged Version of Repository . . . . . . . . . . . . . . . . . . . . . 35-38

Update SVN File Status and Revision . . . . . . . . . . . . . . . . . . . . . . . 35-40

Refresh Status of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-40
Update Revisions of Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-40

Get SVN File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-41

Manage SVN Repository Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-41

Continuous Integration Using MATLAB Projects and Jenkins . . . 35-42

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-42
Set Up MATLAB Project for Continuous Integration in Jenkins . . . 35-42
Reduce Test Runtime Using Dependency Cache and Impact Analysis
................................................ 35-43
Enhance Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-44

Customize External Source Control to Use MATLAB for Diff and

Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-46
Finding the Full Paths for MATLAB Diff, Merge, and AutoMerge . . 35-46
Integration with Git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-47
Integration with SVN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-48
Integration with Other Source Control Tools . . . . . . . . . . . . . . . . . 35-49

MSSCCI Source Control Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 35-51

Set Up MSSCCI Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-52

Create Projects in Source Control System . . . . . . . . . . . . . . . . . . . 35-52
Specify Source Control System with MATLAB Software . . . . . . . . 35-53
Register Source Control Project with MATLAB Software . . . . . . . . 35-54
Add Files to Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-56

xxix
 Check Files In and Out from MSSCCI Source Control . . . . . . . . . . 35-57
Check Files Into Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . 35-57
Check Files Out of Source Control . . . . . . . . . . . . . . . . . . . . . . . . 35-57
Undoing the Checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-58

Additional MSSCCI Source Control Actions . . . . . . . . . . . . . . . . . . 35-59

Getting the Latest Version of Files for Viewing or Compiling . . . . . 35-59
Removing Files from the Source Control System . . . . . . . . . . . . . . 35-60
Showing File History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-60
Comparing the Working Copy of a File to the Latest Version in Source
Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-61
Viewing Source Control Properties of a File . . . . . . . . . . . . . . . . . 35-62
Starting the Source Control System . . . . . . . . . . . . . . . . . . . . . . . 35-63

Access MSSCCI Source Control from Editors . . . . . . . . . . . . . . . . . 35-65

Troubleshoot MSSCCI Source Control Problems . . . . . . . . . . . . . . 35-66

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

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

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

Write Script-Based Test Using Local Functions . . . . . . . . . . . . . . . 36-11

Extend Script-Based Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-14

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

Run Tests in Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-17

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

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

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

Write Test Using Setup and Teardown Functions . . . . . . . . . . . . . . 36-27

Extend Function-Based Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-32

Fixtures for Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . 36-32
Test Logging and Verbosity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-33

xxx Contents
 Test Suite Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-33
Test Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-33
Test Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-34
Programmatic Access of Test Diagnostics . . . . . . . . . . . . . . . . . . . 36-34
Test Runner Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-35

Author Class-Based Unit Tests in MATLAB . . . . . . . . . . . . . . . . . . . 36-36

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

Write Simple Test Case Using Classes . . . . . . . . . . . . . . . . . . . . . . . 36-39

Write Setup and Teardown Code Using Classes . . . . . . . . . . . . . . . 36-42

Test Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-42
Test Case with Method-Level Setup Code . . . . . . . . . . . . . . . . . . . 36-42
Test Case with Class-Level Setup Code . . . . . . . . . . . . . . . . . . . . . 36-43

Table of Verifications, Assertions, and Other Qualifications . . . . . 36-45

Tag Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-48

Tag Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-48
Select and Run Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-49

Write Tests Using Shared Fixtures . . . . . . . . . . . . . . . . . . . . . . . . . . 36-52

Create Basic Custom Fixture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-55

Create Advanced Custom Fixture . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-57

Use Parameters in Class-Based Tests . . . . . . . . . . . . . . . . . . . . . . . 36-62

How to Write Parameterized Tests . . . . . . . . . . . . . . . . . . . . . . . . 36-62
How to Initialize Parameterization Properties . . . . . . . . . . . . . . . . 36-63
Specify Parameterization Level . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-64
Specify How Parameters Are Combined . . . . . . . . . . . . . . . . . . . . 36-65
Use External Parameters in Tests . . . . . . . . . . . . . . . . . . . . . . . . . 36-67

Create Basic Parameterized Test . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-68

Create Advanced Parameterized Test . . . . . . . . . . . . . . . . . . . . . . . . 36-73

Use External Parameters in Parameterized Test . . . . . . . . . . . . . . . 36-80

Define Parameters at Suite Creation Time . . . . . . . . . . . . . . . . . . . 36-84

Create Simple Test Suites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-91

Run Tests for Various Workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-93

Set Up Example Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-93
Run All Tests in Class or Function . . . . . . . . . . . . . . . . . . . . . . . . . 36-93
Run Single Test in Class or Function . . . . . . . . . . . . . . . . . . . . . . . 36-93
Run Test Suites by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-94
Run Test Suites from Test Array . . . . . . . . . . . . . . . . . . . . . . . . . . 36-94
Run Tests with Customized Test Runner . . . . . . . . . . . . . . . . . . . . 36-95

xxxi
 Programmatically Access Test Diagnostics . . . . . . . . . . . . . . . . . . . 36-96

Add Plugin to Test Runner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-97

Write Plugins to Extend TestRunner . . . . . . . . . . . . . . . . . . . . . . . 36-100

Custom Plugins Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-100
Extending Test Session Level Plugin Methods . . . . . . . . . . . . . . . 36-100
Extending Test Suite Level Plugin Methods . . . . . . . . . . . . . . . . 36-101
Extending Test Class Level Plugin Methods . . . . . . . . . . . . . . . . 36-101
Extending Test Level Plugin Methods . . . . . . . . . . . . . . . . . . . . . 36-102

Create Custom Plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-103

Run Tests in Parallel with Custom Plugin . . . . . . . . . . . . . . . . . . . 36-108

Write Plugin to Add Data to Test Results . . . . . . . . . . . . . . . . . . . 36-116

Write Plugin to Save Diagnostic Details . . . . . . . . . . . . . . . . . . . . 36-121

Plugin to Generate Custom Test Output Format . . . . . . . . . . . . . . 36-125

Analyze Test Case Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-128

Analyze Failed Test Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-131

Rerun Failed Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-133

Dynamically Filtered Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-136

Test Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-136
Method Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . . . 36-138
Class Setup and Teardown Code . . . . . . . . . . . . . . . . . . . . . . . . . 36-139

Create Custom Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-142

Create Custom Boolean Constraint . . . . . . . . . . . . . . . . . . . . . . . . 36-145

Overview of App Testing Framework . . . . . . . . . . . . . . . . . . . . . . . 36-149

App Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-149
Gesture Support of UI Components . . . . . . . . . . . . . . . . . . . . . . 36-149
Write a Test for an App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-151

Write Tests for an App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-154

Write Tests That Use App Testing and Mocking Frameworks . . . 36-158
Create App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-158
Test App With Manual Intervention . . . . . . . . . . . . . . . . . . . . . . . 36-159
Create Fully Automated Test . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-160

Overview of Performance Testing Framework . . . . . . . . . . . . . . . . 36-163

Determine Bounds of Measured Code . . . . . . . . . . . . . . . . . . . . . 36-163
Types of Time Experiments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-164
Write Performance Tests with Measurement Boundaries . . . . . . . 36-164
Run Performance Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-165
Understand Invalid Test Results . . . . . . . . . . . . . . . . . . . . . . . . . 36-165

xxxii Contents
Test Performance Using Scripts or Functions . . . . . . . . . . . . . . . . 36-167

Test Performance Using Classes . . . . . . . . . . . . . . . . . . . . . . . . . . 36-171

Measure Fast Executing Test Code . . . . . . . . . . . . . . . . . . . . . . . . 36-177

Create Mock Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-180

Specify Mock Object Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-187

Define Mock Method Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . 36-187
Define Mock Property Behavior . . . . . . . . . . . . . . . . . . . . . . . . . 36-188
Define Repeating and Subsequent Behavior . . . . . . . . . . . . . . . . 36-189
Summary of Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-191

Qualify Mock Object Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . 36-192

Qualify Mock Method Interaction . . . . . . . . . . . . . . . . . . . . . . . . 36-192
Qualify Mock Property Interaction . . . . . . . . . . . . . . . . . . . . . . . 36-193
Use Mock Object Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-194
Summary of Qualifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-196

Ways to Write Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-198

Script-Based Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-198
Function-Based Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-199
Class-Based Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-199
Extend Unit Testing Framework . . . . . . . . . . . . . . . . . . . . . . . . . 36-200

Compile MATLAB Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-201

Run Tests with Standalone Applications . . . . . . . . . . . . . . . . . . . 36-201
Run Tests in Parallel with Standalone Applications . . . . . . . . . . . 36-202
TestRand Class Definition Summary . . . . . . . . . . . . . . . . . . . . . . 36-202

Generate Code Coverage Report in HTML Format . . . . . . . . . . . . 36-204

Statement Coverage for MATLAB Source Code . . . . . . . . . . . . . . 36-204
Function Coverage for MATLAB Source Code . . . . . . . . . . . . . . . 36-204
Generate and Analyze HTML Coverage Report . . . . . . . . . . . . . . 36-205
QuadraticPolynomial Class Definition . . . . . . . . . . . . . . . . . . . . . 36-207

Insert Test Code Using Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-209

Create Test Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-209
Add Parameters and Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-209
Run Tests in Test Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-212

Develop and Integrate Software with Continuous Integration . . 36-213

Continuous Integration Workflow . . . . . . . . . . . . . . . . . . . . . . . . 36-213
Continuous Integration with MathWorks Products . . . . . . . . . . . 36-215

Generate Artifacts Using MATLAB Unit Test Plugins . . . . . . . . . . 36-217

Continuous Integration with MATLAB on CI Platforms . . . . . . . . 36-221

Azure DevOps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-221
Bamboo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-221
CircleCI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-221
GitHub Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-221
GitLab CI/CD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-222
Jenkins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-222

xxxiii
 Travis CI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-222
Other Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36-222

Build Automation
37
Overview of MATLAB Build Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-2
Create Plan with Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-2
Run Tasks in Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-3

Create and Run Tasks Using Build Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-4

Create Build File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-4
Summary of Build File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-5
Visualize Task Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-6
Run Tasks in Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-6

System object Usage and Authoring

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

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

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

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

System Design and Simulation in MATLAB . . . . . . . . . . . . . . . . . . . . . . . 38-7
Create Individual Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-7
Configure Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-8
Create and Configure Components at the Same Time . . . . . . . . . . . . . . . 38-8
Assemble Components Into System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-9
Run Your System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-9
Reconfiguring Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-10

Define Basic System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-11

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

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

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

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

xxxiv Contents
Initialize Properties and Setup One-Time Calculations . . . . . . . . . . . . . 38-18

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

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

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

Define Property Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-24

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

Hide Inactive Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-26

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

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

Property Validation with mustBeMember . . . . . . . . . . . . . . . . . . . . . . . 38-28
Enumeration Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-28
Create a Whiteboard System Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-29

Process Tuned Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-32

Define Composite System Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-34

Define Finite Source Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-36

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

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

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

Define System Object Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-41

Handle Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-43

React to Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 38-43
Restrict Input Specification Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 38-43

Summary of Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-45

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

Detailed Call Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-48

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

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

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-50

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

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

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

Analyze System Object Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-58

Use Global Variables in System Objects . . . . . . . . . . . . . . . . . . . . . . . . . 38-61

System Object Global Variables in MATLAB . . . . . . . . . . . . . . . . . . . . . 38-61
System Object Global Variables in Simulink . . . . . . . . . . . . . . . . . . . . . 38-61

Create Moving Average System Object . . . . . . . . . . . . . . . . . . . . . . . . . . 38-65

Create New System Objects for File Input and Output . . . . . . . . . . . . . 38-70

Create Composite System Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-76

xxxvi Contents
Language

37
 1

Syntax Basics

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

• “Name=Value in Function Calls” on page 1-3
• “Ignore Function Outputs” on page 1-4
• “Variable Names” on page 1-5
• “Case and Space Sensitivity” on page 1-7
• “Choose Command Syntax or Function Syntax” on page 1-8
• “Resolve Error: Undefined Function or Variable” on page 1-11
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
 Name=Value in Function Calls

Name=Value in Function Calls

Since R2021a

MATLAB supports two syntaxes for passing name-value arguments.

plot(x,y,LineWidth=2) name=value syntax

plot(x,y,"LineWidth",2) comma-separated syntax

Use the name=value syntax to help identify name-value arguments for functions and to clearly
distinguish names from values in lists of name-value arguments.

Most functions and methods support both syntaxes, but there are some limitations on where and how
the name=value syntax can be used:

Mixing name,value and name=value syntaxes: The recommended practice is to use only one
syntax in any given function call. However, if you do mix name=value and name,value syntaxes
in a single call, all name=value arguments must appear after the name,value arguments. For
example, plot(x,y,"Color","red",LineWidth=2) is a valid combination, but
plot(x,y,Color="red","LineWidth",2) errors.
• Using positional arguments after name-value arguments: Some functions have positional
arguments that appear after name-value arguments. For example, this call to the verifyEqual
method uses the RelTol name-value argument, followed by a string input:

verifyEqual(testCase,1.5,2,"RelTol",0.1,...
"Difference exceeds relative tolerance.")

Using the name=value syntax (RelTol=0.1) causes the statement to error. In cases where a
positional argument follows name-value arguments, use the name,value syntax.
• Names that are invalid variable names: Name-value arguments with names that are invalid
MATLAB variable names cannot be used with the name=value syntax. See “Variable Names” on
page 1-5 for more info. For example, a name-value argument like "allow-empty",true errors
if passed as allow-empty=true. Use the name,value syntax in these cases.

Function authors do not need to code differently to support both the name,value and name=value
syntaxes. For information on authoring functions that accept name-value arguments, see “Name-Value
Arguments” on page 27-11.

1-3
1 Syntax Basics

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 Inputs in Function Definitions” on page 22-10

1-4
 Variable Names

Variable Names

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

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: Examples of 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-91

1-5
1 Syntax Basics

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

1-6
 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-7
1 Syntax Basics

Choose Command Syntax or Function Syntax

MATLAB has two ways of calling functions, called function syntax and command syntax. This page
discusses the differences between these syntax formats and how to avoid common mistakes
associated with command syntax.

For introductory information on calling functions, see “Calling Functions”. For information related to
defining functions, see “Create Functions in Files” on page 21-2.

Command Syntax and Function Syntax

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)

In function syntax, inputs can be data, variables, and even MATLAB expressions. If an input is data,
such as the numeric value 2 or the string array ["a" "b" "c"], MATLAB passes it to the function
as-is. If an input is a variable MATLAB will pass the value assigned to it. If an input is an expression,
like 2+2 or sin(2*pi), MATLAB evaluates it first, and passes the result to the function. If the
functions has outputs, you can assign them to variables as shown in the example syntax above.

Command syntax is simpler but more limited. To use it, separate inputs with spaces rather than
commas, and do not enclose them in parentheses.

functionName input1 ... inputN

With command syntax, MATLAB passes all inputs as character vectors (that is, as if they were
enclosed in single quotation marks) and does not assign outputs to variables. To pass a data type
other than a character vector, use the function syntax. To pass a value that contains a space, you have
two options. One is to use function syntax. The other is to put single quotes around the value.
Otherwise, MATLAB treats the space as splitting your value into multiple inputs.

If a value is assigned to 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

1-8
 Choose Command Syntax or Function Syntax

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;

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 tempdir cd('tempdir') cd(tempdir)
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')

or

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

1-9
1 Syntax Basics

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

If you issue this 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. When
you are using those components, 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:

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, MATLAB treats the potentially ambiguous statement ls ./d as 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.

See Also
“Calling Functions” | “Create Functions in Files” on page 21-2

1-10
 Resolve Error: Undefined Function or Variable

Resolve Error: Undefined Function or Variable

Issue
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.

Possible Solutions
Verify Spelling of Function or Variable Name

One of the most common causes is misspelling the function or variable name. Especially with longer
names or names containing similar characters (such as the letter l and numeral one), it is easy to
make mistakes and hard to detect them.

Often, when 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:

accumArray

Undefined function or variable 'accumArray'.

Did you mean:

>> accumarray

When this happens, press Enter to execute the suggested command or Esc to dismiss it.

Verify Inputs Correspond to the Function Syntax

Object methods are typically called using function syntax: for instance method(object,inputs).
Alternatively, they can be called using dot notation: for instance object.method(inputs). One
common error is to mix these syntaxes. For instance, you might call the method using function syntax,
but to provide inputs following dot notation syntax and leave out the object as an input: for instance,
method(inputs). To avoid this, when calling an object method, make sure you specify the object
first, either through the first input of function syntax or through the first identifier of dot notation.

Make Sure Function Name Matches File Name

When you write a function, you establish its name 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

1-11
1 Syntax Basics

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.

To Locate the file that defines 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

Make Sure Necessary Toolbox Is Installed and Correct Version

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

If you do not know which toolbox contains 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. Alternatively, for steps to identify toolboxes that a function depends on, see
“Identify Program Dependencies” on page 26-2.

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. If you cannot, you need to install it in order to use it.
For help with installing MathWorks products, see “Install License Manager on License Server”.

1-12
 Another Random Document on
Scribd Without Any Related Topics
the following circumstance in confirmation.
Last spring, while the author was in New York, a Presbyterian
clergyman, of Ohio, came to her, and said, “I understand they
dispute that fact about the woman’s crossing the river. Now, I know
all about that, for I got the story from the very man that helped her
up the bank. I know it is true, for she is now living in Canada.”
It has been objected that the representation of the scene in which
the plan for kidnapping Eliza, concocted by Haley, Marks and Loker,
at the tavern, is a gross caricature on the state of things in Ohio.
What knowledge the author has had of the facilities which some
justices of the peace, under the old fugitive law of Ohio, were in the
habit of giving to kidnapping, may be inferred by comparing the
statement in her book with some in her personal knowledge.
“Ye see,” said Marks to Haley, stirring his punch as he did so, “ye see, we has
justices convenient at all p’ints along shore, that does up any little jobs in our line
quite reasonable. Tom, he does the knockin’ down, and that ar; and I come in all
dressed up,—shining boots,—everything first chop,—when the swearin’ ‘s to be
done. You oughter see me, now!” said Marks, in a glow of professional pride, “how
I can tone it off. One day I’m Mr. Twickem, from New Orleans; ‘nother day, I’m just
come from my plantation on Pearl river, where I works seven hundred niggers;
then, again, I come out a distant relation to Henry Clay, or some old cock in
Kentuck. Talents is different, you know. Now, Tom’s a roarer when there’s any
thumping or fighting to be done; but at lying he an’t good, Tom an’t; ye see it
don’t come natural to him; but, Lord! if thar’s a feller in the country that can swear
to anything and everything, and put in all the circumstances and flourishes with a
longer face, and carry’t through better’n I can, why, I’d like to see him, that’s all! I
b’lieve, my heart, I could get along, and make through, even if justices were more
particular than they is. Sometimes I rather wish they was more particular; ‘twould
be a heap more relishin’ if they was,—more fun, yer know.”
In the year 1839, the writer received into her family, as a servant, a
girl from Kentucky. She had been the slave of one of the lowest and
most brutal families, with whom she had been brought up, in a log-
cabin, in a state of half-barbarism. In proceeding to give her
religious instruction, the author heard, for the first time in her life,
an inquiry which she had not supposed possible to be made in
America:—“Who is Jesus Christ, now, anyhow?”
When the author told her the history of the love and life and death
of Christ, the girl seemed wholly overcome; tears streamed down
her cheeks; and she exclaimed, piteously, “Why didn’t nobody never
tell me this before?”
“But,” said the writer to her, “haven’t you ever seen the Bible?”
“Yes, I have seen missus a-readin’ on’t sometimes; but, law sakes!
she’s just a-readin’ on’t ‘cause she could; don’t s’pose it did her no
good, no way.”
She said she had been to one or two camp-meetings in her life, but
“didn’t notice very particular.”
At all events, the story certainly made great impression on her, and
had such an effect in improving her conduct, that the writer had
great hopes of her.
On inquiring into her history, it was discovered that, by the laws of
Ohio, she was legally entitled to her freedom, from the fact of her
having been brought into the state, and left there, temporarily, by
the consent of her mistress. These facts being properly
authenticated before the proper authorities, papers attesting her
freedom were drawn up, and it was now supposed that all danger of
pursuit was over. After she had remained in the family for some
months, word was sent, from various sources, to Professor Stowe,
that the girl’s young master was over, looking for her, and that, if
care were not taken, she would be conveyed back into slavery.
Professor Stowe called on the magistrate who had authenticated her
papers, and inquired whether they were not sufficient to protect her.
The reply was, “Certainly they are, in law, if she could have a fair
hearing; but they will come to your house in the night, with an
officer and a warrant; they will take her before Justice D——, and
swear to her. He’s the man that does all this kind of business, and,
he’ll deliver her up, and there’ll be an end to it.”
Mr. Stowe then inquired what could be done; and was recommended
to carry her to some place of security till the inquiry for her was
over. Accordingly, that night, a brother of the author, with Professor
Stowe, performed for the fugitive that office which the senator is
represented as performing for Eliza. They drove about ten miles on a
solitary road, crossed the creek at a very dangerous fording, and
presented themselves, at midnight, at the house of John Van Zandt,
a noble-minded Kentuckian, who had performed the good deed
which the author, in her story, ascribes to Van Tromp.
After some rapping at the door, the worthy owner of the mansion
appeared, candle in hand, as has been narrated.
“Are you the man that would save a poor colored girl from
kidnappers?” was the first question.
“Guess I am,” was the prompt response; “where is she?”
“Why, she’s here.”
“But how did you come?”
“I crossed the creek.”
“Why, the Lord helped you!” said he; “I shouldn’t dare cross it myself
in the night. A man and his wife, and five children, were drowned
there, a little while ago.”
The reader may be interested to know that the poor girl never was
retaken; that she married well in Cincinnati, is a very respectable
woman, and the mother of a large family of children.
 CHAPTER VI.
UNCLE TOM.

The character of Uncle Tom has been objected to as improbable;

and yet the writer has received more confirmations of that character,
and from a greater variety of sources, than of any other in the book.
Many people have said to her, “I knew an Uncle Tom in such and
such a Southern State.” All the histories of this kind which have thus
been related to her would of themselves, if collected, make a small
volume. The author will relate a few of them.
While visiting in an obscure town in Maine, in the family of a friend,
the conversation happened to turn upon this subject, and the
gentleman with whose family she was staying related the following.
He said that, when on a visit to his brother, in New Orleans, some
years before, he found in his possession a most valuable negro man,
of such remarkable probity and honesty that his brother literally
trusted him with all he had. He had frequently seen him take out a
handful of bills, without looking at them, and hand them to this
servant, bidding him go and provide what was necessary for the
family, and bring him the change. He remonstrated with his brother
on this imprudence; but the latter replied that he had had such proof
of this servant’s impregnable conscientiousness that he felt it safe to
trust him to any extent.
The history of the servant was this. He had belonged to a man in
Baltimore, who, having a general prejudice against all the religious
exercises of slaves, did all that he could to prevent his having any
time for devotional duties, and strictly forbade him to read the Bible
and pray, either by himself, or with the other servants; and because,
like a certain man of old, named Daniel, he constantly disobeyed this
unchristian edict, his master inflicted upon him that punishment
which a master always has in his power to inflict,—he sold him into
perpetual exile from his wife and children, down to New Orleans.
The gentleman who gave the writer this information says that,
although not himself a religious man at the time, he was so struck
with the man’s piety that he said to his brother, “I hope you will
never do anything to deprive this man of his religious privileges, for I
think a judgment will come upon you if you do.” To this his brother
replied that he should be very foolish to do it, since he had made up
his mind that the man’s religion was the root of his extraordinary
excellences.
Some time since, there was sent to the writer from the South,
through the mail, a little book, entitled, “Sketches of Old Virginia
Family Servants,” with a preface by Bishop Meade. The book
contains an account of the following servants: African Bella, Old
Milly, Blind Lucy, Aunt Betty, Springfield Bob, Mammy Chris, Diana
Washington, Aunt Margaret, Rachel Parker, Nelly Jackson, My Own
Mammy, Aunt Beck.
The following extract from Bishop Meade’s preface may not be uninteresting.
The following sketches were placed in my hands with a request that I would
examine them with a view to publication.
After reading them I could not but think that they would be both pleasing and
edifying.
Very many such examples of fidelity and piety might be added from the old
Virginia families. These will suffice as specimens, and will serve to show how
interesting the relation between master and servant often is.
Many will doubtless be surprised to find that there was so much intelligence, as
well as piety, in some of the old servants of Virginia, and that they had learned to
read the Sacred Scriptures, so as to be useful in this way among their fellow-
servants. It is, and always has been true, in regard to the servants of the Southern
States, that although public schools may have been prohibited, yet no interference
has been attempted, where the owners have chosen to teach their servants, or
permit them to learn in a private way, how to read God’s word. Accordingly, there
always have been some who were thus taught. In the more southern states the
number of these has most abounded. Of this fact I became well assured, about
thirty years since, when visiting the Atlantic states, with a view to the formation of
auxiliary colonization societies, and the selection of the first colonists for Africa. In
the city of Charleston, South Carolina, I found more intelligence and character
among the free colored population than anywhere else. The same was true of
some of those in bondage. A respectable number might be seen in certain parts of
the Episcopal churches which I attended using their prayer-books, and joining in
the responses of the church.
Many purposes of convenience and hospitality were subserved by this
encouragement of cultivation in some of the servants, on the part of the owners.
When travelling many years since with a sick wife, and two female relatives, from
Charleston to Virginia, at a period of the year when many of the families from the
country resort to the town for health, we were kindly urged to call at the seat of
one of the first families in South Carolina, and a letter from the mistress, then in
the city, was given us, to her servant, who had charge of the house in the absence
of the family. On reaching there and delivering the letter to a most respectable-
looking female servant, who immediately read it, we were kindly welcomed, and
entertained, during a part of two days, as sumptuously as though the owner had
been present. We understood that it was no uncommon thing in South Carolina for
travellers to be thus entertained by the servants in the absence of the owners, on
receiving letters from the same.
Instances of confidential and affectionate relationship between servants and their
masters and mistresses, such as are set forth in the following Sketches, are still to
be found in all the slaveholding states. I mention one, which has come under my
own observation. The late Judge Upshur, of Virginia, had a faithful house-servant
(by his will now set free), with whom he used to correspond on matters of
business, when he was absent on his circuit. I was dining at his house, some years
since, with a number of persons, himself being absent, when the conversation
turned on the subject of the presidential election, then going on through the
United States, and about which there was an intense interest; when his servant
informed us that he had that day received a letter from his master, then on the
western shore, in which he stated that the friends of General Harrison might be
relieved from all uneasiness, as the returns already received made his election
quite certain.
Of course it is not to be supposed that we design to convey the impression that
such instances are numerous, the nature of the relationship forbidding it; but we
do mean emphatically to affirm that there is far more of kindly and Christian
intercourse than many at a distance are apt to believe. That there is a great and
sad want of Christian instruction, notwithstanding the more recent efforts put forth
to impart it, we most sorrowfully acknowledge.
Bishop Meade adds that these sketches are published with the hope
that they might have the effect of turning the attention of ministers
and heads of families more seriously to the duty of caring for the
souls of their servants.
With regard to the servant of Judge Upshur, spoken of in this
communication of Bishop Meade, his master has left, in his last will,
the following remarkable tribute to his worth and excellence of
character:
I emancipate and set free my servant, David Rice, and direct my executors to give
him one hundred dollars. I recommend him in the strongest manner to the
respect, esteem and confidence, of any community in which he may happen to
live. He has been my slave for twenty-four years, during all which time he has
been trusted to every extent, and in every respect; my confidence in him has been
unbounded; his relation to myself and family has always been such as to afford
him daily opportunities to deceive and injure us, yet he has never been detected in
any serious fault, nor even in an unintentional breach of the decorum of his
station. His intelligence is of a high order, his integrity above all suspicion, and his
sense of right and propriety correct, and even refined. I feel that he is justly
entitled to carry this certificate from me in the new relations which he must now
form; it is due to his long and most faithful services, and to the sincere and steady
friendship which I bear to him. In the uninterrupted confidential intercourse of
twenty-four years, I have never given him, nor had occasion to give him, one
unpleasant word. I know no man who has fewer faults or more excellences than
he.
In the free states there have been a few instances of such
extraordinary piety among negroes, that their biography and sayings
have been collected in religious tracts, and published for the
instruction of the community.
One of these was, before his conversion, a convict in a state-prison
in New York, and there received what was, perhaps, the first
religious instruction that had ever been imparted to him. He became
so eminent an example of humility, faith, and, above all, fervent
love, that his presence in the neighborhood was esteemed a blessing
to the church. A lady has described to the writer the manner in
which he would stand up and exhort in the church-meetings for
prayer, when, with streaming eyes and the deepest abasement,
humbly addressing them as his masters and misses, he would
nevertheless pour forth religious exhortations which were edifying to
the most cultivated and refined.
In the town of Brunswick, Maine, where the writer lived when
writing “Uncle Tom’s Cabin,” may now be seen the grave of an aged
colored woman, named Phebe, who was so eminent for her piety
and loveliness of character, that the writer has never heard her
name mentioned except with that degree of awe and respect which
one would imagine due to a saint. The small cottage where she
resided is still visited and looked upon as a sort of shrine, as the
spot where old Phebe lived and prayed. Her prayers and pious
exhortations were supposed to have been the cause of the
conversion of many young people in the place. Notwithstanding that
the unchristian feeling of caste prevails as strongly in Maine as
anywhere else in New England, and the negro, commonly speaking,
is an object of aversion and contempt, yet, so great was the
influence of her piety and loveliness of character, that she was
uniformly treated with the utmost respect and attention by all
classes of people. The most cultivated and intelligent ladies of the
place esteemed it a privilege to visit her cottage; and when she was
old and helpless, her wants were most tenderly provided for. When
the news of her death was spread abroad in the place, it excited a
general and very tender sensation of regret. “We have lost Phebe’s
prayers,” was the remark frequently made afterwards by members of
the church, as they met one another. At her funeral the ex-governor
of the state and the professors of the college officiated as pall-
bearers, and a sermon was preached in which the many excellences
of her Christian character were held up as an example to the
community. A small religious tract, containing an account of her life,
was published by the American Tract Society, prepared by a lady of
Brunswick. The writer recollects that on reading the tract, when she
first went to Brunswick, a doubt arose in her mind whether it was
not somewhat exaggerated. Some time afterwards she overheard
some young persons conversing together about the tract, and saying
that they did not think it gave exactly the right idea of Phebe. “Why,
is it too highly colored?” was the inquiry of the author. “O, no, no,
indeed,” was the earnest response; “it doesn’t begin to give an idea
of how good she was.”
Such instances as these serve to illustrate the words of the apostle,
“God hath chosen the foolish things of the world to confound the
wise; and God hath chosen the weak things of the world to
confound the things which are mighty.”
John Bunyan says that although the valley of humiliation be
unattractive in the eyes of the men of this world, yet the very
sweetest flowers grow there. So it is with the condition of the lowly
and poor in this world. God has often, indeed always, shown a
particular regard for it, in selecting from that class the recipients of
his grace. It is to be remembered that Jesus Christ, when he came
to found the Christian dispensation, did not choose his apostles from
the chief priests and the scribes, learned in the law, and high in the
church; nor did he choose them from philosophers and poets, whose
educated and comprehensive minds might be supposed best able to
appreciate his great designs; but he chose twelve plain, poor
fishermen, who were ignorant, and felt that they were ignorant, and
who, therefore, were willing to give themselves up with all simplicity
to his guidance. What God asks of the soul more than anything else
is faith and simplicity, the affection and reliance of the little child.
Even these twelve fancied too much that they were wise, and Jesus
was obliged to set a little child in the midst of them, as a more
perfect teacher.
The negro race is confessedly more simple, docile, childlike and
affectionate, than other races; and hence the divine graces of love
and faith, when in-breathed by the Holy Spirit, find in their natural
temperament a more congenial atmosphere.
A last instance parallel with that of Uncle Tom is to be found in the
published memoirs of the venerable Josiah Henson, now, as we have
said, a clergyman in Canada. He was “raised” in the State of
Maryland. His first recollections were of seeing his father mutilated
and covered with blood, suffering the penalty of the law for the
crime of raising his hand against a white man,—that white man
being the overseer, who had attempted a brutal assault upon his
mother. This punishment made his father surly and dangerous, and
he was subsequently sold south, and thus parted forever from his
wife and children. Henson grew up in a state of heathenism, without
any religious instruction, till, in a camp-meeting, he first heard of
Jesus Christ, and was electrified by the great and thrilling news that
He had tasted death for every man, the bond as well as the free.
This story produced an immediate conversion, such as we read of in
the Acts of the Apostles, where the Ethiopian eunuch, from one
interview, hearing the story of the cross, at once believes and is
baptized. Henson forthwith not only became a Christian, but began
to declare the news to those about him; and, being a man of great
natural force of mind and strength of character, his earnest
endeavors to enlighten his fellow-heathen were so successful that he
was gradually led to assume the station of a negro preacher; and
though he could not read a word of the Bible or hymn-book, his
labors in this line were much prospered. He became immediately a
very valuable slave to his master, and was intrusted by the latter
with the oversight of his whole estate, which he managed with great
judgment and prudence. His master appears to have been a very
ordinary man in every respect,—to have been entirely incapable of
estimating him in any other light then as exceedingly valuable
property, and to have had no other feeling excited by his
extraordinary faithfulness than the desire to make the most of him.
When his affairs became embarrassed, he formed the design of
removing all his negroes into Kentucky, and intrusted the operation
entirely to his overseer. Henson was to take them alone, without any
other attendant, from Maryland to Kentucky, a distance of some
thousands of miles, giving only his promise as a Christian that he
would faithfully perform this undertaking. On the way thither they
passed through a portion of Ohio, and there Henson was informed
that he could now secure his own freedom and that of all his fellows,
and he was strongly urged to do it. He was exceedingly tempted and
tried, but his Christian principle was invulnerable. No inducements
could lead him to feel that it was right for a Christian to violate a
pledge solemnly given, and his influence over the whole band was
so great that he took them all with him into Kentucky. Those casuists
among us who lately seem to think and teach that it is right for us to
violate the plain commands of God whenever some great national
good can be secured by it, would do well to contemplate the
inflexible principle of this poor slave, who, without being able to read
a letter of the Bible, was yet enabled to perform this most sublime
act of self-renunciation in obedience its commands. Subsequently to
this his master, in a relenting moment, was induced by a friend to
sell him his freedom for four hundred dollars; but, when the
excitement of the importunity had passed off, he regretted that he
had suffered so valuable a piece of property to leave his hands for so
slight a remuneration. By an unworthy artifice, therefore, he got
possession of his servant’s free papers, and condemned him still to
hopeless slavery. Subsequently, his affairs becoming still more
involved, he sent his son down the river with a flat-boat loaded with
cattle and produce for the New Orleans market, directing him to take
Henson along, and sell him after they had sold the cattle and the
boat. All the depths of the negro’s soul were torn up and thrown into
convulsion by this horrible piece of ingratitude, cruelty and injustice;
and, while outwardly calm, he was struggling with most bitter
temptations from within, which, as he could not read the Bible, he
could repel only by a recollection of its sacred truths, and by earnest
prayer. As he neared the New Orleans market, he says that these
convulsions of soul increased, especially when he met some of his
old companions from Kentucky, whose despairing countenances and
emaciated forms told of hard work and insufficient food, and
confirmed all his worst fears of the lower country. In the transports
of his despair, the temptation was more urgently presented to him to
murder his young master and the other hand on the flat-boat in their
sleep, to seize upon the boat, and make his escape. He thus relates
the scene where he was almost brought to the perpetration of this
deed:
One dark, rainy night, within a few days of New Orleans, my hour seemed to have
come. I was alone on the deck; Mr. Amos and the hands were all asleep below,
and I crept down noiselessly, got hold of an axe, entered the cabin, and looking by
the aid of the dim light there for my victims, my eye fell upon Master Amos, who
was nearest to me; my hand slid along the axe-handle, I raised it to strike the
fatal blow,—when suddenly the thought came to me, “What! commit murder! and
you a Christian?” I had not called it murder before. It was self-defence,—it was
preventing others from murdering me,—it was justifiable, it was even
praiseworthy. But now, all at once, the truth burst upon me that it was a crime. I
was going to kill a young man, who had done nothing to injure me, but obey
commands which he could not resist; I was about to lose the fruit of all my efforts
at self-improvement, the character I had acquired, and the peace of mind which
had never deserted me. All this came upon me instantly, and with a distinctness
which made me almost think I heard it whispered in my ear; and I believe I even
turned my head to listen. I shrunk back, laid down the axe, crept up on deck
again, and thanked God, as I have done every day since, that I had not committed
murder.
My feelings were still agitated, but they were changed. I was filled with shame and
remorse for the design I had entertained, and with the fear that my companions
would detect it in my face, or that a careless word would betray my guilty
thoughts. I remained on deck all night, instead of rousing one of the men to
relieve me; and nothing brought composure to my mind, but the solemn resolution
I then made to resign myself to the will of God, and take with thankfulness, if I
could, but with submission, at all events, whatever he might decide should be my
lot. I reflected that if my life were reduced to a brief term I should have less to
suffer, and that it was better to die with a Christian’s hope, and a quiet conscience,
than to live with the incessant recollection of a crime that would destroy the value
of life, and under the weight of a secret that would crush out the satisfaction that
might be expected from freedom, and every other blessing.
Subsequently to this, his young master was taken violently down
with the river fever, and became as helpless as a child. He
passionately entreated Henson not to desert him, but to attend to
the selling of the boat and produce, and put him on board the
steamboat, and not to leave him, dead or alive, till he had carried
him back to his father.
The young master was borne in the arms of his faithful servant to
the steamboat, and there nursed by him with unremitting attention
during the journey up the river; nor did he leave him till he had
placed him in his father’s arms.
Our love for human nature would lead us to add, with sorrow, that
all this disinterestedness and kindness was rewarded only by empty
praises, such as would be bestowed upon a very fine dog; and
Henson indignantly resolved no longer to submit to the injustice.
With a degree of prudence, courage and address, which can scarcely
find a parallel in any history, he managed, with his wife and two
children, to escape into Canada. Here he learned to read, and, by his
superior talent and capacity for management, laid the foundation for
the fugitive settlement of Dawn, which is understood to be one of
the most flourishing in Canada.
It would be well for the most cultivated of us to ask, whether our
ten talents in the way of religious knowledge have enabled us to
bring forth as much fruit to the glory of God, to withstand
temptation as patiently, to return good for evil as disinterestedly, as
this poor, ignorant slave. A writer in England has sneeringly
remarked that such a man as Uncle Tom might be imported as a
missionary to teach the most cultivated in England or America the
true nature of religion. These instances show that what has been
said with a sneer is in truth a sober verity; and it should never be
forgotten that out of this race whom man despiseth have often been
chosen of God true messengers of his grace, and temples for the
indwelling of his Spirit.
“For thus saith the high and lofty One that inhabiteth eternity, whose
name is Holy, I dwell in the high and holy place, with him also that is
of a contrite and humble spirit, to revive the spirit of the humble,
and to revive the heart of the contrite ones.”
The vision attributed to Uncle Tom introduces quite a curious chapter
of psychology with regard to the negro race, and indicates a
peculiarity which goes far to show how very different they are from
the white race. They are possessed of a nervous organization
peculiarly susceptible and impressible. Their sensations and
impressions are very vivid, and their fancy and imagination lively. In
this respect the race has an oriental character, and betrays its
tropical origin. Like the Hebrews of old and the oriental nations of
the present, they give vent to their emotions with the utmost
vivacity of expression, and their whole bodily system sympathizes
with the movements of their minds. When in distress, they actually
lift up their voices to weep, and “cry with an exceeding bitter cry.”
When alarmed, they are often paralyzed, and rendered entirely
helpless. Their religious exercises are all colored by this sensitive and
exceedingly vivacious temperament. Like oriental nations, they
incline much to outward expressions, violent gesticulations, and
agitating movements of the body. Sometimes, in their religious
meetings, they will spring from the floor many times in succession,
with a violence and rapidity which is perfectly astonishing. They will
laugh, weep, embrace each other convulsively, and sometimes
become entirely paralyzed and cataleptic. A clergyman from the
North once remonstrated with a Southern clergyman for permitting
such extravagances among his flock. The reply of the Southern
minister was, in effect, this: “Sir, I am satisfied that the races are so
essentially different that they cannot be regulated by the same rules.
I, at first, felt as you do; and, though I saw that genuine conversions
did take place, with all this outward manifestation, I was still so
much annoyed by it as to forbid it among my negroes, till I was
satisfied that the repression of it was a serious hindrance to real
religious feeling; and then I became certain that all men cannot be
regulated in their religious exercises by one model. I am assured
that conversions produced with these accessories are quite as apt to
be genuine, and to be as influential over the heart and life, as those
produced in any other way.” The fact is, that the Anglo-Saxon race—
cool, logical and practical—have yet to learn the doctrine of
toleration for the peculiarities of other races; and perhaps it was
with a foresight of their peculiar character, and dominant position in
the earth, that God gave the Bible to them in the fervent language
and with the glowing imagery of the more susceptible and
passionate oriental races.
Mesmerists have found that the negroes are singularly susceptible to
all that class of influences which produce catalepsy, mesmeric sleep,
and partial clairvoyant phenomena.
The African race, in their own climate, are believers in spells, in
“fetish and obi,” in “the evil eye,” and other singular influences, for
which, probably, there is an origin in this peculiarity of constitution.
The magicians in scriptural history were Africans; and the so-called
magical arts are still practised in Egypt, and other parts of Africa,
with a degree of skill and success which can only be accounted for
by supposing peculiarities of nervous constitution quite different
from those of the whites. Considering those distinctive traits of the
race, it is no matter of surprise to find in their religious histories,
when acted upon by the powerful stimulant of the Christian religion,
very peculiar features. We are not surprised to find almost
constantly, in the narrations of their religious histories, accounts of
visions, of heavenly voices, of mysterious sympathies and
transmissions of knowledge from heart to heart without the
intervention of the senses, or what the Quakers call being “baptized
into the spirit” of those who are distant.
Cases of this kind are constantly recurring in their histories. The
young man whose story was related to the Boston lady, and
introduced above in the chapter on George Harris, stated this
incident concerning the recovery of his liberty: That, after the
departure of his wife and sister, he, for a long time, and very
earnestly, sought some opportunity of escape, but that every avenue
appeared to be closed to him. At length, in despair, he retreated to
his room, and threw himself upon his bed, resolving to give up the
undertaking, when, just as he was sinking to sleep, he was roused
by a voice saying in his ear, “Why do you sleep now? Rise up, if you
ever mean to be free!” He sprang up, went immediately out, and, in
the course of two hours, discovered the means of escape which he
used.
A lady whose history is known to the writer resided for some time on
a Southern plantation, and was in the habit of imparting religious
instruction to the slaves. One day, a woman from a distant
plantation called at her residence, and inquired for her. The lady
asked, in surprise, “How did you know about me?” The old woman’s
reply was, that she had long been distressed about her soul; but
that, several nights before, some one had appeared to her in a
dream, told her to go to this plantation and inquire for the strange
lady there, and that she would teach her the way to heaven.
Another specimen of the same kind was related to the writer by a
slave-woman who had been through the whole painful experience of
a slave’s life. She was originally a young girl of pleasing exterior and
gentle nature, carefully reared as a seamstress and nurse to the
children of a family in Virginia, and attached, with all the warmth of
her susceptible nature, to these children. Although one of the
tenderest of mothers when the writer knew her, yet she assured the
writer that she had never loved a child of her own as she loved the
dear little young mistress who was her particular charge. Owing,
probably, to some pecuniary difficulty in the family, this girl, whom
we will call Louisa, was sold, to go on to a Southern plantation. She
has often described the scene when she was forced into a carriage,
and saw her dear young mistress leaning from the window,
stretching her arms towards her, screaming, and calling her name,
with all the vehemence of childish grief. She was carried in a coffle,
and sold as cook on a Southern plantation. With the utmost
earnestness of language she has described to the writer her utter
loneliness, and the distress and despair of her heart, in this
situation, parted forever from all she held dear on earth, without
even the possibility of writing letters or sending messages,
surrounded by those who felt no kind of interest in her, and forced
to a toil for which her more delicate education had entirely unfitted
her. Under these circumstances, she began to believe that it was for
some dreadful sin she had thus been afflicted. The course of her
mind after this may be best told in her own simple words:
“After that, I began to feel awful wicked,—O, so wicked, you’ve no
idea! I felt so wicked that my sins seemed like a load on me, and I
went so heavy all the day! I felt so wicked that I didn’t feel worthy
to pray in the house, and I used to go way off in the lot and pray. At
last, one day, when I was praying, the Lord he came and spoke to
me.”
“The Lord spoke to you?” said the writer; “what do you mean,
Louisa?”
With a face of the utmost earnestness, she answered, “Why, ma’am,
the Lord Jesus he came and spoke to me, you know; and I never, till
the last day of my life, shall forget what he said to me.”
“What was it?” said the writer.
“He said, ‘Fear not, my little one; thy sins are forgiven thee;’” and
she added to this some verses, which the writer recognized as those
of a Methodist hymn.
Being curious to examine more closely this phenomenon, the author
said,
“You mean that you dreamed this, Louisa.”
With an air of wounded feeling, and much earnestness, she
answered,
“O no, Mrs. Stowe; that never was a dream; you’ll never make me
believe that.”
The thought at once arose in the writer’s mind, If the Lord Jesus is
indeed everywhere present, and if he is as tender-hearted and
compassionate as he was on earth,—and we know he is,—must he
not sometimes long to speak to the poor, desolate slave, when he
knows that no voice but His can carry comfort and healing to his
soul?
This instance of Louisa is so exactly parallel to another case, which
the author received from an authentic source, that she is tempted to
place the two side by side.
Among the slaves who were brought into the New England States, at
the time when slavery was prevalent, was one woman, who,
immediately on being told the history of the love of Jesus Christ,
exclaimed, “He is the one; this is what I wanted.”
This language causing surprise, her history was inquired into. It was
briefly this: While living in her simple hut in Africa, the kidnappers
one day rushed upon her family, and carried her husband and
children off to the slave-ship, she escaping into the woods. On
returning to her desolate home, she mourned with the bitterness of
“Rachel weeping for her children.” For many days her heart was
oppressed with a heavy weight of sorrow; and, refusing all
sustenance, she wandered up and down the desolate forest.
At last, she says, a strong impulse came over her to kneel down and
pour out her sorrows into the ear of some unknown Being whom she
fancied to be above her, in the sky.
She did so; and, to her surprise, found an inexpressible sensation of
relief. After this, it was her custom daily to go out to this same spot,
and supplicate this unknown Friend. Subsequently, she was herself
taken, and brought over to America; and, when the story of Jesus
and his love was related to her, she immediately felt in her soul that
this Jesus was the very friend who had spoken comfort to her
yearning spirit in the distant forest of Africa.
Compare now these experiences with the earnest and beautiful
language of Paul: “He hath made of one blood all nations of men,
for to dwell on all the face of the earth; and hath determined the
times before appointed and the bounds of their habitation, that THEY
SHOULD seek the Lord, if haply they might feel after Him and find Him,
though he be not far from every one of us.”
Is not this truly “feeling after God and finding Him”? And may we not
hope that the yearning, troubled, helpless heart of man, pressed by
the insufferable anguish of this short life, or wearied by its utter
vanity, never extends its ignorant, pleading hand to God in vain? Is
not the veil which divides us from an almighty and most merciful
Father much thinner than we, in the pride of our philosophy, are apt
to imagine? and is it not the most worthy conception of Him to
suppose that the more utterly helpless and ignorant the human
being is that seeks His aid, the more tender and the more
condescending will be His communication with that soul?
If a mother has among her children one whom sickness has made
blind, or deaf, or dumb, incapable of acquiring knowledge through
the usual channels of communication, does she not seek to reach its
darkened mind by modes of communication tenderer and more
intimate than those which she uses with the stronger and more
favored ones? But can the love of any mother be compared with the
infinite love of Jesus? Has He not described himself as that good
Shepherd who leaves the whole flock of secure and well-instructed
ones, to follow over the mountains of sin and ignorance the one lost
sheep; and, when He hath found it, rejoicing more over that one
than over the ninety and nine that went not astray? Has He not told
us that each of these little ones has a guardian angel that doth
always behold the face of his Father which is in heaven? And is it not
comforting to us to think that His love and care will be in proportion
to the ignorance and the wants of His chosen ones?

Since the above was prepared for the press the author has received
the following extract from a letter written by a gentleman in Missouri
to the editor of the Oberlin (Ohio) Evangelist:
I really thought, while reading “Uncle Tom’s Cabin,” that the authoress, when
describing the character of Tom, had in her mind’s eye a slave whose acquaintance
I made some years since, in the State of Mississippi, called “Uncle Jacob.” I was
staying a day or two with a planter, and in the evening, when out in the yard, I
heard a well-known hymn and tune sung in one of the “quarters,” and then the
voice of prayer; and O, such a prayer! what fervor, what unction,—nay, the man
“prayed right up;” and when I read of Uncle Tom, how “nothing could exceed the
touching simplicity, the childlike earnestness, of his prayer, enriched with the
language of Scripture, which seemed so entirely to have wrought itself into his
being as to have become a part of himself,” the recollections of that evening
prayer were strangely vivid. On entering the house and referring to what I had
heard, his master replied, “Ah, sir, if I covet anything in this world, it is Uncle
Jacob’s religion. If there is a good man on earth, he certainly is one.” He said
Uncle Jacob was a regulator on the plantation; that a word or a look from him,
addressed to younger slaves, had more efficacy than a blow from the overseer.
The next morning Uncle Jacob informed me he was from Kentucky, opposite
Cincinnati; that his opportunities for attending religious worship had been
frequent; that at about the age of forty he was sold south, was set to picking
cotton; could not, when doing his best, pick the task assigned him; was whipped
and whipped, he could not possibly tell how often; was of the opinion that the
overseer came to the conclusion that whipping could not bring one more pound
out of him, for he set him to driving a team. At this and other work he could
“make a hand;” had changed owners three or four times. He expressed himself as
well pleased with his present situation as he expected to be in the South, but was
yearning to return to his former associations in Kentucky.
 CHAPTER VII.
MISS OPHELIA.

Miss Ophelia stands as the representative of a numerous class of the

very best of Northern people; to whom, perhaps, if our Lord should
again address his churches a letter, as he did those of old time, he
would use the same words as then: “I know thy works, and thy
labor, and thy patience, and how thou canst not bear them which
are evil; and thou hast tried them which are apostles and are not,
and hast found them liars; and hast borne, and hast patience, and
for my name’s sake hast labored and hast not fainted. Nevertheless,
I have somewhat against thee, because thou hast left thy first love.”
There are in this class of people activity, zeal, unflinching
conscientiousness, clear intellectual discriminations between truth
and error, and great logical and doctrinal correctness; but there is a
want of that spirit of love, without which, in the eye of Christ, the
most perfect character is as deficient as a wax flower—wanting in
life and perfume.
Yet this blessed principle is not dead in their hearts, but only
sleepeth; and so great is the real and genuine goodness, that, when
the true magnet of divine love is applied, they always answer to its
touch.
So when the gentle Eva, who is an impersonation in childish form of
the love of Christ, solves at once, by a blessed instinct, the problem
which Ophelia has long been unable to solve by dint of utmost
hammering and vehement effort, she at once, with a good and
honest heart, perceives and acknowledges her mistake, and is willing
to learn even of a little child.
Miss Ophelia, again, represents one great sin, of which,
unconsciously, American Christians have allowed themselves to be
guilty. Unconsciously it must be, for nowhere is conscience so
predominant as among this class, and nowhere is there a more
honest strife to bring every thought into captivity to the obedience of
Christ.
One of the first and most declared objects of the gospel has been to
break down all those irrational barriers and prejudices which
separate the human brotherhood into diverse and contending clans.
Paul says, “In Christ Jesus there is neither Jew nor Greek, barbarian,
Scythian, bond nor free.” The Jews at that time were separated from
the Gentiles by an insuperable wall of prejudice. They could not eat
and drink together, nor pray together. But the apostles most
earnestly labored to show them the sin of this prejudice. St. Paul
says to the Ephesians, speaking of this former division, “He is our
peace, who hath made both one, and hath broken down the middle
wall of partition between us.”
It is very easy to see that although slavery has been abolished in the
New England States, it has left behind it the most baneful feature of
the system—that which makes American worse than Roman slavery
—the prejudice of caste and color. In the New England States the
negro has been treated as belonging to an inferior race of beings;—
forced to sit apart by himself in the place of worship; his children
excluded from the schools; himself excluded from the railroad-car
and the omnibus, and the peculiarities of his race made the subject
of bitter contempt and ridicule.
This course of conduct has been justified by saying that they are a
degraded race. But how came they degraded? Take any class of
men, and shut them from the means of education, deprive them of
hope and self-respect, close to them all avenues of honorable
ambition, and you will make just such a race of them as the negroes
have been among us.
So singular and so melancholy is the dominion of prejudice over the
human mind, that professors of Christianity in our New England
States have often, with very serious self-denial to themselves, sent
the gospel to heathen as dark-complexioned as the Africans, when in
their very neighborhood were persons of dark complexion, who, on
that account, were forbidden to send their children to the schools,
and discouraged from entering the churches. The effect of this has
been directly to degrade and depress the race, and then this very
degradation and depression has been pleaded as the reason for
continuing this course.
Not long since the writer called upon a benevolent lady, and during
the course of the call the conversation turned upon the incidents of
a fire which had occurred the night before in the neighborhood. A
deserted house had been burned to the ground. The lady said it was
supposed it had been set on fire. “What could be any one’s motive
for setting it on fire?” said the writer.
“Well,” replied the lady, “it was supposed that a colored family was
about to move into it, and it was thought that the neighborhood
wouldn’t consent to that. So it was supposed that was the reason.”
This was said with an air of innocence and much unconcern.
The writer inquired, “Was it a family of bad character?”
“No, not particularly, that I know of,” said the lady; “but then they
are negroes, you know.”
Now, this lady is a very pious lady. She probably would deny herself
to send the gospel to the heathen, and if she had ever thought of
considering this family a heathen family, would have felt the deepest
interest in their welfare; because on the subject of duty to the
heathen she had been frequently instructed from the pulpit, and had
all her religious and conscientious sensibilities awake. Probably she
had never listened from the pulpit to a sermon which should exhibit
the great truth, that “in Christ Jesus there is neither Jew nor Greek,
barbarian, Scythian, bond nor free.”
Supposing our Lord was now on earth, as he was once, what course
is it probable that he would pursue with regard to this unchristian
prejudice of color?
There was a class of men in those days as much despised by the
Jews as the negroes are by us; and it was a complaint made of
Christ that he was a friend of publicans and sinners. And if Christ
should enter, on some communion season, into a place of worship,
and see the colored man sitting afar off by himself, would it not be
just in his spirit to go there and sit with him, rather than to take the
seats of his richer and more prosperous brethren?
It is, however, but just to our Northern Christians to say that this sin
has been committed ignorantly and in unbelief, and that within a few
years signs of a much better spirit have begun to manifest
themselves. In some places, recently, the doors of school-houses
have been thrown open to the children, and many a good Miss
Ophelia has opened her eyes in astonishment to find that, while she
has been devouring the Missionary Herald, and going without butter
on her bread and sugar in her tea to send the gospel to the
Sandwich Islands, there is a very thriving colony of heathen in her
own neighborhood at home; and, true to her own good and honest
heart, she has resolved, not to give up her prayers and efforts for
the heathen abroad, but to add thereunto labors for the heathen at
home.
Our safety and hope in this matter is this: that there are multitudes
in all our churches who do most truly and sincerely love Christ above
all things, and who, just so soon as a little reflection shall have made
them sensible of their duty in this respect, will most earnestly
perform it.
It is true that, if they do so, they may be called Abolitionists; but the
true Miss Ophelia is not afraid of a hard name in a good cause, and
has rather learned to consider “the reproach of Christ a greater
treasure than the riches of Egypt.”
That there is much already for Christians to do in enlightening the
moral sense of the community on this subject, will appear if we
consider that even so well-educated and gentlemanly a man as
Frederick Douglass was recently obliged to pass the night on the
deck of a steamer, when in delicate health, because this senseless
prejudice deprived him of a place in the cabin; and that that very
laborious and useful minister, Dr. Pennington, of New York, has,
during the last season, been often obliged seriously to endanger his
health, by walking to his pastoral labors, over his very extended
parish, under a burning sun, because he could not be allowed the
common privilege of the omnibus, which conveys every class of
white men, from the most refined to the lowest and most disgusting.
Let us consider now the number of professors of the religion of
Christ in New York, and consider also that, by the very fact of their
profession, they consider Dr. Pennington the brother of their Lord,
and a member with them of the body of Christ.
Now, these Christians are influential, rich and powerful; they can
control public sentiment on any subject that they think of any
particular importance, and they profess, by their religion, that “if one
member suffers, all the members suffer with it.”
It is a serious question, whether such a marked indignity offered to
Christ and his ministry, in the person of a colored brother, without
any remonstrance on their part, will not lead to a general feeling
that all that the Bible says about the union of Christians is a mere
hollow sound, and means nothing.
Those who are anxious to do something directly to improve the
condition of the slave, can do it in no way so directly as by elevating
the condition of the free colored people around them, and taking
every pains to give them equal rights and privileges.
This unchristian prejudice has doubtless stood in the way of the
emancipation of hundreds of slaves. The slave-holder, feeling and
acknowledging the evils of slavery, has come to the North, and seen
evidences of this unkindly and unchristian state of feeling towards
the slave, and has thus reflected within himself:
“If I keep my slave at the South, he is, it is true, under the dominion
of a very severe law; but then he enjoys the advantage of my
friendship and assistance, and derives, through his connection with
me and my family, some kind of a position in the community. As my
servant he is allowed a seat in the car and a place at the table. But if
I emancipate and send him North, he will encounter substantially all
the disadvantages of slavery, with no master to protect him.”
This mode of reasoning has proved an apology to many a man for
keeping his slaves in a position which he confesses to be a bad one;
and it will be at once perceived that, should the position of the
negro be conspicuously reversed in our northern states, the effect
upon the emancipation of the slave would be very great. They, then,
who keep up this prejudice, may be said to be, in a certain sense,
slave-holders.
It is not meant by this that all distinctions of society should be
broken over, and that people should be obliged to choose their
intimate associates from a class unfitted by education and habits to
sympathize with them.
The negro should not be lifted out of his sphere of life because he is
a negro, but he should be treated with Christian courtesy in his
sphere. In the railroad car, in the omnibus and steamboat, all ranks
and degrees of white persons move with unquestioned freedom side
by side; and Christianity requires that the negro have the same
privilege.
That the dirtiest and most uneducated foreigner or American, with
breath redolent of whiskey and clothes foul and disordered, should
have an unquestioned right to take a seat next to any person in a
railroad car or steamboat, and that the respectable, decent and
gentlemanly negro should be excluded simply because he is a negro,
cannot be considered otherwise than as an irrational and unchristian
thing: and any Christian who allows such things done in his presence
without remonstrance, and the use of his Christian influence, will
certainly be made deeply sensible of his error when he comes at last
to direct and personal interview with his Lord.
There is no hope for this matter, if the love of Christ is not strong
enough, and if it cannot be said, with regard to the two races, “He is
Welcome to Our Bookstore - The Ultimate Destination for Book Lovers
Are you passionate about books and eager to explore new worlds of
knowledge? At our website, we offer a vast collection of books that
cater to every interest and age group. From classic literature to
specialized publications, self-help books, and children’s stories, we
have it all! Each book is a gateway to new adventures, helping you
expand your knowledge and nourish your soul
Experience Convenient and Enjoyable Book Shopping Our website is more
than just an online bookstore—it’s a bridge connecting readers to the
timeless values of culture and wisdom. With a sleek and user-friendly
interface and a smart search system, you can find your favorite books
quickly and easily. Enjoy special promotions, fast home delivery, and
a seamless shopping experience that saves you time and enhances your
love for reading.
Let us accompany you on the journey of exploring knowledge and
personal growth!

ebookball.com