Essentials

Introduction

Julia Base contains a range of functions and macros appropriate for performing scientific and numerical computing, but is also as broad as those of many general purpose programming languages. Additional functionality is available from a growing collection of available packages. Functions are grouped by topic below.

Some general notes:

To use module functions, use import Module to import the module, and Module.fn(x) to use the functions.
Alternatively, using Module will import all exported Module functions into the current namespace.
By convention, function names ending with an exclamation point (!) modify their arguments. Some functions have both modifying (e.g., sort!) and non-modifying (sort) versions.

The behaviors of Base and standard libraries are stable as defined in SemVer only if they are documented; i.e., included in the Julia documentation and not marked as unstable. See API FAQ for more information.

Getting Around

# Base.exit — Function

exit(code=0)

Stop the program with an exit code. The default exit code is zero, indicating that the program completed successfully. In an interactive session, exit() can be called with the keyboard shortcut ^D.

# Base.atexit — Function

atexit(f)

Register a zero- or one-argument function f() to be called at process exit. atexit() hooks are called in last in first out (LIFO) order and run before object finalizers.

If f has a method defined for one integer argument, it will be called as f(n::Int32), where n is the current exit code, otherwise it will be called as f().

Compatibility: Julia 1.9

The one-argument form requires Julia 1.9

Exit hooks are allowed to call exit(n), in which case Julia will exit with exit code n (instead of the original exit code). If more than one exit hook calls exit(n), then Julia will exit with the exit code corresponding to the last called exit hook that calls exit(n). (Because exit hooks are called in LIFO order, "last called" is equivalent to "first registered".)

Once all exit hooks have been called, no more exit hooks can be registered, and any call to atexit(f) after all hooks have completed will throw an exception. This situation may occur if you are registering exit hooks from background Tasks that may still be executing concurrently during shutdown.

# Base.isinteractive — Function

isinteractive() -> Bool

Determine whether Julia is running an interactive session.

# Base.summarysize — Function

Base.summarysize(obj; exclude=Union{...}, chargeall=Union{...}) -> Int

Compute the amount of memory, in bytes, used by all unique objects reachable from the argument.

Keyword Arguments

exclude: specifies the types of objects to exclude from the traversal.
chargeall: specifies the types of objects to always charge the size of all of their fields, even if those fields would normally be excluded.

Keywords

This is the list of reserved keywords in Julia: baremodule, begin, break, catch, const, continue, do, else, elseif, end, export, false, finally, for, function, global, if, import, let, local, macro, module, quote, return, struct, true, try, using, while. Those keywords are not allowed to be used as variable names.

The following two-word sequences are reserved: abstract type, mutable struct, primitive type. However, you can create variables with names: abstract, mutable, primitive and type.

Finally: where is parsed as an infix operator for writing parametric method and type definitions; in and isa are parsed as infix operators; and outer is parsed as a keyword when used to modify the scope of a variable in an iteration specification of a for loop. Creation of variables named where, in, isa or outer is allowed though.

# module — Keyword

module

module declares a Module, which is a separate global variable workspace. Within a module, you can control which names from other modules are visible (via importing), and specify which of your names are intended to be public (via exporting). Modules allow you to create top-level definitions without worrying about name conflicts when your code is used together with somebody else’s. See the manual section about modules for more details.

Examples

module Foo
import Base.show
export MyType, foo

struct MyType
    x
end

bar(x) = 2x
foo(a::MyType) = bar(a.x) + 1
show(io::IO, a::MyType) = print(io, "MyType $(a.x)")
end

# export — Keyword

export

export is used within modules to tell Julia which functions should be made available to the user. For example: export foo makes the name foo available when using the module. See the manual section about modules for details.

# import — Keyword

import

import Foo will load the module or package Foo. Names from the imported Foo module can be accessed with dot syntax (e.g. Foo.foo to access the name foo). See the manual section about modules for details.

# using — Keyword

using

using Foo will load the module or package Foo and make its exported names available for direct use. Names can also be used via dot syntax (e.g. Foo.foo to access the name foo), whether they are exported or not. See the manual section about modules for details.

# baremodule — Keyword

baremodule

baremodule declares a module that does not contain using Base or local definitions of eval and include. It does still import Core. In other words,

module Mod

...

end

is equivalent to

baremodule Mod

using Base

eval(x) = Core.eval(Mod, x)
include(p) = Base.include(Mod, p)

...

end

# function — Keyword

function

Functions are defined with the function keyword:

function add(a, b)
    return a + b
end

Or the short form notation:

add(a, b) = a + b

The use of the return keyword is exactly the same as in other languages, but is often optional. A function without an explicit return statement will return the last expression in the function body.

# macro — Keyword

macro

macro defines a method for inserting generated code into a program. A macro maps a sequence of argument expressions to a returned expression, and the resulting expression is substituted directly into the program at the point where the macro is invoked. Macros are a way to run generated code without calling eval, since the generated code instead simply becomes part of the surrounding program. Macro arguments may include expressions, literal values, and symbols. Macros can be defined for variable number of arguments (varargs), but do not accept keyword arguments. Every macro also implicitly gets passed the arguments __source__, which contains the line number and file name the macro is called from, and __module__, which is the module the macro is expanded in.

See the manual section on Metaprogramming for more information about how to write a macro.

Examples

julia> macro sayhello(name)
           return :( println("Hello, ", $name, "!") )
       end
@sayhello (macro with 1 method)

julia> @sayhello "Charlie"
Hello, Charlie!

julia> macro saylots(x...)
           return :( println("Say: ", $(x...)) )
       end
@saylots (macro with 1 method)

julia> @saylots "hey " "there " "friend"
Say: hey there friend

# return — Keyword

return

return x causes the enclosing function to exit early, passing the given value x back to its caller. return by itself with no value is equivalent to return nothing (see nothing).

function compare(a, b)
    a == b && return "equal to"
    a < b ? "less than" : "greater than"
end

In general you can place a return statement anywhere within a function body, including within deeply nested loops or conditionals, but be careful with do blocks. For example:

function test1(xs)
    for x in xs
        iseven(x) && return 2x
    end
end

function test2(xs)
    map(xs) do x
        iseven(x) && return 2x
        x
    end
end

In the first example, the return breaks out of test1 as soon as it hits an even number, so test1([5,6,7]) returns 12.

You might expect the second example to behave the same way, but in fact the return there only breaks out of the inner function (inside the do block) and gives a value back to map. test2([5,6,7]) then returns [5,12,7].

When used in a top-level expression (i.e. outside any function), return causes the entire current top-level expression to terminate early.

# do — Keyword

do

Create an anonymous function and pass it as the first argument to a function call. For example:

map(1:10) do x
    2x
end

is equivalent to map(x->2x, 1:10).

Use multiple arguments like so:

map(1:10, 11:20) do x, y
    x + y
end

# begin — Keyword

begin

begin...end denotes a block of code.

begin
    println("Hello, ")
    println("World!")
end

Usually begin will not be necessary, since keywords such as function and let implicitly begin blocks of code. See also ;.

begin may also be used when indexing to represent the first index of a collection or the first index of a dimension of an array.

Examples

julia> A = [1 2; 3 4]
2×2 Array{Int64,2}:
 1  2
 3  4

julia> A[begin, :]
2-element Array{Int64,1}:
 1
 2

# end — Keyword

end

end marks the conclusion of a block of expressions, for example module, struct, mutable struct, begin, let, for etc.

end may also be used when indexing to represent the last index of a collection or the last index of a dimension of an array.

Examples

julia> A = [1 2; 3 4]
2×2 Array{Int64, 2}:
 1  2
 3  4

julia> A[end, :]
2-element Array{Int64, 1}:
 3
 4

# let — Keyword

let

let blocks create a new hard scope and optionally introduce new local bindings.

Just like the other scope constructs, let blocks define the block of code where newly introduced local variables are accessible. Additionally, the syntax has a special meaning for comma-separated assignments and variable names that may optionally appear on the same line as the let:

let var1 = value1, var2, var3 = value3
    code
end

The variables introduced on this line are local to the let block and the assignments are evaluated in order, with each right-hand side evaluated in the scope without considering the name on the left-hand side. Therefore it makes sense to write something like let x = x, since the two x variables are distinct with the left-hand side locally shadowing the x from the outer scope. This can even be a useful idiom as new local variables are freshly created each time local scopes are entered, but this is only observable in the case of variables that outlive their scope via closures.

By contrast, begin blocks also group multiple expressions together but do not introduce scope or have the special assignment syntax.

Examples

In the function below, there is a single x that is iteratively updated three times by the map. The closures returned all reference that one x at its final value:

julia> function test_outer_x()
           x = 0
           map(1:3) do _
               x += 1
               return ()->x
           end
       end
test_outer_x (generic function with 1 method)

julia> [f() for f in test_outer_x()]
3-element Vector{Int64}:
 3
 3
 3

If, however, we add a let block that introduces a new local variable we will end up with three distinct variables being captured (one at each iteration) even though we chose to use (shadow) the same name.

julia> function test_let_x()
           x = 0
           map(1:3) do _
               x += 1
               let x = x
                   return ()->x
               end
           end
       end
test_let_x (generic function with 1 method)

julia> [f() for f in test_let_x()]
3-element Vector{Int64}:
 1
 2
 3

All scope constructs that introduce new local variables behave this way when repeatedly run; the distinctive feature of let is its ability to succinctly declare new locals that may shadow outer variables of the same name. For example, directly using the argument of the do function similarly captures three distinct variables:

