Struct TCString

#[repr(C)]
pub struct TCString { /* private fields */ }

***** TCString *****

TCString supports passing strings into and out of the TaskChampion API.

Rust Strings and C Strings

A Rust string can contain embedded NUL characters, while C considers such a character to mark the end of a string. Strings containing embedded NULs cannot be represented as a “C string” and must be accessed using tc_string_content_and_len and tc_string_clone_with_len. In general, these two functions should be used for handling arbitrary data, while more convenient forms may be used where embedded NUL characters are impossible, such as in static strings.

UTF-8

TaskChampion expects all strings to be valid UTF-8. tc_string_… functions will fail if given a *TCString containing invalid UTF-8.

Safety

The ptr field may be checked for NULL, where documentation indicates this is possible. All other fields in a TCString are private and must not be used from C. They exist in the struct to ensure proper allocation and alignment.

When a TCString appears as a return value or output argument, ownership is passed to the caller. The caller must pass that ownership back to another function or free the string.

Any function taking a TCString requires:

• the pointer must not be NUL;
• the pointer must be one previously returned from a tc_… function; and
• the memory referenced by the pointer must never be modified by C code.

Unless specified otherwise, TaskChampion functions take ownership of a TCString when it is given as a function argument, and the caller must not use or free TCStrings after passing them to such API functions.

A TCString with a NULL ptr field need not be freed, although tc_free_string will not fail for such a value.

TCString is not threadsafe.

typedef struct TCString {
  void *ptr;   // opaque, but may be checked for NULL
  size_t _u1;  // reserved
  size_t _u2;  // reserved
  uint8_t _u3; // reserved
} TCString;

Trait Implementations

impl Debug for TCString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for TCString

fn default() -> Self

Returns the “default value” for a type.