Programming Fundamentals Using MATLAB Analyze

Data And Develop Algorithms 1st Edition by

Michael Weeks B09NZC2XC1 download

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

Instantly Access and Download Textbook at https://ebookball.com

 Get Your Digital Files Instantly: PDF, ePub, MOBI and More
Quick Digital Downloads: PDF, ePub, MOBI and Other Formats

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/

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/

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/

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

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/

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/

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/

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/
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
Other documents randomly have
different content
silta ja koko se kehä vuoria ja kukkuloita, jotka ympäröivät sisimmän
osan Puteolin lahtea, lukemattomien tulisoihtujen valossa. Kaikki tuo
muistuttaa jättiläisteatteria. Sillalla, joka nyt on avattu suurelle
yleisölle, vilisee iloisia ihmisparvia, silloin kuuluu yhdellä erää vihlova
huuto. Gajus Cesarin viittauksesta syöstään kävelijät mereen. Niiden
yli, jotka pysyttelevät uiden pinnalla tai jotka ovat tarttuneet
laivanruoreihin ja ankkuriketjuihin, sataa kangen- ja aironiskuja,
kunnes he vajoavat syvyyteen.

Kauan puhuttiin Bajæssa tästä koirankurista, kauemmin kuin

Cesarin kylvyistä hyvätuoksuisissa esanseissa tai hänen
päivällisistään, jotka nielivät miljonia.

Kaligula haaveksi rakentamista; mutta melkein kaikki, mitä hän

rakennutti, oli tarkoituksetonta kuten mainittu siltakin. On vaikeata
ajatella taiteilijoita ikävämmässä asemassa kuin hänen arkkitehtinsä
olivat. Gajuksella oli oma makunsa kirjoihin ja taideluomiin nähden,
eikä yksikään pienokainen koulunpenkillä ole urheammin hyljännyt
kaikkea, mikä siihen saakka on ollut kauneuden esikuvana. Tästä
terävästä arvostelijasta oli Virgilius pölkkypää, Livius lörpöttelijä;
kerrotaan, että hän oli aikonut heittää Homeroksen laulut yleisesti
hävitettäväksi, ehkä muistellen sitä ankaruutta, jolla Tiberius oli
vaatinut hänen lukemaan niitä. Kaikkien täytyi taipua Gajuksen
makuun, ja todennäköistä on, että tuo suuri määrä siihen aikaan niin
tavallisia Virgiliuspatsaita hävisi hänen hallitessaan: meidän aikamme
osaksi ei ole tullut yhtään, mutta arviolta on annettu runoilijan nimi
eräälle Kapitoliumin museossa olevalle antiikiselle rintakuvalle, johon
on herttaisesti yhtynyt hänen runottarensa ja luonteensa piirteet.
Gajuksen arvostelut arkitehtuurista olivat aivan yhtä repivää laatua.
Huvilinnojaan ja huviloitaan varten hän teki suunnitelmia, joita hän
luuli nerokkaiksi sikäli kuin ne sotivat tervettä järkeä vastaan.
Rakennusmestarin tuli totella ja pitää huoli siitä, jos elämänsä oli
hänelle kallis, että kaikki oli valmiina sen ajan kuluessa, jonka Cesar
kärsimättömyydessään oli määrännyt.

Lähellä Karakallan termejä ja Porta San Sebastianoa on

kolumbariumi, johon Augustuksen vapautetut orjat ovat haudatut.
Siellä on komero, joka on koristettu barokin maun mukaan
typistetyllä kiekuralla. Ei odottanut antiikin pohjalla tapaavansa
ennusmerkkiä siitä tyylistä, joka enemmän kuin puolentoista
tuhannen vuoden päästä kaunistaisi Rooman kirkkoja ja portteja
kiharilla tekotukilla; mutta huomaa kohta, että maku ei ole
synnyttänyt tätä kummallisuutta, vaan on tilanpuute pakottanut sen.
Jos aika olisi säästänyt jonkun Kaligulan huvilinnoista, niin epäilen,
että meitä olisi siellä hämmästyttänyt moni pieni esitunne barokki- ja
rokokotyylistä. Mutta näistä rakennuksista on jäljellä ainoastaan
hänen Palatinuksella olevan keisarilinnansa mahtavat rauniot ja sen
sillan tukimuuri, jonka hän tältä kukkulalta rakennutti korkealle
forum romanumin yli Kapitoliumin toiselle huipulle. Silta oli tienä
kahden korkean jumalan välillä, silloinkuin nämä tahtoivat neuvotella
tärkeistä asioista. Toinen jumalista oli Jupiter Kapitolinus; toinen jolle
keisari oli rakennuttanut temppeleitä, perustanut papistoja,
pystyttänyt kultapatsaita ja miettinyt kalliita ja oivallisia uhreja — oli
Gajus itse. Heidän puhelunsa tapahtui siten, että Gajus, jota myös
Jupiter Latiarikseksi nimitettiin, kuiskasi jumaltoverinsa korvaan ja
asetti sitten oman korvansa hänen suulleen. Toisinaan kohotti Jupiter
Latiaris uhkaavasti äänensä. Jupiter Kapitolinuksella, joka ei
milloinkaan vastannut samalla äänellä, oli kuitenkin syytä napista,
ellei omasta niin sukulaistensa puolesta, sillä keisari oli tuotattanut
Roomaan joukon Kreikan ihanimpia jumalankuvia ja hakkauttanut
niiltä päät poikki antaakseen niille toiset, joilla oli hänen omat
kasvonpiirteensä, ja kerrottiin, että hän oli aikonut Olympon Zeulle
saman kohtalon.

Tämä muistuttaa kieltämättä hulluutta. Kaligulan aikalaiset

epäilivätkin, että hänen aivonsa eivät olleet kunnossa. Kuiskailtiin
rakkaudenjuomasta, joka oli hämmentänyt hänen järkensä. Mutta
antakaa kaikkivalta pojannulikalle, asettakaa orjia tai imartelijoita
hänen valtaistuimensa ympäri, ja mielettömyys on ilmenevä ilman
Kanidiaksen taitoja.

Gajus oli kateellinen. Ne suurten miesten patsaat, jotka Augustus

oli siirtänyt ääriään myöten täynnä olevalta Kapitoliumilta
Marskentälle, murskasi hän kappaleiksi, sillä Roomalle oli kylliksi yksi
suuruus. Jos hän huomasi, että kaunis mies teatterissa veti
puoleensa naisten katseet, niin voi sitä miestä! Hän oli kuoleman
oma; hän oli varastanut Cesarilta sen suosion, jota kauniimpi
sukupuoli oli velvollinen yksinomaan hänelle osoittamaan. Kateus
esiintyy lapsen koko teeskentelemättömyydellä, kun kansa taputtaa
käsiään vaunutaistelija Poriukselle, joka voitosta iloiten vapauttaa
orjansa. Kaligula huutaa istuimeltaan: "tämä kansa kunnioittaa
enemmän gladiaattoria kuin ruhtinastaan", ja hän syöksyy niin
kiivaasti ulos, että sotkeutuu toogaan ja suistuu portaita alas.
Sellaisessa tilaisuudessa hän toivoi, että Rooman kansalla olisi ollut
yksi kaula pyövelien huojennukseksi.

Hänen tyranniallaan on, kuten ennen on huomautettu, kokonaan

toinen leima kuin Tiberiuksen. Toinen on julmuudessaan viekas ja
laskeva, toinen ajattelematon ja ilkivaltainen. Pelkästä
juonikkaisuudesta hän herättää kaikkien luokkien vihan etsimättä
kenestäkään tukea. Hän antaa senaattorien toogaan puettuina
juosta tuhansia askeleita vaunujensa vieressä; juhlissa, joita hän
vietti näyttelijäin ja irstaiden naisten kanssa, olivat senaattorit
orjanpuvussa pöytäpalvelijoina. Ritarisäätyä hän ei pidä sellaisen
alennuksen arvoisena; mutta hänen huvituksiinsa kuuluu asettaa
jätkiä sirkuksen ja amfiteatterin ritaripenkkeihin ja katsella
tappeluita, joita siitä syntyy. Rikkaita kansalaisia hän pusertaa kuin
sieniä tyhjennettyään vajaassa vuodessa Tiberiuksen aarrekammion.
Joskus hän antaa tälle hankkimistavalle hullunkurisen leiman, kuten
silloin, kun vanha Aponius Saturninus, joka on sattunut
nukahtamaan eräässä keisarin toimeenpanemassa julkisessa
huutokaupassa ja unessa nyökkäämään päätään
huutokaupanpitäjälle, huomaa itsensä herättyään Cesarin
kolmentoista gladiaattorin omistajaksi 1 1/2 miljonan kruunun
kauppahinnasta. Joita elinaikana ei imetty tyhjiin, niiden täytyi tehdä
Cesar perillisekseen ja odottaa myrkytystä. Hänen ahneutensa,
samoinkuin hänen ilkivaltansakin, kohtasi köyhiäkin. Kantajien täytyi
luovuttaa keisarille kahdeksas osa päiväpalkastaan. Kun vilja-aitat
olivat täynnä, huvitti häntä sulkea ne ja antaa joukkojen nähdä
nälkää. Legioonia hän ei myöskään empinyt härsyttää. Kun Kaligula
lapsena oleskeli vanhempiensa luona leirissä Reinin rannalla, olivat
Germanian legioonat nousseet kapinaan. Nyt, noin kaksikymmentä
vuotta myöhemmin, tahtoi hän surmauttaa heidät viimeiseen
mieheen saakka; mutta muutti ympäristönsä hartaista rukouksista
päätöksensä siten, että ottaisi verikymmenykset heiltä. Dio
Kassiuksen mukaan hän pani toimeen ajatuksensa; Suetoniuksen
mukaan pakeni hän paikalta ja luopui aikeesta, kun legioonissa,
jotka olivat kutsutut kokoon aseitta ja saarretut ratsujoukoilla,
muutamat sotamiehet aavistivat petosta ja riensivät tarttumaan
miekkoihinsa.

