The Julia Language

Contents....2

Manual....15

Julia 1.9 Documentation....16

Getting Started....18

Resources....19

Variables....20

Allowed Variable Names....21

Assignment expressions and assignment versus mutation....22

Stylistic Conventions....23

Integers and Floating-Point Numbers....25

Integers....26

Floating-Point Numbers....30

Arbitrary Precision Arithmetic....35

Numeric Literal Coefficients....36

Literal zero and one....38

Mathematical Operations and Elementary Functions....39

Arithmetic Operators....39

Boolean Operators....40

Bitwise Operators....40

Updating operators....41

Vectorized "dot" operators....42

Numeric Comparisons....43

Operator Precedence and Associativity....46

Numerical Conversions....47

Complex and Rational Numbers....51

Complex Numbers....51

Rational Numbers....54

Strings....57

Characters....58

String Basics....60

Unicode and UTF-8....61

Concatenation....65

Interpolation....66

Triple-Quoted String Literals....67

Common Operations....68

Non-Standard String Literals....70

Regular Expressions....70

Byte Array Literals....75

Version Number Literals....77

Raw String Literals....77

Functions....79

Argument Passing Behavior....80

Argument-type declarations....81

The return Keyword....81

Operators Are Functions....83

Operators With Special Names....84

Anonymous Functions....84

Tuples....85

Named Tuples....86

Destructuring Assignment and Multiple Return Values....86

Property destructuring....89

Argument destructuring....89

Varargs Functions....90

Optional Arguments....92

Keyword Arguments....93

Evaluation Scope of Default Values....94

Do-Block Syntax for Function Arguments....95

Function composition and piping....96

Dot Syntax for Vectorizing Functions....97

Further Reading....99

Control Flow....100

Compound Expressions....100

Conditional Evaluation....101

Short-Circuit Evaluation....104

Repeated Evaluation: Loops....107

Exception Handling....110

Tasks (aka Coroutines)....115

Scope of Variables....116

Global Scope....117

Local Scope....118

Constants....128

Typed Globals....130

Types....132

Type Declarations....133

Abstract Types....135

Primitive Types....136

Composite Types....137

Mutable Composite Types....139

Declared Types....141

Type Unions....141

Parametric Types....142

UnionAll Types....150

Singleton types....151

Types of functions....152

Type{T} type selectors....153

Type Aliases....155

Operations on Types....155

Custom pretty-printing....156

"Value types"....159

Methods....161

Defining Methods....162

Method specializations....165

Method Ambiguities....166

Parametric Methods....167

Redefining Methods....170

Design Patterns with Parametric Methods....172

Parametrically-constrained Varargs methods....176

Note on Optional and keyword Arguments....176

Function-like objects....177

Empty generic functions....178

Method design and the avoidance of ambiguities....178

Defining methods in local scope....181

Constructors....183

Outer Constructor Methods....184

Inner Constructor Methods....184

Incomplete Initialization....186

Parametric Constructors....188

Case Study: Rational....190

Outer-only constructors....192

Conversion and Promotion....194

Conversion....195

Promotion....197

Interfaces....201

Iteration....201

Indexing....204

Abstract Arrays....205

Strided Arrays....208

Customizing broadcasting....209

Instance Properties....214

Modules....217

Namespace management....218

Submodules and relative paths....223

Module initialization and precompilation....225

Documentation....229

Accessing Documentation....229

Writing Documentation....229

Functions & Methods....233

Advanced Usage....234

Syntax Guide....235

Metaprogramming....240

Program representation....240

Expressions and evaluation....243

Macros....248

Code Generation....256

Non-Standard String Literals....257

Generated functions....259

Single- and multi-dimensional Arrays....266

Basic Functions....266

Construction and Initialization....266

Array literals....267

Comprehensions....272

Generator Expressions....273

Indexing....274

Indexed Assignment....276

Supported index types....277

Iteration....282

Array traits....283

Array and Vectorized Operators and Functions....283

Broadcasting....284

Implementation....285

Missing Values....288

Propagation of Missing Values....288

Equality and Comparison Operators....289

Logical operators....290

Control Flow and Short-Circuiting Operators....291

Arrays With Missing Values....292

Skipping Missing Values....293

Logical Operations on Arrays....294

Networking and Streams....296

Basic Stream I/O....296

Text I/O....297

IO Output Contextual Properties....298

Working with Files....298

A simple TCP example....299

Resolving IP Addresses....301

Asynchronous I/O....301

Multicast....302

Parallel Computing....304

Asynchronous Programming....305

Basic Task operations....305

Communicating with Channels....306

More task operations....310

Tasks and events....310

Multi-Threading....312

Starting Julia with multiple threads....312

Threadpools....313

Communication and synchronization....314

The @threads Macro....315

Atomic Operations....316

Per-field atomics....317

Side effects and mutable function arguments....317

@threadcall....317

Caveats....318

Safe use of Finalizers....318

Multi-processing and Distributed Computing....320

Code Availability and Loading Packages....322

Starting and managing worker processes....324

Data Movement....325

Global variables....325

Parallel Map and Loops....327

Remote References and AbstractChannels....329

Channels and RemoteChannels....329

Local invocations....331

Shared Arrays....333

ClusterManagers....336

Specifying Network Topology (Experimental)....342

Noteworthy external packages....343

Running External Programs....346

Interpolation....347

Quoting....349

Pipelines....350

Cmd Objects....352

Calling C and Fortran Code....354

Creating C-Compatible Julia Function Pointers....356

Mapping C Types to Julia....358

Mapping C Functions to Julia....364

C Wrapper Examples....366

Fortran Wrapper Example....367

Garbage Collection Safety....368

Non-constant Function Specifications....368

Indirect Calls....369

Closure cfunctions....369

Closing a Library....370

Variadic function calls....370

ccall interface....370

Calling Convention....371

Accessing Global Variables....371

Accessing Data through a Pointer....372

Thread-safety....372

More About Callbacks....373

C++....373

Handling Operating System Variation....376

Environment Variables....377

File locations....377

Pkg.jl....380

Network transport....381

External applications....381

Parallelization....382

REPL formatting....383

Debugging and profiling....383

Embedding Julia....386

High-Level Embedding....386

High-Level Embedding on Windows with Visual Studio....388

Converting Types....389

Calling Julia Functions....390

Memory Management....390

Working with Arrays....393

Exceptions....395

Code Loading....398

Definitions....398

Federation of packages....399

Environments....400

Conclusion....410

Profiling....411

Basic usage....411

Accumulation and clearing....415

Options for controlling the display of profile results....415

Configuration....416

Memory allocation analysis....416

External Profiling....417

Stack Traces....419

Viewing a stack trace....419

Extracting useful information....420

Error handling....421

Exception stacks and current_exceptions....422

Comparison with backtrace....423

Performance Tips....425

Performance critical code should be inside a function....425

Avoid untyped global variables....425

Measure performance with @time and pay attention to memory allocation....426

Tools....428

Avoid containers with abstract type parameters....428

Type declarations....429

Break functions into multiple definitions....435

Write "type-stable" functions....436

Avoid changing the type of a variable....436

Separate kernel functions (aka, function barriers)....437

Types with values-as-parameters....438

The dangers of abusing multiple dispatch (aka, more on types with values-as-parameters)....439

Access arrays in memory order, along columns....440

Pre-allocating outputs....442

More dots: Fuse vectorized operations....443

Consider using views for slices....444

Copying data is not always bad....444

Consider StaticArrays.jl for small fixed-size vector/matrix operations....445

Avoid string interpolation for I/O....445

Optimize network I/O during parallel execution....446

Fix deprecation warnings....446

Tweaks....446

Performance Annotations....447

Treat Subnormal Numbers as Zeros....450

@code_warntype....451

Performance of captured variable....453

Workflow Tips....455

REPL-based workflow....455

Browser-based workflow....456

Revise-based workflows....456

Style Guide....458

Indentation....458

Write functions, not just scripts....458

Avoid writing overly-specific types....458

Handle excess argument diversity in the caller....459

Append ! to names of functions that modify their arguments....459

Avoid strange type Unions....460

Avoid elaborate container types....460

Prefer exported methods over direct field access....460

Use naming conventions consistent with Julia base/....461

Write functions with argument ordering similar to Julia Base....461

Don't overuse try-catch....462

Don't parenthesize conditions....462

Don't overuse .......462

Don't use unnecessary static parameters....462

Avoid confusion about whether something is an instance or a type....463

Don't overuse macros....463

Don't expose unsafe operations at the interface level....463

Don't overload methods of base container types....463

Avoid type piracy....464

Be careful with type equality....464

Do not write x->f(x)....464

Avoid using floats for numeric literals in generic code when possible....464

Frequently Asked Questions....466

General....466

Public API....467

Sessions and the REPL....467

Scripting....468

