Pass filesystem paths as OsStr instead of str

Author: twistedfall

Cargo.toml

@@ -52,6 +52,7 @@ winsplit = "0.1"
 [dev-dependencies]
 # Switch to std's assert_matches when MSRV is 1.96
 matches = "0.1"
+tempdir = "0.3"
 # copy of build-dependencies because we need to test methods of the build script
 opencv-binding-generator = { version = "0.103.0", path = "binding-generator" }
 cc = { version = "1.0.83", features = ["parallel"] }

binding-generator/src/func.rs

@@ -491,31 +491,21 @@ impl<'tu, 'ge> Func<'tu, 'ge> {
 					.into_iter()
 					.enumerate()
 					.map(|(idx, a)| {
+						let arg_name = a.get_name();
 						if let Some(func_arg_override) = arg_overrides
-							&& let Some(type_hint) = a.get_name().and_then(|arg_name| func_arg_override.get(arg_name.as_str()))
+							&& let Some(type_hint) = arg_name.as_deref().and_then(|arg_name| func_arg_override.get(arg_name))
 						{
 							return Field::new_ext(a, type_hint.clone(), gen_env);
 						}
-						let out = Field::new(a, gen_env);
-						slice_arg_finder.feed(idx, &out);
-						out
+						let mut arg = Field::new(a, gen_env);
+						if let Some(arg_name) = arg_name.as_deref() {
+							update_path_argument(&mut arg, arg_name);
+						}
+						slice_arg_finder.feed(idx, &arg);
+						arg
 					})
 					.collect::<Vec<_>>();
-				for (slice_arg_indices, slice_len_arg_idx) in slice_arg_finder.finish() {
-					let mut slice_arg_names = Vec::with_capacity(slice_arg_indices.len());
-					for &slice_arg_idx in &slice_arg_indices {
-						let slice_arg = &mut out[slice_arg_idx];
-						slice_arg_names.push(slice_arg.rust_name(NameStyle::ref_()).into_owned());
-						slice_arg.set_type_ref_type_hint(TypeRefTypeHint::Slice);
-					}
-					let slice_len_arg = &mut out[slice_len_arg_idx];
-					let divisor = if slice_len_arg.cpp_name(CppNameStyle::Declaration).contains("pair") {
-						2
-					} else {
-						1
-					};
-					slice_len_arg.set_type_ref_type_hint(TypeRefTypeHint::LenForSlice(slice_arg_names.into(), divisor));
-				}
+				update_slice_arguments(&mut out, slice_arg_finder);
 				Owned(out)
 			}
 			Self::Desc(desc) => Borrowed(desc.arguments.as_ref()),
@@ -874,3 +864,53 @@ impl InheritConfig {
 		self.kind || self.name || self.arguments || self.doc_comment || self.return_type_ref || self.definition_location
 	}
 }
