Module: R::Result Abstract

Extended by:
T::Generic, T::Helpers, T::Sig
Includes:
Kernel
Included in:
Err, Ok
Defined in:
lib/r/result.rb

Overview

This module is abstract.

Subclasses must implement the abstract methods below.

Result is a type that represents either success (Ok) or failure (Err).

See Also:

Constant Summary collapse

OkType =

The type of the success value.

type_member(:out)
ErrType =

The type of the error value.

type_member(:out)

Instance Method Summary collapse

Instance Method Details

#==(other) ⇒ Boolean

This method is abstract.

Returns true if self and other are both Ok and self.ok == other.ok, or if self and other are both Err and self.err == other.err.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x == R.ok(2) # => true
x == R.ok(3) # => false
x == R.err("not Ok") # => false
x == "not Result" # => false

x = T.let(R.err("Some error message"), R::Result[Integer, String])
x == R.ok(2) # => false
x == R.err("Some error message") # => true
x == R.err("Different error message") # => false
x == "not Result" # => false

Parameters:

  • other (T.anything)

Returns:

  • (Boolean)

See Also:



48
 
# File 'lib/r/result.rb', line 48

def ==(other); end

#and(res) ⇒ Result[T.type_parameter(:U), T.any(ErrType, T.type_parameter(:F))]

This method is abstract.

Returns res if the result is Ok, otherwise returns the Err value of self.

Arguments passed to and are eagerly evaluated; if you are passing the result of a function call, it is recommended to use #and_then, which is lazily evaluated.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
y = T.let(R.err("late error"), R::Result[String, String])
x.and(y) # => R.err("late error")

x = T.let(R.err("early error"), R::Result[Integer, String])
y = T.let(R.ok("foo"), R::Result[String, String])
x.and(y) # => R.err("early error")

x = T.let(R.err("not a 2"), R::Result[Integer, String])
y = T.let(R.err("late error"), R::Result[String, String])
x.and(y) # => R.err("not a 2")

x = T.let(R.ok(2), R::Result[Integer, String])
y = T.let(R.ok("different result type"), R::Result[String, String])
x.and(y) # => R.ok("different result type")

Parameters:

  • res (Result[T.type_parameter(:U), T.type_parameter(:F)])

Returns:

  • (Result[T.type_parameter(:U), T.any(ErrType, T.type_parameter(:F))])

See Also:



417
 
# File 'lib/r/result.rb', line 417

def and(res); end

#and_then(&blk) ⇒ Result[T.type_parameter(:U), T.any(ErrType, T.type_parameter(:F))]

This method is abstract.

Calls the block if the result is Ok, otherwise returns the Err value of self.

This function can be used for control flow based on R::Result values.

Examples:

module Example
  extend T::Sig

  sig { params(x: Integer).returns(R::Result[String, String])}
  def self.sqrt_then_to_s(x)
    return R.err("negative value") if x < 0
    R.ok(Math.sqrt(x).to_s)
  end
end

R.ok(4).and_then { |x| Example.sqrt_then_to_s(x) } # => R.ok("2.0")
R.ok(-4).and_then { |x| Example.sqrt_then_to_s(x) } # => R.err("negative value")
R.err("not a number").and_then { |x| Example.sqrt_then_to_s(x) } # => R.err("not a number")

Parameters:

  • blk (T.proc.params(arg: OkType).returns(Result[T.type_parameter(:U), T.type_parameter(:F)]))

Returns:

  • (Result[T.type_parameter(:U), T.any(ErrType, T.type_parameter(:F))])

See Also:



446
 
# File 'lib/r/result.rb', line 446

def and_then(&blk); end

#err ⇒ ErrType?

This method is abstract.

Returns the value if the result is Err, or nil if the result is Ok.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.err => nil

x = T.let(R.err("Nothing here"), R::Result[Integer, String])
x.err => "Nothing here"

Returns:

See Also:



152
 
# File 'lib/r/result.rb', line 152

