linux.git/rust/kernel/str.rs, branch v6.6.132

rust: str: make doctests compilable/testable

2023-07-19T15:25:02+00:00

Rust documentation tests are going to be build/run-tested
with the KUnit integration added in a future patch, thus
update them to make them compilable/testable so that we
may start enforcing it.

Reviewed-by: Björn Roy Baron 
Reviewed-by: Alice Ryhl 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Vincenzo Palazzo 
Reviewed-by: David Gow 
Signed-off-by: Miguel Ojeda 
Signed-off-by: Shuah Khan

rust: str: add conversion from `CStr` to `CString`

2023-05-31T16:53:10+00:00

These methods can be used to copy the data in a temporary c string into
a separate allocation, so that it can be accessed later even if the
original is deallocated.

The API in this change mirrors the standard library API for the `&str`
and `String` types. The `ToOwned` trait is not implemented because it
assumes that allocations are infallible.

Reviewed-by: Benno Lossin 
Signed-off-by: Alice Ryhl 
Reviewed-by: Martin Rodriguez Reboredo 
Reviewed-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20230503141016.683634-1-aliceryhl@google.com
Signed-off-by: Miguel Ojeda

rust: str: fix requierments->requirements typo

2023-04-06T19:55:12+00:00

Fix a trivial spelling error in the `rust/kernel/str.rs` file.

Fixes: 247b365dc8dc ("rust: add `kernel` crate")
Reported-by: Miguel Ojeda 
Link: https://github.com/Rust-for-Linux/linux/issues/978
Signed-off-by: Patrick Blass 
Reviewed-by: Vincenzo Palazzo 
[Reworded slightly]
Signed-off-by: Miguel Ojeda

rust: str: add `fmt!` macro

2022-12-04T00:59:16+00:00

Add the `fmt!` macro, which is a convenience alias for the Rust
`core::format_args!` macro.

For instance, it may be used to create a `CString`:

    CString::try_from_fmt(fmt!("{}{}", "abc", 42))?

Signed-off-by: Wedson Almeida Filho 
Reviewed-by: Gary Guo 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `CString` type

2022-12-04T00:59:15+00:00

Add the `CString` type, which is an owned string that is guaranteed
to have exactly one `NUL` byte at the end, i.e. the owned equivalent
to `CStr` introduced earlier.

It is used for interoperability with kernel APIs that take C strings.

In order to do so, implement the `RawFormatter::new()` constructor
and the `RawFormatter::bytes_written()` method as well.

Signed-off-by: Wedson Almeida Filho 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `Formatter` type

2022-12-04T00:59:15+00:00

Add the `Formatter` type, which leverages `RawFormatter`,
but fails if callers attempt to write more than will fit
in the buffer.

In order to so, implement the `RawFormatter::from_buffer()`
constructor as well.

Co-developed-by: Adam Bratschi-Kaye 
Signed-off-by: Adam Bratschi-Kaye 
Signed-off-by: Wedson Almeida Filho 
Reviewed-by: Gary Guo 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `c_str!` macro

2022-12-04T00:59:15+00:00

Add `c_str!`, which is a convenience macro that creates a new `CStr`
from a string literal.

It is designed to be similar to a `str` in usage, and it is usable
in const contexts, for instance:

    const X: &CStr = c_str!("Example");

Co-developed-by: Alex Gaynor 
Signed-off-by: Alex Gaynor 
Signed-off-by: Gary Guo 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `CStr` unit tests

2022-12-04T00:59:15+00:00

Add unit tests for `CStr::from_bytes_with_nul()` and
`CStr::from_bytes_with_nul_unchecked()`.

These serve as an example of the first unit tests for Rust code
(i.e. different from documentation tests).

Signed-off-by: Milan Landaverde 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: implement several traits for `CStr`

2022-12-04T00:59:15+00:00

Implement `Debug`, `Display`, `Deref` (into `BStr`), `AsRef`
and a set of `Index<...>` traits.

This makes it `CStr` more convenient to use (and closer to `str`).

Co-developed-by: Alex Gaynor 
Signed-off-by: Alex Gaynor 
Co-developed-by: Morgan Bartlett 
Signed-off-by: Morgan Bartlett 
Signed-off-by: Gary Guo 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda

rust: str: add `CStr` type

2022-12-04T00:59:15+00:00

Add the `CStr` type, which is a borrowed string that is guaranteed
to have exactly one `NUL` byte, which is at the end.

It is used for interoperability with kernel APIs that take C strings.

Add it to the prelude too.

Co-developed-by: Alex Gaynor 
Signed-off-by: Alex Gaynor 
Co-developed-by: Milan Landaverde 
Signed-off-by: Milan Landaverde 
Signed-off-by: Gary Guo 
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda