Sophie: rust-doc-1.28.0-1.mga6 armv7hl

rust-doc-1.28.0-1.mga6.armv7hl.rpm

<!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="API documentation for the Rust `ffi` mod in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, ffi"><title>std::ffi - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script src="../../storage.js"></script><link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico"></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">&#9776;</div><a href='../../std/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Module ffi</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li></ul></div><p class='location'><a href='../index.html'>std</a></p><script>window.sidebarCurrent = {name: 'ffi', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><input class="search-input" name="search" autocomplete="off" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>std</a>::<wbr><a class="mod" href=''>ffi</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>&#x2212;</span>]</a></span><a class='srclink' href='../../src/std/ffi/mod.rs.html#11-175' title='goto source code'>[src]</a></span></h1><div class='docblock'><p>Utilities related to FFI bindings.</p>
<p>This module provides utilities to handle data across non-Rust
interfaces, like other programming languages and the underlying
operating system. It is mainly of use for FFI (Foreign Function
Interface) bindings and code that needs to exchange C-like strings
with other languages.</p>
<h1 id="overview" class="section-header"><a href="#overview">Overview</a></h1>
<p>Rust represents owned strings with the <a href="../string/struct.String.html"><code>String</code></a> type, and
borrowed slices of strings with the <a href="../primitive.str.html"><code>str</code></a> primitive. Both are
always in UTF-8 encoding, and may contain nul bytes in the middle,
i.e. if you look at the bytes that make up the string, there may
be a <code>\0</code> among them. Both <code>String</code> and <code>str</code> store their length
explicitly; there are no nul terminators at the end of strings
like in C.</p>
<p>C strings are different from Rust strings:</p>
<ul>
<li>
<p><strong>Encodings</strong> - Rust strings are UTF-8, but C strings may use
other encodings. If you are using a string from C, you should
check its encoding explicitly, rather than just assuming that it
is UTF-8 like you can do in Rust.</p>
</li>
<li>
<p><strong>Character size</strong> - C strings may use <code>char</code> or <code>wchar_t</code>-sized
characters; please <strong>note</strong> that C's <code>char</code> is different from Rust's.
The C standard leaves the actual sizes of those types open to
interpretation, but defines different APIs for strings made up of
each character type. Rust strings are always UTF-8, so different
Unicode characters will be encoded in a variable number of bytes
each. The Rust type <a href="../primitive.char.html"><code>char</code></a> represents a '<a href="http://www.unicode.org/glossary/#unicode_scalar_value">Unicode scalar
value</a>', which is similar to, but not the same as, a '<a href="http://www.unicode.org/glossary/#code_point">Unicode
code point</a>'.</p>
</li>
<li>
<p><strong>Nul terminators and implicit string lengths</strong> - Often, C
strings are nul-terminated, i.e. they have a <code>\0</code> character at the
end. The length of a string buffer is not stored, but has to be
calculated; to compute the length of a string, C code must
manually call a function like <code>strlen()</code> for <code>char</code>-based strings,
or <code>wcslen()</code> for <code>wchar_t</code>-based ones. Those functions return
the number of characters in the string excluding the nul
terminator, so the buffer length is really <code>len+1</code> characters.
Rust strings don't have a nul terminator; their length is always
stored and does not need to be calculated. While in Rust
accessing a string's length is a O(1) operation (because the
length is stored); in C it is an O(length) operation because the
length needs to be computed by scanning the string for the nul
terminator.</p>
</li>
<li>
<p><strong>Internal nul characters</strong> - When C strings have a nul
terminator character, this usually means that they cannot have nul
characters in the middle — a nul character would essentially
truncate the string. Rust strings <em>can</em> have nul characters in
the middle, because nul does not have to mark the end of the
string in Rust.</p>
</li>
</ul>
<h1 id="representations-of-non-rust-strings" class="section-header"><a href="#representations-of-non-rust-strings">Representations of non-Rust strings</a></h1>
<p><a href="struct.CString.html"><code>CString</code></a> and <a href="struct.CStr.html"><code>CStr</code></a> are useful when you need to transfer
UTF-8 strings to and from languages with a C ABI, like Python.</p>
<ul>
<li>
<p><strong>From Rust to C:</strong> <a href="struct.CString.html"><code>CString</code></a> represents an owned, C-friendly
string: it is nul-terminated, and has no internal nul characters.
Rust code can create a <code>CString</code> out of a normal string (provided
that the string doesn't have nul characters in the middle), and
then use a variety of methods to obtain a raw <code>*mut u8</code> that can
then be passed as an argument to functions which use the C
conventions for strings.</p>
</li>
<li>
<p><strong>From C to Rust:</strong> <a href="struct.CStr.html"><code>CStr</code></a> represents a borrowed C string; it
is what you would use to wrap a raw <code>*const u8</code> that you got from
a C function. A <code>CStr</code> is guaranteed to be a nul-terminated array
of bytes. Once you have a <code>CStr</code>, you can convert it to a Rust
<code>&amp;str</code> if it's valid UTF-8, or lossily convert it by adding
replacement characters.</p>
</li>
</ul>
<p><a href="struct.OsString.html"><code>OsString</code></a> and <a href="struct.OsStr.html"><code>OsStr</code></a> are useful when you need to transfer
strings to and from the operating system itself, or when capturing
the output of external commands. Conversions between <code>OsString</code>,
<code>OsStr</code> and Rust strings work similarly to those for <a href="struct.CString.html"><code>CString</code></a>
and <a href="struct.CStr.html"><code>CStr</code></a>.</p>
<ul>
<li>
<p><a href="struct.OsString.html"><code>OsString</code></a> represents an owned string in whatever
representation the operating system prefers. In the Rust standard
library, various APIs that transfer strings to/from the operating
system use <code>OsString</code> instead of plain strings. For example,
<a href="../env/fn.var_os.html"><code>env::var_os()</code></a> is used to query environment variables; it
returns an <code>Option&lt;OsString&gt;</code>. If the environment variable exists
you will get a <code>Some(os_string)</code>, which you can <em>then</em> try to
convert to a Rust string. This yields a <a href="../result/enum.Result.html"><code>Result&lt;&gt;</code></a>, so that
your code can detect errors in case the environment variable did
not in fact contain valid Unicode data.</p>
</li>
<li>
<p><a href="struct.OsStr.html"><code>OsStr</code></a> represents a borrowed reference to a string in a
format that can be passed to the operating system. It can be
converted into an UTF-8 Rust string slice in a similar way to
<code>OsString</code>.</p>
</li>
</ul>
<h1 id="conversions" class="section-header"><a href="#conversions">Conversions</a></h1><h2 id="on-unix" class="section-header"><a href="#on-unix">On Unix</a></h2>
<p>On Unix, <a href="struct.OsStr.html"><code>OsStr</code></a> implements the
<code>std::os::unix:ffi::</code><a href="../os/unix/ffi/trait.OsStrExt.html"><code>OsStrExt</code></a> trait, which
augments it with two methods, <a href="../os/unix/ffi/trait.OsStrExt.html#tymethod.from_bytes"><code>from_bytes</code></a> and <a href="../os/unix/ffi/trait.OsStrExt.html#tymethod.as_bytes"><code>as_bytes</code></a>.
These do inexpensive conversions from and to UTF-8 byte slices.</p>
<p>Additionally, on Unix <a href="struct.OsString.html"><code>OsString</code></a> implements the
<code>std::os::unix:ffi::</code><a href="../os/unix/ffi/trait.OsStringExt.html"><code>OsStringExt</code></a> trait,
which provides <a href="../os/unix/ffi/trait.OsStringExt.html#tymethod.from_vec"><code>from_vec</code></a> and <a href="../os/unix/ffi/trait.OsStringExt.html#tymethod.into_vec"><code>into_vec</code></a> methods that consume
their arguments, and take or produce vectors of <a href="../primitive.u8.html"><code>u8</code></a>.</p>
<h2 id="on-windows" class="section-header"><a href="#on-windows">On Windows</a></h2>
<p>On Windows, <a href="struct.OsStr.html"><code>OsStr</code></a> implements the
<code>std::os::windows::ffi::</code><a href="../os/windows/ffi/trait.OsStrExt.html"><code>OsStrExt</code></a> trait,
which provides an <a href="../os/windows/ffi/trait.OsStrExt.html#tymethod.encode_wide"><code>encode_wide</code></a> method. This provides an
iterator that can be <a href="../iter/trait.Iterator.html#method.collect"><code>collect</code></a>ed into a vector of <a href="../primitive.u16.html"><code>u16</code></a>.</p>
<p>Additionally, on Windows <a href="struct.OsString.html"><code>OsString</code></a> implements the
<code>std::os::windows:ffi::</code><a href="../os/windows/ffi/trait.OsStringExt.html"><code>OsStringExt</code></a>
trait, which provides a <a href="../os/windows/ffi/trait.OsStringExt.html#tymethod.from_wide"><code>from_wide</code></a> method. The result of this
method is an <code>OsString</code> which can be round-tripped to a Windows
string losslessly.</p>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.CStr.html"
                                  title='struct std::ffi::CStr'>CStr</a></td>
                           <td class='docblock-short'>
                                <p>Representation of a borrowed C string.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.CString.html"
                                  title='struct std::ffi::CString'>CString</a></td>
                           <td class='docblock-short'>
                                <p>A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the
middle.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.FromBytesWithNulError.html"
                                  title='struct std::ffi::FromBytesWithNulError'>FromBytesWithNulError</a></td>
                           <td class='docblock-short'>
                                <p>An error indicating that a nul byte was not in the expected position.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.IntoStringError.html"
                                  title='struct std::ffi::IntoStringError'>IntoStringError</a></td>
                           <td class='docblock-short'>
                                <p>An error indicating invalid UTF-8 when converting a <a href="struct.CString.html"><code>CString</code></a> into a <a href="../string/struct.String.html"><code>String</code></a>.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.NulError.html"
                                  title='struct std::ffi::NulError'>NulError</a></td>
                           <td class='docblock-short'>
                                <p>An error indicating that an interior nul byte was found.</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.OsStr.html"
                                  title='struct std::ffi::OsStr'>OsStr</a></td>
                           <td class='docblock-short'>
                                <p>Borrowed reference to an OS string (see <a href="struct.OsString.html"><code>OsString</code></a>).</p>

                           </td>
                       </tr>
                       <tr class=' module-item'>
                           <td><a class="struct" href="struct.OsString.html"
                                  title='struct std::ffi::OsString'>OsString</a></td>
                           <td class='docblock-short'>
                                <p>A type that can represent owned, mutable platform-native strings, but is
cheaply inter-convertible with Rust strings.</p>

                           </td>
                       </tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>&#9166;</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g. <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g. <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g. <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "std";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html>