Struct JavaString 

pub struct JavaString { /* private fields */ }

A Java CESU-8 encoded, growable string.

Implementations

impl JavaString

pub const fn new() -> JavaString

Creates a new empty JavaString.

Given that the JavaString is empty, this will not allocate any initial buffer. While that means that this initial operations is very inexpensive, it may cause excessive allocation later when you add data. If you have an idea of how much data the JavaString will hold, consider the with_capacity method to prevent excessive re-allocation.

pub fn with_capacity(capacity: usize) -> JavaString

Creates a new empty JavaString with at least the specified capacity.

JavaStrings have an internal buffer to hold their data. The capacity is at length of that buffer, and can be queried with the capacity method. This method creates an empty JavaString, but one with an initial buffer that can hold at least capacity bytes. This is useful when you may be appending a bunch of data to the JavaString, reducing the number of reallocations it needs to do.

If the given capacity is 0, no allocation will occur, and this method is identical to the new method.

pub fn from_java_cesu8(vec: Vec<u8>) -> Result<JavaString, FromVecError>

Converts a vector of bytes into a JavaString.

A string (JavaString) is made of bytes (u8), and a vector of bytes (Vec<u8>) is made of bytes, so this function converts between the two. Not all byte slices are valid JavaStrings, however: JavaString 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.

This method will take care to not to copy the vector, for efficiency’s sake.

If you need a &JavaStr instead of a JavaString, consider JavaStr::from_java_cesu8.

The inverse of this method is into_bytes.

Errors

Returns Err if the slice is not Java CESU-8 with the index and length of the invalid byte. The vector you moved in is also included.

pub unsafe fn from_raw_parts( buf: *mut u8, length: usize, capacity: usize, ) -> JavaString

Creates a new JavaString from a length, capacity, and pointer.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• The memory at buf needs to have been previously allocationed by the same allocator the standard library uess, with a required alignment of exactly 1.
• length needs to be less than or equal to capacity.
• capacity needs to be the correct value.
• The first length bytes at buf need to be valid Java CESU-8.

Violating these may cause problems like correcting the allocator’s internal data structures. For example, it is normally not safe to build a JavaString from a pointer to a C char array containing Java CESU-8 unless you are certain that array was originally allocated by the Rust standard library’s allocator.

The ownership of buf is effectively transferred to the JavaString which may then deallocate, reallocate, or change the contents of memory pointed to by the pointer at will. Ensure that nothing elese uses the pointer after calling this function.

pub const unsafe fn from_java_cesu8_unchecked(bytes: Vec<u8>) -> JavaString

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

Safety

This function is unsafe because it does not check that the bytes passed to it are valid Java CESU-8. If this constraint is violated, it may cause memory unsafety issues with future users of the JavaString.

pub fn into_bytes(self) -> Vec<u8>

Converts a JavaString into a byte vector.

This consumes the JavaString, so we do not need to copy its contents.

pub fn as_str(&self) -> &JavaStr

Extracts a string slice containing the entire JavaString.

pub fn as_mut_str(&mut self) -> &mut JavaStr

Converts a JavaString into a mutable string slice.

pub fn push_str(&mut self, str: &JavaStr)

Appends a given string slice onto the end of this JavaString.

pub fn capacity(&self) -> usize

Returns this JavaString’s capacity, in bytes.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional bytes more than the current length. The allocator may reserve more space to speculatively avoid frequent allocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

pub fn reserve_exact(&mut self, additional: usize)

Reserves the minimum capacity for at least additional bytes more than the current length. Unlike reserve, this will not deliberately over-allocate to speculatively avoid allocations. After calling reserve reserve_excat, capacity will be greater than or equal to self.len() + additional. Does nothing if the capacity is already sufficient.

Panics

Panics if the new capacity overflows usize.

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Tries to reserve capacity for at least additional bytes more than the current length. The allocator may reserve more space to speculatively avoid frequent allocations. After calling try_reserve, capacity will be greater than or equal to self.len() + additional if it returns OK(()). Does nothing if capacity is already sufficient. This method preserves the contents even if an error occurs.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn try_reserve_exact( &mut self, additional: usize, ) -> Result<(), TryReserveError>

