Crate zstring

A crate to make zero-termiated FFI data easier to work with.

Literals

You can use this to make “literals” for passing to C. Imagine that there’s a C function such as the following from the Windows API:

FARPROC GetProcAddress(HMODULE hModule, LPCSTR  lpProcName);

We can expose this in Rust like this

use core::ffi::c_void;
use zstring::ZStr;

#[link(name = "Kernel32")]
extern "system" {
  pub fn GetProcAddress<'a>(
    hModule: *mut c_void, lpProcName: ZStr<'a>,
  ) -> *mut c_void;
}

and then call it as follows:

use zstring::zstr;

let proc = unsafe { GetProcAddress(module, zstr!("initscr")) };

Allocations

If the alloc feature is enabled then additional types which own their data are provided.

Say we have a C struct such as the following:

typedef struct VkInstanceCreateInfo {
  VkStructureType             sType;
  const void*                 pNext;
  VkInstanceCreateFlags       flags;
  const VkApplicationInfo*    pApplicationInfo;
  uint32_t                    enabledLayerCount;
  const char* const*          ppEnabledLayerNames;
  uint32_t                    enabledExtensionCount;
  const char* const*          ppEnabledExtensionNames;
} VkInstanceCreateInfo;

Normally it would very troublesome to get the data for ppEnabledLayerNames and ppEnabledExtensionNames arranged. However, if we use a Vec<ZString> then the pointer to the vec’s data will naturally line up with what we need.

Macros

zstr

Makes a ZStr<'static> value.

Structs

CharDecoder

Decodes byte sequences that are assumed to be utf-8.

ZBytesalloc

Owns a non-null pointer to some zero-terminated bytes.

ZBytesRef

Borrows a non-null const pointer to zero-terminated bytes.

ZBytesRefIter

Iterator over a ZBytesRef

ZStr

Borrows a non-null const pointer to zero-terminated bytes.

ZStringalloc

Owns a non-null pointer to zero-terminated bytes.

Enums

ZBytesCreationError

An error when you tried to make a z-bytes variant.