Struct reaper_medium::ReaperStringArg

pub struct ReaperStringArg<'a>(_);

A string parameter.

Medium-level API functions with string parameters accept all kinds of strings which can be converted into this type, most notably &CStr and &str.

Design

This is a wrapper around a Cow<CStr>.

Why C strings and not regular Rust strings?

We use a sort of C string because that perfectly accounts for the medium-level API's design goal to be still as close to the original REAPER API as possible (while at the same time introducing Rust's type safety). The C++ REAPER API generally expects C strings (*const c_char). Fortunately UTF-8 encoded ones - which makes a character set conversion unnecessary.

Why &CStr and not *const c_char?

We don't use *const c_char directly because we want more type safety. We use &CStr instead because in Rust that's the closest thing to a *const c_char (infact it's the same + some additional guarantees). It's a reference instead of a pointer so we can assume it's neither stale nor null. Also, the &CStr type gives us important guarantees, for example that there are no intermediate zero bytes - which would make the string end abruptly in C world.

Why Cow and ReaperStringArg?

We don't use just a plain &CStr as parameter type because &CStr is not the regular string type in Rust. It's much harder to create and use than &str. We want the API to be a pleasure to use! That's the reason for adding ReaperStringArg and Cow to the mix. Cowis necessary because we might need to own a possible conversion result (e.g. from &str). ReaperStringArg is necessary to offer implicit conversions from regular Rust string types. Because medium-level API functions take string parameters as impl Into<ReaperStringArg>, they just work with regular Rust strings.

Performance considerations

A conversion from a regular Rust string is not entirely without cost because we need to check for intermediate zero bytes and append a zero byte (which demands a copy if a borrowed string is passed)! Therefore, if you want to be sure to not waste any performance and you can get cheap access to a C string, just pass that one directly. Then there's no extra cost involved. In many scenarios this is probably over optimization, but the point is, you can go the zero-cost way, if you want.

In the reaper-rs code base you will find many examples that pass c_str!("...") to string parameters. This macro from the c_str_macro crate creates static (UTF-8 encoded) &CStr literals, just as "..." creates static &str literals. Because those literals are embedded in the binary itself, no heap-space allocation or conversion is necessary at all. If you want, you can do the same with your literals.

Trait Implementations

impl<'a> From<&'a CStr> for ReaperStringArg<'a>

fn from(s: &'a CStr) -> Self

Performs the conversion.

impl<'a> From<&'a str> for ReaperStringArg<'a>

fn from(s: &'a str) -> Self

Performs the conversion.

impl<'a> From<String> for ReaperStringArg<'a>

fn from(s: String) -> Self

Performs the conversion.