# Internal & Design

JLD2.CustomSerializationType
CustomSerialization{T,S}

On-disk representation for data that is written as if it were of Julia type T, but is read as type S.

source
JLD2.GroupMethod
Group(f::JLDFile, name::AbstractString)

Construct an empty group named name at the top level of JLDFile f.

source
JLD2.GroupMethod
Group(g::Group, name::AbstractString)

Construct a group named name as a child of group g.

source
JLD2.IndirectPointerType
IndirectPointer

When writing data, we may need to enlarge the memory mapping, which would invalidate any memory addresses arising from the old mmap pointer. IndirectPointer holds a pointer to the startptr field of an MmapIO, and the offset relative to that pointer. It defers computing a memory address until converted to a Ptr{T}, so the memory mapping can be enlarged and addresses will remain valid.

source
JLD2.InlineUnionElType
InlineUnionEl{T1,T2}(mask::UInt8, t1::T1, t2::T2)

Custom serialization struct for two member isbits union fields e.g. in other structs or arrays. To indicate that t1 is relevant the mask takes the value UInt8(0) and for t2 UInt8(255)

source
JLD2.JLDWriteSessionType
JLDWriteSession{T}

A JLDWriteSession keeps track of references to serialized objects. If T is a Dict, h5offset maps an object ID (returned by calling objectid) to th RelOffset of the written dataset. If it is Union{}, then references are not tracked, and objects referenced multiple times are written multiple times.

source
JLD2.RelOffsetType
RelOffset

Represents an HDF5 relative offset. This differs from a file offset (used elsewhere) in that it is relative to the superblock base address. In practice, this means that FILE_HEADER_LENGTHhas been subtracted. fileoffset and h5offset convert between RelOffsets and file offsets.

source
JLD2.TypeMappingExceptionType

Constructs a ReadRepresentation for a given type. This is the generic method for all types not specially handled below.

If hard_failure is true, then throw a TypeMappingException instead of attempting reconstruction. This helps in cases where we can't know if reconstructed parametric types will have a matching memory layout without first inspecting the memory layout.

source
JLD2.beheadMethod
behead(T)

Given a UnionAll type, recursively eliminates the where clauses

source
JLD2.construct_arrayMethod
construct_array{T}(io::IO, ::Type{T}, ndims::Int)

Construct array by reading ndims dimensions from io. Assumes io has already been seeked to the correct position.

source
JLD2.fileoffsetMethod
fileoffset(f::JLDFile, x::RelOffset)

Converts an offset x relative to the superblock of file f to an absolute offset.

source
JLD2.group_payload_sizeMethod
group_payload_size(g)

Returns the size of a group payload, including link info, group info, and link messages, but not the object header. Provides space after the last object message for a continuation message.

source
JLD2.h5offsetMethod
h5offset(f::JLDFile, x::RelOffset)

Converts an absolute file offset x to an offset relative to the superblock of file f.

source
JLD2.jld_finalizerMethod
jld_finalizer(f::JLDFile)

When a JLDFile is finalized, it is possible that the MmapIO has been munmapped, since Julia does not guarantee finalizer order. This means that the underlying file may be closed before we get a chance to write to it.

source
JLD2.jldopenFunction
jldopen(fname::AbstractString, mode::AbstractString; iotype=MmapIO, compress=false)

Opens a JLD2 file at path fname.

"r": Open for reading only, failing if no file exists "r+": Open for reading and writing, failing if no file exists "w"/"w+": Open for reading and writing, overwriting the file if it already exists "a"/"a+": Open for reading and writing, creating a new file if none exists, but preserving the existing file if one is present

source
JLD2.jldsaveMethod
jldsave(filename, compress=false; kwargs...)

Creates a JLD2 file at filename and stores the variables given as keyword arguments.

Examples

jldsave("example.jld2"; a=1, b=2, c)

is equivalent to

