std_prelude/
lib.rs

1//! `use std_prelude::*` so you can be ready to code!
2//!
3//! # Traits
4//! Not having common traits imported is one of the most annoying gotchas in rust when coming from
5//! other languages. When you are used to the language, you expect the commonly used methods to
6//! always work... not so in rust! Using `Vec::from_iter` is extremely common, but you must first
7//! import the `FromIterator` trait.
8//!
9//! The following are the traits that are exported and why:
10//!
11//! - **std::ascii::[AsciiExt](trait.AsciiExt.html)**: adds the `to_ascii_uppercase` onto `&str`
12//!   types.
13//! - **std::borrow::[Borrow](trait.Borrow.html)**: for manually defining the `Borrow` trait.
14//! - **std::cmp::{[Ord](enum.Ord.html), [PartialOrd](enum.PartialOrd.html)}**: for manually
15//!   defining the Ordering traits and using them in trait bounds.
16//! - **std::fmt::[Debug](trait.Debug.html)**: allows you to define Debug manually and use in trait
17//!   bounds.
18//! - **std::hash::{[Hash](trait.Hash.html), [Hasher](trait.Hasher.html)}**: allows you to
19//!   define Hash manually and use in trait bounds.
20//! - **std::fmt::[Write as FmtWrite](trait.FmtWrite.html)**: adds `write_str` onto byte buffers
21//!   (such as `String`). Renamed `FmtWrite` to avoid conflict with `std::io::Write`
22//! - **std::io::[BufRead](trait.BufRead.html)**: the `BufRead` trait allows you to use the methods
23//!   associated with the `BufReader` struct (also imported).
24//! - **std::io::[Read](trait.Read.html)**: allows you to use `file.read()`
25//! - **std::io::[Seek](trait.Seek.html)**: allows you to use `file.seek()`
26//! - **std::io::[Write as IoWrite](trait.IoWrite.html)**: allows you to use `file.write()` and
27//!   `file.write_all()`. Renamed `IoWrite` to avoid conflict with `std::fmt::Write`
28//! - **std::ops::{[Deref](trait.Deref.html), [DerefMut](trait.DerefMut.html)}**: allows deref
29//!   through `*v` and also enables Deref coercions
30//! - **std::str::[FromStr](trait.FromStr.html)**: allows you to use `type::from_str` constructor
31//!   for several types. This is what is implicitly called with `str::parse<_>()`
32//!
33//! # Structs
34//! These are extremely commonly used types and it is annoying to have to reimport them all the
35//! time.
36//!
37//! - **std::borrow::[Cow](struct.Cow.html)**: A clone-on-write smart pointer (often called copy on
38//!   write in other languages). This is used by many libraries to be as efficient as possible when
39//!   returned data is identical to the data passed in, among other uses.
40//! - **std::collections::{[BTreeMap](struct.BTreeMap.html), [HashMap](struct.HashMap.html),
41//!   [HashSet](struct.HashSet.html)}**: ordered-dict, dict and set
42//! - **std::cmp::[Ordering](enum.Ordering.html)**: the enum type used in the Ordering traits.
43//! - **std::ffi::[OsString](struct.OsString.html)**: os agnostic (non unicode) string type.
44//!   `std::path::PathBuf` uses this.
45//! - **std::fs::[File](struct.File.html)**: for opening files.
46//!     - `File::open` to open a file for reading
47//!     - `File::write` to open a file for writing
48//! - **std::fs::[OpenOptions](struct.OpenOptions.html)**: file opening options.
49//! - **std::fs::[ReadDir](struct.ReadDir.html)**: to iterate over the entries in a directory.
50//! - **std::io::[BufReader](struct.BufReader.html)**: the BufRead struct wraps `io::Read` using a
51//!   buffer reducing the number of OS calls and giving helpful methods
52//!   - `read_line()`: read a single line
53//!   - `lines()`: return an iterator over all lines.
54//!   - `split(byte: u8)`: return an iterator which splits at the chosen byte.
55//! - **std::io::[BufWriter](struct.BufWriter.html)**: similar to `BufReader`, buffers writes to
56//!   reduce the number of calls to the OS. Provides no new methods.
57//!
58//! - **std::path::{[Path](struct.Path.html), [PathBuf](struct.PathBuf.html)}**: specifies an os
59//!   path.
60//! - **std::rc::[Rc](struct.Rc.html)**: reference counted pointer
61//! - **std::sync::[Arc](struct.Arc.html)**: atomically reference counted pointer
62//! - **std::sync::[Mutex](struct.Mutex.html)**: mutual exclusion primitive for threading.
63//! - **std::sync::atomic::{AtomicBool, AtomicIsize, AtomicUsize}**: basic atomic types. Good for
64//!   unique ids and lots of other use cases.
65//! - **std::sync::atomic::[Ordering as AtomicOrdering](struct.AtomicOrdering.html)**: necessary
66//!   for performing operations on atomic types. For incrementing a counter use `val.fetch_add(1,
67//!   AtomicOrdering::SeqCst)`. Renamed to not conflict with `std::cmp::Ordering`.
68//! - **std::sync::atomic::ATOMIC_USIZE_INIT**: initialized `AtomicUsize` of 0. Use with `static
69//!   COUNTER: AtomicUsize = ATOMIC_USIZE_INIT;`
70//! - **std::time::[Duration](struct.Duration.html)**: an amount of time, used for
71//!   `std::thread::sleep`.
72//!
73//! # Functions
74//! These are mostly just "nice to have" functions and it is *really* unlikely that they would ever
75//! be overriden.
76//!
77//! - **std::cmp::{[max](fn.max.html), [min](fn.min.html)}**: get the max or min of two comparable integers.
78//! - **std::mem::{[size_of](fn.size_of.html), [size_of_val](fn.size_of_val.html)}**: get the size
79//!   of a type. This is safe and common enough that it should be always available.
80//! - **std::thread::[sleep](fn.sleep.html)**: put the thread to sleep for a `Duration`.
81//! - **std::thread::[spawn](fn.spawn.html)**: spawn a function in a new thread. In rust this is
82//!   memory safe, so it is nice to have it always available.
83//!
84//! # Modules (_primitive type_ only)
85//! The following modules are imported so that it is easy to access their relevant constants and
86//! constructors.
87//!
88//! - **u8 u16 u64 usize**: unsigned integer modules with `MAX` and `MIN`
89//! - **i8 i16 i64 isize**: signed integer modules with `MAX` and `MIN`
90//! - **f32 f64**: floating point modules with not just `MAX` and `MIN` but also `NAN`, `INFINITY`,
91//!   etc as well as a [f32::consts](f32/consts/index.html) and [f64::consts](f64/consts/index.html)
92//!   modules with basic mathematical constants like `PI` and `E`.
93//! - [**str**](str/index.html): core string type with [`from_utf8`](str/fn.from_utf8.html)
94//!   function.
95
96// ------------------------------
97// ----------- TRAITS -----------
98pub use std::ascii::AsciiExt;
99pub use std::borrow::Borrow;
100pub use std::cmp::{
101    Ord, PartialOrd, Ordering
102};
103pub use std::fmt::{Debug, Write as FmtWrite};
104pub use std::hash::{Hash, Hasher};
105pub use std::io::{
106    BufRead,
107    Read, Seek, SeekFrom,
108    Write as IoWrite,
109};
110pub use std::iter::FromIterator;
111pub use std::ops::{Deref, DerefMut};
112pub use std::str::FromStr;
113
114
115// -------------------------------
116// ----------- STRUCTS -----------
117pub use std::borrow::Cow;
118pub use std::collections::{BTreeMap, HashMap, HashSet};
119pub use std::ffi::OsString;
120pub use std::fs::{
121    File,
122    OpenOptions,
123    ReadDir,
124};
125pub use std::io::{
126    BufReader, BufWriter,
127};
128pub use std::path::{Path, PathBuf};
129pub use std::rc::Rc;
130pub use std::sync::{Arc, Mutex};
131pub use std::sync::atomic::{
132    AtomicBool,
133    AtomicIsize,
134    AtomicUsize,
135    Ordering as AtomicOrdering,
136    ATOMIC_USIZE_INIT,
137};
138pub use std::time::Duration;
139
140
141// ---------------------------------
142// ----------- FUNCTIONS -----------
143pub use std::mem::{size_of, size_of_val};
144pub use std::thread::{sleep, spawn};
145
146
147// ---------------------------------
148// ----------- MODULES -----------
149
150pub use std::u8;
151pub use std::u16;
152pub use std::u64;
153pub use std::usize;
154pub use std::i8;
155pub use std::i16;
156pub use std::i64;
157pub use std::isize;
158pub use std::f32;
159pub use std::f64;
160pub use std::str;
std_prelude/lib.rs

std_prelude/
lib.rs