julia> function test_do_x()
           map(1:3) do x
               return ()->x
           end
       end
test_do_x (generic function with 1 method)

julia> [f() for f in test_do_x()]
3-element Vector{Int64}:
 1
 2
 3

# if — Keyword

if/elseif/else

if/elseif/else performs conditional evaluation, which allows portions of code to be evaluated or not evaluated depending on the value of a boolean expression. Here is the anatomy of the if/elseif/else conditional syntax:

if x < y
    println("x is less than y")
elseif x > y
    println("x is greater than y")
else
    println("x is equal to y")
end

If the condition expression x < y is true, then the corresponding block is evaluated; otherwise the condition expression x > y is evaluated, and if it is true, the corresponding block is evaluated; if neither expression is true, the else block is evaluated. The elseif and else blocks are optional, and as many elseif blocks as desired can be used.

In contrast to some other languages conditions must be of type Bool. It does not suffice for conditions to be convertible to Bool.

julia> if 1 end
ERROR: TypeError: non-boolean (Int64) used in boolean context

# for — Keyword

for

for loops repeatedly evaluate a block of statements while iterating over a sequence of values.

The iteration variable is always a new variable, even if a variable of the same name exists in the enclosing scope. Use outer to reuse an existing local variable for iteration.

Examples

julia> for i in [1, 4, 0]
           println(i)
       end
1
4
0

# while — Keyword

while

while loops repeatedly evaluate a conditional expression, and continue evaluating the body of the while loop as long as the expression remains true. If the condition expression is false when the while loop is first reached, the body is never evaluated.

Examples

julia> i = 1
1

julia> while i < 5
           println(i)
           global i += 1
       end
1
2
3
4

# break — Keyword

break

Break out of a loop immediately.

Examples

julia> i = 0
0

julia> while true
           global i += 1
           i > 5 && break
           println(i)
       end
1
2
3
4
5

# continue — Keyword

continue

Skip the rest of the current loop iteration.

Examples

julia> for i = 1:6
           iseven(i) && continue
           println(i)
       end
1
3
5

# try — Keyword

try/catch

A try/catch statement allows intercepting errors (exceptions) thrown by throw so that program execution can continue. For example, the following code attempts to write a file, but warns the user and proceeds instead of terminating execution if the file cannot be written:

try
    open("/danger", "w") do f
        println(f, "Hello")
    end
catch
    @warn "Could not write file."
end

or, when the file cannot be read into a variable:

lines = try
    open("/danger", "r") do f
        readlines(f)
    end
catch
    @warn "File not found."
end

The syntax catch e (where e is any variable) assigns the thrown exception object to the given variable within the catch block.

The power of the try/catch construct lies in the ability to unwind a deeply nested computation immediately to a much higher level in the stack of calling functions.

# finally — Keyword

finally

Run some code when a given block of code exits, regardless of how it exits. For example, here is how we can guarantee that an opened file is closed:

f = open("file")
try
    operate_on_file(f)
finally
    close(f)
end

When control leaves the try block (for example, due to a return, or just finishing normally), close(f) will be executed. If the try block exits due to an exception, the exception will continue propagating. A catch block may be combined with try and finally as well. In this case the finally block will run after catch has handled the error.

# quote — Keyword

quote

quote creates multiple expression objects in a block without using the explicit Expr constructor. For example:

ex = quote
    x = 1
    y = 2
    x + y
end

Unlike the other means of quoting, :( ... ), this form introduces QuoteNode elements to the expression tree, which must be considered when directly manipulating the tree. For other purposes, :( ... ) and quote .. end blocks are treated identically.

# local — Keyword

local

local introduces a new local variable. See the manual section on variable scoping for more information.

Examples

julia> function foo(n)
           x = 0
           for i = 1:n
               local x # introduce a loop-local x
               x = i
           end
           x
       end
foo (generic function with 1 method)

julia> foo(10)
0

# global — Keyword

global

global x makes x in the current scope and its inner scopes refer to the global variable of that name. See the manual section on variable scoping for more information.

Examples

julia> z = 3
3

julia> function foo()
           global z = 6 # use the z variable defined outside foo
       end
foo (generic function with 1 method)

julia> foo()
6

julia> z
6

# outer — Keyword

for outer

Reuse an existing local variable for iteration in a for loop.

See the manual section on variable scoping for more information.

Standard Modules

# Main — Module

Main

Main is the top-level module, and Julia starts with Main set as the current module. Variables defined at the prompt go in Main, and varinfo lists variables in Main.

julia> @__MODULE__
Main

# Core — Module

Core

Core is the module that contains all identifiers considered "built in" to the language, i.e. part of the core language and not libraries. Every module implicitly specifies using Core, since you can’t do anything without those definitions.

# Base — Module

Base

The base library of Julia. Base is a module that contains basic functionality (the contents of base/). All modules implicitly contain using Base, since this is needed in the vast majority of cases.

Base Submodules

# Base.Broadcast — Module

Base.Broadcast

Module containing the broadcasting implementation.

# Base.Docs — Module

Docs

The Docs module provides the @doc macro which can be used to set and retrieve documentation metadata for Julia objects.

Please see the manual section on documentation for more information.

# Base.Iterators — Module

Methods for working with Iterators.

# Base.Libc — Module

Interface to libc, the C standard library.

# Base.Meta — Module

Convenience functions for metaprogramming.

# Base.StackTraces — Module

Tools for collecting and manipulating stack traces. Mainly used for building errors.

# Base.Sys — Module

Provide methods for retrieving information about hardware and the operating system.

# Base.Threads — Module

Multithreading support.

# Base.GC — Module

Base.GC

Module with garbage collection utilities.

All Objects

# Core.:=== — Function

===(x,y) -> Bool
≡(x,y) -> Bool

Determine whether x and y are identical, in the sense that no program could distinguish them. First the types of x and y are compared. If those are identical, mutable objects are compared by address in memory and immutable objects (such as numbers) are compared by contents at the bit level. This function is sometimes called "egal". It always returns a Bool value.

Examples

julia> a = [1, 2]; b = [1, 2];

julia> a == b
true

julia> a === b
false

julia> a === a
true

# Core.isa — Function

isa(x, type) -> Bool

Determine whether x is of the given type. Can also be used as an infix operator, e.g. x isa type.

Examples

julia> isa(1, Int)
true

julia> isa(1, Matrix)
false

julia> isa(1, Char)
false

julia> isa(1, Number)
true

julia> 1 isa Number
true

# Base.isequal — Function

isequal(x, y)

Similar to ==, except for the treatment of floating point numbers and of missing values. isequal treats all floating-point NaN values as equal to each other, treats -0.0 as unequal to 0.0, and missing as equal to missing. Always returns a Bool value.

isequal is an equivalence relation - it is reflexive (=== implies isequal), symmetric (isequal(a, b) implies isequal(b, a)) and transitive (isequal(a, b) and isequal(b, c) implies isequal(a, c)).

Implementation

The default implementation of isequal calls ==, so a type that does not involve floating-point values generally only needs to define ==.

isequal is the comparison function used by hash tables (Dict). isequal(x,y) must imply that hash(x) == hash(y).

This typically means that types for which a custom == or isequal method exists must implement a corresponding hash method (and vice versa). Collections typically implement isequal by calling isequal recursively on all contents.

Furthermore, isequal is linked with isless, and they work together to define a fixed total ordering, where exactly one of isequal(x, y), isless(x, y), or isless(y, x) must be true (and the other two false).

Scalar types generally do not need to implement isequal separate from ==, unless they represent floating-point numbers amenable to a more efficient implementation than that provided as a generic fallback (based on isnan, signbit, and ==).

Examples

julia> isequal([1., NaN], [1., NaN])
true

julia> [1., NaN] == [1., NaN]
false

julia> 0.0 == -0.0
true

julia> isequal(0.0, -0.0)
false

julia> missing == missing
missing

julia> isequal(missing, missing)
true

isequal(x)

Create a function that compares its argument to x using isequal, i.e. a function equivalent to y -> isequal(y, x).

The returned function is of type Base.Fix2{typeof(isequal)}, which can be used to implement specialized methods.

# Base.isless — Function

isless(x, y)

Test whether x is less than y, according to a fixed total order (defined together with isequal). isless is not defined on all pairs of values (x, y). However, if it is defined, it is expected to satisfy the following:

If isless(x, y) is defined, then so is isless(y, x) and isequal(x, y), and exactly one of those three yields true.
The relation defined by isless is transitive, i.e., isless(x, y) && isless(y, z) implies isless(x, z).

Values that are normally unordered, such as NaN, are ordered after regular values. missing values are ordered last.

This is the default comparison used by sort.

Implementation

Non-numeric types with a total order should implement this function. Numeric types only need to implement it if they have special values such as NaN. Types with a partial order should implement <. See the documentation on Alternate orderings for how to define alternate ordering methods that can be used in sorting and related functions.

Examples

julia> isless(1, 3)
true

julia> isless("Red", "Blue")
false

# Base.ifelse — Function

ifelse(condition::Bool, x, y)

Return x if condition is true, otherwise return y. This differs from ? or if in that it is an ordinary function, so all the arguments are evaluated first. In some cases, using ifelse instead of an if statement can eliminate the branch in generated code and provide higher performance in tight loops.

Examples

julia> ifelse(1 > 2, 1, 2)
2

# Core.typeassert — Function

typeassert(x, type)