+
+/// Checks whether the `arg_name` is a name of the argument that's expected to receive a filesystem path, and adds a corresponding
+/// type hint to `field` if so.
+fn update_path_argument(field: &mut Field, arg_name: &str) {
+	const CHECK_SUFFIXES: [&str; 5] = ["file", "filename", "file_name", "path", "pathorname"];
+	const CHECK_PREFIXES: [&str; 2] = ["pathto", "path_to"];
+
+	let len = arg_name.len();
+	let arg_name_matched = CHECK_SUFFIXES
+		.into_iter()
+		.filter(|suf| suf.len() <= len)
+		.flat_map(|suf| {
+			arg_name
+				.get(len - suf.len()..)
+				.filter(|suf_check| suf_check.eq_ignore_ascii_case(suf))
+		})
+		.chain(CHECK_PREFIXES.into_iter().flat_map(|pref| {
+			arg_name
+				.get(..pref.len())
+				.filter(|pref_check| pref_check.eq_ignore_ascii_case(pref))
+		}))
+		.next()
+		.is_some();
+	if arg_name_matched {
+		field.set_type_ref_type_hint(TypeRefTypeHint::StringAsPath);
+		return;
+	}
+
+	if arg_name == "filenames" || arg_name == "paths" {
+		// todo: add support for Vector<impl Into<OsStr>>
+	}
+}
+
+fn update_slice_arguments(arguments: &mut [Field], slice_arg_finder: SliceArgFinder) {
+	for (slice_arg_indices, slice_len_arg_idx) in slice_arg_finder.finish() {
+		let mut slice_arg_names = Vec::with_capacity(slice_arg_indices.len());
+		for &slice_arg_idx in &slice_arg_indices {
+			let slice_arg = &mut arguments[slice_arg_idx];
+			slice_arg_names.push(slice_arg.rust_name(NameStyle::ref_()).into_owned());
+			slice_arg.set_type_ref_type_hint(TypeRefTypeHint::Slice);
+		}
+		let slice_len_arg = &mut arguments[slice_len_arg_idx];
+		let divisor = if slice_len_arg.cpp_name(CppNameStyle::Declaration).contains("pair") {
+			2
+		} else {
+			1
+		};
+		slice_len_arg.set_type_ref_type_hint(TypeRefTypeHint::LenForSlice(slice_arg_names.into(), divisor));
+	}
+}

binding-generator/src/lib.rs

@@ -6,6 +6,7 @@
 // todo public static properties like opencv2/core/base.hpp:384 Hamming::normType
 // todo test returning reference to array like cv_MatStep_buf
 // todo, allow extension of simple classes for e.g. Elliptic_KeyPoint
+// todo OCRTesseract::create should have nullable params
 // fixme vector<Mat*> get's interpreted as Vector<Mat> which should be wrong (e.g. Layer::forward and Layer::apply_halide_scheduler)
 // fixme MatConstIterator::m return Mat**, is it handled correctly?
 // fixme VectorOfMat::get allows mutation

binding-generator/src/type_ref.rs

@@ -493,26 +493,17 @@ impl fmt::Debug for TypeRef<'_, '_> {
 					str_type
 				}
 			};