def err; end

#err? ⇒ Boolean

This method is abstract.

Returns true if the result is Err.

Examples:

x = T.let(R.ok(-3), R::Result[Integer, String])
x.err? # => false

x = T.let(R.err("Some error message"), R::Result[Integer, String])
x.err? # => true

Returns:

  • (Boolean)

See Also:



107
 
# File 'lib/r/result.rb', line 107

def err?; end

#err_and?(&blk) ⇒ Boolean

This method is abstract.

Returns true if the result is Err and the value inside of it matches a predicate.

Examples:

x = T.let(R.err(ArgumentError.new), R::Result[Integer, StandardError])
x.err_and? { |x| x.is_a?(ArgumentError) } # => true

x = T.let(R.err(IOError.new), R::Result[Integer, StandardError])
x.err_and? { |x| x.is_a?(ArgumentError) } # => false

x = T.let(R.ok(123), R::Result[Integer, StandardError])
x.err_and? { |x| x.is_a?(ArgumentError) } # => false

Parameters:

  • blk (T.proc.params(value: ErrType).returns(T::Boolean))

Returns:

  • (Boolean)

See Also:



124
 
# File 'lib/r/result.rb', line 124

def err_and?(&blk); end

#expect!(msg) ⇒ OkType

This method is abstract.

Returns the contained Ok value, or raises an UnwrapFailedError if the result is Err.

Because this function may raise an exception, its use is generally discouraged. Instead, prefer to use pattern matching and #ok, or call #unwrap_or or #unwrap_or_else.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.expect!("Testing expect!") # => 2

This example raises an UnwrapFailedError exception.

x = T.let(R.err("emergency failure"), R::Result[Integer, String])
x.expect!("Testing expect!") # => raise R::UnwrapFailedError.new("Testing expect!", "emergency failure")

Parameters:

  • msg (String)

Returns:

Raises:

  • (UnwrapFailedError) —

    if the result is Err, with a message including the passed message, and the content of the Err value

See Also:



330
 
# File 'lib/r/result.rb', line 330

def expect!(msg); end

#expect_err!(msg) ⇒ ErrType

This method is abstract.

Returns the contained Err value, or raises an UnwrapFailedError if the result is Ok.

Examples:

This example raises an UnwrapFailedError exception.

x = R.ok(10)
x.expect_err!("Testing expect_err!") # => raise R::UnwrapFailedError.new("Testing expect_err!", 10)
x = T.let(R.err("emergency failure"), R::Result[Integer, String])
x.expect_err!("Testing expect_err!") # => "emergency failure"

Parameters:

  • msg (String)

Returns:

Raises:

  • (UnwrapFailedError) —

    if the result is Ok, with a message including the passed message, and the content of the Ok value

See Also:



368
 
# File 'lib/r/result.rb', line 368

def expect_err!(msg); end

#inspect ⇒ String

This method is abstract.

Returns a string representation of self.

Examples:

x = T.let(R.ok(-3), R::Result[Integer, String])
x.inspect # => "R.ok(-3)"

x = T.let(R.err("Some error message"), R::Result[Integer, String])
x.inspect # => "R.err(\"Some error message\")"

Returns:

  • (String)

See Also:



62
 
# File 'lib/r/result.rb', line 62

def inspect; end

#map(&blk) ⇒ Result[T.type_parameter(:U), ErrType]

This method is abstract.

Maps a R::Result[T, E] to R::Result[U, E] by applying a function to a contained Ok value, leaving an Err value untouched.

This function can be used to compose the results of two functions.

Examples:

module Example
  extend T::Sig

  sig { params(str: String).returns(R::Result[Integer, String]) }
  def self.parse_int(str)
    R.ok(Integer(str))
  rescue ArgumentError
    R.err("Cannot parse #{str} as an integer")
  end
end

