737 lines
52 KiB
HTML
737 lines
52 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>struct — Interpret bytes as packed binary data — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="codecs — Codec registry and base classes" href="codecs.html" />
|
|||
|
|
<link rel="prev" title="Binary Data Services" href="binary.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/struct.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="codecs.html" title="codecs — Codec registry and base classes"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="binary.html" title="Binary Data Services"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="binary.html" accesskey="U">Binary Data Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="module-struct">
|
|||
|
|
<span id="struct-interpret-bytes-as-packed-binary-data"></span><h1><a class="reference internal" href="#module-struct" title="struct: Interpret bytes as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> — Interpret bytes as packed binary data<a class="headerlink" href="#module-struct" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/struct.py">Lib/struct.py</a></p>
|
|||
|
|
<hr class="docutils" id="index-0" />
|
|||
|
|
<p>This module performs conversions between Python values and C structs represented
|
|||
|
|
as Python <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> objects. This can be used in handling binary data
|
|||
|
|
stored in files or from network connections, among other sources. It uses
|
|||
|
|
<a class="reference internal" href="#struct-format-strings"><span class="std std-ref">Format Strings</span></a> as compact descriptions of the layout of the C
|
|||
|
|
structs and the intended conversion to/from Python values.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>By default, the result of packing a given C struct includes pad bytes in
|
|||
|
|
order to maintain proper alignment for the C types involved; similarly,
|
|||
|
|
alignment is taken into account when unpacking. This behavior is chosen so
|
|||
|
|
that the bytes of a packed struct correspond exactly to the layout in memory
|
|||
|
|
of the corresponding C struct. To handle platform-independent data formats
|
|||
|
|
or omit implicit pad bytes, use <code class="docutils literal notranslate"><span class="pre">standard</span></code> size and alignment instead of
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">native</span></code> size and alignment: see <a class="reference internal" href="#struct-alignment"><span class="std std-ref">Byte Order, Size, and Alignment</span></a> for details.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>Several <a class="reference internal" href="#module-struct" title="struct: Interpret bytes as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> functions (and methods of <a class="reference internal" href="#struct.Struct" title="struct.Struct"><code class="xref py py-class docutils literal notranslate"><span class="pre">Struct</span></code></a>) take a <em>buffer</em>
|
|||
|
|
argument. This refers to objects that implement the <a class="reference internal" href="../c-api/buffer.html#bufferobjects"><span class="std std-ref">Buffer Protocol</span></a> and
|
|||
|
|
provide either a readable or read-writable buffer. The most common types used
|
|||
|
|
for that purpose are <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> and <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>, but many other types
|
|||
|
|
that can be viewed as an array of bytes implement the buffer protocol, so that
|
|||
|
|
they can be read/filled without additional copying from a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
|||
|
|
<div class="section" id="functions-and-exceptions">
|
|||
|
|
<h2>Functions and Exceptions<a class="headerlink" href="#functions-and-exceptions" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The module defines the following exception and functions:</p>
|
|||
|
|
<dl class="exception">
|
|||
|
|
<dt id="struct.error">
|
|||
|
|
<em class="property">exception </em><code class="descclassname">struct.</code><code class="descname">error</code><a class="headerlink" href="#struct.error" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Exception raised on various occasions; argument is a string describing what
|
|||
|
|
is wrong.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.pack">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">pack</code><span class="sig-paren">(</span><em>format</em>, <em>v1</em>, <em>v2</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.pack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a bytes object containing the values <em>v1</em>, <em>v2</em>, … packed according
|
|||
|
|
to the format string <em>format</em>. The arguments must match the values required by
|
|||
|
|
the format exactly.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.pack_into">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">pack_into</code><span class="sig-paren">(</span><em>format</em>, <em>buffer</em>, <em>offset</em>, <em>v1</em>, <em>v2</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.pack_into" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Pack the values <em>v1</em>, <em>v2</em>, … according to the format string <em>format</em> and
|
|||
|
|
write the packed bytes into the writable buffer <em>buffer</em> starting at
|
|||
|
|
position <em>offset</em>. Note that <em>offset</em> is a required argument.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.unpack">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">unpack</code><span class="sig-paren">(</span><em>format</em>, <em>buffer</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.unpack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Unpack from the buffer <em>buffer</em> (presumably packed by <code class="docutils literal notranslate"><span class="pre">pack(format,</span> <span class="pre">...)</span></code>)
|
|||
|
|
according to the format string <em>format</em>. The result is a tuple even if it
|
|||
|
|
contains exactly one item. The buffer’s size in bytes must match the
|
|||
|
|
size required by the format, as reflected by <a class="reference internal" href="#struct.calcsize" title="struct.calcsize"><code class="xref py py-func docutils literal notranslate"><span class="pre">calcsize()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.unpack_from">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">unpack_from</code><span class="sig-paren">(</span><em>format</em>, <em>buffer</em>, <em>offset=0</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.unpack_from" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Unpack from <em>buffer</em> starting at position <em>offset</em>, according to the format
|
|||
|
|
string <em>format</em>. The result is a tuple even if it contains exactly one
|
|||
|
|
item. The buffer’s size in bytes, minus <em>offset</em>, must be at least
|
|||
|
|
the size required by the format, as reflected by <a class="reference internal" href="#struct.calcsize" title="struct.calcsize"><code class="xref py py-func docutils literal notranslate"><span class="pre">calcsize()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.iter_unpack">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">iter_unpack</code><span class="sig-paren">(</span><em>format</em>, <em>buffer</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.iter_unpack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Iteratively unpack from the buffer <em>buffer</em> according to the format
|
|||
|
|
string <em>format</em>. This function returns an iterator which will read
|
|||
|
|
equally-sized chunks from the buffer until all its contents have been
|
|||
|
|
consumed. The buffer’s size in bytes must be a multiple of the size
|
|||
|
|
required by the format, as reflected by <a class="reference internal" href="#struct.calcsize" title="struct.calcsize"><code class="xref py py-func docutils literal notranslate"><span class="pre">calcsize()</span></code></a>.</p>
|
|||
|
|
<p>Each iteration yields a tuple as specified by the format string.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="struct.calcsize">
|
|||
|
|
<code class="descclassname">struct.</code><code class="descname">calcsize</code><span class="sig-paren">(</span><em>format</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.calcsize" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the size of the struct (and hence of the bytes object produced by
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">pack(format,</span> <span class="pre">...)</span></code>) corresponding to the format string <em>format</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="format-strings">
|
|||
|
|
<span id="struct-format-strings"></span><h2>Format Strings<a class="headerlink" href="#format-strings" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>Format strings are the mechanism used to specify the expected layout when
|
|||
|
|
packing and unpacking data. They are built up from <a class="reference internal" href="#format-characters"><span class="std std-ref">Format Characters</span></a>,
|
|||
|
|
which specify the type of data being packed/unpacked. In addition, there are
|
|||
|
|
special characters for controlling the <a class="reference internal" href="#struct-alignment"><span class="std std-ref">Byte Order, Size, and Alignment</span></a>.</p>
|
|||
|
|
<div class="section" id="byte-order-size-and-alignment">
|
|||
|
|
<span id="struct-alignment"></span><h3>Byte Order, Size, and Alignment<a class="headerlink" href="#byte-order-size-and-alignment" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>By default, C types are represented in the machine’s native format and byte
|
|||
|
|
order, and properly aligned by skipping pad bytes if necessary (according to the
|
|||
|
|
rules used by the C compiler).</p>
|
|||
|
|
<p id="index-1">Alternatively, the first character of the format string can be used to indicate
|
|||
|
|
the byte order, size and alignment of the packed data, according to the
|
|||
|
|
following table:</p>
|
|||
|
|
<table class="docutils align-center">
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 20%" />
|
|||
|
|
<col style="width: 43%" />
|
|||
|
|
<col style="width: 18%" />
|
|||
|
|
<col style="width: 20%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="row-odd"><th class="head"><p>Character</p></th>
|
|||
|
|
<th class="head"><p>Byte order</p></th>
|
|||
|
|
<th class="head"><p>Size</p></th>
|
|||
|
|
<th class="head"><p>Alignment</p></th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">@</span></code></p></td>
|
|||
|
|
<td><p>native</p></td>
|
|||
|
|
<td><p>native</p></td>
|
|||
|
|
<td><p>native</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">=</span></code></p></td>
|
|||
|
|
<td><p>native</p></td>
|
|||
|
|
<td><p>standard</p></td>
|
|||
|
|
<td><p>none</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre"><</span></code></p></td>
|
|||
|
|
<td><p>little-endian</p></td>
|
|||
|
|
<td><p>standard</p></td>
|
|||
|
|
<td><p>none</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">></span></code></p></td>
|
|||
|
|
<td><p>big-endian</p></td>
|
|||
|
|
<td><p>standard</p></td>
|
|||
|
|
<td><p>none</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">!</span></code></p></td>
|
|||
|
|
<td><p>network (= big-endian)</p></td>
|
|||
|
|
<td><p>standard</p></td>
|
|||
|
|
<td><p>none</p></td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p>If the first character is not one of these, <code class="docutils literal notranslate"><span class="pre">'@'</span></code> is assumed.</p>
|
|||
|
|
<p>Native byte order is big-endian or little-endian, depending on the host
|
|||
|
|
system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
|
|||
|
|
Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
|
|||
|
|
switchable endianness (bi-endian). Use <code class="docutils literal notranslate"><span class="pre">sys.byteorder</span></code> to check the
|
|||
|
|
endianness of your system.</p>
|
|||
|
|
<p>Native size and alignment are determined using the C compiler’s
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">sizeof</span></code> expression. This is always combined with native byte order.</p>
|
|||
|
|
<p>Standard size depends only on the format character; see the table in
|
|||
|
|
the <a class="reference internal" href="#format-characters"><span class="std std-ref">Format Characters</span></a> section.</p>
|
|||
|
|
<p>Note the difference between <code class="docutils literal notranslate"><span class="pre">'@'</span></code> and <code class="docutils literal notranslate"><span class="pre">'='</span></code>: both use native byte order, but
|
|||
|
|
the size and alignment of the latter is standardized.</p>
|
|||
|
|
<p>The form <code class="docutils literal notranslate"><span class="pre">'!'</span></code> is available for those poor souls who claim they can’t remember
|
|||
|
|
whether network byte order is big-endian or little-endian.</p>
|
|||
|
|
<p>There is no way to indicate non-native byte order (force byte-swapping); use the
|
|||
|
|
appropriate choice of <code class="docutils literal notranslate"><span class="pre">'<'</span></code> or <code class="docutils literal notranslate"><span class="pre">'>'</span></code>.</p>
|
|||
|
|
<p>Notes:</p>
|
|||
|
|
<ol class="arabic simple">
|
|||
|
|
<li><p>Padding is only automatically added between successive structure members.
|
|||
|
|
No padding is added at the beginning or the end of the encoded struct.</p></li>
|
|||
|
|
<li><p>No padding is added when using non-native size and alignment, e.g.
|
|||
|
|
with ‘<’, ‘>’, ‘=’, and ‘!’.</p></li>
|
|||
|
|
<li><p>To align the end of a structure to the alignment requirement of a
|
|||
|
|
particular type, end the format with the code for that type with a repeat
|
|||
|
|
count of zero. See <a class="reference internal" href="#struct-examples"><span class="std std-ref">Examples</span></a>.</p></li>
|
|||
|
|
</ol>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="format-characters">
|
|||
|
|
<span id="id1"></span><h3>Format Characters<a class="headerlink" href="#format-characters" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>Format characters have the following meaning; the conversion between C and
|
|||
|
|
Python values should be obvious given their types. The ‘Standard size’ column
|
|||
|
|
refers to the size of the packed value in bytes when using standard size; that
|
|||
|
|
is, when the format string starts with one of <code class="docutils literal notranslate"><span class="pre">'<'</span></code>, <code class="docutils literal notranslate"><span class="pre">'>'</span></code>, <code class="docutils literal notranslate"><span class="pre">'!'</span></code> or
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'='</span></code>. When using native size, the size of the packed value is
|
|||
|
|
platform-dependent.</p>
|
|||
|
|
<table class="docutils align-center">
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 10%" />
|
|||
|
|
<col style="width: 32%" />
|
|||
|
|
<col style="width: 24%" />
|
|||
|
|
<col style="width: 20%" />
|
|||
|
|
<col style="width: 15%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="row-odd"><th class="head"><p>Format</p></th>
|
|||
|
|
<th class="head"><p>C Type</p></th>
|
|||
|
|
<th class="head"><p>Python type</p></th>
|
|||
|
|
<th class="head"><p>Standard size</p></th>
|
|||
|
|
<th class="head"><p>Notes</p></th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">x</span></code></p></td>
|
|||
|
|
<td><p>pad byte</p></td>
|
|||
|
|
<td><p>no value</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">c</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code></p></td>
|
|||
|
|
<td><p>bytes of length 1</p></td>
|
|||
|
|
<td><p>1</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">b</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">signed</span> <span class="pre">char</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>1</p></td>
|
|||
|
|
<td><p>(1),(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">B</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>1</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">?</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">_Bool</span></code></p></td>
|
|||
|
|
<td><p>bool</p></td>
|
|||
|
|
<td><p>1</p></td>
|
|||
|
|
<td><p>(1)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">h</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">short</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>2</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">H</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>2</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">i</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>4</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">I</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>4</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">l</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>4</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">L</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>4</p></td>
|
|||
|
|
<td><p>(3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">q</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>8</p></td>
|
|||
|
|
<td><p>(2), (3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">Q</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span>
|
|||
|
|
<span class="pre">long</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td><p>8</p></td>
|
|||
|
|
<td><p>(2), (3)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">n</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">ssize_t</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td><p>(4)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">N</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">size_t</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td><p>(4)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">e</span></code></p></td>
|
|||
|
|
<td><p>(7)</p></td>
|
|||
|
|
<td><p>float</p></td>
|
|||
|
|
<td><p>2</p></td>
|
|||
|
|
<td><p>(5)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">f</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code></p></td>
|
|||
|
|
<td><p>float</p></td>
|
|||
|
|
<td><p>4</p></td>
|
|||
|
|
<td><p>(5)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">d</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code></p></td>
|
|||
|
|
<td><p>float</p></td>
|
|||
|
|
<td><p>8</p></td>
|
|||
|
|
<td><p>(5)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">s</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">char[]</span></code></p></td>
|
|||
|
|
<td><p>bytes</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">p</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">char[]</span></code></p></td>
|
|||
|
|
<td><p>bytes</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">P</span></code></p></td>
|
|||
|
|
<td><p><code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code></p></td>
|
|||
|
|
<td><p>integer</p></td>
|
|||
|
|
<td></td>
|
|||
|
|
<td><p>(6)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>Added support for the <code class="docutils literal notranslate"><span class="pre">'n'</span></code> and <code class="docutils literal notranslate"><span class="pre">'N'</span></code> formats.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>Added support for the <code class="docutils literal notranslate"><span class="pre">'e'</span></code> format.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>Notes:</p>
|
|||
|
|
<ol class="arabic">
|
|||
|
|
<li><p id="index-2">The <code class="docutils literal notranslate"><span class="pre">'?'</span></code> conversion code corresponds to the <code class="xref c c-type docutils literal notranslate"><span class="pre">_Bool</span></code> type defined by
|
|||
|
|
C99. If this type is not available, it is simulated using a <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code>. In
|
|||
|
|
standard mode, it is always represented by one byte.</p>
|
|||
|
|
</li>
|
|||
|
|
<li><p>The <code class="docutils literal notranslate"><span class="pre">'q'</span></code> and <code class="docutils literal notranslate"><span class="pre">'Q'</span></code> conversion codes are available in native mode only if
|
|||
|
|
the platform C compiler supports C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>, or, on Windows,
|
|||
|
|
<code class="xref c c-type docutils literal notranslate"><span class="pre">__int64</span></code>. They are always available in standard modes.</p></li>
|
|||
|
|
<li><p>When attempting to pack a non-integer using any of the integer conversion
|
|||
|
|
codes, if the non-integer has a <a class="reference internal" href="../reference/datamodel.html#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a> method then that method is
|
|||
|
|
called to convert the argument to an integer before packing.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>Use of the <a class="reference internal" href="../reference/datamodel.html#object.__index__" title="object.__index__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__index__()</span></code></a> method for non-integers is new in 3.2.</p>
|
|||
|
|
</div>
|
|||
|
|
</li>
|
|||
|
|
<li><p>The <code class="docutils literal notranslate"><span class="pre">'n'</span></code> and <code class="docutils literal notranslate"><span class="pre">'N'</span></code> conversion codes are only available for the native
|
|||
|
|
size (selected as the default or with the <code class="docutils literal notranslate"><span class="pre">'@'</span></code> byte order character).
|
|||
|
|
For the standard size, you can use whichever of the other integer formats
|
|||
|
|
fits your application.</p></li>
|
|||
|
|
<li><p>For the <code class="docutils literal notranslate"><span class="pre">'f'</span></code>, <code class="docutils literal notranslate"><span class="pre">'d'</span></code> and <code class="docutils literal notranslate"><span class="pre">'e'</span></code> conversion codes, the packed
|
|||
|
|
representation uses the IEEE 754 binary32, binary64 or binary16 format (for
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'f'</span></code>, <code class="docutils literal notranslate"><span class="pre">'d'</span></code> or <code class="docutils literal notranslate"><span class="pre">'e'</span></code> respectively), regardless of the floating-point
|
|||
|
|
format used by the platform.</p></li>
|
|||
|
|
<li><p>The <code class="docutils literal notranslate"><span class="pre">'P'</span></code> format character is only available for the native byte ordering
|
|||
|
|
(selected as the default or with the <code class="docutils literal notranslate"><span class="pre">'@'</span></code> byte order character). The byte
|
|||
|
|
order character <code class="docutils literal notranslate"><span class="pre">'='</span></code> chooses to use little- or big-endian ordering based
|
|||
|
|
on the host system. The struct module does not interpret this as native
|
|||
|
|
ordering, so the <code class="docutils literal notranslate"><span class="pre">'P'</span></code> format is not available.</p></li>
|
|||
|
|
<li><p>The IEEE 754 binary16 “half precision” type was introduced in the 2008
|
|||
|
|
revision of the <a class="reference external" href="https://en.wikipedia.org/wiki/IEEE_floating_point#IEEE_754-2008">IEEE 754 standard</a>. It has a sign
|
|||
|
|
bit, a 5-bit exponent and 11-bit precision (with 10 bits explicitly stored),
|
|||
|
|
and can represent numbers between approximately <code class="docutils literal notranslate"><span class="pre">6.1e-05</span></code> and <code class="docutils literal notranslate"><span class="pre">6.5e+04</span></code>
|
|||
|
|
at full precision. This type is not widely supported by C compilers: on a
|
|||
|
|
typical machine, an unsigned short can be used for storage, but not for math
|
|||
|
|
operations. See the Wikipedia page on the <a class="reference external" href="https://en.wikipedia.org/wiki/Half-precision_floating-point_format">half-precision floating-point
|
|||
|
|
format</a> for more information.</p></li>
|
|||
|
|
</ol>
|
|||
|
|
<p>A format character may be preceded by an integral repeat count. For example,
|
|||
|
|
the format string <code class="docutils literal notranslate"><span class="pre">'4h'</span></code> means exactly the same as <code class="docutils literal notranslate"><span class="pre">'hhhh'</span></code>.</p>
|
|||
|
|
<p>Whitespace characters between formats are ignored; a count and its format must
|
|||
|
|
not contain whitespace though.</p>
|
|||
|
|
<p>For the <code class="docutils literal notranslate"><span class="pre">'s'</span></code> format character, the count is interpreted as the length of the
|
|||
|
|
bytes, not a repeat count like for the other format characters; for example,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'10s'</span></code> means a single 10-byte string, while <code class="docutils literal notranslate"><span class="pre">'10c'</span></code> means 10 characters.
|
|||
|
|
If a count is not given, it defaults to 1. For packing, the string is
|
|||
|
|
truncated or padded with null bytes as appropriate to make it fit. For
|
|||
|
|
unpacking, the resulting bytes object always has exactly the specified number
|
|||
|
|
of bytes. As a special case, <code class="docutils literal notranslate"><span class="pre">'0s'</span></code> means a single, empty string (while
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'0c'</span></code> means 0 characters).</p>
|
|||
|
|
<p>When packing a value <code class="docutils literal notranslate"><span class="pre">x</span></code> using one of the integer formats (<code class="docutils literal notranslate"><span class="pre">'b'</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'B'</span></code>, <code class="docutils literal notranslate"><span class="pre">'h'</span></code>, <code class="docutils literal notranslate"><span class="pre">'H'</span></code>, <code class="docutils literal notranslate"><span class="pre">'i'</span></code>, <code class="docutils literal notranslate"><span class="pre">'I'</span></code>, <code class="docutils literal notranslate"><span class="pre">'l'</span></code>, <code class="docutils literal notranslate"><span class="pre">'L'</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">'q'</span></code>, <code class="docutils literal notranslate"><span class="pre">'Q'</span></code>), if <code class="docutils literal notranslate"><span class="pre">x</span></code> is outside the valid range for that format
|
|||
|
|
then <a class="reference internal" href="#struct.error" title="struct.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">struct.error</span></code></a> is raised.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.1: </span>In 3.0, some of the integer formats wrapped out-of-range values and
|
|||
|
|
raised <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> instead of <a class="reference internal" href="#struct.error" title="struct.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">struct.error</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">'p'</span></code> format character encodes a “Pascal string”, meaning a short
|
|||
|
|
variable-length string stored in a <em>fixed number of bytes</em>, given by the count.
|
|||
|
|
The first byte stored is the length of the string, or 255, whichever is
|
|||
|
|
smaller. The bytes of the string follow. If the string passed in to
|
|||
|
|
<a class="reference internal" href="#struct.pack" title="struct.pack"><code class="xref py py-func docutils literal notranslate"><span class="pre">pack()</span></code></a> is too long (longer than the count minus 1), only the leading
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">count-1</span></code> bytes of the string are stored. If the string is shorter than
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">count-1</span></code>, it is padded with null bytes so that exactly count bytes in all
|
|||
|
|
are used. Note that for <a class="reference internal" href="#struct.unpack" title="struct.unpack"><code class="xref py py-func docutils literal notranslate"><span class="pre">unpack()</span></code></a>, the <code class="docutils literal notranslate"><span class="pre">'p'</span></code> format character consumes
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">count</span></code> bytes, but that the string returned can never contain more than 255
|
|||
|
|
bytes.</p>
|
|||
|
|
<p id="index-3">For the <code class="docutils literal notranslate"><span class="pre">'?'</span></code> format character, the return value is either <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> or
|
|||
|
|
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. When packing, the truth value of the argument object is used.
|
|||
|
|
Either 0 or 1 in the native or standard bool representation will be packed, and
|
|||
|
|
any non-zero value will be <code class="docutils literal notranslate"><span class="pre">True</span></code> when unpacking.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="examples">
|
|||
|
|
<span id="struct-examples"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>All examples assume a native byte order, size, and alignment with a
|
|||
|
|
big-endian machine.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>A basic example of packing/unpacking three integers:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">struct</span> <span class="k">import</span> <span class="o">*</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">pack</span><span class="p">(</span><span class="s1">'hhl'</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
|
|||
|
|
<span class="go">b'\x00\x01\x00\x02\x00\x00\x00\x03'</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">unpack</span><span class="p">(</span><span class="s1">'hhl'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'</span><span class="se">\x00\x01\x00\x02\x00\x00\x00\x03</span><span class="s1">'</span><span class="p">)</span>
|
|||
|
|
<span class="go">(1, 2, 3)</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">calcsize</span><span class="p">(</span><span class="s1">'hhl'</span><span class="p">)</span>
|
|||
|
|
<span class="go">8</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Unpacked fields can be named by assigning them to variables or by wrapping
|
|||
|
|
the result in a named tuple:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">record</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'raymond </span><span class="se">\x32\x12\x08\x01\x08</span><span class="s1">'</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">name</span><span class="p">,</span> <span class="n">serialnum</span><span class="p">,</span> <span class="n">school</span><span class="p">,</span> <span class="n">gradelevel</span> <span class="o">=</span> <span class="n">unpack</span><span class="p">(</span><span class="s1">'<10sHHb'</span><span class="p">,</span> <span class="n">record</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">collections</span> <span class="k">import</span> <span class="n">namedtuple</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">Student</span> <span class="o">=</span> <span class="n">namedtuple</span><span class="p">(</span><span class="s1">'Student'</span><span class="p">,</span> <span class="s1">'name serialnum school gradelevel'</span><span class="p">)</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">Student</span><span class="o">.</span><span class="n">_make</span><span class="p">(</span><span class="n">unpack</span><span class="p">(</span><span class="s1">'<10sHHb'</span><span class="p">,</span> <span class="n">record</span><span class="p">))</span>
|
|||
|
|
<span class="go">Student(name=b'raymond ', serialnum=4658, school=264, gradelevel=8)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The ordering of format characters may have an impact on size since the padding
|
|||
|
|
needed to satisfy alignment requirements is different:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pack</span><span class="p">(</span><span class="s1">'ci'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'*'</span><span class="p">,</span> <span class="mh">0x12131415</span><span class="p">)</span>
|
|||
|
|
<span class="go">b'*\x00\x00\x00\x12\x13\x14\x15'</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">pack</span><span class="p">(</span><span class="s1">'ic'</span><span class="p">,</span> <span class="mh">0x12131415</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'*'</span><span class="p">)</span>
|
|||
|
|
<span class="go">b'\x12\x13\x14\x15*'</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">calcsize</span><span class="p">(</span><span class="s1">'ci'</span><span class="p">)</span>
|
|||
|
|
<span class="go">8</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">calcsize</span><span class="p">(</span><span class="s1">'ic'</span><span class="p">)</span>
|
|||
|
|
<span class="go">5</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The following format <code class="docutils literal notranslate"><span class="pre">'llh0l'</span></code> specifies two pad bytes at the end, assuming
|
|||
|
|
longs are aligned on 4-byte boundaries:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">pack</span><span class="p">(</span><span class="s1">'llh0l'</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
|
|||
|
|
<span class="go">b'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>This only works when native size and alignment are in effect; standard size and
|
|||
|
|
alignment does not enforce any alignment.</p>
|
|||
|
|
<div class="admonition seealso">
|
|||
|
|
<p class="admonition-title">See also</p>
|
|||
|
|
<dl class="simple">
|
|||
|
|
<dt>Module <a class="reference internal" href="array.html#module-array" title="array: Space efficient arrays of uniformly typed numeric values."><code class="xref py py-mod docutils literal notranslate"><span class="pre">array</span></code></a></dt><dd><p>Packed binary storage of homogeneous data.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt>Module <a class="reference internal" href="xdrlib.html#module-xdrlib" title="xdrlib: Encoders and decoders for the External Data Representation (XDR)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">xdrlib</span></code></a></dt><dd><p>Packing and unpacking of XDR data.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="classes">
|
|||
|
|
<span id="struct-objects"></span><h2>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The <a class="reference internal" href="#module-struct" title="struct: Interpret bytes as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> module also defines the following type:</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="struct.Struct">
|
|||
|
|
<em class="property">class </em><code class="descclassname">struct.</code><code class="descname">Struct</code><span class="sig-paren">(</span><em>format</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a new Struct object which writes and reads binary data according to
|
|||
|
|
the format string <em>format</em>. Creating a Struct object once and calling its
|
|||
|
|
methods is more efficient than calling the <a class="reference internal" href="#module-struct" title="struct: Interpret bytes as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> functions with the
|
|||
|
|
same format since the format string only needs to be compiled once.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>The compiled versions of the most recent format strings passed to
|
|||
|
|
<a class="reference internal" href="#struct.Struct" title="struct.Struct"><code class="xref py py-class docutils literal notranslate"><span class="pre">Struct</span></code></a> and the module-level functions are cached, so programs
|
|||
|
|
that use only a few format strings needn’t worry about reusing a single
|
|||
|
|
<a class="reference internal" href="#struct.Struct" title="struct.Struct"><code class="xref py py-class docutils literal notranslate"><span class="pre">Struct</span></code></a> instance.</p>
|
|||
|
|
</div>
|
|||
|
|
<p>Compiled Struct objects support the following methods and attributes:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="struct.Struct.pack">
|
|||
|
|
<code class="descname">pack</code><span class="sig-paren">(</span><em>v1</em>, <em>v2</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct.pack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Identical to the <a class="reference internal" href="#struct.pack" title="struct.pack"><code class="xref py py-func docutils literal notranslate"><span class="pre">pack()</span></code></a> function, using the compiled format.
|
|||
|
|
(<code class="docutils literal notranslate"><span class="pre">len(result)</span></code> will equal <a class="reference internal" href="#struct.Struct.size" title="struct.Struct.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a>.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="struct.Struct.pack_into">
|
|||
|
|
<code class="descname">pack_into</code><span class="sig-paren">(</span><em>buffer</em>, <em>offset</em>, <em>v1</em>, <em>v2</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct.pack_into" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Identical to the <a class="reference internal" href="#struct.pack_into" title="struct.pack_into"><code class="xref py py-func docutils literal notranslate"><span class="pre">pack_into()</span></code></a> function, using the compiled format.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="struct.Struct.unpack">
|
|||
|
|
<code class="descname">unpack</code><span class="sig-paren">(</span><em>buffer</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct.unpack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Identical to the <a class="reference internal" href="#struct.unpack" title="struct.unpack"><code class="xref py py-func docutils literal notranslate"><span class="pre">unpack()</span></code></a> function, using the compiled format.
|
|||
|
|
The buffer’s size in bytes must equal <a class="reference internal" href="#struct.Struct.size" title="struct.Struct.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="struct.Struct.unpack_from">
|
|||
|
|
<code class="descname">unpack_from</code><span class="sig-paren">(</span><em>buffer</em>, <em>offset=0</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct.unpack_from" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Identical to the <a class="reference internal" href="#struct.unpack_from" title="struct.unpack_from"><code class="xref py py-func docutils literal notranslate"><span class="pre">unpack_from()</span></code></a> function, using the compiled format.
|
|||
|
|
The buffer’s size in bytes, minus <em>offset</em>, must be at least
|
|||
|
|
<a class="reference internal" href="#struct.Struct.size" title="struct.Struct.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="struct.Struct.iter_unpack">
|
|||
|
|
<code class="descname">iter_unpack</code><span class="sig-paren">(</span><em>buffer</em><span class="sig-paren">)</span><a class="headerlink" href="#struct.Struct.iter_unpack" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Identical to the <a class="reference internal" href="#struct.iter_unpack" title="struct.iter_unpack"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter_unpack()</span></code></a> function, using the compiled format.
|
|||
|
|
The buffer’s size in bytes must be a multiple of <a class="reference internal" href="#struct.Struct.size" title="struct.Struct.size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">size</span></code></a>.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="struct.Struct.format">
|
|||
|
|
<code class="descname">format</code><a class="headerlink" href="#struct.Struct.format" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The format string used to construct this Struct object.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.7: </span>The format string type is now <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> instead of <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="struct.Struct.size">
|
|||
|
|
<code class="descname">size</code><a class="headerlink" href="#struct.Struct.size" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The calculated size of the struct (and hence of the bytes object produced
|
|||
|
|
by the <a class="reference internal" href="#struct.pack" title="struct.pack"><code class="xref py py-meth docutils literal notranslate"><span class="pre">pack()</span></code></a> method) corresponding to <a class="reference internal" href="functions.html#format" title="format"><code class="xref py py-attr docutils literal notranslate"><span class="pre">format</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code> — Interpret bytes as packed binary data</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#functions-and-exceptions">Functions and Exceptions</a></li>
|
|||
|
|
<li><a class="reference internal" href="#format-strings">Format Strings</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#byte-order-size-and-alignment">Byte Order, Size, and Alignment</a></li>
|
|||
|
|
<li><a class="reference internal" href="#format-characters">Format Characters</a></li>
|
|||
|
|
<li><a class="reference internal" href="#examples">Examples</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#classes">Classes</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="binary.html"
|
|||
|
|
title="previous chapter">Binary Data Services</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="codecs.html"
|
|||
|
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">codecs</span></code> — Codec registry and base classes</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/struct.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="codecs.html" title="codecs — Codec registry and base classes"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="binary.html" title="Binary Data Services"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="binary.html" >Binary Data Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|