rune/runtime/
bytes.rs

Help
1//! A container of bytes, corresponding to the [Value::Bytes] type.
2//!
3//! [Value::Bytes]: crate::Value::Bytes.
4
5use core::fmt;
6use core::ops;
7
8use serde::de;
9use serde::ser;
10
11use crate as rune;
12use crate::alloc::prelude::*;
13use crate::alloc::{self, Box, Vec};
14use crate::runtime::VmResult;
15use crate::TypeHash as _;
16use crate::{Any, FromValue};
17
18use super::{
19    IntoOutput, Range, RangeFrom, RangeFull, RangeInclusive, RangeTo, RangeToInclusive,
20    RawAnyGuard, Ref, RuntimeError, UnsafeToRef, Value, VmErrorKind,
21};
22
23/// A vector of bytes.
24#[derive(Any, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
25#[rune(item = ::std::bytes)]
26pub struct Bytes {
27    bytes: Vec<u8>,
28}
29
30impl Bytes {
31    /// Construct a new byte array.
32    ///
33    /// # Examples
34    ///
35    /// ```
36    /// use rune::runtime::Bytes;
37    ///
38    /// let bytes = Bytes::new();
39    /// assert_eq!(bytes, b"");
40    /// ```
41    #[inline]
42    pub const fn new() -> Self {
43        Bytes { bytes: Vec::new() }
44    }
45
46    /// Construct a byte array with the given preallocated capacity.
47    ///
48    /// # Examples
49    ///
50    /// ```
51    /// use rune::runtime::Bytes;
52    ///
53    /// let mut bytes = Bytes::with_capacity(32)?;
54    /// assert_eq!(bytes, b"");
55    /// bytes.extend(b"abcd")?;
56    /// assert_eq!(bytes, b"abcd");
57    /// # Ok::<_, rune::support::Error>(())
58    /// ```
59    #[inline]
60    pub fn with_capacity(cap: usize) -> alloc::Result<Self> {
61        Ok(Self {
62            bytes: Vec::try_with_capacity(cap)?,
63        })
64    }
65
66    /// Convert the byte array into a vector of bytes.
67    ///
68    /// # Examples
69    ///
70    /// ```
71    /// use rune::runtime::Bytes;
72    /// use rune::alloc::prelude::*;
73    /// use rune::alloc::try_vec;
74    ///
75    /// let bytes = Bytes::from_vec(try_vec![b'a', b'b', b'c', b'd']);
76    /// assert_eq!(bytes.into_vec(), [b'a', b'b', b'c', b'd']);
77    ///
78    /// Ok::<_, rune::support::Error>(())
79    /// ```
80    #[inline]
81    pub fn into_vec(self) -> Vec<u8> {
82        self.bytes
83    }
84
85    /// Access bytes as a slice.
86    ///
87    /// # Examples
88    ///
89    /// ```
90    /// use rune::runtime::Bytes;
91    /// use rune::alloc::try_vec;
92    ///
93    /// let bytes = Bytes::from_vec(try_vec![b'a', b'b', b'c', b'd']);
94    /// assert_eq!(bytes.as_slice(), &[b'a', b'b', b'c', b'd']);
95    ///
96    /// Ok::<_, rune::support::Error>(())
97    /// ```
98    #[inline]
99    pub fn as_slice(&self) -> &[u8] {
100        &self.bytes
101    }
102
103    /// Convert a slice into bytes.
104    ///
105    /// Calling this function allocates bytes internally.
106    ///
107    /// # Examples
108    ///
109    /// ```
110    /// use rune::runtime::Bytes;
111    ///
112    /// let bytes = Bytes::from_slice(vec![b'a', b'b', b'c', b'd'])?;
113    /// assert_eq!(bytes, b"abcd");
114    ///
115    /// # Ok::<_, rune::support::Error>(())
116    /// ```
117    #[inline]
118    pub fn from_slice<B>(bytes: B) -> alloc::Result<Self>
119    where
120        B: AsRef<[u8]>,
121    {
122        Ok(Self {
123            bytes: Vec::try_from(bytes.as_ref())?,
124        })
125    }
126
127    /// Convert a byte array into bytes.
128    ///
129    /// # Examples
130    ///
131    /// ```
132    /// use rune::runtime::Bytes;
133    /// use rune::alloc::try_vec;
134    ///
135    /// let bytes = Bytes::from_vec(try_vec![b'a', b'b', b'c', b'd']);
136    /// assert_eq!(bytes, b"abcd");
137    /// # Ok::<_, rune::support::Error>(())
138    /// ```
139    #[inline]
140    pub fn from_vec(bytes: Vec<u8>) -> Self {
141        Self { bytes }
142    }
143
144    /// Extend these bytes with another collection of bytes.
145    ///
146    /// # Examples
147    ///
148    /// ```
149    /// use rune::runtime::Bytes;
150    /// use rune::alloc::try_vec;
151    ///
152    /// let mut bytes = Bytes::from_vec(try_vec![b'a', b'b', b'c', b'd']);
153    /// bytes.extend(b"efgh");
154    /// assert_eq!(bytes, b"abcdefgh");
155    ///
156    /// Ok::<_, rune::support::Error>(())
157    /// ```
158    pub fn extend<O>(&mut self, other: O) -> alloc::Result<()>
159    where
160        O: AsRef<[u8]>,
161    {
162        self.bytes.try_extend_from_slice(other.as_ref())
163    }
164
165    /// Test if the collection is empty.
166    ///
167    /// # Examples
168    ///
169    /// ```
170    /// use rune::runtime::Bytes;
171    ///
172    /// let mut bytes = Bytes::new();
173    /// assert!(bytes.is_empty());
174    /// ```
175    pub fn is_empty(&self) -> bool {
176        self.bytes.is_empty()
177    }
178
179    /// Get the length of the bytes collection.
180    ///
181    /// # Examples
182    ///
183    /// ```
184    /// use rune::runtime::Bytes;
185    ///
186    /// let mut bytes = Bytes::new();
187    /// assert_eq!(bytes.len(), 0);
188    /// bytes.extend(b"abcd");
189    /// assert_eq!(bytes.len(), 4);
190    /// ```
191    pub fn len(&self) -> usize {
192        self.bytes.len()
193    }
194
195    /// Get the capacity of the bytes collection.
196    pub fn capacity(&self) -> usize {
197        self.bytes.capacity()
198    }
199
200    /// Get the bytes collection.
201    pub fn clear(&mut self) {
202        self.bytes.clear();
203    }
204
205    /// Reserve additional space.
206    ///
207    /// The exact amount is unspecified.
208    pub fn reserve(&mut self, additional: usize) -> alloc::Result<()> {
209        self.bytes.try_reserve(additional)
210    }
211
212    /// Resever additional space to the exact amount specified.
213    pub fn reserve_exact(&mut self, additional: usize) -> alloc::Result<()> {
214        self.bytes.try_reserve_exact(additional)
215    }
216
217    /// Shrink to fit the amount of bytes in the container.
218    pub fn shrink_to_fit(&mut self) -> alloc::Result<()> {
219        self.bytes.try_shrink_to_fit()
220    }
221
222    /// Pop the last byte.
223    ///
224    /// # Examples
225    ///
226    /// ```
227    /// use rune::runtime::Bytes;
228    ///
229    /// let mut bytes = Bytes::from_slice(b"abcd")?;
230    /// assert_eq!(bytes.pop(), Some(b'd'));
231    /// assert_eq!(bytes, b"abc");
232    /// Ok::<_, rune::support::Error>(())
233    /// ```
234    pub fn pop(&mut self) -> Option<u8> {
235        self.bytes.pop()
236    }
237
238    /// Append a byte to the back.
239    ///
240    /// # Examples
241    ///
242    /// ```
243    /// use rune::runtime::Bytes;
244    ///
245    /// let mut bytes = Bytes::from_slice(b"abcd")?;
246    /// bytes.push(b'e');
247    /// assert_eq!(bytes, b"abcde");
248    /// Ok::<_, rune::support::Error>(())
249    /// ```
250    pub fn push(&mut self, value: u8) -> alloc::Result<()> {
251        self.bytes.try_push(value)
252    }
253
254    /// Removes the byte at the specified index.
255    ///
256    /// # Panics
257    ///
258    /// Panics if `index` is out of bounds.
259    ///
260    /// # Examples
261    ///
262    /// ```
263    /// use rune::runtime::Bytes;
264    ///
265    /// let mut bytes = Bytes::from_slice(b"abcd")?;
266    /// bytes.remove(2);
267    /// assert_eq!(bytes, b"abd");
268    /// Ok::<_, rune::support::Error>(())
269    /// ```
270    pub fn remove(&mut self, index: usize) -> u8 {
271        self.bytes.remove(index)
272    }
273
274    /// Inserts a byte at position index within the vector, shifting all
275    /// elements after it to the right.
276    ///
277    /// # Panics
278    ///
279    /// Panics if `index` is out of bounds.
280    ///
281    /// # Examples
282    ///
283    /// ```
284    /// use rune::runtime::Bytes;
285    ///
286    /// let mut bytes = Bytes::from_slice(b"abcd")?;
287    /// bytes.insert(2, b'e');
288    /// assert_eq!(bytes, b"abecd");
289    /// Ok::<_, rune::support::Error>(())
290    /// ```
291    pub fn insert(&mut self, index: usize, value: u8) -> alloc::Result<()> {
292        self.bytes.try_insert(index, value)
293    }
294
295    /// Returns a subslice of Bytes.
296    ///
297    /// -  If given a position, returns the byte at that position or `None` if
298    ///    out of bounds.
299    /// - If given a range, returns the subslice corresponding to that range, or
300    ///   `None` if out of bounds.
301    pub(crate) fn index_get(&self, index: Value) -> VmResult<Option<Value>> {
302        bytes_slice_index_get(&self.bytes, index)
303    }
304
305    /// Set by index
306    ///
307    /// # Examples
308    ///
309    /// ```
310    /// use rune::runtime::Bytes;
311    ///
312    /// let mut bytes = Bytes::from_slice(b"abcd")?;
313    /// bytes.set(0, b'A');
314    /// assert_eq!(bytes, b"Abcd");
315    /// Ok::<_, rune::support::Error>(())
316    /// ```
317    pub fn set(&mut self, index: usize, value: u8) -> VmResult<()> {
318        let Some(v) = self.bytes.get_mut(index) else {
319            return VmResult::err(VmErrorKind::OutOfRange {
320                index: index.into(),
321                length: self.len().into(),
322            });
323        };
324
325        *v = value;
326        VmResult::Ok(())
327    }
328
329    /// Get the first byte.
330    ///
331    /// # Examples
332    ///
333    /// ```
334    /// use rune::runtime::Bytes;
335    ///
336    /// let bytes = Bytes::from_slice(b"abcd")?;
337    /// assert_eq!(bytes.first(), Some(b'a'));
338    ///
339    /// Ok::<_, rune::support::Error>(())
340    /// ```
341    pub fn first(&self) -> Option<u8> {
342        self.bytes.first().copied()
343    }
344
345    /// Get the last byte.
346    ///
347    /// # Examples
348    ///
349    /// ```
350    /// use rune::runtime::Bytes;
351    ///
352    /// let bytes = Bytes::from_slice(b"abcd")?;
353    /// assert_eq!(bytes.last(), Some(b'd'));
354    ///
355    /// Ok::<_, rune::support::Error>(())
356    /// ```
357    pub fn last(&self) -> Option<u8> {
358        self.bytes.last().copied()
359    }
360}
361
362impl TryClone for Bytes {
363    #[inline]
364    fn try_clone(&self) -> alloc::Result<Self> {
365        Ok(Self {
366            bytes: self.bytes.try_clone()?,
367        })
368    }
369}
370
371impl From<Vec<u8>> for Bytes {
372    #[inline]
373    fn from(bytes: Vec<u8>) -> Self {
374        Self { bytes }
375    }
376}
377
378#[cfg(feature = "alloc")]
379impl TryFrom<&[u8]> for Bytes {
380    type Error = alloc::Error;
381
382    #[inline]
383    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
384        let mut bytes = Vec::try_with_capacity(value.len())?;
385        bytes.try_extend_from_slice(value)?;
386        Ok(Self { bytes })
387    }
388}
389
390#[cfg(feature = "alloc")]
391impl TryFrom<::rust_alloc::vec::Vec<u8>> for Bytes {
392    type Error = alloc::Error;
393
394    #[inline]
395    fn try_from(bytes: ::rust_alloc::vec::Vec<u8>) -> Result<Self, Self::Error> {
396        Ok(Self {
397            bytes: Vec::try_from(bytes)?,
398        })
399    }
400}
401
402impl From<Box<[u8]>> for Bytes {
403    #[inline]
404    fn from(bytes: Box<[u8]>) -> Self {
405        Self {
406            bytes: Vec::from(bytes),
407        }
408    }
409}
410
411#[cfg(feature = "alloc")]
412impl TryFrom<::rust_alloc::boxed::Box<[u8]>> for Bytes {
413    type Error = alloc::Error;
414
415    #[inline]
416    fn try_from(bytes: ::rust_alloc::boxed::Box<[u8]>) -> Result<Self, Self::Error> {
417        Ok(Self {
418            bytes: Vec::try_from(bytes.as_ref())?,
419        })
420    }
421}
422
423impl fmt::Debug for Bytes {
424    #[inline]
425    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
426        fmt.debug_list().entries(&self.bytes).finish()
427    }
428}
429
430impl ops::Deref for Bytes {
431    type Target = [u8];
432
433    #[inline]
434    fn deref(&self) -> &Self::Target {
435        &self.bytes
436    }
437}
438
439impl ops::DerefMut for Bytes {
440    #[inline]
441    fn deref_mut(&mut self) -> &mut Self::Target {
442        &mut self.bytes
443    }
444}
445
446impl AsRef<[u8]> for Bytes {
447    #[inline]
448    fn as_ref(&self) -> &[u8] {
449        &self.bytes
450    }
451}
452
453impl UnsafeToRef for [u8] {
454    type Guard = RawAnyGuard;
455
456    #[inline]
457    unsafe fn unsafe_to_ref<'a>(value: Value) -> Result<(&'a Self, Self::Guard), RuntimeError> {
458        let (value, guard) = Ref::into_raw(value.into_ref::<Bytes>()?);
459        Ok((value.as_ref().as_slice(), guard))
460    }
461}
462
463impl<const N: usize> PartialEq<[u8; N]> for Bytes {
464    #[inline]
465    fn eq(&self, other: &[u8; N]) -> bool {
466        self.bytes == other[..]
467    }
468}
469
470impl<const N: usize> PartialEq<&[u8; N]> for Bytes {
471    #[inline]
472    fn eq(&self, other: &&[u8; N]) -> bool {
473        self.bytes == other[..]
474    }
475}
476
477impl<const N: usize> PartialEq<Bytes> for [u8; N] {
478    #[inline]
479    fn eq(&self, other: &Bytes) -> bool {
480        self[..] == other.bytes
481    }
482}
483
484impl<const N: usize> PartialEq<Bytes> for &[u8; N] {
485    #[inline]
486    fn eq(&self, other: &Bytes) -> bool {
487        self[..] == other.bytes
488    }
489}
490
491impl PartialEq<[u8]> for Bytes {
492    #[inline]
493    fn eq(&self, other: &[u8]) -> bool {
494        self.bytes == other
495    }
496}
497
498impl PartialEq<Bytes> for [u8] {
499    #[inline]
500    fn eq(&self, other: &Bytes) -> bool {
501        self == other.bytes
502    }
503}
504
505impl ser::Serialize for Bytes {
506    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
507    where
508        S: ser::Serializer,
509    {
510        serializer.serialize_bytes(&self.bytes)
511    }
512}
513
514impl<'de> de::Deserialize<'de> for Bytes {
515    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
516    where
517        D: de::Deserializer<'de>,
518    {
519        struct Visitor;
520
521        impl de::Visitor<'_> for Visitor {
522            type Value = Bytes;
523
524            #[inline]
525            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
526                write!(f, "a byte array")
527            }
528
529            #[inline]
530            fn visit_bytes<E>(self, v: &[u8]) -> Result<Self::Value, E>
531            where
532                E: de::Error,
533            {
534                Bytes::from_slice(v).map_err(E::custom)
535            }
536        }
537
538        deserializer.deserialize_bytes(Visitor)
539    }
540}
541
542impl TryFrom<&[u8]> for Value {
543    type Error = alloc::Error;
544
545    #[inline]
546    fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
547        Value::new(Bytes::try_from(value)?)
548    }
549}
550
551impl IntoOutput for &[u8] {
552    #[inline]
553    fn into_output(self) -> Result<Value, RuntimeError> {
554        Ok(Value::try_from(self)?)
555    }
556}
557
558/// This is a common index get implementation that is helpfull for custom type to impl `INDEX_GET` protocol.
559pub fn bytes_slice_index_get(this: &[u8], index: Value) -> VmResult<Option<Value>> {
560    let slice: Option<&[u8]> = 'out: {
561        if let Some(value) = index.as_any() {
562            match value.type_hash() {
563                RangeFrom::HASH => {
564                    let range = vm_try!(value.borrow_ref::<RangeFrom>());
565                    let start = vm_try!(range.start.as_usize());
566                    break 'out this.get(start..);
567                }
568                RangeFull::HASH => {
569                    _ = vm_try!(value.borrow_ref::<RangeFull>());
570                    break 'out this.get(..);
571                }
572                RangeInclusive::HASH => {
573                    let range = vm_try!(value.borrow_ref::<RangeInclusive>());
574                    let start = vm_try!(range.start.as_usize());
575                    let end = vm_try!(range.end.as_usize());
576                    break 'out this.get(start..=end);
577                }
578                RangeToInclusive::HASH => {
579                    let range = vm_try!(value.borrow_ref::<RangeToInclusive>());
580                    let end = vm_try!(range.end.as_usize());
581                    break 'out this.get(..=end);
582                }
583                RangeTo::HASH => {
584                    let range = vm_try!(value.borrow_ref::<RangeTo>());
585                    let end = vm_try!(range.end.as_usize());
586                    break 'out this.get(..end);
587                }
588                Range::HASH => {
589                    let range = vm_try!(value.borrow_ref::<Range>());
590                    let start = vm_try!(range.start.as_usize());
591                    let end = vm_try!(range.end.as_usize());
592                    break 'out this.get(start..end);
593                }
594                _ => {}
595            }
596        };
597
598        let index = vm_try!(usize::from_value(index));
599        let Some(value) = this.get(index) else {
600            return VmResult::Ok(None);
601        };
602
603        return VmResult::Ok(Some((*value).into()));
604    };
605
606    let Some(values) = slice else {
607        return VmResult::Ok(None);
608    };
609
610    let bytes = vm_try!(Bytes::try_from(values));
611    VmResult::Ok(Some(vm_try!(bytes.try_into())))
612}
rune/runtime/bytes.rs

rune/runtime/
bytes.rs