out = T.let([], T::Array[Integer])
text = "1\n2\nHi\n4\n"
text.lines.each do |num|
  res = Example.parse_int(num).map { |i| i * 2 }
  case res
  when R::Ok
    out << res.ok
  when R::Err
    # do nothing
  end
end
out # => [2, 4, 8]

Parameters:

  • blk (T.proc.params(value: OkType).returns(T.type_parameter(:U)))

Returns:

See Also:



192
 
# File 'lib/r/result.rb', line 192

def map(&blk); end

#map_err(&blk) ⇒ Result[OkType, T.type_parameter(:F)]

This method is abstract.

Maps a R::Result[T, E] to R::Result[T, F] by applying a function to a contained Err value, leaving an Ok value untouched.

This function can be used to pass through a successful result while handling an error.

Examples:

module Example
  extend T::Sig

  sig { params(x: Integer).returns(String) }
  def self.stringify(x)
    "error code: #{x}"
  end
end

x = T.let(R.ok(2), R::Result[Integer, Integer])
x.map_err { |x| Example.stringify(x) } # => R.ok(2)

x = T.let(R.err(13), R::Result[Integer, Integer])
x.map_err { |x| Example.stringify(x) } # => R.err("error code: 13")

Parameters:

  • blk (T.proc.params(value: ErrType).returns(T.type_parameter(:F)))

Returns:

See Also:



275
 
# File 'lib/r/result.rb', line 275

def map_err(&blk); end

#map_or(default, &blk) ⇒ T.type_parameter(:U)

This method is abstract.

Returns the provided default (if Err), or applies a function to the contained value (if Ok).

Arguments passed to #map_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use #map_or_else, which is lazily evaluated.

Examples:

x = T.let(R.ok("foo"), R::Result[String, String])
x.map_or(42) { |v| v.size } # => 3

x = T.let(R.err("bar"), R::Result[String, String])
x.map_or(42) { |v| v.size } # => 42

Parameters:

  • default (T.type_parameter(:U))
  • blk (T.proc.params(value: OkType).returns(T.type_parameter(:U)))

Returns:

  • (T.type_parameter(:U))

See Also:



217
 
# File 'lib/r/result.rb', line 217

def map_or(default, &blk); end

#map_or_else(default, &blk) ⇒ T.type_parameter(:U)

This method is abstract.

Maps a R::Result[T, E] to U by applying fallback function default to a contained Err value, or function f to a contained Ok value.

This function can be used to unpack a successful result while handling an error.

Examples:

k = 21

x = T.let(R.ok("foo"), R::Result[String, String])
x.map_or_else(->(e) { k * 2 }) { |v| v.size } # => 3

x = T.let(R.err("bar"), R::Result[Integer, String])
x.map_or_else(->(e) { k * 2 }) { |v| v.size } # => 42

Parameters:

  • default (T.proc.params(value: ErrType).returns(T.type_parameter(:U)))
  • blk (T.proc.params(value: OkType).returns(T.type_parameter(:U)))

Returns:

  • (T.type_parameter(:U))

See Also:



244
 
# File 'lib/r/result.rb', line 244

def map_or_else(default, &blk); end

#ok ⇒ OkType?

This method is abstract.

Returns the value if the result is Ok, or nil if the result is Err.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.ok => 2

x = T.let(R.err("Nothing here"), R::Result[Integer, String])
x.ok => nil

Returns:

See Also:



138
 
# File 'lib/r/result.rb', line 138

def ok; end

#ok? ⇒ Boolean

This method is abstract.

Returns true if the result is Ok.

Examples:

x = T.let(R.ok(-3), R::Result[Integer, String])
x.ok? # => true

x = T.let(R.err("Some error message"), R::Result[Integer, String])
x.ok? # => false

Returns:

  • (Boolean)

See Also:



76
 
# File 'lib/r/result.rb', line 76

def ok?; end

#ok_and?(&blk) ⇒ Boolean

This method is abstract.

Returns true if the result is Ok and the value inside of it matches a predicate.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.ok_and? { |x| x > 1 } # => true