Variables and Assignments....469

Functions....469

Types, type declarations, and constructors....473

Troubleshooting "method not matched": parametric type invariance and MethodErrors....480

Packages and Modules....481

Nothingness and missing values....481

Memory....482

Asynchronous IO and concurrent synchronous writes....482

Arrays....483

Computing cluster....485

Julia Releases....485

Noteworthy Differences from other Languages....487

Noteworthy differences from MATLAB....487

Noteworthy differences from R....489

Noteworthy differences from Python....492

Noteworthy differences from C/C++....494

Noteworthy differences from Common Lisp....498

Unicode Input....501

Command-line Interface....502

Using arguments inside scripts....502

Parallel mode....502

Startup file....503

Command-line switches for Julia....503

Base....505

Essentials....506

Introduction....506

Getting Around....506

Keywords....511

Standard Modules....529

Base Submodules....530

All Objects....531

Properties of Types....544

Special Types....559

Generic Functions....568

Syntax....575

Missing Values....591

System....594

Versioning....607

Errors....608

Events....618

Reflection....619

Code loading....624

Internals....626

Meta....632

Collections and Data Structures....635

Iteration....635

Constructors and Types....637

General Collections....639

Iterable Collections....641

Indexable Collections....686

Dictionaries....688

Set-Like Collections....701

Dequeues....707

Utility Collections....716

Mathematics....718

Mathematical Operators....718

Mathematical Functions....746

Customizable binary operators....786

Numbers....787

Standard Numeric Types....787

Data Formats....792

General Number Functions and Constants....798

BigFloats and BigInts....812

Strings....815

Arrays....857

Constructors and Types....857

Basic functions....871

Broadcast and vectorization....877

Indexing and assignment....882

Views (SubArrays and other view types)....889

Concatenation and permutation....897

Array functions....916

Combinatorics....929

Tasks....933

Scheduling....937

Synchronization....939

Channels....945

Low-level synchronization using schedule and wait....950

Multi-Threading....953

Atomic operations....957

ccall using a libuv threadpool (Experimental)....965

Low-level synchronization primitives....965

Constants....967

Filesystem....971

I/O and Network....991

General I/O....991

Text I/O....1011

Multimedia I/O....1018

Network I/O....1022

Punctuation....1024

Sorting and Related Functions....1026

Sorting Functions....1028

Order-Related Functions....1035

Sorting Algorithms....1041

Alternate orderings....1041

Iteration utilities....1044

C Interface....1056

LLVM Interface....1068

C Standard Library....1069

StackTraces....1072

SIMD Support....1074

Standard Library....1075

ArgTools....1076

Argument Handling....1076

Function Testing....1077

Artifacts....1080

Base64....1082

CRC32c....1085

Dates....1086

Constructors....1086

Durations/Comparisons....1089

Accessor Functions....1090

Query Functions....1091

TimeType-Period Arithmetic....1092

Adjuster Functions....1094

Period Types....1095

Rounding....1096

API reference....1099

Dates and Time Types....1099

Dates Functions....1100

Delimited Files....1124

Distributed Computing....1129

Cluster Manager Interface....1144

Downloads....1147

File Events....1151

Pidfile....1153

Primary Functions....1153

Helper Functions....1154

Future....1155

Interactive Utilities....1156

Lazy Artifacts....1164

LibCURL....1165

LibGit2....1166

Dynamic Linker....1207

Linear Algebra....1210

Special matrices....1213

Matrix factorizations....1215

Standard functions....1215

Low-level matrix operations....1308

BLAS functions....1313

LAPACK functions....1324

Logging....1339

Log event structure....1340

Processing log events....1341

Testing log events....1342

Environment variables....1342

Examples....1343

Reference....1344

Markdown....1350

Inline elements....1350

Toplevel elements....1352

Markdown Syntax Extensions....1356

Memory-mapped I/O....1358

NetworkOptions....1361

Pkg....1365

Printf....1369

Profiling....1371

CPU Profiling....1371

Via @profile....1371

Triggered During Execution....1371

Reference....1372

Memory profiling....1375

Heap Snapshots....1376

The Julia REPL....1377

The different prompt modes....1377

Key bindings....1381

Tab completion....1382

Customizing Colors....1385

Changing the contextual module which is active at the REPL....1386

Numbered prompt....1387

TerminalMenus....1388

References....1391

Random Numbers....1397

Random numbers module....1398

Random generation functions....1398

Subsequences, permutations and shuffling....1402

