cstr-argument-0.1.1/.gitignore010060000017500001750000000002001315443177400145060ustar0000000000000000.* !.gitignore !.gitmodules !.travis.yml # Compiled files *.o *.so *.rlib *.dll *.exe # Generated by Cargo Cargo.lock target/ cstr-argument-0.1.1/.travis.yml010060000017500001750000000003571315513026500146340ustar0000000000000000language: rust rust: - 1.20.0 - stable matrix: include: rust: nightly script: - cargo build --features 'nightly' --verbose - cargo test --features 'nightly' --verbose notifications: email: on_success: never cstr-argument-0.1.1/Cargo.toml.orig010060000017500001750000000010741342351655600154200ustar0000000000000000[package] name = "cstr-argument" version = "0.1.1" authors = ["John Schug "] license = "Unlicense" readme = "README.md" repository = "https://github.com/johnschug/cstr-argument" documentation = "https://docs.rs/cstr-argument" keywords = ["ffi"] description = "A trait for converting function arguments to null terminated strings" [badges] travis-ci = { repository = "johnschug/cstr-argument" } maintenance = { status = "experimental" } [features] nightly = [] [dependencies] cfg-if = "0.1" memchr = { version = "2", default-features = false } cstr-argument-0.1.1/Cargo.toml0000644000000021250000000000000116630ustar00# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g. crates.io) dependencies # # If you believe there's an error in this file please file an # issue against the rust-lang/cargo repository. If you're # editing this file be aware that the upstream Cargo.toml # will likely look very different (and much more reasonable) [package] name = "cstr-argument" version = "0.1.1" authors = ["John Schug "] description = "A trait for converting function arguments to null terminated strings" documentation = "https://docs.rs/cstr-argument" readme = "README.md" keywords = ["ffi"] license = "Unlicense" repository = "https://github.com/johnschug/cstr-argument" [dependencies.cfg-if] version = "0.1" [dependencies.memchr] version = "2" default-features = false [features] nightly = [] [badges.maintenance] status = "experimental" [badges.travis-ci] repository = "johnschug/cstr-argument" cstr-argument-0.1.1/README.md010060000017500001750000000020331315534302700137750ustar0000000000000000cstr-argument ============= A trait for converting function arguments to null terminated strings [![Build Status](https://travis-ci.org/johnschug/cstr-argument.svg?branch=master)](https://travis-ci.org/johnschug/cstr-argument) [![Version](https://img.shields.io/crates/v/cstr-argument.svg)](https://crates.io/crates/cstr-argument) [Documentation](https://docs.rs/cstr-argument) ## Usage Add this to your `Cargo.toml`: ```toml [dependencies] cstr-argument = "0.0.2" ``` and this to your crate root: ```rust extern crate cstr_argument; ``` ## Example ```rust use std::os::raw::c_char; use cstr_argument::CStrArgument; extern "C" { fn foo(s: *const c_char); } fn bar(s: S) { let s = s.into_cstr(); unsafe { foo(s.as_ref().as_ptr()) } } fn baz() { bar("hello "); // Argument will be converted to a CString requiring an allocation bar("world\0"); // Argument will be converted to a CStr without allocation bar("!".to_owned()); // Argument will be converted to a CString possibly requiring an allocation } ``` cstr-argument-0.1.1/UNLICENSE010060000017500001750000000022731315443273700140020ustar0000000000000000This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. For more information, please refer to cstr-argument-0.1.1/src/lib.rs010060000017500001750000000242321326476241500144350ustar0000000000000000//! A trait for converting function arguments to null terminated strings. #![deny(missing_docs)] // #![cfg_attr(any(nightly, feature = "nightly"), feature(specialization))] // #[macro_use] // extern crate cfg_if; extern crate memchr; use std::borrow::Cow; use std::error; use std::ffi::{CStr, CString}; use std::fmt; use std::result; use memchr::memchr; /// An error returned from [`CStrArgument::try_into_cstr`] to indicate that a null byte /// was found before the last byte in the string. /// /// [`CStrArgument::try_into_cstr`]: trait.CStrArgument.html#tymethod.try_into_cstr #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub struct NulError { inner: T, pos: usize, } impl NulError { /// Returns the position of the null byte in the string. #[inline] pub fn nul_position(&self) -> usize { self.pos } /// Returns the original string. #[inline] pub fn into_inner(self) -> T { self.inner } } impl fmt::Display for NulError { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!( f, "nul byte found before end of provided data at position: {}", self.pos ) } } impl error::Error for NulError { fn description(&self) -> &str { "nul byte found before end of data" } } type Result = result::Result>; /// A trait for converting function arguments to null terminated strings. It can be used to convert /// string arguments that are passed on to C APIs using the minimal amount of allocations. /// /// Strings that are already null terminated are just wrapped in a CStr without any allocations. /// Strings that are not already null terminated are converted to a CString possibly requiring one /// or more allocations. Trying to convert strings with a null byte in any position other than the /// final will result in an error. /// /// # Example /// /// ```no_run /// use std::os::raw::c_char; /// use cstr_argument::CStrArgument; /// /// extern "C" { /// fn foo(s: *const c_char); /// } /// /// fn bar(s: S) { /// let s = s.into_cstr(); /// unsafe { /// foo(s.as_ref().as_ptr()) /// } /// } /// /// fn baz() { /// bar("hello "); // Argument will be converted to a CString requiring an allocation /// bar("world\0"); // Argument will be converted to a CStr without any allocations /// bar("!".to_owned()); // Argument will be converted to a CString possibly requiring an /// // allocation /// } /// ``` pub trait CStrArgument: fmt::Debug + Sized { /// The type of the string after conversion. The type may or may not own the resulting string. type Output: AsRef; /// Returns the string with a null terminator or an error. /// /// # Errors /// /// This function will return an error if the string contains a null byte at any position /// other than the final. fn try_into_cstr(self) -> Result; /// Returns the string with a null terminator. /// /// # Panics /// /// This function will panic if the string contains a null byte at any position other /// than the final. See [`try_into_cstr`](#tymethod.try_into_cstr) for a non-panicking version /// of this function. fn into_cstr(self) -> Self::Output { self.try_into_cstr() .expect("string contained an interior null byte") } } // BUG in rustc (#23341) // cfg_if! { // if #[cfg(any(nightly, feature = "nightly"))] { // impl CStrArgument for T where Self: AsRef { // default type Output = Self; // // default fn try_into_cstr(self) -> Result { // Ok(self) // } // } // // impl<'a, T> CStrArgument for &'a T where Self: AsRef { // default type Output = Cow<'a, CStr>; // // default fn try_into_cstr(self) -> Result { // self.as_ref().try_into_cstr() // } // } // } else { impl<'a> CStrArgument for CString { type Output = Self; #[inline] fn try_into_cstr(self) -> Result { Ok(self) } } impl<'a> CStrArgument for &'a CString { type Output = &'a CStr; #[inline] fn try_into_cstr(self) -> Result { Ok(self) } } impl<'a> CStrArgument for &'a CStr { type Output = Self; #[inline] fn try_into_cstr(self) -> Result { Ok(self) } } // } // } impl CStrArgument for String { type Output = CString; #[inline] fn try_into_cstr(self) -> Result { self.into_bytes().try_into_cstr().map_err(|e| NulError { inner: unsafe { String::from_utf8_unchecked(e.inner) }, pos: e.pos, }) } } impl<'a> CStrArgument for &'a String { type Output = Cow<'a, CStr>; #[inline] fn try_into_cstr(self) -> Result { self.as_bytes().try_into_cstr().map_err(|e| NulError { inner: self, pos: e.pos, }) } } impl<'a> CStrArgument for &'a str { type Output = Cow<'a, CStr>; #[inline] fn try_into_cstr(self) -> Result { self.as_bytes().try_into_cstr().map_err(|e| NulError { inner: self, pos: e.pos, }) } } impl<'a> CStrArgument for Vec { type Output = CString; fn try_into_cstr(mut self) -> Result { match memchr(0, &self) { Some(n) if n == (self.len() - 1) => { self.pop(); Ok(unsafe { CString::from_vec_unchecked(self) }) } Some(n) => Err(NulError { inner: self, pos: n, }), None => Ok(unsafe { CString::from_vec_unchecked(self) }), } } } impl<'a> CStrArgument for &'a Vec { type Output = Cow<'a, CStr>; #[inline] fn try_into_cstr(self) -> Result { self.as_slice().try_into_cstr().map_err(|e| NulError { inner: self, pos: e.pos, }) } } impl<'a> CStrArgument for &'a [u8] { type Output = Cow<'a, CStr>; fn try_into_cstr(self) -> Result { match memchr(0, self) { Some(n) if n == (self.len() - 1) => Ok(Cow::Borrowed(unsafe { CStr::from_bytes_with_nul_unchecked(self) })), Some(n) => Err(NulError { inner: self, pos: n, }), None => Ok(Cow::Owned(unsafe { CString::from_vec_unchecked(self.into()) })), } } } #[cfg(test)] mod tests { use super::{CStrArgument, NulError}; fn test(t: T, f: F) -> R where T: CStrArgument, F: FnOnce(Result>) -> R, { f(t.try_into_cstr()) } #[test] fn test_basic() { let case = ""; test(case, |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); assert_ne!(s.as_ptr() as *const u8, case.as_ptr()); }); test(case.to_owned(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); }); test(case.as_bytes(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); assert_ne!(s.as_ptr() as *const u8, case.as_ptr()); }); let case = "hello"; test(case, |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); assert_ne!(s.as_ptr() as *const u8, case.as_ptr()); }); test(case.to_owned(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); }); test(case.as_bytes(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len() + 1); assert_ne!(s.as_ptr() as *const u8, case.as_ptr()); }); } #[test] fn test_terminating_null() { let case = "\0"; test(case, |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); assert_eq!(s.as_ptr() as *const u8, case.as_ptr()); }); test(case.to_owned(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); }); test(case.as_bytes(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); assert_eq!(s.as_ptr() as *const u8, case.as_ptr()); }); let case = "hello\0"; test(case, |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); assert_eq!(s.as_ptr() as *const u8, case.as_ptr()); }); test(case.to_owned(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); }); test(case.as_bytes(), |s| { let s = s.unwrap(); assert_eq!(s.to_bytes_with_nul().len(), case.len()); assert_eq!(s.as_ptr() as *const u8, case.as_ptr()); }); } #[test] fn test_interior_null() { let case = "hello\0world"; test(case, |s| s.unwrap_err()); test(case.to_owned(), |s| s.unwrap_err()); test(case.as_bytes(), |s| s.unwrap_err()); } #[test] fn test_interior_and_terminating_null() { let case = "\0\0"; test(case, |s| s.unwrap_err()); test(case.to_owned(), |s| s.unwrap_err()); test(case.as_bytes(), |s| s.unwrap_err()); let case = "hello\0world\0"; test(case, |s| s.unwrap_err()); test(case.to_owned(), |s| s.unwrap_err()); test(case.as_bytes(), |s| s.unwrap_err()); let case = "hello world\0\0"; test(case, |s| s.unwrap_err()); test(case.to_owned(), |s| s.unwrap_err()); test(case.as_bytes(), |s| s.unwrap_err()); } #[test] #[should_panic] fn test_interior_null_panic() { "\0\0".into_cstr(); } }