| <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Getting started"><meta name="keywords" content="rust, rustlang, rust-lang, base64"><title>base64 - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><link rel="stylesheet" href="../normalize.css"><link rel="stylesheet" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" href="../ayu.css" disabled><link rel="stylesheet" href="../dark.css" disabled><link rel="stylesheet" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script defer src="../crates.js"></script><script defer src="../main.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../favicon.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">☰</button><a class="sidebar-logo" href="../base64/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2></h2></nav><nav class="sidebar"><a class="sidebar-logo" href="../base64/index.html"><div class="logo-container"><img class="rust-logo" src="../rust-logo.svg" alt="logo"></div></a><h2 class="location"><a href="#">Crate base64</a></h2><div class="sidebar-elems"><ul class="block"><li class="version">Version 0.21.2</li><li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#reexports">Re-exports</a></li><li><a href="#modules">Modules</a></li><li><a href="#enums">Enums</a></li><li><a href="#functions">Functions</a></li></ul></section></div></nav><main><div class="width-limiter"><nav class="sub"><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" title="help" tabindex="-1"><a href="../help.html">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1 class="fqn">Crate <a class="mod" href="#">base64</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="srclink" href="../src/base64/lib.rs.html#1-179">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">−</span>]</a></span></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="getting-started"><a href="#getting-started">Getting started</a></h2> |
| <ol> |
| <li>Perhaps one of the preconfigured engines in <a href="engine/general_purpose/index.html" title="engine::general_purpose">engine::general_purpose</a> will suit, e.g. |
| <a href="engine/general_purpose/constant.STANDARD_NO_PAD.html" title="engine::general_purpose::STANDARD_NO_PAD">engine::general_purpose::STANDARD_NO_PAD</a>. |
| <ul> |
| <li>These are re-exported in <a href="prelude/index.html" title="prelude">prelude</a> with a <code>BASE64_</code> prefix for those who prefer to |
| <code>use base64::prelude::*</code> or equivalent, e.g. <a href="engine/general_purpose/constant.STANDARD_NO_PAD.html" title="prelude::BASE64_STANDARD_NO_PAD">prelude::BASE64_STANDARD_NO_PAD</a></li> |
| </ul> |
| </li> |
| <li>If not, choose which alphabet you want. Most usage will want <a href="alphabet/constant.STANDARD.html" title="alphabet::STANDARD">alphabet::STANDARD</a> or <a href="alphabet/constant.URL_SAFE.html" title="alphabet::URL_SAFE">alphabet::URL_SAFE</a>.</li> |
| <li>Choose which <a href="engine/trait.Engine.html" title="Engine">Engine</a> implementation you want. For the moment there is only one: <a href="engine/general_purpose/struct.GeneralPurpose.html" title="engine::GeneralPurpose">engine::GeneralPurpose</a>.</li> |
| <li>Configure the engine appropriately using the engine’s <code>Config</code> type. |
| <ul> |
| <li>This is where you’ll select whether to add padding (when encoding) or expect it (when |
| decoding). If given the choice, prefer no padding.</li> |
| </ul> |
| </li> |
| <li>Build the engine using the selected alphabet and config.</li> |
| </ol> |
| <p>For more detail, see below.</p> |
| <h3 id="alphabets"><a href="#alphabets">Alphabets</a></h3> |
| <p>An <a href="alphabet/struct.Alphabet.html" title="alphabet::Alphabet">alphabet::Alphabet</a> defines what ASCII symbols are used to encode to or decode from.</p> |
| <p>Constants in <a href="alphabet/index.html" title="alphabet">alphabet</a> like <a href="alphabet/constant.STANDARD.html" title="alphabet::STANDARD">alphabet::STANDARD</a> or <a href="alphabet/constant.URL_SAFE.html" title="alphabet::URL_SAFE">alphabet::URL_SAFE</a> provide commonly used |
| alphabets, but you can also build your own custom <a href="alphabet/struct.Alphabet.html" title="alphabet::Alphabet">alphabet::Alphabet</a> if needed.</p> |
| <h3 id="engines"><a href="#engines">Engines</a></h3> |
| <p>Once you have an <code>Alphabet</code>, you can pick which <code>Engine</code> you want. A few parts of the public |
| API provide a default, but otherwise the user must provide an <code>Engine</code> to use.</p> |
| <p>See <a href="engine/trait.Engine.html" title="Engine">Engine</a> for more.</p> |
| <h3 id="config"><a href="#config">Config</a></h3> |
| <p>In addition to an <code>Alphabet</code>, constructing an <code>Engine</code> also requires an <a href="engine/trait.Config.html" title="engine::Config">engine::Config</a>. Each |
| <code>Engine</code> has a corresponding <code>Config</code> implementation since different <code>Engine</code>s may offer different |
| levels of configurability.</p> |
| <h2 id="encoding"><a href="#encoding">Encoding</a></h2> |
| <p>Several different encoding methods on <a href="engine/trait.Engine.html" title="Engine">Engine</a> are available to you depending on your desire for |
| convenience vs performance.</p> |
| <div><table><thead><tr><th>Method</th><th>Output</th><th>Allocates</th></tr></thead><tbody> |
| <tr><td><a href="engine/trait.Engine.html#method.encode" title="Engine::encode">Engine::encode</a></td><td>Returns a new <code>String</code></td><td>Always</td></tr> |
| <tr><td><a href="engine/trait.Engine.html#method.encode_string" title="Engine::encode_string">Engine::encode_string</a></td><td>Appends to provided <code>String</code></td><td>Only if <code>String</code> needs to grow</td></tr> |
| <tr><td><a href="engine/trait.Engine.html#method.encode_slice" title="Engine::encode_slice">Engine::encode_slice</a></td><td>Writes to provided <code>&[u8]</code></td><td>Never - fastest</td></tr> |
| </tbody></table> |
| </div> |
| <p>All of the encoding methods will pad as per the engine’s config.</p> |
| <h2 id="decoding"><a href="#decoding">Decoding</a></h2> |
| <p>Just as for encoding, there are different decoding methods available.</p> |
| <div><table><thead><tr><th>Method</th><th>Output</th><th>Allocates</th></tr></thead><tbody> |
| <tr><td><a href="engine/trait.Engine.html#method.decode" title="Engine::decode">Engine::decode</a></td><td>Returns a new <code>Vec<u8></code></td><td>Always</td></tr> |
| <tr><td><a href="engine/trait.Engine.html#method.decode_vec" title="Engine::decode_vec">Engine::decode_vec</a></td><td>Appends to provided <code>Vec<u8></code></td><td>Only if <code>Vec</code> needs to grow</td></tr> |
| <tr><td><a href="engine/trait.Engine.html#method.decode_slice" title="Engine::decode_slice">Engine::decode_slice</a></td><td>Writes to provided <code>&[u8]</code></td><td>Never - fastest</td></tr> |
| </tbody></table> |
| </div> |
| <p>Unlike encoding, where all possible input is valid, decoding can fail (see <a href="enum.DecodeError.html" title="DecodeError">DecodeError</a>).</p> |
| <p>Input can be invalid because it has invalid characters or invalid padding. The nature of how |
| padding is checked depends on the engine’s config. |
| Whitespace in the input is invalid, just like any other non-base64 byte.</p> |
| <h2 id="read-and-write"><a href="#read-and-write"><code>Read</code> and <code>Write</code></a></h2> |
| <p>To decode a <a href="https://doc.rust-lang.org/nightly/std/io/trait.Read.html" title="std::io::Read">std::io::Read</a> of b64 bytes, wrap a reader (file, network socket, etc) with |
| <a href="read/struct.DecoderReader.html" title="read::DecoderReader">read::DecoderReader</a>.</p> |
| <p>To write raw bytes and have them b64 encoded on the fly, wrap a <a href="https://doc.rust-lang.org/nightly/std/io/trait.Write.html" title="std::io::Write">std::io::Write</a> with |
| <a href="write/struct.EncoderWriter.html" title="write::EncoderWriter">write::EncoderWriter</a>.</p> |
| <p>There is some performance overhead (15% or so) because of the necessary buffer shuffling – |
| still fast enough that almost nobody cares. Also, these implementations do not heap allocate.</p> |
| <h2 id="display"><a href="#display"><code>Display</code></a></h2> |
| <p>See <a href="display/index.html" title="display">display</a> for how to transparently base64 data via a <code>Display</code> implementation.</p> |
| <h2 id="examples"><a href="#examples">Examples</a></h2><h3 id="using-predefined-engines"><a href="#using-predefined-engines">Using predefined engines</a></h3> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>base64::{Engine <span class="kw">as _</span>, engine::general_purpose}; |
| |
| <span class="kw">let </span>orig = <span class="string">b"data"</span>; |
| <span class="kw">let </span>encoded: String = general_purpose::STANDARD_NO_PAD.encode(orig); |
| <span class="macro">assert_eq!</span>(<span class="string">"ZGF0YQ"</span>, encoded); |
| <span class="macro">assert_eq!</span>(orig.as_slice(), <span class="kw-2">&</span>general_purpose::STANDARD_NO_PAD.decode(encoded).unwrap()); |
| |
| <span class="comment">// or, URL-safe |
| </span><span class="kw">let </span>encoded_url = general_purpose::URL_SAFE_NO_PAD.encode(orig);</code></pre></div> |
| <h3 id="custom-alphabet-config-and-engine"><a href="#custom-alphabet-config-and-engine">Custom alphabet, config, and engine</a></h3> |
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>base64::{engine, alphabet, Engine <span class="kw">as _</span>}; |
| |
| <span class="comment">// bizarro-world base64: +/ as the first symbols instead of the last |
| </span><span class="kw">let </span>alphabet = |
| alphabet::Alphabet::new(<span class="string">"+/ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"</span>) |
| .unwrap(); |
| |
| <span class="comment">// a very weird config that encodes with padding but requires no padding when decoding...? |
| </span><span class="kw">let </span>crazy_config = engine::GeneralPurposeConfig::new() |
| .with_decode_allow_trailing_bits(<span class="bool-val">true</span>) |
| .with_encode_padding(<span class="bool-val">true</span>) |
| .with_decode_padding_mode(engine::DecodePaddingMode::RequireNone); |
| |
| <span class="kw">let </span>crazy_engine = engine::GeneralPurpose::new(<span class="kw-2">&</span>alphabet, crazy_config); |
| |
| <span class="kw">let </span>encoded = crazy_engine.encode(<span class="string">b"abc 123"</span>); |
| </code></pre></div> |
| <h2 id="panics"><a href="#panics">Panics</a></h2> |
| <p>If length calculations result in overflowing <code>usize</code>, a panic will result.</p> |
| </div></details><h2 id="reexports" class="small-section-header"><a href="#reexports">Re-exports</a></h2><div class="item-table"><div class="item-row"><div class="item-left import-item" id="reexport.Engine"><code>pub use engine::<a class="trait" href="engine/trait.Engine.html" title="trait base64::engine::Engine">Engine</a>;</code></div></div></div><h2 id="modules" class="small-section-header"><a href="#modules">Modules</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="mod" href="alphabet/index.html" title="base64::alphabet mod">alphabet</a></div><div class="item-right docblock-short">Provides <a href="alphabet/struct.Alphabet.html" title="Alphabet">Alphabet</a> and constants for alphabets commonly used in the wild.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="display/index.html" title="base64::display mod">display</a></div><div class="item-right docblock-short">Enables base64’d output anywhere you might use a <code>Display</code> implementation, like a format string.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="engine/index.html" title="base64::engine mod">engine</a></div><div class="item-right docblock-short">Provides the <a href="engine/trait.Engine.html" title="Engine">Engine</a> abstraction and out of the box implementations.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="prelude/index.html" title="base64::prelude mod">prelude</a></div><div class="item-right docblock-short">Preconfigured engines for common use cases.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="read/index.html" title="base64::read mod">read</a></div><div class="item-right docblock-short">Implementations of <code>io::Read</code> to transparently decode base64.</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="write/index.html" title="base64::write mod">write</a></div><div class="item-right docblock-short">Implementations of <code>io::Write</code> to transparently handle base64.</div></div></div><h2 id="enums" class="small-section-header"><a href="#enums">Enums</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.DecodeError.html" title="base64::DecodeError enum">DecodeError</a></div><div class="item-right docblock-short">Errors that can occur while decoding.</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.DecodeSliceError.html" title="base64::DecodeSliceError enum">DecodeSliceError</a></div><div class="item-right docblock-short">Errors that can occur while decoding into a slice.</div></div><div class="item-row"><div class="item-left module-item"><a class="enum" href="enum.EncodeSliceError.html" title="base64::EncodeSliceError enum">EncodeSliceError</a></div><div class="item-right docblock-short">Errors that can occur while encoding into a slice.</div></div></div><h2 id="functions" class="small-section-header"><a href="#functions">Functions</a></h2><div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.decode.html" title="base64::decode fn">decode</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Decode base64 using the <a href="engine/general_purpose/constant.STANDARD.html"><code>STANDARD</code> engine</a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.decode_engine.html" title="base64::decode_engine fn">decode_engine</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Decode from string reference as octets using the specified <a href="engine/trait.Engine.html" title="Engine">Engine</a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.decode_engine_slice.html" title="base64::decode_engine_slice fn">decode_engine_slice</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Decode the input into the provided output slice.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.decode_engine_vec.html" title="base64::decode_engine_vec fn">decode_engine_vec</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Decode from string reference as octets.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.decoded_len_estimate.html" title="base64::decoded_len_estimate fn">decoded_len_estimate</a></div><div class="item-right docblock-short">Returns a conservative estimate of the decoded size of <code>encoded_len</code> base64 symbols (rounded up |
| to the next group of 3 decoded bytes).</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.encode.html" title="base64::encode fn">encode</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Encode arbitrary octets as base64 using the <a href="engine/general_purpose/constant.STANDARD.html"><code>STANDARD</code> engine</a>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.encode_engine.html" title="base64::encode_engine fn">encode_engine</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Encode arbitrary octets as base64 using the provided <code>Engine</code> into a new <code>String</code>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.encode_engine_slice.html" title="base64::encode_engine_slice fn">encode_engine_slice</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Encode arbitrary octets as base64 into a supplied slice.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.encode_engine_string.html" title="base64::encode_engine_string fn">encode_engine_string</a><span class="stab deprecated" title="">Deprecated</span></div><div class="item-right docblock-short">Encode arbitrary octets as base64 into a supplied <code>String</code>.</div></div><div class="item-row"><div class="item-left module-item"><a class="fn" href="fn.encoded_len.html" title="base64::encoded_len fn">encoded_len</a></div><div class="item-right docblock-short">Calculate the base64 encoded length for a given input length, optionally including any |
| appropriate padding bytes.</div></div></div></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="base64" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.66.0-nightly (5c8bff74b 2022-10-21)" ></div></body></html> |