Generators (creation and seeding)....1405

Hooking into the Random API....1408

Reproducibility....1415

SHA....1416

SHA functions....1416

Working with context....1419

HMAC functions....1422

Serialization....1426

Shared Arrays....1428

Sockets....1430

Sparse Arrays....1437

Compressed Sparse Column (CSC) Sparse Matrix Storage....1437

Sparse Vector Storage....1438

Sparse Vector and Matrix Constructors....1438

Sparse matrix operations....1440

Correspondence of dense and sparse methods....1440

SparseArrays API....1441

Noteworthy external packages....1453

Statistics....1454

TOML....1464

Parsing TOML data....1464

Exporting data to TOML file....1465

References....1466

Tar....1468

Unit Testing....1473

Testing Base Julia....1473

Basic Unit Tests....1473

Working with Test Sets....1476

Testing Log Statements....1480

Other Test Macros....1482

Broken Tests....1484

Creating Custom AbstractTestSet Types....1485

Test utilities....1487

Workflow for Testing Packages....1488

UUIDs....1492

Unicode....1494

Developer Documentation....1498

Reflection and introspection....1499

Module bindings....1499

DataType fields....1499

Subtypes....1500

DataType layout....1500

Function methods....1500

Expansion and lowering....1500

Intermediate and compiled representations....1501

Documentation of Julia's Internals....1502

Initialization of the Julia runtime....1502

Julia ASTs....1505

More about types....1518

Memory layout of Julia Objects....1527

Eval of Julia code....1530

Calling Conventions....1533

High-level Overview of the Native-Code Generation Process....1534

Julia Functions....1536

Base.Cartesian....1541

Talking to the compiler (the :meta mechanism)....1546

SubArrays....1546

isbits Union Optimizations....1550

System Image Building....1551

Package Images....1553

Working with LLVM....1555

printf() and stdio in the Julia runtime....1561

Bounds checking....1563

Proper maintenance and care of multi-threading locks....1565

Arrays with custom indices....1569

Module loading....1572

Inference....1573

Julia SSA-form IR....1575

EscapeAnalysis....1578

Static analyzer annotations for GC correctness in C code....1591

Garbage Collection in Julia....1596

Developing/debugging Julia's C code....1598

Reporting and analyzing crashes (segfaults)....1598

gdb debugging tips....1601

Using Valgrind with Julia....1605

Sanitizer support....1606

Instrumenting Julia with DTrace, and bpftrace....1609

Building Julia....1615

Building Julia (Detailed)....1615

Linux....1622

macOS....1623

Windows....1624

tools....1626

For 64 bit Julia, install x86_64....1626

For 32 bit Julia, install i686....1626

FreeBSD....1628

ARM (Linux)....1629

Binary distributions....1630

Point releasing 101....1632

Julia v1.9 Release Notes....1639

New language features....1639

Language changes....1639

Compiler/Runtime improvements....1639

Command-line option changes....1640

Multi-threading changes....1640

Build system changes....1640

New library functions....1640

New library features....1641

Standard library changes....1641

Deprecated or removed....1643

External dependencies....1643

Tooling Improvements....1643

Scientific computing has traditionally required the highest performance, yet domain experts have largely moved to slower dynamic languages for daily work. We believe there are many good reasons to prefer dynamic languages for these applications, and we do not expect their use to diminish. Fortunately, modern language design and compiler techniques make it possible to mostly eliminate the performance trade-off and provide a single environment productive enough for prototyping and efficient enough for deploying performance-intensive applications. The Julia programming language fills this role: it is a flexible dynamic language, appropriate for scientific and numerical computing, with performance comparable to traditional statically-typed languages.

Because Julia's compiler is different from the interpreters used for languages like Python or R, you may find that Julia's performance is unintuitive at first. If you find that something is slow, we highly recommend reading through the Performance Tips section before trying anything else. Once you understand how Julia works, it's easy to write code that's nearly as fast as C.

Julia features optional typing, multiple dispatch, and good performance, achieved using type inference and just-in-time (JIT) compilation (and optional ahead-of-time compilation), implemented using LLVM. It is multi-paradigm, combining features of imperative, functional, and object-oriented programming. Julia provides ease and expressiveness for high-level numerical computing, in the same way as languages such as R, MATLAB, and Python, but also supports general programming. To achieve this, Julia builds upon the lineage of mathematical programming languages, but also borrows much from popular dynamic languages, including Lisp, Perl, Python, Lua, and Ruby.