Feature Request

Is your feature request related to a problem? Please describe clearly and concisely what is it.

I have a frequent need for something that is similar to Enumerable#find, but rather than returning the element for which the block is truthy, it returns that truthy block result itself.

This comes up when I have an array of objects that may or may not have a property set. The most recent need for this came up when implementing tool use for LLM APIs. The API response has an array of choices, each with a message, and those messages may or may not have a tool_calls array.

record Response, choices : Array(Choice)
record Choice, message : Message
record Message, tool_calls : Array(ToolCall)?
record ToolCall

response = Response.new([Choice.new(Message.new([ToolCall.new]))])

Describe the feature you would like, optionally illustrated by examples, and how it will solve the above problem.

What I've been using in my code to make this more expressive is a monkeypatch on Enumerable called find_first:

if tool_calls = response.choices.find_first &.message.tool_calls
  # find the tools for these calls, execute them, and send the results back to the API
end

Describe considered alternative solutions, and the reasons why you have not proposed them as a solution here.

Currently, as far as I can tell, at least, the only ways to do this involve either executing that same criteria again:

if choice_with_tool_call = response.choices.find &.message.tool_calls
  # the method chain for choice.message.tool_calls has to be repeated
  tool_calls = choice_with_tool_call
    .message
    .tool_calls
end

if tool_calls
  # find the tools for these calls, execute them, and send the results back to the API
end

Or this format with the block expanded

# or this
response.choices.each do |choice|
  if tool_calls = choice.message.tool_calls
    # find the tools for these calls, execute them, and send the results back to the API
    break
  end
end

These are both a lot more verbose, especially when there are multiple layers of these arrays. Having a method that returns the truthy value lets us use the shorthand block syntax and have a single expression that does all of these things smoothly.

Does it break backward compatibility, if yes then what's the migration path?

Nope. Purely additive.