mono-api-string.html
   
Strings
	Strings representation inside the Mono runtime.
Synopsis
	
	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 stringlength: 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 stringlen: 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 stringlen: 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 compares2: 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.