samples: Add red-black tree sample program

Introduce an example program to demonstrate
how to use the red-black tree API.

Signed-off-by: James Roy <rruuaanng@outlook.com>

samples/data_structures/rbtree/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(rbtree)
+
+target_sources(app PRIVATE src/main.c)

samples/data_structures/rbtree/README.rst

@@ -0,0 +1,60 @@
+.. zephyr:code-sample:: red-black-tree
+   :name: Red-Black Tree Data Structure
+
+   Use a red-black tree data structure in a Zephyr application.
+
+Overview
+********
+
+This sample demonstrates how to use the Red-Black Tree (rbtree) data structure
+in a Zephyr application.
+The example shows basic rbtree operations such as insert, remove and foreach.
+
+Building and Running
+********************
+
+To build and run this sample on a supported board:
+
+.. code-block:: console
+
+   west build -b <your_board> samples/data_structures/rbtree
+   west flash
+
+Replace ``<your_board>`` with your actual board name (e.g., ``native_sim``).
+
+Sample Output
+*************
+
+On startup, the sample application will perform a sequence of rbtree operations
+and print the results. Expected output resembles:
+
+.. code-block:: console
+
+        *** Booting Zephyr OS build gd2a5c1ca82f0 ***
+        insert n=1 rb=0x105004
+        insert n=3 rb=0x105010
+        insert n=2 rb=0x10501c
+        insert n=5 rb=0x105028
+        insert n=4 rb=0x105034
+        max=1 min=5
+        rbtree elements:
+        n=5
+        n=4
+        n=3
+        n=2
+        n=1
+        removed max=1
+        removed min=5
+        rbtree after removal:
+        n=4
+        n=3
+        n=2
+        Done
+
+
+Requirements
+************
+
+No external hardware is required to run this sample.
+It runs on any Zephyr-supported board with standard console output, or
+native_sim.

samples/data_structures/rbtree/prj.conf

@@ -0,0 +1 @@
+# nothing here

samples/data_structures/rbtree/sample.yaml

@@ -0,0 +1,22 @@
+# Copyright (c) 2025 James Roy <rruuaanng@outlook.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+sample:
+  description: zephyr red-black tree library application
+  name: red-black tree
+tests:
+  sample.data_structures.red-black-tree:
+    tags:
+      - data_structures
+    harness: console
+    integration_platforms:
+      - native_sim
+    harness_config:
+      type: multi_line
+      ordered: false
+      regex:
+        - "max=5 min=1"
+        - "removed max=5"
+        - "removed min=1"
+        - "Done"

samples/data_structures/rbtree/src/main.c

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2025 James Roy <rruuaanng@outlook.com>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h>
+#include <zephyr/kernel.h>
+#include <zephyr/sys/rb.h>
+#include <zephyr/sys/printk.h>
+
+struct user_data {
+	int n;
+	struct rbnode rbnode;
+} data_list[5] = {{.n = 1}, {.n = 3}, {.n = 2}, {.n = 5}, {.n = 4}};
+
+bool user_data_lessthan_func(struct rbnode *a, struct rbnode *b)
+{
+	struct user_data *n1 = CONTAINER_OF(a, struct user_data, rbnode);
+	struct user_data *n2 = CONTAINER_OF(b, struct user_data, rbnode);
+
+	return n1->n < n2->n;
+}
+
+int main(void)
+{
+	struct rbnode *n;
+	struct rbnode *max, *min;
+
+	struct rbtree tree = { .lessthan_fn = user_data_lessthan_func };
+
+	for (int i = 0; i < ARRAY_SIZE(data_list); i++) {
+		printk("insert n=%d rb=%p\n", data_list[i].n, &data_list[i].rbnode);
+		rb_insert(&tree, &(data_list[i].rbnode));
+	}
+
+	max = rb_get_max(&tree);
+	min = rb_get_min(&tree);
+	struct user_data *max_node = CONTAINER_OF(max, struct user_data, rbnode);
+	struct user_data *min_node = CONTAINER_OF(min, struct user_data, rbnode);
+
+	printk("max=%d min=%d\n", max_node->n, min_node->n);
+
+	printk("rbtree elements:\n");
+	RB_FOR_EACH(&tree, n) {
+		struct user_data *ent = CONTAINER_OF(n, struct user_data, rbnode);
+
+		printk("n=%d\n", ent->n);
+	}
+
+	printk("removed max=%d\n", max_node->n);
+	printk("removed min=%d\n", min_node->n);
+	rb_remove(&tree, max);
+	rb_remove(&tree, min);
+
+	printk("rbtree after removal:\n");
+	RB_FOR_EACH(&tree, n) {
+		struct user_data *ent = CONTAINER_OF(n, struct user_data, rbnode);
+
+		printk("n=%d\n", ent->n);
+	}
+
+	printk("Done\n");
+	return 0;
+}