lent support

`lent` allows returning a (hidden) pointer to a member thus making
Result slightly more efficient when working with types that are
expensive to copy.

`lent` is enabled by default only on recent versions as Nim is known to
generate invalid code in earlier releases - how far back `lent` works
reliably depends on where Result appears but versions as recent as
1.6.14 have been known to have issues.

As such, `lent` support is conservatively enabled only for 2.0.8+ but
can be enabled for earlier versoins as well via a compile-time define.

results.nim

@@ -377,6 +377,18 @@ const
 
   resultsGenericsOpenSymWorkaroundHint* {.booldefine.} = true
 
+  resultsLent {.booldefine.} = (NimMajor, NimMinor, NimPatch) >= (2, 0, 8)
+    ## Enable return of `lent` types - this *mostly* works in Nim 1.6+ but there
+    ## have been edge cases reported as late as 1.6.14 - YMMV - conservatively,
+    ## `lent` is therefore enabled only with the latest Nim version at the time
+    ## of writing, where it could be verified to work with several large
+    ## applications
+
+when resultsLent:
+  template maybeLent(T: untyped): untyped = lent T
+else:
+  template maybeLent(T: untyped): untyped = T
+
 func raiseResultOk[T, E](self: Result[T, E]) {.noreturn, noinline.} =
   # noinline because raising should take as little space as possible at call
   # site
