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