Skip to content

Commit

Permalink
build based on d6dcefa
Browse files Browse the repository at this point in the history
  • Loading branch information
Documenter.jl committed Oct 24, 2024
1 parent d49f124 commit 03944f2
Show file tree
Hide file tree
Showing 20 changed files with 1,490 additions and 0 deletions.
1 change: 1 addition & 0 deletions previews/PR612/.documenter-siteinfo.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-10-24T10:19:49","documenter_version":"1.7.0"}}
50 changes: 50 additions & 0 deletions previews/PR612/advanced/index.html
View file
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 &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"><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(&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-repl hljs">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 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&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 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(&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 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="Thursday 24 October 2024 10:19">Thursday 24 October 2024</span>. Using Julia version 1.11.1.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
Loading

0 comments on commit 03944f2

Please sign in to comment.