Aikakirjat kätkevät muutamia Kaligulan lausuntoja, jotka tekevät

mahdolliseksi silmäyksen hänen sieluunsa. Itse ylisti hän
horjumatonta lujuuttaan parhaaksi ja kuvaavimmaksi
ominaisuudekseen. Tämä lausunto heittää valonvälkähdyksen hänen
sisäiseen maailmaansa. Psykolooginen kokemus osoittaa
poikkeuksetta, että sydämettömät ihmiset ihailevat itseään
lujamielisinä. Ajaja, joka ruoskaniskuilla raatelee kaakkinsa
haavoittunutta selkää, luulee olevansa lujatahtoinen mies, niin kauan
kuin hänen oma selkänsä on vapaana, ja toisten sääli vahvistaa vain
hänen itseihailuaan. Pelkurien sydämettömyys on toinen sääntö, jota
sen poikkeukset eivät kumoa. Cowards are cruel, lausuu Gay ja on
siinä oikeassa, vaikkakaan hän ei aina ole lisätessään:

but the brave Love mercy

and delight to save.

Kaligulan pelkuruus on tunnettu. Hänen elämäkerrankirjoittajansa

kertovat surullisen hullunkurisia todistuksia siitä. Hänen kuviteltu
lujuutensa ei kestänyt edes uhkaavan vaaran näkyä. Mutta arka
poika, jota lujakourainen mies suojelee, luulee voivansa haastaa
kanssansa taisteluun kokonaisen maailman. Kaligula, jota ympäröi
hyvinpalkattu joukko rotevakasvuisia germaaneja ja vapautettuja
gladiaattoreita, luuli samaa. Pelkuruus sopii hyvin yhteen uhman
kanssa. Mutta Gajukselle oli uhma samaa kuin rohkeus. Siis: tämä
raukka ihaili itseään lujana ja urhoollisena miehenä ja sai yhä
useammista rikoksista lisäkiihdykettä itseihailulleen. Tiberius kärsi
omantunnontuskia. Kaligula ei kypsynyt milloinkaan niin suureen
ihmisyyteen, että omantunnontuskat olivat hänelle mahdollisia. Kun
hänen isoäitinsä Antonia kerran uskalsi soimata häntä jostakin
ilkityöstä, kohtasi hän kummastuneen silmäparin ja kuuli vastauksen:
oletko unhoittanut, että kaikki on minulle luvallista? Mitä lapsi saa
tehdä, ja mitä siltä ei nimenomaan ole kielletty, se on sille luvallista.
Itse hänen käsityksensä majesteetista oli lastenkamarin syrjäkuva,
missä mörkö on maailman hirvittävin asia. Hänet nähtiin kuvastimen
ääressä harjoittavan ilkeimpiä kasvonilmeitä voidakseen esiintyä
kuten elämän ja kuoleman herralle sopii.

Kaligulalla oli unettomia öitä, mutta niitä saattaa olla, vaikkakaan

omatunto ei ole sairas. Syynä siihen oli pikemmin kuvitteluvoima,
jonka liejussa hirviöt ja iljetykset rypivät, odottaen hetkeä, jolloin
voisivat muuttua teoksi. Hän ei voinut milloinkaan lakata
ihmettelemästä valtansa laajuutta ja iloitsi sitä enemmän sen
äärettömyydestä, mitä kauemmaksi hän eteni yli niiden rajojen, jotka
sisällinen laki on asettanut ulkonaisen herroille. Vastapainon
puutteesta hänen tahtonsa hikoili verta kuten ihmisruumis
ilmanpaineen puutteesta. Usein vartiat näkivät hänen hoippuvan
tähtien välkkeessä ja kuutamossa palatsin laajoissa pylväskäytävissä
tai sillalla, joka kulki yli forum romanumin. Missä asioissa askaroivat
hänen ajatuksensa silloin? Tavallisesti hurjissa
kaunopuhekappaleissa, jotka saivat senaatin kauhuun seuraavana
päivänä. Ennenkuin hän alkoi tällaisen puheen, lausui hän kernaasti
edeltä sanat: "Vedän yötutkielmieni miekan huotrastaan". Erityisesti
häntä huvitti puhua pahantekijäin puolesta ja syyttömien turmioksi,
koska hänen asianajajataitonsa näyttäytyi silloin suuremmaksi.
Siveellisesti tylsämielisenä ei hän silti ollut mikään tyhmyri. Hänellä
oli mielijuohteita, joita ilkeys teroitti, hänellä oli logiikka, jota pahuus
karkaisi, ja tyyli, jolle hirvittävän ihaileminen antoi kantavuutta.

Ellei tämä ihminen ollutkaan täysijärkinen, niin epäilen kuitenkin,

ettei häntä yksityisenä miehenä täydellä syyllä olisi voitu sulkea
hourujenhuoneeseen. Pikemmin hän olisi joutunut
kuritushuoneeseen. Missä hulluuden ja rikoksen raja on, siitä ei ole
vielä päästy selville, vaikkakin jokainen päivä vaatii
syyntakeisuuskysymyksen ratkaisemista. Että Kaligula rakensi linnan
lemmikkihevoselleen Incitatukselle ja valitsi sille hovikunnan, sitä
eivät taida ainakaan ratsastusseuramme katsoa järjettömyyden
merkiksi, eikä myöskään ole niin hullua, että hän aikoi tehdä
Incitatuksen Rooman konsuliksi. Huonompia konsuleita oli Roomalla
ollut, ja tätä arvoa seuraavat virkatehtävät eivät olleet enää niin
tärkeät, että Incitatus ei olisi voinut hoitaa niitä tallirengin avulla.

Kaksi miestä Kaligulan hovissa oli hänen säälimättömän pilansa

esineitä. Toinen oli hänen setänsä Klaudius, toinen kaartineversti
Kassius Kerea. Tämän verrattomat miehuudennäytteet
taistelukentällä eivät suojelleet häntä häpeällisimmältä pilkalta
keisarilinnassa. Kerea sieti tai näytti sietävän sitä iäkkään sotilaan
jäykällä kärsivällisyydellä; Klaudius oppineen vanhuksen
hajamielisellä levollisuudella. Toisesta tuli Kaligulan surmaaja,
toisesta hänen seuraajansa.

Eräänä päivänä, kun Kaligula lähti teatterista, odotti häntä

holvikäytävässä kaksi kaartineverstiä, joiden tehtävänä oli ottaa
päivän tunnussana. Toinen heistä oli Kerea. Kun tämä muutoin kysyi
tunnussanaa, oli keisarin tavallinen pilkallinen vastaus: Priapus!
Mutta Kerea pysyttelihe tällä kertaa hiukan taampana, ja Kaligula
antoi toiselle everstille tunnussanan: Jupiter! Tuskin sana oli
lausuttu, ennenkuin kajahti huuto: Niinpä kohdatkoon hänen vihansa
sinut! ja Kerean miekka veristyi keisarin ruumiissa. Useita
salaliittolaisia syöksyi hänen kimppuunsa, ja ennenkuin
germaanilainen henkivartio oli ennättänyt esiin, makasi Kaligula
maassa verisenä ja elottomana möhkäleenä.

*****

Ne patsaat ja rintakuvat, joita meillä on Gajus Cesarista,

