summary refs log tree commit diff
path: root/library/alloc/src/string.rs
AgeCommit message (Collapse)AuthorLines
2022-06-19Fix documentation for with_capacity and reserve families of methodsjmaargh-35/+35
Documentation for the following methods with_capacity with_capacity_in with_capacity_and_hasher reserve reserve_exact try_reserve try_reserve_exact was inconsistent and often not entirely correct where they existed on the following types Vec VecDeque String OsString PathBuf BinaryHeap HashSet HashMap BufWriter LineWriter since the allocator is allowed to allocate more than the requested capacity in all such cases, and will frequently "allocate" much more in the case of zero-sized types (I also checked BufReader, but there the docs appear to be accurate as it appears to actually allocate the exact capacity). Some effort was made to make the documentation more consistent between types as well. Fix with_capacity* methods for Vec Fix *reserve* methods for Vec Fix docs for *reserve* methods of VecDeque Fix docs for String::with_capacity Fix docs for *reserve* methods of String Fix docs for OsString::with_capacity Fix docs for *reserve* methods on OsString Fix docs for with_capacity* methods on HashSet Fix docs for *reserve methods of HashSet Fix docs for with_capacity* methods of HashMap Fix docs for *reserve methods on HashMap Fix expect messages about OOM in doctests Fix docs for BinaryHeap::with_capacity Fix docs for *reserve* methods of BinaryHeap Fix typos Fix docs for with_capacity on BufWriter and LineWriter Fix consistent use of `hasher` between `HashMap` and `HashSet` Fix warning in doc test Add test for capacity of vec with ZST Fix doc test error
2022-05-21Auto merge of #96605 - Urgau:string-retain-codegen, r=thomccbors-8/+17
Improve codegen of String::retain method This pull-request improve the codegen of the `String::retain` method. Using `unwrap_unchecked` helps the optimizer to not generate a panicking path that will never be taken for valid UTF-8 like string. Using `encode_utf8` saves us from an expensive call to `memcpy`, as the optimizer is unable to realize that `ch_len <= 4` and so can generate much better assembly code. https://rust.godbolt.org/z/z73ohenfc
2022-05-01Improve codegen of String::retain method.Loïc BRANSTETT-8/+17
Using unwrap_unchecked helps the optimizer to not generate panicking path, that will never be taken for valid UTF-8 like string. Using encode_utf8 saves us a call to a memcpy, as the optimizer is unable to realize that ch_len <= 4 and so can generate much better assembly code. https://rust.godbolt.org/z/z73ohenfc
2022-04-19Clarify docs for from_raw_partsjmaargh-1/+4
Original safety explanation for from_raw_parts was unclear on safety for consuming a C string. This clarifies when doing so is safe.
2022-04-09Rework String UTF-8 DocumentationMark Lodato-10/+82
**This Commit** Adds some clarity around indexing into Strings and the constraints driving various decisions there. **Why?** The [`String` documentation][0] mentions how `String`s can't be indexed but `Range` has an implementation for `SliceIndex<str>`. This can be confusing. There are also several statements to explain the lack of `String` indexing: - the inability to index into a `String` is an implication of UTF-8 encoding - indexing into a `String` could not be constant-time with UTF-8 encoding - indexing into a `String` does not have an obvious return type This last statement made sense but the first two seemed contradictory to the documentation around [`SliceIndex<str>`][1] which mention: - one can index into a `String` with a `Range` (also called substring slicing but it uses the same syntax and the method name is `index`) - `Range` indexing into a `String` is constant-time To resolve this seeming contradiction the documentation is reworked to more clearly explain what factors drive the decision to disallow indexing into a `String` with a single number. [0]: https://doc.rust-lang.org/stable/std/string/struct.String.html#utf-8 [1]: https://doc.rust-lang.org/stable/std/slice/trait.SliceIndex.html#impl-SliceIndex%3Cstr%3E
2022-03-27Rollup merge of #95368 - ↵Dylan DPC-1/+1
lopopolo:lopopolo/string-try-reserve-exact-doc-typo, r=Dylan-DPC Fix typo in `String::try_reserve_exact` docs Copying the pattern from `Vec::try_reserve_exact` and `String::try_reserve`, it looks like this doc comment is intending to refer to the currently-being-documented function.
2022-03-27Fix typo in `String::try_reserve_exact` docsRyan Lopopolo-1/+1
Copying the pattern from `Vec::try_reserve_exact` and `String::try_reserve`, it looks like this doc comment is intending to refer to the currently-being-documented function.
2022-03-10Use implicit capture syntax in format_argsT-O-R-U-S-1/+1
This updates the standard library's documentation to use the new syntax. The documentation is worthwhile to update as it should be more idiomatic (particularly for features like this, which are nice for users to get acquainted with). The general codebase is likely more hassle than benefit to update: it'll hurt git blame, and generally updates can be done by folks updating the code if (and when) that makes things more readable with the new format. A few places in the compiler and library code are updated (mostly just due to already having been done when this commit was first authored).
2022-02-19Collections: improve the documentation of drain membersStein Somers-5/+12
2021-12-29Fix a minor mistake in `String::try_reserve_exact` examplesSprite-1/+1
2021-12-05doc: suggest try_reserve in try_reserve_exactTennyZhuang-2/+2
Signed-off-by: TennyZhuang <zty0826@gmail.com>
2021-11-25Eliminate an unreachable codepath from String::from_utf8_lossyDavid Tolnay-7/+5
Utf8Lossy's Iterator implementation ensures that only the final chunk has an empty slice for broken. Thus the only way the first chunk could have an empty broken is if it is the final chunk, i.e. there is only one chunk total. And the only way that there could be one chunk total is if the whole input is valid utf8 and non-empty. That condition has already been handled by an early return, so at the point that the first REPLACEMENT is being pushed, it's impossible for first_broken to be empty.
2021-10-31Rollup merge of #89786 - jkugelman:must-use-len-and-is_empty, r=joshtriplettMatthias Krüger-0/+2
Add #[must_use] to len and is_empty Parent issue: #89692 r? `@joshtriplett`
2021-10-31Rollup merge of #89835 - jkugelman:must-use-expensive-computations, ↵Matthias Krüger-0/+2
r=joshtriplett Add #[must_use] to expensive computations The unifying theme for this commit is weak, admittedly. I put together a list of "expensive" functions when I originally proposed this whole effort, but nobody's cared about that criterion. Still, it's a decent way to bite off a not-too-big chunk of work. Given the grab bag nature of this commit, the messages I used vary quite a bit. I'm open to wording changes. For some reason clippy flagged four `BTreeSet` methods but didn't say boo about equivalent ones on `HashSet`. I stared at them for a while but I can't figure out the difference so I added the `HashSet` ones in. ```rust // Flagged by clippy. alloc::collections::btree_set::BTreeSet<T> fn difference<'a>(&'a self, other: &'a BTreeSet<T>) -> Difference<'a, T>; alloc::collections::btree_set::BTreeSet<T> fn symmetric_difference<'a>(&'a self, other: &'a BTreeSet<T>) -> SymmetricDifference<'a, T> alloc::collections::btree_set::BTreeSet<T> fn intersection<'a>(&'a self, other: &'a BTreeSet<T>) -> Intersection<'a, T>; alloc::collections::btree_set::BTreeSet<T> fn union<'a>(&'a self, other: &'a BTreeSet<T>) -> Union<'a, T>; // Ignored by clippy, but not by me. std::collections::HashSet<T, S> fn difference<'a>(&'a self, other: &'a HashSet<T, S>) -> Difference<'a, T, S>; std::collections::HashSet<T, S> fn symmetric_difference<'a>(&'a self, other: &'a HashSet<T, S>) -> SymmetricDifference<'a, T, S> std::collections::HashSet<T, S> fn intersection<'a>(&'a self, other: &'a HashSet<T, S>) -> Intersection<'a, T, S>; std::collections::HashSet<T, S> fn union<'a>(&'a self, other: &'a HashSet<T, S>) -> Union<'a, T, S>; ``` Parent issue: #89692 r? ```@joshtriplett```
2021-10-30Add #[must_use] to len and is_emptyJohn Kugelman-0/+2
2021-10-31Rollup merge of #89899 - jkugelman:must-use-alloc, r=joshtriplettMatthias Krüger-0/+2
Add #[must_use] to remaining alloc functions I've run out of compelling reasons to group functions together across crates so I'm just going to go module-by-module. This is everything remaining from the `alloc` crate. I ignored these because they might be used to purposefully leak memory... or other allocator shenanigans? I dunno. I'll add them if y'all tell me to. ```rust alloc::alloc unsafe fn alloc(layout: Layout) -> *mut u8; alloc::alloc unsafe fn alloc_zeroed(layout: Layout) -> *mut u8; alloc::sync::Arc<T> fn into_raw(this: Self) -> *const T; ``` I don't know why clippy ignored these. I added them myself: ```rust alloc::collections::btree_map::BTreeMap<K, V> fn range<T: ?Sized, R>(&self, range: R) -> Range<'_, K, V>; alloc::collections::btree_set::BTreeSet<T> fn range<K: ?Sized, R>(&self, range: R) -> Range<'_, T>; ``` I added these non-mutating `mut` functions: ```rust alloc::collections::btree_map::BTreeMap<K, V> fn range_mut<T: ?Sized, R>(&mut self, range: R) -> RangeMut<'_, K, V>; alloc::collections::btree_map::BTreeMap<K, V> fn iter_mut(&mut self) -> IterMut<'_, K, V>; alloc::collections::btree_map::BTreeMap<K, V> fn values_mut(&mut self) -> ValuesMut<'_, K, V>; alloc::collections::linked_list::LinkedList<T> fn iter_mut(&mut self) -> IterMut<'_, T>; alloc::collections::linked_list::LinkedList<T> fn cursor_front_mut(&mut self) -> CursorMut<'_, T>; alloc::collections::linked_list::LinkedList<T> fn cursor_back_mut(&mut self) -> CursorMut<'_, T>; alloc::collections::linked_list::LinkedList<T> fn front_mut(&mut self) -> Option<&mut T>; alloc::collections::linked_list::LinkedList<T> fn back_mut(&mut self) -> Option<&mut T>; alloc::collections::linked_list::CursorMut<'a, T> fn current(&mut self) -> Option<&mut T>; alloc::collections::linked_list::CursorMut<'a, T> fn peek_next(&mut self) -> Option<&mut T>; alloc::collections::linked_list::CursorMut<'a, T> fn peek_prev(&mut self) -> Option<&mut T>; alloc::collections::linked_list::CursorMut<'a, T> fn front_mut(&mut self) -> Option<&mut T>; alloc::collections::linked_list::CursorMut<'a, T> fn back_mut(&mut self) -> Option<&mut T>; ``` I moved a few existing `#[must_use]`s from functions onto the iterator types they return: `IntoIterSorted`, `IntoKeys`, `IntoValues`. Parent issue: #89692 r? `@joshtriplett`
2021-10-25Fix copy-paste error in String::as_mut_vec() docsnyanpasu64-4/+5
2021-10-15Add #[must_use] to remaining alloc functionsJohn Kugelman-0/+2
2021-10-12Add #[must_use] to expensive computationsJohn Kugelman-0/+2
The unifying theme for this commit is weak, admittedly. I put together a list of "expensive" functions when I originally proposed this whole effort, but nobody's cared about that criterion. Still, it's a decent way to bite off a not-too-big chunk of work. Given the grab bag nature of this commit, the messages I used vary quite a bit.
2021-10-12Rollup merge of #89778 - jkugelman:must-use-as_type-conversions, r=joshtriplettthe8472-0/+5
Add #[must_use] to as_type conversions Clippy missed these: ```rust alloc::string::String fn as_mut_str(&mut self) -> &mut str; core::mem::NonNull<T> unsafe fn as_uninit_mut<'a>(&mut self) -> &'a MaybeUninit<T>; str unsafe fn as_bytes_mut(&mut self) -> &mut [u8]; str fn as_mut_ptr(&mut self) -> *mut u8; ``` Parent issue: #89692 r? ````@joshtriplett````
2021-10-11Add #[must_use] to as_type conversionsJohn Kugelman-0/+5
2021-10-11Rollup merge of #89753 - jkugelman:must-use-from_value-conversions, ↵Guillaume Gomez-0/+1
r=joshtriplett Add #[must_use] to from_value conversions I added two methods to the list myself. Clippy did not flag them because they take `mut` args, but neither modifies their argument. ```rust core::str const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str; std::ffi::CString unsafe fn from_raw(ptr: *mut c_char) -> CString; ``` I put a custom note on `from_raw`: ```rust #[must_use = "call `drop(from_raw(ptr))` if you intend to drop the `CString`"] pub unsafe fn from_raw(ptr: *mut c_char) -> CString { ``` Parent issue: #89692 r? ``@joshtriplett``
2021-10-11Rollup merge of #89726 - jkugelman:must-use-alloc-constructors, r=joshtriplettGuillaume Gomez-0/+2
Add #[must_use] to alloc constructors Added `#[must_use]`. to the various forms of `new`, `pin`, and `with_capacity` in the `alloc` crate. No extra explanations given as I couldn't think of anything useful to add. I figure this deserves extra scrutiny compared to the other PRs I've done so far. In particular: * The 4 `pin`/`pin_in` methods I touched. Are there legitimate use cases for pinning and not using the result? Pinning's a difficult concept I'm not very comfortable with. * `Box`'s constructors. Do people ever create boxes just for the side effects... allocating or zeroing out memory? Parent issue: #89692 r? ``@joshtriplett``
2021-10-10Add #[must_use] to conversions that move selfJohn Kugelman-0/+4
2021-10-10Add #[must_use] to from_value conversionsJohn Kugelman-0/+1
2021-10-10Add #[must_use] to alloc constructorsJohn Kugelman-0/+2
2021-10-04Stabilize try_reserveKornel-4/+2
2021-10-02Make diangostic item names consistentCameron Steffen-1/+1
2021-09-25Apply 16 commits (squashed)Frank Steffahn-23/+25
---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::fmt ---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::{rc, sync} ---------- Fix spacing for links inside code blocks, and improve link tooltips in alloc::string ---------- Fix spacing for links inside code blocks in alloc::vec ---------- Fix spacing for links inside code blocks in core::option ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in core::result ---------- Fix spacing for links inside code blocks in core::{iter::{self, iterator}, stream::stream, poll} ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in std::{fs, path} ---------- Fix spacing for links inside code blocks in std::{collections, time} ---------- Fix spacing for links inside code blocks in and make formatting of `&str`-like types consistent in std::ffi::{c_str, os_str} ---------- Fix spacing for links inside code blocks, and improve link tooltips in std::ffi ---------- Fix spacing for links inside code blocks, and improve a few link tooltips in std::{io::{self, buffered::{bufreader, bufwriter}, cursor, util}, net::{self, addr}} ---------- Fix typo in link to `into` for `OsString` docs ---------- Remove tooltips that will probably become redundant in the future ---------- Apply suggestions from code review Replacing `…std/primitive.reference.html` paths with just `reference` Co-authored-by: Joshua Nelson <github@jyn.dev> ---------- Also replace `…std/primitive.reference.html` paths with just `reference` in `core::pin`
2021-08-17Constified `Default` implementationsDeadbeef-1/+2
The libs-api team agrees to allow const_trait_impl to appear in the standard library as long as stable code cannot be broken (they are properly gated) this means if the compiler teams thinks it's okay, then it's okay. My priority on constifying would be: 1. Non-generic impls (e.g. Default) or generic impls with no bounds 2. Generic functions with bounds (that use const impls) 3. Generic impls with bounds 4. Impls for traits with associated types For people opening constification PRs: please cc me and/or oli-obk.
2021-08-08Auto merge of #86879 - YohDeadfall:stabilize-vec-shrink-to, r=dtolnaybors-2/+1
Stabilize Vec<T>::shrink_to This PR stabilizes `shrink_to` feature and closes the corresponding issue. The second point was addressed already, and no `panic!` should occur. Closes #56431.
2021-08-08Bump shrink_to stabilization to Rust 1.56David Tolnay-1/+1
2021-08-05alloc: Use intra doc links for the reserve functionest31-1/+3
The sentence exists to highlight the existence of a performance footgun of repeated calls of the reserve_exact function.
2021-07-30Rollup merge of #87574 - cuviper:retain-examples, r=joshtriplettYuki Okushi-3/+4
Update the examples in `String` and `VecDeque::retain` The examples added in #60396 used a "clever" post-increment hack, unrelated to the actual point of the examples. That hack was found [confusing] in the users forum, and #81811 already changed the `Vec` example to use a more direct iterator. This commit changes `String` and `VecDeque` in the same way for consistency. [confusing]: https://users.rust-lang.org/t/help-understand-strange-expression/62858
2021-07-29Fix may not to appropriate might not or must notAli Malik-3/+3
2021-07-28Update the examples in `String` and `VecDeque::retain`Josh Stone-3/+4
The examples added in #60396 used a "clever" post-increment hack, unrelated to the actual point of the examples. That hack was found [confusing] in the users forum, and #81811 already changed the `Vec` example to use a more direct iterator. This commit changes `String` and `VecDeque` in the same way for consistency. [confusing]: https://users.rust-lang.org/t/help-understand-strange-expression/62858
2021-07-06Stabilize Vec<T>::shrink_toYoh Deadfall-2/+1
2021-07-06Rollup merge of #86852 - Amanieu:remove_doc_aliases, r=joshtriplettYuki Okushi-3/+0
Remove some doc aliases As per the new doc alias policy in https://github.com/rust-lang/std-dev-guide/pull/25, this removes some controversial doc aliases: - `malloc`, `alloc`, `realloc`, etc. - `length` (alias for `len`) - `delete` (alias for `remove` in collections and also file/directory deletion) r? `@joshtriplett`
2021-07-04Stabilize `string_drain_as_str`Yuki Okushi-16/+14
2021-06-30Remove "length" doc aliasesAmanieu d'Antras-1/+0
2021-06-30Remove alloc/malloc/calloc/realloc doc aliasesAmanieu d'Antras-2/+0
2021-06-18Use `copy_nonoverlapping` to copy `bytes` in `String::insert_bytes`Paolo Barbolini-1/+1
2021-06-09Rollup merge of #85715 - fee1-dead:document-string, r=JohnTitorYuki Okushi-7/+43
Document `From` impls in string.rs
2021-06-06String::remove_matches O(n^2) -> O(n)Tamir Duberstein-15/+38
Copy only non-matching bytes.
2021-06-06Use iter::from_fn in String::remove_matchesTamir Duberstein-9/+3
2021-05-29Add `String::extend_from_within`Waffle-0/+36
This patch adds `String::extend_from_within` function under the `string_extend_from_within` feature gate similar to the `Vec::extend_from_within` function.
2021-05-26Document `From` impls in string.rsDeadbeef-7/+43
2021-05-17Optimize default ToString implMark Rousskov-2/+3
This avoids a zero-length write_str call, which boils down to a zero-length memmove and ultimately costs quite a few instructions on some workloads. This is approximately a 0.33% instruction count win on diesel-check.
2021-05-05alloc: Add unstable Cfg feature `no-global_oom_handling`John Ericson-5/+75
For certain sorts of systems, programming, it's deemed essential that all allocation failures be explicitly handled where they occur. For example, see Linus Torvald's opinion in [1]. Merely not calling global panic handlers, or always `try_reserving` first (for vectors), is not deemed good enough, because the mere presence of the global OOM handlers is burdens static analysis. One option for these projects to use rust would just be to skip `alloc`, rolling their own allocation abstractions. But this would, in my opinion be a real shame. `alloc` has a few `try_*` methods already, and we could easily have more. Features like custom allocator support also demonstrate and existing to support diverse use-cases with the same abstractions. A natural way to add such a feature flag would a Cargo feature, but there are currently uncertainties around how std library crate's Cargo features may or not be stable, so to avoid any risk of stabilizing by mistake we are going with a more low-level "raw cfg" token, which cannot be interacted with via Cargo alone. Note also that since there is no notion of "default cfg tokens" outside of Cargo features, we have to invert the condition from `global_oom_handling` to to `not(no_global_oom_handling)`. This breaks the monotonicity that would be important for a Cargo feature (i.e. turning on more features should never break compatibility), but it doesn't matter for raw cfg tokens which are not intended to be "constraint solved" by Cargo or anything else. To support this use-case we create a new feature, "global-oom-handling", on by default, and put the global OOM handler infra and everything else it that depends on it behind it. By default, nothing is changed, but users concerned about global handling can make sure it is disabled, and be confident that all OOM handling is local and explicit. For this first iteration, non-flat collections are outright disabled. `Vec` and `String` don't yet have `try_*` allocation methods, but are kept anyways since they can be oom-safely created "from parts", and we hope to add those `try_` methods in the future. [1]: https://lore.kernel.org/lkml/CAHk-=wh_sNLoz84AUUzuqXEsYH35u=8HV3vK-jbRbJ_B-JjGrg@mail.gmail.com/
2021-05-03Fix stability attributes of byte-to-string specializationLingMan-2/+2
generated by cgit-pink 1.4.1-3-g733a5 (git 2.37.1) at 2026-03-02 04:24:11 +0000