stdext/
lib.rs

1//! Additional features for the Rust standard library.
2//!
3//! ## Description
4//!
5//! This crate contains enhancements to the Rust standard library types, useful for
6//! broad audience, but not yet implemented (or stabilized) in `std`.
7//!
8//! Crate is designed to be lightweight (no external dependencies!) and provide essential
9//! functionality which possible can get to the `std` some day.
10//!
11//! ## Extension traits
12//!
13//! All the new functionality the stanard library is added using extension traits.
14//!
15//! Below you can find the table of all the extension traits introduced by this crate:
16//!
17//! | `std` structure | extension traits
18//! | --- | ---
19//! | [`Vec`] | [`VecExt`] and [`VecExtClone`]
20//! | [`&str`] | [`StrExt`]
21//! | [`Option`] | [`OptionExt`]
22//! | [`Result`] | [`ResultExt`]
23//! | [`Duration`] | [`DurationExt`]
24//! | [`RwLock`] | [`RwLockExt`]
25//! | [`Mutex`] | [`MutexExt`]
26//! | [`f32`] and [`f64`] | [`FloatConvert`]
27//!
28//! [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
29//! [`&str`]: https://doc.rust-lang.org/std/primitive.str.html
30//! [`Option`]: https://doc.rust-lang.org/std/option/enum.Option.html
31//! [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
32//! [`Duration`]: https://doc.rust-lang.org/std/time/struct.Duration.html
33//! [`RwLock`]: https://doc.rust-lang.org/std/sync/struct.RwLock.html
34//! [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html
35//!
36//! [`VecExt`]: vec/trait.VecExt.html
37//! [`VecExtClone`]: vec/trait.VecExtClone.html
38//! [`StrExt`]: str/trait.StrExt.html
39//! [`OptionExt`]: option/trait.OptionExt.html
40//! [`ResultExt`]: result/trait.ResultExt.html
41//! [`DurationExt`]: duration/trait.DurationExt.html
42//! [`RwLockExt`]: sync/rw_lock/trait.RwLockExt.html
43//! [`MutexExt`]: sync/mutex/trait.MutexExt.html
44//! [`FloatConvert`]: num/float_convert/trait.FloatConvert.html
45//!
46//! ## Integer super-trait
47//!
48//! While all built-in integer types have mostly the same interface, it's not backed by any trait,
49//! which makes it impossible to write a function that will accept any built-in integer.
50//!
51//! [`Integer`] trait solves that problem by reflecting the common interface of all the built-in integers.
52//!
53//! [`Integer`]: num/integer/trait.Integer.html
54//!
55//! ## Macros
56//!
57//! Another group of extensions in `stdext` is new macros:
58//!
59//! - [`compile_warning`] for spawning a user-defined compilation warnings.
60//! - [`function_name`] for getting an enclosing function name.
61//! - [`debug_name`] for getting a helpful string for debug.
62//!
63//! [`compile_warning`]: ./macro.compile_warning.html
64//! [`function_name`]: ./macro.function_name.html
65//! [`debug_name`]: ./macro.debug_name.html
66//!
67//! ## Highlights
68//!
69//! - Convenient builder methods for **`Duration`**:
70//!   
71//!   ```rust
72//!   use std::time::Duration;
73//!   use stdext::prelude::*;
74//!
75//!   let duration = Duration::from_minutes(1).add_secs(5).add_micros(100);
76//!   assert_eq!(duration, Duration::new(65, 100_000));
77//!   ```
78//!
79//! - Panicking version for **`RwLock::read`**, **`RwLock::write`** and **`Mutex::lock`** (for
80//!   fellows who don't really handle the lock poisoning):
81//!
82//!   ```rust
83//!   use std::sync::{Arc, RwLock};
84//!   use stdext::prelude::*;
85//!   
86//!   let lock = Arc::new(RwLock::new(1));
87//!   {
88//!       let mut n = lock.force_write(); // Instead of `.write().unwrap()`.
89//!       *n = 2;
90//!   }
91//!   let n = lock.force_read();
92//!   assert_eq!(*n, 2);
93//!   ```
94//!   
95//! - **`Result::combine`** and **`Option::combine`** to zip pairs of objects:
96//!   
97//!   ```rust
98//!   use stdext::prelude::*;
99//!   
100//!   let x = Some(1);
101//!   let y = Some("hi");
102//!   let z = None::<u8>;
103//!   
104//!   assert_eq!(x.combine(y), Some((1, "hi")));
105//!   assert_eq!(x.combine(z), None);
106//!
107//!   let x = Ok(1);
108//!   let y = Ok("hi");
109//!   let z: Result<i32, &str> = Err("error");
110//!   let z2: Result<i32, &str> = Err("other_error");
111//!
112//!   assert_eq!(x.combine(y), Ok((1, "hi")));
113//!   assert_eq!(x.combine(z), Err("error"));
114//!   assert_eq!(z.combine(z2), Err("error"));
115//!   ```
116//!
117//! - New handy macros (mostly for development purposes):
118//!   
119//!   ```rust
120//!   use stdext::{compile_warning, debug_name, function_name};
121//!
122//!   fn sample_function() {
123//!     println!("This function is called {}", function_name!());
124//!     println!("You can also found it here: {}", debug_name!());
125//!
126//!     compile_warning!("This function must do something else...");
127//!   }
128//!   ```
129
130#![warn(missing_docs, unreachable_pub)]
131
132pub mod duration;
133#[macro_use]
134pub mod macros;
135pub mod default;
136pub mod num;
137pub mod option;
138pub mod result;
139pub mod str;
140pub mod sync;
141pub mod vec;
142
143/// A "prelude" module which re-exports all the extension traits for the simple library usage.
144pub mod prelude {
145    pub use crate::{
146        default::*,
147        duration::*,
148        num::{float_convert::*, integer::*},
149        option::*,
150        result::*,
151        str::*,
152        sync::{mutex::*, rw_lock::*},
153        vec::*,
154    };
155}
stdext/lib.rs

stdext/
lib.rs
