C++ & Python API: add helpers for constructing an entity path

crates/re_log_types/src/path/mod.rs

@@ -25,7 +25,7 @@ pub use parse_path::PathParseError;
 /// Build a `Vec<EntityPathPart>`:
 /// ```
 /// # use re_log_types::*;
-/// let parts: Vec<EntityPathPart> = entity_path_vec!("foo", "bar");
+/// let parts: Vec<EntityPathPart> = entity_path_vec!("foo", 42, "my image!");
 /// ```
 #[macro_export]
 macro_rules! entity_path_vec {
@@ -34,16 +34,19 @@ macro_rules! entity_path_vec {
         ::std::vec::Vec::<$crate::EntityPathPart>::new()
     };
     ($($part: expr),* $(,)?) => {
-        vec![ $($crate::EntityPathPart::from($part),)+ ]
+        vec![ $($crate::EntityPathPart::from(
+            #[allow(clippy::str_to_string, clippy::string_to_string)]
+            $part.to_string()
+        ),)+ ]
     };
 }
 
 /// Build an [`EntityPath`] from parts that are _not_ escaped:
 ///
 /// ```
 /// # use re_log_types::*;
-/// let path: EntityPath = entity_path!("world", "my image!");
-/// assert_eq!(path, EntityPath::parse_strict(r"world/my\ image\!").unwrap());
+/// let path: EntityPath = entity_path!("world", 42, "my image!");
+/// assert_eq!(path, EntityPath::parse_strict(r"world/42/my\ image\!").unwrap());
 /// ```
 #[macro_export]
 macro_rules! entity_path {

crates/re_sdk/src/lib.rs

@@ -31,7 +31,9 @@ pub use self::recording_stream::{
 
 pub use re_sdk_comms::{default_flush_timeout, default_server_addr};
 
-pub use re_log_types::{entity_path, ApplicationId, EntityPath, StoreId, StoreKind};
+pub use re_log_types::{
+    entity_path, ApplicationId, EntityPath, EntityPathPart, StoreId, StoreKind,
+};
 
 pub use global::cleanup_if_forked_child;
 

crates/re_sdk/src/recording_stream.rs

@@ -719,16 +719,17 @@ impl RecordingStream {
     /// The data will be timestamped automatically based on the [`RecordingStream`]'s internal clock.
     /// See [`RecordingStream::set_time_sequence`] etc for more information.
     ///
+    /// The entity path can either be a string
+    /// (with special characters escaped, split on unescaped slashes)
+    /// or an [`EntityPath`] constructed with [`crate::entity_path`].
+    /// See <https://www.rerun.io/docs/concepts/entity-path> for more on entity paths.
+    ///
     /// See also: [`Self::log_timeless`] for logging timeless data.
     ///
     /// Internally, the stream will automatically micro-batch multiple log calls to optimize
     /// transport.
     /// See [SDK Micro Batching] for more information.
     ///
-    /// The entity path can either be a string
-    /// (with special characters escaped, split on unescaped slashes)
-    /// or an [`EntityPath`] constructed with [`crate::entity_path`].
-    ///
     /// # Example:
     /// ```ignore
     /// # use rerun;
@@ -791,6 +792,11 @@ impl RecordingStream {
     /// internal clock.
     /// See `RecordingStream::set_time_*` family of methods for more information.
     ///
+    /// The entity path can either be a string
+    /// (with special characters escaped, split on unescaped slashes)
+    /// or an [`EntityPath`] constructed with [`crate::entity_path`].
+    /// See <https://www.rerun.io/docs/concepts/entity-path> for more on entity paths.
+    ///
     /// Internally, the stream will automatically micro-batch multiple log calls to optimize
     /// transport.
     /// See [SDK Micro Batching] for more information.
@@ -830,6 +836,11 @@ impl RecordingStream {
     /// All of the batches should have the same number of instances, or length 1 if the component is
     /// a splat, or 0 if the component is being cleared.
     ///
+    /// The entity path can either be a string
+    /// (with special characters escaped, split on unescaped slashes)
+    /// or an [`EntityPath`] constructed with [`crate::entity_path`].
+    /// See <https://www.rerun.io/docs/concepts/entity-path> for more on entity paths.
+    ///
     /// Internally, the stream will automatically micro-batch multiple log calls to optimize
     /// transport.
     /// See [SDK Micro Batching] for more information.

crates/rerun_c/src/lib.rs

@@ -703,6 +703,39 @@ pub unsafe extern "C" fn rr_recording_stream_log(
     }
 }
 
+// ----------------------------------------------------------------------------
+// Private functions
+
+#[allow(unsafe_code)]
+#[no_mangle]
+pub unsafe extern "C" fn _rr_escape_entity_path_part(part: CStringView) -> *const c_char {
+    let Ok(part) = part.as_str("entity_path_part") else {
+        return std::ptr::null();
+    };
+
+    let part = re_sdk::EntityPathPart::from(part).to_string(); // escape the part
+
+    let Ok(part) = CString::new(part) else {
+        return std::ptr::null();
+    };
+
+    part.into_raw()
+}
+
+#[allow(unsafe_code)]
+#[no_mangle]
+pub unsafe extern "C" fn _rr_free_string(str: *mut c_char) {
+    if str.is_null() {
+        return;
+    }
+
+    // Free the string:
+    unsafe {
+        // SAFETY: `_rr_free_string` should
+        let _ = CString::from_raw(str);
+    }
+}
+
 // ----------------------------------------------------------------------------
 // Helper functions:
 

crates/rerun_c/src/rerun.h

@@ -412,6 +412,23 @@ extern void rr_recording_stream_log(
     rr_recording_stream stream, rr_data_row data_row, bool inject_time, rr_error* error
 );
 
+// ----------------------------------------------------------------------------
+// Private functions
+
+/// PRIVATE FUNCTION: do not use.
+///
+/// Escape a single part of an entity path, returning an new null-terminated string.
+///
+/// The returned string must be freed with `_rr_free_string`.
+///
+/// Returns `nullptr` on failure (e.g. invalid UTF8, ore null bytes in the string).
+extern char* _rr_escape_entity_path_part(rr_string part);
+
+/// PRIVATE FUNCTION: do not use.
+///
+/// Must only be called with the results from `_rr_escape_entity_path_part`.
+extern void _rr_free_string(char* string);
+
 // ----------------------------------------------------------------------------
 
 #ifdef __cplusplus

docs/code-examples/Cargo.toml

@@ -71,6 +71,10 @@ path = "depth_image_simple.rs"
 name = "disconnected_space"
 path = "disconnected_space.rs"
 
+[[bin]]
+name = "entity_path"
+path = "entity_path.rs"
+
 [[bin]]
 name = "image_simple"
 path = "image_simple.rs"

docs/code-examples/entity_path.cpp

@@ -0,0 +1,17 @@
+// Log a `TextDocument`
+
+#include <rerun.hpp>
+
+int main() {
+    const auto rec = rerun::RecordingStream("rerun_example_text_document");
+    rec.spawn().exit_on_failure();
+
+    rec.log(
+        R"(world/42/escaped\ string\!)",
+        rerun::TextDocument("This entity path was escaped manually")
+    );
+    rec.log(
+        rerun::new_entity_path({"world", std::to_string(42), "unescaped string!"}),
+        rerun::TextDocument("This entity path was provided as a list of unescaped strings")
+    );
+}

docs/code-examples/entity_path.py

@@ -0,0 +1,8 @@
+import rerun as rr
+
+rr.init("rerun_example_entity_path", spawn=True)
+
+rr.log(r"world/42/escaped\ string\!", rr.TextDocument("This entity path was escaped manually"))
+rr.log(
+    ["world", 42, "unescaped string!"], rr.TextDocument("This entity path was provided as a list of unescaped strings")
+)

docs/code-examples/entity_path.rs

@@ -0,0 +1,14 @@
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let rec = rerun::RecordingStreamBuilder::new("rerun_example_text_document").spawn()?;
+
+    rec.log(
+        r"world/42/escaped\ string\!",
+        &rerun::TextDocument::new("This entity path was escaped manually"),
+    )?;
+    rec.log(
+        rerun::entity_path!["world", 42, "unescaped string!"],
+        &rerun::TextDocument::new("This entity path was provided as a list of unescaped strings"),
+    )?;
+
+    Ok(())
+}

docs/code-examples/roundtrips.py

@@ -41,6 +41,7 @@
 opt_out_compare = {
     "arrow3d_simple": ["cpp", "py", "rust"], # TODO(#3206): examples use different RNGs
     "asset3d_out_of_tree": ["cpp", "py", "rust"], # float issues since calculation is done slightly differently (also, Python uses doubles)
+    "entity_path": ["cpp"], # C++ doesn't have helpers for escaping an entity path yet
     "mesh3d_partial_updates": ["cpp", "py", "rust"], # float precision issues
     "pinhole_simple": ["cpp", "py", "rust"], # TODO(#3206): examples use different RNGs
     "point2d_random": ["cpp", "py", "rust"], # TODO(#3206): examples use different RNGs

rerun_cpp/src/rerun.hpp

@@ -10,6 +10,7 @@
 #include "rerun/collection_adapter.hpp"
 #include "rerun/collection_adapter_builtins.hpp"
 #include "rerun/config.hpp"
+#include "rerun/entity_path.hpp"
 #include "rerun/error.hpp"
 #include "rerun/recording_stream.hpp"
 #include "rerun/result.hpp"

rerun_cpp/src/rerun/entity_path.cpp

@@ -0,0 +1,33 @@
+#include "entity_path.hpp"
+
+#include "c/rerun.h"
+#include "error.hpp"
+#include "string_utils.hpp"
+
+namespace rerun {
+    std::string new_entity_path(const std::vector<std::string_view>& path) {
+        if (path.empty()) {
+            return "/";
+        }
+
+        std::string result;
+
+        for (const auto& part : path) {
+            auto escaped_c_str = _rr_escape_entity_path_part(detail::to_rr_string(part));
+
+            if (escaped_c_str == nullptr) {
+                Error(ErrorCode::InvalidStringArgument, "Failed to escape entity path part")
+                    .handle();
+            } else {
+                if (!result.empty()) {
+                    result += "/"; // leading slash would also have be fine
+                }
+                result += escaped_c_str;
+                _rr_free_string(escaped_c_str);
+            }
+        }
+
+        return result;
+    }
+
+} // namespace rerun

rerun_cpp/src/rerun/entity_path.hpp

@@ -0,0 +1,13 @@
+#pragma once
+
+#include <string_view>
+#include <vector>
+
+namespace rerun {
+    /// Construct an entity path by escaping each part of the path.
+    ///
+    /// For instance, `rerun::new_entity_path({"world", 42, "unescaped string!"})` will return
+    /// `"world/42/escaped\ string\!"`.
+    std::string new_entity_path(const std::vector<std::string_view>& path);
+
+} // namespace rerun