Throw a TypeError unless x isa type. The syntax x::type calls this function.

Examples

julia> typeassert(2.5, Int)
ERROR: TypeError: in typeassert, expected Int64, got a value of type Float64
Stacktrace:
[...]

# Core.typeof — Function

typeof(x)

Get the concrete type of x.

Properties of Types

Type relations

# Base.supertype — Function

supertype(T::DataType)

Return the supertype of DataType T.

Examples

julia> supertype(Int32)
Signed

# Core.Type — Type

Core.Type{T}

Core.Type is an abstract type which has all type objects as its instances. The only instance of the singleton type Core.Type{T} is the object T.

Examples

julia> isa(Type{Float64}, Type)
true

julia> isa(Float64, Type)
true

julia> isa(Real, Type{Float64})
false

julia> isa(Real, Type{Real})
true

# Core.DataType — Type

DataType <: Type{T}

DataType represents explicitly declared types that have names, explicitly declared supertypes, and, optionally, parameters. Every concrete value in the system is an instance of some DataType.

Examples

julia> typeof(Real)
DataType

julia> typeof(Int)
DataType

julia> struct Point
           x::Int
           y
       end

julia> typeof(Point)
DataType

# Core.:<: — Function

<:(T1, T2)

Subtype operator: returns true if and only if all values of type T1 are also of type T2.

Examples

julia> Float64 <: AbstractFloat
true

julia> Vector{Int} <: AbstractArray
true

julia> Matrix{Float64} <: Matrix{AbstractFloat}
false

# Base.:>: — Function

>:(T1, T2)

Supertype operator, equivalent to T2 <: T1.

# Base.typejoin — Function

typejoin(T, S, ...)

Return the closest common ancestor of types T and S, i.e. the narrowest type from which they both inherit. Recurses on additional varargs.

Examples

julia> typejoin(Int, Float64)
Real

julia> typejoin(Int, Float64, ComplexF32)
Number

# Base.typeintersect — Function

typeintersect(T::Type, S::Type)

Compute a type that contains the intersection of T and S. Usually this will be the smallest such type or one close to it.

# Base.promote_type — Function

promote_type(type1, type2, ...)

Promotion refers to converting values of mixed types to a single common type. promote_type represents the default promotion behavior in Julia when operators (usually mathematical) are given arguments of differing types. promote_type generally tries to return a type which can at least approximate most values of either input type without excessively widening. Some loss is tolerated; for example, promote_type(Int64, Float64) returns Float64 even though strictly, not all Int64 values can be represented exactly as Float64 values.

Examples

julia> promote_type(Int64, Float64)
Float64

julia> promote_type(Int32, Int64)
Int64

julia> promote_type(Float32, BigInt)
BigFloat

julia> promote_type(Int16, Float16)
Float16

julia> promote_type(Int64, Float16)
Float16

julia> promote_type(Int8, UInt16)
UInt16

!!! warning "Don’t overload this directly" To overload promotion for your own types you should overload promote_rule. promote_type calls promote_rule internally to determine the type. Overloading promote_type directly can cause ambiguity errors.

# Base.promote_rule — Function

promote_rule(type1, type2)

Specifies what type should be used by promote when given values of types type1 and type2. This function should not be called directly, but should have definitions added to it for new types as appropriate.

# Base.promote_typejoin — Function

promote_typejoin(T, S)

Compute a type that contains both T and S, which could be either a parent of both types, or a Union if appropriate. Falls back to typejoin.

See instead promote, promote_type.

Examples

julia> Base.promote_typejoin(Int, Float64)
Real

julia> Base.promote_type(Int, Float64)
Float64

# Base.isdispatchtuple — Function

isdispatchtuple(T)

Determine whether type T is a tuple "leaf type", meaning it could appear as a type signature in dispatch and has no subtypes (or supertypes) which could appear in a call.

Declared structure

# Base.ismutable — Function

ismutable(v) -> Bool

Return true if and only if value v is mutable. See Mutable Composite Types for a discussion of immutability. Note that this function works on values, so if you give it a DataType, it will tell you that a value of the type is mutable.

Memory layout

# Base.sizeof — Method

sizeof(T::DataType)
sizeof(obj)

Size, in bytes, of the canonical binary representation of the given DataType T, if any. Or the size, in bytes, of object obj if it is not a DataType.

Special values

# Base.typemin — Function

typemin(T)

The lowest value representable by the given (real) numeric DataType T.

Special Types

# Core.Any — Type

Any::DataType

Any is the union of all types. It has the defining property isa(x, Any) == true for any x. Any therefore describes the entire universe of possible values. For example Integer is a subset of Any that includes Int, Int8, and other integer types.

# Core.Union — Type

Union{Types...}

A type union is an abstract type which includes all instances of any of its argument types. The empty union Union{} is the bottom type of Julia.

Examples

julia> IntOrString = Union{Int,AbstractString}
Union{Int64, AbstractString}

julia> 1 isa IntOrString
true

julia> "Hello!" isa IntOrString
true

julia> 1.0 isa IntOrString
false

# Union{} — Keyword

Union{}

Union{}, the empty Union of types, is the type that has no values. That is, it has the defining property isa(x, Union{}) == false for any x. Base.Bottom is defined as its alias and the type of Union{} is Core.TypeofBottom.

Examples

julia> isa(nothing, Union{})
false

# Core.UnionAll — Type

UnionAll

A union of types over all values of a type parameter. UnionAll is used to describe parametric types where the values of some parameters are not known.

Examples

julia> typeof(Vector)
UnionAll

julia> typeof(Vector{Int})
DataType

# Core.Tuple — Type

Tuple{Types...}

Tuples are an abstraction of the arguments of a function — without the function itself. The salient aspects of a function’s arguments are their order and their types. Therefore a tuple type is similar to a parameterized immutable type where each parameter is the type of one field. Tuple types may have any number of parameters.

Tuple types are covariant in their parameters: Tuple{Int} is a subtype of Tuple{Any}. Therefore Tuple{Any} is considered an abstract type, and tuple types are only concrete if their parameters are. Tuples do not have field names; fields are only accessed by index.

See the manual section on Tuple Types.

See also Vararg, NTuple, tuple, NamedTuple.

# Core.NTuple — Type

NTuple{N, T}

A compact way of representing the type for a tuple of length N where all elements are of type T.

Examples

julia> isa((1, 2, 3, 4, 5, 6), NTuple{6, Int})
true

# Core.NamedTuple — Type

NamedTuple

NamedTuples are, as their name suggests, named Tuples. That is, they’re a tuple-like collection of values, where each entry has a unique name, represented as a Symbol. Like Tuples, NamedTuples are immutable; neither the names nor the values can be modified in place after construction.

Accessing the value associated with a name in a named tuple can be done using field access syntax, e.g. x.a, or using getindex, e.g. x[:a] or x[(:a, :b)]. A tuple of the names can be obtained using keys, and a tuple of the values can be obtained using values.

Iteration over NamedTuples produces the values without the names. (See example below.) To iterate over the name-value pairs, use the pairs function.

The @NamedTuple macro can be used for conveniently declaring NamedTuple types.

Examples

julia> x = (a=1, b=2)
(a = 1, b = 2)

julia> x.a
1

julia> x[:a]
1

julia> x[(:a,)]
(a = 1,)

julia> keys(x)
(:a, :b)

julia> values(x)
(1, 2)

julia> collect(x)
2-element Vector{Int64}:
 1
 2

julia> collect(pairs(x))
2-element Vector{Pair{Symbol, Int64}}:
 :a => 1
 :b => 2

In a similar fashion as to how one can define keyword arguments programmatically, a named tuple can be created by giving a pair name::Symbol => value or splatting an iterator yielding such pairs after a semicolon inside a tuple literal:

julia> (; :a => 1)
(a = 1,)

julia> keys = (:a, :b, :c); values = (1, 2, 3);

julia> (; zip(keys, values)...)
(a = 1, b = 2, c = 3)

As in keyword arguments, identifiers and dot expressions imply names:

julia> x = 0
0

julia> t = (; x)
(x = 0,)

julia> (; t.x)
(x = 0,)

Compatibility: Julia 1.5

Implicit names from identifiers and dot expressions are available as of Julia 1.5.

Compatibility: Julia 1.7

Use of getindex methods with multiple Symbols is available as of Julia 1.7.

# Base.@NamedTuple — Macro

@NamedTuple{key1::Type1, key2::Type2, ...}
@NamedTuple begin key1::Type1; key2::Type2; ...; end

This macro gives a more convenient syntax for declaring NamedTuple types. It returns a NamedTuple type with the given keys and types, equivalent to NamedTuple{(:key1, :key2, ...), Tuple{Type1,Type2,...}}. If the ::Type declaration is omitted, it is taken to be Any. The begin ... end form allows the declarations to be split across multiple lines (similar to a struct declaration), but is otherwise equivalent.

For example, the tuple (a=3.1, b="hello") has a type NamedTuple{(:a, :b),Tuple{Float64,String}}, which can also be declared via @NamedTuple as:

julia> @NamedTuple{a::Float64, b::String}
NamedTuple{(:a, :b), Tuple{Float64, String}}

julia> @NamedTuple begin
           a::Float64
           b::String
       end
NamedTuple{(:a, :b), Tuple{Float64, String}}

Compatibility: Julia 1.5

This macro is available as of Julia 1.5.

# Base.Val — Type

Val(c)

