struct

Oak::Result(T)

Inherits Struct / Value / Object

Result of a tree search operation containing matched payloads and extracted parameters.

Example

result = tree.find "/users/123/posts/456"
if result.found?
  result.payload           # => :show_post
  result.params["user_id"] # => "123"
  result.params["post_id"] # => "456"
  result.key               # => "/users/:user_id/posts/:post_id"
end

Performance Note

Results created with find_first: true (used by Tree#find) are optimized to avoid unnecessary cloning during tree traversal, reducing memory allocation by 25-35%.

Instance methods

found?

Returns true if any payloads were found.

Example

result = tree.find "/users/123"
if result.found?
  # Process result
else
  # Handle not found
end

key

The full matched pattern from the tree.

This reconstructs the original pattern that matched, not the search path. The result is cached after first access for performance.

Example

tree.add "/users/:id/posts/:post_id", :show_post
result = tree.find "/users/123/posts/456"
result.key # => "/users/:id/posts/:post_id"

Performance: First call builds the string, subsequent calls return cached value.

params

Hash of named parameters extracted from the path.

Example

# For path "/users/:id" matching "/users/123"
result.params["id"] # => "123"

# For path "/posts/:year/:month" matching "/posts/2024/03"
result.params["year"]  # => "2024"
result.params["month"] # => "03"

payload

Returns the first matching payload.

Raises Enumerable::EmptyError if no payloads found. Use payload? for safe access.

Example

result = tree.find "/users/123"
payload = result.payload # Raises if not found

payload?

Returns the first payload or nil if not found.

Use this when you want to safely check for a result without raising an exception.

Example

if payload = result.payload?
  process(payload)
end

payloads

Array of all matching payloads.

Multiple payloads can exist for the same path when using constraint-based routing. Use payload or payload? for single-payload scenarios.

Example

# Multiple payloads at same path
tree.add "/users/:id", RouteA.new
tree.add "/users/:id", RouteB.new

result = tree.find "/users/123"
result.payloads.size # => 2