Skip to main content

tvm_ffi/
string.rs

1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements.  See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership.  The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License.  You may obtain a copy of the License at
9 *
10 *   http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied.  See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19//! [`String`] and [`Bytes`], immutable reference-counted strings.
20
21use crate::derive::Object;
22use crate::object::{Object, ObjectArc, ObjectCoreWithExtraItems, unsafe_};
23use crate::type_traits::AnyCompatible;
24use std::cmp::Ordering;
25use std::fmt::{Debug, Display};
26use std::hash::{Hash, Hasher};
27use std::ops::Deref;
28use tvm_ffi_sys::TVMFFITypeIndex as TypeIndex;
29use tvm_ffi_sys::{TVMFFIAny, TVMFFIAnyDataUnion, TVMFFIByteArray, TVMFFIObject};
30
31//-----------------------------------------------------
32// Bytes
33//-----------------------------------------------------
34/// An immutable byte string, passed across languages as `ffi.Bytes` (Python
35/// `bytes`).
36///
37/// # Examples
38///
39/// ```
40/// use tvm_ffi::Bytes;
41///
42/// let bytes = Bytes::from(&b"abc"[..]);
43/// assert_eq!(bytes.as_slice(), b"abc");
44/// ```
45#[repr(C)]
46pub struct Bytes {
47    data: TVMFFIAny,
48}
49
50// SAFETY: `Bytes` is immutable: inline bytes or an immutable bytes object.
51unsafe impl Send for Bytes {}
52unsafe impl Sync for Bytes {}
53
54// BytesObj for heap-allocated bytes
55#[repr(C)]
56#[derive(Object)]
57#[object(type_key = "ffi.Bytes", unsafe type_index = TypeIndex::kTVMFFIBytes)]
58pub(crate) struct BytesObj {
59    object: Object,
60    data: TVMFFIByteArray,
61}
62
63impl Bytes {
64    /// An empty byte string.
65    pub fn new() -> Self {
66        Self {
67            data: TVMFFIAny {
68                type_index: TypeIndex::kTVMFFISmallBytes as i32,
69                small_str_len: 0,
70                data_union: TVMFFIAnyDataUnion { v_int64: 0 },
71            },
72        }
73    }
74
75    /// The number of bytes.
76    pub fn len(&self) -> usize {
77        self.as_slice().len()
78    }
79
80    /// Whether there are no bytes.
81    pub fn is_empty(&self) -> bool {
82        self.len() == 0
83    }
84
85    /// The bytes as a slice.
86    pub fn as_slice(&self) -> &[u8] {
87        unsafe {
88            if self.data.type_index == TypeIndex::kTVMFFISmallBytes as i32 {
89                std::slice::from_raw_parts(
90                    self.data.data_union.v_bytes.as_ptr(),
91                    self.data.small_str_len as usize,
92                )
93            } else {
94                let str_obj: &BytesObj = &*(self.data.data_union.v_obj as *const BytesObj);
95                std::slice::from_raw_parts(str_obj.data.data, str_obj.data.size)
96            }
97        }
98    }
99}
100
101impl Default for Bytes {
102    #[inline]
103    fn default() -> Self {
104        Self::new()
105    }
106}
107
108unsafe impl ObjectCoreWithExtraItems for BytesObj {
109    type ExtraItem = u8;
110    /// The bytes plus a trailing NUL, so the data is also a C string.
111    #[inline]
112    fn extra_items_count(this: &Self) -> usize {
113        this.data.size + 1
114    }
115}
116
117impl From<&[u8]> for Bytes {
118    /// Copy the bytes of `value`.
119    fn from(value: &[u8]) -> Self {
120        // to be compatible with normal c++
121        const MAX_SMALL_BYTES_LEN: usize = 7;
122        unsafe {
123            if value.len() <= MAX_SMALL_BYTES_LEN {
124                let mut data_union = TVMFFIAnyDataUnion { v_int64: 0 };
125                data_union.v_bytes[..value.len()].copy_from_slice(value);
126                // small bytes
127                Self {
128                    data: TVMFFIAny {
129                        type_index: TypeIndex::kTVMFFISmallBytes as i32,
130                        small_str_len: value.len() as u32,
131                        data_union,
132                    },
133                }
134            } else {
135                // large bytes
136                let mut obj_arc = ObjectArc::new_with_extra_items(BytesObj {
137                    object: Object::new(),
138                    data: TVMFFIByteArray {
139                        data: std::ptr::null(),
140                        size: value.len(),
141                    },
142                });
143                // The fresh allocation is unique and has not been exposed.
144                let object = ObjectArc::as_mut_ptr(&mut obj_arc);
145                let items = BytesObj::extra_items_ptr(object);
146                std::ptr::copy_nonoverlapping(value.as_ptr(), items, value.len());
147                // write the trailing \0 for ffi compatibility
148                items.add(value.len()).write(0);
149                (*object).data.data = items;
150                Self {
151                    data: TVMFFIAny {
152                        type_index: TypeIndex::kTVMFFIBytes as i32,
153                        small_str_len: 0,
154                        data_union: TVMFFIAnyDataUnion {
155                            v_obj: ObjectArc::into_raw(obj_arc) as *mut BytesObj
156                                as *mut TVMFFIObject,
157                        },
158                    },
159                }
160            }
161        }
162    }
163}
164
165impl Deref for Bytes {
166    type Target = [u8];
167    #[inline]
168    fn deref(&self) -> &[u8] {
169        self.as_slice()
170    }
171}
172
173impl Clone for Bytes {
174    #[inline]
175    fn clone(&self) -> Self {
176        if self.data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
177            unsafe { unsafe_::inc_ref(self.data.data_union.v_obj) }
178        }
179        Self { data: self.data }
180    }
181}
182
183impl Drop for Bytes {
184    #[inline]
185    fn drop(&mut self) {
186        if self.data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
187            unsafe { unsafe_::dec_ref(self.data.data_union.v_obj) }
188        }
189    }
190}
191
192impl PartialEq for Bytes {
193    #[inline]
194    fn eq(&self, other: &Self) -> bool {
195        self.as_slice() == other.as_slice()
196    }
197}
198
199impl Eq for Bytes {}
200
201impl PartialOrd for Bytes {
202    #[inline]
203    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
204        Some(self.cmp(other))
205    }
206}
207
208impl Ord for Bytes {
209    #[inline]
210    fn cmp(&self, other: &Self) -> Ordering {
211        self.as_slice().cmp(other.as_slice())
212    }
213}
214
215impl Hash for Bytes {
216    #[inline]
217    fn hash<H: Hasher>(&self, state: &mut H) {
218        self.as_slice().hash(state);
219    }
220}
221
222/// Formats as `[u8]` does, such as `[97, 98]`.
223impl Debug for Bytes {
224    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
225        Debug::fmt(self.as_slice(), f)
226    }
227}
228
229macro_rules! impl_bytes_from {
230    ($([$($g:tt)*] $t:ty),* $(,)?) => {
231        $(impl<$($g)*> From<$t> for Bytes {
232            #[inline]
233            fn from(value: $t) -> Self {
234                Self::from(&value[..])
235            }
236        })*
237    };
238}
239
240impl_bytes_from!([] &mut [u8], [] Vec<u8>, [] &Vec<u8>, [] Box<[u8]>, [const N: usize] [u8; N], [const N: usize] &[u8; N]);
241
242macro_rules! impl_bytes_eq {
243    ($([$($g:tt)*] $t:ty),* $(,)?) => {
244        $(impl<$($g)*> PartialEq<$t> for Bytes {
245            #[inline]
246            fn eq(&self, other: &$t) -> bool {
247                self.as_slice() == &other[..]
248            }
249        }
250
251        impl<$($g)*> PartialEq<Bytes> for $t {
252            #[inline]
253            fn eq(&self, other: &Bytes) -> bool {
254                &self[..] == other.as_slice()
255            }
256        })*
257    };
258}
259
260impl_bytes_eq!([] [u8], ['a] &'a [u8], [] Vec<u8>, [const N: usize] [u8; N], ['a, const N: usize] &'a [u8; N]);
261
262impl AsRef<[u8]> for Bytes {
263    #[inline]
264    fn as_ref(&self) -> &[u8] {
265        self.as_slice()
266    }
267}
268
269impl std::borrow::Borrow<[u8]> for Bytes {
270    #[inline]
271    fn borrow(&self) -> &[u8] {
272        self.as_slice()
273    }
274}
275
276impl From<Bytes> for Vec<u8> {
277    #[inline]
278    fn from(value: Bytes) -> Self {
279        value.as_slice().to_vec()
280    }
281}
282
283//-----------------------------------------------------
284// String
285//-----------------------------------------------------
286
287/// An immutable UTF-8 string, passed across languages as `ffi.String`
288/// (Python `str`).
289///
290/// An `ffi.String` holds UTF-8 by contract, which other languages keep, so
291/// [`as_str`](Self::as_str) does not validate strings received through FFI.
292///
293/// Short strings are stored inline in an [`Any`](crate::Any) without an
294/// allocation.
295///
296/// # Examples
297///
298/// ```
299/// use tvm_ffi::String;
300///
301/// let text = String::from("hello");
302/// assert_eq!(text.as_str(), "hello");
303/// assert_eq!(text.len(), 5);
304/// assert_eq!(text, "hello");
305/// ```
306#[repr(C)]
307pub struct String {
308    data: TVMFFIAny,
309}
310
311// SAFETY: a `String` is immutable: an inline small string or an immutable string object.
312unsafe impl Send for String {}
313unsafe impl Sync for String {}
314
315// StringObj for heap-allocated string
316#[repr(C)]
317#[derive(Object)]
318#[object(type_key = "ffi.String", unsafe type_index = TypeIndex::kTVMFFIStr)]
319pub(crate) struct StringObj {
320    object: Object,
321    data: TVMFFIByteArray,
322}
323
324unsafe impl ObjectCoreWithExtraItems for StringObj {
325    type ExtraItem = u8;
326    /// The bytes plus a trailing NUL, so the data is also a C string.
327    #[inline]
328    fn extra_items_count(this: &Self) -> usize {
329        this.data.size + 1
330    }
331}
332
333impl String {
334    /// An empty string.
335    pub fn new() -> Self {
336        Self {
337            data: TVMFFIAny {
338                type_index: TypeIndex::kTVMFFISmallStr as i32,
339                small_str_len: 0,
340                data_union: TVMFFIAnyDataUnion { v_int64: 0 },
341            },
342        }
343    }
344
345    /// The length in bytes.
346    pub fn len(&self) -> usize {
347        self.as_bytes().len()
348    }
349
350    /// Whether the string is empty.
351    pub fn is_empty(&self) -> bool {
352        self.len() == 0
353    }
354
355    /// The string as bytes.
356    pub fn as_bytes(&self) -> &[u8] {
357        unsafe {
358            if self.data.type_index == TypeIndex::kTVMFFISmallStr as i32 {
359                std::slice::from_raw_parts(
360                    self.data.data_union.v_bytes.as_ptr(),
361                    self.data.small_str_len as usize,
362                )
363            } else {
364                let str_obj: &StringObj = &*(self.data.data_union.v_obj as *const StringObj);
365                std::slice::from_raw_parts(str_obj.data.data, str_obj.data.size)
366            }
367        }
368    }
369
370    /// The string as a `str`.
371    pub fn as_str(&self) -> &str {
372        unsafe { std::str::from_utf8_unchecked(self.as_bytes()) }
373    }
374}
375
376impl From<&str> for String {
377    /// Copy the string `value`.
378    fn from(value: &str) -> Self {
379        unsafe {
380            let bytes = value.as_bytes();
381            const MAX_SMALL_BYTES_LEN: usize = 7;
382            if bytes.len() <= MAX_SMALL_BYTES_LEN {
383                let mut data_union = TVMFFIAnyDataUnion { v_int64: 0 };
384                data_union.v_bytes[..bytes.len()].copy_from_slice(bytes);
385                Self {
386                    data: TVMFFIAny {
387                        type_index: TypeIndex::kTVMFFISmallStr as i32,
388                        small_str_len: bytes.len() as u32,
389                        data_union,
390                    },
391                }
392            } else {
393                let mut obj_arc = ObjectArc::new_with_extra_items(StringObj {
394                    object: Object::new(),
395                    data: TVMFFIByteArray {
396                        data: std::ptr::null(),
397                        size: bytes.len(),
398                    },
399                });
400                // The fresh allocation is unique and has not been exposed.
401                let object = ObjectArc::as_mut_ptr(&mut obj_arc);
402                let items = StringObj::extra_items_ptr(object);
403                std::ptr::copy_nonoverlapping(bytes.as_ptr(), items, bytes.len());
404                // write the trailing \0 for ffi compatibility
405                items.add(bytes.len()).write(0);
406                (*object).data.data = items;
407                Self {
408                    data: TVMFFIAny {
409                        type_index: TypeIndex::kTVMFFIStr as i32,
410                        small_str_len: 0,
411                        data_union: TVMFFIAnyDataUnion {
412                            v_obj: ObjectArc::into_raw(obj_arc) as *mut StringObj
413                                as *mut TVMFFIObject,
414                        },
415                    },
416                }
417            }
418        }
419    }
420}
421
422impl Default for String {
423    #[inline]
424    fn default() -> Self {
425        Self::new()
426    }
427}
428
429impl Deref for String {
430    type Target = str;
431    #[inline]
432    fn deref(&self) -> &str {
433        self.as_str()
434    }
435}
436
437impl Clone for String {
438    #[inline]
439    fn clone(&self) -> Self {
440        if self.data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
441            unsafe { unsafe_::inc_ref(self.data.data_union.v_obj) }
442        }
443        Self { data: self.data }
444    }
445}
446
447impl Drop for String {
448    #[inline]
449    fn drop(&mut self) {
450        if self.data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
451            unsafe { unsafe_::dec_ref(self.data.data_union.v_obj) }
452        }
453    }
454}
455
456impl PartialEq for String {
457    #[inline]
458    fn eq(&self, other: &Self) -> bool {
459        self.as_bytes() == other.as_bytes()
460    }
461}
462
463macro_rules! impl_string_from {
464    ($([$($g:tt)*] $t:ty),* $(,)?) => {
465        $(impl<$($g)*> From<$t> for String {
466            #[inline]
467            fn from(value: $t) -> Self {
468                Self::from(&value[..])
469            }
470        })*
471    };
472}
473
474impl_string_from!([] &mut str, [] std::string::String, [] &std::string::String, [] Box<str>, ['a] std::borrow::Cow<'a, str>);
475
476macro_rules! impl_string_eq {
477    ($([$($g:tt)*] $t:ty),* $(,)?) => {
478        $(impl<$($g)*> PartialEq<$t> for String {
479            #[inline]
480            fn eq(&self, other: &$t) -> bool {
481                self.as_str() == &other[..]
482            }
483        }
484
485        impl<$($g)*> PartialEq<String> for $t {
486            #[inline]
487            fn eq(&self, other: &String) -> bool {
488                &self[..] == other.as_str()
489            }
490        })*
491    };
492}
493
494impl_string_eq!([] str, ['a] &'a str, [] std::string::String, ['a] std::borrow::Cow<'a, str>);
495
496impl AsRef<str> for String {
497    #[inline]
498    fn as_ref(&self) -> &str {
499        self.as_str()
500    }
501}
502
503impl AsRef<[u8]> for String {
504    #[inline]
505    fn as_ref(&self) -> &[u8] {
506        self.as_bytes()
507    }
508}
509
510impl std::borrow::Borrow<str> for String {
511    #[inline]
512    fn borrow(&self) -> &str {
513        self.as_str()
514    }
515}
516
517impl From<String> for std::string::String {
518    #[inline]
519    fn from(value: String) -> Self {
520        value.as_str().to_owned()
521    }
522}
523
524impl Eq for String {}
525
526impl PartialOrd for String {
527    #[inline]
528    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
529        Some(self.cmp(other))
530    }
531}
532
533impl Ord for String {
534    #[inline]
535    fn cmp(&self, other: &Self) -> Ordering {
536        self.as_str().cmp(other.as_str())
537    }
538}
539
540impl Hash for String {
541    #[inline]
542    fn hash<H: Hasher>(&self, state: &mut H) {
543        self.as_str().hash(state);
544    }
545}
546
547impl Display for String {
548    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
549        Display::fmt(self.as_str(), f)
550    }
551}
552
553/// Formats as `str` does, such as `"hi"`.
554impl Debug for String {
555    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
556        Debug::fmt(self.as_str(), f)
557    }
558}
559
560//-----------------------------------------------------
561// AnyCompatible implementation for Bytes and String
562//-----------------------------------------------------
563unsafe impl AnyCompatible for Bytes {
564    fn type_str() -> std::string::String {
565        "ffi.Bytes".to_string()
566    }
567
568    // Bytes are small bytes or a bytes object, never None.
569    #[inline]
570    unsafe fn is_undefined(field: *const Self) -> bool {
571        unsafe { (*std::ptr::addr_of!((*field).data.type_index)) == TypeIndex::kTVMFFINone as i32 }
572    }
573
574    unsafe fn copy_to_any_view(this: &Self, data: &mut TVMFFIAny) {
575        *data = this.data;
576    }
577
578    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
579        *data = src.data;
580        std::mem::forget(src);
581    }
582
583    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
584        data.type_index == TypeIndex::kTVMFFISmallBytes as i32
585            || data.type_index == TypeIndex::kTVMFFIBytes as i32
586    }
587
588    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
589        if data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
590            unsafe { unsafe_::inc_ref(data.data_union.v_obj) }
591        }
592        Self { data: *data }
593    }
594
595    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
596        Self { data: *data }
597    }
598
599    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
600        if data.type_index == TypeIndex::kTVMFFIByteArrayPtr as i32 {
601            // deep copy from bytearray ptr
602            let bytes = unsafe { &*(data.data_union.v_ptr as *const TVMFFIByteArray) };
603            Ok(unsafe {
604                Self::from(crate::util::slice_from_nullable_raw_parts(
605                    bytes.data, bytes.size,
606                ))
607            })
608        } else if data.type_index == TypeIndex::kTVMFFISmallBytes as i32 {
609            Ok(Self { data: *data })
610        } else if data.type_index == TypeIndex::kTVMFFIBytes as i32 {
611            unsafe { unsafe_::inc_ref(data.data_union.v_obj) }
612            Ok(Self { data: *data })
613        } else {
614            Err(())
615        }
616    }
617}
618
619unsafe impl AnyCompatible for String {
620    fn type_str() -> std::string::String {
621        "ffi.String".to_string()
622    }
623
624    // A string is a small string or a string object, never None.
625    #[inline]
626    unsafe fn is_undefined(field: *const Self) -> bool {
627        unsafe { (*std::ptr::addr_of!((*field).data.type_index)) == TypeIndex::kTVMFFINone as i32 }
628    }
629
630    unsafe fn copy_to_any_view(this: &Self, data: &mut TVMFFIAny) {
631        *data = this.data;
632    }
633
634    unsafe fn move_to_any(src: Self, data: &mut TVMFFIAny) {
635        *data = src.data;
636        std::mem::forget(src);
637    }
638
639    unsafe fn check_any_strict(data: &TVMFFIAny) -> bool {
640        data.type_index == TypeIndex::kTVMFFISmallStr as i32
641            || data.type_index == TypeIndex::kTVMFFIStr as i32
642    }
643
644    unsafe fn copy_from_any_view_after_check(data: &TVMFFIAny) -> Self {
645        if data.type_index >= TypeIndex::kTVMFFIStaticObjectBegin as i32 {
646            unsafe { unsafe_::inc_ref(data.data_union.v_obj) }
647        }
648        Self { data: *data }
649    }
650
651    unsafe fn move_from_any_after_check(data: &mut TVMFFIAny) -> Self {
652        Self { data: *data }
653    }
654
655    unsafe fn try_cast_from_any_view(data: &TVMFFIAny) -> Result<Self, ()> {
656        if data.type_index == TypeIndex::kTVMFFIRawStr as i32 {
657            let c_str = unsafe {
658                std::ffi::CStr::from_ptr(data.data_union.v_c_str as *const std::os::raw::c_char)
659            };
660            c_str.to_str().map(Self::from).map_err(|_| ())
661        } else if data.type_index == TypeIndex::kTVMFFISmallStr as i32 {
662            Ok(Self { data: *data })
663        } else if data.type_index == TypeIndex::kTVMFFIStr as i32 {
664            unsafe { unsafe_::inc_ref(data.data_union.v_obj) }
665            Ok(Self { data: *data })
666        } else {
667            Err(())
668        }
669    }
670}