Return Val{c}(), which contains no run-time data. Types like this can be used to pass the information between functions through the value c, which must be an isbits value or a Symbol. The intent of this construct is to be able to dispatch on constants directly (at compile time) without having to test the value of the constant at run time.

Examples

julia> f(::Val{true}) = "Good"
f (generic function with 1 method)

julia> f(::Val{false}) = "Bad"
f (generic function with 2 methods)

julia> f(Val(true))
"Good"

# Core.Vararg — Constant

Vararg{T,N}

The last parameter of a tuple type Tuple can be the special value Vararg, which denotes any number of trailing elements. Vararg{T,N} corresponds to exactly N elements of type T. Finally Vararg{T} corresponds to zero or more elements of type T. Vararg tuple types are used to represent the arguments accepted by varargs methods (see the section on Varargs Functions in the manual.)

Generic Functions

# Core.Function — Type

Function

Abstract type of all functions.

Examples

julia> isa(+, Function)
true

julia> typeof(sin)
typeof(sin) (singleton type of function sin, subtype of Function)

julia> ans <: Function
true

# Base.hasmethod — Function

hasmethod(f, t::Type{<:Tuple}[, kwnames]; world=get_world_counter()) -> Bool

Determine whether the given generic function has a method matching the given Tuple of argument types with the upper bound of world age given by world.

If a tuple of keyword argument names kwnames is provided, this also checks whether the method of f matching t has the given keyword argument names. If the matching method accepts a variable number of keyword arguments, e.g. with kwargs..., any names given in kwnames are considered valid. Otherwise the provided names must be a subset of the method’s keyword arguments.

Syntax

# Core.eval — Function

Core.eval(m::Module, expr)

Evaluate an expression in the given module and return the result.

# Base.MainInclude.eval — Function

eval(expr)

Evaluate an expression in the global scope of the containing module. Every Module (except those defined with baremodule) has its own 1-argument definition of eval, which evaluates expressions in that module.

# Base.@eval — Macro

@eval [mod,] ex

Evaluate an expression with values interpolated into it using eval. If two arguments are provided, the first is the module to evaluate in.

# Base.evalfile — Function

evalfile(path::AbstractString, args::Vector{String}=String[])

Load the file into an anonymous module using include, evaluate all expressions, and return the value of the last expression. The optional args argument can be used to set the input arguments of the script (i.e. the global ARGS variable). Note that definitions (e.g. methods, globals) are evaluated in the anonymous module and do not affect the current module.

Example

julia> write("testfile.jl", """
           @show ARGS
           1 + 1
       """);

julia> x = evalfile("testfile.jl", ["ARG1", "ARG2"]);
ARGS = ["ARG1", "ARG2"]

julia> x
2

julia> rm("testfile.jl")

# Base.esc — Function

esc(e)

Only valid in the context of an Expr returned from a macro. Prevents the macro hygiene pass from turning embedded variables into gensym variables. See the Macros section of the Metaprogramming chapter of the manual for more details and examples.

# Base.@inbounds — Macro

@inbounds(blk)

Eliminates array bounds checking within expressions.

In the example below the in-range check for referencing element i of array A is skipped to improve performance.

function sum(A::AbstractArray)
    r = zero(eltype(A))
    for i in eachindex(A)
        @inbounds r += A[i]
    end
    return r
end

Using @inbounds may return incorrect results/crashes/corruption for out-of-bounds indices. The user is responsible for checking it manually. Only use @inbounds when it is certain from the information locally available that all accesses are in bounds. In particular, using 1:length(A) instead of eachindex(A) in a function like the one above is not safely inbounds because the first index of A may not be 1 for all user defined types that subtype AbstractArray.

# Base.@boundscheck — Macro

@boundscheck(blk)

Annotates the expression blk as a bounds checking block, allowing it to be elided by @inbounds.

The function in which @boundscheck is written must be inlined into its caller in order for @inbounds to have effect.

Examples

julia> @inline function g(A, i)
           @boundscheck checkbounds(A, i)
           return "accessing ($A)[$i]"
       end;

julia> f1() = return g(1:2, -1);

julia> f2() = @inbounds return g(1:2, -1);

julia> f1()
ERROR: BoundsError: attempt to access 2-element UnitRange{Int64} at index [-1]
Stacktrace:
 [1] throw_boundserror(::UnitRange{Int64}, ::Tuple{Int64}) at ./abstractarray.jl:455
 [2] checkbounds at ./abstractarray.jl:420 [inlined]
 [3] g at ./none:2 [inlined]
 [4] f1() at ./none:1
 [5] top-level scope

julia> f2()
"accessing (1:2)[-1]"

The @boundscheck annotation allows you, as a library writer, to opt-in to allowing other code to remove your bounds checks with @inbounds. As noted there, the caller must verify—using information they can access—that their accesses are valid before using @inbounds. For indexing into your AbstractArray subclasses, for example, this involves checking the indices against its axes. Therefore, @boundscheck annotations should only be added to a getindex or setindex! implementation after you are certain its behavior is correct.

# Base.@propagate_inbounds — Macro

@propagate_inbounds

Tells the compiler to inline a function while retaining the caller’s inbounds context.

# Base.@inline — Macro

@inline

Give a hint to the compiler that this function is worth inlining.

Small functions typically do not need the @inline annotation, as the compiler does it automatically. By using @inline on bigger functions, an extra nudge can be given to the compiler to inline it.

@inline can be applied immediately before the definition or in its function body.

# annotate long-form definition
@inline function longdef(x)
    ...
end

# annotate short-form definition
@inline shortdef(x) = ...

# annotate anonymous function that a `do` block creates
f() do
    @inline
    ...
end

Compatibility: Julia 1.8

The usage within a function body requires at least Julia 1.8.

@inline block

Give a hint to the compiler that calls within block are worth inlining.

# The compiler will try to inline `f`
@inline f(...)

# The compiler will try to inline `f`, `g` and `+`
@inline f(...) + g(...)

A callsite annotation always has the precedence over the annotation applied to the definition of the called function:

@noinline function explicit_noinline(args...)
    # body
end

let
    @inline explicit_noinline(args...) # will be inlined
end

When there are nested callsite annotations, the innermost annotation has the precedence:

```julia
@noinline let a0, b0 = ...
    a = @inline f(a0)  # the compiler will try to inline this call
    b = f(b0)          # the compiler will NOT try to inline this call
    return a, b
end
```

Although a callsite annotation will try to force inlining in regardless of the cost model, there are still chances it can’t succeed in it. Especially, recursive calls can not be inlined even if they are annotated as @inlined.

Compatibility: Julia 1.8

The callsite annotation requires at least Julia 1.8.

# Base.@noinline — Macro

@noinline

Give a hint to the compiler that it should not inline a function.

Small functions are typically inlined automatically. By using @noinline on small functions, auto-inlining can be prevented.

@noinline can be applied immediately before the definition or in its function body.

# annotate long-form definition
@noinline function longdef(x)
    ...
end

# annotate short-form definition
@noinline shortdef(x) = ...

# annotate anonymous function that a `do` block creates
f() do
    @noinline
    ...
end

Compatibility: Julia 1.8

The usage within a function body requires at least Julia 1.8.

@noinline block

Give a hint to the compiler that it should not inline the calls within block.

# The compiler will try to not inline `f`
@noinline f(...)

# The compiler will try to not inline `f`, `g` and `+`
@noinline f(...) + g(...)

A callsite annotation always has the precedence over the annotation applied to the definition of the called function:

@inline function explicit_inline(args...)
    # body
end

let
    @noinline explicit_inline(args...) # will not be inlined
end

When there are nested callsite annotations, the innermost annotation has the precedence:

```julia
@inline let a0, b0 = ...
    a = @noinline f(a0)  # the compiler will NOT try to inline this call
    b = f(b0)            # the compiler will try to inline this call
    return a, b
end
```

Compatibility: Julia 1.8

The callsite annotation requires at least Julia 1.8.

If the function is trivial (for example returning a constant) it might get inlined anyway.

# Base.@nospecialize — Macro

@nospecialize

Applied to a function argument name, hints to the compiler that the method implementation should not be specialized for different types of that argument, but instead use the declared type for that argument. It can be applied to an argument within a formal argument list, or in the function body. When applied to an argument, the macro must wrap the entire argument expression, e.g., @nospecialize(x::Real) or @nospecialize(i::Integer...) rather than wrapping just the argument name. When used in a function body, the macro must occur in statement position and before any code.

When used without arguments, it applies to all arguments of the parent scope. In local scope, this means all arguments of the containing function. In global (top-level) scope, this means all methods subsequently defined in the current module.

Specialization can reset back to the default by using @specialize.

function example_function(@nospecialize x)
    ...
end

function example_function(x, @nospecialize(y = 1))
    ...
end

function example_function(x, y, z)
    @nospecialize x y
    ...
end

@nospecialize
f(y) = [x for x in y]
@specialize

@nospecialize affects code generation but not inference: it limits the diversity of the resulting native code, but it does not impose any limitations (beyond the standard ones) on type-inference.

Example

julia> f(A::AbstractArray) = g(A)
f (generic function with 1 method)

julia> @noinline g(@nospecialize(A::AbstractArray)) = A[1]
g (generic function with 1 method)

julia> @code_typed f([1.0])
CodeInfo(
1 ─ %1 = invoke Main.g(_2::AbstractArray)::Float64
└──      return %1
) => Float64

Here, the @nospecialize annotation results in the equivalent of