Tries to reserve the minimum capacity for at least additional bytes more than current length. Unlike try_reserve, this will not deliberately over-allocate to speculatively avoid frequent allocations. After calling try_reserve_exact, capacity will be greater than or equal self.len() + additional if it returns Ok(()). Does nothing if the capacity is already sufficient.

Not that the allocator may give the collection more space than it requests. Therefore, capacity can not be relied upon to be precisely minimal. Prefer try_reserve if future insertions are expected.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of this JavaString to match its length.

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of this JavaString with a lower bound.

The capacity will remaing at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

pub fn push(&mut self, c: char)

Appends the given char to the end of this JavaString.

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

Returns a byte slice of this JavaString’s contents.

pub fn truncate(&mut self, new_len: usize)

Shortens this JavaString to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string.

Panics

Panics if new_len does not lie on a char boundary.

pub fn pop(&mut self) -> Option<char>

Removes the last character from the string buffer and returns it.

Returns None if this JavaString is empty.

pub fn remove(&mut self, idx: usize) -> char

Removes a char from this JavaString at a byte position and returns it.

This is an O(n) operation, as it requires copy every element in the buffer.

Panics

Panics if idx is large than or equal to the JavaString’s length, or if it does not lie on a char boundary.

pub fn insert(&mut self, idx: usize, c: char)

Inserts a character into this JavaString at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the JavaString’s length, or if it does not lie on a char boundary.

pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8>

Returns a mutable reference to the contents of this JavaString.

Safety

This function is unsafe because the returned &mut Vec allows writing bytes which are not valid Java Java CESU-8. If this constraint is violated, using the original JavaString after dropping the &mut Vec may violate memory safety, as JavaStrings are expected to always contains valid Java Java CESU-8.

pub fn len(&self) -> usize

Returns the length of this JavaString, in bytes, nor chars or graphemes. In other words, it might not be what a human considers the length of the string.

pub fn is_empty(&self) -> bool

Returns true if this JavaString has a length of zero, and false otherwise.

pub fn clear(&mut self)

Truncates this JavaString, removing all contents.

While this means the JavaString will have a length of zero, it does not touch its capacity.

pub fn into_boxed_str(self) -> Box<JavaStr>

Converts this JavaString into a Box<JavaStr.

This will drop any excess capacity.

pub fn leak<'a>(self) -> &'a mut JavaStr

Consumes and leaks the JavaString, returning a mutable reference to the contents, &'a mut InternalStr.

The caller has free choice over the returned lifetime, including 'static. Indeed, this function is ideally used for data that lives fro the remainder of the program’s life, as dropping the returned reference will cause a memory leak.

It does not reallocate or shrink the JavaString, so the leaked allocation may include unused capacity that is not part of the returned slice. If you don’t want that, call into_boxed_str, and then Box::leak.

Methods from Deref<Target = JavaStr>

pub 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.

pub fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

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().

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

Converts a string slice to a byte slice.

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.

pub 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

pub fn is_ascii(&self) -> bool

Checks if all characters in this string are within the ASCII range.

Trait Implementations

impl Borrow<JavaStr> for JavaString

fn borrow(&self) -> &JavaStr

Immutably borrows from an owned value.

impl Clone for JavaString

fn clone(&self) -> JavaString

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JavaString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for JavaString

fn default() -> Self

Returns the “default value” for a type.

impl Deref for JavaString

type Target = JavaStr

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for JavaString

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Display for JavaString

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Index<Range<usize>> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<Range<usize>> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<Range<usize>> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for &JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for &mut JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for JavaString

Available on crate feature alloc only.

type Output = JavaStr

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<Range<usize>> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: Range<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<Range<usize>> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: Range<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeFrom<usize>> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeFrom<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeFrom<usize>> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeFrom<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeFull> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeFull) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeFull> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeFull) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeInclusive<usize>> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeInclusive<usize>> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeTo<usize>> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeTo<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeTo<usize>> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeTo<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeToInclusive<usize>> for &mut JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeToInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl IndexMut<RangeToInclusive<usize>> for JavaString

Available on crate feature alloc only.

fn index_mut(&mut self, index: RangeToInclusive<usize>) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl Ord for JavaString

fn cmp(&self, other: &JavaString) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for JavaString

fn eq(&self, other: &JavaString) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for JavaString

fn partial_cmp(&self, other: &JavaString) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for JavaString

impl StructuralPartialEq for JavaString