      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178

    //! Utilities related to FFI bindings.
    //!
    //! 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.
    //!
    //! # Overview
    //!
    //! Rust represents owned strings with the [`String`] type, and
    //! borrowed slices of strings with the [`str`] 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 `\0` among them. Both `String` and `str` store their length
    //! explicitly; there are no nul terminators at the end of strings
    //! like in C.
    //!
    //! C strings are different from Rust strings:
    //!
    //! * **Encodings** - 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.
    //!
    //! * **Character size** - C strings may use `char` or `wchar_t`-sized
    //! characters; please **note** that C's `char` 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 [`char`] represents a '[Unicode scalar
    //! value]', which is similar to, but not the same as, a '[Unicode
    //! code point]'.
    //!
    //! * **Nul terminators and implicit string lengths** - Often, C
    //! strings are nul-terminated, i.e., they have a `\0` 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 `strlen()` for `char`-based strings,
    //! or `wcslen()` for `wchar_t`-based ones. Those functions return
    //! the number of characters in the string excluding the nul
    //! terminator, so the buffer length is really `len+1` 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.
    //!
    //! * **Internal nul characters** - 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 *can* have nul characters in
    //! the middle, because nul does not have to mark the end of the
    //! string in Rust.
    //!
    //! # Representations of non-Rust strings
    //!
    //! [`CString`] and [`CStr`] are useful when you need to transfer
    //! UTF-8 strings to and from languages with a C ABI, like Python.
    //!
    //! * **From Rust to C:** [`CString`] represents an owned, C-friendly
    //! string: it is nul-terminated, and has no internal nul characters.
    //! Rust code can create a [`CString`] 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 `*mut `[`u8`] that can
    //! then be passed as an argument to functions which use the C
    //! conventions for strings.
    //!
    //! * **From C to Rust:** [`CStr`] represents a borrowed C string; it
    //! is what you would use to wrap a raw `*const `[`u8`] that you got from
    //! a C function. A [`CStr`] is guaranteed to be a nul-terminated array
    //! of bytes. Once you have a [`CStr`], you can convert it to a Rust
    //! [`&str`][`str`] if it's valid UTF-8, or lossily convert it by adding
    //! replacement characters.
    //!
    //! [`OsString`] and [`OsStr`] 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 [`OsString`],
    //! [`OsStr`] and Rust strings work similarly to those for [`CString`]
    //! and [`CStr`].
    //!
    //! * [`OsString`] 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 [`OsString`] instead of plain strings. For example,
    //! [`env::var_os()`] is used to query environment variables; it
    //! returns an [`Option`]`<`[`OsString`]`>`. If the environment variable
    //! exists you will get a [`Some`]`(os_string)`, which you can *then* try to
    //! convert to a Rust string. This yields a [`Result<>`], so that
    //! your code can detect errors in case the environment variable did
    //! not in fact contain valid Unicode data.
    //!
    //! * [`OsStr`] 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
    //! [`OsString`].
    //!
    //! # Conversions
    //!
    //! ## On Unix
    //!
    //! On Unix, [`OsStr`] implements the
    //! `std::os::unix::ffi::`[`OsStrExt`][unix.OsStrExt] trait, which
    //! augments it with two methods, [`from_bytes`] and [`as_bytes`].
    //! These do inexpensive conversions from and to UTF-8 byte slices.
    //!
    //! Additionally, on Unix [`OsString`] implements the
    //! `std::os::unix::ffi::`[`OsStringExt`][unix.OsStringExt] trait,
    //! which provides [`from_vec`] and [`into_vec`] methods that consume
    //! their arguments, and take or produce vectors of [`u8`].
    //!
    //! ## On Windows
    //!
    //! On Windows, [`OsStr`] implements the
    //! `std::os::windows::ffi::`[`OsStrExt`][windows.OsStrExt] trait,
    //! which provides an [`encode_wide`] method. This provides an
    //! iterator that can be [`collect`]ed into a vector of [`u16`].
    //!
    //! Additionally, on Windows [`OsString`] implements the
    //! `std::os::windows:ffi::`[`OsStringExt`][windows.OsStringExt]
    //! trait, which provides a [`from_wide`] method. The result of this
    //! method is an [`OsString`] which can be round-tripped to a Windows
    //! string losslessly.
    //!
    //! [`String`]: ../string/struct.String.html
    //! [`str`]: ../primitive.str.html
    //! [`char`]: ../primitive.char.html
    //! [`u8`]: ../primitive.u8.html
    //! [`u16`]: ../primitive.u16.html
    //! [Unicode scalar value]: http://www.unicode.org/glossary/#unicode_scalar_value
    //! [Unicode code point]: http://www.unicode.org/glossary/#code_point
    //! [`CString`]: struct.CString.html
    //! [`CStr`]: struct.CStr.html
    //! [`OsString`]: struct.OsString.html
    //! [`OsStr`]: struct.OsStr.html
    //! [`env::set_var()`]: ../env/fn.set_var.html
    //! [`env::var_os()`]: ../env/fn.var_os.html
    //! [`Result<>`]: ../result/enum.Result.html
    //! [unix.OsStringExt]: ../os/unix/ffi/trait.OsStringExt.html
    //! [`from_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.from_vec
    //! [`into_vec`]: ../os/unix/ffi/trait.OsStringExt.html#tymethod.into_vec
    //! [unix.OsStrExt]: ../os/unix/ffi/trait.OsStrExt.html
    //! [`from_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.from_bytes
    //! [`as_bytes`]: ../os/unix/ffi/trait.OsStrExt.html#tymethod.as_bytes
    //! [`OsStrExt`]: ../os/unix/ffi/trait.OsStrExt.html
    //! [windows.OsStrExt]: ../os/windows/ffi/trait.OsStrExt.html
    //! [`encode_wide`]: ../os/windows/ffi/trait.OsStrExt.html#tymethod.encode_wide
    //! [`collect`]: ../iter/trait.Iterator.html#method.collect
    //! [windows.OsStringExt]: ../os/windows/ffi/trait.OsStringExt.html
    //! [`from_wide`]: ../os/windows/ffi/trait.OsStringExt.html#tymethod.from_wide
    //! [`Option`]: ../option/enum.Option.html
    //! [`Some`]: ../option/enum.Option.html#variant.Some

    #![stable(feature = "rust1", since = "1.0.0")]

    #[stable(feature = "cstr_from_bytes", since = "1.10.0")]
    pub use self::c_str::FromBytesWithNulError;
    #[stable(feature = "rust1", since = "1.0.0")]
    pub use self::c_str::{CStr, CString, IntoStringError, NulError};

    #[stable(feature = "rust1", since = "1.0.0")]
    pub use self::os_str::{OsStr, OsString};

    #[stable(feature = "core_c_void", since = "1.30.0")]
    pub use core::ffi::c_void;

    #[unstable(
        feature = "c_variadic",
        reason = "the `c_variadic` feature has not been properly tested on \
                  all supported platforms",
        issue = "44930"
    )]
    pub use core::ffi::{VaList, VaListImpl};

    mod c_str;
    mod os_str;