1 use std::borrow::Cow;
2 use std::error;
3 use std::ffi::{OsStr, OsString};
4 use std::fmt;
5 use std::iter;
6 use std::ops;
7 use std::path::{Path, PathBuf};
8 use std::ptr;
9 use std::str;
10 use std::vec;
11
12 use crate::ext_slice::ByteSlice;
13 use crate::utf8::{self, Utf8Error};
14
15 /// Concatenate the elements given by the iterator together into a single
16 /// `Vec<u8>`.
17 ///
18 /// The elements may be any type that can be cheaply converted into an `&[u8]`.
19 /// This includes, but is not limited to, `&str`, `&BStr` and `&[u8]` itself.
20 ///
21 /// # Examples
22 ///
23 /// Basic usage:
24 ///
25 /// ```
26 /// use bstr;
27 ///
28 /// let s = bstr::concat(&["foo", "bar", "baz"]);
29 /// assert_eq!(s, "foobarbaz".as_bytes());
30 /// ```
31 #[inline]
concat<T, I>(elements: I) -> Vec<u8> where T: AsRef<[u8]>, I: IntoIterator<Item = T>,32 pub fn concat<T, I>(elements: I) -> Vec<u8>
33 where
34 T: AsRef<[u8]>,
35 I: IntoIterator<Item = T>,
36 {
37 let mut dest = vec![];
38 for element in elements {
39 dest.push_str(element);
40 }
41 dest
42 }
43
44 /// Join the elements given by the iterator with the given separator into a
45 /// single `Vec<u8>`.
46 ///
47 /// Both the separator and the elements may be any type that can be cheaply
48 /// converted into an `&[u8]`. This includes, but is not limited to,
49 /// `&str`, `&BStr` and `&[u8]` itself.
50 ///
51 /// # Examples
52 ///
53 /// Basic usage:
54 ///
55 /// ```
56 /// use bstr;
57 ///
58 /// let s = bstr::join(",", &["foo", "bar", "baz"]);
59 /// assert_eq!(s, "foo,bar,baz".as_bytes());
60 /// ```
61 #[inline]
join<B, T, I>(separator: B, elements: I) -> Vec<u8> where B: AsRef<[u8]>, T: AsRef<[u8]>, I: IntoIterator<Item = T>,62 pub fn join<B, T, I>(separator: B, elements: I) -> Vec<u8>
63 where
64 B: AsRef<[u8]>,
65 T: AsRef<[u8]>,
66 I: IntoIterator<Item = T>,
67 {
68 let mut it = elements.into_iter();
69 let mut dest = vec![];
70 match it.next() {
71 None => return dest,
72 Some(first) => {
73 dest.push_str(first);
74 }
75 }
76 for element in it {
77 dest.push_str(&separator);
78 dest.push_str(element);
79 }
80 dest
81 }
82
83 impl ByteVec for Vec<u8> {
84 #[inline]
as_vec(&self) -> &Vec<u8>85 fn as_vec(&self) -> &Vec<u8> {
86 self
87 }
88
89 #[inline]
as_vec_mut(&mut self) -> &mut Vec<u8>90 fn as_vec_mut(&mut self) -> &mut Vec<u8> {
91 self
92 }
93
94 #[inline]
into_vec(self) -> Vec<u8>95 fn into_vec(self) -> Vec<u8> {
96 self
97 }
98 }
99
100 /// Ensure that callers cannot implement `ByteSlice` by making an
101 /// umplementable trait its super trait.
102 pub trait Sealed {}
103 impl Sealed for Vec<u8> {}
104
105 /// A trait that extends `Vec<u8>` with string oriented methods.
106 ///
107 /// Note that when using the constructor methods, such as
108 /// `ByteVec::from_slice`, one should actually call them using the concrete
109 /// type. For example:
110 ///
111 /// ```
112 /// use bstr::{B, ByteVec};
113 ///
114 /// let s = Vec::from_slice(b"abc"); // NOT ByteVec::from_slice("...")
115 /// assert_eq!(s, B("abc"));
116 /// ```
117 pub trait ByteVec: Sealed {
118 /// A method for accessing the raw vector bytes of this type. This is
119 /// always a no-op and callers shouldn't care about it. This only exists
120 /// for making the extension trait work.
121 #[doc(hidden)]
as_vec(&self) -> &Vec<u8>122 fn as_vec(&self) -> &Vec<u8>;
123
124 /// A method for accessing the raw vector bytes of this type, mutably. This
125 /// is always a no-op and callers shouldn't care about it. This only exists
126 /// for making the extension trait work.
127 #[doc(hidden)]
as_vec_mut(&mut self) -> &mut Vec<u8>128 fn as_vec_mut(&mut self) -> &mut Vec<u8>;
129
130 /// A method for consuming ownership of this vector. This is always a no-op
131 /// and callers shouldn't care about it. This only exists for making the
132 /// extension trait work.
133 #[doc(hidden)]
into_vec(self) -> Vec<u8> where Self: Sized134 fn into_vec(self) -> Vec<u8>
135 where
136 Self: Sized;
137
138 /// Create a new owned byte string from the given byte slice.
139 ///
140 /// # Examples
141 ///
142 /// Basic usage:
143 ///
144 /// ```
145 /// use bstr::{B, ByteVec};
146 ///
147 /// let s = Vec::from_slice(b"abc");
148 /// assert_eq!(s, B("abc"));
149 /// ```
150 #[inline]
from_slice<B: AsRef<[u8]>>(bytes: B) -> Vec<u8>151 fn from_slice<B: AsRef<[u8]>>(bytes: B) -> Vec<u8> {
152 bytes.as_ref().to_vec()
153 }
154
155 /// Create a new byte string from an owned OS string.
156 ///
157 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
158 /// this returns the original OS string if it is not valid UTF-8.
159 ///
160 /// # Examples
161 ///
162 /// Basic usage:
163 ///
164 /// ```
165 /// use std::ffi::OsString;
166 ///
167 /// use bstr::{B, ByteVec};
168 ///
169 /// let os_str = OsString::from("foo");
170 /// let bs = Vec::from_os_string(os_str).expect("valid UTF-8");
171 /// assert_eq!(bs, B("foo"));
172 /// ```
173 #[inline]
from_os_string(os_str: OsString) -> Result<Vec<u8>, OsString>174 fn from_os_string(os_str: OsString) -> Result<Vec<u8>, OsString> {
175 #[cfg(unix)]
176 #[inline]
177 fn imp(os_str: OsString) -> Result<Vec<u8>, OsString> {
178 use std::os::unix::ffi::OsStringExt;
179
180 Ok(Vec::from(os_str.into_vec()))
181 }
182
183 #[cfg(not(unix))]
184 #[inline]
185 fn imp(os_str: OsString) -> Result<Vec<u8>, OsString> {
186 os_str.into_string().map(Vec::from)
187 }
188
189 imp(os_str)
190 }
191
192 /// Lossily create a new byte string from an OS string slice.
193 ///
194 /// On Unix, this always succeeds, is zero cost and always returns a slice.
195 /// On non-Unix systems, this does a UTF-8 check. If the given OS string
196 /// slice is not valid UTF-8, then it is lossily decoded into valid UTF-8
197 /// (with invalid bytes replaced by the Unicode replacement codepoint).
198 ///
199 /// # Examples
200 ///
201 /// Basic usage:
202 ///
203 /// ```
204 /// use std::ffi::OsStr;
205 ///
206 /// use bstr::{B, ByteVec};
207 ///
208 /// let os_str = OsStr::new("foo");
209 /// let bs = Vec::from_os_str_lossy(os_str);
210 /// assert_eq!(bs, B("foo"));
211 /// ```
212 #[inline]
from_os_str_lossy<'a>(os_str: &'a OsStr) -> Cow<'a, [u8]>213 fn from_os_str_lossy<'a>(os_str: &'a OsStr) -> Cow<'a, [u8]> {
214 #[cfg(unix)]
215 #[inline]
216 fn imp<'a>(os_str: &'a OsStr) -> Cow<'a, [u8]> {
217 use std::os::unix::ffi::OsStrExt;
218
219 Cow::Borrowed(os_str.as_bytes())
220 }
221
222 #[cfg(not(unix))]
223 #[inline]
224 fn imp<'a>(os_str: &'a OsStr) -> Cow<'a, [u8]> {
225 match os_str.to_string_lossy() {
226 Cow::Borrowed(x) => Cow::Borrowed(x.as_bytes()),
227 Cow::Owned(x) => Cow::Owned(Vec::from(x)),
228 }
229 }
230
231 imp(os_str)
232 }
233
234 /// Create a new byte string from an owned file path.
235 ///
236 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
237 /// this returns the original path if it is not valid UTF-8.
238 ///
239 /// # Examples
240 ///
241 /// Basic usage:
242 ///
243 /// ```
244 /// use std::path::PathBuf;
245 ///
246 /// use bstr::{B, ByteVec};
247 ///
248 /// let path = PathBuf::from("foo");
249 /// let bs = Vec::from_path_buf(path).expect("must be valid UTF-8");
250 /// assert_eq!(bs, B("foo"));
251 /// ```
252 #[inline]
from_path_buf(path: PathBuf) -> Result<Vec<u8>, PathBuf>253 fn from_path_buf(path: PathBuf) -> Result<Vec<u8>, PathBuf> {
254 Vec::from_os_string(path.into_os_string()).map_err(PathBuf::from)
255 }
256
257 /// Lossily create a new byte string from a file path.
258 ///
259 /// On Unix, this always succeeds, is zero cost and always returns a slice.
260 /// On non-Unix systems, this does a UTF-8 check. If the given path is not
261 /// valid UTF-8, then it is lossily decoded into valid UTF-8 (with invalid
262 /// bytes replaced by the Unicode replacement codepoint).
263 ///
264 /// # Examples
265 ///
266 /// Basic usage:
267 ///
268 /// ```
269 /// use std::path::Path;
270 ///
271 /// use bstr::{B, ByteVec};
272 ///
273 /// let path = Path::new("foo");
274 /// let bs = Vec::from_path_lossy(path);
275 /// assert_eq!(bs, B("foo"));
276 /// ```
277 #[inline]
from_path_lossy<'a>(path: &'a Path) -> Cow<'a, [u8]>278 fn from_path_lossy<'a>(path: &'a Path) -> Cow<'a, [u8]> {
279 Vec::from_os_str_lossy(path.as_os_str())
280 }
281
282 /// Appends the given byte to the end of this byte string.
283 ///
284 /// Note that this is equivalent to the generic `Vec::push` method. This
285 /// method is provided to permit callers to explicitly differentiate
286 /// between pushing bytes, codepoints and strings.
287 ///
288 /// # Examples
289 ///
290 /// Basic usage:
291 ///
292 /// ```
293 /// use bstr::ByteVec;
294 ///
295 /// let mut s = <Vec<u8>>::from("abc");
296 /// s.push_byte(b'\xE2');
297 /// s.push_byte(b'\x98');
298 /// s.push_byte(b'\x83');
299 /// assert_eq!(s, "abc☃".as_bytes());
300 /// ```
301 #[inline]
push_byte(&mut self, byte: u8)302 fn push_byte(&mut self, byte: u8) {
303 self.as_vec_mut().push(byte);
304 }
305
306 /// Appends the given `char` to the end of this byte string.
307 ///
308 /// # Examples
309 ///
310 /// Basic usage:
311 ///
312 /// ```
313 /// use bstr::ByteVec;
314 ///
315 /// let mut s = <Vec<u8>>::from("abc");
316 /// s.push_char('1');
317 /// s.push_char('2');
318 /// s.push_char('3');
319 /// assert_eq!(s, "abc123".as_bytes());
320 /// ```
321 #[inline]
push_char(&mut self, ch: char)322 fn push_char(&mut self, ch: char) {
323 if ch.len_utf8() == 1 {
324 self.push_byte(ch as u8);
325 return;
326 }
327 self.as_vec_mut()
328 .extend_from_slice(ch.encode_utf8(&mut [0; 4]).as_bytes());
329 }
330
331 /// Appends the given slice to the end of this byte string. This accepts
332 /// any type that be converted to a `&[u8]`. This includes, but is not
333 /// limited to, `&str`, `&BStr`, and of course, `&[u8]` itself.
334 ///
335 /// # Examples
336 ///
337 /// Basic usage:
338 ///
339 /// ```
340 /// use bstr::ByteVec;
341 ///
342 /// let mut s = <Vec<u8>>::from("abc");
343 /// s.push_str(b"123");
344 /// assert_eq!(s, "abc123".as_bytes());
345 /// ```
346 #[inline]
push_str<B: AsRef<[u8]>>(&mut self, bytes: B)347 fn push_str<B: AsRef<[u8]>>(&mut self, bytes: B) {
348 self.as_vec_mut().extend_from_slice(bytes.as_ref());
349 }
350
351 /// Converts a `Vec<u8>` into a `String` if and only if this byte string is
352 /// valid UTF-8.
353 ///
354 /// If it is not valid UTF-8, then a
355 /// [`FromUtf8Error`](struct.FromUtf8Error.html)
356 /// is returned. (This error can be used to examine why UTF-8 validation
357 /// failed, or to regain the original byte string.)
358 ///
359 /// # Examples
360 ///
361 /// Basic usage:
362 ///
363 /// ```
364 /// use bstr::ByteVec;
365 ///
366 /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
367 /// let bytes = Vec::from("hello");
368 /// let string = bytes.into_string()?;
369 ///
370 /// assert_eq!("hello", string);
371 /// # Ok(()) }; example().unwrap()
372 /// ```
373 ///
374 /// If this byte string is not valid UTF-8, then an error will be returned.
375 /// That error can then be used to inspect the location at which invalid
376 /// UTF-8 was found, or to regain the original byte string:
377 ///
378 /// ```
379 /// use bstr::{B, ByteVec};
380 ///
381 /// let bytes = Vec::from_slice(b"foo\xFFbar");
382 /// let err = bytes.into_string().unwrap_err();
383 ///
384 /// assert_eq!(err.utf8_error().valid_up_to(), 3);
385 /// assert_eq!(err.utf8_error().error_len(), Some(1));
386 ///
387 /// // At no point in this example is an allocation performed.
388 /// let bytes = Vec::from(err.into_vec());
389 /// assert_eq!(bytes, B(b"foo\xFFbar"));
390 /// ```
391 #[inline]
into_string(self) -> Result<String, FromUtf8Error> where Self: Sized,392 fn into_string(self) -> Result<String, FromUtf8Error>
393 where
394 Self: Sized,
395 {
396 match utf8::validate(self.as_vec()) {
397 Err(err) => Err(FromUtf8Error { original: self.into_vec(), err }),
398 Ok(()) => {
399 // SAFETY: This is safe because of the guarantees provided by
400 // utf8::validate.
401 unsafe { Ok(self.into_string_unchecked()) }
402 }
403 }
404 }
405
406 /// Lossily converts a `Vec<u8>` into a `String`. If this byte string
407 /// contains invalid UTF-8, then the invalid bytes are replaced with the
408 /// Unicode replacement codepoint.
409 ///
410 /// # Examples
411 ///
412 /// Basic usage:
413 ///
414 /// ```
415 /// use bstr::ByteVec;
416 ///
417 /// let bytes = Vec::from_slice(b"foo\xFFbar");
418 /// let string = bytes.into_string_lossy();
419 /// assert_eq!(string, "foo\u{FFFD}bar");
420 /// ```
421 #[inline]
into_string_lossy(self) -> String where Self: Sized,422 fn into_string_lossy(self) -> String
423 where
424 Self: Sized,
425 {
426 match self.as_vec().to_str_lossy() {
427 Cow::Borrowed(_) => {
428 // SAFETY: to_str_lossy() returning a Cow::Borrowed guarantees
429 // the entire string is valid utf8.
430 unsafe { self.into_string_unchecked() }
431 }
432 Cow::Owned(s) => s,
433 }
434 }
435
436 /// Unsafely convert this byte string into a `String`, without checking for
437 /// valid UTF-8.
438 ///
439 /// # Safety
440 ///
441 /// Callers *must* ensure that this byte string is valid UTF-8 before
442 /// calling this method. Converting a byte string into a `String` that is
443 /// not valid UTF-8 is considered undefined behavior.
444 ///
445 /// This routine is useful in performance sensitive contexts where the
446 /// UTF-8 validity of the byte string is already known and it is
447 /// undesirable to pay the cost of an additional UTF-8 validation check
448 /// that [`into_string`](#method.into_string) performs.
449 ///
450 /// # Examples
451 ///
452 /// Basic usage:
453 ///
454 /// ```
455 /// use bstr::ByteVec;
456 ///
457 /// // SAFETY: This is safe because string literals are guaranteed to be
458 /// // valid UTF-8 by the Rust compiler.
459 /// let s = unsafe { Vec::from("☃βツ").into_string_unchecked() };
460 /// assert_eq!("☃βツ", s);
461 /// ```
462 #[inline]
into_string_unchecked(self) -> String where Self: Sized,463 unsafe fn into_string_unchecked(self) -> String
464 where
465 Self: Sized,
466 {
467 String::from_utf8_unchecked(self.into_vec())
468 }
469
470 /// Converts this byte string into an OS string, in place.
471 ///
472 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
473 /// this returns the original byte string if it is not valid UTF-8.
474 ///
475 /// # Examples
476 ///
477 /// Basic usage:
478 ///
479 /// ```
480 /// use std::ffi::OsStr;
481 ///
482 /// use bstr::ByteVec;
483 ///
484 /// let bs = Vec::from("foo");
485 /// let os_str = bs.into_os_string().expect("should be valid UTF-8");
486 /// assert_eq!(os_str, OsStr::new("foo"));
487 /// ```
488 #[inline]
into_os_string(self) -> Result<OsString, Vec<u8>> where Self: Sized,489 fn into_os_string(self) -> Result<OsString, Vec<u8>>
490 where
491 Self: Sized,
492 {
493 #[cfg(unix)]
494 #[inline]
495 fn imp(v: Vec<u8>) -> Result<OsString, Vec<u8>> {
496 use std::os::unix::ffi::OsStringExt;
497
498 Ok(OsString::from_vec(v))
499 }
500
501 #[cfg(not(unix))]
502 #[inline]
503 fn imp(v: Vec<u8>) -> Result<OsString, Vec<u8>> {
504 match v.into_string() {
505 Ok(s) => Ok(OsString::from(s)),
506 Err(err) => Err(err.into_vec()),
507 }
508 }
509
510 imp(self.into_vec())
511 }
512
513 /// Lossily converts this byte string into an OS string, in place.
514 ///
515 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
516 /// this will perform a UTF-8 check and lossily convert this byte string
517 /// into valid UTF-8 using the Unicode replacement codepoint.
518 ///
519 /// Note that this can prevent the correct roundtripping of file paths on
520 /// non-Unix systems such as Windows, where file paths are an arbitrary
521 /// sequence of 16-bit integers.
522 ///
523 /// # Examples
524 ///
525 /// Basic usage:
526 ///
527 /// ```
528 /// use bstr::ByteVec;
529 ///
530 /// let bs = Vec::from_slice(b"foo\xFFbar");
531 /// let os_str = bs.into_os_string_lossy();
532 /// assert_eq!(os_str.to_string_lossy(), "foo\u{FFFD}bar");
533 /// ```
534 #[inline]
into_os_string_lossy(self) -> OsString where Self: Sized,535 fn into_os_string_lossy(self) -> OsString
536 where
537 Self: Sized,
538 {
539 #[cfg(unix)]
540 #[inline]
541 fn imp(v: Vec<u8>) -> OsString {
542 use std::os::unix::ffi::OsStringExt;
543
544 OsString::from_vec(v)
545 }
546
547 #[cfg(not(unix))]
548 #[inline]
549 fn imp(v: Vec<u8>) -> OsString {
550 OsString::from(v.into_string_lossy())
551 }
552
553 imp(self.into_vec())
554 }
555
556 /// Converts this byte string into an owned file path, in place.
557 ///
558 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
559 /// this returns the original byte string if it is not valid UTF-8.
560 ///
561 /// # Examples
562 ///
563 /// Basic usage:
564 ///
565 /// ```
566 /// use bstr::ByteVec;
567 ///
568 /// let bs = Vec::from("foo");
569 /// let path = bs.into_path_buf().expect("should be valid UTF-8");
570 /// assert_eq!(path.as_os_str(), "foo");
571 /// ```
572 #[inline]
into_path_buf(self) -> Result<PathBuf, Vec<u8>> where Self: Sized,573 fn into_path_buf(self) -> Result<PathBuf, Vec<u8>>
574 where
575 Self: Sized,
576 {
577 self.into_os_string().map(PathBuf::from)
578 }
579
580 /// Lossily converts this byte string into an owned file path, in place.
581 ///
582 /// On Unix, this always succeeds and is zero cost. On non-Unix systems,
583 /// this will perform a UTF-8 check and lossily convert this byte string
584 /// into valid UTF-8 using the Unicode replacement codepoint.
585 ///
586 /// Note that this can prevent the correct roundtripping of file paths on
587 /// non-Unix systems such as Windows, where file paths are an arbitrary
588 /// sequence of 16-bit integers.
589 ///
590 /// # Examples
591 ///
592 /// Basic usage:
593 ///
594 /// ```
595 /// use bstr::ByteVec;
596 ///
597 /// let bs = Vec::from_slice(b"foo\xFFbar");
598 /// let path = bs.into_path_buf_lossy();
599 /// assert_eq!(path.to_string_lossy(), "foo\u{FFFD}bar");
600 /// ```
601 #[inline]
into_path_buf_lossy(self) -> PathBuf where Self: Sized,602 fn into_path_buf_lossy(self) -> PathBuf
603 where
604 Self: Sized,
605 {
606 PathBuf::from(self.into_os_string_lossy())
607 }
608
609 /// Removes the last byte from this `Vec<u8>` and returns it.
610 ///
611 /// If this byte string is empty, then `None` is returned.
612 ///
613 /// If the last codepoint in this byte string is not ASCII, then removing
614 /// the last byte could make this byte string contain invalid UTF-8.
615 ///
616 /// Note that this is equivalent to the generic `Vec::pop` method. This
617 /// method is provided to permit callers to explicitly differentiate
618 /// between popping bytes and codepoints.
619 ///
620 /// # Examples
621 ///
622 /// Basic usage:
623 ///
624 /// ```
625 /// use bstr::ByteVec;
626 ///
627 /// let mut s = Vec::from("foo");
628 /// assert_eq!(s.pop_byte(), Some(b'o'));
629 /// assert_eq!(s.pop_byte(), Some(b'o'));
630 /// assert_eq!(s.pop_byte(), Some(b'f'));
631 /// assert_eq!(s.pop_byte(), None);
632 /// ```
633 #[inline]
pop_byte(&mut self) -> Option<u8>634 fn pop_byte(&mut self) -> Option<u8> {
635 self.as_vec_mut().pop()
636 }
637
638 /// Removes the last codepoint from this `Vec<u8>` and returns it.
639 ///
640 /// If this byte string is empty, then `None` is returned. If the last
641 /// bytes of this byte string do not correspond to a valid UTF-8 code unit
642 /// sequence, then the Unicode replacement codepoint is yielded instead in
643 /// accordance with the
644 /// [replacement codepoint substitution policy](index.html#handling-of-invalid-utf8-8).
645 ///
646 /// # Examples
647 ///
648 /// Basic usage:
649 ///
650 /// ```
651 /// use bstr::ByteVec;
652 ///
653 /// let mut s = Vec::from("foo");
654 /// assert_eq!(s.pop_char(), Some('o'));
655 /// assert_eq!(s.pop_char(), Some('o'));
656 /// assert_eq!(s.pop_char(), Some('f'));
657 /// assert_eq!(s.pop_char(), None);
658 /// ```
659 ///
660 /// This shows the replacement codepoint substitution policy. Note that
661 /// the first pop yields a replacement codepoint but actually removes two
662 /// bytes. This is in contrast with subsequent pops when encountering
663 /// `\xFF` since `\xFF` is never a valid prefix for any valid UTF-8
664 /// code unit sequence.
665 ///
666 /// ```
667 /// use bstr::ByteVec;
668 ///
669 /// let mut s = Vec::from_slice(b"f\xFF\xFF\xFFoo\xE2\x98");
670 /// assert_eq!(s.pop_char(), Some('\u{FFFD}'));
671 /// assert_eq!(s.pop_char(), Some('o'));
672 /// assert_eq!(s.pop_char(), Some('o'));
673 /// assert_eq!(s.pop_char(), Some('\u{FFFD}'));
674 /// assert_eq!(s.pop_char(), Some('\u{FFFD}'));
675 /// assert_eq!(s.pop_char(), Some('\u{FFFD}'));
676 /// assert_eq!(s.pop_char(), Some('f'));
677 /// assert_eq!(s.pop_char(), None);
678 /// ```
679 #[inline]
pop_char(&mut self) -> Option<char>680 fn pop_char(&mut self) -> Option<char> {
681 let (ch, size) = utf8::decode_last_lossy(self.as_vec());
682 if size == 0 {
683 return None;
684 }
685 let new_len = self.as_vec().len() - size;
686 self.as_vec_mut().truncate(new_len);
687 Some(ch)
688 }
689
690 /// Removes a `char` from this `Vec<u8>` at the given byte position and
691 /// returns it.
692 ///
693 /// If the bytes at the given position do not lead to a valid UTF-8 code
694 /// unit sequence, then a
695 /// [replacement codepoint is returned instead](index.html#handling-of-invalid-utf8-8).
696 ///
697 /// # Panics
698 ///
699 /// Panics if `at` is larger than or equal to this byte string's length.
700 ///
701 /// # Examples
702 ///
703 /// Basic usage:
704 ///
705 /// ```
706 /// use bstr::ByteVec;
707 ///
708 /// let mut s = Vec::from("foo☃bar");
709 /// assert_eq!(s.remove_char(3), '☃');
710 /// assert_eq!(s, b"foobar");
711 /// ```
712 ///
713 /// This example shows how the Unicode replacement codepoint policy is
714 /// used:
715 ///
716 /// ```
717 /// use bstr::ByteVec;
718 ///
719 /// let mut s = Vec::from_slice(b"foo\xFFbar");
720 /// assert_eq!(s.remove_char(3), '\u{FFFD}');
721 /// assert_eq!(s, b"foobar");
722 /// ```
723 #[inline]
remove_char(&mut self, at: usize) -> char724 fn remove_char(&mut self, at: usize) -> char {
725 let (ch, size) = utf8::decode_lossy(&self.as_vec()[at..]);
726 assert!(
727 size > 0,
728 "expected {} to be less than {}",
729 at,
730 self.as_vec().len(),
731 );
732 self.as_vec_mut().drain(at..at + size);
733 ch
734 }
735
736 /// Inserts the given codepoint into this `Vec<u8>` at a particular byte
737 /// position.
738 ///
739 /// This is an `O(n)` operation as it may copy a number of elements in this
740 /// byte string proportional to its length.
741 ///
742 /// # Panics
743 ///
744 /// Panics if `at` is larger than the byte string's length.
745 ///
746 /// # Examples
747 ///
748 /// Basic usage:
749 ///
750 /// ```
751 /// use bstr::ByteVec;
752 ///
753 /// let mut s = Vec::from("foobar");
754 /// s.insert_char(3, '☃');
755 /// assert_eq!(s, "foo☃bar".as_bytes());
756 /// ```
757 #[inline]
insert_char(&mut self, at: usize, ch: char)758 fn insert_char(&mut self, at: usize, ch: char) {
759 self.insert_str(at, ch.encode_utf8(&mut [0; 4]).as_bytes());
760 }
761
762 /// Inserts the given byte string into this byte string at a particular
763 /// byte position.
764 ///
765 /// This is an `O(n)` operation as it may copy a number of elements in this
766 /// byte string proportional to its length.
767 ///
768 /// The given byte string may be any type that can be cheaply converted
769 /// into a `&[u8]`. This includes, but is not limited to, `&str` and
770 /// `&[u8]`.
771 ///
772 /// # Panics
773 ///
774 /// Panics if `at` is larger than the byte string's length.
775 ///
776 /// # Examples
777 ///
778 /// Basic usage:
779 ///
780 /// ```
781 /// use bstr::ByteVec;
782 ///
783 /// let mut s = Vec::from("foobar");
784 /// s.insert_str(3, "☃☃☃");
785 /// assert_eq!(s, "foo☃☃☃bar".as_bytes());
786 /// ```
787 #[inline]
insert_str<B: AsRef<[u8]>>(&mut self, at: usize, bytes: B)788 fn insert_str<B: AsRef<[u8]>>(&mut self, at: usize, bytes: B) {
789 let bytes = bytes.as_ref();
790 let len = self.as_vec().len();
791 assert!(at <= len, "expected {} to be <= {}", at, len);
792
793 // SAFETY: We'd like to efficiently splice in the given bytes into
794 // this byte string. Since we are only working with `u8` elements here,
795 // we only need to consider whether our bounds are correct and whether
796 // our byte string has enough space.
797 self.as_vec_mut().reserve(bytes.len());
798 unsafe {
799 // Shift bytes after `at` over by the length of `bytes` to make
800 // room for it. This requires referencing two regions of memory
801 // that may overlap, so we use ptr::copy.
802 ptr::copy(
803 self.as_vec().as_ptr().add(at),
804 self.as_vec_mut().as_mut_ptr().add(at + bytes.len()),
805 len - at,
806 );
807 // Now copy the bytes given into the room we made above. In this
808 // case, we know that the given bytes cannot possibly overlap
809 // with this byte string since we have a mutable borrow of the
810 // latter. Thus, we can use a nonoverlapping copy.
811 ptr::copy_nonoverlapping(
812 bytes.as_ptr(),
813 self.as_vec_mut().as_mut_ptr().add(at),
814 bytes.len(),
815 );
816 self.as_vec_mut().set_len(len + bytes.len());
817 }
818 }
819
820 /// Removes the specified range in this byte string and replaces it with
821 /// the given bytes. The given bytes do not need to have the same length
822 /// as the range provided.
823 ///
824 /// # Panics
825 ///
826 /// Panics if the given range is invalid.
827 ///
828 /// # Examples
829 ///
830 /// Basic usage:
831 ///
832 /// ```
833 /// use bstr::ByteVec;
834 ///
835 /// let mut s = Vec::from("foobar");
836 /// s.replace_range(2..4, "xxxxx");
837 /// assert_eq!(s, "foxxxxxar".as_bytes());
838 /// ```
839 #[inline]
replace_range<R, B>(&mut self, range: R, replace_with: B) where R: ops::RangeBounds<usize>, B: AsRef<[u8]>,840 fn replace_range<R, B>(&mut self, range: R, replace_with: B)
841 where
842 R: ops::RangeBounds<usize>,
843 B: AsRef<[u8]>,
844 {
845 self.as_vec_mut().splice(range, replace_with.as_ref().iter().cloned());
846 }
847
848 /// Creates a draining iterator that removes the specified range in this
849 /// `Vec<u8>` and yields each of the removed bytes.
850 ///
851 /// Note that the elements specified by the given range are removed
852 /// regardless of whether the returned iterator is fully exhausted.
853 ///
854 /// Also note that is is unspecified how many bytes are removed from the
855 /// `Vec<u8>` if the `DrainBytes` iterator is leaked.
856 ///
857 /// # Panics
858 ///
859 /// Panics if the given range is not valid.
860 ///
861 /// # Examples
862 ///
863 /// Basic usage:
864 ///
865 /// ```
866 /// use bstr::ByteVec;
867 ///
868 /// let mut s = Vec::from("foobar");
869 /// {
870 /// let mut drainer = s.drain_bytes(2..4);
871 /// assert_eq!(drainer.next(), Some(b'o'));
872 /// assert_eq!(drainer.next(), Some(b'b'));
873 /// assert_eq!(drainer.next(), None);
874 /// }
875 /// assert_eq!(s, "foar".as_bytes());
876 /// ```
877 #[inline]
drain_bytes<R>(&mut self, range: R) -> DrainBytes<'_> where R: ops::RangeBounds<usize>,878 fn drain_bytes<R>(&mut self, range: R) -> DrainBytes<'_>
879 where
880 R: ops::RangeBounds<usize>,
881 {
882 DrainBytes { it: self.as_vec_mut().drain(range) }
883 }
884 }
885
886 /// A draining byte oriented iterator for `Vec<u8>`.
887 ///
888 /// This iterator is created by
889 /// [`ByteVec::drain_bytes`](trait.ByteVec.html#method.drain_bytes).
890 ///
891 /// # Examples
892 ///
893 /// Basic usage:
894 ///
895 /// ```
896 /// use bstr::ByteVec;
897 ///
898 /// let mut s = Vec::from("foobar");
899 /// {
900 /// let mut drainer = s.drain_bytes(2..4);
901 /// assert_eq!(drainer.next(), Some(b'o'));
902 /// assert_eq!(drainer.next(), Some(b'b'));
903 /// assert_eq!(drainer.next(), None);
904 /// }
905 /// assert_eq!(s, "foar".as_bytes());
906 /// ```
907 #[derive(Debug)]
908 pub struct DrainBytes<'a> {
909 it: vec::Drain<'a, u8>,
910 }
911
912 impl<'a> iter::FusedIterator for DrainBytes<'a> {}
913
914 impl<'a> Iterator for DrainBytes<'a> {
915 type Item = u8;
916
917 #[inline]
next(&mut self) -> Option<u8>918 fn next(&mut self) -> Option<u8> {
919 self.it.next()
920 }
921 }
922
923 impl<'a> DoubleEndedIterator for DrainBytes<'a> {
924 #[inline]
next_back(&mut self) -> Option<u8>925 fn next_back(&mut self) -> Option<u8> {
926 self.it.next_back()
927 }
928 }
929
930 impl<'a> ExactSizeIterator for DrainBytes<'a> {
931 #[inline]
len(&self) -> usize932 fn len(&self) -> usize {
933 self.it.len()
934 }
935 }
936
937 /// An error that may occur when converting a `Vec<u8>` to a `String`.
938 ///
939 /// This error includes the original `Vec<u8>` that failed to convert to a
940 /// `String`. This permits callers to recover the allocation used even if it
941 /// it not valid UTF-8.
942 ///
943 /// # Examples
944 ///
945 /// Basic usage:
946 ///
947 /// ```
948 /// use bstr::{B, ByteVec};
949 ///
950 /// let bytes = Vec::from_slice(b"foo\xFFbar");
951 /// let err = bytes.into_string().unwrap_err();
952 ///
953 /// assert_eq!(err.utf8_error().valid_up_to(), 3);
954 /// assert_eq!(err.utf8_error().error_len(), Some(1));
955 ///
956 /// // At no point in this example is an allocation performed.
957 /// let bytes = Vec::from(err.into_vec());
958 /// assert_eq!(bytes, B(b"foo\xFFbar"));
959 /// ```
960 #[derive(Debug, Eq, PartialEq)]
961 pub struct FromUtf8Error {
962 original: Vec<u8>,
963 err: Utf8Error,
964 }
965
966 impl FromUtf8Error {
967 /// Return the original bytes as a slice that failed to convert to a
968 /// `String`.
969 ///
970 /// # Examples
971 ///
972 /// Basic usage:
973 ///
974 /// ```
975 /// use bstr::{B, ByteVec};
976 ///
977 /// let bytes = Vec::from_slice(b"foo\xFFbar");
978 /// let err = bytes.into_string().unwrap_err();
979 ///
980 /// // At no point in this example is an allocation performed.
981 /// assert_eq!(err.as_bytes(), B(b"foo\xFFbar"));
982 /// ```
983 #[inline]
as_bytes(&self) -> &[u8]984 pub fn as_bytes(&self) -> &[u8] {
985 &self.original
986 }
987
988 /// Consume this error and return the original byte string that failed to
989 /// convert to a `String`.
990 ///
991 /// # Examples
992 ///
993 /// Basic usage:
994 ///
995 /// ```
996 /// use bstr::{B, ByteVec};
997 ///
998 /// let bytes = Vec::from_slice(b"foo\xFFbar");
999 /// let err = bytes.into_string().unwrap_err();
1000 /// let original = err.into_vec();
1001 ///
1002 /// // At no point in this example is an allocation performed.
1003 /// assert_eq!(original, B(b"foo\xFFbar"));
1004 /// ```
1005 #[inline]
into_vec(self) -> Vec<u8>1006 pub fn into_vec(self) -> Vec<u8> {
1007 self.original
1008 }
1009
1010 /// Return the underlying UTF-8 error that occurred. This error provides
1011 /// information on the nature and location of the invalid UTF-8 detected.
1012 ///
1013 /// # Examples
1014 ///
1015 /// Basic usage:
1016 ///
1017 /// ```
1018 /// use bstr::{B, ByteVec};
1019 ///
1020 /// let bytes = Vec::from_slice(b"foo\xFFbar");
1021 /// let err = bytes.into_string().unwrap_err();
1022 ///
1023 /// assert_eq!(err.utf8_error().valid_up_to(), 3);
1024 /// assert_eq!(err.utf8_error().error_len(), Some(1));
1025 /// ```
1026 #[inline]
utf8_error(&self) -> &Utf8Error1027 pub fn utf8_error(&self) -> &Utf8Error {
1028 &self.err
1029 }
1030 }
1031
1032 impl error::Error for FromUtf8Error {
1033 #[inline]
description(&self) -> &str1034 fn description(&self) -> &str {
1035 "invalid UTF-8 vector"
1036 }
1037 }
1038
1039 impl fmt::Display for FromUtf8Error {
1040 #[inline]
fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result1041 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1042 write!(f, "{}", self.err)
1043 }
1044 }
1045
1046 #[cfg(test)]
1047 mod tests {
1048 use crate::ext_vec::ByteVec;
1049
1050 #[test]
insert()1051 fn insert() {
1052 let mut s = vec![];
1053 s.insert_str(0, "foo");
1054 assert_eq!(s, "foo".as_bytes());
1055
1056 let mut s = Vec::from("a");
1057 s.insert_str(0, "foo");
1058 assert_eq!(s, "fooa".as_bytes());
1059
1060 let mut s = Vec::from("a");
1061 s.insert_str(1, "foo");
1062 assert_eq!(s, "afoo".as_bytes());
1063
1064 let mut s = Vec::from("foobar");
1065 s.insert_str(3, "quux");
1066 assert_eq!(s, "fooquuxbar".as_bytes());
1067
1068 let mut s = Vec::from("foobar");
1069 s.insert_str(3, "x");
1070 assert_eq!(s, "fooxbar".as_bytes());
1071
1072 let mut s = Vec::from("foobar");
1073 s.insert_str(0, "x");
1074 assert_eq!(s, "xfoobar".as_bytes());
1075
1076 let mut s = Vec::from("foobar");
1077 s.insert_str(6, "x");
1078 assert_eq!(s, "foobarx".as_bytes());
1079
1080 let mut s = Vec::from("foobar");
1081 s.insert_str(3, "quuxbazquux");
1082 assert_eq!(s, "fooquuxbazquuxbar".as_bytes());
1083 }
1084
1085 #[test]
1086 #[should_panic]
insert_fail1()1087 fn insert_fail1() {
1088 let mut s = vec![];
1089 s.insert_str(1, "foo");
1090 }
1091
1092 #[test]
1093 #[should_panic]
insert_fail2()1094 fn insert_fail2() {
1095 let mut s = Vec::from("a");
1096 s.insert_str(2, "foo");
1097 }
1098
1099 #[test]
1100 #[should_panic]
insert_fail3()1101 fn insert_fail3() {
1102 let mut s = Vec::from("foobar");
1103 s.insert_str(7, "foo");
1104 }
1105 }
1106