f(A::AbstractArray) = invoke(g, Tuple{AbstractArray}, A)

ensuring that only one version of native code will be generated for g, one that is generic for any AbstractArray. However, the specific return type is still inferred for both g and f, and this is still used in optimizing the callers of f and g.

# Base.@specialize — Macro

@specialize

Reset the specialization hint for an argument back to the default. For details, see @nospecialize.

# Base.gensym — Function

gensym([tag])

Generates a symbol which will not conflict with other variable names (in the same module).

# Base.@gensym — Macro

@gensym

Generates a gensym symbol for a variable. For example, @gensym x y is transformed into x = gensym("x"); y = gensym("y").

# var"name" — Keyword

var

The syntax var"example" refers to a variable named Symbol("example"), even though example is not a valid Julia identifier name.

This can be useful for interoperability with programming languages which have different rules for the construction of valid identifiers. For example, to refer to the R variable draw.segments, you can use var"draw.segments" in your Julia code.

It is also used to show julia source code which has gone through macro hygiene or otherwise contains variable names which can’t be parsed normally.

Note that this syntax requires parser support so it is expanded directly by the parser rather than being implemented as a normal string macro @var_str.

Compatibility: Julia 1.3

This syntax requires at least Julia 1.3.

# Base.@goto — Macro

@goto name

@goto name unconditionally jumps to the statement at the location @label name.

@label and @goto cannot create jumps to different top-level statements. Attempts cause an error. To still use @goto, enclose the @label and @goto in a block.

# Base.@label — Macro

@label name

Labels a statement with the symbolic label name. The label marks the end-point of an unconditional jump with @goto name.

# Base.SimdLoop.@simd — Macro

@simd

Annotate a for loop to allow the compiler to take extra liberties to allow loop re-ordering

This feature is experimental and could change or disappear in future versions of Julia. Incorrect use of the @simd macro may cause unexpected results.

The object iterated over in a @simd for loop should be a one-dimensional range. By using @simd, you are asserting several properties of the loop:

It is safe to execute iterations in arbitrary or overlapping order, with special consideration for reduction variables.
Floating-point operations on reduction variables can be reordered, possibly causing different results than without @simd.

In many cases, Julia is able to automatically vectorize inner for loops without the use of @simd. Using @simd gives the compiler a little extra leeway to make it possible in more situations. In either case, your inner loop should have the following properties to allow vectorization:

The loop must be an innermost loop
The loop body must be straight-line code. Therefore, @inbounds is currently needed for all array accesses. The compiler can sometimes turn short &&, ||, and ?: expressions into straight-line code if it is safe to evaluate all operands unconditionally. Consider using the ifelse function instead of ?: in the loop if it is safe to do so.
Accesses must have a stride pattern and cannot be "gathers" (random-index reads) or "scatters" (random-index writes).
The stride should be unit stride.

The @simd does not assert by default that the loop is completely free of loop-carried memory dependencies, which is an assumption that can easily be violated in generic code. If you are writing non-generic code, you can use @simd ivdep for ... end to also assert that:

There exists no loop-carried memory dependencies
No iteration ever waits on a previous iteration to make forward progress.

# Base.@polly — Macro

@polly

Tells the compiler to apply the polyhedral optimizer Polly to a function.

# Base.@generated — Macro

@generated f

@generated is used to annotate a function which will be generated. In the body of the generated function, only types of arguments can be read (not the values). The function returns a quoted expression evaluated when the function is called. The @generated macro should not be used on functions mutating the global scope or depending on mutable elements.

See Metaprogramming for further details.

Examples

julia> @generated function bar(x)
           if x <: Integer
               return :(x ^ 2)
           else
               return :(x)
           end
       end
bar (generic function with 1 method)

julia> bar(4)
16

julia> bar("baz")
"baz"

# Base.@pure — Macro

@pure ex

@pure gives the compiler a hint for the definition of a pure function, helping for type inference.

This macro is intended for internal compiler use and may be subject to changes.

In Julia 1.8 and higher, it is favorable to use @assume_effects instead of @pure. This is because @assume_effects allows a finer grained control over Julia’s purity modeling and the effect system enables a wider range of optimizations.

# Base.@assume_effects — Macro

@assume_effects setting... ex

@assume_effects overrides the compiler’s effect modeling for the given method. ex must be a method definition or @ccall expression.

Compatibility: Julia 1.8

Using Base.@assume_effects requires Julia version 1.8.

Examples

julia> Base.@assume_effects :terminates_locally function pow(x)
           # this :terminates_locally allows `pow` to be constant-folded
           res = 1
           1 < x < 20 || error("bad pow")
           while x > 1
               res *= x
               x -= 1
           end
           return res
       end
pow (generic function with 1 method)

julia> code_typed() do
           pow(12)
       end
1-element Vector{Any}:
 CodeInfo(
1 ─     return 479001600
) => Int64

julia> Base.@assume_effects :total !:nothrow @ccall jl_type_intersection(Vector{Int}::Any, Vector{<:Integer}::Any)::Any
Vector{Int64} (alias for Array{Int64, 1})

Improper use of this macro causes undefined behavior (including crashes, incorrect answers, or other hard to track bugs). Use with care and only as a last resort if absolutely required. Even in such a case, you SHOULD take all possible steps to minimize the strength of the effect assertion (e.g., do not use :total if :nothrow would have been sufficient).

In general, each setting value makes an assertion about the behavior of the function, without requiring the compiler to prove that this behavior is indeed true. These assertions are made for all world ages. It is thus advisable to limit the use of generic functions that may later be extended to invalidate the assumption (which would cause undefined behavior).

The following settings are supported.

:consistent
:effect_free
:nothrow
:terminates_globally
:terminates_locally
:notaskstate
:inaccessiblememonly
:foldable
:total

Extended help

:consistent

The :consistent setting asserts that for egal (===) inputs:

The manner of termination (return value, exception, non-termination) will always be the same.
If the method returns, the results will always be egal.

This in particular implies that the method must not return a freshly allocated mutable object. Multiple allocations of mutable objects (even with identical contents) are not egal.

The :consistent-cy assertion is made world-age wise. More formally, write for the evaluation of in world-age , then we require:

∀ i, x, y: x ≡ y → fᵢ(x) ≡ fᵢ(y)

However, for two world ages , s.t. , we may have .

A further implication is that :consistent functions may not make their return value dependent on the state of the heap or any other global state that is not constant for a given world age.

The :consistent-cy includes all legal rewrites performed by the optimizer. For example, floating-point fastmath operations are not considered :consistent, because the optimizer may rewrite them causing the output to not be :consistent, even for the same world age (e.g. because one ran in the interpreter, while the other was optimized).

If :consistent functions terminate by throwing an exception, that exception itself is not required to meet the egality requirement specified above.

:effect_free

The :effect_free setting asserts that the method is free of externally semantically visible side effects. The following is an incomplete list of externally semantically visible side effects:

Changing the value of a global variable.
Mutating the heap (e.g. an array or mutable value), except as noted below
Changing the method table (e.g. through calls to eval)
File/Network/etc. I/O
Task switching

However, the following are explicitly not semantically visible, even if they may be observable:

Memory allocations (both mutable and immutable)
Elapsed time
Garbage collection
Heap mutations of objects whose lifetime does not exceed the method (i.e. were allocated in the method and do not escape).
The returned value (which is externally visible, but not a side effect)

The rule of thumb here is that an externally visible side effect is anything that would affect the execution of the remainder of the program if the function were not executed.

The :effect_free assertion is made both for the method itself and any code that is executed by the method. Keep in mind that the assertion must be valid for all world ages and limit use of this assertion accordingly.

:nothrow

The :nothrow settings asserts that this method does not terminate abnormally (i.e. will either always return a value or never return).

It is permissible for :nothrow annotated methods to make use of exception handling internally as long as the exception is not rethrown out of the method itself.

MethodErrors and similar exceptions count as abnormal termination.

:terminates_globally

The :terminates_globally settings asserts that this method will eventually terminate (either normally or abnormally), i.e. does not loop indefinitely.

This :terminates_globally assertion covers any other methods called by the annotated method.

The compiler will consider this a strong indication that the method will terminate relatively quickly and may (if otherwise legal), call this method at compile time. I.e. it is a bad idea to annotate this setting on a method that technically, but not practically, terminates.

:terminates_locally

The :terminates_locally setting is like :terminates_globally, except that it only applies to syntactic control flow within the annotated method. It is thus a much weaker (and thus safer) assertion that allows for the possibility of non-termination if the method calls some other method that does not terminate.

:terminates_globally implies :terminates_locally.

:notaskstate

The :notaskstate setting asserts that the method does not use or modify the local task state (task local storage, RNG state, etc.) and may thus be safely moved between tasks without observable results.

The implementation of exception handling makes use of state stored in the task object. However, this state is currently not considered to be within the scope of :notaskstate and is tracked separately using the :nothrow effect.

The :notaskstate assertion concerns the state of the currently running task. If a reference to a Task object is obtained by some other means that does not consider which task is currently running, the :notaskstate effect need not be tainted. This is true, even if said task object happens to be === to the currently running task.

Access to task state usually also results in the tainting of other effects, such as :effect_free (if task state is modified) or :consistent (if task state is used in the computation of the result). In particular, code that is not :notaskstate, but is :effect_free and :consistent may still be dead-code-eliminated and thus promoted to :total.

:inaccessiblememonly

The :inaccessiblememonly setting asserts that the method does not access or modify externally accessible mutable memory. This means the method can access or modify mutable memory for newly allocated objects that is not accessible by other methods or top-level execution before return from the method, but it can not access or modify any mutable global state or mutable memory pointed to by its arguments.

Below is an incomplete list of examples that invalidate this assumption:

a global reference or getglobal call to access a mutable global variable
a global assignment or setglobal! call to perform assignment to a non-constant global variable
setfield! call that changes a field of a global mutable variable

This :inaccessiblememonly assertion covers any other methods called by the annotated method.

:foldable

This setting is a convenient shortcut for the set of effects that the compiler requires to be guaranteed to constant fold a call at compile time. It is currently equivalent to the following settings:

:consistent
:effect_free
:terminates_globally

This list in particular does not include :nothrow. The compiler will still attempt constant propagation and note any thrown error at compile time. Note however, that by the :consistent-cy requirements, any such annotated call must consistently throw given the same argument values.

An explicit @inbounds annotation inside the function will also disable constant folding and not be overriden by :foldable.

:total

This setting is the maximum possible set of effects. It currently implies the following other settings:

:consistent
:effect_free
:nothrow
:terminates_globally
:notaskstate
:inaccessiblememonly

:total is a very strong assertion and will likely gain additional semantics in future versions of Julia (e.g. if additional effects are added and included in the definition of :total). As a result, it should be used with care. Whenever possible, prefer to use the minimum possible set of specific effect assertions required for a particular application. In cases where a large number of effect overrides apply to a set of functions, a custom macro is recommended over the use of :total.

Negated effects

Effect names may be prefixed by ! to indicate that the effect should be removed from an earlier meta effect. For example, :total !:nothrow indicates that while the call is generally total, it may however throw.

Comparison to @pure

@assume_effects :foldable is similar to @pure with the primary distinction that the :consistent-cy requirement applies world-age wise rather than globally as described above. However, in particular, a method annotated @pure should always be at least :foldable. Another advantage is that effects introduced by @assume_effects are propagated to callers interprocedurally while a purity defined by @pure is not.

# Base.@deprecate — Macro

@deprecate old new [export_old=true]

Deprecate method old and specify the replacement call new, defining a new method old with the specified signature in the process.

To prevent old from being exported, set export_old to false.

Compatibility: Julia 1.5

As of Julia 1.5, functions defined by @deprecate do not print warning when julia is run without the --depwarn=yes flag set, as the default value of --depwarn option is no. The warnings are printed from tests run by Pkg.test().

Examples

julia> @deprecate old(x) new(x)
old (generic function with 1 method)

julia> @deprecate old(x) new(x) false
old (generic function with 1 method)

Calls to @deprecate without explicit type-annotations will define deprecated methods accepting any number of positional and keyword arguments of type Any.

Compatibility: Julia 1.9

Keyword arguments are forwarded when there is no explicit type annotation as of Julia 1.9. For older versions, you can manually forward positional and keyword arguments by doing @deprecate old(args...; kwargs...) new(args...; kwargs...).

To restrict deprecation to a specific signature, annotate the arguments of old. For example,

julia> new(x::Int) = x;

julia> new(x::Float64) = 2x;

julia> @deprecate old(x::Int) new(x);

julia> methods(old)
# 1 method for generic function "old" from Main:
 [1] old(x::Int64)
     @ deprecated.jl:94

will define and deprecate a method old(x::Int) that mirrors new(x::Int) but will not define nor deprecate the method old(x::Float64).

Missing Values

# Base.Missing — Type

Missing

A type with no fields whose singleton instance missing is used to represent missing values.

# Base.missing — Constant

missing

The singleton instance of type Missing representing a missing value.

See also: NaN, skipmissing, nonmissingtype.

# Base.coalesce — Function

coalesce(x...)

Return the first value in the arguments which is not equal to missing, if any. Otherwise return missing.

Examples

julia> coalesce(missing, 1)
1

julia> coalesce(1, missing)
1

julia> coalesce(nothing, 1)  # returns `nothing`

julia> coalesce(missing, missing)
missing

# Base.@coalesce — Macro

@coalesce(x...)

Short-circuiting version of coalesce.

Examples

julia> f(x) = (println("f($x)"); missing);

julia> a = 1;

julia> a = @coalesce a f(2) f(3) error("`a` is still missing")
1

julia> b = missing;

julia> b = @coalesce b f(2) f(3) error("`b` is still missing")
f(2)
f(3)
ERROR: `b` is still missing
[...]

Compatibility: Julia 1.7

This macro is available as of Julia 1.7.

# Base.ismissing — Function

ismissing(x)

Indicate whether x is missing.

See also: skipmissing, isnothing, isnan.

# Base.skipmissing — Function

skipmissing(itr)

Return an iterator over the elements in itr skipping missing values. The returned object can be indexed using indices of itr if the latter is indexable. Indices corresponding to missing values are not valid: they are skipped by keys and eachindex, and a MissingException is thrown when trying to use them.

Use collect to obtain an Array containing the non-missing values in itr. Note that even if itr is a multidimensional array, the result will always be a Vector since it is not possible to remove missings while preserving dimensions of the input.

See also coalesce, ismissing, something.

Examples

julia> x = skipmissing([1, missing, 2])
skipmissing(Union{Missing, Int64}[1, missing, 2])

julia> sum(x)
3

julia> x[1]
1

julia> x[2]
ERROR: MissingException: the value at index (2,) is missing
[...]

julia> argmax(x)
3

julia> collect(keys(x))
2-element Vector{Int64}:
 1
 3

julia> collect(skipmissing([1, missing, 2]))
2-element Vector{Int64}:
 1
 2

julia> collect(skipmissing([1 missing; 2 missing]))
2-element Vector{Int64}:
 1
 2

# Base.nonmissingtype — Function

nonmissingtype(T::Type)

If T is a union of types containing Missing, return a new type with Missing removed.

Examples

julia> nonmissingtype(Union{Int64,Missing})
Int64

julia> nonmissingtype(Any)
Any

Compatibility: Julia 1.3

This function is exported as of Julia 1.3.

System

# Base.run — Function

run(command, args...; wait::Bool = true)

Run a command object, constructed with backticks (see the Running External Programs section in the manual). Throws an error if anything goes wrong, including the process exiting with a non-zero status (when wait is true).

The args... allow you to pass through file descriptors to the command, and are ordered like regular unix file descriptors (eg stdin, stdout, stderr, FD(3), FD(4)...).

If wait is false, the process runs asynchronously. You can later wait for it and check its exit status by calling success on the returned process object.

When wait is false, the process' I/O streams are directed to devnull. When wait is true, I/O streams are shared with the parent process. Use pipeline to control I/O redirection.

# Base.devnull — Constant

devnull

Used in a stream redirect to discard all data written to it. Essentially equivalent to /dev/null on Unix or NUL on Windows. Usage:

run(pipeline(`cat test.txt`, devnull))

# Base.success — Function

success(command)

Run a command object, constructed with backticks (see the Running External Programs section in the manual), and tell whether it was successful (exited with a code of 0). An exception is raised if the process cannot be started.

# Base.process_running — Function

process_running(p::Process)

Determine whether a process is currently running.

# Base.process_exited — Function

process_exited(p::Process)

Determine whether a process has exited.

# Base.kill — Method

kill(p::Process, signum=Base.SIGTERM)

Send a signal to a process. The default is to terminate the process. Returns successfully if the process has already exited, but throws an error if killing the process failed for other reasons (e.g. insufficient permissions).

# Base.Sys.set_process_title — Function

Sys.set_process_title(title::AbstractString)

Set the process title. No-op on some operating systems.

# Base.Sys.get_process_title — Function

Sys.get_process_title()

Get the process title. On some systems, will always return an empty string.

# Base.ignorestatus — Function

ignorestatus(command)

Mark a command object so that running it will not throw an error if the result code is non-zero.

# Base.detach — Function

detach(command)

Mark a command object so that it will be run in a new process group, allowing it to outlive the julia process, and not have Ctrl-C interrupts passed to it.

# Base.Cmd — Type

Cmd(cmd::Cmd; ignorestatus, detach, windows_verbatim, windows_hide, env, dir)

Construct a new Cmd object, representing an external program and arguments, from cmd, while changing the settings of the optional keyword arguments:

ignorestatus::Bool: If true (defaults to false), then the Cmd will not throw an error if the return code is nonzero.
detach::Bool: If true (defaults to false), then the Cmd will be run in a new process group, allowing it to outlive the julia process and not have Ctrl-C passed to it.
windows_verbatim::Bool: If true (defaults to false), then on Windows the Cmd will send a command-line string to the process with no quoting or escaping of arguments, even arguments containing spaces. (On Windows, arguments are sent to a program as a single "command-line" string, and programs are responsible for parsing it into arguments. By default, empty arguments and arguments with spaces or tabs are quoted with double quotes " in the command line, and \ or " are preceded by backslashes. windows_verbatim=true is useful for launching programs that parse their command line in nonstandard ways.) Has no effect on non-Windows systems.
windows_hide::Bool: If true (defaults to false), then on Windows no new console window is displayed when the Cmd is executed. This has no effect if a console is already open or on non-Windows systems.
env: Set environment variables to use when running the Cmd. env is either a dictionary mapping strings to strings, an array of strings of the form "var=val", an array or tuple of "var"=>val pairs. In order to modify (rather than replace) the existing environment, initialize env with copy(ENV) and then set env["var"]=val as desired. To add to an environment block within a Cmd object without replacing all elements, use addenv() which will return a Cmd object with the updated environment.
dir::AbstractString: Specify a working directory for the command (instead of the current directory).

