From 701321eb098eb3bb2bc091adbae30ba0305a3888 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Wed, 23 Oct 2024 14:41:52 -0400 Subject: [PATCH] Start sample stdlib documentation --- src/SUMMARY.md | 4 + src/core.md | 16 ++++ src/core/ffi.md | 244 ++++++++++++++++++++++++++++++++++++++++++++++++ src/stdlib.md | 1 + 4 files changed, 265 insertions(+) create mode 100644 src/core.md create mode 100644 src/core/ffi.md create mode 100644 src/stdlib.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 91f343b8d..91f3e24a3 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -129,6 +129,10 @@ - [The Rust runtime](runtime.md) +- [Standard Library](stdlib.md) + - [core](core.md) + - [core::ffi](core/ffi.md) + - [Appendices](appendices.md) - [Macro Follow-Set Ambiguity Formal Specification](macro-ambiguity.md) - [Influences](influences.md) diff --git a/src/core.md b/src/core.md new file mode 100644 index 000000000..3d9e806ae --- /dev/null +++ b/src/core.md @@ -0,0 +1,16 @@ +# core + +r[library.core] + +r[library.core.intro] +The `core` library is the most fundamental library in the Rust language. Every crate (other than itself) depends on it. `core` defines fundamental operations and language item types, as well as (most) functions on primitive types. + +## Synopsis + +r[library.core.synopsis] +```rust + +pub mod ffi; +pub mod marker; + +``` \ No newline at end of file diff --git a/src/core/ffi.md b/src/core/ffi.md new file mode 100644 index 000000000..80f10ee7e --- /dev/null +++ b/src/core/ffi.md @@ -0,0 +1,244 @@ +# Module core::ffi + +r[core.ffi] + + +## Module core::ffi Synopsis + +r[core.ffi.synopsis] + + +```rust,ignore + +pub struct FromBytesUntilNulError(/*private fields*/); +pub struct FromBytesWithNulError(/*private fields*/); +pub struct CStr{/*private fields*/} + +pub enum c_void{} + +pub type c_char = /* see below */; +pub type c_double = /* see below */; +pub type c_float = /* see below */; +pub type c_int = /* see below */; +pub type c_long = /*see below*/; +pub type c_longlong = /*see below*/; +pub type c_schar = /*see below*/; +pub type c_short = /*see below*/; +pub type c_uchar = /*see below*/; +pub type c_ulong = /*see below*/; +pub type c_ulonglong = /*see below*/; +pub type c_ushort = /* see below */; +``` + +## CStr + +r[core.ffi.cstr] + +r[core.ffi.cstr.intro] +A `CStr` is a slice of bytes that contains a nul-terminated string of arbitrary non-nul bytes. + +r[core.ffi.cstr.literal] +A literal of the form `c""` has type `&'static core::ffi::CStr`. + +r[core.ffi.cstr.sized] +`CStr` is an unsized type. + +### `CStr::from_ptr` + +r[core.ffi.cstr.from_ptr] + +r[core.ffi.cstr.from_ptr.def] + +```rust,ignore +impl CStr{ + pub const unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr; +} +``` + +r[core.ffi.cstr.from_ptr.intro] +The `CStr::from_ptr` can be used to `unsafe`ly construct a `CStr` from a pointer to a nul-terminated C string. + +r[core.ffi.cstr.from_ptr.precondition] +The behavior of this function is undefined unless: +* There exists a value `i` of type `usize`, + such that the range `[ptr, ptr.add(i)]` is a range valid for reads, and `ptr.add(i).read()==0`, +* `i < (isize::MAX as usize)`, + +> [!WARNING] +> In addition, to safely use the result, the callee must ensure that the validity of `ptr` remains for the duration of `'a`, +> and that the bytes referred to be the `CStr` aren't modified for the duration of `'a`. + +r[core.ffi.cstr.from_ptr.postcondition] +The returned reference is a shared borrow derived from `ptr` which borrows `[ptr, ptr.add(i+1))` + +r[core.ffi.cstr.from_ptr.return] +The return value is a `&CStr` that starts at `ptr`, and for which `CStr::count_bytes` returns `i`. + +r[core.ffi.cstr.from_ptr.safety] +`CStr::from_ptr` is an `unsafe` function. + +r[core.ffi.cstr.from_ptr.const] +`CStr::from_ptr` is a `const` function. + +### `CStr::from_bytes_until_nul` + +r[core.ffi.cstr.from_bytes_until_nul] + +r[core.ffi.cstr.from_bytes_until_nul.def] + +```rust,ignore +impl CStr{ + pub const fn from_bytes_until_nul(bytes: &[u8]) -> Result<&CStr, FromBytesUntilNulError>; +} +``` + +r[core.ffi.cstr.from_bytes_until_nul.intro] +Constructs a `CStr` slice over `bytes`, up to the first instance of a `0` byte, terminating the string. If no such terminator exists, an error is returned instead. + +r[core.ffi.cstr.from_bytes_until_nul.return] +If there exists some index `i` of type `usize`, such that `i < bytes.len()` and `bytes[i] == 0`, returns a `CStr` borrowed from `bytes` starting from the first index, +and such that `CStr::count_bytes` returns `i` . If no such `i` exists, returns a `FromBytesUntilNulError` that indicates the failure. + +> [!NOTE] +> If there is exactly one 0 byte in `bytes`, located at the last index of the slice, the returned slice is identical to the one returned by [`CStr::from_bytes_with_nul`][core.ffi.cstr.from_bytes_with_nul] + +### `CStr::from_bytes_with_nul` + +r[core.ffi.cstr.from_bytes_with_nul] + +r[core.ffi.cstr.from_bytes_with_nul.def] + +```rust,ignore +impl CStr{ + pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&CStr, FromBytesWithNulError>; +} +``` + +r[core.ffi.cstr.from_bytes_with_nul.intro] +Constructs a `CStr` slice over `bytes`, provided that exactly one `0` byte occurs at the very end of `bytes`. If the last byte of the string is not `0`, or a `0` byte occurs anywhere else in `bytes`, an error is returned instead. + +r[core.ffi.cstr.from_bytes_with_nul.return] +If there exists some index `i` of type `usize`, such that `i < bytes.len()` and `bytes[i] == 0`, then: +* If `i + 1 == bytes.len()`, returns a `CStr` borrowed from `bytes` starting from the first index, + and such that `CStr::count_bytes` returns `i`, +* Otherwise, or if no such index exists, returns a `FromBytesWithNullError` that indicates the failure. + +## C-compatible primitive types + +r[core.ffi.c-primitives] + +r[core.ffi.c-primitives.def] + +```rust +pub type c_char = /* see below */; +pub type c_double = /* see below */; +pub type c_float = /* see below */; +pub type c_int = /* see below */; +pub type c_long = /*see below*/; +pub type c_longlong = /*see below*/; +pub type c_schar = i8; +pub type c_short = /*see below*/; +pub type c_uchar = /*see below*/; +pub type c_ulong = /*see below*/; +pub type c_ulonglong = /*see below*/; +pub type c_ushort = u8; +``` + +r[core.ffi.c-primitives.intro] +The C-compatible primitive types are type aliases of primitive types, which are ABI compatible with the corresponding type in C on the current target. + +r[core.ffi.c-primitives.c_char] +The type alias `c_char` is a target dependent integer type with the same width and signedness as the `char` type in C. + +> [!NOTE] +> On every platform that can support Rust, this is either `u8` or `i8`. + +r[core.ffi.c-primitives.c_double] +The type alias `c_double` is a target dependent floating-point type with the same range and precision as the `double` type in C. + +> [!NOTE] +> On most platforms, this is `f64`. + +r[core.ffi.c-primitives.c_float] +The type alias `c_float` is a target dependent floating-point type with the same range and precision as the `float` type in C. + +> [!NOTE] +> On most platforms, this is `f32`. + +r[core.ffi.c-primitives.c_int] +The type alias `c_int` is a target dependent signed integer type with the same width as the `int` type in C. +The minimum width of this type is 16-bit, and it is at least as wide as the `c_short` alias. + +> [!NOTE] +> On most 32 and 64-bit platforms, this is `i32`, +> but it may be `i16` also on a 16-bit platform. + +r[core.ffi.c-primitives.c_long] +The type alias `c_long` is a target dependent signed integer type with the same width as the `long` type in C. +The minimum width of this type is 32-bit, and it is at least as wide as the `c_int` alias. + +> [!NOTE] +> The minimum width for this type is 32-bit. +> On most 64-bit platforms, this is `i64`. + +r[core.ffi.c-primitives.c_longlong] +The type alias `c_longlong` is a target dependent signed integer type with the same width as the `long long` type in C. +The minimum width of this type is 64-bit, and it is at least as wide as the `c_long` alias. + +> [!NOTE] +> This is almost always `i64`, but may be wider. + +r[core.ffi.c-primitives.c_schar] +The type alias `c_schar` is an alias of the type `i8`. + +> [!NOTE] +> On every platform that can support Rust, this is compatible with the C type `signed char` + +r[core.ffi.c-primitives.c_short] +The type alias `c_short` is a target depedent signed integer type with the same width as the `short` type in C. +The minimum width of this type is 16-bit. + +> [!NOTE] +> This is almost always `i16`. + +r[core.ffi.c-primitives.c_uchar] +The type alias `c_uchar` is an alias of the type `u8`. + +> [!NOTE] +> On every platform that can support Rust, this is compatible with the C type `unsigned char` + +r[core.ffi.c-primitives.unsigned] +The aliases `c_uint`, `c_ulong`, `c_ulonglong`, and `c_ushort` are all aliases of the unsigned counterpart of the same integer type as the corresponding signed alias. + +> [!NOTE] +> In particular, an alias `c_u`*`ty`* is `usize` if and only if `c_`*`ty`* is `isize`. +> In all other cases, they will be `uN` and `iN` respectively, where `N` is the appropriate width. + +r[core.ffi.c-primitives.traits] +Each type in this section implements the traits `Copy`, `Clone`, `Send`, `Sync`, `Debug`, and `Display`. The integer type aliases implement `LowerHex`, `UpperHex`, `Octal`, and `Binary`. `c_float` and `c_double` implement `LowerExp` and `UpperExp`. + +## c_void + +r[core.ffi.c_void] + +r[core.ffi.c_void.def] + +```rust,ignore +#[non_exhaustive] +pub enum c_void{} +``` + +r[core.ffi.c_void.intro] +The `c_void` type is an enum type such that `*const c_void` is compatible with the C type `const void*`. + +> [!NOTE] +> This is only true behind an indirection - `c_void` itself is not compatible with a function returning `void`. + +r[core.ffi.c_void.variants] +The `c_void` type cannot be constructed, and it cannot be exhaustively matched. + +> [!NOTE] +> The `c_void` type acts as though it has no variants. but cannot be matched like an empty enum. + +r[core.ffi.c_void.traits] +The `c_void` type implements the `Send`, `Sync`, and `Debug` traits. diff --git a/src/stdlib.md b/src/stdlib.md new file mode 100644 index 000000000..017d56cde --- /dev/null +++ b/src/stdlib.md @@ -0,0 +1 @@ +# Standard Library