s are a fundamental concept to grasp to become a proficient Rust developer, but they can feel a little weird coming from JavaScript. But if we take it slow, they're not that hard to understand: 

Below, I'm going to guide you through the ins and outs of the 

 concept in the Rust programming language. 

By the way, if you're just getting started with Rust, and you want to learn to build Rust applications checkout the 

Coming from JavaScript, one of the first stumps beginner Rust developers hit is on 

 errors and treats them as any other data type, consolidating most of the error treatment code around the 

. This is a lot different than exception-based approaches, so it's worth a closer look.

Results are the output of fallible operations - you might also find 

 is "just" the return type of a function that is not guaranteed to work. 

But what kind of functions are not guaranteed to work?

Imagine a function that divides two integers. If 

 are parameters, then the answer will be 3. We might be inclined to think our function's return type is an integer as well, but hold up. Can we guarantee that a division between two integers will 

// what should be the return type?
fn integer_divide(a: u32, b: u32) -> _ {
  a / b // can this operation fail?
}

 as inputs. What should be the answer in this case? What integer would be a valid answer in this case? That's right, there is none; Because 

 is not an integer - here it's a failure. A perfect case for the 

fn integer_divide(a: u32, b: u32) -> Result<u32, String> {
 if b != 0 {
 Ok(a / b)
 } else {
 Err("Division by zero!".into())
 }
}

Because our integer division function won't return an integer, we need to return something else. In this case, we'll use a 

 will wrap the explanation of why an integer could not be generated. 

Because this function is fallible it returns a Result so that the user can deal with its failure properly.

, failures must be expected and well defined

This is also an important part of how we use 

: errors that cannot be anticipated, cannot be handled properly upstream. 

If we want to properly define and type this function, 

 cannot output an integer and plan for that if we intend to always output the correct data type.