x = T.let(R.ok(0), R::Result[Integer, String])
x.ok_and? { |x| x > 1 } # => false

x = T.let(R.err("hey"), R::Result[Integer, String])
x.ok_and? { |x| x > 1 } # => false

Parameters:

  • blk (T.proc.params(value: OkType).returns(T::Boolean))

Returns:

  • (Boolean)

See Also:



93
 
# File 'lib/r/result.rb', line 93

def ok_and?(&blk); end

#on_err(&blk) ⇒ T.self_type

This method is abstract.

Calls the provided block with the contained error (if Err).

Returns self so this can be chained with #on_ok.

Examples:

msg = T.let(nil, T.nilable(String))
x = T.let(R.err("ohno"), R::Result[String, String])
x
  .on_ok  { |x| msg = "Success! #{x}" }
  .on_err { |x| msg = "Failure! #{x}" }
msg # => "Failure! ohno"

Parameters:

  • blk (T.proc.params(value: ErrType).void)

Returns:

  • (T.self_type)

See Also:



309
 
# File 'lib/r/result.rb', line 309

def on_err(&blk); end

#on_ok(&blk) ⇒ T.self_type

This method is abstract.

Calls the provided block with the contained value (if Ok).

Returns self so this can be chained with #on_err.

Examples:

msg = T.let(nil, T.nilable(String))
x = T.let(R.ok("42"), R::Result[String, String])
x
  .on_ok  { |x| msg = "Success! #{x}" }
  .on_err { |x| msg = "Failure! #{x}" }
msg # => "Success! 42"

Parameters:

  • blk (T.proc.params(value: OkType).void)

Returns:

  • (T.self_type)

See Also:



292
 
# File 'lib/r/result.rb', line 292

def on_ok(&blk); end

#or(res) ⇒ Result[T.any(OkType, T.type_parameter(:U)), T.type_parameter(:F)]

This method is abstract.

Returns res if the result is Err, otherwise returns the Ok value of self.

Arguments passed to or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use #or_else, which is lazily evaluated.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
y = T.let(R.err("late error"), R::Result[Integer, String])
x.or(y) # => R.ok(2)

x = T.let(R.err("early error"), R::Result[Integer, String])
y = T.let(R.ok(2), R::Result[Integer, String])
x.or(y) # => R.ok(2)

x = T.let(R.err("not a 2"), R::Result[Integer, String])
y = T.let(R.err("late error"), R::Result[Integer, String])
x.or(y) # => R.err("late error")

x = T.let(R.ok(2), R::Result[Integer, String])
y = T.let(R.ok(100), R::Result[Integer, String])
x.or(y) # => R.ok(2)

Parameters:

  • res (Result[T.type_parameter(:U), T.type_parameter(:F)])

Returns:

  • (Result[T.any(OkType, T.type_parameter(:U)), T.type_parameter(:F)])

See Also:



478
 
# File 'lib/r/result.rb', line 478

def or(res); end

#or_else(&blk) ⇒ Result[T.any(OkType, T.type_parameter(:U)), T.type_parameter(:F)]

This method is abstract.

Calls the block if the result is Err, otherwise returns the Ok value of self.

This function can be used for control flow based on R::Result values.

Examples:

module Example
  extend T::Sig

  sig { params(x: Integer).returns(R::Result[Integer, Integer])}
  def self.sq(x)
    R.ok(x * x)
  end

  sig { params(x: Integer).returns(R::Result[Integer, Integer])}
  def self.err(x)
    R.err(x)
  end
end

R.ok(2).or_else { |x| Example.sq(x) }.or_else { |x| Example.sq(x) } # => R.ok(2)
R.ok(2).or_else { |x| Example.err(x) }.or_else { |x| Example.sq(x) } # => R.ok(2)
R.err(3).or_else { |x| Example.sq(x) }.or_else { |x| Example.err(x) } # => R.ok(9)
R.err(3).or_else { |x| Example.err(x) }.or_else { |x| Example.err(x) } # => R.err(3)

