The Julia Language 1.12.5

Contents....2 Manual....16 Julia 1.12 Documentation....17 Introduction....17 Julia Compared to Other Languages....17 Important Links....19 Getting Started....20 Resources....21 Installation....22 Windows....22 Mac and Linux....22 Alternative installation methods....23 Variables....25 Allowed Variable Names....27 Assignment expressions and assignment versus mutation....28 Stylistic Conventions....29 Integers and Floating-Point Numbers....30 Integers....31 Floating-Point Numbers....35 Arbitrary Precision Arithmetic....40 Numeric Literal Coefficients....42 Literal zero and one....44 Mathematical Operations and Elementary Functions....45 Arithmetic Operators....45 Boolean Operators....46 Bitwise Operators....46 Updating operators....47 Vectorized "dot" operators....48 Numeric Comparisons....49 Operator Precedence and Associativity....52 Numerical Conversions....53 Complex and Rational Numbers....57 Complex Numbers....57 Rational Numbers....60 Strings....64 Characters....65 String Basics....67 Unicode and UTF-8....68 Concatenation....72 Interpolation....73 Triple-Quoted String Literals....74 Common Operations....76 Non-Standard String Literals....77 Regular Expressions....77 Byte Array Literals....82 Version Number Literals....84 Raw String Literals....84 Annotated Strings....85 Functions....87 Argument Passing Behavior....88 Argument-type declarations....89 The return Keyword....90 Operators Are Functions....92 Operators With Special Names....92 Anonymous Functions....92 Tuples....93 Named Tuples....94 Destructuring Assignment and Multiple Return Values....94 Property destructuring....97 Argument destructuring....98 Varargs Functions....98 Optional Arguments....100 Keyword Arguments....101 Evaluation Scope of Default Values....103 Do-Block Syntax for Function Arguments....103 Function composition and piping....104 Dot Syntax for Vectorizing Functions....105 Further Reading....107 Control Flow....108 Compound Expressions....108 Conditional Evaluation....109 Short-Circuit Evaluation....112 Repeated Evaluation: Loops....115 Exception Handling....118 Tasks (aka Coroutines)....124 Scope of Variables....125 Global Scope....127 Local Scope....127 Constants....138 Typed Globals....139 Types....140 Type Declarations....141 Abstract Types....143 Primitive Types....144 Composite Types....145 Mutable Composite Types....147 Declared Types....149 Type Unions....149 Parametric Types....150 UnionAll Types....158 Singleton types....159 Types of functions....160 Type{T} type selectors....161 Type Aliases....163 Operations on Types....163 Custom pretty-printing....164 "Value types"....168 Methods....170 Defining Methods....171 Method specializations....175 Method Ambiguities....175 Parametric Methods....176 Redefining Methods....179 Design Patterns with Parametric Methods....180 Parametrically-constrained Varargs methods....184 Note on Optional and keyword Arguments....185 Function-like objects....186 Empty generic functions....186 Method design and the avoidance of ambiguities....186 Defining methods in local scope....189 Constructors....191 Outer Constructor Methods....192 Inner Constructor Methods....192 Incomplete Initialization....194 Parametric Constructors....196 Case Study: Rational....198 Outer-only constructors....200 Constructors are just callable objects....201 Conversion and Promotion....203 Conversion....204 Promotion....206 Interfaces....210 Iteration....210 Indexing....213 Abstract Arrays....214 Strided Arrays....217 Customizing broadcasting....217 Instance Properties....222 Rounding....224 Modules....228 Namespace management....229 Submodules and relative paths....236 Module initialization and precompilation....237 Documentation....242 Accessing Documentation....242 Writing Documentation....242 Functions & Methods....246 Advanced Usage....247 Syntax Guide....248 Metaprogramming....255 Program representation....255 Expressions and evaluation....258 Macros....263 Code Generation....271 Non-Standard String Literals....272 Generated functions....274 Single- and multi-dimensional Arrays....282 Basic Functions....282 Construction and Initialization....282 Array literals....283 Comprehensions....288 Generator Expressions....289 Indexing....290 Indexed Assignment....292 Supported index types....293 Iteration....299 Array traits....300 Array and Vectorized Operators and Functions....300 Broadcasting....300 Implementation....302 Missing Values....304 Propagation of Missing Values....304 Equality and Comparison Operators....305 Logical operators....306 Control Flow and Short-Circuiting Operators....307 Arrays With Missing Values....308 Skipping Missing Values....309 Logical Operations on Arrays....310 Networking and Streams....312 Basic Stream IO....312 Text IO....313 IO Output Contextual Properties....314 Working with Files....314 A simple TCP example....316 Resolving IP Addresses....318 Asynchronous IO....318 Multicast....319 Parallel Computing....321 Asynchronous Programming....322 Basic Task operations....322 Communicating with Channels....323 More task operations....327 Tasks and events....328 Multi-Threading....329 Starting Julia with multiple threads....329 Threadpools....331 The threads Macro....332 Communication and data-races between threads....334 Side effects and mutable function arguments....337 threadcall....337 Caveats....338 Task Migration....338 Safe use of Finalizers....338 Multi-processing and Distributed Computing....340 Code Availability and Loading Packages....342 Starting and managing worker processes....344 Data Movement....345 Global variables....345 Parallel Map and Loops....347 Remote References and AbstractChannels....349 Channels and RemoteChannels....350 Local invocations....352 Shared Arrays....354 ClusterManagers....357 Specifying Network Topology (Experimental)....363 Noteworthy external packages....364 Running External Programs....367 Interpolation....368 Quoting....370 Pipelines....371 Cmd Objects....373 Calling C and Fortran Code....375 Creating C-Compatible Julia Function Pointers....377 Mapping C Types to Julia....379 Mapping C Functions to Julia....385 C Wrapper Examples....388 Fortran Wrapper Example....389 Garbage Collection Safety....389 Non-constant Function Specifications....390 Indirect Calls....390 Closure cfunctions....391 Closing a Library....391 Variadic function calls....392 ccall interface....392 Calling Convention....392 Accessing Global Variables....393 Accessing Data through a Pointer....393 Thread-safety....394 More About Callbacks....394 C....395 Handling Operating System Variation....398 Environment Variables....399 File locations....399 Pkg.jl....402 Network transport....404 External applications....405 Parallelization....405 Garbage Collection....407 REPL formatting....407 System and Package Image Building....408 Debugging and profiling....409 Embedding Julia....411 High-Level Embedding....411 High-Level Embedding on Windows with Visual Studio....413 Converting Types....414 Calling Julia Functions....415 Memory Management....415 Working with Arrays....419 Exceptions....420 Code Loading....424 Definitions....424 Federation of packages....425 Environments....426 Conclusion....436 Profiling....438 Basic usage....438 Accumulation and clearing....442 Options for controlling the display of profile results....442 Configuration....443 Wall-time Profiler....443 Memory allocation analysis....449 External Profiling....452 Stack Traces....454 Viewing a stack trace....454 Extracting useful information....455 Error handling....456 Exception stacks and current_exceptions....457 Comparison with backtrace....458 Memory Management and Garbage Collection....460 Garbage Collection Overview....460 Memory Architecture....460 System Memory Requirements....461 Multithreaded Garbage Collection....461 Monitoring and Debugging....462 Performance Considerations....463 Advanced Configuration....463 Troubleshooting Memory Issues....463 Performance Tips....465 Table of contents....465 General advice....466 Type inference....470 Memory management and arrays....485 Execution latency, package loading and package precompiling time....491 Miscellaneous....494 Workflow Tips....501 REPL-based workflow....501 Browser-based workflow....502 Revise-based workflows....502 Style Guide....504 Indentation....504 Write functions, not just scripts....504 Avoid writing overly-specific types....504 Handle excess argument diversity in the caller....505 Append ! to names of functions that modify their arguments....505 Avoid strange type Unions....506 Avoid elaborate container types....506 Prefer exported methods over direct field access....506 Use naming conventions consistent with Julia base....507 Write functions with argument ordering similar to Julia Base....507 Don't overuse try-catch....508 Don't parenthesize conditions....508 Don't overuse .......508 Ensure constructors return an instance of their own type....508 Don't use unnecessary static parameters....509 Avoid confusion about whether something is an instance or a type....509 Don't overuse macros....509 Don't expose unsafe operations at the interface level....510 Don't overload methods of base container types....510 Avoid type piracy....510 Be careful with type equality....511 Don't write a trivial anonymous function x->f(x) for a named function f....511 Avoid using floats for numeric literals in generic code when possible....511 Frequently Asked Questions....513 General....513 Public API....514 Sessions and the REPL....514 Scripting....515 Variables and Assignments....516 Functions....516 Types, type declarations, and constructors....520 Troubleshooting "method not matched": parametric type invariance and MethodErrors....527 Packages and Modules....528 Nothingness and missing values....528 Memory....529 Asynchronous IO and concurrent synchronous writes....529 Arrays....530 Computing cluster....532 Julia Releases....532 Noteworthy Differences from other Languages....534 Noteworthy differences from MATLAB....534 Noteworthy differences from R....536 Noteworthy differences from Python....539 Noteworthy differences from CC....542 Noteworthy differences from Common Lisp....546 Unicode Input....548 Command-line Interface....549 Using arguments inside scripts....549 The Main.main entry point....550 Parallel mode....551 Startup file....551 Command-line switches for Julia....551 The World Age mechanism....554 World age in general....554 Temporarily raising the world age using invokelatest....556 World age and const struct redefinitions....557 World age and usingimport....558 World age capture....559 Base....562 Essentials....563 Introduction....563 Getting Around....563 Keywords....570 Standard Modules....592 Base Submodules....593 All Objects....594 Properties of Types....610 Special Types....627 Generic Functions....638 Syntax....647 Managing deprecations....666 Missing Values....667 System....670 Versioning....690 Errors....692 Events....702 Reflection....704 Documentation....714 Code loading....716 Internals....717 Meta....724 Collections and Data Structures....727 Iteration....727 Constructors and Types....729 General Collections....731 Iterable Collections....733 Indexable Collections....782 Dictionaries....784 Set-Like Collections....798 Dequeues....807 Utility Collections....816 Mathematics....818 Mathematical Operators....818 Mathematical Functions....851 Customizable binary operators....896 Numbers....897 Standard Numeric Types....897 Data Formats....904 General Number Functions and Constants....911 BigFloats and BigInts....925 Strings....929 AnnotatedStrings....974 Arrays....978 Constructors and Types....978 Basic functions....993 Broadcast and vectorization....999 Indexing and assignment....1004 Views (SubArrays and other view types)....1015 Concatenation and permutation....1024 Array functions....1047 Combinatorics....1060 Tasks....1065 Scheduling....1070 Synchronization....1072 Channels....1080 Low-level synchronization using schedule and wait....1086 Multi-Threading....1089 Atomic operations....1095 ccall using a libuv threadpool (Experimental)....1106 Low-level synchronization primitives....1107 Task metrics (Experimental)....1107 Scoped Values....1109 Example....1112 Idioms....1113 API docs....1114 Implementation notes and performance....1117 Design inspiration....1117 Constants....1118 Filesystem....1122 IO and Network....1146 General IO....1146 Text IO....1170 Multimedia IO....1178 Network IO....1183 Punctuation....1185 Sorting and Related Functions....1187 Sorting Functions....1189 Order-Related Functions....1198 Sorting Algorithms....1204 Alternate Orderings....1205 Iteration utilities....1207 Reflection and introspection....1219 Module bindings....1219 DataType fields....1219 Subtypes....1220 DataType layout....1220 Function methods....1220 Expansion and lowering....1220 Intermediate and compiled representations....1221 C Interface....1222 LLVM Interface....1237 C Standard Library....1238 StackTraces....1243 SIMD Support....1245 Standard Library....1246 ArgTools....1247 Argument Handling....1247 Function Testing....1248 Artifacts....1251 Base64....1254 CRC32c....1257 Dates....1258 Constructors....1258 DurationsComparisons....1261 Accessor Functions....1262 Query Functions....1263 TimeType-Period Arithmetic....1264 Adjuster Functions....1266 Period Types....1267 Rounding....1268 API reference....1270 Delimited Files....1295 Distributed Computing....1300 Cluster Manager Interface....1316 Downloads....1320 Dynamic Linker....1324 File Events....1327 Pidfile....1331 Primary Functions....1331 Helper Functions....1332 Future....1334 Interactive Utilities....1335 Julia Syntax Highlighting....1344 Functions....1344 Faces....1345 Lazy Artifacts....1348 LibCURL....1349 LibGit2....1350 Linear Algebra....1391 Special matrices....1394 Matrix factorizations....1396 Orthogonal matrices (AbstractQ)....1396 Pivoting Strategies....1398 Standard functions....1399 Low-level matrix operations....1500 BLAS functions....1506 LAPACK functions....1517 Developer Documentation....1532 Logging....1534 Log event structure....1535 Processing log events....1536 Testing log events....1537 Environment variables....1537 Examples....1538 Reference....1539 Markdown....1545 Inline elements....1545 Toplevel elements....1547 Markdown String Literals....1552 Markdown Syntax Extensions....1552 API reference....1552 Memory-mapped IO....1555 Network Options....1558 Pkg....1562 Printf....1566 Profiling....1569 CPU Profiling....1569 Via profile....1569 Triggered During Execution....1569 Reference....1570 Memory profiling....1573 Heap Snapshots....1574 Random Numbers....1576 Random numbers module....1577 Random generation functions....1577 Subsequences, permutations and shuffling....1581 Generators (creation and seeding)....1585 Hooking into the Random API....1588 Reproducibility....1595 The Julia REPL....1596 The different prompt modes....1596 Key bindings....1600 Tab completion....1601 Customizing Colors....1605 Changing the contextual module which is active at the REPL....1605 Numbered prompt....1606 TerminalMenus....1607 References....1610 Serialization....1616 SHA....1618 SHA functions....1618 Working with context....1622 HMAC functions....1625 Shared Arrays....1629 Sockets....1631 Sparse Arrays....1639 Compressed Sparse Column (CSC) Sparse Matrix Storage....1639 Sparse Vector Storage....1640 Sparse Vector and Matrix Constructors....1640 Sparse matrix operations....1642 Correspondence of dense and sparse methods....1642 SparseArrays API....1643 Noteworthy External Sparse Packages....1657 Statistics....1659 StyledStrings....1668 Styling....1668 Annotated Strings....1669 Styling via AnnotatedStrings....1669 Faces....1669 Styled String Literals....1672 API reference....1673 Tar....1678 TOML....1683 Parsing TOML data....1683 Exporting data to TOML file....1684 References....1685 Unicode....1687 Unit Testing....1692 Testing Base Julia....1692 Basic Unit Tests....1692 Working with Test Sets....1695 Testing Log Statements....1700 Other Test Macros....1702 Broken Tests....1704 Test result types....1705 Creating Custom AbstractTestSet Types....1706 Test utilities....1709 Workflow for Testing Packages....1710 UUIDs....1714 Developer Documentation....1716 Documentation of Julia's Internals....1717 Initialization of the Julia runtime....1717 Julia ASTs....1720 More about types....1735 Memory layout of Julia Objects....1744 Eval of Julia code....1747 Calling Conventions....1751 High-level Overview of the Native-Code Generation Process....1752 Julia Functions....1754 Base.Cartesian....1758 Talking to the compiler (the :meta mechanism)....1763 SubArrays....1764 isbits Union Optimizations....1768 System Image Building....1769 Package Images....1773 Custom LLVM Passes....1774 Working with LLVM....1779 printf() and stdio in the Julia runtime....1787 Bounds checking....1789 Proper maintenance and care of multi-threading locks....1791 Arrays with custom indices....1795 Module loading....1798 Inference....1799 Julia SSA-form IR....1801 EscapeAnalysis....1806 Ahead of Time Compilation....1821 Static analyzer annotations for GC correctness in C code....1824 Garbage Collection in Julia....1830 JIT Design and Implementation....1832 Core.Builtins....1837 Fixing precompilation hangs due to open tasks or IO....1841 Developingdebugging Julia's C code....1844 Reporting and analyzing crashes (segfaults)....1844 gdb debugging tips....1847 Using Valgrind with Julia....1851 External Profiler Support....1853 Sanitizer support....1856 Instrumenting Julia with DTrace, and bpftrace....1858 Building Julia....1865 Building Julia (Detailed)....1865 Linux....1874 macOS....1874 Windows....1874 FreeBSD....1880 ARM (Linux)....1880 RISC-V (Linux)....1881 Binary distributions....1883 Point releasing 101....1885 Julia v1.12 Release Notes....1892 New language features....1892 Language changes....1893 CompilerRuntime improvements....1893 Command-line option changes....1894 Multi-threading changes....1894 Build system changes....1894 New library functions....1894 New library features....1895 Standard library changes....1895 External dependencies....1897 Tooling Improvements....1897