todistavat, että hänen herkeämätön pyrkimyksensä saavuttaa hirveä
ulkonäkö onnistui verrattain lyhyessä ajassa — hänet surmattiin näet
29:nä elinvuotenaan. Välimatka Kapitoliumin museon galleriassa
olevan kauniin nuorukaisen ja Villa Borghesessa olevan toogakuvan
välillä on suunnaton, vaikkakin yhtäläisyys on silminnähtävä.
Edelliseltä ei tahtoisi tuomita ylevän kehityksen mahdollisuutta.
Ennen mainitusta basalttipäästä saman museon keisarisalissa ei lue
muuta kuin pahaa, mutta vielä, niin sanoaksemme, matkitussa
muodossa. Tässä hän koettaa olla iljettävän näköinen.
Haarniskapatsas Napolissa, sankaripatsas Vatikaanissa ja
toogapatsas Villa Borghesessa ovat kuin merkkipylväitä tiellä
selväpiirteiseen roistouteen. Viimeksi mainitussa taideteoksessa ja
Villa Albanissa olevassa erinomaisessa patsaassa hänet esitetään
papillisessa puvussa, ja tämä, kuten kasvojen ilmekin, johtavat
mieleen tilaisuuden, jolloin hän esiintyi uhraajana ja kaatoi kirveellä
— uhrieläimen? Ei, vaan pahaa aavistamattoman alttaripalvelijan,
joka seisoi vieressä. Villa Borghesen Kaligula viistoine silmineen ja
suussaan ilkeä piirre tuntuu miettivän samallaista pilaa.

Kaligulan kuoleman jälkeen katosivat yhtenä yönä ne

lukemattomat Roomassa olevat patsaat, joilla oli hänen
kasvonpiirteensä. Onnellista on, että hävittämisen into kannustaa
keräämisen intoa. Muutoin ei aikamme voisi verrata Kaligulaa, Neroa,
Kommodusta marmorihahmossa aikakirjojen samoihin miehiin. Gajus
Cesarin Napolin museossa oleva haarniskapatsas kaivettiin esille
Gariglianossa samaan aikaan kuin eräs Trajanuspatsas. Ainoastaan
keräilijän mieleen saattaa juontua säilyttää niitä saman katon alla.
IV.

Jos Klaudius eläisi jälkimaailmalle vain säätäneissään laeissa,

teettämissään rakennuksissa ja niissä patsaissa, joita hänestä vielä
on jäljellä, niin ne houkuttelisivat ehdottomasti imartelevaan
käsitykseen Kaligulan seuraajasta.

Klaudiuspatsaat Rooman museoissa hämmästyttävät. Epäsikiö,

joksi hänen oma äitinsä nimitti häntä, gladiaattorileikkien ystävä,
herkuttelija ja juoppo, oppinut hölmö, tahdoton mielipuoli — kaikki
lausuntoja, joita on kerätty hänen niskoilleen — onko mahdollista,
että hänellä on ollut mitään yhtäläisyyttä näiden kuvien kanssa,
joiden säännöllisistä julilaisista piirteistä säteilee surumielisyys ja
lempeys meitä vastaan.

Niin, päättäen siitä, mitä tiedämme Rooman muotokuvataiteesta,

olemme velvolliset siihen uskomaan. Tätä taidetta ei voi soimata
imartelemisesta. Se antoi, mitä roomalaiset siltä vaativat: jyrkkää,
heltymätöntä luonnonmukaisuutta, eikä se tehnyt poikkeusta
Cesareihin ja heidän perheisiinsäkään nähden, ei edes heidän
naisiinsa.
 Löytää melkein vastenmielisiä todistuksia siitä. Kypsyyden iän yli
ennättänyt keisarinna on esitettävä Venuksena. Mahdollista on, että
hän kernaasti luopuisi tästä kunniasta, ja että hän kernaasti olisi kuin

"die alten, die sich klug verhüllen",

mutta hänellä on Cesarin puolisona velvollisuuksia arvoansa

kohtaan ja hänen täytyy alistua kohtaloonsa.
Rakkaudenjumalatarhan oli julilaisen suvun kantaäiti: senvuoksi
käyvät hänen atribuuttinsa, vaikkakaan ei hänen kauneutensa,
perintönä jokaiselle perheenäidille cesarisen lieden ääressä,
samoinkuin paavi perii pyhän Pietarin avaimet, perimättä ehkä hänen
uskoaan. Ja niin on taiteilijan ikuistutettava hänen alaston sulonsa,
ja hän tekee sen niin totuudenmukaisesti, että se pieni amoriini, joka
sormi suulla seisoo kuvan juuressa, ei voi kuiskata näille suloille
muuta kuin: verhotkaa itsenne!

Voihan sitäpaitsi sanoa, että hienoin imartelu oli pysytellä

todellisuudessa, jonka olisi pitänyt olla kyllin hyvä eikä tarvita taiteen
oikaisuja.

Sitä vaati joka tapauksessa varovaisuus, sillä kokkailijoita ja

irvihampaita oli yllin kyllin toreilla ja kokoussaleissa ja
kylpylaitoksissa, minne keisarilliset kuvat olivat asetetut. Imartelu
olisi herättänyt pilkkaa. Se syy, jonka vuoksi Sturleson kiittää
muinaisajan virsiä suurmiesten urotöistä, kun laulut olivat lauletut
heille itselleen, voidaan sovittaa myöskin keisarikuvien tarkkuuteen:
turhamaisuuteen perustuva, kaikille selvä poikkeaminen totuudesta
— "se olisi ollut pilkkaa, eikä ylistystä".

Ainoastaan niissä patsaissa ja kohokuvissa, jotka esittävät jotakin

keisaria jumalana, voidaan havaita ihannoimista, mutta sellaista,
joka tahtoo kirkastaa luontoa sitä korjaamatta.

Siis on uskottava, että Klaudiuksella on ollut nämä miellyttävät

piirteet. Kaikki eri talttojen luomat ja eriarvoiset kuvat hänestä
todistavat yhtäpitävästi sitä. Ja sitä eivät hänen historioitsijansakaan
kiistä vastaan. Tosin he ovat laskeneet pilaa hänen turhantarkasta
käytöksestään ja huojuvasta käynnistään, mutta yksikään ei ole
väittänyt häntä rumaksi. Suetoniuskin, joka innokkaasti kokosi
kaikkea, mikä voisi saattaa Klaudiuksen muiston naurunalaiseksi,
puhuu "käskevästä arvokkaisuudesta hänen ulkoasussaan, (autoritas
dignitasque formæ), hänen seisoessaan, istuessaan tai levätessään."

Klaudiuspatsas Vatikaanin rotondassa on merkillinen taideteos.

Vanhentunut Hamlet! Se on ensimäinen vaikutus. Mutta Hamlet ja
Klaudius Cesar, Shakspearen hieno romantisen-moderni uneksija, ja
tuo saamaton, heikko, aistillinen ukko Rooman valtaistuimella —
tuollaisen vertailunhan täytyy synnyttää lukuisia vastaväitteitä! Se on
totta, mutta en luovu kuitenkaan siitä uskosta, että Shakspeare oli
lukenut Klaudiuksesta, ennenkuin hän kirjoitti Hamletin, että
Suetoniuksen kuvaus onnettomasta roomalaisesta ruhtinaanpojasta
ja Saxon satu onnettomasta tanskalaisesta olivat yhdistyneet
runoilijan mielikuvituksessa, silloinkuin se loi Hamletin. Surullinen
nuoruus hovissa, joka pakotti heidät teeskentelemään
mielipuolisuutta, oli heille molemmille yhteistä. Ja että Hamlet oli
syvälle kätkeytyneenä Klaudius Cesarin sieluun ja että Shakspearen
terävä katse on löytänyt hänet sieltä ja antanut hänen perhosena
lentää ulos tuosta muodottomasta kuoresta, sen on näkevinään
Vatikaanin patsaasta, jonka mestari, niin sanoaksemme, on veistänyt
marmoriin sen kreikkalaisen sanan, jolla Augustus osui Klaudiuksen
luonteen pääpiirteeseen. Sana, sovitettuna häneen, ei vaadi mitään
selityksiä: kun kuulee sanan meteoria, kuvittelee mielessään liitelyä
äärettömissä avaruuksissa, usman ja pilvien joukossa, empivän
elämän tyhjien unelmien vallassa, jota surullisuus tahdon
heikkoudesta painostaa ja jota suuret aikeet joskus ovat
koskettaneet. Sellainen oli nuoren Hamletin elämä ja sellainen
Rooman vanhan imperaattorin. Sen lukee hämmästyttävän selvästi
jokaisesta piirteestä.

Hänen päänsä on hyvin muodostunut, jota vastaan kauneuden

näkökannalta tuskin lie muuta muistuttamista, kuin että kasvojen
soikea muoto on hiukan kokoonpuristunut. Leveällä otsalla lepää
raskasmielisyyden pilviä. Silmät, joiden katse on empivä, surullinen
ja hyväntahtoinen, ilmaisevat mietiskelevän ja kärsivän hengen, joka
tuntee itsensä jalosyntyiseksi, mutta kykenemättömäksi nauttimaan
vapaudestaan. Suu on hyvin muovailtu ja ilmaisee hienotunteisuutta,
jota ei olisi tässä odottanut, mutta joka selviää puolueettomasti
tarkastaessa Klaudiuksen luonnetta. Ryhti on ylevä, mutta
ponnisteltu, jäsen rakenne virheetön, lukuunottamatta liian kapeita
hartioita. Kokonaisuus tekee huolestuneen ja kuitenkin voittavan
vaikutuksen. On näkevinään onnettomuuden, jolla on oikeus vedota
osanottoon, ja heikkouden, joka on yhtynyt liian suureen hyvyyteen
herättääkseen ainoastaan surkuttelua ja ylenkatsetta.

