Add functions to convert a CString to upper- / lowercase, either
in-place or by creating a copy of the original CString.
Naming followes the one from the Rust stdlib, where functions starting
with 'to' create a copy and functions starting with 'make' perform an
in-place conversion.
This is required by the Nova project (GSP only Rust successor of
Nouveau) to convert stringified enum values (representing different GPU
chipsets) to strings in order to generate the corresponding firmware
paths. See also [1].
[1] https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/String.20manipulation.20in.20kernel.20Rust
Reviewed-by: Alice Ryhl <[email protected]>
Signed-off-by: Danilo Krummrich <[email protected]>
---
Changes in V5:
- remove unneeded return statements
- use Vec::as_mut_slice() instead of a dereference
Changes in V4:
- move to_ascii_{lower,upper}case() to CStr
- add a few comments suggested by Alice
Changes in V3:
- add an `impl DerefMut for CString`, such that these functions can be defined
for `CStr` as `&mut self` and still be called on a `CString`
Changes in V2:
- expand commit message mentioning the use case
- expand function doc comments to match the ones from Rust's stdlib
- rename to_* to make_* and add the actual to_* implementations
---
rust/kernel/str.rs | 87 +++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 86 insertions(+), 1 deletion(-)
diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
index 7d848b83add4..c1c8ccc80c52 100644
--- a/rust/kernel/str.rs
+++ b/rust/kernel/str.rs
@@ -5,7 +5,7 @@
use alloc::alloc::AllocError;
use alloc::vec::Vec;
use core::fmt::{self, Write};
-use core::ops::{self, Deref, Index};
+use core::ops::{self, Deref, DerefMut, Index};
use crate::{
bindings,
@@ -143,6 +143,19 @@ pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError
unsafe { core::mem::transmute(bytes) }
}
+ /// Creates a mutable [`CStr`] from a `[u8]` without performing any
+ /// additional checks.
+ ///
+ /// # Safety
+ ///
+ /// `bytes` *must* end with a `NUL` byte, and should only have a single
+ /// `NUL` byte (or the string will be truncated).
+ #[inline]
+ pub unsafe fn from_bytes_with_nul_unchecked_mut(bytes: &mut [u8]) -> &mut CStr {
+ // SAFETY: Properties of `bytes` guaranteed by the safety precondition.
+ unsafe { &mut *(bytes as *mut [u8] as *mut CStr) }
+ }
+
/// Returns a C pointer to the string.
#[inline]
pub const fn as_char_ptr(&self) -> *const core::ffi::c_char {
@@ -206,6 +219,70 @@ pub unsafe fn as_str_unchecked(&self) -> &str {
pub fn to_cstring(&self) -> Result<CString, AllocError> {
CString::try_from(self)
}
+
+ /// Converts this [`CStr`] to its ASCII lower case equivalent in-place.
+ ///
+ /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
+ /// but non-ASCII letters are unchanged.
+ ///
+ /// To return a new lowercased value without modifying the existing one, use
+ /// [`to_ascii_lowercase()`].
+ ///
+ /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
+ pub fn make_ascii_lowercase(&mut self) {
+ // INVARIANT: This doesn't introduce or remove NUL bytes in the C
+ // string.
+ self.0.make_ascii_lowercase();
+ }
+
+ /// Converts this [`CStr`] to its ASCII upper case equivalent in-place.
+ ///
+ /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
+ /// but non-ASCII letters are unchanged.
+ ///
+ /// To return a new uppercased value without modifying the existing one, use
+ /// [`to_ascii_uppercase()`].
+ ///
+ /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
+ pub fn make_ascii_uppercase(&mut self) {
+ // INVARIANT: This doesn't introduce or remove NUL bytes in the C
+ // string.
+ self.0.make_ascii_uppercase();
+ }
+
+ /// Returns a copy of this [`CString`] where each character is mapped to its
+ /// ASCII lower case equivalent.
+ ///
+ /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
+ /// but non-ASCII letters are unchanged.
+ ///
+ /// To lowercase the value in-place, use [`make_ascii_lowercase`].
+ ///
+ /// [`make_ascii_lowercase`]: str::make_ascii_lowercase
+ pub fn to_ascii_lowercase(&self) -> Result<CString, AllocError> {
+ let mut s = self.to_cstring()?;
+
+ s.make_ascii_lowercase();
+
+ Ok(s)
+ }
+
+ /// Returns a copy of this [`CString`] where each character is mapped to its
+ /// ASCII upper case equivalent.
+ ///
+ /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
+ /// but non-ASCII letters are unchanged.
+ ///
+ /// To uppercase the value in-place, use [`make_ascii_uppercase`].
+ ///
+ /// [`make_ascii_uppercase`]: str::make_ascii_uppercase
+ pub fn to_ascii_uppercase(&self) -> Result<CString, AllocError> {
+ let mut s = self.to_cstring()?;
+
+ s.make_ascii_uppercase();
+
+ Ok(s)
+ }
}
impl fmt::Display for CStr {
@@ -593,6 +670,14 @@ fn deref(&self) -> &Self::Target {
}
}
+impl DerefMut for CString {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ // SAFETY: A `CString` is always NUL-terminated and contains no other
+ // NUL bytes.
+ unsafe { CStr::from_bytes_with_nul_unchecked_mut(self.buf.as_mut_slice()) }
+ }
+}
+
impl<'a> TryFrom<&'a CStr> for CString {
type Error = AllocError;
base-commit: 39133352cbed6626956d38ed72012f49b0421e7b
--
2.43.0
On 2/23/24 17:37, Danilo Krummrich wrote:
> Add functions to convert a CString to upper- / lowercase, either
> in-place or by creating a copy of the original CString.
>
> Naming followes the one from the Rust stdlib, where functions starting
> with 'to' create a copy and functions starting with 'make' perform an
> in-place conversion.
>
> This is required by the Nova project (GSP only Rust successor of
> Nouveau) to convert stringified enum values (representing different GPU
> chipsets) to strings in order to generate the corresponding firmware
> paths. See also [1].
Gentle ping.
>
> [1] https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/String.20manipulation.20in.20kernel.20Rust
>
> Reviewed-by: Alice Ryhl <[email protected]>
> Signed-off-by: Danilo Krummrich <[email protected]>
> ---
> Changes in V5:
> - remove unneeded return statements
> - use Vec::as_mut_slice() instead of a dereference
> Changes in V4:
> - move to_ascii_{lower,upper}case() to CStr
> - add a few comments suggested by Alice
> Changes in V3:
> - add an `impl DerefMut for CString`, such that these functions can be defined
> for `CStr` as `&mut self` and still be called on a `CString`
> Changes in V2:
> - expand commit message mentioning the use case
> - expand function doc comments to match the ones from Rust's stdlib
> - rename to_* to make_* and add the actual to_* implementations
> ---
> rust/kernel/str.rs | 87 +++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 86 insertions(+), 1 deletion(-)
>
> diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
> index 7d848b83add4..c1c8ccc80c52 100644
> --- a/rust/kernel/str.rs
> +++ b/rust/kernel/str.rs
> @@ -5,7 +5,7 @@
> use alloc::alloc::AllocError;
> use alloc::vec::Vec;
> use core::fmt::{self, Write};
> -use core::ops::{self, Deref, Index};
> +use core::ops::{self, Deref, DerefMut, Index};
>
> use crate::{
> bindings,
> @@ -143,6 +143,19 @@ pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError
> unsafe { core::mem::transmute(bytes) }
> }
>
> + /// Creates a mutable [`CStr`] from a `[u8]` without performing any
> + /// additional checks.
> + ///
> + /// # Safety
> + ///
> + /// `bytes` *must* end with a `NUL` byte, and should only have a single
> + /// `NUL` byte (or the string will be truncated).
> + #[inline]
> + pub unsafe fn from_bytes_with_nul_unchecked_mut(bytes: &mut [u8]) -> &mut CStr {
> + // SAFETY: Properties of `bytes` guaranteed by the safety precondition.
> + unsafe { &mut *(bytes as *mut [u8] as *mut CStr) }
> + }
> +
> /// Returns a C pointer to the string.
> #[inline]
> pub const fn as_char_ptr(&self) -> *const core::ffi::c_char {
> @@ -206,6 +219,70 @@ pub unsafe fn as_str_unchecked(&self) -> &str {
> pub fn to_cstring(&self) -> Result<CString, AllocError> {
> CString::try_from(self)
> }
> +
> + /// Converts this [`CStr`] to its ASCII lower case equivalent in-place.
> + ///
> + /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
> + /// but non-ASCII letters are unchanged.
> + ///
> + /// To return a new lowercased value without modifying the existing one, use
> + /// [`to_ascii_lowercase()`].
> + ///
> + /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
> + pub fn make_ascii_lowercase(&mut self) {
> + // INVARIANT: This doesn't introduce or remove NUL bytes in the C
> + // string.
> + self.0.make_ascii_lowercase();
> + }
> +
> + /// Converts this [`CStr`] to its ASCII upper case equivalent in-place.
> + ///
> + /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
> + /// but non-ASCII letters are unchanged.
> + ///
> + /// To return a new uppercased value without modifying the existing one, use
> + /// [`to_ascii_uppercase()`].
> + ///
> + /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
> + pub fn make_ascii_uppercase(&mut self) {
> + // INVARIANT: This doesn't introduce or remove NUL bytes in the C
> + // string.
> + self.0.make_ascii_uppercase();
> + }
> +
> + /// Returns a copy of this [`CString`] where each character is mapped to its
> + /// ASCII lower case equivalent.
> + ///
> + /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
> + /// but non-ASCII letters are unchanged.
> + ///
> + /// To lowercase the value in-place, use [`make_ascii_lowercase`].
> + ///
> + /// [`make_ascii_lowercase`]: str::make_ascii_lowercase
> + pub fn to_ascii_lowercase(&self) -> Result<CString, AllocError> {
> + let mut s = self.to_cstring()?;
> +
> + s.make_ascii_lowercase();
> +
> + Ok(s)
> + }
> +
> + /// Returns a copy of this [`CString`] where each character is mapped to its
> + /// ASCII upper case equivalent.
> + ///
> + /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
> + /// but non-ASCII letters are unchanged.
> + ///
> + /// To uppercase the value in-place, use [`make_ascii_uppercase`].
> + ///
> + /// [`make_ascii_uppercase`]: str::make_ascii_uppercase
> + pub fn to_ascii_uppercase(&self) -> Result<CString, AllocError> {
> + let mut s = self.to_cstring()?;
> +
> + s.make_ascii_uppercase();
> +
> + Ok(s)
> + }
> }
>
> impl fmt::Display for CStr {
> @@ -593,6 +670,14 @@ fn deref(&self) -> &Self::Target {
> }
> }
>
> +impl DerefMut for CString {
> + fn deref_mut(&mut self) -> &mut Self::Target {
> + // SAFETY: A `CString` is always NUL-terminated and contains no other
> + // NUL bytes.
> + unsafe { CStr::from_bytes_with_nul_unchecked_mut(self.buf.as_mut_slice()) }
> + }
> +}
> +
> impl<'a> TryFrom<&'a CStr> for CString {
> type Error = AllocError;
>
>
> base-commit: 39133352cbed6626956d38ed72012f49b0421e7b
On Mon, Mar 04, 2024 at 01:22:17PM +0100, Danilo Krummrich wrote:
> On 2/23/24 17:37, Danilo Krummrich wrote:
> > Add functions to convert a CString to upper- / lowercase, either
> > in-place or by creating a copy of the original CString.
> >
> > Naming followes the one from the Rust stdlib, where functions starting
> > with 'to' create a copy and functions starting with 'make' perform an
> > in-place conversion.
> >
> > This is required by the Nova project (GSP only Rust successor of
> > Nouveau) to convert stringified enum values (representing different GPU
> > chipsets) to strings in order to generate the corresponding firmware
> > paths. See also [1].
>
> Gentle ping.
It doesn't seem there's any further feedback, thus can this be merged?
- Danilo
>
> >
> > [1] https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/String.20manipulation.20in.20kernel.20Rust
> >
> > Reviewed-by: Alice Ryhl <[email protected]>
> > Signed-off-by: Danilo Krummrich <[email protected]>
> > ---
> > Changes in V5:
> > - remove unneeded return statements
> > - use Vec::as_mut_slice() instead of a dereference
> > Changes in V4:
> > - move to_ascii_{lower,upper}case() to CStr
> > - add a few comments suggested by Alice
> > Changes in V3:
> > - add an `impl DerefMut for CString`, such that these functions can be defined
> > for `CStr` as `&mut self` and still be called on a `CString`
> > Changes in V2:
> > - expand commit message mentioning the use case
> > - expand function doc comments to match the ones from Rust's stdlib
> > - rename to_* to make_* and add the actual to_* implementations
> > ---
> > rust/kernel/str.rs | 87 +++++++++++++++++++++++++++++++++++++++++++++-
> > 1 file changed, 86 insertions(+), 1 deletion(-)
> >
> > diff --git a/rust/kernel/str.rs b/rust/kernel/str.rs
> > index 7d848b83add4..c1c8ccc80c52 100644
> > --- a/rust/kernel/str.rs
> > +++ b/rust/kernel/str.rs
> > @@ -5,7 +5,7 @@
> > use alloc::alloc::AllocError;
> > use alloc::vec::Vec;
> > use core::fmt::{self, Write};
> > -use core::ops::{self, Deref, Index};
> > +use core::ops::{self, Deref, DerefMut, Index};
> > use crate::{
> > bindings,
> > @@ -143,6 +143,19 @@ pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, CStrConvertError
> > unsafe { core::mem::transmute(bytes) }
> > }
> > + /// Creates a mutable [`CStr`] from a `[u8]` without performing any
> > + /// additional checks.
> > + ///
> > + /// # Safety
> > + ///
> > + /// `bytes` *must* end with a `NUL` byte, and should only have a single
> > + /// `NUL` byte (or the string will be truncated).
> > + #[inline]
> > + pub unsafe fn from_bytes_with_nul_unchecked_mut(bytes: &mut [u8]) -> &mut CStr {
> > + // SAFETY: Properties of `bytes` guaranteed by the safety precondition.
> > + unsafe { &mut *(bytes as *mut [u8] as *mut CStr) }
> > + }
> > +
> > /// Returns a C pointer to the string.
> > #[inline]
> > pub const fn as_char_ptr(&self) -> *const core::ffi::c_char {
> > @@ -206,6 +219,70 @@ pub unsafe fn as_str_unchecked(&self) -> &str {
> > pub fn to_cstring(&self) -> Result<CString, AllocError> {
> > CString::try_from(self)
> > }
> > +
> > + /// Converts this [`CStr`] to its ASCII lower case equivalent in-place.
> > + ///
> > + /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
> > + /// but non-ASCII letters are unchanged.
> > + ///
> > + /// To return a new lowercased value without modifying the existing one, use
> > + /// [`to_ascii_lowercase()`].
> > + ///
> > + /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
> > + pub fn make_ascii_lowercase(&mut self) {
> > + // INVARIANT: This doesn't introduce or remove NUL bytes in the C
> > + // string.
> > + self.0.make_ascii_lowercase();
> > + }
> > +
> > + /// Converts this [`CStr`] to its ASCII upper case equivalent in-place.
> > + ///
> > + /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
> > + /// but non-ASCII letters are unchanged.
> > + ///
> > + /// To return a new uppercased value without modifying the existing one, use
> > + /// [`to_ascii_uppercase()`].
> > + ///
> > + /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
> > + pub fn make_ascii_uppercase(&mut self) {
> > + // INVARIANT: This doesn't introduce or remove NUL bytes in the C
> > + // string.
> > + self.0.make_ascii_uppercase();
> > + }
> > +
> > + /// Returns a copy of this [`CString`] where each character is mapped to its
> > + /// ASCII lower case equivalent.
> > + ///
> > + /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
> > + /// but non-ASCII letters are unchanged.
> > + ///
> > + /// To lowercase the value in-place, use [`make_ascii_lowercase`].
> > + ///
> > + /// [`make_ascii_lowercase`]: str::make_ascii_lowercase
> > + pub fn to_ascii_lowercase(&self) -> Result<CString, AllocError> {
> > + let mut s = self.to_cstring()?;
> > +
> > + s.make_ascii_lowercase();
> > +
> > + Ok(s)
> > + }
> > +
> > + /// Returns a copy of this [`CString`] where each character is mapped to its
> > + /// ASCII upper case equivalent.
> > + ///
> > + /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
> > + /// but non-ASCII letters are unchanged.
> > + ///
> > + /// To uppercase the value in-place, use [`make_ascii_uppercase`].
> > + ///
> > + /// [`make_ascii_uppercase`]: str::make_ascii_uppercase
> > + pub fn to_ascii_uppercase(&self) -> Result<CString, AllocError> {
> > + let mut s = self.to_cstring()?;
> > +
> > + s.make_ascii_uppercase();
> > +
> > + Ok(s)
> > + }
> > }
> > impl fmt::Display for CStr {
> > @@ -593,6 +670,14 @@ fn deref(&self) -> &Self::Target {
> > }
> > }
> > +impl DerefMut for CString {
> > + fn deref_mut(&mut self) -> &mut Self::Target {
> > + // SAFETY: A `CString` is always NUL-terminated and contains no other
> > + // NUL bytes.
> > + unsafe { CStr::from_bytes_with_nul_unchecked_mut(self.buf.as_mut_slice()) }
> > + }
> > +}
> > +
> > impl<'a> TryFrom<&'a CStr> for CString {
> > type Error = AllocError;
> >
> > base-commit: 39133352cbed6626956d38ed72012f49b0421e7b
On Mon, Mar 11, 2024 at 1:22 PM Danilo Krummrich <[email protected]> wrote:
>
> It doesn't seem there's any further feedback, thus can this be merged?
No, it cannot be applied until the merge window closes, i.e. 2 weeks from now.
Please note that there are other patches yet to be applied that were
sent before this v5 -- we aim to send early PRs to Linus, and in
general for at least a week in -next and for at least a week for
review. Thus -rc5/6 is already quite late in general.
Cheers,
Miguel
On 3/11/24 14:10, Miguel Ojeda wrote:
> On Mon, Mar 11, 2024 at 1:22 PM Danilo Krummrich <[email protected]> wrote:
>>
>> It doesn't seem there's any further feedback, thus can this be merged?
>
> No, it cannot be applied until the merge window closes, i.e. 2 weeks from now.
>
> Please note that there are other patches yet to be applied that were
> sent before this v5 -- we aim to send early PRs to Linus, and in
> general for at least a week in -next and for at least a week for
> review. Thus -rc5/6 is already quite late in general.
Thanks for sharing, that sounds all good. Just wanted to know if the
patch was queued up.
- Danilo
>
> Cheers,
> Miguel
>
On 2/23/24 17:37, Danilo Krummrich wrote:
> Add functions to convert a CString to upper- / lowercase, either
> in-place or by creating a copy of the original CString.
>
> Naming followes the one from the Rust stdlib, where functions starting
> with 'to' create a copy and functions starting with 'make' perform an
> in-place conversion.
>
> This is required by the Nova project (GSP only Rust successor of
> Nouveau) to convert stringified enum values (representing different GPU
> chipsets) to strings in order to generate the corresponding firmware
> paths. See also [1].
>
> [1] https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/String.20manipulation.20in.20kernel.20Rust
>
> Reviewed-by: Alice Ryhl <[email protected]>
> Signed-off-by: Danilo Krummrich <[email protected]>
Reviewed-by: Benno Lossin <[email protected]>
--
Cheers,
Benno
On Tue, Mar 12, 2024 at 9:08 AM Danilo Krummrich <[email protected]> wrote:
>
> Thanks for sharing, that sounds all good. Just wanted to know if the
> patch was queued up.
My pleasure -- I took the chance to add it to our Contributing page
(which is our `P:` field, i.e. Maintainer Entry Profile):
https://rust-for-linux.com/contributing
Cheers,
Miguel
On Fri, Feb 23, 2024 at 5:37 PM Danilo Krummrich <[email protected]> wrote:
>
> Add functions to convert a CString to upper- / lowercase, either
> in-place or by creating a copy of the original CString.
>
> Naming followes the one from the Rust stdlib, where functions starting
> with 'to' create a copy and functions starting with 'make' perform an
> in-place conversion.
>
> This is required by the Nova project (GSP only Rust successor of
> Nouveau) to convert stringified enum values (representing different GPU
> chipsets) to strings in order to generate the corresponding firmware
> paths. See also [1].
>
> [1] https://rust-for-linux.zulipchat.com/#narrow/stream/288089-General/topic/String.20manipulation.20in.20kernel.20Rust
>
> Reviewed-by: Alice Ryhl <[email protected]>
> Signed-off-by: Danilo Krummrich <[email protected]>
[ Reworded to fix typo and to make the link use the `Link:` tag. ]
Applied to `rust-next` -- thanks everyone!
Cheers,
Miguel