-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Documenter.jl
committed
Nov 6, 2024
1 parent
b31ed8f
commit 5c05deb
Showing
20 changed files
with
1,490 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-11-06T09:43:25","documenter_version":"1.7.0"}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
<!DOCTYPE html> | ||
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Advanced Usage · Julia Data Format</title><meta name="title" content="Advanced Usage · Julia Data Format"/><meta property="og:title" content="Advanced Usage · Julia Data Format"/><meta property="twitter:title" content="Advanced Usage · Julia Data Format"/><meta name="description" content="Documentation for Julia Data Format."/><meta property="og:description" content="Documentation for Julia Data Format."/><meta property="twitter:description" content="Documentation for Julia Data Format."/><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../search_index.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-mocha.css" data-theme-name="catppuccin-mocha"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-macchiato.css" data-theme-name="catppuccin-macchiato"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-frappe.css" data-theme-name="catppuccin-frappe"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/catppuccin-latte.css" data-theme-name="catppuccin-latte"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">Julia Data Format</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../">Basics</a></li><li><a class="tocitem" href="../customserialization/">Custom Serialization</a></li><li><a class="tocitem" href="../compression/">Compression</a></li><li><a class="tocitem" href="../internals/">Internals & Design</a></li><li><a class="tocitem" href="../hdf5compat/">HDF5 Compatibility</a></li><li class="is-active"><a class="tocitem" href>Advanced Usage</a><ul class="internal"><li><a class="tocitem" href="#Explicit-Type-Remapping"><span>Explicit Type Remapping</span></a></li><li><a class="tocitem" href="#Upgrading-old-structures-on-load"><span>Upgrading old structures on load</span></a></li><li><a class="tocitem" href="#Groups-Appending-to-files"><span>Groups - Appending to files</span></a></li><li><a class="tocitem" href="#JLD2DebugTools"><span>JLD2DebugTools</span></a></li><li><a class="tocitem" href="#Fallback-Behaviour"><span>Fallback Behaviour</span></a></li></ul></li><li><a class="tocitem" href="../legacy/">Legacy</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Advanced Usage</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Advanced Usage</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/JuliaIO/JLD2.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/JuliaIO/JLD2.jl/blob/master/docs/src/advanced.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="Advanced-Usage"><a class="docs-heading-anchor" href="#Advanced-Usage">Advanced Usage</a><a id="Advanced-Usage-1"></a><a class="docs-heading-anchor-permalink" href="#Advanced-Usage" title="Permalink"></a></h1><h2 id="Explicit-Type-Remapping"><a class="docs-heading-anchor" href="#Explicit-Type-Remapping">Explicit Type Remapping</a><a id="Explicit-Type-Remapping-1"></a><a class="docs-heading-anchor-permalink" href="#Explicit-Type-Remapping" title="Permalink"></a></h2><p>Sometimes you store data using <code>struct</code>s that you defined yourself or are shipped with some package and weeks later, when you want to load the data, the structs have changed.</p><pre><code class="language-julia hljs">using JLD2 | ||
struct A | ||
x::Int | ||
end | ||
jldsave("example.jld2"; a = A(42))</code></pre><p>This results in warnings and sometimes even errors when trying to load the file as demonstrated here.</p><pre><code class="language-julia-repl hljs">julia> using JLD2 | ||
|
||
julia> struct A{T} | ||
x::T | ||
end | ||
|
||
julia> load("example.jld2") | ||
┌ Warning: read type A is not a leaf type in workspace; reconstructing | ||
└ @ JLD2 ~/.julia/dev/JLD2/src/data/reconstructing_datatypes.jl:273 | ||
Dict{String, Any} with 1 entry: | ||
"a" => var"##A#257"(42)</code></pre><p>As of JLD2 version 0.4.21 there is a fix. The <code>JLDFile</code> struct contains a <code>typemap</code> dictionary that allows for explicit type remapping. Now you can define a struct that matches the old definition and load your data.</p><pre><code class="language-julia-repl hljs">julia> struct A_old | ||
x::Int | ||
end | ||
|
||
julia> f = jldopen("example.jld2","r"; typemap=Dict("Main.A" => A_old)) | ||
JLDFile /home/jonas/.julia/dev/JLD2/example.jld2 (read-only) | ||
└─🔢 a | ||
|
||
julia> f["a"] | ||
A_old(42)</code></pre><h2 id="Upgrading-old-structures-on-load"><a class="docs-heading-anchor" href="#Upgrading-old-structures-on-load">Upgrading old structures on load</a><a id="Upgrading-old-structures-on-load-1"></a><a class="docs-heading-anchor-permalink" href="#Upgrading-old-structures-on-load" title="Permalink"></a></h2><p>The section above explains how you can make JLD2 load old structs with a different DataType name as target. A different method for loading old data is described here:</p><pre><code class="language-julia hljs"># This is the old version of the struct stored in the file | ||
struct OldStructVersion | ||
x::Int | ||
y::Float64 | ||
end | ||
orig = OldStructVersion(1,2.0) | ||
jldsave("test.jld2"; data=orig) | ||
|
||
### new session | ||
|
||
# This is the new version of your struct | ||
struct UpdatedStruct | ||
x::Float64 # no longer int | ||
y::Float64 | ||
z::Float64 # = x*y | ||
end | ||
|
||
# When upgrading a struct, JLD2 will load the fields of the old struct into a `NamedTuple` | ||
# and call `rconvert` on it. Here we implement a conversion method that returns an `UpdatedStruct` | ||
JLD2.rconvert(::Type{UpdatedStruct}, nt::NamedTuple) = UpdatedStruct(Float64(nt.x), nt.y, nt.x*nt.y) | ||
|
||
# Here we provide the `typemap` keyword argument. It is a dictionary mapping the stored struct name | ||
# to an `Upgrade` instance with the new struct. | ||
load("test.jld2", "data"; typemap=Dict("Main.OldStructVersion" => JLD2.Upgrade(UpdatedStruct)))</code></pre><h2 id="Groups-Appending-to-files"><a class="docs-heading-anchor" href="#Groups-Appending-to-files">Groups - Appending to files</a><a id="Groups-Appending-to-files-1"></a><a class="docs-heading-anchor-permalink" href="#Groups-Appending-to-files" title="Permalink"></a></h2><p>Group objects can be constructed with two optional keyword arguments:</p><pre><code class="language-julia hljs">g = Group(file; | ||
est_num_entries=4 | ||
est_link_name_len=8)</code></pre><p>These determine how much (additional) empty space should be allocated for the group description. (list of entries) This can be useful for performance when one expects to append many additional datasets after first writing the file.</p><h2 id="JLD2DebugTools"><a class="docs-heading-anchor" href="#JLD2DebugTools">JLD2DebugTools</a><a id="JLD2DebugTools-1"></a><a class="docs-heading-anchor-permalink" href="#JLD2DebugTools" title="Permalink"></a></h2><p>There is an experimental repository <a href="https://github.com/JonasIsensee/JLD2DebugTools.jl">JLD2DebugTools.jl</a> that may help with debugging files.</p><h2 id="Fallback-Behaviour"><a class="docs-heading-anchor" href="#Fallback-Behaviour">Fallback Behaviour</a><a id="Fallback-Behaviour-1"></a><a class="docs-heading-anchor-permalink" href="#Fallback-Behaviour" title="Permalink"></a></h2><p>By default JLD2 will attempt to open files using the <code>MmapIO</code> backend. If that fails, it retries using <code>IOStream</code>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../hdf5compat/">« HDF5 Compatibility</a><a class="docs-footer-nextpage" href="../legacy/">Legacy »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.7.0 on <span class="colophon-date" title="Wednesday 6 November 2024 09:43">Wednesday 6 November 2024</span>. Using Julia version 1.11.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html> |
Oops, something went wrong.