-			match str_type {
-				StrType::StdString(StrEnc::Text) => {
-					props.push("std_string");
-				}
-				StrType::CvString(StrEnc::Text) => {
-					props.push("cv_string");
-				}
-				StrType::CharPtr(StrEnc::Text) => {
-					props.push("char_ptr_string");
-				}
-				StrType::StdString(StrEnc::Binary) => {
-					props.push("byte_std_string");
-				}
-				StrType::CvString(StrEnc::Binary) => {
-					props.push("byte_cv_string");
-				}
-				StrType::CharPtr(StrEnc::Binary) => {
-					props.push("byte_ptr_string");
-				}
-			}
+			props.push(match str_type {
+				StrType::StdString(StrEnc::Text) => "std_string",
+				StrType::CvString(StrEnc::Text) => "cv_string",
+				StrType::CharPtr(StrEnc::Text) => "char_ptr_string",
+				StrType::StdString(StrEnc::Binary) => "byte_std_string",
+				StrType::CvString(StrEnc::Binary) => "byte_cv_string",
+				StrType::CharPtr(StrEnc::Binary) => "byte_ptr_string",
+				StrType::StdString(StrEnc::OsStr) => "osstr_std_string",
+				StrType::CvString(StrEnc::OsStr) => "osstr_cv_string",
+				StrType::CharPtr(StrEnc::OsStr) => "osstr_ptr_string",
+			})
 		}
 		if kind.as_by_move().is_some() {
 			props.push("by_move");

binding-generator/src/type_ref/kind.rs

@@ -260,10 +260,12 @@ impl<'tu, 'ge> TypeRefKind<'tu, 'ge> {
 			TypeRefKind::Typedef(tdef) => tdef.underlying_type_ref().kind().as_string(type_hint),
 			_ => None,
 		};
-		if let Some((_, str_type)) = out.as_mut()
-			&& matches!(type_hint, TypeRefTypeHint::StringAsBytes(_))
-		{
-			str_type.set_encoding(StrEnc::Binary)
+		if let Some((_, str_type)) = out.as_mut() {
+			match type_hint {
+				TypeRefTypeHint::StringAsBytes(_) => str_type.set_encoding(StrEnc::Binary),
+				TypeRefTypeHint::StringAsPath => str_type.set_encoding(StrEnc::OsStr),
+				_ => {}
+			}
 		}
 		out
 	}

binding-generator/src/type_ref/types.rs

@@ -21,6 +21,8 @@ pub enum TypeRefTypeHint {
 	LenForSlice(Arc<[String]>, usize),
 	/// Treat C++ string as a byte buffer (`Vec<u8>`) instead of an actual string, argument is optional cpp_arg_name of the argument that specifies the buffer byte length
 	StringAsBytes(Option<Arc<str>>),
+	/// Treat C++ string as a file path, done heuristically based on the argument name
+	StringAsPath,
 	/// String len is passed in an additional argument (cpp_arg_name)
 	StringWithLen(Rc<str>),
 	/// when C++ char needs to be represented as Rust char
@@ -60,6 +62,7 @@ impl TypeRefTypeHint {
 			| Self::Slice
 			| Self::LenForSlice(_, _)
 			| Self::StringAsBytes(_)
+			| Self::StringAsPath
 			| Self::StringWithLen(_)
 			| Self::CharAsRustChar
 			| Self::CharPtrSingleChar
@@ -78,6 +81,7 @@ impl TypeRefTypeHint {
 			| Self::Slice
 			| Self::LenForSlice(_, _)
 			| Self::StringAsBytes(_)
+			| Self::StringAsPath
 			| Self::StringWithLen(_)
 			| Self::CharAsRustChar
 			| Self::CharPtrSingleChar
@@ -244,23 +248,24 @@ pub enum StrType {
 impl StrType {
 	pub fn set_encoding(&mut self, enc: StrEnc) {
 		match self {
-			StrType::StdString(old_enc) | StrType::CvString(old_enc) | StrType::CharPtr(old_enc) => *old_enc = enc,
+			Self::StdString(old_enc) | Self::CvString(old_enc) | Self::CharPtr(old_enc) => *old_enc = enc,
 		}
 	}
 
-	pub fn is_binary(&self) -> bool {
+	pub fn encoding(&self) -> StrEnc {
 		match self {
-			StrType::StdString(StrEnc::Binary) | StrType::CvString(StrEnc::Binary) | StrType::CharPtr(StrEnc::Binary) => true,
-			StrType::StdString(StrEnc::Text) | StrType::CvString(StrEnc::Text) | StrType::CharPtr(StrEnc::Text) => false,
+			Self::StdString(enc) | Self::CvString(enc) | Self::CharPtr(enc) => *enc,
 		}
 	}
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum StrEnc {
 	Text,
-	/// string with binary data, e.g. can contain 0 byte
+	/// string with binary data (=== [Vec<u8>]), can contain 0 byte
 	Binary,
+	/// OS-specific encoding (== [std::ffi::OsString]), used to pass filesystem paths for example
+	OsStr,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]

binding-generator/src/writer/rust_native/func.rs

@@ -789,15 +789,16 @@ pub fn cpp_return_map<'f>(return_type: &TypeRef, name: &'f str, is_constructor:
 		("".into(), false)
 	} else if let Some((_, string_type)) = return_kind.as_string(return_type.type_hint()) {
 		let str_mk = match string_type {
-			StrType::StdString(StrEnc::Text) | StrType::CvString(StrEnc::Text) => {
-				format!("ocvrs_create_string({name}.c_str())").into()
-			}
-			StrType::StdString(StrEnc::Binary) => format!("ocvrs_create_byte_string({name}.data(), {name}.size())").into(),
-			StrType::CvString(StrEnc::Binary) => format!("ocvrs_create_byte_string({name}.begin(), {name}.size())").into(),
-			StrType::CharPtr(StrEnc::Text) => format!("ocvrs_create_string({name})").into(),
+			StrType::StdString(StrEnc::Text) | StrType::CvString(StrEnc::Text) => format!("ocvrs_create_string({name}.c_str())"),
+			StrType::StdString(StrEnc::Binary) => format!("ocvrs_create_byte_string({name}.data(), {name}.size())"),
+			StrType::CvString(StrEnc::Binary) => format!("ocvrs_create_byte_string({name}.begin(), {name}.size())"),
+			StrType::CharPtr(StrEnc::Text) => format!("ocvrs_create_string({name})"),
 			StrType::CharPtr(StrEnc::Binary) => panic!("Returning a byte string via char* is not supported yet"),
+			StrType::StdString(StrEnc::OsStr) | StrType::CvString(StrEnc::OsStr) | StrType::CharPtr(StrEnc::OsStr) => {
+				panic!("Returning a path string is not supported yet")
+			}
 		};
-		(str_mk, false)
+		(str_mk.into(), false)
 	} else if return_kind.extern_pass_kind().is_by_void_ptr() && !is_constructor {
 		let ret_source = return_type.source();
 		let out = ret_source.kind().as_class().filter(|cls| cls.is_abstract()).map_or_else(

binding-generator/src/writer/rust_native/renderer.rs

@@ -3,7 +3,7 @@ use std::fmt::Write;
 
 use crate::renderer::TypeRefRenderer;
 use crate::type_ref::{
-	Constness, CppNameStyle, Dir, ExternDir, FishStyle, NameStyle, StrType, TemplateArg, TypeRef, TypeRefDesc, TypeRefKind,
+	Constness, CppNameStyle, Dir, ExternDir, FishStyle, NameStyle, StrEnc, StrType, TemplateArg, TypeRef, TypeRefDesc, TypeRefKind,
 };
 use crate::writer::rust_native::class::ClassExt;
 use crate::writer::rust_native::element::RustElement;
@@ -72,10 +72,10 @@ impl TypeRefRenderer<'_> for RustRenderer {
 	fn render<'t>(self, type_ref: &'t TypeRef) -> Cow<'t, str> {
 		let kind = type_ref.kind();
 		if let Some((_, str_type)) = kind.as_string(type_ref.type_hint()) {
-			if str_type.is_binary() {
-				format!("Vec{fish}<u8>", fish = self.name_style.turbo_fish_style().rust_qual()).into()
-			} else {
-				"String".into()
+			match str_type.encoding() {
+				StrEnc::Text => "String".into(),
+				StrEnc::Binary => format!("Vec{fish}<u8>", fish = self.name_style.turbo_fish_style().rust_qual()).into(),
+				StrEnc::OsStr => "PathBuf".into(),
 			}
 		} else {
 			kind.map_borrowed(|kind| match kind {

binding-generator/src/writer/rust_native/type_ref/render_lane/string.rs

@@ -21,19 +21,23 @@ impl RenderLaneTrait for InStringRenderLane<'_, '_> {
 	}
 
 	fn rust_arg_func_decl(&self, name: &str, _lifetime: Lifetime) -> String {
-		let typ = if self.str_type.is_binary() {
-			"&[u8]"
-		} else {
-			"&str"
+		let typ = match self.str_type.encoding() {
+			StrEnc::Text => "&str",
+			StrEnc::Binary => "&[u8]",
+			StrEnc::OsStr => "impl AsRef<OsStr>",
 		};
 		rust_arg_func_decl(name, Constness::Const, typ)
 	}
 
 	fn rust_arg_pre_call(&self, name: &str, function_props: &FunctionProps) -> String {
-		if function_props.is_infallible {
-			format!("extern_container_arg!(nofail {name})")
+		let fail_spec = if function_props.is_infallible {
+			"nofail "
 		} else {
-			format!("extern_container_arg!({name})")
+			""
+		};
+		match self.str_type.encoding() {
+			StrEnc::Text | StrEnc::Binary => format!("extern_container_arg!({fail_spec}{name})"),
+			StrEnc::OsStr => format!("path_arg!({fail_spec}{name})"),
 		}
 	}
 
@@ -75,10 +79,10 @@ impl RenderLaneTrait for OutStringRenderLane<'_, '_> {
 	}
 
 	fn rust_arg_func_decl(&self, name: &str, _lifetime: Lifetime) -> String {
-		let typ = if self.str_type.is_binary() {
-			"&mut Vec<u8>"
-		} else {
-			"&mut String"
+		let typ = match self.str_type.encoding() {
+			StrEnc::Text => "&mut String",
+			StrEnc::Binary => "&mut Vec<u8>",
+			StrEnc::OsStr => "&mut OsString",
 		};
 		rust_arg_func_decl(name, Constness::Const, typ)
 	}
@@ -117,6 +121,7 @@ impl RenderLaneTrait for OutStringRenderLane<'_, '_> {
 					| TypeRefTypeHint::Slice
 					| TypeRefTypeHint::LenForSlice(_, _)
 					| TypeRefTypeHint::StringAsBytes(_)
+					| TypeRefTypeHint::StringAsPath
 					| TypeRefTypeHint::CharAsRustChar
 					| TypeRefTypeHint::CharPtrSingleChar
 					| TypeRefTypeHint::PrimitivePtrAsRaw
@@ -149,21 +154,23 @@ impl RenderLaneTrait for OutStringRenderLane<'_, '_> {
 			StrType::StdString(StrEnc::Text) | StrType::CvString(StrEnc::Text) => {
 				format!("*{name} = ocvrs_create_string({name}_out.c_str())")
 			}
+			StrType::CharPtr(StrEnc::Text) => {
+				format!("*{name} = ocvrs_create_string({name}_out.get())")
+			}
 			StrType::StdString(StrEnc::Binary) => {
 				format!("*{name} = ocvrs_create_byte_string({name}_out.data(), {name}_out.size())")
 			}
 			StrType::CvString(StrEnc::Binary) => {
 				format!("*{name} = ocvrs_create_byte_string({name}_out.begin(), {name}_out.size())")
 			}
-			StrType::CharPtr(StrEnc::Text) => {
-				format!("*{name} = ocvrs_create_string({name}_out.get())")
-			}
 			StrType::CharPtr(StrEnc::Binary) => {
-				if let TypeRefTypeHint::StringAsBytes(Some(len_arg_name)) = self.canonical.type_hint() {
-					format!("*{name} = ocvrs_create_byte_string({name}_out.get(), {len_arg_name})")
-				} else {
+				let TypeRefTypeHint::StringAsBytes(Some(len_arg_name)) = self.canonical.type_hint() else {
 					panic!("Output argument of type `char*` with binary encoding must have `len` argument specified")
-				}
+				};
+				format!("*{name} = ocvrs_create_byte_string({name}_out.get(), {len_arg_name})")
+			}
+			StrType::StdString(StrEnc::OsStr) | StrType::CvString(StrEnc::OsStr) | StrType::CharPtr(_) => {
+				panic!("Output string argument with OsStr encoding is not supported")
 			}
 		}
 	}

src/lib.rs

@@ -33,14 +33,15 @@ pub mod platform_types {
 
 /// Prelude for sys (externs) module and types
 pub mod mod_prelude_sys {
-	pub use std::ffi::{c_char, c_void};
+	pub use core::ffi::{c_char, c_void};
 
 	pub use crate::platform_types::*;
 	pub use crate::traits::{Boxed, OpenCVFromExtern, OpenCVIntoExternContainer, OpenCVTypeExternContainer};
 }
 
 /// Prelude for generated modules and types
 pub mod mod_prelude {
+	pub use std::ffi::OsStr;
 	pub use std::marker::PhantomData;
 
 	pub use crate::boxed_ref::{BoxedRef, BoxedRefMut};