@@ -840,7 +852,14 @@ func `==`*[T0, T1](lhs: Result[T0, void], rhs: Result[T1, void]): bool {.inline.
     of false:
       true
 
-func value*[T, E](self: Result[T, E]): T {.inline.} =
+func value*[E](self: Result[void, E]) {.inline.} =
+  ## Fetch value of result if set, or raise Defect
+  ## Exception bridge mode: raise given Exception instead
+  ## See also: Option.get
+  withAssertOk(self):
+    discard
+
+func value*[T: not void, E](self: Result[T, E]): maybeLent T {.inline.} =
   ## Fetch value of result if set, or raise Defect
   ## Exception bridge mode: raise given Exception instead
   ## See also: Option.get
@@ -882,18 +901,28 @@ template unsafeValue*[E](self: Result[void, E]) =
   ## See also: `unsafeError`
   assert self.oResultPrivate # Emulate field access defect in debug builds
 
-func tryValue*[T, E](self: Result[T, E]): T {.inline.} =
+func tryValue*[E](self: Result[void, E]) {.inline.} =
   ## Fetch value of result if set, or raise
   ## When E is an Exception, raise that exception - otherwise, raise a ResultError[E]
   mixin raiseResultError
   case self.oResultPrivate
   of false:
     self.raiseResultError()
   of true:
-    when T isnot void:
-      self.vResultPrivate
+    discard
 
-func expect*[T, E](self: Result[T, E], m: string): T =
+func tryValue*[T: not void, E](self: Result[T, E]): maybeLent T {.inline.} =
+  ## Fetch value of result if set, or raise
+  ## When E is an Exception, raise that exception - otherwise, raise a ResultError[E]
+  mixin raiseResultError
+  case self.oResultPrivate
+  of false:
+    self.raiseResultError()
+  of true:
+    # TODO https://github.com/nim-lang/Nim/issues/22216
+    result = self.vResultPrivate
+
+func expect*[E](self: Result[void, E], m: string) =
   ## Return value of Result, or raise a `Defect` with the given message - use
   ## this helper to extract the value when an error is not expected, for example
   ## because the program logic dictates that the operation should never fail
@@ -910,8 +939,27 @@ func expect*[T, E](self: Result[T, E], m: string): T =
     else:
       raiseResultDefect(m)
   of true:
-    when T isnot void:
-      self.vResultPrivate
+    discard
+
+func expect*[T: not void, E](self: Result[T, E], m: string): maybeLent T =
+  ## Return value of Result, or raise a `Defect` with the given message - use
+  ## this helper to extract the value when an error is not expected, for example
+  ## because the program logic dictates that the operation should never fail
+  ##
+  ## ```nim
+  ## let r = Result[int, int].ok(42)
+  ## # Put here a helpful comment why you think this won't fail
+  ## echo r.expect("r was just set to ok(42)")
+  ## ```
+  case self.oResultPrivate
+  of false:
+    when E isnot void:
+      raiseResultDefect(m, self.eResultPrivate)
+    else:
+      raiseResultDefect(m)
+  of true:
+    # TODO https://github.com/nim-lang/Nim/issues/22216
+    result = self.vResultPrivate
 
 func expect*[T: not void, E](self: var Result[T, E], m: string): var T =
   (
@@ -939,7 +987,7 @@ func `$`*[T, E](self: Result[T, E]): string =
     else:
       "err(" & $self.eResultPrivate & ")"
 
-func error*[T, E](self: Result[T, E]): E =
+func error*[T](self: Result[T, void]) =
   ## Fetch error of result if set, or raise Defect
   case self.oResultPrivate
   of true:
@@ -948,19 +996,40 @@ func error*[T, E](self: Result[T, E]): E =
     else:
       raiseResultDefect("Trying to access error when value is set")
   of false:
-    when E isnot void:
-      self.eResultPrivate
+    discard
 
-func tryError*[T, E](self: Result[T, E]): E {.inline.} =
+func error*[T; E: not void](self: Result[T, E]): maybeLent E =
+  ## Fetch error of result if set, or raise Defect
+  case self.oResultPrivate
+  of true:
+    when T isnot void:
+      raiseResultDefect("Trying to access error when value is set", self.vResultPrivate)
+    else:
+      raiseResultDefect("Trying to access error when value is set")
+  of false:
+    # TODO https://github.com/nim-lang/Nim/issues/22216
+    result = self.eResultPrivate
+
+func tryError*[T](self: Result[T, void]) {.inline.} =
   ## Fetch error of result if set, or raise
   ## Raises a ResultError[T]
   mixin raiseResultOk
   case self.oResultPrivate
   of true:
     self.raiseResultOk()
   of false:
-    when E isnot void:
-      self.eResultPrivate
+    discard
+
+func tryError*[T; E: not void](self: Result[T, E]): maybeLent E {.inline.} =
+  ## Fetch error of result if set, or raise
+  ## Raises a ResultError[T]
+  mixin raiseResultOk
+  case self.oResultPrivate
+  of true:
+    self.raiseResultOk()
+  of false:
+    # TODO https://github.com/nim-lang/Nim/issues/22216
+    result = self.eResultPrivate
 
 template unsafeError*[T; E: not void](self: Result[T, E]): E =
   ## Fetch error of result if set, undefined behavior if unset
@@ -1488,23 +1557,23 @@ template `?`*[T, E](self: Result[T, E]): auto =
 
 # Collection integration
 
-iterator values*[T, E](self: Result[T, E]): T =
+iterator values*[T, E](self: Result[T, E]): maybeLent T =
   ## Iterate over a Result as a 0/1-item collection, returning its value if set
   case self.oResultPrivate
   of true:
     yield self.vResultPrivate
   of false:
     discard
 
-iterator errors*[T, E](self: Result[T, E]): E =
+iterator errors*[T, E](self: Result[T, E]): maybeLent E =
   ## Iterate over a Result as a 0/1-item collection, returning its error if set
   case self.oResultPrivate
   of false:
     yield self.eResultPrivate
   of true:
     discard
 
-iterator items*[T](self: Opt[T]): T =
+iterator items*[T](self: Opt[T]): maybeLent T =
   ## Iterate over an Opt as a 0/1-item collection, returning its value if set
   case self.oResultPrivate
   of true:

results.nimble

@@ -1,11 +1,11 @@
 # Package
 
-version       = "0.4.0"
-author        = "Jacek Sieka"
-description   = "Friendly, exception-free value-or-error returns, similar to Option[T]"
-license       = "MIT"
-skipDirs      = @["benchmarks", "tests"]
-installFiles  = @["results.nim"]
+version = "0.4.0"
+author = "Jacek Sieka"
+description = "Friendly, exception-free value-or-error returns, similar to Option[T]"
+license = "MIT"
+skipDirs = @["benchmarks", "tests"]
+installFiles = @["results.nim"]
 # Dependencies
 
 requires "nim >= 1.2"
@@ -15,12 +15,16 @@ proc test(env, path: string) =
   var lang = "c"
   if existsEnv"TEST_LANG":
     lang = getEnv"TEST_LANG"
-  exec "nim " & lang & " " & env &
-    " -r " & path
+  exec "nim " & lang & " " & env & " -r " & path
 
 task test, "Runs the test suite":
   for f in ["test_results.nim", "test_results2.nim"]:
-    for opt in ["", "-d:resultsGenericBindingWorkaround=false"]:
+    for opt in [
+      "-d:resultsGenericsOpenSym:false", "-d:resultsGenericsOpenSym:true",
+      "-d:resultsGenericsOpenSymWorkaround=false",
+      "-d:resultsGenericsOpenSymWorkaround=true", "-d:resultsLent=false",
+      "-d:resultsLent=true",
+    ]:
       test opt, "tests/" & f
       if (NimMajor, NimMinor) >= (2, 0):
         test opt & " --mm:refc", "tests/" & f