Struct NodePath

pub struct NodePath { /* private fields */ }

Expand description

A pre-parsed scene tree path.

§Null bytes

Note that Godot ignores any bytes after a null-byte. This means that for instance "hello, world!" and "hello, world!\0 ignored by Godot" will be treated as the same string if converted to a NodePath.

§All string types

Intended use case	String type
General purpose	`GString`
Interned names	`StringName`
Scene-node paths	`NodePath`

§Godot docs

NodePath (stable)

Implementations§

§

impl NodePath

pub fn get_name(&self, index: usize) -> StringName

Returns the node name at position index.

If you want to get a property name instead, check out get_subname().

§Example

let path = NodePath::from("../RigidBody2D/Sprite2D");
godot_print!("{}", path.get_name(0)); // ".."
godot_print!("{}", path.get_name(1)); // "RigidBody2D"
godot_print!("{}", path.get_name(2)); // "Sprite"

§Panics (safeguards-balanced)

If index is out of bounds. In safeguards-disengaged level, a Godot error is generated and the result is unspecified (but safe).

pub fn get_subname(&self, index: usize) -> StringName

Returns the node subname (property) at position index.

If you want to get a node name instead, check out get_name().

§Example

let path = NodePath::from("Sprite2D:texture:resource_name");
godot_print!("{}", path.get_subname(0)); // "texture"
godot_print!("{}", path.get_subname(1)); // "resource_name"

§Panics (safeguards-balanced)

If index is out of bounds. In safeguards-disengaged level, a Godot error is generated and the result is unspecified (but safe).

pub fn get_name_count(&self) -> usize

Returns the number of node names in the path. Property subnames are not included.

pub fn get_subname_count(&self) -> usize

Returns the number of property names (“subnames”) in the path. Each subname in the node path is listed after a colon character (:).

pub fn get_total_count(&self) -> usize

Returns the total number of names + subnames.

This method does not exist in Godot and is provided in Rust for convenience.

pub fn hash_u32(&self) -> u32

Returns a 32-bit integer hash value representing the node path.

pub fn hash(&self) -> u32

👎Deprecated: renamed to hash_u32

pub fn subpath(&self, range: impl SignedRange) -> NodePath

Available on since_api=4.3 only.

Returns the range begin..exclusive_end as a new NodePath.

The absolute value of begin and exclusive_end will be clamped to get_total_count().

§Usage

For negative indices, use wrapped().

let path = NodePath::from("path/to/Node:with:props");

// If upper bound is not defined, `exclusive_end` will span to the end of the `NodePath`.
let sub = path.subpath(2..);
assert_eq!(sub, ":props".into());

// If either `begin` or `exclusive_end` are negative, they will be relative to the end of the `NodePath`.
let total_count = path.get_total_count();
let wrapped_sub = path.subpath(wrapped(0..-2));
let normal_sub = path.subpath(0..total_count - 2);
// Both are equal to "path/to/Node".
assert_eq!(wrapped_sub, normal_sub);

Godot equivalent: slice

§Compatibility

The slice() behavior for Godot <= 4.3 is unintuitive, see #100954. Godot-rust automatically changes this to the fixed version for Godot 4.4+, even when used in older versions. So, the behavior is always the same.

pub fn arg<T>(&self) -> impl AsArg<T>
where T: for<'a> From<&'a NodePath> + for<'a> ToGodot + 'a,

Use as argument for an impl AsArg<GString|StringName> parameter.

This is a convenient way to convert arguments of similar string types.

§Example

PackedStringArray can insert elements using AsArg<GString>, so let’s pass a NodePath:

let node_path = NodePath::from("Node2D/Label");

let mut array = PackedStringArray::new();
array.push(node_path.arg());

§Generic bounds

The bounds are implementation-defined and may change at any time. Do not use this function in a generic context requiring T – use the From trait or AsArg in that case.

§