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

//! Additional features for the Rust standard library.
//!
//! ## Description
//!
//! This crate contains enhancements to the Rust standard library types, useful for
//! broad audience, but not yet implemented (or stabilized) in `std`.
//!
//! Crate is designed to be lightweight (no external dependencies!) and provide essential
//! functionality which possible can get to the `std` some day.
//!
//! ## Extension traits
//!
//! All the new functionality the stanard library is added using extension traits.
//!
//! Below you can find the table of all the extension traits introduced by this crate:
//!
//! | `std` structure | extension traits
//! | --- | ---
//! | [`Vec`] | [`VecExt`] and [`VecExtClone`]
//! | [`&str`] | [`StrExt`]
//! | [`Option`] | [`OptionExt`]
//! | [`Result`] | [`ResultExt`]
//! | [`Duration`] | [`DurationExt`]
//! | [`RwLock`] | [`RwLockExt`]
//! | [`Mutex`] | [`MutexExt`]
//!
//! [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
//! [`&str`]: https://doc.rust-lang.org/std/primitive.str.html
//! [`Option`]: https://doc.rust-lang.org/std/option/enum.Option.html
//! [`Result`]: https://doc.rust-lang.org/std/result/enum.Result.html
//! [`Duration`]: https://doc.rust-lang.org/std/time/struct.Duration.html
//! [`RwLock`]: https://doc.rust-lang.org/std/sync/struct.RwLock.html
//! [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html
//!
//! [`VecExt`]: vec/trait.VecExt.html
//! [`VecExtClone`]: vec/trait.VecExtClone.html
//! [`StrExt`]: str/trait.StrExt.html
//! [`OptionExt`]: option/trait.OptionExt.html
//! [`ResultExt`]: result/trait.ResultExt.html
//! [`DurationExt`]: duration/trait.DurationExt.html
//! [`RwLockExt`]: sync/rw_lock/trait.RwLockExt.html
//! [`MutexExt`]: sync/mutex/trait.MutexExt.html
//!
//! ## Macros
//!
//! Another group of extensions in `stdext` is new macros:
//!
//! - [`compile_warning`] for spawning a user-defined compilation warnings.
//! - [`function_name`] for getting an enclosing function name.
//!
//! [`compile_warning`]: ./macro.compile_warning.html
//! [`function_name`]: ./macro.function_name.html
//!
//! ## Highlights
//!
//! - Convenient builder methods for **`Duration`**:
//!   
//!   ```rust
//!   use std::time::Duration;
//!   use stdext::prelude::*;
//!
//!   let duration = Duration::from_minutes(1).add_secs(5).add_micros(100);
//!   assert_eq!(duration, Duration::new(65, 100_000));
//!   ```
//!
//! - Panicking version for **`RwLock::read`**, **`RwLock::write`** and **`Mutex::lock`** (for
//!   fellows who don't really handle the lock poisoning):
//!
//!   ```rust
//!   use std::sync::{Arc, RwLock};
//!   use stdext::prelude::*;
//!   
//!   let lock = Arc::new(RwLock::new(1));
//!   {
//!       let mut n = lock.force_write(); // Instead of `.write().unwrap()`.
//!       *n = 2;
//!   }
//!   let n = lock.force_read();
//!   assert_eq!(*n, 2);
//!   ```
//!   
//! - **`Result::combine`** and **`Option::combine`** to zip pairs of objects:
//!   
//!   ```rust
//!   use stdext::prelude::*;
//!   
//!   let x = Some(1);
//!   let y = Some("hi");
//!   let z = None::<u8>;
//!   
//!   assert_eq!(x.combine(y), Some((1, "hi")));
//!   assert_eq!(x.combine(z), None);
//!
//!   let x = Ok(1);
//!   let y = Ok("hi");
//!   let z: Result<i32, &str> = Err("error");
//!   let z2: Result<i32, &str> = Err("other_error");
//!
//!   assert_eq!(x.combine(y), Ok((1, "hi")));
//!   assert_eq!(x.combine(z), Err("error"));
//!   assert_eq!(z.combine(z2), Err("error"));
//!   ```
//!
//! - New handy macros (mostly for development purposes):
//!   
//!   ```rust
//!   use stdext::{compile_warning, function_name};
//!
//!   fn sample_function() {
//!     println!("This function is called {}", function_name!());
//!
//!     compile_warning!("This function must do something else...");
//!   }
//!   ```

pub mod duration;
#[macro_use]
pub mod macros;
pub mod option;
pub mod result;
pub mod str;
pub mod sync;
pub mod vec;

/// A "prelude" module which re-exports all the extension traits for the simple library usage.
pub mod prelude {
    pub use crate::{
        duration::*,
        option::*,
        result::*,
        str::*,
        sync::{mutex::*, rw_lock::*},
        vec::*,
    };
}