Tämäkin patsas todistaa, että vanhaa puheenpartta antiikin

viileydestä sietää tinkiä. Kun esine oli sellainen, että paino lankesi
enemmän elämän särkymisen kuin sopusoinnun puolelle, luotiin
taideteoksia, jotka henkivät sitä lämpöä, jonka sielunvoimien
epätasainen toiminta synnyttää. Mutta antiikin teokset eivät ole
kaupaksi: ostajia kohtaan ne ovat kylmiä. Ne eivät antaudu millään
teennäisellä sielukkuudella, millään eleiden liioitteluilla, millään
laskoksien mutkikkaisuudella miellyttämään barbaarin makua. Me
yllätämme ne niiden tunnetunnustuksessa; mutta ne eivät tahdo
yllättää tunnetunnustuksillaan. Usein on huomautettu, että ne
näyttävät olevan olemassa itsensä vuoksi, kukkasen lailla, joka
kenenkään näkemättä puhkee kauneuteensa aarniometsän
syvyydessä.

Se Klaudiuspatsas, josta nyt on puhuttu, kaivettiin esille Civita

Lavignassa vuonna 1865. Vatikaanin rotondassa on myös
erinomainen rintakuva samasta keisarista, ja Lateraanissa säilytetään
toista valtaistuinpatsasta, joka myöskin on hyvä teos. Kaikki ne
puhuvat hyvin perikuvastaan, ja kaikki ne näyttävät todistavan, että
niiden mestari on rakastanut tehtäväänsä. Tämä rakkaus, jonka
huomaa, ties mistä syystä, ei ole aina ryhtynyt Rooman
keisaripatsaiden taiteilijoissa yhteistyöhön silmän ja maun kanssa.
Tämän yhteisvaikutuksen huomaa Klaudiuskuvissa, Vatikaanin
ihanassa Nerva-patsaassa, muutamissa parhaissa Trajanus- ja
Antoninus-Pius-kuvissa, mutta muutoin harvoin.

Jos jätämme museot mennäksemme Kampagnalle, kohtaa

Klaudius meidät sielläkin. Kampagna sulkee syliinsä hänen
muistonsa, ja se ja tämä muisto kaunistavat toisiaan. Se
surumielisyys ja se häviön suuruus, jonka huomaa poloisen keisarin
piirteissä, tavataan tässä luonnon ja taiteen muodostamassa
ryhmässä. Aqua Claudian holvikaaret kulkevat halki Rooman
erämaan, kuten järkähtämätön päätös joskus halki usmaisten
avaruuksien tämän Cesarin sielussa. Vuorilta, jotka idässä saartavat
Rooman taivaanrantaa, kulkevat Klaudiuksen vesijohdon kaaret
monipeninkulmaisen matkan ikuiseen kaupunkiin: vanha kirjoitus
Porta Maggioren yläpuolella kertoo, mistä kohdasta ne tulivat
Roomaan, ja ne viisi kaarta, jotka ovat jäljellä Palatinus vuoren
rinteellä Via di Gregorian puolella, lausuvat meille, minne johto
päättyi, tyhjennettyään lähderaikkaan juoksunsa moniin
marmorilampiin, jotka taide oli kaunistanut. Jos kulkee Via Appia
Nuovaa tai Frascatin tietä, näkee silmän kantamiin, pitempien tai
lyhyempien välimatkojen päässä, nämä suunnattomat kaaret, jotka
usein kohoavat sadan jalan korkeuteen ja jotka helposti erottaa
suuruutensa tähden samaan suuntaan kulkevista Aqua Marcian
kaarista. Vaikeata on uskoa, että tämän jättiläistyön on saanut
aikaan heikoin kaikista Cesareista; omituinen kohtalon leikki on, että
juuri hänen nimensä yhtyy muistomerkkiin, joka enemmän kuin
mikään todistaa muinaisen Rooman valtaa ja roomalaisen
kansanheimon tahdonvoimaa.

Jos on jossakin niistä pienistä höyrylaivoista, jotka kyntävät

Tiberiä, matkustanut Ostiaan, kohtaa samallaisen ristiriitaisuuden.
Siellä missä nyt näkee muutamia kurjia hökkeleitä, oli muinoin
Rooman väkirikas ja upea satamakaupunki, ja tämän kaupungin ja
sen sataman, joka luettiin maailman ihmetöihin, oli kiittäminen
Klaudiusta kukoistuksestaan. Tiberin suu Ostian luona oli jo ennen
Julius Cesarin aikaa niin virran liejun ja meren hiekan sekoittama,
että suuremmilla aluksilla ei uskallettu purjehtia sinne. Yksi Julius
Cesarin suurista suunnitelmista oli tehdä Ostia jälleen Rooman
satamaksi; mutta hän ei olisi toteuttanut tätä ajatusta, vaikkakin olisi
saanut elää, sillä hän, jota vaikeudet muutoin kannustivat, antoi
yrityksen raueta, sittenkuin asiantuntijat olivat selittäneet sen
mahdottomaksi. Klaudius otti suunnitelman uudelleen esille.
Asiantuntijat epäsivät jälleen. Keisari antoi heidän esittää syynsä,
tutki niitä, hylkäsi ne ja määräsi, että oli ryhdyttävä työhön.
Muutamia vuosia myöhemmin oli Ostia satama, jonka suunnattomien
käsivarsien välissä Egyptistä ja Afrikasta saapuva viljalaivasto löysi
vakavan ankkuripohjan ja jonka aallonmurtajan yllä kohosi majakka,
joka kilpaili Alexandrian majakan kanssa.
 Sabinilaisvuorten takana, eräässä Apenninien muodostamassa
kattilalaaksossa on Celanojärvi, muinaisajan Fucinus. Vuonna 1752,
jolloin vesi järvessä oli hyvin alhaalla, paljastuivat erään vanhan
kaupungin jätteet, ja niiden joukosta löydettiin patsaita keisari
Klaudiuksesta ja hänen toisesta vaimostaan, Agrippinasta. Mistä vain
joku Klaudiuspatsas on löydetty, siellä on vanha keisari elänyt
muistossa jonkin hyödyllisen yrityksen vuoksi. Niinpä täälläkin.
Fucinuksella ei ollut mitään näkyvää laskupaikkaa ja peitti se usein
ympäröivän seudun tulvallaan. Julius Cesar aikoi senvuoksi ehkäistä
veden korkeuden tunnelilla, jonka piti kulkea sen vuoren läpi, jota
nykyään nimitetään Monte Salvianoksi. Mutta Klaudiuksen osalle oli
tässäkin langennut ottaa esille ja toteuttaa Cesarin ajatus. Yksitoista
vuotta työskenteli 30,000 miestä vuoren murtamisessa. Vuonna 54
jälkeen Kristuksen oli työ loppuunsuoritettu. Se, kuten niin moni
muukin, rappeutui keskiajalla. Yli tuhannen vuotta Klaudiuksen
jälkeen otettiin asia uudelleen esille, ja uusi tunneli on nyt
lahjoittanut maanviljelykselle Celanojärven ympäristöllä viljavia
maankaistaleita varmaksi omaisuudeksi. Vuonna 1875 juhli Italia tätä
suurtyötä lyömällä muistorahan sen alkuunpanijasta, ruhtinas
Alessandro Torloniasta.

*****

Klaudius oli lapsena ja nuorukaisena sairaloinen. Hänen ruumiin-

