Yog.Pathfinding.Path (YogEx v0.70.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.

from_map(map)

Backward compatibility: convert from legacy map format.

from_tuple(arg)

Creates a path from the legacy tuple format {:path, nodes, weight}.

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.

to_map(path)

Convert to legacy map format.

to_tuple(path)

Converts the path to a legacy tuple format {:path, nodes, weight}.

Types

t()

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

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

from_map(map)

@spec from_map(map()) :: t()

Backward compatibility: convert from legacy map format.

from_tuple(arg)

@spec from_tuple({:path, [Yog.Model.node_id()], number()}) :: t()

Creates a path from the legacy tuple format {:path, nodes, weight}.

Examples

iex> path = Yog.Pathfinding.Path.from_tuple({:path, [1, 2, 3], 10})
iex> path.nodes
[1, 2, 3]
iex> path.weight
10

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()], number()) :: 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()], number(), 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()], number(), 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

to_map(path)

@spec to_map(t()) :: map()

Convert to legacy map format.

to_tuple(path)

@spec to_tuple(t()) :: {:path, [Yog.Model.node_id()], number()}

Converts the path to a legacy tuple format {:path, nodes, weight}.

Examples

iex> path = Yog.Pathfinding.Path.new([1, 2, 3], 10)
iex> Yog.Pathfinding.Path.to_tuple(path)
{:path, [1, 2, 3], 10}