rust/src/libcore/result.rs

455 lines
11 KiB
Rust
Raw Normal View History

// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! A type representing either success or failure
2012-09-25 18:23:04 -05:00
// NB: transitionary, de-mode-ing.
2012-09-04 13:12:17 -05:00
use cmp::Eq;
use either;
2012-09-04 13:12:17 -05:00
use either::Either;
use kinds::Copy;
use option::{None, Option, Some};
use vec;
/// The result type
2013-03-22 14:33:53 -05:00
#[deriving(Clone, Eq)]
pub enum Result<T, U> {
/// Contains the successful result value
2012-08-26 18:54:31 -05:00
Ok(T),
/// Contains the error value
2012-08-26 18:54:31 -05:00
Err(U)
}
/**
* Get the value out of a successful result
*
* # Failure
*
* If the result is an error
*/
#[inline(always)]
pub fn get<T:Copy,U>(res: &Result<T, U>) -> T {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Ok(copy t) => t,
Err(ref the_err) =>
fail!(fmt!("get called on error result: %?", *the_err))
}
}
/**
* Get a reference to the value out of a successful result
*
* # Failure
*
* If the result is an error
*/
#[inline(always)]
pub fn get_ref<'a, T, U>(res: &'a Result<T, U>) -> &'a T {
match *res {
2012-08-26 18:54:31 -05:00
Ok(ref t) => t,
Err(ref the_err) =>
fail!(fmt!("get_ref called on error result: %?", *the_err))
}
}
/**
* Get the value out of an error result
*
* # Failure
*
* If the result is not an error
*/
#[inline(always)]
pub fn get_err<T, U: Copy>(res: &Result<T, U>) -> U {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Err(copy u) => u,
Ok(_) => fail!(~"get_err called on ok result")
}
}
/// Returns true if the result is `ok`
#[inline(always)]
pub fn is_ok<T, U>(res: &Result<T, U>) -> bool {
2012-09-25 18:23:04 -05:00
match *res {
2012-08-26 18:54:31 -05:00
Ok(_) => true,
Err(_) => false
}
}
/// Returns true if the result is `err`
#[inline(always)]
pub fn is_err<T, U>(res: &Result<T, U>) -> bool {
!is_ok(res)
}
/**
* Convert to the `either` type
*
* `ok` result variants are converted to `either::right` variants, `err`
* result variants are converted to `either::left`.
*/
#[inline(always)]
pub fn to_either<T:Copy,U:Copy>(res: &Result<U, T>)
-> Either<T, U> {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Ok(copy res) => either::Right(res),
Err(copy fail_) => either::Left(fail_)
}
}
/**
* Call a function based on a previous result
*
* If `res` is `ok` then the value is extracted and passed to `op` whereupon
* `op`s result is returned. if `res` is `err` then it is immediately
* returned. This function can be used to compose the results of two
* functions.
*
* Example:
*
* let res = chain(read_file(file)) { |buf|
* ok(parse_bytes(buf))
* }
*/
#[inline(always)]
pub fn chain<T, U, V>(res: Result<T, V>, op: &fn(T)
2012-09-25 21:12:50 -05:00
-> Result<U, V>) -> Result<U, V> {
2013-02-15 02:51:28 -06:00
match res {
Ok(t) => op(t),
Err(e) => Err(e)
}
}
2012-01-17 19:28:21 -06:00
/**
* Call a function based on a previous result
*
* If `res` is `err` then the value is extracted and passed to `op`
* whereupon `op`s result is returned. if `res` is `ok` then it is
* immediately returned. This function can be used to pass through a
* successful result while handling an error.
*/
#[inline(always)]
pub fn chain_err<T, U, V>(
res: Result<T, V>,
op: &fn(t: V) -> Result<T, U>)
2012-08-26 18:54:31 -05:00
-> Result<T, U> {
2013-02-15 02:51:28 -06:00
match res {
Ok(t) => Ok(t),
Err(v) => op(v)
2012-03-22 22:06:01 -05:00
}
}
/**
* Call a function based on a previous result
*
* If `res` is `ok` then the value is extracted and passed to `op` whereupon
* `op`s result is returned. if `res` is `err` then it is immediately
* returned. This function can be used to compose the results of two
* functions.
*
* Example:
*
* iter(read_file(file)) { |buf|
* print_buf(buf)
* }
*/
#[inline(always)]
pub fn iter<T, E>(res: &Result<T, E>, f: &fn(&T)) {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Ok(ref t) => f(t),
2012-08-26 18:54:31 -05:00
Err(_) => ()
}
}
/**
* Call a function based on a previous result
*
* If `res` is `err` then the value is extracted and passed to `op` whereupon
* `op`s result is returned. if `res` is `ok` then it is immediately returned.
* This function can be used to pass through a successful result while
* handling an error.
*/
#[inline(always)]
pub fn iter_err<T, E>(res: &Result<T, E>, f: &fn(&E)) {
2012-09-25 18:23:04 -05:00
match *res {
2012-08-26 18:54:31 -05:00
Ok(_) => (),
2012-09-28 15:00:07 -05:00
Err(ref e) => f(e)
}
}
/**
* Call a function based on a previous result
*
* If `res` is `ok` then the value is extracted and passed to `op` whereupon
* `op`s result is wrapped in `ok` and returned. if `res` is `err` then it is
* immediately returned. This function can be used to compose the results of
* two functions.
*
* Example:
*
* let res = map(read_file(file)) { |buf|
* parse_bytes(buf)
* }
*/
#[inline(always)]
pub fn map<T, E: Copy, U: Copy>(res: &Result<T, E>, op: &fn(&T) -> U)
2012-08-26 18:54:31 -05:00
-> Result<U, E> {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Ok(ref t) => Ok(op(t)),
Err(copy e) => Err(e)
}
}
/**
* Call a function based on a previous result
*
* If `res` is `err` then the value is extracted and passed to `op` whereupon
* `op`s result is wrapped in an `err` and returned. if `res` is `ok` then it
* is immediately returned. This function can be used to pass through a
* successful result while handling an error.
*/
#[inline(always)]
pub fn map_err<T:Copy,E,F:Copy>(res: &Result<T, E>, op: &fn(&E) -> F)
2012-08-26 18:54:31 -05:00
-> Result<T, F> {
2012-09-25 18:23:04 -05:00
match *res {
2012-09-28 15:00:07 -05:00
Ok(copy t) => Ok(t),
Err(ref e) => Err(op(e))
}
}
pub impl<T, E> Result<T, E> {
2013-04-10 15:11:35 -05:00
#[inline(always)]
fn get_ref<'a>(&'a self) -> &'a T { get_ref(self) }
#[inline(always)]
fn is_ok(&self) -> bool { is_ok(self) }
2012-04-01 17:44:01 -05:00
#[inline(always)]
fn is_err(&self) -> bool { is_err(self) }
2012-04-01 17:44:01 -05:00
#[inline(always)]
fn iter(&self, f: &fn(&T)) { iter(self, f) }
#[inline(always)]
fn iter_err(&self, f: &fn(&E)) { iter_err(self, f) }
#[inline(always)]
fn unwrap(self) -> T { unwrap(self) }
#[inline(always)]
fn unwrap_err(self) -> E { unwrap_err(self) }
#[inline(always)]
fn chain<U>(self, op: &fn(T) -> Result<U,E>) -> Result<U,E> {
chain(self, op)
}
#[inline(always)]
fn chain_err<F>(self, op: &fn(E) -> Result<T,F>) -> Result<T,F> {
chain_err(self, op)
}
}
pub impl<T:Copy,E> Result<T, E> {
#[inline(always)]
fn get(&self) -> T { get(self) }
#[inline(always)]
fn map_err<F:Copy>(&self, op: &fn(&E) -> F) -> Result<T,F> {
map_err(self, op)
}
}
pub impl<T, E: Copy> Result<T, E> {
#[inline(always)]
fn get_err(&self) -> E { get_err(self) }
#[inline(always)]
fn map<U:Copy>(&self, op: &fn(&T) -> U) -> Result<U,E> {
map(self, op)
}
}
/**
* Maps each element in the vector `ts` using the operation `op`. Should an
* error occur, no further mappings are performed and the error is returned.
* Should no error occur, a vector containing the result of each map is
* returned.
*
* Here is an example which increments every integer in a vector,
* checking for overflow:
*
* fn inc_conditionally(x: uint) -> result<uint,str> {
2012-08-01 19:30:05 -05:00
* if x == uint::max_value { return err("overflow"); }
* else { return ok(x+1u); }
* }
* map(~[1u, 2u, 3u], inc_conditionally).chain {|incd|
2013-03-28 20:39:09 -05:00
* assert!(incd == ~[2u, 3u, 4u]);
* }
*/
#[inline(always)]
pub fn map_vec<T,U:Copy,V:Copy>(
ts: &[T], op: &fn(&T) -> Result<V,U>) -> Result<~[V],U> {
let mut vs: ~[V] = vec::with_capacity(vec::len(ts));
for vec::each(ts) |t| {
2012-08-06 14:34:08 -05:00
match op(t) {
2012-09-28 15:00:07 -05:00
Ok(copy v) => vs.push(v),
Err(copy u) => return Err(u)
}
}
2013-02-15 02:51:28 -06:00
return Ok(vs);
}
#[inline(always)]
pub fn map_opt<T,U:Copy,V:Copy>(
o_t: &Option<T>, op: &fn(&T) -> Result<V,U>) -> Result<Option<V>,U> {
2012-09-25 18:23:04 -05:00
match *o_t {
2012-08-26 18:54:31 -05:00
None => Ok(None),
2012-09-28 15:00:07 -05:00
Some(ref t) => match op(t) {
Ok(copy v) => Ok(Some(v)),
Err(copy e) => Err(e)
}
}
}
/**
* Same as map, but it operates over two parallel vectors.
*
* A precondition is used here to ensure that the vectors are the same
* length. While we do not often use preconditions in the standard
* library, a precondition is used here because result::t is generally
* used in 'careful' code contexts where it is both appropriate and easy
* to accommodate an error like the vectors being of different lengths.
*/
#[inline(always)]
pub fn map_vec2<S,T,U:Copy,V:Copy>(ss: &[S], ts: &[T],
op: &fn(&S,&T) -> Result<V,U>) -> Result<~[V],U> {
2013-03-28 20:39:09 -05:00
assert!(vec::same_length(ss, ts));
let n = vec::len(ts);
let mut vs = vec::with_capacity(n);
let mut i = 0u;
while i < n {
2012-09-25 18:23:04 -05:00
match op(&ss[i],&ts[i]) {
2012-09-28 15:00:07 -05:00
Ok(copy v) => vs.push(v),
Err(copy u) => return Err(u)
}
i += 1u;
}
2013-02-15 02:51:28 -06:00
return Ok(vs);
}
/**
* Applies op to the pairwise elements from `ss` and `ts`, aborting on
2013-04-25 00:38:44 -05:00
* error. This could be implemented using `map_zip()` but it is more efficient
* on its own as no result vector is built.
*/
#[inline(always)]
pub fn iter_vec2<S,T,U:Copy>(ss: &[S], ts: &[T],
op: &fn(&S,&T) -> Result<(),U>) -> Result<(),U> {
2013-03-28 20:39:09 -05:00
assert!(vec::same_length(ss, ts));
2012-03-22 22:06:01 -05:00
let n = vec::len(ts);
let mut i = 0u;
while i < n {
2012-09-25 18:23:04 -05:00
match op(&ss[i],&ts[i]) {
2012-08-26 18:54:31 -05:00
Ok(()) => (),
2012-09-28 15:00:07 -05:00
Err(copy u) => return Err(u)
2012-03-22 22:06:01 -05:00
}
i += 1u;
}
2012-08-26 18:54:31 -05:00
return Ok(());
2012-03-22 22:06:01 -05:00
}
/// Unwraps a result, assuming it is an `ok(T)`
#[inline(always)]
pub fn unwrap<T, U>(res: Result<T, U>) -> T {
2013-02-15 02:51:28 -06:00
match res {
Ok(t) => t,
Err(_) => fail!(~"unwrap called on an err result")
}
}
2012-08-30 17:54:16 -05:00
/// Unwraps a result, assuming it is an `err(U)`
#[inline(always)]
pub fn unwrap_err<T, U>(res: Result<T, U>) -> U {
2013-02-15 02:51:28 -06:00
match res {
Err(u) => u,
Ok(_) => fail!(~"unwrap called on an ok result")
2012-08-30 17:54:16 -05:00
}
}
2012-01-17 19:28:21 -06:00
#[cfg(test)]
#[allow(non_implicitly_copyable_typarams)]
2012-01-17 19:28:21 -06:00
mod tests {
use result::{Err, Ok, Result, chain, get, get_err};
use result;
pub fn op1() -> result::Result<int, ~str> { result::Ok(666) }
2012-01-17 19:28:21 -06:00
pub fn op2(i: int) -> result::Result<uint, ~str> {
2012-08-26 18:54:31 -05:00
result::Ok(i as uint + 1u)
}
2012-01-17 19:28:21 -06:00
pub fn op3() -> result::Result<int, ~str> { result::Err(~"sadface") }
2012-01-17 19:28:21 -06:00
#[test]
pub fn chain_success() {
2013-03-28 20:39:09 -05:00
assert!(get(&chain(op1(), op2)) == 667u);
2012-01-17 19:28:21 -06:00
}
#[test]
pub fn chain_failure() {
2013-03-28 20:39:09 -05:00
assert!(get_err(&chain(op3(), op2)) == ~"sadface");
2012-01-17 19:28:21 -06:00
}
#[test]
pub fn test_impl_iter() {
let mut valid = false;
2012-08-26 18:54:31 -05:00
Ok::<~str, ~str>(~"a").iter(|_x| valid = true);
2013-03-28 20:39:09 -05:00
assert!(valid);
2012-08-26 18:54:31 -05:00
Err::<~str, ~str>(~"b").iter(|_x| valid = false);
2013-03-28 20:39:09 -05:00
assert!(valid);
}
#[test]
pub fn test_impl_iter_err() {
let mut valid = true;
2012-08-26 18:54:31 -05:00
Ok::<~str, ~str>(~"a").iter_err(|_x| valid = false);
2013-03-28 20:39:09 -05:00
assert!(valid);
valid = false;
2012-08-26 18:54:31 -05:00
Err::<~str, ~str>(~"b").iter_err(|_x| valid = true);
2013-03-28 20:39:09 -05:00
assert!(valid);
}
#[test]
pub fn test_impl_map() {
2013-03-28 20:39:09 -05:00
assert!(Ok::<~str, ~str>(~"a").map(|_x| ~"b") == Ok(~"b"));
assert!(Err::<~str, ~str>(~"a").map(|_x| ~"b") == Err(~"a"));
}
#[test]
pub fn test_impl_map_err() {
2013-03-28 20:39:09 -05:00
assert!(Ok::<~str, ~str>(~"a").map_err(|_x| ~"b") == Ok(~"a"));
assert!(Err::<~str, ~str>(~"a").map_err(|_x| ~"b") == Err(~"b"));
}
2012-10-22 20:31:13 -05:00
#[test]
pub fn test_get_ref_method() {
2012-10-22 20:31:13 -05:00
let foo: Result<int, ()> = Ok(100);
2013-03-28 20:39:09 -05:00
assert!(*foo.get_ref() == 100);
2012-10-22 20:31:13 -05:00
}
2012-01-17 19:28:21 -06:00
}