ja sielunvoimansa kehittyivät niin hitaasti, että hän vielä täysi-
ikäisenä oli "lastenhoitajan" hallussa. Kodissa kohtelivat kaikki häntä
sydämettömästi, äitikin. Hänen kuultiin valittavan, että hän oli
synnyttänyt vaivaisen olennon maailmaan, ja jos hän tahtoi merkitä
jonkun tavattoman tuhmaksi, lausui hän aina: "hän on tuhmempi
kuin poikani Klaudius". Se kauneus ja nero, jolla hänen veljensä
Germanikus loisti, teki vertailun kautta Klaudiuksen aseman vieläkin
vaikeammaksi. Ainoa sukulaisista, joka osoitti hänelle hyvyyttä, oli
keisari Augustus. Niistä kirjeistä, joita tämä kirjoitti Livialle (ja joista
Suetonius on antanut meille otteita) huomaa muun muassa, että
keisari jonkun aikaa kutsui Klaudiuksen joka päivä pöytäänsä toivoen
voivansa vieroittaa hänet siitä ihmisarkuudesta ja siitä
tomppelimaisesta käytöksestä, joka teki hänet niin naurettavaksi.
Nuorukainen oli, paetakseen ivaa ja pilkkaa, vetäytynyt niin
näkymättömiin kuin suinkin ja valinnut seuralaisikseen muutamia
kunnioitettavia kirjatoukkia, joilla ei ollut rahtuakaan helleenisten
tiedemiesten maailmantottumusta, siroja eleitä ja kevyttä
seurusteluääntä. Näiden ystävien ohjaamana oli hän innolla
antautunut opiskelemaan. Titus Livius, erinomainen historioitsija,
keisarin helmaystävä, ilmestyi joskus tähän piiriin ja innosti
Klaudiuksen historialliseen kirjailemiseen, ellei muun, niin senvuoksi,
että nuorukaisen sielulla olisi ollut ylevää työskentelyä. Mutta keisari
huomasi pian sekä naurukseen että ikäväkseen, että nuori ruhtinas
ei ollut omistanut ainoastaan niitä tietoja, joita jollakin Sulpicius
Floruksella, jollakin Athenodoruksella oli tarjottavana, vaan myöskin
heidän turhantarkat eleensä. Mitä tehdä hänelle? Kun keisari kirjoitti
yhden näistä kirjeistä, oli juhla Mars Ultorin kunniaksi tulossa, jonka
hän oli säätänyt, ja siellä olisi pitänyt koko keisarillisen huoneen olla
läsnä. Mutta voitiinko Klaudius parkaa ("misellus") ottaa mukaan?
Voisikohan hän, vaikkakin oli 21 vuotias, käydä kypsyneestä
ihmisestä? Eikö panisi itseään ivalle alttiiksi, jos näyttäisi hänet niin
häijyyn pilaan taipuvalle kansalle kuin roomalaiset olivat?
Kirjeenkirjoittaja myöntää, että nämä kysymykset huolestuttivat
häntä, ja että hän nyt kerta kaikkiaan tahtoi saada ratkaisun siitä,
onko Klaudius mahdollinen seuraelämään ja valtiolliseen elämään vai
eikö. — Toisessa tilaisuudessa kirjoittaa keisari, että hän on löytänyt
sielun aateluutta tuon hullunkurisen kuoren alla — löytö, joka
tuottaa kunniaa hänen yhtä terävälle kuin hyväntahtoiselle
katseelleen — ja hän lausuu ihmettelynsä siitä ajatuskulun
yhtenäisyydestä ja lausumatavan selvyydestä, joihin Klaudius kykeni
pitäessään harkitun esitelmän, kun hänen tapanaan taas arkioloissa
oli lörpötellä.

Saman huomion oli Rooman kansa usein tilaisuudessa tekemään,

sittenkuin Klaudius oli noussut valtaistuimelle. Kun hän ei puhunut
valmistautumatta, eivät hänen puheensa senaatissa olleet
ainoastaan selviä, vaan myöskin runsasaineisia ja huomattavia
perinpohjaisuutensa takia; ja siitä huolimatta kului tuskin
päivääkään, jolloin ei forumilla tai yksityisissä piireissä voitu toistaa
jotakin hänen lausumaansa tuhmuutta tai hupsua sanankäännettä.

Sitä säälivää ystävällisyyttä, jota Augustus oli osoittanut hänelle

hänen nuoruutensa ilottomina päivinä, hän säilytti muistossaan mitä
suurimmalla kiitollisuudella. Se, että Augustus oli katsonut
välttämättömäksi sulkea hänet kaikista valtion virka-arvoista,
lukuunottamatta auguripapin tointa, ja testamentissaan muistanut
häntä ainoastaan vähäpätöisellä rahasummalla, ei vähentänyt hänen
kiitollisuuttaan. Jos Rooman valtakunnassa oli joku, joka
keisarikunnan perustajassa näki korkeamman olennon ja kiinnitti
vakavan merkityksen hänen korottamiseensa jumalien joukkoon, niin
se oli tämä hänen seuraajistaan.

Tiberiuksen hallitusaikana oli Klaudius vielä ankarammin eristetty

yleisistä toimista. Kun senaatti antoi hänelle paikan ja
äänestysoikeuden konsulinarvoisten jäsentensä joukossa, kumosi
Tiberius päätöksen selittäen avonaisesti, että hänen sukulaisensa ei
ollut täysijärkinen. Siihen ylenkatseeseen, jolla Tiberius kohteli
häntä, ja siihen pelkoon, jota hän tunsi, että tuo "mielipuoli" tekisi
Cesarin huoneen naurettavaksi, sekaantui kuitenkin toisiakin
tunteita. Hänkin oli havainnut Klaudiuksessa jaloa kuntoa; häntä
närkästytti, että ne harvinaiset taipumukset hyvään ihmiseen, jotka
hän luuli tässä löytäneensä, olivat yhtyneet niin auttamattomaan
heikkouteen, ja testamentillaan hän koetti turvata Klaudiukselle
itsenäisen ja huolettoman taloudellisen aseman. Mutta Kaligula ryösti
hänen omaisuutensa, ja Klaudius eli sitten köyhän oppineen elämää
sen kaikkine kieltäymyksineen. Onneton hän ei ollut kuitenkaan,
lukuunottamatta niitä hetkiä, jolloin hänet kutsuttiin hoviin ollakseen
siellä Kaligulan pilkallisten sanansutkausten maalitauluna. Hän löysi
lohtunsa lukemisesta ja kirjailemisesta ja hänen leponaan olivat ne
tyhjät unelmat, joihin hän antautui, sittenkuin oli lähimmästä
ravintolasta tuodulla aterialla tyydyttänyt alati suurenmoisen
ruokahalunsa ja rakkautensa albaniviiniin. Silloin kun hän ei
oleskellut maalla, asui hän eräässä kehnossa talossa Rooman
laitakaupungilla, naapurien rakastamana, jotka kunnioittavalla
kohtelulla näyttivät tahtovan hyvittää sen pilkan, jota hän sai kokea
sukulaistensa puolelta. Kreikkalaisen kirjamaailman hän oli
perusteellisesti tutkinut; hänen historialliset tutkimuksensa olivat
tarkat ja laajat; hänen työskentelynsä kirjailijana laveudeltaan
suurenmoinen ja, hänen aikalaistensa lausunnoista päättäen,
sisällöltään kunnioitettava. Rooman historiaa hän kirjoitti
kaksikymmentäkolme nidosta; etrurilaisia tutkimuksia hän kirjoitti
kaksikymmentä kirjaa ja kartagolaisia kahdeksan. Sitäpaitsi hän
kirjoitti "Ciceron puolustuksen" tämän vastustajaa Asinius Gallusta
vastaan, teoksen lautapelistä, toisen latinankielen
oikeinkirjoituksesta, sekä lopuksi laajoja muistiinpanoja omasta
elämästään. Luettakoon auttamattomaksi vahingoksi tieteelle se,
että hänen etruriset ja kartagolaiset historiansa ovat joutuneet
hukkaan, sillä epäilemättä niissä olisi ollut suunnattomasti kirjatietoja
ja suuri määrä tunnontarkkoja tosiasioita, jotka ovat saadut jo kauan
sitten kuivuneista lähteistä. Klaudiuksella oli kokonaan meidän
päiviemme ammattioppineen luonne, joka rakkaudella syventyy
tutkimansa esineen pienimpiin yksityiskohtiin, eikä uskalla lausua
arvostelua mistään tutkimatta tarkasti kaikkea, mitä siihen saakka on
tutkisteltu ja lausuttu samasta aineesta.

Tämä ominaisuus oli ehkä hänen suurimpia onnettomuuksiaan

