Struct JString 

pub struct JString<'local>(/* private fields */);

A java.lang.String reference, tied to a JNI local reference frame.

See the JObject documentation for more information about object references, how to cast them, and local reference frame lifetimes.

Implementations

impl<'local> JString<'local>

pub unsafe fn from_raw<'env_inner>( env: &Env<'env_inner>, raw: jstring, ) -> JString<'env_inner>

Creates a JString that wraps the given raw jobject

Safety

• raw must be a valid raw JNI local reference (or null).
• raw must be an instance of the correct Java class.
• There must not be any other owning Reference wrapper for the same reference.
• The local reference must belong to the current thread and not outlive the JNI stack frame associated with the Env 'local lifetime.

pub const fn null() -> JString<'static>

Creates a new null reference.

Null references are always valid and do not belong to a local reference frame. Therefore, the returned JString always has the 'static lifetime.

pub fn into_raw(self) -> jstring

Unwrap to the raw jni type.

pub fn cast_local<'any_local>( env: &mut Env<'_>, obj: impl Reference + Into<JObject<'any_local>> + AsRef<JObject<'any_local>>, ) -> Result<JString<'any_local>>

Cast a local reference to a JString

This will do a runtime (IsInstanceOf) check that the object is an instance of the correct class.

Also see these other options for casting local or global references to a JString:

• Env::as_cast
• Env::new_cast_local_ref
• Env::cast_local
• Env::new_cast_global_ref
• Env::cast_global

Errors

Returns Error::WrongObjectType if the IsInstanceOf check fails.

impl<'local> JString<'local>

pub fn as_char_sequence(&self) -> Cast<'local, '_, JCharSequence<'local>>

Casts this JString to a ::jni::objects::JCharSequence

This does not require a runtime type check since any JString is also a ::jni::objects::JCharSequence

impl<'local> JString<'local>

pub fn intern<'env_local>( &self, env: &mut Env<'env_local>, ) -> Result<JString<'env_local>>

Returns a canonical, interned version of this string.

impl JString<'_>

pub fn new<'env_local>( env: &mut Env<'env_local>, from: impl AsRef<str>, ) -> Result<JString<'env_local>>

Encodes a Rust &str to MUTF-8 and creates a JString (java.lang.String object).

This is a convenience that’s equivalent to calling Self::from_str

This API catches exceptions internally and is not expected to return Error::JavaException (unless called while there is a pending exception).

Performance

The input string is re-encoded to modified UTF-8, so this involves a copy of your input to encode, before calling into JNI to create the JString.

To avoid the overhead of encoding and copying, use Self::from_jni_str and the crate::jni_str! macro to encode strings to MUTF-8 at compile time.

pub fn from_str<'env_local>( env: &mut Env<'env_local>, from: impl AsRef<str>, ) -> Result<JString<'env_local>>

Encodes a Rust &str to MUTF-8 and creates a JString (java.lang.String object).

This API catches exceptions internally and is not expected to return Error::JavaException (unless called while there is a pending exception).

Performance

The input string is re-encoded to modified UTF-8, so this involves a copy of your input to encode, before calling into JNI to create the JString.

To avoid the overhead of encoding and copying, use Self::from_jni_str and the crate::jni_str! macro to encode strings to MUTF-8 at compile time.

pub fn from_jni_str<'env_local>( env: &mut Env<'env_local>, from: impl AsRef<JNIStr>, ) -> Result<JString<'env_local>>

Creates a JString (java.lang.String object) from a JNIStr (modified UTF-8).

For simple string literals, consider using the crate::jni_str! macro to create / encode JNIStr literals at compile time.

This API catches exceptions internally and is not expected to return Error::JavaException (unless called while there is a pending exception).

