Struct JavaStr

Source

pub struct JavaStr { /* private fields */ }

Expand description

A Java CESU-8 encoded string slice.

Implementations§

Source §

impl JavaStr

Source

pub const fn from_java_cesu8(v: &[u8]) -> Result<&JavaStr, EncodingError>

Converts a slice of bytes to a JavaStr.

A Java CESU-8 string slice (JavaStr) is made of bytes (u8), and a byte slice ([u8]) is made of bytes, so this function converts betwen the two. Not all byte slices are valid string slices, however JavaStr requires that it is valid Java CESU-8. from_java_cesu8 checks to ensure that the bytes are valid Java CESU-8, and then does the conversion.

If you are sure that the byte slice is valid Java CESU-8, and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function from_java_cesu8_unchecked, which has the same behavior but skips the check.

§Errors

Returns Err if the slice is not Java CESU-8 with a description as to why the provided slice is not Java CESU-8.

Source

pub fn from_java_cesu8_mut(v: &mut [u8]) -> Result<&mut JavaStr, EncodingError>

Converts a mutable slice of bytes to a mutable JavaStr.

A Java CESU-8 string slice (JavaStr) is made of bytes (u8), and a byte slice ([u8]) is made of bytes, so this function converts betwen the two. Not all byte slices are valid string slices, however JavaStr requires that it is valid Java CESU-8. from_java_cesu8 checks to ensure that the bytes are valid Java CESU-8, and then does the conversion.

If you are sure that the byte slice is valid Java CESU-8, and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function from_java_cesu8_unchecked_mut, which has the same behavior but skips the check.

§Errors

Returns Err if the slice is not Java CESU-8 with a description as to why the provided slice is not Java CESU-8.

Source

pub const unsafe fn from_java_cesu8_unchecked(v: &[u8]) -> &JavaStr

Converts a slice of bytes to a JavaStr without checking that the string contains valid Java CESU-8.

See the safe version, from_java_cesu8, for more details.

§Safety

The bytes passed in must be valid Java CESU-8.

Source

pub unsafe fn from_java_cesu8_unchecked_mut(v: &mut [u8]) -> &mut JavaStr

Converts a mutable slice of bytes to a mutable JavaStr without checking that the string contains valid Java CESU-8.

See the safe version, from_java_cesu8_mut, for more details.

§Safety

The bytes passed in must be valid Java CESU-8.

Source

pub unsafe fn from_boxed_java_cesu8_unchecked(v: Box<[u8]>) -> Box<JavaStr>

Converts a boxed slice of bytes to a boxed string slice without checking that the string contains valid Java CESU-8.

§Safety

The bytes passed in must be valid Java CESU-8.

Source

pub const fn len(&self) -> usize

Returns the length of self.

This length is in bytes, not chars or graphemes. In other words, it might not be what a human considers the length of the string.

Source

pub const fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

Source

pub fn is_char_boundary(&self, index: usize) -> bool

Checks that the index-th byte is the first byte in a Java CESU-8 code point sequence or the end of the string.

The start and end of the string (when index == self.len()) are considered to be boundaries.

Returns false if index is greater than self.len().

Source

pub const fn as_bytes(&self) -> &[u8]

Converts a string slice to a byte slice.

Source

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

Converts a mutable string slice to a mutable byte slice.

§Safety

The caller must ensure that the content of the slice is valid Java CESU-8 before the borrow ends and the underlying JavaStr is used.

Use of a JavaStr whose contents are not valid Java CESU-8 is undefined behavior.

Source

pub const fn as_ptr(&self) -> *const u8

Converts a string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a u8. This pointer will be pointing to the first bytes of the string slice.

The caller must ensure that the returned pointer is never written to. If you need to mutate the contents of the string slice, use as_mut_ptr.

Source

pub fn as_mut_ptr(&mut self) -> *mut u8

Converts a mutable string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a u8. This pointer will be pointing to the first byte of the string slice.

It is your responsibility to make sure that the string slice only gets modified in a way that it remains valid Java CESU-8.

Source

pub fn get<I: RangeBounds<usize>>(&self, index: I) -> Option<&JavaStr>

Returns a subslice of JavaStr.

This is the non-panicking alternative to indexing the str. Returns None whenever equivalent indexing operations would panic.

Source

pub fn get_mut<I: RangeBounds<usize>>( &mut self, index: I, ) -> Option<&mut JavaStr>

Returns a mutable subslice of JavaStr.