valtakunnan hallitsijana. Se teki hänet turhantarkaksi ja
virkavaltaiseksi holhoojaksi jokaisessa pikkuasiassa, jonka hän tiesi
ymmärtävänsä, ja houkutteli hänet hyvää tarkoittavaan, mutta
naurua ja suuttumusta herättävään sekaantumiseen määräystensä
kautta talouskokeissa ja muissa asioissa, joita ne virkamiehet, joita
määräykset koskivat, ymmärsivät ainakin yhtä hyvin kuin hän itse.
Mutta vielä pahempaa oli: sama hänen ominaisuutensa teki hänet
aivan saamattomaksi niissä joka päivä esiintyvissä kysymyksissä,
joita hän ei tuntenut käsittävänsä. Tuntien sen tylsyyden, millä hän
sai vaikutelmat kaikesta, mikä ei kiihoittanut hänen nautintoaan, ja
tietäen sen hitauden, jolla hän muodosti ajatuksiaan, ei hän
luottanut lainkaan arvostelukykyynsä välittömästi vaikuttavana, ja
sellaisiin kysymyksiin hänellä ei ollut muuta vastausta kuin
holbergiläinen: "kysykää hovimestariltani!" Vähimmän hän uskoi
voivansa lukea toisten ajatuksia ja aikeita, erottaa rehellistä
epärehellisestä ja ystävää vihollisesta. Tämän huolen hän heitti niille
ympäristönsä ihmisille, jotka kerta kaikkiaan olivat voittaneet hänen
luottamuksensa. Ne syytökset, joiden uhriksi suuri joukko
senaattoreja ja ritareja joutui hänen hallitusaikanaan, ovat kaikki
tyynni asetettavat tämän ympäristön syntiluetteloon. Kun keisarin
kuoltua tutkittiin hänen papereitaan, niin huomattiin, ettei hän itse
milloinkaan ollut vaatinut eikä aloittanut yhtään syytöstä. Tavallisesti
hän ei tiennyt langetetuista kuolemantuomioista mitään, ennenkuin
ne olivat toimeenpantuja, usein ei jälkeenkäänpäin, niin että hän
kutsui pöytäänsä ylhäisiä roomalaisia, jotka jo olivat mestattuja
valtiopetoksesta. Hän tunsi olevansa "kykenemätön puolustamaan
itseään", kuten Tacitus on sanonut; kun hän oppineista
tutkimuksistaan tai tärkeitten lakiehdotusten mietiskelyistään tai
askarteluistaan virkavaltaisessa töryssä herätettiin katselemaan
ympäröivää elämää, ja kun hän kuuli puhuttavan valtiolle
vaarallisista juonista ja uhkaavista salaliitoista, istui hän
neuvottomana ja epäillen, tokko voisi saada selville mikä oli totta ja
mikä valhetta, mikä todellista ja mikä kuvailtua kuulemassaan, ja
hän alistui niiden mielivallan alaiseksi, joiden "käytännölliseen
kykyyn" hän luotti ja joiden rakkaudesta ja ystävyydestä hän luuli
olevansa varma. Että tämä oli heikkous, turmiollinen ja ruhtinaalle
arvoton, sen hän tuskallisesti tiesi ja koetti tukauttaa tuota tunnetta
päivällispöydän huvitteluilla ja väsymättömillä tutkimuksilla.

Hän teki kuitenkin uutteria yrityksiä kehittääkseen

arvostelukykyään käytännöllisen elämän tarpeissa. Senvuoksi hän
asettui usein tuomarinistuimelle, silloinkin kun oli esillä
vähäpätöisempiä oikeudenkäyntejä. Hänen yrityksensä olla
tuomarina onnistuivat milloin mitenkin. Toisinaan hänen onnistui
kuunnella tarkkaavaisesti niitä perusteita ja vastaperusteita, joita
asian käsittelyssä esitettiin, ja kun hän sitten oli jonkun aikaa
harkinnut, saattoi hän julistaa päätöksen, joka todisti älykkäisyyttä.
Mutta yhtä usein tapahtui, että mietiskelyt mahdollisesti
etrurilaisesta tai kartagolaisesta ajanlaskusta tai jostakin
lautapelitehtävästä hämmensivät hänen ajatuksensa, ja sen
mukaiseksi tuli tuomiokin. Sellaisessa tilaisuudessa viskasi toinen
asianomaisista, eräs helleeni, hänelle vasten kasvoja sanan tyhmyri.
Keisari otti nöyrästi vastaan syytöksen, tuntien että se oli hyvin
ansaittu. Toisen kerran hänen istuessaan tuomarina tunkeutui saliin
suloisia ruuanhöyryjä eräästä lähellä olevasta temppelistä, jonka
papit olivat kautta koko kaupungin tunnettuja herkkusuita. Klaudius
unhoitti silloin sekä oikeudenkäynnin että riitapuolet ja kiirehti
tuomarinistuimelta pappien ruokasaliin, missä hän istuutui ja nautti
perusteellisen aterian.

Yleensä voidaan sanoa, että hänen hermostonsa oli häntä

voimakkaampi. Hän oli ylen heikko aistiärsytyksiin nähden.
Naisellinen kauneus, jalo viini, herkullinen pöytä olivat kiusauksia,
joihin hän lankesi tuntematta muita kuin äänettömiä vastaväitteitä,
jota vastoin hän asioissa, jotka eivät vedonneet aisteihin, vaan
mietintöön, osoitti tahdonvoimaa, sittenkuin oli muodostanut niistä
vakuutuksen. Tämän ärtyisyyden perustalla on selitettävissä ne
monet synnit, joita hän teki hovitapoja vastaan, vieläpä
säädyllisyyttä ja maltillisuuttakin vastaan, jotka jokainen roomalainen
tahtoi ottaa huomioon ulkonaisessa esiintymisessä. Hän saattoi
juhlallisissakin tilaisuuksissa ja valtaistuimella osoittaa iljettävää,
joskin nopeasti ohimenevää ja aivan vaaratonta kiukkua
odottamattoman vastaväitteen johdosta; hän saattoi vuodattaa
kyyneleitä, jos hiukankin vedottiin hänen sydämeensä, ja nauraa
kohti kurkkua, kun jokin näytti hullunkuriselta, minkä seurusteluäly
vaati sivuuttamaan. Kun hänen herkeämätön pyrkimyksensä esiintyä
keisarille arvokkaalla tavalla ei kantanut parempaa hedelmää, niin
älköön ihmeteltäkö seuraavaa tapausta, joka sattui hänen vielä
eläessään yksityisenä miehenä ja "vanhana ylioppilaana". Hän tahtoi
silloin, kuten toisetkin kirjailijat, julkisilla luennoilla päästä selville,
minkälainen menestys hänen julkaisemattomilla kirjoituksillaan olisi.
Ensimäiselle luennolle saapui paljon väkeä, ja kunnioittavalla
äänettömyydellä odotettiin, mitä ruhtinaan vaatimattomalla ja
suositulla sukulaisella olisi sanottavaa. Mutta kun tämä oli aloittanut
esitelmänsä, murtui penkki tavallista paksumman kuulijan alla.
Luentosali selvisi pian siitä naurukohtauksesta, minkä tämä herätti;
mutta se, joka ei voinut hillitä nauruhermojaan, oli luennoitsija itse,
ja kuulijoiden täytyi poistua, sittenkuin kauan olivat turhaan
vartoneet, että hän antaisi heille muutakin nautittavaa kuin
naurunhohotusta.

Tähän hermoärtyisyyteen kuului hänen hätäilevä pelkonsakin, jota

väärin on tulkittu arkuudeksi, sillä sitä vastasi moraalinen rohkeus,
joka usein voitti sen. Hänen tosin kyllä lyhyeltä sotaretkeltään
Britanniassa ei tuo innokas juttujenkerääjä Suetonius ole voinut
kertoa yhtään ainoata piirrettä, mikä oikeuttaisi syyttämään keisaria
pelkuruudesta. Saman ruumiillisen heikkouden perustalla on
selitettävissä se hekumallinen nautinto, minkä joskus oltiin
näkevinään hänen kasvonpiirteissään, silloin kuin hän näki
verenvuodatusta. Hänen aikalaisensa, jotka niin kyllästymättömästi
kaipasivat julmia gladiaattorileikkejä, eivät kai milloinkaan olisi
huomauttaneet tästä, elleivät olisi havainneet sitä juuri ruhtinaassa,
jonka ihmisystävällinen mielenlaatu oli yleisesti tunnettu.

Klaudiuksen kasvoista lukee, että hän murehti tappioita taistelussa