Parameters:

  • blk (T.proc.params(arg: ErrType).returns(Result[T.type_parameter(:U), T.type_parameter(:F)]))

Returns:

  • (Result[T.any(OkType, T.type_parameter(:U)), T.type_parameter(:F)])

See Also:



512
 
# File 'lib/r/result.rb', line 512

def or_else(&blk); end

#try?(&blk) ⇒ OkType

This method is abstract.

Returns the contained Ok value or calls the block with the Err value.

This method is similar to #unwrap_or_else, but in case of an Err value, the block must short-circuit by either calling return (which will return from the enclosing method) or raising an exception.

This is useful to make error handling less tedious when dealing with many methods returning results.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.try? { |e| return e } # => 2

x = T.let(R.err("foo"), R::Result[Integer, String])
x.try? { |e| return e } # => return R.err("foo")

Parameters:

  • blk (T.proc.params(arg: Err[ErrType]).returns(T.noreturn))

Returns:

See Also:



582
 
# File 'lib/r/result.rb', line 582

def try?(&blk); end

#unwrap! ⇒ OkType

This method is abstract.

Returns the contained Ok value, or raises an UnwrapFailedError if the result is Err.

Because this function may raise an exception, its use is generally discouraged. Instead, prefer to use pattern matching and #ok, or call #unwrap_or or #unwrap_or_else.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.unwrap! # => 2

This example raises an UnwrapFailedError exception.

x = T.let(R.err("emergency failure"), R::Result[Integer, String])
x.unwrap! # => raise R::UnwrapFailedError.new("called `Result#unwrap!` on an `Err` value", "emergency failure")

Returns:

Raises:

See Also:



350
 
# File 'lib/r/result.rb', line 350

def unwrap!; end

#unwrap_err! ⇒ ErrType

This method is abstract.

Returns the contained Err value, or raises an UnwrapFailedError if the result is Ok.

Examples:

This example raises an UnwrapFailedError exception.

x = T.let(R.ok(2), R::Result[Integer, String])
x.unwrap_err! # => raise R::UnwrapFailedError.new("called `Result#unwrap_err!` on an `Ok` value", 2)
x = T.let(R.err("emergency failure"), R::Result[Integer, String])
x.unwrap_err! # => "emergency failure"

Returns:

Raises:

See Also:



385
 
# File 'lib/r/result.rb', line 385

def unwrap_err!; end

#unwrap_or(default) ⇒ OkType, T.type_parameter(:DefaultType)

This method is abstract.

Returns the contained Ok value or a provided default.

Arguments passed to unwrap_or are eagerly evaluated; if you are passing the result of a function call, it is recommended to use #unwrap_or_else, which is lazily evaluated.

Examples:

default = 2

x = T.let(R.ok(9), R::Result[Integer, String])
x.unwrap_or(default) # => 9

x = T.let(R.err("error"), R::Result[Integer, String])
x.unwrap_or(default) # => 2

Parameters:

  • default (T.type_parameter(:DefaultType))

Returns:

  • (OkType, T.type_parameter(:DefaultType))

See Also:



536
 
# File 'lib/r/result.rb', line 536

def unwrap_or(default); end

#unwrap_or_else(&blk) ⇒ OkType, T.type_parameter(:DefaultType)

This method is abstract.

Returns the contained Ok value or computes it from a closure.

Examples:

x = T.let(R.ok(2), R::Result[Integer, String])
x.unwrap_or_else(&:size) # => 2

x = T.let(R.err("foo"), R::Result[Integer, String])
x.unwrap_or_else(&:size) # => 3

Parameters:

  • blk (T.proc.params(arg: ErrType).returns(T.type_parameter(:DefaultType)))

Returns:

  • (OkType, T.type_parameter(:DefaultType))

See Also:



555
 
# File 'lib/r/result.rb', line 555

def unwrap_or_else(&blk); end