pub fn mutf8_chars(&self, env: &Env<'_>) -> Result<MUTF8Chars<'_, &JString<'_>>>

Gets the contents of this string, in modified UTF-8 encoding (via GetStringUTFChars).

The returned MUTF8Chars guard can be used to access the modified UTF-8 bytes, or to convert to a Rust string (UTF-8).

For example:

let my_jstring = JString::from_str(env, "Hello, world!")?;
let mutf8_chars = my_jstring.mutf8_chars(env)?;
let jni_str: &JNIStr = &mutf8_chars;
let rust_str = jni_str.to_str();

When the MUTF8Chars guard is dropped, the reference to the contents gets released.

The MUTF8Chars guard dereferences to a JNIStr.

Also note that MUTF8Chars (and also JString itself) implements Display and ToString so it’s also possible to use .to_string() to get a Rust String from a JString

Errors

Returns an Error::NullPtr if this JString is null.

pub fn try_to_string(&self, env: &Env<'_>) -> Result<String>

Gets the contents of this string as a Rust String.

For example:

let jstring = JString::from_str(env, "Hello, world!")?;
let rust_string = jstring.try_to_string(&env)?;
assert_eq!(rust_string, "Hello, world!");

This is equivalent to calling Self::mutf8_chars and then converting that to a String, like:

let jstring = JString::from_str(env, "Hello, world!")?;
let mutf8_chars = jstring.mutf8_chars(&env)?;
let rust_string = mutf8_chars.to_string();

Errors

Returns an Error::NullPtr if this JString is null.

Methods from Deref<Target = JObject<'local>>

pub fn as_raw(&self) -> jobject

Returns the raw JNI pointer.

Trait Implementations

impl<'local> AsRef<JCharSequence<'local>> for JString<'local>

fn as_ref(&self) -> &JCharSequence<'local>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'local> AsRef<JObject<'local>> for JString<'local>

fn as_ref(&self) -> &JObject<'local>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'local> AsRef<JString<'local>> for JString<'local>

fn as_ref(&self) -> &JString<'local>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'local> Debug for JString<'local>

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

Formats the value using the given formatter.

impl<'local> Default for JString<'local>

fn default() -> JString<'local>

Returns the “default value” for a type.

impl<'local> Deref for JString<'local>

type Target = JObject<'local>

The resulting type after dereferencing.

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

Dereferences the value.

impl<'local> Display for JString<'local>

Display the contents of a JString

This implementation relies on JNI (GetStringUTFChars) to retrieve the string contents for display.

If you try and format a null reference this will output “”

In case you attempt to format a JString before JavaVM::singleton has been initialized then this will simply output “” and log an error.

In case of any other unexpected JNI error, this will output “” and log the error details.

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

Formats the value using the given formatter.

impl<'local> From<JString<'local>> for JCharSequence<'local>

fn from(value: JString<'local>) -> JCharSequence<'local>

Converts to this type from the input type.

impl<'local> From<JString<'local>> for JObject<'local>

fn from(other: JString<'local>) -> JObject<'local>

Converts to this type from the input type.

impl<'local> Reference for JString<'local>

type Kind<'env> = JString<'env>

The generic associated Self::Kind type corresponds to the underlying class type (such as JObject or JString), parameterized by the lifetime that indicates whether the type holds a global reference ('static) or a local reference that’s tied to a JNI stack frame.

type GlobalKind = JString<'static>

The associated GlobalKind type should be equivalent to Kind<'static>, with the additional bound that ensures the type is Send + Sync

fn as_raw(&self) -> jobject

Returns the underlying, raw crate::sys::jobject reference.

fn class_name() -> Cow<'static, JNIStr>

The fully qualified class name of the Java class represented by this reference.

fn lookup_class<'caller>( env: &Env<'_>, loader_context: &LoaderContext<'_, '_>, ) -> Result<impl Deref<Target = Global<JClass<'static>>> + 'caller>

Looks up a global reference to the JClass associated with this reference.

unsafe fn kind_from_raw<'env>(local_ref: jobject) -> Self::Kind<'env>

Returns a new reference type based on Self::Kind for the given reference that is tied to the specified lifetime.

unsafe fn global_kind_from_raw(global_ref: jobject) -> Self::GlobalKind

Returns a ('static) reference type based on Self::GlobalKind for the given global_ref.

fn is_null(&self) -> bool

Returns true if this is a null object reference

fn null<'any>() -> Self::Kind<'any>

Returns null reference based on Self::Kind