jldopen("example.jld2, "w") do f
f["a"] = 1
f["b"] = 2
f["c"] = c
end

To choose the io type IOStream instead of the default MmapIO use jldsave{IOStream}(fn; kwargs...).

source
JLD2.links_sizeMethod
links_size(pairs)

Returns the size of several link messages. pairs is an iterator of String => RelOffset pairs.

source
JLD2.load_datatypesMethod
load_datatypes(f::JLDFile)

Populate f.datatypes and f.jlh5types with all of the committed datatypes from a file. We need to do this before writing to make sure we reuse written datatypes.

source
JLD2.load_objectMethod
load_object(filename)

Returns the only available object from the JLD2 file filename (The stored object name is inconsequential). If the file contains more than one or no objects, the function throws an ArgumentError.

For loading more than one object, use @load macro, jldopen or the FileIO API.

Example

To load the only object from the JLD2 file example.jld2:

hello = "world"
save_object("example.jld2", hello)
hello_loaded = load_object("example.jld2")
source
JLD2.lookup_offsetMethod
lookup_offset(g::Group, name::AbstractString) -> RelOffset

Lookup the offset of a dataset in a group. Returns UNDEFINED_ADDRESS if the dataset is not present. Does not inspect unwritten_child_groups.

source
JLD2.pathizeMethod
pathize(g::Group, name::AbstractString, create::Bool) -> Tuple{Group,String}

Converts a path to a group and name object. If create is true, any intermediate groups will be created, and the dataset name will be checked for uniqueness with existing names.

source
JLD2.prewriteMethod
prewrite(f::JLDFile)

Check that a JLD file is actually writable, and throw an error if not. Sets the written flag on the file.

source
JLD2.printtocMethod
printtoc([io::IO,] f::JLDFile [; numlines])

Prints an overview of the contents of f to the IO.

Use the optional numlines parameter to restrict the amount of items listed.

source
JLD2.read_array!Function
read_array!(v::Array, f::JLDFile, rr)

Fill the array v with the contents of JLDFile f at the current position, assuming a ReadRepresentation rr.

source
JLD2.read_attr_dataMethod
read_attr_data(f::JLDFile, attr::ReadAttribute, expected_datatype::H5Datatype,
rr::ReadRepresentation)

jlread data from an attribute, assuming a specific HDF5 datatype and ReadRepresentation. If the HDF5 datatype does not match, throws an UnsupportedFeatureException. This allows better type stability while simultaneously validating the data.

source
JLD2.read_compressed_array!Function
read_compressed_array!(v::Array, f::JLDFile, rr, data_length::Int, ::Val{filter_id})

Fill the array v with the compressed contents of JLDFile f at the current position, assuming a ReadRepresentation rr and that the compressed data has length data_length.

source
JLD2.read_dataFunction
read_data(f::JLDFile, dataspace::ReadDataspace, datatype_class::UInt8,
datatype_offset::Int64, data_offset::Int64[, filter_id::UInt16,
header_offset::RelOffset, attributes::Vector{ReadAttribute}])

Read data from a file. If datatype_class is typemax(UInt8), the datatype is assumed to be committed, and datatype_offset points to the offset of the committed datatype's header. Otherwise, datatype_offset points to the offset of the datatype attribute.

source
JLD2.read_scalarFunction
read_scalar(f::JLDFile, rr, header_offset::RelOffset)

Read raw data representing a scalar with read representation rr from the current position of JLDFile f. header_offset is the RelOffset of the object header, used to resolve cycles.

source
JLD2.read_sizeMethod
read_size(io::IO, flags::UInt8)

Loads a variable-length size according to flags Expects that the first two bits of flags mean: 0 The size of the Length of Link Name field is 1 byte. 1 The size of the Length of Link Name field is 2 bytes. 2 The size of the Length of Link Name field is 4 bytes. 3 The size of the Length of Link Name field is 8 bytes. Returns the size as an Int

source
JLD2.save_groupMethod
save_group(g::Group) -> RelOffset

Stores a group to a file, updating it if it has already been saved. Returns UNDEFINED_ADDRESS if the group was already stored, or the offset of the new group otherwise.

source
JLD2.save_objectMethod
save_object(filename, x)

Stores an object x in a new JLD2 file at filename. If a file exists at this path, it will be overwritten.

Since the JLD2 format requires that all objects have a name, the object will be stored as single_sotred_object. If you want to store more than one object, use @save macro, jldopen or the FileIO API.

Example

To save the string hello to the JLD2 file example.jld2:

hello = "world"
save_object("example.jld2", hello)
source
JLD2.@loadMacro
@load filename var1 [var2 ...]

Load one or more variables var1,... from JLD2 file filename into the current scope and return a vector of the loaded variable names.

For interactive use, the form @load "somefile.jld2" will load all variables from "somefile.jld2" into the current scope. This form only supports literal file names and should be avoided in more permanent code so that it's clear where the variables come from.

Example

To load the variables hello and foo from the file example.jld2, use

@load "example.jld2" hello foo
source
JLD2.@saveMacro
@save filename var1 [var2 ...]
@save filename {compress=true} var1 name2=var2

Write one or more variables var1,... from the current scope to a JLD2 file filename.

For interactive use you can save all variables in the current module's global scope using @save filename. More permanent code should prefer the explicit form to avoid saving unwanted variables.

Example

To save the string hello and array xs to the JLD2 file example.jld2:

hello = "world"
xs = [1,2,3]
@save "example.jld2" hello xs

For passing options to the saving command use {}

@save "example.jld2" {compress=true} hello xs

For saving variables under a different name use regular assignment syntax

@save "example.jld2" greeting=hello xarray = xs
source