For any keywords that are not specified, the current settings from cmd are used. Normally, to create a Cmd object in the first place, one uses backticks, e.g.

Cmd(`echo "Hello world"`, ignorestatus=true, detach=false)

# Base.setenv — Function

setenv(command::Cmd, env; dir)

Set environment variables to use when running the given command. env is either a dictionary mapping strings to strings, an array of strings of the form "var=val", or zero or more "var"=>val pair arguments. In order to modify (rather than replace) the existing environment, create env through copy(ENV) and then setting env["var"]=val as desired, or use addenv.

The dir keyword argument can be used to specify a working directory for the command. dir defaults to the currently set dir for command (which is the current working directory if not specified already).

Versioning

# Base.VersionNumber — Type

VersionNumber

Version number type which follows the specifications of semantic versioning (semver), composed of major, minor and patch numeric values, followed by pre-release and build alpha-numeric annotations.

VersionNumber objects can be compared with all of the standard comparison operators (==, <, <=, etc.), with the result following semver rules.

See also @v_str to efficiently construct VersionNumber objects from semver-format literal strings, VERSION for the VersionNumber of Julia itself, and Version Number Literals in the manual.

Examples

julia> a = VersionNumber(1, 2, 3)
v"1.2.3"

julia> a >= v"1.2"
true

julia> b = VersionNumber("2.0.1-rc1")
v"2.0.1-rc1"

julia> b >= v"2.0.1"
false

# Base.@v_str — Macro

@v_str

String macro used to parse a string to a VersionNumber.

Examples

julia> v"1.2.3"
v"1.2.3"

julia> v"2.0.1-rc1"
v"2.0.1-rc1"

Errors

# Base.error — Function

error(message::AbstractString)

Raise an ErrorException with the given message.

error(msg...)

Raise an ErrorException with the given message.

# Core.throw — Function

throw(e)

Throw an object as an exception.

Events

# Base.Timer — Method

Timer(callback::Function, delay; interval = 0)

Create a timer that runs the function callback at each timer expiration.

Waiting tasks are woken and the function callback is called after an initial delay of delay seconds, and then repeating with the given interval in seconds. If interval is equal to 0, the callback is only run once. The function callback is called with a single argument, the timer itself. Stop a timer by calling close. The cb may still be run one final time, if the timer has already expired.

Examples

Here the first number is printed after a delay of two seconds, then the following numbers are printed quickly.

julia> begin
           i = 0
           cb(timer) = (global i += 1; println(i))
           t = Timer(cb, 2, interval=0.2)
           wait(t)
           sleep(0.5)
           close(t)
       end
1
2
3

# Base.Timer — Type

Timer(delay; interval = 0)

Create a timer that wakes up tasks waiting for it (by calling wait on the timer object).

Waiting tasks are woken after an initial delay of at least delay seconds, and then repeating after at least interval seconds again elapse. If interval is equal to 0, the timer is only triggered once. When the timer is closed (by close) waiting tasks are woken with an error. Use isopen to check whether a timer is still active.

interval is subject to accumulating time skew. If you need precise events at a particular absolute time, create a new timer at each expiration with the difference to the next time computed.

A Timer requires yield points to update its state. For instance, isopen(t::Timer) cannot be used to timeout a non-yielding while loop.

# Base.AsyncCondition — Type

AsyncCondition()

Create a async condition that wakes up tasks waiting for it (by calling wait on the object) when notified from C by a call to uv_async_send. Waiting tasks are woken with an error when the object is closed (by close). Use isopen to check whether it is still active.

This provides an implicit acquire & release memory ordering between the sending and waiting threads.

# Base.AsyncCondition — Method

AsyncCondition(callback::Function)

Create a async condition that calls the given callback function. The callback is passed one argument, the async condition object itself.

Reflection

# Base.nameof — Method

nameof(m::Module) -> Symbol

Get the name of a Module as a Symbol.

Examples

julia> nameof(Base.Broadcast)
:Broadcast

# Base.parentmodule — Function

parentmodule(m::Module) -> Module

Get a module’s enclosing Module. Main is its own parent.

See also: names, nameof, fullname, @__MODULE__.

Examples

julia> parentmodule(Main)
Main

julia> parentmodule(Base.Broadcast)
Base

parentmodule(t::DataType) -> Module

Determine the module containing the definition of a (potentially UnionAll-wrapped) DataType.

Examples

julia> module Foo
           struct Int end
       end
Foo

julia> parentmodule(Int)
Core

julia> parentmodule(Foo.Int)
Foo

parentmodule(f::Function) -> Module

Determine the module containing the (first) definition of a generic function.

parentmodule(f::Function, types) -> Module

Determine the module containing a given definition of a generic function.

# Base.pathof — Method

pathof(m::Module)

Return the path of the m.jl file that was used to import module m, or nothing if m was not imported from a package.

Use dirname to get the directory part and basename to get the file name part of the path.

# Base.pkgdir — Method

pkgdir(m::Module[, paths::String...])

Return the root directory of the package that imported module m, or nothing if m was not imported from a package. Optionally further path component strings can be provided to construct a path within the package root.

To get the root directory of the package that imported the current module the form pkgdir(@__MODULE__) can be used.

julia> pkgdir(Foo)
"/path/to/Foo.jl"

julia> pkgdir(Foo, "src", "file.jl")
"/path/to/Foo.jl/src/file.jl"

Compatibility: Julia 1.7

The optional argument paths requires at least Julia 1.7.

# Base.pkgversion — Method

pkgversion(m::Module)

Return the version of the package that imported module m, or nothing if m was not imported from a package, or imported from a package without a version field set.

The version is read from the package’s Project.toml during package load.

To get the version of the package that imported the current module the form pkgversion(@__MODULE__) can be used.

Compatibility: Julia 1.9

This function was introduced in Julia 1.9.

# Base.moduleroot — Function

moduleroot(m::Module) -> Module

Find the root module of a given module. This is the first module in the chain of parent modules of m which is either a registered root module or which is its own parent module.

# __module__ — Keyword

__module__

The argument __module__ is only visible inside the macro, and it provides information (in the form of a Module object) about the expansion context of the macro invocation. See the manual section on Macro invocation for more information.

# __source__ — Keyword

__source__

The argument __source__ is only visible inside the macro, and it provides information (in the form of a LineNumberNode object) about the parser location of the @ sign from the macro invocation. See the manual section on Macro invocation for more information.

# Base.@__MODULE__ — Macro

@__MODULE__ -> Module

Get the Module of the toplevel eval, which is the Module code is currently being read from.

# Base.@__FILE__ — Macro

@__FILE__ -> AbstractString

Expand to a string with the path to the file containing the macrocall, or an empty string if evaluated by julia -e <expr>. Return nothing if the macro was missing parser source information. Alternatively see PROGRAM_FILE.

# Base.@__DIR__ — Macro

@__DIR__ -> AbstractString

Expand to a string with the absolute path to the directory of the file containing the macrocall. Return the current working directory if run from a REPL or if evaluated by julia -e <expr>.

# Base.@__LINE__ — Macro

@__LINE__ -> Int

Expand to the line number of the location of the macrocall. Return 0 if the line number could not be determined.

# Base.fullname — Function

fullname(m::Module)

Get the fully-qualified name of a module as a tuple of symbols. For example,

Examples

julia> fullname(Base.Iterators)
(:Base, :Iterators)

julia> fullname(Main)
(:Main,)

# Base.names — Function

names(x::Module; all::Bool = false, imported::Bool = false)

Get an array of the names exported by a Module, excluding deprecated names. If all is true, then the list also includes non-exported names defined in the module, deprecated names, and compiler-generated names. If imported is true, then names explicitly imported from other modules are also included.

As a special case, all names defined in Main are considered "exported", since it is not idiomatic to explicitly export names from Main.

Code loading

# Base.identify_package — Function

Base.identify_package(name::String)::Union{PkgId, Nothing}
Base.identify_package(where::Union{Module,PkgId}, name::String)::Union{PkgId, Nothing}

Identify the package by its name from the current environment stack, returning its PkgId, or nothing if it cannot be found.

If only the name argument is provided, it searches each environment in the stack and its named direct dependencies.

There where argument provides the context from where to search for the package: in this case it first checks if the name matches the context itself, otherwise it searches all recursive dependencies (from the resolved manifest of each environment) until it locates the context where, and from there identifies the dependency with with the corresponding name.

julia> Base.identify_package("Pkg") # Pkg is a dependency of the default environment
Pkg [44cfe95a-1eb2-52ea-b672-e2afdf69b78f]

julia> using LinearAlgebra

julia> Base.identify_package(LinearAlgebra, "Pkg") # Pkg is not a dependency of LinearAlgebra

# Base.locate_package — Function

Base.locate_package(pkg::PkgId)::Union{String, Nothing}

The path to the entry-point file for the package corresponding to the identifier pkg, or nothing if not found. See also identify_package.

julia> pkg = Base.identify_package("Pkg")
Pkg [44cfe95a-1eb2-52ea-b672-e2afdf69b78f]

julia> Base.locate_package(pkg)
"/path/to/julia/stdlib/v1.9/Pkg/src/Pkg.jl"

# Base.require — Function

require(into::Module, module::Symbol)