sisällisen lakinsa ja jäseniensä lain välillä. Tutkimukset ja mietiskelyt
olivat hänen ainoana turvanaan aistien viettelyjä vastaan. Kun hän
silloin oli vaipuneena ajatustensa ja unelmiensa maailmaan, saattoi
esineitä kulkea hänen katseensa ohi hänen niitä näkemättä, ääniä
kaikua hänen läheisyydessään hänen niitä kuulematta, tapahtumia
sattua, jotka liikuttivat kaikkia hänen ympärillään olevia hänen niistä
mitään aavistamatta. Hänen sielunsa oli camera obscura, joka imi
itseensä kapean valonsiinnon ja jätti kaiken muun pimeään. Hänen
täytyi kääntää katseensa ulkonaisista ilmiöistä, ellei mielinyt joutua
jonkun hermovaikutelman orjaksi. Hänellä kun ei ollut äkillisiä
mielijuohteita eikä terävää katsetta, niin hän koetti voimiaan
käytännöllisten kysymysten teoreetisen solmun etsimisessä ja
selvittelemisessä, ja tämän hän teki usein tavalla, joka todisti
filosoofisia lahjoja. Tacitus on antanut meille merkillisen näytteen
tästä. Gallia Comatan ylhäisemmät asukkaat, joilla oli Rooman
kansalaisoikeudet ja joiden kieli ja sivistys oli kauan ollut
roomalainen, vaativat itselleen oikeutta saada hakea ja tulla
nimitetyiksi Rooman valtionvirkoihin. Vaatimus herätti katkeruutta ja
kiivasta vastarintaa ei ainoastaan senaattorien ja ritarien joukossa,
vaan pääkaupungin rahvaassakin; sillä huolimatta kaikista
säätyjaoista ja arvoluokista tahtoi vielä tähän aikaan jokainen
kaupungin muurien sisäpuolella syntynyt katupoikakin käydä
korkeammasta henkilöstä kuin parhaimmat kansalaiset
maaseutukaupungeissa, ja itse asiassa oli olemassa eräs ajatustavan
voimassapitämä, vaikkakaan ei valtioelämään sovellutettu
pappisvaltainen järjestys Rooman vallanalaisten maiden ja kansojen
välillä, jossa italialaiset saivat ensimäisen sijan, kreikkalaiset toisen,
gallialaiset kolmannen ja niin edespäin aina egyptiläisiin saakka,
jotka tavallisesti asetettiin alimmalle asteelle. Nyt tuumittiin
Roomassa, saisivatko ihmiset, joiden isät olivat olleet barbaareja ja
Tiberinkaupungin turmiollisimpia vihollisia, tunkeutua itse senaattiin
ja kantamalla purppurareunaista toogaa nöyryyttää Romuluksen
jälkeläisiä. Huuto veren, heimon, "kansojen" oikeudesta kaikui sillä
kertaa yhtä voimakkaasti kuin meidän päivinämme. Silloin kutsui
Klaudius senaatin kokoon ja piti vastahakoisesti kuunteleville isille
esitelmän, joka tahtoi näyttää toteen, että Rooma ei ollut, ei ollut
milloinkaan ollutkaan sitä, mitä he tahtoivat mielessään kuvitella:
yhteiskunta, joka oli rakennettu kansallisuuden pohjalle. Hän
muistutti oman ikivanhan sukunsa sabinilaisesta alkuperästä,
julilaisten sukuluetteloa Alba Longasta ja Porciusten Tuskulumista.
Hän muistutti eqveistä, hernikeistä, etruskeista, lukaneista ja niin
monesta muusta kansasta, jotka Rooma oli kukistanut, mutta
elähyttääkseen heitä roomalaisella hengellä ja sivistyksellä ja
sulattaakseen heidät yhdeksi kokonaisuudeksi itsensä kanssa.

Nyt nimitettiin näiden heimojen jälkeläisiä roomalaisiksi ja he

rakastivat Roomaa isänmaanaan. Hän osoitti, että valtiot sellaiset
kuin Ateena ja Sparta olivat käyneet perikatoon siksi, että
pysyttelivät liian ankarasti veren perustassa, kun Rooma sitävastoin
pääsi maailman herrauteen senvuoksi, että se taisteli enemmän
sivistyksensä levittämisen kuin jonkun määrätyn kansanheimon
ylivallan puolesta. "Kokoontuneet isät," niin hän lopetti puheensa,
"kaikki, mitä nyt pidetään ikivanhana, oli kerran uutta:
patriisivirkamiesten jälkeen tuli plebejejä, heidän jälkeensä
latinalaisia, heidän jälkeensä taas virkamiehiä toisista italialaisista
heimoista. Tämäkin on saavuttava vanhuuden tavan, ja mitä nyt
puolustamme aikakirjojen esimerkeillä, on sekin kerran oleva
aikakirjain esimerkkien joukossa."

*****

Hänen puheensa senaatissa eivät käsitelleet aina niin tärkeitä

valtiollisia kysymyksiä. Kuten edellä on mainittu sekaantui hän
kaikkeen, mihin tiesi kykenevänsä, eikä mikään aine tuntunut
hänestä silloin arvottomalta valtion päämiehen puuttua sen
käsittelyyn. Kun senaatti oli eräänä päivänä ryhtynyt harkitsemaan
kysymystä jostakin muutoksesta kaupungin kehnompien
ruokapaikkojen ja kapakoiden säännöissä, ilmestyi keisari kuriaan, ja
kun hän syystä kyllä oli sitä mieltä, että yksikään kokoontuneista
isistä ei tuntenut paremmin niitä paikkoja kuin hän, joka niin useasti
oli tuonut päivällisateriansa niistä, vieläpä astunut niiden
kynnyksenkin yli pelatakseen viinimitan ääressä lautapeliä
vakinaisten vieraiden kanssa, niin hän nousi ja antoi, senaattorien
närkästykseksi ja nauruksi, tarkkoja selityksiä siitä, mitä huomioita
hän itse oli tehnyt näiden paikkojen laitoksista, tavaroista ja
hinnoista.

Siitä elämästä, jota hän näin kuvaili, oli kohtalo hänet äkkipikaa
siirtänyt valtaistuimelle. Me kaikki tiedämme kuinka se tapahtui.
Kaligula oli kaatunut salaliittolaisten miekaniskuista, ja senaatti,
ensimäisen sanoman saavuttua tästä, oli kokoontunut Kapitoliumille
palauttaakseen kiireesti koottujen kaupunkilaiskohorttien aseiden
suojassa "vapauden entiselleen", kuten tuo kaunis lausetapa kuului.
Mutta senaattorien kiistellessä siitä, kuinka tämä on tapahtuva, ja
kuinka vapaudella on turvattava järjestys ja omistusoikeus, eikä
vähimmän omistusoikeus orjiin, sattuu muutaman kivenheiton
päässä surullisen hullunkurinen tapaus, joka yhdellä erää tekee
tyhjäksi tuon suurenmoisen suunnitelman. Eräs pitkäkyntinen
sotamies on sekasorron aikana hiipinyt autioon keisarinlinnaan ja
löytää sieltä jalkaparin erään oviverhon alta. Jalkojen omistaja
lankee kauhuissaan polvilleen ja rukoilee, että hänen henkeään
säästettäisiin. Sotamiehen, joka tuntee rukoilijan erääksi keisarillisen
huoneen jäseneksi, Kaligulan sedäksi Klaudiukseksi, päähän pälähtää
silloin oivallinen tuuma. Hän varastaa Klaudiuksen ja kohtaa,
kiirehdittyään tämän kanssa palatsista, muutamia aseveikkoja, jotka
auttavat häntä nostamaan varastetun saaliin kantotuoliin ja siirtävät
sen pretoriaanileiriin. Pretoriaanit, jotka ovat suutuksissaan siitä
luottamuksesta, jota senaatti on osoittanut kaupunkilaiskohorteille,
ja haaveksivat sitäpaitsi enemmän palkkoja ja rahalahjoja kuin
vapautta, huutavat Klaudiuksen keisariksi. Kansa, joka on
kokoontunut senaatin neuvotteluhuoneen ulkopuolelle, yhtyy
vannomaan uskollisuusvalaa, kaupunkilaiskohortit marssivat takaisin
kasarmeihinsa, vapaudenhuudot lakkaavat ja senaattorit hajaantuvat
kuin akanat tuuleen. Ne aivot, joissa pretoriaanivalta siten ensiksi
otti miehuuden kekseliäänä kujeena, jonkinlaisena
varkausajatuksena, ansaitsevat kuolemattomuuden yhtä hyvin kuin
joku toinenkin, joka on saanut kunnian kantaa sytyttävän kypenen jo
valmiiseen historialliseen ilotuleen: sotamiehen nimi oli Gratus ja oli
hän syntyisin Epiruksesta.

*****

Kaikesta, mitä Klaudiuksen hallitessa tapahtui, lienee hänen

