Class ScyllaGraphPath

Represents the result of a graph path-finding search as an ordered sequence of node IDs and an accumulated traversal cost. An instance can be either valid - meaning a path was found - or invalid, meaning the search failed to connect source and target.

Inheritance
object
ScyllaGraphPath
Inherited Members
Namespace: Scylla.Core.Structures
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaGraphPath
Remarks

Validity: always check IsValid before consuming NodeIDs or TotalCost. An invalid path has no node IDs and a cost of zero. Use CreateInvalid() as a canonical empty failure result.

Construction: prefer the static factory methods (CreateInvalid(), CreateFromNodes(IList<int>, float)) for read-only consumers. Mutation methods (AddNode(int), SetTotalCost(float), SetValid(), Reverse()) are intended for use by ScyllaGraphAlgorithms when building path results; application code should treat path objects as read-only after they are returned from a search.

Pooling: the class is designed for reuse via ScyllaGenericObjectPool<T>. Call Reset() before returning an instance to the pool; it clears all state and trims the internal buffer when it exceeds a reasonable threshold.

Constructors

ScyllaGraphPath()

Initializes a new empty, invalid ScyllaGraphPath with no pre-allocated capacity. Use Reset() and the mutation methods to populate the path incrementally, or prefer the static factory methods (CreateInvalid(), CreateFromNodes(IList<int>, float)) for convenient one-shot construction.

Declaration
public ScyllaGraphPath()

ScyllaGraphPath(int)

Initializes a new empty, invalid ScyllaGraphPath with the specified initial capacity for the internal node ID list. Pre-allocating reduces reallocations when the expected path length is known in advance - for example when building paths in a grid graph where the maximum hop count is bounded by grid dimensions. Negative values are silently treated as zero.

Declaration
public ScyllaGraphPath(int capacity)
Parameters
Type Name Description
int capacity

The initial capacity (element slots) for the internal node ID list. Values less than zero are clamped to zero.

Properties

IsValid

Indicates whether this instance represents a successful path-finding result. true means a path from source to target was found and NodeIDs contains at least one node ID. false means the search failed (target unreachable, source not in graph, etc.) and NodeIDs is empty. Always check this property before accessing path content.

Declaration
public bool IsValid { get; }
Property Value
Type Description
bool

Length

The number of nodes in this path. A value of 0 means the path is empty (either invalid or a trivial zero-hop path from a node to itself). One hop between two adjacent nodes yields a Length of 2.

Declaration
public int Length { get; }
Property Value
Type Description
int

NodeIDs

The ordered sequence of node IDs that form this path, from source to target. The list is empty when IsValid is false. Do not modify the returned collection; use the mutation methods on this class if structural changes are required (e.g., during path construction inside an algorithm).

Declaration
public IReadOnlyList<int> NodeIDs { get; }
Property Value
Type Description
IReadOnlyList<int>

SourceID

The ID of the first node in the path (the search origin). Returns -1 if the path is empty (either invalid or not yet populated). Equivalent to NodeIDs[0] when Length is greater than zero.

Declaration
public int SourceID { get; }
Property Value
Type Description
int

TargetID

The ID of the last node in the path (the search destination). Returns -1 if the path is empty. Equivalent to NodeIDs[Length - 1] when Length is greater than zero. For a single-node path, equals SourceID.

Declaration
public int TargetID { get; }
Property Value
Type Description
int

TotalCost

The total accumulated edge-weight cost of this path, computed as the sum of Weight values along all traversed edges. For unweighted graphs all edge weights are 1.0f, so this equals the hop count minus one. Value is 0 for invalid or single-node paths.

Declaration
public float TotalCost { get; }
Property Value
Type Description
float

Methods

AddNode(int)

Appends a node ID to the end of the path. Call this in sequence from source to target during incremental path construction (e.g., inside a custom algorithm that builds upon ScyllaGraphAlgorithms). Does not affect IsValid or TotalCost; set those explicitly via SetValid() and SetTotalCost(float) after all nodes have been added.

Declaration
public void AddNode(int nodeID)
Parameters
Type Name Description
int nodeID

The node ID to append to the path.

CopyTo(Span<int>)

Copies node IDs into the provided span. Returns the number of IDs copied. If the destination is smaller than Length, only the first destination.Length node IDs are copied (silent truncation).

Declaration
public int CopyTo(Span<int> destination)
Parameters
Type Name Description
Span<int> destination

Destination span for node IDs.
Returns
Type Description
int

Number of node IDs actually copied (may be less than Length).

CreateFromNodes(IList<int>, float)

Creates a valid ScyllaGraphPath from an existing ordered list of node IDs and a precomputed total traversal cost. The node IDs are copied into the new path; modifying nodeIDs after this call does not affect the returned path. IsValid will be true on the returned instance.

Declaration
public static ScyllaGraphPath CreateFromNodes(IList<int> nodeIDs, float totalCost)
Parameters
Type Name Description
IList<int> nodeIDs

An ordered list of node IDs from source (index 0) to target (last index). Must not be null.
float totalCost

The total accumulated edge-weight cost of the path. Pass 0 for single-node or trivially zero-cost paths.
Returns
Type Description
ScyllaGraphPath

A new valid path containing a copy of nodeIDs.

CreateInvalid()

Creates an invalid, empty ScyllaGraphPath that represents a failed or unreachable search result. IsValid will be false, NodeIDs will be empty, and TotalCost will be 0. Uses zero initial list capacity to minimise allocation overhead for failure cases.

Declaration
public static ScyllaGraphPath CreateInvalid()
Returns
Type Description
ScyllaGraphPath

A new invalid path instance.

GetNodeAt(int)

Returns the node ID at the specified zero-based position in the path. Use this when you need a single node ID by position rather than iterating the full NodeIDs list. For sequential traversal prefer iterating NodeIDs directly to avoid per-element bounds-check overhead.

Declaration
public int GetNodeAt(int index)
Parameters
Type Name Description
int index

Zero-based index into the path. 0 is SourceID; Length - 1 is TargetID.
Returns
Type Description
int

The node ID stored at position index.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if the path is empty, or if index is negative or greater than or equal to Length.

Reset()

Resets the path to an empty, invalid state. Use this when pooling to prepare for reuse. Trims excess capacity above Scylla.Core.Structures.ScyllaGraphPath.MAX_RETAINED_CAPACITY to prevent memory leaks from very long paths while preserving reasonable capacity for reuse.

Declaration
public void Reset()

Reverse()

Reverses the order of node IDs in-place so the path runs from what was previously the target to what was previously the source. This is commonly called after path reconstruction from a back-pointer table (e.g., Dijkstra builds the path backwards from target to source by following ParentID links, then calls Reverse() to produce the canonical source-to-target order).

Declaration
public void Reverse()

SetTotalCost(float)

Sets the TotalCost of this path to the specified value. Call this after all nodes have been added and the final accumulated cost is known. This method does not mark the path as valid; call SetValid() separately.

Declaration
public void SetTotalCost(float cost)
Parameters
Type Name Description
float cost

The total accumulated edge-weight cost to assign to this path.

SetValid()

Marks this path as valid by setting IsValid to true. Call this after all node IDs have been added via AddNode(int) and the total cost has been set via SetTotalCost(float) to signal to consumers that the path represents a successful search result.

Declaration
public void SetValid()

ToString()

Declaration
public override string ToString()
Returns
Type Description
string
Overrides

Extension Methods

See Also