This function is part of the implementation of using / import, if a module is not already defined in Main. It can also be called directly to force reloading a module, regardless of whether it has been loaded before (for example, when interactively developing libraries).

Loads a source file, in the context of the Main module, on every active node, searching standard locations for files. require is considered a top-level operation, so it sets the current include path but does not use it to search for files (see help for include). This function is typically used to load library code, and is implicitly called by using to load packages.

When searching for files, require first looks for package code in the global array LOAD_PATH. require is case-sensitive on all platforms, including those with case-insensitive filesystems like macOS and Windows.

For more details regarding code loading, see the manual sections on modules and parallel computing.

# Base.compilecache — Function

Base.compilecache(module::PkgId)

Creates a precompiled cache file for a module and all of its dependencies. This can be used to reduce package load times. Cache files are stored in DEPOT_PATH[1]/compiled. See Module initialization and precompilation for important notes.

# Base.get_extension — Function

get_extension(parent::Module, extension::Symbol)

Return the module for extension of parent or return nothing if the extension is not loaded.

Internals

# Base.GC.gc — Function

GC.gc([full=true])

Perform garbage collection. The argument full determines the kind of collection: A full collection (default) sweeps all objects, which makes the next GC scan much slower, while an incremental collection may only sweep so-called young objects.

Excessive use will likely lead to poor performance.

# Base.GC.enable — Function

GC.enable(on::Bool)

Control whether garbage collection is enabled using a boolean argument (true for enabled, false for disabled). Return previous GC state.

Disabling garbage collection should be used only with caution, as it can cause memory use to grow without bound.

# Base.GC.@preserve — Macro

GC.@preserve x1 x2 ... xn expr

Mark the objects x1, x2, ... as being in use during the evaluation of the expression expr. This is only required in unsafe code where expr implicitly uses memory or other resources owned by one of the xs.

Implicit use of x covers any indirect use of resources logically owned by x which the compiler cannot see. Some examples:

Accessing memory of an object directly via a Ptr
Passing a pointer to x to ccall
Using resources of x which would be cleaned up in the finalizer.

@preserve should generally not have any performance impact in typical use cases where it briefly extends object lifetime. In implementation, @preserve has effects such as protecting dynamically allocated objects from garbage collection.

Examples

When loading from a pointer with unsafe_load, the underlying object is implicitly used, for example x is implicitly used by unsafe_load(p) in the following:

julia> let
           x = Ref{Int}(101)
           p = Base.unsafe_convert(Ptr{Int}, x)
           GC.@preserve x unsafe_load(p)
       end
101

When passing pointers to ccall, the pointed-to object is implicitly used and should be preserved. (Note however that you should normally just pass x directly to ccall which counts as an explicit use.)

julia> let
           x = "Hello"
           p = pointer(x)
           Int(GC.@preserve x @ccall strlen(p::Cstring)::Csize_t)
           # Preferred alternative
           Int(@ccall strlen(x::Cstring)::Csize_t)
       end
5

# Base.GC.safepoint — Function

GC.safepoint()

Inserts a point in the program where garbage collection may run. This can be useful in rare cases in multi-threaded programs where some threads are allocating memory (and hence may need to run GC) but other threads are doing only simple operations (no allocation, task switches, or I/O). Calling this function periodically in non-allocating threads allows garbage collection to run.

Compatibility: Julia 1.4

This function is available as of Julia 1.4.

# Base.GC.enable_logging — Function

GC.enable_logging(on::Bool)

When turned on, print statistics about each GC to stderr.

# Base.Meta.lower — Function

lower(m, x)

Takes the expression x and returns an equivalent expression in lowered form for executing in module m. See also code_lowered.

# Base.Meta.@lower — Macro

@lower [m] x

Return lowered form of the expression x in module m. By default m is the module in which the macro is called. See also lower.

# Base.Meta.parse — Method

parse(str, start; greedy=true, raise=true, depwarn=true)

Parse the expression string and return an expression (which could later be passed to eval for execution). start is the code unit index into str of the first character to start parsing at (as with all string indexing, these are not character indices). If greedy is true (default), parse will try to consume as much input as it can; otherwise, it will stop as soon as it has parsed a valid expression. Incomplete but otherwise syntactically valid expressions will return Expr(:incomplete, "(error message)"). If raise is true (default), syntax errors other than incomplete expressions will raise an error. If raise is false, parse will return an expression that will raise an error upon evaluation. If depwarn is false, deprecation warnings will be suppressed.

julia> Meta.parse("(α, β) = 3, 5", 1) # start of string
(:((α, β) = (3, 5)), 16)

julia> Meta.parse("(α, β) = 3, 5", 1, greedy=false)
(:((α, β)), 9)

julia> Meta.parse("(α, β) = 3, 5", 16) # end of string
(nothing, 16)

julia> Meta.parse("(α, β) = 3, 5", 11) # index of 3
(:((3, 5)), 16)

julia> Meta.parse("(α, β) = 3, 5", 11, greedy=false)
(3, 13)

# Base.Meta.parse — Method

parse(str; raise=true, depwarn=true)

Parse the expression string greedily, returning a single expression. An error is thrown if there are additional characters after the first expression. If raise is true (default), syntax errors will raise an error; otherwise, parse will return an expression that will raise an error upon evaluation. If depwarn is false, deprecation warnings will be suppressed.

julia> Meta.parse("x = 3")
:(x = 3)

julia> Meta.parse("x = ")
:($(Expr(:incomplete, "incomplete: premature end of input")))

julia> Meta.parse("1.0.2")
ERROR: Base.Meta.ParseError("invalid numeric constant \"1.0.\"")
Stacktrace:
[...]

julia> Meta.parse("1.0.2"; raise = false)
:($(Expr(:error, "invalid numeric constant \"1.0.\"")))

# Base.Meta.ParseError — Type

ParseError(msg)

The expression passed to the parse function could not be interpreted as a valid Julia expression.

# Core.QuoteNode — Type

QuoteNode

A quoted piece of code, that does not support interpolation. See the manual section about QuoteNodes for details.

# Base.macroexpand — Function

macroexpand(m::Module, x; recursive=true)

Take the expression x and return an equivalent expression with all macros removed (expanded) for executing in module m. The recursive keyword controls whether deeper levels of nested macros are also expanded. This is demonstrated in the example below:

julia> module M
           macro m1()
               42
           end
           macro m2()
               :(@m1())
           end
       end
M

julia> macroexpand(M, :(@m2()), recursive=true)
42

julia> macroexpand(M, :(@m2()), recursive=false)
:(#= REPL[16]:6 =# M.@m1)

# Base.@macroexpand — Macro

@macroexpand

Return equivalent expression with all macros removed (expanded).

There are differences between @macroexpand and macroexpand.

While macroexpand takes a keyword argument recursive, @macroexpand is always recursive. For a non recursive macro version, see @macroexpand1.
While macroexpand has an explicit module argument, @macroexpand always expands with respect to the module in which it is called.

This is best seen in the following example:

julia> module M
           macro m()
               1
           end
           function f()
               (@macroexpand(@m),
                macroexpand(M, :(@m)),
                macroexpand(Main, :(@m))
               )
           end
       end
M

julia> macro m()
           2
       end
@m (macro with 1 method)

julia> M.f()
(1, 1, 2)

With @macroexpand the expression expands where @macroexpand appears in the code (module M in the example). With macroexpand the expression expands in the module given as the first argument.

# Base.@macroexpand1 — Macro

@macroexpand1

Non recursive version of @macroexpand.

# Base.code_lowered — Function

code_lowered(f, types; generated=true, debuginfo=:default)

Return an array of the lowered forms (IR) for the methods matching the given generic function and type signature.

If generated is false, the returned CodeInfo instances will correspond to fallback implementations. An error is thrown if no fallback implementation exists. If generated is true, these CodeInfo instances will correspond to the method bodies yielded by expanding the generators.

The keyword debuginfo controls the amount of code metadata present in the output.

Note that an error will be thrown if types are not leaf types when generated is true and any of the corresponding methods are an @generated method.

# Base.code_typed — Function

code_typed(f, types; kw...)

Returns an array of type-inferred lowered form (IR) for the methods matching the given generic function and type signature.

Keyword Arguments

optimize=true: controls whether additional optimizations, such as inlining, are also applied.
debuginfo=:default: controls the amount of code metadata present in the output,

possible options are :source or :none.

Internal Keyword Arguments

This section should be considered internal, and is only for who understands Julia compiler internals.

world=Base.get_world_counter(): optional, controls the world age to use when looking up methods,

use current world age if not specified.

interp=Core.Compiler.NativeInterpreter(world): optional, controls the interpreter to use,

use the native interpreter Julia uses if not specified.

Example

One can put the argument types in a tuple to get the corresponding code_typed.

julia> code_typed(+, (Float64, Float64))
1-element Vector{Any}:
 CodeInfo(
1 ─ %1 = Base.add_float(x, y)::Float64
└──      return %1
) => Float64

# Base.precompile — Function

precompile(f, argtypes::Tuple{Vararg{Any}})

Compile the given function f for the argument tuple (of types) argtypes, but do not execute it.

precompile(f, argtypes::Tuple{Vararg{Any}}, m::Method)

Precompile a specific method for the given argument types. This may be used to precompile a different method than the one that would ordinarily be chosen by dispatch, thus mimicking invoke.

# Base.jit_total_bytes — Function

Base.jit_total_bytes()

Return the total amount (in bytes) allocated by the just-in-time compiler for e.g. native code and data.