mono-api-string.html

## Strings

Strings representation inside the Mono runtime.

### Synopsis

#include <metadata/object.h> typedef struct { MonoObject object; gint32 length; gunichar2 chars [0]; } MonoString;

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 a UTF-8 string

Return value
A newly created string object which contains text.
Description
This function asserts if it cannot allocate a new string.
`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.
`mono_string_new_size`
Syntax
MonoString* mono_string_new_size (MonoDomain *domain, gint32 len)

Parameters

text | a pointer to a UTF-16 string
len | the length of the string

Return value
A newly created string object of len
`mono_string_new_utf16`
Syntax
MonoString* mono_string_new_utf16 (MonoDomain *domain, const mono_unichar2 *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.
`mono_string_new_utf32`
Syntax
MonoString* mono_string_new_utf32 (MonoDomain *domain, const mono_unichar4 *text, gint32 len)

Parameters

text | a pointer to a UTF-32 string
len | the length of the string

Return value
A newly created string object which contains text.
`mono_string_from_utf16`
Syntax
MonoString* mono_string_from_utf16 (gunichar2 *data)

Parameters

data | the UTF-16 string (LPWSTR) to convert

Return value
a `MonoString`.
Description
Converts a `NULL`-terminated UTF-16 string (LPWSTR) to a `MonoString`.
`mono_string_from_utf32`
Syntax
MonoString* mono_string_from_utf32 (/*const*/ mono_unichar4 *data)

Parameters

data | the UTF-32 string (LPWSTR) to convert

Return value
a `MonoString`.
Description
Converts a UTF-32 (UCS-4) string to a `MonoString`.

### Conversions

`mono_string_to_utf16`
Syntax
mono_unichar2* mono_string_to_utf16 (MonoString *string_obj)

Parameters

s | a `MonoString`

Return value
a 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`
Deprecated: Use `mono_string_to_utf8_checked_internal` to avoid having an exception arbitrarily raised.
Syntax
char* mono_string_to_utf8 (MonoString *s)

Parameters

s | a `System.String`

Return value
the UTF-8 representation for s. The resulting buffer needs to be freed with `mono_free()`.
`mono_string_to_utf8_checked`
Syntax
char* mono_string_to_utf8_checked (MonoString *string_obj, MonoError *error)

Parameters

s | a `System.String`
error | a `MonoError`.

Description
Converts a `MonoString` to its UTF-8 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 *string_obj)

Parameters

s | a `MonoString`

Return value
a 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

Return value
`FALSE` if the strings differ.
Description

Compares two `MonoString*` instances ordinally for equality.

`mono_string_hash`
Syntax
guint mono_string_hash (MonoString *s)

Parameters

s | the string to hash

Return value
the hash for the string.
Description

Compute the hash for a `MonoString*`
`mono_string_intern`
Syntax
MonoString* mono_string_intern (MonoString *str_raw)

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 *str_raw)

Parameters

o | String to probe

Return value
Whether the string has been interned.
`mono_string_new_wrapper`
Syntax
MonoString* mono_string_new_wrapper (const char *text)

Parameters

text | pointer to UTF-8 characters.

Description
Helper function to create a string object from text in the current domain.
`mono_string_chars`
Syntax
mono_unichar2* mono_string_chars (MonoString *s)

Parameters

s | a `MonoString`

Return value
a pointer to the UTF-16 characters stored in the `MonoString`