Proposal: `@Result` to match cast builtins inference API

[candrewlee14]

Note: This is a formalized proposal based on discussion here: #5909 (comment)

Proposal started with the addition of @ResultType, like pub inline fn intCast(x: anytype) @ResultType.
It has been revised to use @Result and anytype in a function declarations, pub inline fn intCast(x: anytype) anytype

Problem: Builtin-exclusive inference API

With the recent merging of #16163, cast builtins now use an API that can't be replicated in regular userspace.
For example, take the std.fmt.parseInt function:

fn parseInt(comptime T: type, buf: []const u8, base: u8) std.fmt.ParseIntError!T

which currently has to be used like:

const foo = std.fmt.parseInt(u32, content, 10); // T must be explictly provided

compared to the usage of a cast builtin which can be used like

const bar: u32 = @intCast(x - y); // T is inferred

For the sake of consistency, it seems like parseInt should be able to be used in a similar fashion.

const bar: u32 = try std.fmt.parseInt(content, 10);

Proposal: @Result

The introduction of a builtin @Result could allow the declaration of std.fmt.parseInt to look like this:

fn parseInt(buf: []const u8, base: u8) std.fmt.ParseIntError!anytype {
    const T = @Result();
    ...
}

pub fn main() !void {
    const word1 = "12";
    const word2 = "42";
    const foo: u32 = try parseInt(word1, 10); // @Result is u32
    const bar: u64 = try parseInt(word2, 10); // @Result is u64 
    ...
}

Benefits

• This democratizes this kind of inference API currently exclusive to builtins.
• This may improve the consistency of callsites of functions with inferable types.
• Could benefit from cast-builtin-related improvements in type inference resolution, like in the case of something like:

  // possible builtin inference improvement
  const foo: u32 = @intCast(a + b) * @intCast(c);
  // potential downstream benefit
  const bar: u32 = try parseInt(word1, 10) + try parseInt(word2, 10);

• This also allows for the user to implement a function that looks like cast builtins from a caller's perspective, like this (via remove the destination type parameter from all cast builtins #5909 (comment)):

  pub inline fn intCast(x: anytype) anytype {
      return @intCast(x);
  }

Drawbacks

• Allows functions with identical functionality to be defined with 2 different APIs.
  When should a user define a function with @Result inference vs. having a comptime T: type parameter?
• ?

[N00byEdge]

When should a user define a function with @ResultType inference vs. having a comptime T: type parameter?

If you're returning T, never according to the new logic in zig, since you can just wrap it in an @as(T, f(...)).

One big drawback of this is that you're adding an invisible comptime parameter which silently adds more instantiations of your functions.

[rohlem]

I really like having custom casting functions - f.e. enhanced by comptime type checks specific to a use case.
With the benefits of the new inferred result type already visible in some code, I'd hate to give them up when switching from builtins to user-space functions.

In general the interface of @ResultType() providing the type of the result location to me seems minimal and sufficient, so fit for Zig.
However, the original proposal text glances over type unwrapping a bit, and I think it's a rough edge worth bringing up specifically:

The cast builtins currently already unwrap error unions and optionals: const c: error{Z}!?u8 = @intCast(@as(u16, 40)); deduces u8.
It would be easier to automatically do the same thing in @ResultType().

IMO hiding this step from the user (and discarding the additional information) would be a bit of a shame though, but I can't quite figure out how to make it work.

• If given the full type, userspace can implement these steps manually, f.e. in a helper function, making the return type something along the lines of NonOptionalPayload(@ResultType()).
  Note that this will practically work as long as NonOptionalPayload(@ResultType()) can implicitly coerce to the actual @ResultType(), T -> E!?T will always work.
• However, concluding from the last bullet point, the return type std.fmt.ParseIntError!@ResultType() constructed in one example would probably not work:
  No matter what R = @ResultType() we provide, the returned type E!R can never match the original R expected/deduced from the expression's result location.
  ... That is, unless result locations were propagated through (error-unwrapping if and) try expressions, and then stripped E!T -> T.

Maybe we would want both options, accessible as @ResultType() and @ResultTypeErrorUnionPayload()/@NonErrorResultType() ?
Or we choose not to provide the second first one, because behavior dependent on the callsite error set is too implicit.
Well, I can't really think of a non-confusing use case right now, so maybe it can actually be that simple.

---

One big drawback of this is that you're adding an invisible comptime parameter which silently adds more instantiations of your functions.

