Yog.Pathfinding.Path (YogEx v0.97.0)

Result of pathfinding algorithms (Dijkstra, A*, BFS, etc.).

Represents a path through the graph as a sequence of nodes with a total weight and metadata about how the path was found.

Fields

nodes - Ordered list of node IDs forming the path
weight - Total weight/cost of the path
algorithm - Name of the algorithm used (optional)
metadata - Optional metadata (visited nodes, iterations, time, etc.)

Examples

iex> path = %Yog.Pathfinding.Path{
...>   nodes: [1, 2, 3, 4],
...>   weight: 15.5,
...>   algorithm: :dijkstra
...> }
iex> path.weight
15.5
iex> Yog.Pathfinding.Path.length(path)
3
iex> Yog.Pathfinding.Path.start(path)
1
iex> Yog.Pathfinding.Path.finish(path)
4

Summary

Types

t()

Functions

at(path, index)

Returns the node at a specific position in the path (0-indexed).

contains?(path, node_id)

Checks if a node is part of the path.

empty?(path)

Checks if the path is empty (contains no nodes).

finish(path)

Returns the ending node of the path.

hydrate_path(graph, node_ids)

Hydrates a path of node IDs with their corresponding edge attributes from the graph.

length(path)

Returns the length of the path (number of edges).

new(nodes, weight)

Creates a new path result.

new(nodes, weight, algorithm)

Creates a new path result with algorithm name.

new(nodes, weight, algorithm, metadata)

Creates a new path result with algorithm and metadata.

reverse(path)

Reverses the path (both node order and preserves weight).

start(path)

Returns the starting node of the path.

Types

t()

@type t() :: %Yog.Pathfinding.Path{
  algorithm: atom(),
  metadata: map(),
  nodes: [Yog.Model.node_id()],
  weight: any()
}

Functions

at(path, index)

@spec at(t(), non_neg_integer()) :: Yog.Model.node_id() | nil

Returns the node at a specific position in the path (0-indexed).

Returns nil if the index is out of bounds.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> Yog.Pathfinding.Path.at(path, 0)
1
iex> Yog.Pathfinding.Path.at(path, 2)
3
iex> Yog.Pathfinding.Path.at(path, 5)
nil

contains?(path, node_id)

@spec contains?(t(), Yog.Model.node_id()) :: boolean()

Checks if a node is part of the path.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> Yog.Pathfinding.Path.contains?(path, 2)
true
iex> Yog.Pathfinding.Path.contains?(path, 5)
false

empty?(path)

@spec empty?(t()) :: boolean()

Checks if the path is empty (contains no nodes).

Examples

iex> path = Yog.Pathfinding.Path.new([], 0)
iex> Yog.Pathfinding.Path.empty?(path)
true
iex> path = Yog.Pathfinding.Path.new([1, 2], 5)
iex> Yog.Pathfinding.Path.empty?(path)
false

finish(path)

@spec finish(t()) :: Yog.Model.node_id() | nil

Returns the ending node of the path.

Returns nil if the path is empty.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> Yog.Pathfinding.Path.finish(path)
3
iex> path = Yog.Pathfinding.Path.new([], 0)
iex> Yog.Pathfinding.Path.finish(path)
nil

hydrate_path(graph, node_ids)

@spec hydrate_path(Yog.Model.graph(), [Yog.Model.node_id()]) :: list()

Hydrates a path of node IDs with their corresponding edge attributes from the graph.

This function transforms a list of node IDs representing a path (e.g., [A, B, C]) into a list of edge triplets {u, v, data} by looking up the edge metadata for each consecutive pair in the graph.

This is particularly useful when you have a sequence of nodes (from a pathfinding algorithm) and you need to "hydrate" it with the actual edge weights or attributes used to traverse it.

Examples

iex> graph =
...>   Yog.directed()
...>   |> Yog.add_edge_ensure(from: 1, to: 2, with: 10, default: nil)
...>   |> Yog.add_edge_ensure(from: 2, to: 3, with: 5, default: nil)
iex> path = [1, 2, 3]
iex> Yog.Pathfinding.Path.hydrate_path(graph, path)
[{1, 2, 10}, {2, 3, 5}]

length(path)

@spec length(t()) :: non_neg_integer()

Returns the length of the path (number of edges).

The length is the number of nodes minus 1. An empty path or single-node path has length 0.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3, 4], 15)
iex> Yog.Pathfinding.Path.length(path)
3
iex> path = Yog.Pathfinding.Path.new([1], 0)
iex> Yog.Pathfinding.Path.length(path)
0
iex> path = Yog.Pathfinding.Path.new([], 0)
iex> Yog.Pathfinding.Path.length(path)
0

new(nodes, weight)

@spec new([Yog.Model.node_id()], any()) :: t()

Creates a new path result.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> path.nodes
[1, 2, 3]
iex> path.weight
10

new(nodes, weight, algorithm)

@spec new([Yog.Model.node_id()], any(), atom()) :: t()

Creates a new path result with algorithm name.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10, :dijkstra)
iex> path.algorithm
:dijkstra

new(nodes, weight, algorithm, metadata)

@spec new([Yog.Model.node_id()], any(), atom(), map()) :: t()

Creates a new path result with algorithm and metadata.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10, :astar, %{visited: 42})
iex> path.metadata
%{visited: 42}

reverse(path)

@spec reverse(t()) :: t()

Reverses the path (both node order and preserves weight).

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10, :dijkstra)
iex> reversed = Yog.Pathfinding.Path.reverse(path)
iex> reversed.nodes
[3, 2, 1]
iex> reversed.weight
10
iex> reversed.algorithm
:dijkstra

start(path)

@spec start(t()) :: Yog.Model.node_id() | nil

Returns the starting node of the path.

Returns nil if the path is empty.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> Yog.Pathfinding.Path.start(path)
1
iex> path = Yog.Pathfinding.Path.new([], 0)
iex> Yog.Pathfinding.Path.start(path)
nil