/c-utf8-rs

UTF-8 encoded C strings for Rust

Primary LanguageRustApache License 2.0Apache-2.0

C-Style UTF-8 Strings for Rust

Build status Crate version rustc version

This project makes it easier to establish guarantees when interfacing with nul-terminated C string APIs that require UTF-8 encoding.

Documentation

Become a Patron! Buy me a coffee

What is UTF-8?

UTF-8 is the character encoding chosen by much of the programming community since 2008, including Rust with its str primitive.

The usage of the main encodings on the web as recorded by Google

UTF-8 is capable of representing all 1,112,064 code points of the Unicode standard. Code points are variable-width, ranging from 8 to 32 bits wide.

Where does UTF-8 appear in C?

UTF-8 in SDL

The Simple DirectMedia Layer (SDL) library exposes certain APIs that only interface with UTF-8 encoded C strings. Here's a potential wrapper one could create around SDL:

impl Window {
    /* ... */

    fn title(&self) -> &CUtf8 {
        unsafe {
            let title = SDL_GetWindowTitle(self.inner);
            CUtf8::from_ptr(title).unwrap()
        }
    }

    fn set_title(&mut self, title: &CUtf8) {
        unsafe {
            SDL_SetWindowTitle(self.inner, title.as_ptr());
        }
    }

    /* ... */
}

Creating a &CUtf8 instance to interface with the above code can be done easily via the c_utf8! macro:

window.set_title(c_utf8!("MyAwesomeApp"));

Installation

This crate is available on crates.io and can be used by adding the following to your project's Cargo.toml:

[dependencies]
c_utf8 = "0.1.0"

and this to your crate root (lib.rs or main.rs):

#[macro_use]
extern crate c_utf8;

License

This project is licensed under either of

at your option.