## 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