diff options
Diffstat (limited to 'devdocs/elisp/bindat-functions.html')
| -rw-r--r-- | devdocs/elisp/bindat-functions.html | 26 |
1 files changed, 26 insertions, 0 deletions
diff --git a/devdocs/elisp/bindat-functions.html b/devdocs/elisp/bindat-functions.html new file mode 100644 index 00000000..5b6f1924 --- /dev/null +++ b/devdocs/elisp/bindat-functions.html @@ -0,0 +1,26 @@ + <h4 class="subsection">Functions to Unpack and Pack Bytes</h4> <p>In the following documentation, <var>type</var> refers to a Bindat type value as returned from <code>bindat-type</code>, <var>raw</var> to a byte array, and <var>struct</var> to an alist representing unpacked field data. </p> <dl> <dt id="bindat-unpack">Function: <strong>bindat-unpack</strong> <em>type raw &optional idx</em> +</dt> <dd> +<p>This function unpacks data from the unibyte string or byte array <var>raw</var> according to <var>type</var>. Normally, this starts unpacking at the beginning of the byte array, but if <var>idx</var> is non-<code>nil</code>, it specifies a zero-based starting position to use instead. </p> <p>The value is an alist or nested alist in which each element describes one unpacked field. </p> +</dd> +</dl> <dl> <dt id="bindat-get-field">Function: <strong>bindat-get-field</strong> <em>struct &rest name</em> +</dt> <dd> +<p>This function selects a field’s data from the nested alist <var>struct</var>. Usually <var>struct</var> was returned by <code>bindat-unpack</code>. If <var>name</var> corresponds to just one argument, that means to extract a top-level field value. Multiple <var>name</var> arguments specify repeated lookup of sub-structures. An integer <var>name</var> acts as an array index. </p> <p>For example, <code><span class="nolinebreak">(bindat-get-field</span> <var>struct</var> a b 2 c)</code> means to find field <code>c</code> in the third element of subfield <code>b</code> of field <code>a</code>. (This corresponds to <code><var>struct</var>.a.b[2].c</code> in the C programming language syntax.) </p> +</dd> +</dl> <p>Although packing and unpacking operations change the organization of data (in memory), they preserve the data’s <em>total length</em>, which is the sum of all the fields’ lengths, in bytes. This value is not generally inherent in either the specification or alist alone; instead, both pieces of information contribute to its calculation. Likewise, the length of a string or array being unpacked may be longer than the data’s total length as described by the specification. </p> <dl> <dt id="bindat-length">Function: <strong>bindat-length</strong> <em>type struct</em> +</dt> <dd><p>This function returns the total length of the data in <var>struct</var>, according to <var>type</var>. </p></dd> +</dl> <dl> <dt id="bindat-pack">Function: <strong>bindat-pack</strong> <em>type struct &optional raw idx</em> +</dt> <dd> +<p>This function returns a byte array packed according to <var>type</var> from the data in the alist <var>struct</var>. It normally creates and fills a new byte array starting at the beginning. However, if <var>raw</var> is non-<code>nil</code>, it specifies a pre-allocated unibyte string or vector to pack into. If <var>idx</var> is non-<code>nil</code>, it specifies the starting offset for packing into <var>raw</var>. </p> <p>When pre-allocating, you should make sure <code>(length <var>raw</var>)</code> meets or exceeds the total length to avoid an out-of-range error. </p> +</dd> +</dl> <dl> <dt id="bindat-ip-to-string">Function: <strong>bindat-ip-to-string</strong> <em>ip</em> +</dt> <dd> +<p>Convert the Internet address vector <var>ip</var> to a string in the usual dotted notation. </p> <div class="example"> <pre class="example">(bindat-ip-to-string [127 0 0 1]) + ⇒ "127.0.0.1" +</pre> +</div> </dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Bindat-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Bindat-Functions.html</a> + </p> +</div> |