rename TCStrings to TCStringList

lib/src/stringlist.rs

@@ -0,0 +1,72 @@
+use crate::string::TCString;
+use crate::traits::*;
+use std::ptr::NonNull;
+
+/// TCStringList represents a list of strings.
+///
+/// The content of this struct must be treated as read-only.
+#[repr(C)]
+pub struct TCStringList {
+    /// number of strings in items
+    len: libc::size_t,
+
+    /// total size of items (internal use only)
+    _capacity: libc::size_t,
+
+    /// TCStringList representing each string. these remain owned by the TCStringList instance and will
+    /// be freed by tc_string_list_free.  This pointer is never NULL for a valid TCStringList, and the
+    /// *TCStringList at indexes 0..len-1 are not NULL.
+    items: *const NonNull<TCString<'static>>,
+}
+
+impl PointerArray for TCStringList {
+    type Element = TCString<'static>;
+
+    unsafe fn from_raw_parts(items: *const NonNull<Self::Element>, len: usize, cap: usize) -> Self {
+        TCStringList {
+            len,
+            _capacity: cap,
+            items,
+        }
+    }
+
+    fn into_raw_parts(self) -> (*const NonNull<Self::Element>, usize, usize) {
+        (self.items, self.len, self._capacity)
+    }
+}
+
+/// Free a TCStringList instance.  The instance, and all TCStringList it contains, must not be used after
+/// this call.
+///
+/// When this call returns, the `items` pointer will be NULL, signalling an invalid TCStringList.
+#[no_mangle]
+pub unsafe extern "C" fn tc_string_list_free(tcstrings: *mut TCStringList) {
+    debug_assert!(!tcstrings.is_null());
+    // SAFETY:
+    //  - *tcstrings is a valid TCStringList (caller promises to treat it as read-only)
+    let strings = unsafe { TCStringList::take_from_arg(tcstrings, TCStringList::null_value()) };
+    TCStringList::drop_pointer_vector(strings);
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn empty_array_has_non_null_pointer() {
+        let tcstrings = TCStringList::return_val(Vec::new());
+        assert!(!tcstrings.items.is_null());
+        assert_eq!(tcstrings.len, 0);
+        assert_eq!(tcstrings._capacity, 0);
+    }
+
+    #[test]
+    fn free_sets_null_pointer() {
+        let mut tcstrings = TCStringList::return_val(Vec::new());
+        // SAFETY: testing expected behavior
+        unsafe { tc_string_list_free(&mut tcstrings) };
+        assert!(tcstrings.items.is_null());
+        assert_eq!(tcstrings.len, 0);
+        assert_eq!(tcstrings._capacity, 0);
+    }
+}