https://github.com/nvzqz/c-utf8-rs
UTF-8 encoded C strings for Rust
https://github.com/nvzqz/c-utf8-rs
c rust string text unicode utf-8
Last synced: about 1 year ago
JSON representation
UTF-8 encoded C strings for Rust
- Host: GitHub
- URL: https://github.com/nvzqz/c-utf8-rs
- Owner: nvzqz
- License: apache-2.0
- Created: 2018-06-11T09:26:27.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2024-06-04T01:37:29.000Z (about 2 years ago)
- Last Synced: 2025-03-22T15:51:38.529Z (over 1 year ago)
- Topics: c, rust, string, text, unicode, utf-8
- Language: Rust
- Homepage: https://docs.rs/c_utf8/
- Size: 40 KB
- Stars: 7
- Watchers: 3
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# C-Style UTF-8 Strings for Rust
[![Build status][travis-badge]][travis]
This project makes it easier to establish guarantees when interfacing with
[nul-terminated C string][c_str] APIs that require [UTF-8] encoding.
[Documentation](https://docs.rs/c_utf8/)
## 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.
[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)][sdl] library exposes certain APIs that only
interface with UTF-8 encoded C strings. Here's a potential wrapper one could
create around SDL:
```rust
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`](https://docs.rs/c_utf8/*/c_utf8/struct.CUtf8.html)
instance to interface with the above code can be done easily via the
[`c_utf8!`](https://docs.rs/c_utf8/*/c_utf8/macro.c_utf8.html) macro:
```rust
window.set_title(c_utf8!("MyAwesomeApp"));
```
## Installation
This crate is available [on crates.io][crate] and can be used by adding the
following to your project's [`Cargo.toml`]:
```toml
[dependencies]
c_utf8 = "0.1.0"
```
and this to your crate root (`lib.rs` or `main.rs`):
```rust
#[macro_use]
extern crate c_utf8;
```
## License
This project is licensed under either of
- Apache License, Version 2.0 ([`LICENSE-APACHE`] or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT License ([`LICENSE-MIT`] or http://opensource.org/licenses/MIT)
at your option.
[`Cargo.toml`]: https://doc.rust-lang.org/cargo/reference/manifest.html
[`str`]: https://doc.rust-lang.org/std/primitive.str.html
[sdl]: https://en.wikipedia.org/wiki/Simple_DirectMedia_Layer
[c_str]: https://en.wikipedia.org/wiki/Null-terminated_string
[UTF-8]: https://en.wikipedia.org/wiki/UTF-8
[Unicode]: https://en.wikipedia.org/wiki/Unicode
[crate]: https://crates.io/crates/c_utf8
[travis]: https://travis-ci.com/nvzqz/c-utf8-rs
[travis-badge]: https://travis-ci.com/nvzqz/c-utf8-rs.svg?branch=master
[`LICENSE-APACHE`]: https://github.com/nvzqz/c-utf8-rs/blob/master/LICENSE-APACHE
[`LICENSE-MIT`]: https://github.com/nvzqz/c-utf8-rs/blob/master/LICENSE-MIT
