deme by name

demes/src/ffi.rs

@@ -332,6 +332,11 @@ pub unsafe extern "C" fn demes_graph_num_demes(graph: *const Graph) -> usize {
 /// # Safety
 ///
 /// `graph` must point to a non-NULL [`Graph`]
+///
+/// # Note
+///
+/// The return value is owned by rust and **MUST NOT** be modified or freed
+/// by client code.
 #[no_mangle]
 pub unsafe extern "C" fn demes_graph_deme(graph: *const Graph, at: usize) -> *mut Deme {
     match (*graph).get_deme(at) {
@@ -340,6 +345,28 @@ pub unsafe extern "C" fn demes_graph_deme(graph: *const Graph, at: usize) -> *mu
     }
 }
 
+#[no_mangle]
+pub unsafe extern "C" fn demes_graph_deme_by_name(
+    graph: *const Graph,
+    name: *const c_char,
+    error: *mut FFIError,
+) -> *mut Deme {
+    if (*error).error.is_some() {
+        return std::ptr::null_mut();
+    }
+    let n = CStr::from_ptr(name);
+    match n.to_str() {
+        Ok(n) => match (*graph).get_deme(n) {
+            Some(d) => (d as *const Deme) as *mut Deme,
+            None => std::ptr::null_mut(),
+        },
+        Err(e) => {
+            (*error).error = Some(ErrorDetails::NonLibraryError(Box::new(e)));
+            std::ptr::null_mut()
+        }
+    }
+}
+
 /// Return a string representation of the [`Graph`]
 ///
 /// # Returns
@@ -464,6 +491,10 @@ pub unsafe extern "C" fn demes_deme_get_ancestors(deme: *const Deme) -> *mut usi
     rv
 }
 
+/// # Note
+///
+/// The return value is owned by rust and **MUST NOT** be modified or freed
+/// by client code.
 #[no_mangle]
 pub unsafe extern "C" fn demes_deme_proportions(deme: *const Deme) -> *mut f64 {
     (*deme).proportions().as_ptr().cast::<f64>() as _
@@ -518,6 +549,10 @@ pub unsafe extern "C" fn demes_deme_size_at(
     }
 }
 
+/// # Note
+///
+/// The return value is owned by rust and **MUST NOT** be modified or freed
+/// by client code.
 #[no_mangle]
 pub unsafe extern "C" fn demes_deme_epoch(deme: *const Deme, at: usize) -> *mut Epoch {
     // NOTE: we work thru the slice b/c Deme::get_epoch returns a copy.