Skip to content

Commit

Permalink
build based on 9babc06
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Jan 4, 2024
1 parent b58f3dc commit 305eb56
Show file tree
Hide file tree
Showing 15 changed files with 16,111 additions and 0 deletions.
46 changes: 46 additions & 0 deletions previews/PR523/advanced/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<!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><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/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="../siteinfo.js"></script><script src="../../versions.js"></script><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">Julia Data Format</span></div><form class="docs-search" action="../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><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 &amp; 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"><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-edit-link" href="https://github.com/JuliaIO/JLD2.jl" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></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">using JLD2
struct A
x::Int
end
jldsave(&quot;example.jld2&quot;; 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">julia&gt; using JLD2
julia&gt; struct A{T}
x::T
end
julia&gt; load(&quot;example.jld2&quot;)
┌ 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:
&quot;a&quot; =&gt; var&quot;##A#257&quot;(42)</code></pre><p>As of JLD2 version <code>v0.4.21</code> 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">julia&gt; struct A_old
x::Int
end
julia&gt; f = jldopen(&quot;example.jld2&quot;,&quot;r&quot;; typemap=Dict(&quot;Main.A&quot; =&gt; A_old))
JLDFile /home/jonas/.julia/dev/JLD2/example.jld2 (read-only)
└─🔢 a
julia&gt; f[&quot;a&quot;]
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"># 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(&quot;test.jld2&quot;; 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(&quot;test.jld2&quot;, &quot;data&quot;; typemap=Dict(&quot;Main.OldStructVersion&quot; =&gt; 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">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="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> on <span class="colophon-date" title="Thursday 4 January 2024 10:44">Thursday 4 January 2024</span>. Using Julia version 1.10.0.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
264 changes: 264 additions & 0 deletions previews/PR523/assets/documenter.js
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit 305eb56

Please sign in to comment.