From db0c3938a0be68c71ad90692491b79793388f141 Mon Sep 17 00:00:00 2001 From: Christopher Cole Date: Thu, 9 Feb 2023 01:42:02 -0800 Subject: [PATCH] Rewrite docs section about unsafe code This addresses feedback from #30 --- README.md | 22 ++++++++-------------- src/lib.rs | 18 ++++++------------ 2 files changed, 14 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e7780b6..36d162b 100644 --- a/README.md +++ b/README.md @@ -11,22 +11,16 @@ The `elf` crate provides a pure-safe-rust interface for reading ELF object files # Capabilities -### ✨ No unsafe code ✨ -With memory safety a core goal, this crate contains zero unsafe code blocks, so you -can trust in rust's memory safety guarantees without also having to trust this -library developer as having truly been "right" in why some unsafe block was safe. 💃 - -Many of the other rust ELF parsers out there contain bits of unsafe code deep -down or in dependencies to reinterpret/transmute byte contents as structures in -order to drive zero-copy parsing. They're slick, and there's typically -appropriate checking to validate the assumptions to make that unsafe code work, -but nevertheless it introduces unsafe code blocks at the core of the parsers. This -crate strives to serve as an alternate implementation with zero unsafe blocks, while -also biasing for performance. +### ✨ Uses only safe interfaces ✨ +With memory safety a core goal, this crate contains zero unsafe code blocks of +its own and only uses safe interface methods from core and std, so you can +trust in rust's memory safety guarantees without also having to trust this +library developer as having truly been "right" in why some unsafe block was +safe. 💃 Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. -See +See: ### ✨ Fuzz Tested ✨ Various parts of the library are fuzz tested for panics and crashes (see `fuzz/`). @@ -140,4 +134,4 @@ let (sym_idx, sym) = hash_table.find(name, &dynsyms, &strtab) assert_eq!(sym_idx, 2); assert_eq!(strtab.get(sym.st_name as usize).unwrap(), "memset"); assert_eq!(sym, dynsyms.get(sym_idx).unwrap()); -``` \ No newline at end of file +``` diff --git a/src/lib.rs b/src/lib.rs index 4afc12a..7b0e180 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,18 +2,12 @@ //! //! # Capabilities //! -//! ### ✨ No unsafe code ✨ -//! With memory safety a core goal, this crate contains zero unsafe code blocks, so you -//! can trust in rust's memory safety guarantees without also having to trust this -//! library developer as having truly been "right" in why some unsafe block was safe. 💃 -//! -//! Many of the other rust ELF parsers out there contain bits of unsafe code deep -//! down or in dependencies to reinterpret/transmute byte contents as structures in -//! order to drive zero-copy parsing. They're slick, and there's typically -//! appropriate checking to validate the assumptions to make that unsafe code work, -//! but nevertheless it introduces unsafe code blocks at the core of the parsers. This -//! crate strives to serve as an alternate implementation with zero unsafe blocks, while -//! also biasing for performance. +//! ### ✨ Uses only safe interfaces ✨ +//! With memory safety a core goal, this crate contains zero unsafe code blocks +//! of its own and only uses safe interface methods from core and std, so you can +//! trust in rust's memory safety guarantees without also having to trust this +//! library developer as having truly been "right" in why some unsafe block was +//! safe. 💃 //! //! Note: I'd love to see this crate be enhanced further once rust provides safe transmutes. //!