ensimäisen puolisonsa Messalinan kohtalo se, mikä enin on
herättänyt tapojen kuvaajain huomiota. Tacitus maalaa elävin värein
tämän julman ja rikollisen naisen elämän viimeiset tapahtumat.
Viimeinen hänen vapaaehtoisten tai pakotettujen rakastajainsa
pitkässä sarjassa oli Cajus Silius, kaunein Rooman nuorukaisista. Niin
vaarallista kuin olikin ottaa vastaan hänen suosionsa, niin vieläkin
turmiollisempaa oli työntää se luotaan. Jälkimäisessä tapauksessa
vartosi miestä kuolema; edellisessä ainakin mahdollisuus saada
rankaisematta nauttia niistä rikkauksista ja arvonosoituksista, joita
keisarinna tuhlasi intohimonsa esineille, sillä vaikkakin koko Rooma
tiesi ja puhui hänen hurjista irstailuistaan, niin ei Klaudiuksella
näyttänyt olevan pienintä aavistustakaan niistä. Saattaa sanoa, että
koko kaupunki oli hänen uskottunsa ja että hän teeskenteli vain
miehelleen. Pakotettuaan Siliuksen hylkäämään nuoren vaimonsa,
tuli hän usein tämän taloon, oli melkein aina Siliuksen rinnalla, kun
tämä näyttäytyi ulkona, ja ympäröi hänet ruhtinaallisella loistolla. Tuli
syksy. Keisari oli matkustanut Ostiaan ollakseen läsnä
Backusjuhlassa, ja Messalina käytti hyväkseen hänen poissa oloaan
viettääkseen hänkin palatsissaan Palatinuksella viininkorjuujuhlaa ja
tämän yhteydessä — niin uskomattomalta kuin se kuuluukin —
häitään rakastajan kanssa, häitä, joista ei tiedetä, tuliko niiden vain
esittää häitä vaiko olla lailliset, mutta joista tiedetään, että ne
tapahtuivat augurien läsnäollessa, että niihin oli kutsuttu todistajia,
että niissä uhrattiin jumalille, suudeltiin ja syleiltiin. Senjälkeen
seurasi viininkorjuujuhla, joka oli järjestetty hurjaksi juomingiksi.
Viinipusertimet ovat käynnissä, rypäleen mehut virtaavat, juhlaan
osaaottavat naiset, puettuina ainoastaan Backuksen papittaren
eläimennahkaan, tanssivat uhraavina tai juopuneina backanteina.
Heidän keskellään nähdään Messalina tukka valloillaan liehuen ja
tyrsusta heiluttaen, ja hänen rinnallaan Silius, tämäkin melkein
alastomana, muratilla seppelöitynä ja koturnissa. Palatsin
rakennukset ja kamarit kaikuvat mässäävän kuoron lauluista ja
evoehuudoista. Eräs humalaisista osanottajista, Victius Valens, kiipee
korkeaan puuhun ja silmäilee ympärilleen. "Mitä näet?" huudetaan
hänelle. "Hirvittävän myrskyn, joka tulee Ostiasta", kuului hänen
ennustava vastauksensa. Heti sen jälkeen syöksyy lähettiläitä
palatsiin ilmoittaen, että keisari tietää kaikki ja saapuu kostamaan.
Orgia hajoaa kauhuissaan. Vieraat hajaantuvat joka taholle, mutta
heidän jäljissään ovat jo centurioonit, jotka vangitsevat heidät, missä
heitä vain tavataan, kaduilla ja taloissa. Messalina on ainoa, joka
nopeasti jälleen saavuttaa mielenmalttinsa. Hän rientää palatsista
puutarhoihinsa, jotka olivat nykyisellä Monte Pinciolla, ja käskee
lapsiensa, Britannikuksen ja Oktavian, kiirehtimään isäänsä vastaan
ja heittäytymään hänen syliinsä. Itse päättää hän kiirehtiä lasten
edelle. Hän tuntee puolisonsa heikkouden ja rakentaa toivonsa
kauneutensa, hyväilyjensä ja kyyneltensä voimaan ja lastensa
esirukouksiin.

Niin riensi hän jalkaisin tuon pitkän matkan Monte Pinciolta sille
kaupunginportille, jolla nyt on apostoli Paavalin nimi. Siellä hän
heittäytyy ihan uupuneena ensimäiseen käytettävissä olevaan
ajoneuvoon ja kiirehtii edelleen tietä, joka Tiberin rantaa pitkin vie
Ostiaan. Nyt hän näkee keisarillisen saattueen edessään: hän
huomaa keisarin ja tämän rinnalla kolme hovimiestä, joiden joukossa
on Narcissus, hänen vihollisensa ja ilmiantajansa. Klaudiuksen kasvot
virittävät jälleen eloon hänen rohkeutensa, keisarin piirteet
ilmaisevat enemmän tuskaa kuin suuttumusta: hänen huulillaan ei
ole koko matkalla ollut muuta kuin nämä sanat: "Lapsieni äidin,
lapsieni äidin häpäisemä! Oi poloisia lapsiani!" Hetki oli ratkaiseva.
Se on syöksevä surmaan jomman kumman: Messalinan tai
Narcissuksen. Molemmat käsittävät tämän. Messalina huutaa jo
etäältä: "Cesar, kuule Oktaviasi, kuule Britannikuksesi äitiä!" Klaudius
ei ollut milloinkaan voinut vastustaa tämän äänen sointua, tämän
ihanuuden näkyä; mutta Narcissus tukauttaa Messalinan äänen
huudolla: "Cesar, älä unhoita Siliusta! älä unhoita noita häpeällisiä
häitä!", ja kun keisarinna tahtoo kiirehtiä vaunujen luo, aukaisee
Narcissus kääröstä hänen ja hänen puolisonsa väliin
ilmiantokirjelmän, jossa kerrotaan Messalinan irstailuista. Keisari
vaikenee, kaikki vaikenevat, paitsi Narcissus, jonka ääni kaikuu
voimakkaana ja käskevänä ja pakottaa ympäristön tottelemaan.
Keisarilliset vaunut saattueineen jatkavat matkaansa.
Kaupunginportilla vartoo heitä eräs vestaali pidellen kädestä
Britannikusta ja Oktaviaa; mutta Narcissus poistaa lapset paikalta ja
määrää vestaalin jälleen hoitamaan velvollisuuksiaan. Senjälkeen
ajaa hän keisarin suoraan Siliuksen taloon, jonka Messalina on
koristanut julilaisen ja Klaudiusten suvun taideaarteilla, ja sieltä
pretoriaanien luo, jotka huutavat kuolemaa syyllisille. Silius
asetetaan tuomioistuimen eteen, tunnustaa empimättä kaiken ja
mestataan heti. Kun Klaudius on palannut takaisin palatsiin, ilmoittaa
hän, että hän itse tahtoo seuraavana aamuna kuulustella "tuota
onnetonta". Mutta Narcissus, joka tietää, että Messalinan ei tarvitse
muuta kuin heittäytyä keisarin jalkoihin voittaakseen jälleen hänen
sydämensä, lähettää heti muutamia vahdissa olevia centuriooneja
panemaan toimeen kuolemantuomiota, kuten hän sanoo. He löysivät
hänet makaavana maassa äitinsä jalkojen juuressa, epätoivoissaan
väännellen käsiään, kuuntelematta vanhusta, joka pyysi hänen
kiirehtimään ennen pyöveleitä ja kuolemaan vähemmän häpeällisen
kuoleman oman käden kautta. Kun sotamiehet astuivat sisään,
tarttui keisarinna vihdoinkin tikariin ja kohotti sen kohti kaulaansa ja
rintaansa, mutta vapiseva käsi kieltäytyi tottelemasta. Eräs
henkivartioston eversti lävisti hänet silloin miekallaan. Kun
Klaudiukselle ilmoitettiin, että Messalina oli "heittänyt henkensä",
tyhjensi hän maljansa eikä lausunut mitään. Hän ei maininnut
milloinkaan enää keisarinnan nimeä.

Vielä vanhuudessaankin heikkona naiselliselle kauneudelle, antoi

Klaudius nuoren ja ihanan veljensätyttären Agrippinan lumota
itsensä, naisen, josta tuli hänen toinen puolisonsa ja sanan
surullisimmassa merkityksessä äitipuoli hänen pojalleen
Britannikukselle, jonka vahingoksi hän valmisti kaikki korottaakseen
oman poikansa Lucius Domitiuksen (Neron) Cesariksi. Kun hän epäili,
että Klaudius, jota hän tähän saakka oli mielensä mukaan ohjannut,
tahtoi ehkäistä hänen tuumansa, antoi hän tälle myrkkyä, kuten
väitetään. Kertomus tapahtumasta ei vaiennut siitä, että hän
kunnioitti Klaudiuksen nimeä ja muistoa suurella
temppelirakennuksella. Tämän jäännökset ovat vielä Celius vuorella
Koliseumin takana.

Pysyvämmin on kuitenkin Klaudius itse tehnyt muistonsa

kunnioitetuksi ihmisystävällisillä laeilla. Vielä kaivetaan toisinaan
vanhan Gallian maasta patsaita, joissa on sen keisarin nimi, joka
poisti Druidien ihmisuhrit ja saattoi roomalaisen sivistyksen siellä
ratkaisevaan voittoon. — Roomassa on alue, joka yli kaksituhatta
vuotta on ollut vihitty säälin valloille. Se on Tiber-saari. Missä nyt
vuosisatoja on ollut sairaala kirkon ja luostarin yhteydessä, siellä oli
muinoin Eskulapius-temppeli, josta köyhät sairaat etsivät apua ja
hoivaa. Sydämettömyys tunki kuitenkin täälläkin esiin hyötyäkseen
armeliaisuudesta. Tunnottomilla herroilla oli tapana viedä sairaat
orjansa Tiber-saarelle vaatiakseen heidät takaisin, jos paranivat,
mutta muutoin heittääkseen heidät oman onnensa nojaan. Klaudius
lopetti tämän väärinkäytöksen. Hän laati lain, joka lienee tuntunut
monesta orjanomistajasta yhteiskunnalle vaaralliselta, sillä laki
määräsi, että jokainen sinne viety orja, joka parani, oli vapaa mies,
ja että jokainen herra, joka surmasi sairaan orjan mieluummin kuin
hoiti häntä tai toimitti hänet sairaalaan, oli saava murhaajan
rangaistuksen.

Tällaiset muistot sovittakoot jossakin määrin sitä, mitä tämä Cesar

heikkoudessaan on rikkonut. Hän oli kahlehdittu jalo sielu. Paha
kyllä, että sellaista heikkoutta tuomitaan usein ankarammin kuin
tahdonvoimaa, jolla ei ole mitään siteitä, ei edes omantunnon,
pudistettavana yltään.
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