This is the non-panicking alternative to indexing the JavaStr. Returns None whenver equivalent indexing operations would panic.

Source

pub unsafe fn get_unchecked<I: RangeBounds<usize>>(&self, index: I) -> &JavaStr

Returns an unchecked subslice of JavaStr.

This is the unchecked alternative to indexing the JavaStr.

§Safety

Callers of this function are responsible for ensuring that:

The starting index does not exceed the ending index;
The indices are within the bounds of the original slice;
The indices fall on Java CESU-8 sequence boundaries.

Failing that, the returned string slice may reference invalid memory or violate the invariants communicated by the JavaStr type.

Source

pub unsafe fn get_unchecked_mut<I: RangeBounds<usize>>( &mut self, index: I, ) -> &mut JavaStr

Returns a mutable, unchecked subslice of JavaStr.

This the unchecked alternative to indexing the JavaStr.

§Safety

Callers of this function are responsible for ensuring that:

The starting index does not exceed the ending index;
The indices are within the bounds of the original slice;
The indices fall on Java CESU-8 sequence boundaries.

Failing that, the returned string slice may reference invalid memory or violate the invariants communicated by the JavaStr type.

Source

pub fn split_at(&self, mid: usize) -> (&JavaStr, &JavaStr)

Divide one string slice into two at an index.

The argument, mid, should be a byte offset from the start of the string. It must also be on the boundary of a Java CESU-8 character.

The two slices returned go from the string of the string slice to mid, and from mid to the end of the string slice.

To get mutable string slices instead, see the split_at_mut method.

Source

pub fn split_at_mut(&mut self, mid: usize) -> (&mut JavaStr, &mut JavaStr)

Divide one mutable string slice into two at an index.

The argument, mid, should be a byte offset from the start of the string. It must also be on the boundary of a Java CESU-8 character.

The two slices returned go from the string of the string slice to mid, and from mid to the end of the string slice.

To get immutable string slices instead, see the split_at method.

Source

pub fn split_at_checked(&self, mid: usize) -> Option<(&JavaStr, &JavaStr)>

Divide one string slice into two at an index.

The argument, mid, should be a valid byte offset from the start of the string. It must also be on the boundary of a Java CESU-8 code point. The method returns None if that’s not the case.

The two slices returned go from the start of the string slice to mid, and from mid to the end of the string slice.

To get mutable string slices instead, see the split_at_mut_checked method.

Source

pub fn split_at_mut_checked( &mut self, mid: usize, ) -> Option<(&mut JavaStr, &mut JavaStr)>

Divide one mutable string slice into two at an index.

The argument, mid, should be a valid byte offset from the start of the string. It must also be on the boundary of a Java CESU-8 code point. The method returns None if that’s not the case.

The two slices returned go from the start of the string slice to mid, and from mid to the end of the string slice.

To get immutable string slices instead, see the split_at_checked method.

Source

pub unsafe fn split_at_unchecked(&self, mid: usize) -> (&JavaStr, &JavaStr)

Divide a string into two at an index.

The two slices returned go from the start of the string slice to mid, and from mid to the end of the string slice.

To get mutable string slices instead, see the split_at_mut_unchecked method.

§Safety

The caller must ensure that mid is a valid byte offset from the start of the string and falls on the boundary of a Java CESU-8 character.

Source

pub unsafe fn split_at_mut_unchecked( &mut self, mid: usize, ) -> (&mut JavaStr, &mut JavaStr)

Divide a mutable string into two at an index.

The two slices returned go from the start of the string slice to mid, and from mid to the end of the string slice.

To get immutable string slices instead, see the split_at_unchecked method.

§Safety

The caller must ensure that mid is a valid byte offset from the start of the string and falls on the boundary of a Java CESU-8 character.

Source

pub fn chars(&self) -> JavaChars<'_> ⓘ

Returns an iterator over the chars of a string slice.

As an JavaStr consists of valid Java CESU-8, we can iterate through a string by char. This method returns such an iterator.

It’s important to remember that char represents a Unicode Scalar Value, and might not match your idea of what a ‘character’ is. Iteration over grapheme clusters may be what you actually want. This functionality is not provided by this crate.

Source

pub fn char_indices(&self) -> JavaCharIndices<'_> ⓘ

Returns an iterator over the chars of a string slice, and their positions.

As an JavaStr consists of valid Java CESU-8, we can iterate through a string by char. This method returns an iterator of both these chars, as well as their byte positions.

The iterator yields tuples. The position is first, the char is second.

Source