That is true; in my custom meta functions I often have a nicer interface in f that wraps an fImpl function with more verbose signature.
Especially when stripping a type (like ?T -> T) is done in userspace, you would probably want an Impl function like that to deduplicate the instantiation.
For me this is an okay approach in meta code, while in other areas it could get rather crowded.

Although for explicitness here's another idea: Instead of implicitly passing a type for @ResultType() to read from, we could instead make it an explicit parameter declaration:

fn(comptime R: type = @ResultType(), x: R) R {return x;}

Downsides:

• We don't have assignment syntax in arguments for any other use case yet.
• We declare a parameter slot that needs to be omitted from call sites.

The most in-line with current syntax would actually be a capture IMO:

// `keyword |capture|` has precedence in Zig
fn |R| f(x: R) R {return x;}
// could use an additional keyword
fn resulttype |R| f(x: R) R {return x;}
// (could use an operator, but no precedence of this in Zig, therefore I like it less)
fn -> |R| f(x: R) R {return x;}

// could also put it after the function name, so `fn <name>` remains Ctrl+F-/grep-/searchable
fn f |R| (x: R) R {return x;}

[Jarred-Sumner]

I like this idea a lot

What if it was infer or @Infer instead? One could imagine a future follow-up proposal for constraining the type to be an integer without specifying the size or implement a handful of functions like isLessThan, etc

[nektro]

related, infer keyword is proposed here #9260 too, the syntax actually pairs pretty well

[candrewlee14]

@Jarred-Sumner So you're thinking something like this instead?

fn parseInt(buf: []const u8, base: u8) std.fmt.ParseIntError!infer T {
    ...
}

The infer keyword might communicate the existence of multiple function instances better than a builtin @ResultType.

That could also be complementary if the infer syntax was already available to be used on parameters (as in the mentioned #9260).

fn foo(bar: infer T) infer K {
    ...
}

[bcrist]

I like this proposal as is, but I can also see a slight modification:

@ResultType() seems to function basically the same as anytype for parameters, in that they both implicitly make the function polymorphic. So reusing anytype in the function signature makes sense to me. @ResultType() would often still be necessary to access the actual result type within the function, but it could be made to only be usable within a function body.

Advantages:

• anytype is shorter and easier to read/type than @ResultType()
• @ResultType() can be used even when the result type is specified explicitly (removes redundancy when the result type in the function signature is a complicated comptime expression)
• anytype communicates intention better when used in a function signature (possibly subjective, but IMO it makes it clear that you need to use comptime checks if you want to limit what the result type might be, just like with anytype parameters)
• The @ResultType() intrinsic and inferred-return-type-via-anytype could be implemented as two separate, smaller features

Disadvantages:

• Perhaps slightly more difficult to learn - two different keywords to remember (in the context of return type inferrence; anytype already exists)

related: #447

[N00byEdge]

I think the anytype return type also is a valid option, but if so, @ResultType() is a terrible name and I would much rather have @ReturnType()

[AssortedFantasy]

I like @ReturnType() much better than @ResultType(). Its way clearer that the type is inferred from the function return location, wherever that may be.

[candrewlee14]

Hmm, personally both feel pretty similar. What about @CallsiteType?

[rohlem]

To me Return and Result can both be read to mean the result returned / decided by the function itself.
However, there is at least precedent for the term "Result Location Semantics" in Zig's nomenclature.

I agree CallSite (or maybe CallSiteDestination if there is some propagation through expressions like try) would be more explicit, imo preferable.
(nitpick note: Wiktionary lists both call site and callsite although the first seems preferred, Wikipedia also went with the first spelling. Langref is currently unopinionated at 5 vs 5 occurrences.)

[log0div0]

As it was already mentioned in other discussions it's a bit cumbersome to use @as to specify the return type of an expression. For example

std.log.info("{}", .{@as(u32, try std.fmt.parseInt(content, 10))})

In the same time Zig already has a perfect way to specify the type of a constant/variable/function-argument with a colon syntax:

const x: u32 = try std.fmt.parseInt(content, 10);

It would be really nice to allow the same syntax to specify the type of an arbitrary expression (like in Julia lang, but they use double colon for this purpose). So the example above will look like this:

std.log.info("{}", .{try std.fmt.parseInt(content, 10): !u32})

Another example from here with buildins. Old syntax:

return @intCast(@as(i64, @bitCast(val)));

New syntax:

return @intCast(@bitCast(val): i64);