Strings

Strings representation inside the Mono runtime.

Synopsis

#include <metadata/object.h> typedef struct { MonoObject object; gint32 length; gunichar2 chars [0]; } MonoString; MonoString* mono_string_new (MonoDomain *domain, const char *text); MonoString* mono_string_new_len (MonoDomain *domain, const char *text, guint length); MonoString* mono_string_new_size (MonoDomain *domain, gint32 len); MonoString* mono_string_new_utf16 (MonoDomain *domain, const guint16 *text, gint32 len); MonoString* mono_string_new_utf32 (MonoDomain *domain, const mono_unichar4 *text, gint32 len); MonoString* mono_string_from_utf16 (gunichar2 *data); MonoString* mono_string_from_utf32 (mono_unichar4 *data); mono_unichar2* mono_string_to_utf16 (MonoString *s); char* mono_string_to_utf8 (MonoString *s); char* mono_string_to_utf8_checked (MonoString *s, MonoError *error); mono_unichar4* mono_string_to_utf32 (MonoString *s); gboolean mono_string_equal (MonoString *s1, MonoString *s2); guint mono_string_hash (MonoString *s); MonoString* mono_string_intern (MonoString *str); MonoString* mono_string_is_interned (MonoString *o); MonoString* mono_string_new_wrapper (const char *text); gunichar2* mono_string_chars (MonoString *s); int mono_string_length (MonoString *s);

All of the operations on strings are done on pointers to `MonoString` objects, like this:

MonoString *hello = mono_string_new (mono_domain_get (), "hello, world");

Strings are bound to a particular application domain, which is why it is necessary to pass a MonoDomain argument as the first parameter to all the constructor functions.

Typically, you want to create the strings on the current application domain, so a call to mono_domain_get() is sufficient.

Constructors

mono_string_new
Syntax
MonoString* mono_string_new (MonoDomain *domain, const char *text)

Parameters
text a pointer to an utf8 string
Return value
A newly created string object which contains text.

This function asserts if it cannot allocate a new string.

deprecated Use mono_string_new_checked in new code.

Description

mono_string_new_len
Syntax
MonoString* mono_string_new_len (MonoDomain *domain, const char *text, guint length)

Parameters
text a pointer to an utf8 string
length number of bytes in text to consider
Return value
A newly created string object which contains text.
Description

mono_string_new_size
Syntax
MonoString* mono_string_new_size (MonoDomain *domain, gint32 len)

Parameters
text a pointer to an utf16 string
len the length of the string
Return value
A newly created string object of len
Description

mono_string_new_utf16
Syntax
MonoString* mono_string_new_utf16 (MonoDomain *domain, const guint16 *text, gint32 len)

Parameters
text a pointer to an utf16 string
len the length of the string
Return value
A newly created string object which contains text.
Description

mono_string_new_utf32
Syntax
MonoString* mono_string_new_utf32 (MonoDomain *domain, const mono_unichar4 *text, gint32 len)

Parameters
text a pointer to an utf32 string
len the length of the string
Return value
A newly created string object which contains text.
Description

mono_string_from_utf16
Syntax
MonoString* mono_string_from_utf16 (gunichar2 *data)

Parameters
data the UTF16 string (LPWSTR) to convert
Return value
a MonoString.
Description

Converts a NULL terminated UTF16 string (LPWSTR) to a MonoString.

mono_string_from_utf32
Syntax
MonoString* mono_string_from_utf32 (mono_unichar4 *data)

Parameters
data the UTF32 string (LPWSTR) to convert
Return value
a MonoString.
Description

Converts a UTF32 (UCS-4)to a MonoString.

Conversions

mono_string_to_utf16
Syntax
mono_unichar2* mono_string_to_utf16 (MonoString *s)

Parameters
s a MonoString
Description

Return an null-terminated array of the utf-16 chars contained in s. The result must be freed with g_free(). This is a temporary helper until our string implementation is reworked to always include the null terminating char.

mono_string_to_utf8
Syntax
char* mono_string_to_utf8 (MonoString *s)

Parameters
s a System.String
Description

Returns the UTF8 representation for s. The resulting buffer needs to be freed with mono_free().

deprecated Use mono_string_to_utf8_checked to avoid having an exception arbritraly raised.

mono_string_to_utf8_checked
Syntax
char* mono_string_to_utf8_checked (MonoString *s, MonoError *error)

Parameters
s a System.String
error a MonoError.
Description

Converts a MonoString to its UTF8 representation. May fail; check error to determine whether the conversion was successful. The resulting buffer should be freed with mono_free().

mono_string_to_utf32
Syntax
mono_unichar4* mono_string_to_utf32 (MonoString *s)

Parameters
s a MonoString
Description

Return an null-terminated array of the UTF-32 (UCS-4) chars contained in s. The result must be freed with g_free().

Methods

mono_string_equal
Syntax
gboolean mono_string_equal (MonoString *s1, MonoString *s2)

Parameters
s1 First string to compare
s2 Second string to compare
Description

Compares two MonoString* instances ordinally for equality.

Returns FALSE if the strings differ.

mono_string_hash
Syntax
guint mono_string_hash (MonoString *s)

Parameters
s the string to hash
Description

Compute the hash for a MonoString* Returns the hash for the string.

mono_string_intern
Syntax
MonoString* mono_string_intern (MonoString *str)

Parameters
o String to intern
Return value
The interned string.
Description

Interns the string passed.

mono_string_is_interned
Syntax
MonoString* mono_string_is_interned (MonoString *o)

Parameters
o String to probe
Description

Returns whether the string has been interned.

mono_string_new_wrapper
Syntax
MonoString* mono_string_new_wrapper (const char *text)

Parameters
text pointer to utf8 characters.
Description

Helper function to create a string object from text in the current domain.

mono_string_chars
Syntax
gunichar2* mono_string_chars (MonoString *s)

Parameters
s a MonoString
Description

Returns a pointer to the UCS16 characters stored in the MonoString