struct Oak::Result(T)

Overview

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%.

Defined in:

oak/result.cr

Instance Method Summary

Instance Method Detail

def found? #

Returns true if any payloads were found.

Example

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

[View source]
def 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.


[View source]
def 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"

[View source]
def 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

[View source]
def 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

[View source]
def 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

[View source]