eso/lib.rs
1// Copyright (c) 2021 Sebastien Braun
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at http://mozilla.org/MPL/2.0/.
6
7//! [](https://crates.io/crates/eso)
8//! [](https://docs.rs/eso)
9//! [](https://github.com/braunse/eso/issues)
10//! [](https://github.com/braunse/eso/pulls)
11//! [](https://github.com/braunse/eso/commits)
12//! 
13//! 
14//!
15//! Type-level machinery for building [`Cow`](std::borrow::Cow)-like
16//! types while avoiding unnecessary copies of `'static' or
17//! other shareable references.
18//!
19//! The main feature of this crate is the [`Eso`] type, which tracks
20//! whether the contained value is ephemeral (i.e. borrowed with any
21//! lifetime), static/shared (i.e. can be held on to indefinitely) or
22//! owned (i.e. can be moved and may be mutably accessed).
23//!
24//! In addition, it also statically tracks which of these is *possible*
25//! at any given point in the code by encoding the information on a
26//! type level using the definitions in the [`maybe`] module.
27//!
28//! While [`Eso`] is perfectly happy working with normal Rust references,
29//! it also provides an abstraction to support a more generalized notion
30//! of reference. The definitions in the [`borrow`] module describe
31//! the different operations that are required to use generalized
32//! references.
33//!
34//! ## Feature flags
35//!
36//! ### `allow-unsafe`: Allow usage of `unsafe` Rust
37//!
38//! This feature is active by default.
39//!
40//! `Eso` contains two usages of `unsafe`, which make the [`No`](crate::maybe::No)
41//! type implement [`Send`] and [`Sync`] irrespective of its type
42//! parameter.
43//! This should be safe since no value of the [`No`] type can ever exist
44//! and it therefore cannot participate in any races or memory safety violations.
45//!
46//! Nonetheless, if you want to disallow usage of `unsafe`,
47//! turn off the default features in your `Cargo.toml`:
48//!
49//! ```toml
50//! [dependencies.eso]
51//! version = "0.0.2"
52//! default-features = false
53//! ```
54
55#![deny(
56 missing_docs,
57 missing_debug_implementations,
58 missing_copy_implementations,
59 trivial_casts,
60 trivial_numeric_casts,
61 unsafe_code,
62 unstable_features,
63 unused_import_braces,
64 unused_qualifications
65)]
66#![warn(rustdoc::broken_intra_doc_links)]
67
68#[cfg_attr(feature = "unstable-doc-cfg", feature(doc_cfg))]
69pub mod borrow;
70pub mod eso;
71pub mod maybe;
72pub mod shorthand;
73pub mod unify;
74
75#[doc(inline)]
76pub use crate::eso::Eso;
77#[doc(inline)]
78pub use crate::maybe::{An, No};