sys: Add Disjoint-set data structure

Add a set of Disjoint-set functions (`find`, `union`)
to handle queries between sets.

Signed-off-by: James Roy <[email protected]>

Author: rruuaanng

include/zephyr/sys/uf.h

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025 James Roy <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @defgroup union_find_apis Disjoint-set
+ * @ingroup datastructure_apis
+ *
+ * @brief Disjoint-set implementation
+ *
+ * This implements a disjoint-set (union-find) that guarantees
+ * O(alpha(n)) runtime for all operations. The algorithms and
+ * naming are conventional per existing academic and didactic
+ * implementations, c.f.:
+ *
+ * https://en.wikipedia.org/wiki/Disjoint-set_data_structure
+ *
+ * @{
+ */
+
+#ifndef ZEPHYR_INCLUDE_SYS_UF_H_
+#define ZEPHYR_INCLUDE_SYS_UF_H_
+
+#include <stdint.h>
+
+/**
+ * @brief Disjoint-set node structure
+ */
+struct uf_node {
+	/** @cond INTERNAL_HIDDEN */
+	struct uf_node *parent;
+	uint16_t rank;
+	/** @endcond */
+};
+
+/**
+ * @brief Initialize a disjoint-set.
+ */
+static inline void uf_makeset(struct uf_node *node)
+{
+	node->parent = node;
+	node->rank = 0;
+}
+
+/**
+ * @brief Find the root of the disjoint-set.
+ */
+struct uf_node *uf_find(struct uf_node *node);
+
+/**
+ * @brief Merge two nodes into the same disjoint-set.
+ */
+void uf_union(struct uf_node *node1, struct uf_node *node2);
+
+/** @} */
+
+#endif /* ZEPHYR_INCLUDE_SYS_UF_H_ */

lib/utils/uf.c

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2025 James Roy <[email protected]>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/sys/uf.h>
+
+struct uf_node *uf_find(struct uf_node *node)
+{
+	while (node != node->parent) {
+		node->parent = node->parent->parent;
+		node = node->parent;
+	}
+
+	return node;
+}
+
+void uf_union(struct uf_node *node1, struct uf_node *node2)
+{
+	struct uf_node *root1 = uf_find(node1);
+	struct uf_node *root2 = uf_find(node2);
+
+	if (root1 == root2) {
+		return;
+	}
+
+	if (root1->rank < root2->rank) {
+		root1->parent = root2;
+	} else if (root1->rank > root2->rank) {
+		root2->parent = root1;
+	} else {
+		root2->parent = root1;
+		root1->rank++;
+	}
+}