Adding `ffi_enum` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add ffi-enum

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

ffi-enum = "0.1.5"

The ffi_enum library will be automatically available globally. Read the ffi_enum library documentation.

Back to the crate overview.

Readme

ffi-enum

Simply write and use enums like rust native enums, freely passing through ffi.

Why not using `#[repr(C)]` and `#[non_exhaustive]` ?

Rust's #[repr(C)] is not fully equal to a C-abi enum, and it is still an undefined behavior when an enum defined with #[repr(C)] recieves a value that is not listed in the definition of enum, from ffi.
#[non_exhaustive] is only designed for inter-crate compatibility, while the compiler might still optimize based on the assumption that the binary pattern of an enum value is always in its defined range.

Why not existing alternatives?

The current alternatives mostly define complex DSL with function macros, which could be hard to read/maintain and not supported by rustfmt or rust-analyzer, and they do not support derive macros.

While this crate offers a nearly native experience by trying the best to fully mimic the behaviors of native enums, despite it requires non-exhaustive matching even inside the defining crate. FFi enums are defined with native rust enum item syntax with full support of formatting, code hint, and auto completion.

use ffi_enum::prelude::*;
use serde::{Deserialize, Serialize};

#[ffi_enum]
#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Animal {
    Cat,
    Dog,
}

fn main() {
    let json = serde_json::to_string(&Animal::Cat).unwrap();
    assert_eq!(json, "\"cat\"");
    let value: Animal = serde_json::from_str(&json).unwrap();
    assert_eq!(value, Animal::Cat);
    assert_eq!(value, serde_json::from_str("\"kitty\"").unwrap());
    assert!(serde_json::from_str::<Animal>("\"Rat\"").is_err());
    let value = Animal::from(2i16);
    let json = serde_json::to_string(&value).unwrap();
    assert_eq!(json, "\"<Unknown>\"");
    assert_eq!(usize::from(value), 2);
    assert_eq!(u8::try_from(value).unwrap(), 2);
}

Adding ffi_enum library as a dependency

Adding `ffi_enum` library as a dependency