An unexpected failure cannot be annotated (because we don't know what it is yet) and it's handling will be impossible. However, an expected failure can have it's failure "encoded" as a 

 which will allow us to properly handle the failure case.

💡 Tip: Failures must be recoverable and will be handled by the caller

 formally tells the caller of a function that the function call can "fail" -- this means the caller is not surprised when the call fails, and we have alternative code paths for when it happens. Common alternative paths involve:

One feature of the Rust compiler is that it will 

. There are several ways you can do this, if you don't provide and handling code it will cause the compiler to raise a warning. This feature is great because we can be fearless about the execution of our programs -- we know that when the compilation returns no warning flags for our code, we've handled all of the 

. Exceptions on these languages have similar intentions as our 

s here, but there are two crucial differences to note.

1 . Exceptions represent the error, while Results represent the whole outcome

Let's think back to our integer division example. The function returns a 

 so it can account for the outcome when there is a division by 

. However, if the division works properly the returned data type is still a 

 because it contains the operation outcome as a whole.

integer_divide(6, 2) // => Ok(3), a Result containing the integer 3
integer_divide(6, 0) // => Err(...), a Result containing an string

Now, let's think about Exceptions. We usually see them 

. The successful path just returns the naked data type (the integer in our case). In other words, the function would yield the exception 

// This is JavaScript code
function integerDivide(a, b) {
  if (b === 0) {
    throw new Error("Division by zero!");
  } else {
    return a / b;
  }
}

integerDivide(6, 2) // => 3, just the naked integer type
integerDivide(6, 0) // => returns nothing, it "throws" the error

2 . Exceptions are special, while Results are just a regular type

When talking about Exceptions above, you might have taken note of the "yield" verb. Why couldn't I have just used the "return" verb? An Exception is a special kind of data type on languages that implement it. They are generally seen together with verbs like "raise" and "throw", which are reserved keywords used to notify the runtime that something bad happened.

Getting more technical, we could say an Exception is thrown, which will reverse the execution stack until it's properly dealt with. This means Exceptions are special to the runtime and have special keywords defined so they can be interacted with. 

Results, on the other hand, are just a data type that you return from a function.

 The norm is to treat them like you would treat any other data type. This lowers the cognitive load.

 for every function they are used in: so you'll never be surprised when a 

 is returned. The compiler won't let you be surprised: it will tell you beforehand and make sure you handle it.

At this point, I hope you understand the basic rationale behind 

. But let's figure out how to read it and use it in more practical situations.

 in Rust is defined as an enumeration of two options, 

Aside for polyglots: One curious bit about this definition is that it's pretty common in many languages that have a Result implementation, like 

. Many concepts read here transfer cleanly to those contexts.

Here is the definition directly from Rust's code.

enum Result<T, E> {
 Ok(T),
 Err(E),
}

 outcomes respectively. These values will each be 

 by the Result. Each constructor carries one of these types, so we have a constructor for successes (

Going back to our example, our integer division example returns a 

The construction of a "success", would be the number wrapped by an 

). The failure, on the other hand, would be wrapped by an 

Say that after we perform the integer division we want to do another operation with the outcome. Let's say we want to divide 

 by 2, which would promptly yield a compiler error:

let result = integer_divide(6, 2);
let doubled_result = result * 2;
// error: cannot multiply `{integer}` to `Result<u32, String>`

The error you see is the compiler looking out for us. It letting us know that we are assuming an operation-that-can-fail will never fail. 

In other words, we are trying to multiply the 

 by 2, but we aren't handling the case where the division has failed. 

So how should the program react in the case where our division fails?

 the division can never fail since the inputs are the constants 6 and 2, which we 

. In these cases, we can tell Rust we are super-sure-and-positive the error will never happen, so just trust us:

let result = integer_divide(6, 2);
let doubled_result = result.unwrap() * 2;
println!("{}", doubled_result); // => prints 6

Of course, you're probably wondering, what happens if the outcome was a failure? In our case, the error would be associated with a 

 type, which cannot be multiplied by two.

You, as a developer, are taking the responsibility and vowing the 

 will never be a failure. If it is, Rust will crash your whole program with a 

. At that point, nothing can stop the inevitable crash.

Scary, huh? So what should we do if we are not sure the 

 is always a success? Or if you are simply not comfortable taking this kind of risk? For that, we'll use 

 is risky. Unwrapping is only safe if there is no way for the error to happen, which is unusual in complex systems. 

In real-world programs, the arguments often come from the outside (like user input) - we just can't be sure that the division will work or not. For these cases, we would like to know if the operation succeeded or failed without risking a crash.

Rust has a powerful pattern matching implementation that works perfectly for us in this case.

For example, we could use it to default an error to a constant value (like 

let result = integer_divide(6, user_input_integer);
let treated_result = match result {
  Ok(int) => int,
  Err(_) => 0,
};
let doubled_result = treated_result * 2;
println!("{}", doubled_result); // => prints 6

 constructors and associate a path of execution to each. And this example above shows how to provide a default value for a failure.

But as we said before, we could also pass the error "up the chain". Let's see what it looks like:

fn divide_then_double(input: u32) -> Result<u32, String> {
 let result = integer_divide(6, input);
 
 let treated_result = match result {
 Ok(int) => int,
 _ => return result,
 };
 
 Ok(treated_result * 2)
}

Now we are passing the problem to the caller, just like the 

 function does. If the division fails, we don't know what to do, so we just return the 

. Note that in this case, we have to wrap the successful result in an 

 constructor so function signature is respected.

This pattern of unwrapping or returning the result is so prevalent and useful, we Rust developers got tired of writing it every time. Rust has 

fn divide_then_double(input: u32) -> Result<u32, String> {
 let treated_result = integer_divide(6, input)?;
 Ok(treated_result * 2)
}

This looks better, doesn't it? The star of the show here is the 

 operator. The funny thing about this example is that both the 

 are the same from the compiler's point of view. The macro and operator just make it easier to read.

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Introduction to Results in Rust</h1><code>Result</code>s are a fundamental concept to grasp to become a proficient Rust developer, but they can feel a little weird coming from JavaScript. But if we take it slow, they're not that hard to understand: <code>Result</code> is just a way to handle errors with a type.Below, I'm going to guide you through the ins and outs of the <code>Result</code> concept in the Rust programming language. <h3 class="heading-anchor-text" id="what-will-you-learn">What will you learn<a class="d-inline" href="#what-will-you-learn">#</a></h3><ul><li>The problem Results solve and how</li><li>Where to use Results in practice</li><li>How to understand the Result type definition</li><li>How to use the values contained in a Result, safely or otherwise</li></ul><blockquote data-block-type="information" class="information annotated">By the way, if you're just getting started with Rust, and you want to learn to build Rust applications checkout the <a href="https://www.newline.co/fullstack-rust" rel="noopener noreferrer nofollow">Fullstack Rust Book</a> </blockquote>Coming from JavaScript, one of the first stumps beginner Rust developers hit is on error handling. Rust statically types errors and treats them as any other data type, consolidating most of the error treatment code around the <a href="https://doc.rust-lang.org/std/result/enum.Result.html" rel="noopener noreferrer nofollow">Result type</a>. This is a lot different than exception-based approaches, so it's worth a closer look.<h3 class="heading-anchor-text" id="okay,-so-what-is-a-result?">Okay, so what is a Result?<a class="d-inline" href="#okay,-so-what-is-a-result?">#</a></h3>A <code>Result</code> is a data type that is expected to be returned from functions that can fail in an expected and recoverable way. <blockquote data-block-type="information" class="information annotated">Results are the output of fallible operations - you might also find <a href="https://doc.rust-lang.org/std/result/index.html" rel="noopener noreferrer nofollow">result's module documentation</a> helpful as you read this blog</blockquote>So put another way, a <code>Result</code> is "just" the return type of a function that is not guaranteed to work. But what kind of functions are not guaranteed to work?Imagine a function that divides two integers. If <code>6</code> and <code>2</code> are parameters, then the answer will be 3. We might be inclined to think our function's return type is an integer as well, but hold up. Can we guarantee that a division between two integers will always work?<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-tANGyW-_hiuY6tsBg9OPl" id="cm-tANGyW-_hiuY6tsBg9OPl">// what should be the return type?
fn integer_divide(a: u32, b: u32) -&gt; _ {
 a / b // can this operation fail?
}</textarea>Well, let's say we have <code>6</code> and <code>0</code> as inputs. What should be the answer in this case? What integer would be a valid answer in this case? That's right, there is none; Because <code>6</code> divided by <code>0</code> is not an integer - here it's a failure. A perfect case for the <code>Result</code> type.<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-ir1CwSZqIK0XZrxA_By3r" id="cm-ir1CwSZqIK0XZrxA_By3r">fn integer_divide(a: u32, b: u32) -&gt; Result&lt;u32, String&gt; {
 if b != 0 {
 Ok(a / b)
 } else {
 Err("Division by zero!".into())
 }
}</textarea>Because our integer division function won't return an integer, we need to return something else. In this case, we'll use a <code>Result</code> to wrap the integer when there is a success, or the <code>Result</code> will wrap the explanation of why an integer could not be generated. Because this function is fallible it returns a Result so that the user can deal with its failure properly.<blockquote data-block-type="information" class="information annotated">💡 Tip: when using <code>Result</code>, failures must be expected and well defined</blockquote>This is also an important part of how we use <code>Result</code>: errors that cannot be anticipated, cannot be handled properly upstream. If we want to properly define and type this function, we must know beforehand that it can fail. We must know <code>6</code> divided by <code>0</code> cannot output an integer and plan for that if we intend to always output the correct data type.An unexpected failure cannot be annotated (because we don't know what it is yet) and it's handling will be impossible. However, an expected failure can have it's failure "encoded" as a <code>Result</code> which will allow us to properly handle the failure case.<blockquote data-block-type="information" class="information annotated">💡 Tip: Failures must be recoverable and will be handled by the caller</blockquote><code>Result</code> formally tells the caller of a function that the function call can "fail" -- this means the caller is not surprised when the call fails, and we have alternative code paths for when it happens. Common alternative paths involve:<ol><li>using a default value or </li><li>passing up the error.</li></ol>One feature of the Rust compiler is that it will <a href="https://doc.rust-lang.org/std/result/index.html#results-must-be-used" rel="noopener noreferrer nofollow">require </a><code><a href="https://doc.rust-lang.org/std/result/index.html#results-must-be-used" rel="noopener noreferrer nofollow">Result</a></code><a href="https://doc.rust-lang.org/std/result/index.html#results-must-be-used" rel="noopener noreferrer nofollow"> to be handled</a>. There are several ways you can do this, if you don't provide and handling code it will cause the compiler to raise a warning. This feature is great because we can be fearless about the execution of our programs -- we know that when the compilation returns no warning flags for our code, we've handled all of the <code>Result</code> possibilities.<h3 class="heading-anchor-text" id="result-vs-exceptions">Result vs Exceptions<a class="d-inline" href="#result-vs-exceptions">#</a></h3>You might think that the definition of <code>Result</code> resembles <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error" rel="noopener noreferrer nofollow">JavaScript Errors</a> or <a href="https://ruby-doc.org/core-2.5.1/Exception.html" rel="noopener noreferrer nofollow">Ruby Exceptions</a>. Exceptions on these languages have similar intentions as our <code>Result</code>s here, but there are two crucial differences to note.1 . Exceptions represent the error, while Results represent the whole outcomeLet's think back to our integer division example. The function returns a <code>Result</code> so it can account for the outcome when there is a division by <code>0</code>. However, if the division works properly the returned data type is still a <code>Result</code>. The <code>Result</code> is returned either way because it contains the operation outcome as a whole.<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-u5aho7P8HqT9cf6VGdEOX" id="cm-u5aho7P8HqT9cf6VGdEOX">integer_divide(6, 2) // =&gt; Ok(3), a Result containing the integer 3
integer_divide(6, 0) // =&gt; Err(...), a Result containing an string</textarea>Now, let's think about Exceptions. We usually see them only when something went wrong. The successful path just returns the naked data type (the integer in our case). In other words, the function would yield the exception or the successful data type.<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-qBRHCLrJoz8ZSBL55MIT4" id="cm-qBRHCLrJoz8ZSBL55MIT4">// This is JavaScript code
function integerDivide(a, b) {
 if (b === 0) {
 throw new Error("Division by zero!");
 } else {
 return a / b;
 }
}

integerDivide(6, 2) // =&gt; 3, just the naked integer type
integerDivide(6, 0) // =&gt; returns nothing, it "throws" the error</textarea>Kind of weird, right?<code>Result</code> gives us consistency because we always get a <code>Result</code> regardless of success or failure.2 . Exceptions are special, while Results are just a regular typeWhen talking about Exceptions above, you might have taken note of the "yield" verb. Why couldn't I have just used the "return" verb? An Exception is a special kind of data type on languages that implement it. They are generally seen together with verbs like "raise" and "throw", which are reserved keywords used to notify the runtime that something bad happened.Getting more technical, we could say an Exception is thrown, which will reverse the execution stack until it's properly dealt with. This means Exceptions are special to the runtime and have special keywords defined so they can be interacted with. Results, on the other hand, are just a data type that you return from a function. The norm is to treat them like you would treat any other data type. This lowers the cognitive load.Also, because <code>Result</code> is "just a regular type", <code>Result</code>s are part of the type signature for every function they are used in: so you'll never be surprised when a <code>Result</code> is returned. The compiler won't let you be surprised: it will tell you beforehand and make sure you handle it.<h3 class="heading-anchor-text" id="anatomy-of-a-result">Anatomy of a Result<a class="d-inline" href="#anatomy-of-a-result">#</a></h3>At this point, I hope you understand the basic rationale behind <code>Result</code>. But let's figure out how to read it and use it in more practical situations.The <code>Result</code> in Rust is defined as an enumeration of two options, with two generic types. <blockquote data-block-type="information" class="information annotated">Aside for polyglots: One curious bit about this definition is that it's pretty common in many languages that have a Result implementation, like <a href="https://package.elm-lang.org/packages/elm/core/latest/Result" rel="noopener noreferrer nofollow">Elm</a> and <a href="https://developer.apple.com/documentation/swift/result" rel="noopener noreferrer nofollow">Swift</a>. Many concepts read here transfer cleanly to those contexts.</blockquote>Here is the definition directly from Rust's code.<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-DXH6cNRPFHwi6W8wIB4e1" id="cm-DXH6cNRPFHwi6W8wIB4e1">enum Result&lt;T, E&gt; {
 Ok(T),
 Err(E),
}</textarea>The two generic types, <code>T</code> and <code>E</code>, represent the type of the successful and failed outcomes respectively. These values will each be contained by the Result. Each constructor carries one of these types, so we have a constructor for successes (<code>Ok</code>) and another for failures (<code>Err</code>).Going back to our example, our integer division example returns a <code>Result&lt;u32, String&gt;</code>, which means the operation can either:<ul><li>be successful and return an integer (<code>u32</code>) or </li><li>fail and return a <code>String</code>. </li></ul>The construction of a "success", would be the number wrapped by an <code>Ok</code> constructor (<code>6 / 2 = Ok(3)</code>). The failure, on the other hand, would be wrapped by an <code>Err</code> constructor (<code>6 / 0 = Err("Division by zero!")</code>).<h3 class="heading-anchor-text" id="result-unwrapping">Result unwrapping<a class="d-inline" href="#result-unwrapping">#</a></h3>Say that after we perform the integer division we want to do another operation with the outcome. Let's say we want to divide <code>6</code> by <code>2</code>, then double the result. We could naively try to multiply the <code>Result</code> by 2, which would promptly yield a compiler error:<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-bC0mFTjyf88hN_6AJvHIX" id="cm-bC0mFTjyf88hN_6AJvHIX">let result = integer_divide(6, 2);
let doubled_result = result * 2;
// error: cannot multiply `{integer}` to `Result&lt;u32, String&gt;`</textarea>The error you see is the compiler looking out for us. It letting us know that we are assuming an operation-that-can-fail will never fail. In other words, we are trying to multiply the successful outcome by 2, but we aren't handling the case where the division has failed. So how should the program react in the case where our division fails?Well, in this case, we know the division can never fail since the inputs are the constants 6 and 2, which we know will result in <code>Ok(3)</code>. In these cases, we can tell Rust we are super-sure-and-positive the error will never happen, so just trust us:<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-rV1lQvd2Nopw6cO9Zeigb" id="cm-rV1lQvd2Nopw6cO9Zeigb">let result = integer_divide(6, 2);
let doubled_result = result.unwrap() * 2;
println!("{}", doubled_result); // =&gt; prints 6</textarea>The <a href="https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap" rel="noopener noreferrer nofollow">unwrap</a> function does this: it removes the <code>Result</code> from the equation. Of course, you're probably wondering, what happens if the outcome was a failure? In our case, the error would be associated with a <code>String</code> type, which cannot be multiplied by two.That's the risk you take when you <code>unwrap</code> a <code>Result</code>. You, as a developer, are taking the responsibility and vowing the <code>Result</code> will never be a failure. If it is, Rust will crash your whole program with a <a href="https://doc.rust-lang.org/std/macro.panic.html" rel="noopener noreferrer nofollow">panic</a>. At that point, nothing can stop the inevitable crash.Scary, huh? So what should we do if we are not sure the <code>Result</code> is always a success? Or if you are simply not comfortable taking this kind of risk? For that, we'll use <code>Result</code> matching.<h3 class="heading-anchor-text" id="result-matching">Result matching<a class="d-inline" href="#result-matching">#</a></h3>Unwrapping a <code>Result</code> is risky. Unwrapping is only safe if there is no way for the error to happen, which is unusual in complex systems. In real-world programs, the arguments often come from the outside (like user input) - we just can't be sure that the division will work or not. For these cases, we would like to know if the operation succeeded or failed without risking a crash.Rust has a powerful pattern matching implementation that works perfectly for us in this case.For example, we could use it to default an error to a constant value (like <code>0</code>), for example:<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-_nsO49TGpHcJkK-lt_vjh" id="cm-_nsO49TGpHcJkK-lt_vjh">let result = integer_divide(6, user_input_integer);
let treated_result = match result {
 Ok(int) =&gt; int,
 Err(_) =&gt; 0,
};
let doubled_result = treated_result * 2;
println!("{}", doubled_result); // =&gt; prints 6</textarea>The <a href="https://doc.rust-lang.org/book/ch06-02-match.html" rel="noopener noreferrer nofollow">match</a> keyword lets us test against <code>Result</code> constructors and associate a path of execution to each. And this example above shows how to provide a default value for a failure.But as we said before, we could also pass the error "up the chain". Let's see what it looks like:<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-tic6vpsPq4K_6I--aIRgC" id="cm-tic6vpsPq4K_6I--aIRgC">fn divide_then_double(input: u32) -&gt; Result&lt;u32, String&gt; {
 let result = integer_divide(6, input);
 
 let treated_result = match result {
 Ok(int) =&gt; int,
 _ =&gt; return result,
 };
 
 Ok(treated_result * 2)
}</textarea>Now we are passing the problem to the caller, just like the <code>integer_divide</code> function does. If the division fails, we don't know what to do, so we just return the <code>Result</code>. Note that in this case, we have to wrap the successful result in an <code>Ok</code> constructor so function signature is respected.<h3 class="heading-anchor-text" id="the-?-operator">The ? operator<a class="d-inline" href="#the-?-operator">#</a></h3>This pattern of unwrapping or returning the result is so prevalent and useful, we Rust developers got tired of writing it every time. Rust has <a href="https://doc.rust-lang.org/edition-guide/rust-2018/error-handling-and-panics/the-question-mark-operator-for-easier-error-handling.html" rel="noopener noreferrer nofollow">a macro that does just that for us</a>.<textarea data-iscodemirror="true" data-mode="text/x-rustsrc" data-uniqueid="cm-_D_g7a6Ce6nquivkV2Ae2" id="cm-_D_g7a6Ce6nquivkV2Ae2">fn divide_then_double(input: u32) -&gt; Result&lt;u32, String&gt; {
 let treated_result = integer_divide(6, input)?;
 Ok(treated_result * 2)
}</textarea>This looks better, doesn't it? The star of the show here is the <code>?</code> operator. The funny thing about this example is that both the <code>match</code> and the <code>?</code> are the same from the compiler's point of view. The macro and operator just make it easier to read.So where to go from here?<ul><li>Read up <a href="https://doc.rust-lang.org/rust-by-example/error.html" rel="noopener noreferrer nofollow">on the examples on error handling</a> might build your confidence that you know your results, panics, and exceptions </li><li>Beyond just error handling, <a href="https://github.com/fmoko/rustlings" rel="noopener noreferrer nofollow">these Rust exercises</a> will help you learn and build confidence in your knowledge about Rust in general</li><li>Of course, you should take a look at <a href="https://newline.co/fullstack-rust" rel="noopener noreferrer nofollow">Fullstack Rust</a></li></ul>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Introduction to Results in Rust

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript