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; 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_from_utf16 (gunichar2 *data); mono_unichar2* mono_string_to_utf16 (MonoString *s); char* mono_string_to_utf8 (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); gunichar2* mono_unicode_from_external (const gchar *in, gsize *bytes);

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
MonoString* mono_string_new (MonoDomain *domain, const char *text)

Parameters

text:
a pointer to an utf8 string
Returns
A newly created string object which contains text.
mono_string_new_len
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
Returns
A newly created string object which contains text.
mono_string_new_size
MonoString* mono_string_new_size (MonoDomain *domain, gint32 len)

Parameters

text:
a pointer to an utf16 string
len:
the length of the string
Returns
A newly created string object of len
mono_string_new_utf16
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
Returns
A newly created string object which contains text.
mono_string_from_utf16
MonoString* mono_string_from_utf16 (gunichar2 *data)

Parameters

data:
the UTF16 string (LPWSTR) to convert
Returns
a MonoString.
Remarks

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

Conversions

mono_string_to_utf16
mono_unichar2* mono_string_to_utf16 (MonoString *s)

Parameters

s:
a MonoString
Remarks

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
char* mono_string_to_utf8 (MonoString *s)

Parameters

s:
a System.String
Remarks

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.

Methods

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

Parameters

s1:
First string to compare
s2:
Second string to compare
Remarks

Returns FALSE if the strings differ.

mono_string_hash
guint mono_string_hash (MonoString *s)

Parameters

s:
the string to hash
Remarks

Returns the hash for the string.

mono_string_intern
MonoString* mono_string_intern (MonoString *str)

Parameters

o:
String to intern
Returns
The interned string.
Remarks

Interns the string passed.

mono_string_is_interned
MonoString* mono_string_is_interned (MonoString *o)

Parameters

o:
String to probe
Remarks

Returns whether the string has been interned.

mono_string_new_wrapper
MonoString* mono_string_new_wrapper (const char *text)

Parameters

text:
pointer to utf8 characters.
Remarks

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

mono_string_chars
gunichar2* mono_string_chars (MonoString *s)

Parameters

s:
a MonoString
Remarks

Returns a pointer to the UCS16 characters stored in the MonoString

mono_string_length
int mono_string_length (MonoString *s)

Parameters

s:
MonoString
Remarks

Returns the lenght in characters of the string

Other Encodings

These routines are used when coping with strings that come from Mono's environment, and might be encoded in one or more of the external encodings.

For example, some file systems might historically contain a mix of file names with both old and new encodings, typically UTF8 for new files, and the old files would be encoded in an 8 bit character set (ISO-8859-1 for example).

These routines try a number of encodings, those specified in the MONO_ENCODINGS environment variable and return unicode strings that can be used internally.

See the mono(1) man page for more details.

mono_unicode_from_external
gunichar2* mono_unicode_from_external (const gchar *in, gsize *bytes)

Parameters

in:
pointers to the buffer.
bytes:
number of bytes in the string.
Remarks

Tries to turn a NULL-terminated string into UTF16. First, see if it's valid UTF8, in which case just turn it directly into UTF16. Next, run through the colon-separated encodings in MONO_EXTERNAL_ENCODINGS and do an iconv conversion on each, returning the first successful conversion to UTF16. If no conversion succeeds, return NULL. Callers must free the returned string if not NULL. bytes holds the number of bytes in the returned string, not including the terminator.

mono_unicode_to_external
gchar*mono_unicode_to_external (const gunichar2 *uni)

Parameters

uni:
an UTF16 string to conver to an external representation.
Remarks

Turns NULL-terminated UTF16 into either UTF8, or the first working item in MONO_EXTERNAL_ENCODINGS if set. If no conversions work, then UTF8 is returned. Callers must free the returned string.