Utilities related to FFI bindings.

This module provides utilities to handle data across non-Rustinterfaces, like other programming languages and the underlyingoperating system. It is mainly of use for FFI (Foreign FunctionInterface) bindings and code that needs to exchange C-like stringswith other languages.

§Overview

Rust represents owned strings with theString type, andborrowed slices of strings with thestr primitive. Both arealways 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 maybe a\0 among them. BothString andstr store their lengthexplicitly; there are no nul terminators at the end of stringslike in C.

C strings are different from Rust strings:

• Encodings - Rust strings are UTF-8, but C strings may useother encodings. If you are using a string from C, you shouldcheck its encoding explicitly, rather than just assuming that itis UTF-8 like you can do in Rust.

• Character size - C strings may usechar orwchar_t-sizedcharacters; pleasenote that C’schar is different from Rust’s.The C standard leaves the actual sizes of those types open tointerpretation, but defines different APIs for strings made up ofeach character type. Rust strings are always UTF-8, so differentUnicode characters will be encoded in a variable number of byteseach. The Rust typechar represents a ‘Unicode scalarvalue’, which is similar to, but not the same as, a ‘Unicodecode point’.

• Nul terminators and implicit string lengths - Often, Cstrings are nul-terminated, i.e., they have a\0 character at theend. The length of a string buffer is not stored, but has to becalculated; to compute the length of a string, C code mustmanually call a function likestrlen() forchar-based strings,orwcslen() forwchar_t-based ones. Those functions returnthe number of characters in the string excluding the nulterminator, so the buffer length is reallylen+1 characters.Rust strings don’t have a nul terminator; their length is alwaysstored and does not need to be calculated. While in Rustaccessing a string’s length is anO(1) operation (because thelength is stored); in C it is anO(n) operation because thelength needs to be computed by scanning the string for the nulterminator.

• Internal nul characters - When C strings have a nulterminator character, this usually means that they cannot have nulcharacters in the middle — a nul character would essentiallytruncate the string. Rust stringscan have nul characters inthe middle, because nul does not have to mark the end of thestring in Rust.

§Representations of non-Rust strings

CString andCStr are useful when you need to transferUTF-8 strings to and from languages with a C ABI, like Python.

• From Rust to C:CString represents an owned, C-friendlystring: it is nul-terminated, and has no internal nul characters.Rust code can create aCString out of a normal string (providedthat the string doesn’t have nul characters in the middle), andthen use a variety of methods to obtain a raw*mutu8 that canthen be passed as an argument to functions which use the Cconventions for strings.

• From C to Rust:CStr represents a borrowed C string; itis what you would use to wrap a raw*constu8 that you got froma C function. ACStr is guaranteed to be a nul-terminated arrayof bytes. Once you have aCStr, you can convert it to a Rust&str if it’s valid UTF-8, or lossily convert it by addingreplacement characters.

OsString andOsStr are useful when you need to transferstrings to and from the operating system itself, or when capturingthe output of external commands. Conversions betweenOsString,OsStr and Rust strings work similarly to those forCStringandCStr.

• OsString losslessly represents an owned platform string. However, thisrepresentation is not necessarily in a form native to the platform.In the Rust standard library, various APIs that transfer strings to/from the operatingsystem useOsString instead of plain strings. For example,env::var_os() is used to query environment variables; itreturns anOption<OsString>. If the environment variableexists you will get aSome(os_string), which you canthen try to convert to a Rust string. This yields aResult, so thatyour code can detect errors in case the environment variable didnot in fact contain valid Unicode data.

• OsStr losslessly represents a borrowed reference to a platform string.However, this representation is not necessarily in a form native to the platform.It can be converted into a UTF-8 Rust string slice in a similar way toOsString.

§Conversions

§On Unix

On Unix,OsStr implements thestd::os::unix::ffi::OsStrExt trait, whichaugments it with two methods,from_bytes andas_bytes.These do inexpensive conversions from and to byte slices.

Additionally, on UnixOsString implements thestd::os::unix::ffi::OsStringExt trait,which providesfrom_vec andinto_vec methods that consumetheir arguments, and take or produce vectors ofu8.

§On Windows

AnOsStr can be losslessly converted to a native Windows string. Anda native Windows string can be losslessly converted to anOsString.

On Windows,OsStr implements thestd::os::windows::ffi::OsStrExt trait,which provides anencode_wide method. This provides aniterator that can becollected into a vector ofu16. After a nulcharacters is appended, this is the same as a native Windows string.

Additionally, on WindowsOsString implements thestd::os::windows:ffi::OsStringExttrait, which provides afrom_wide method to convert a native Windowsstring (without the terminating nul character) to anOsString.

§Other platforms

Many other platforms provide their own extension traits in astd::os::*::ffi module.

§On all platforms

On all platforms,OsStr consists of a sequence of bytes that is encoded as a superset ofUTF-8; seeOsString for more details on its encoding on different platforms.

For limited, inexpensive conversions from and to bytes, seeOsStr::as_encoded_bytes andOsStr::from_encoded_bytes_unchecked.

For basic string processing, seeOsStr::slice_encoded_bytes.