<?xml version="1.0" encoding="us-ascii"?><span>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>mono-api-string.html</title>
<style type="text/css">
h3 {
font-size: 18px;
padding-bottom: 4pt;
border-bottom: 2px solid #dddddd;
}
.api {
border: 1px solid;
padding: 10pt;
margin: 10pt;
}
.api-entry {
border-bottom: none;
font-size: 18px;
}
.prototype {
border: 1px solid;
background-color: #f2f2f2;
padding: 5pt;
margin-top: 5pt;
margin-bottom: 5pt;
}
.header {
border: 1px solid;
padding: 0 0 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
}
.code {
border: 1px solid;
padding: 0 0 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
}
</style>
</head>
<body>
<h2>Strings</h2>
<p />Strings representation inside the Mono runtime.
<h3>Synopsis</h3>
<div class="header">
#include <metadata/object.h>
typedef struct {
MonoObject object;
gint32 length;
gunichar2 chars [0];
} MonoString;
MonoString* <a href="#api:mono_string_new">mono_string_new</a> (MonoDomain *domain,
const char *text);
MonoString* <a href="#api:mono_string_new_len">mono_string_new_len</a> (MonoDomain *domain,
const char *text,
guint length);
MonoString* <a href="#api:mono_string_new_size">mono_string_new_size</a> (MonoDomain *domain,
gint32 len);
MonoString* <a href="#api:mono_string_new_utf16">mono_string_new_utf16</a> (MonoDomain *domain,
const guint16 *text,
gint32 len);
MonoString* <a href="#api:mono_string_from_utf16">mono_string_from_utf16</a> (gunichar2 *data);
void <a href="#api:mono_string_to_byvalstr">mono_string_to_byvalstr</a> (gpointer dst,
MonoString *src,
int size);
void <a href="#api:mono_string_to_byvalwstr">mono_string_to_byvalwstr</a> (gpointer dst,
MonoString *src,
int size);
gunichar2* <a href="#api:mono_string_to_utf16">mono_string_to_utf16</a> (MonoString *s);
char* <a href="#api:mono_string_to_utf8">mono_string_to_utf8</a> (MonoString *s);
<a href="#api:mono_string_utf16_to_builder"></a>
<a href="#api:mono_string_utf8_to_builder"></a>
gboolean <a href="#api:mono_string_equal">mono_string_equal</a> (MonoString *s1,
MonoString *s2);
guint <a href="#api:mono_string_hash">mono_string_hash</a> (MonoString *s);
MonoString* <a href="#api:mono_string_intern">mono_string_intern</a> (MonoString *str);
MonoString* <a href="#api:mono_string_is_interned">mono_string_is_interned</a> (MonoString *o);
MonoString* <a href="#api:mono_string_new_wrapper">mono_string_new_wrapper</a> (const char *text);
<a href="#api:mono_string_chars"></a>
int <a href="#api:mono_string_length">mono_string_length</a> (MonoString *s);
gpointer <a href="#api:mono_string_builder_to_utf16">mono_string_builder_to_utf16</a> (MonoStringBuilder *sb);
gpointer <a href="#api:mono_string_builder_to_utf8">mono_string_builder_to_utf8</a> (MonoStringBuilder *sb);
gunichar2* <a href="#api:mono_unicode_from_external">mono_unicode_from_external</a> (const gchar *in,
gsize *bytes);
<a href="#api:mono_unicode_to_external"></a>
<a href="#api:mono_utf8_from_external"></a>
</div>
<p />All of the operations on strings are done on pointers to
MonoString objects, like this:
<div class="code">
MonoString *hello = mono_string_new (mono_domain_get (), "hello, world");
</div>
<p />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.
<p />Typically, you want to create the strings on the current
application domain, so a call to <tt>mono_domain_get()</tt> is
sufficient.
<h3>Constructors</h3>
<a name="api:mono_string_new"></a>
<div class="api">
<div class="api-entry">mono_string_new</div>
<div class="prototype">MonoString*
mono_string_new (MonoDomain *domain, const char *text)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>text:</i></dt><dd> a pointer to an utf8 string</dd></blockquote>
<b>Returns</b>
<blockquote> A newly created string object which contains <i>text</i>.
</blockquote>
</div> <a name="api:mono_string_new_len"></a>
<div class="api">
<div class="api-entry">mono_string_new_len</div>
<div class="prototype">MonoString*
mono_string_new_len (MonoDomain *domain, const char *text, guint length)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>text:</i></dt><dd> a pointer to an utf8 string</dd><dt><i>length:</i></dt><dd> number of bytes in <i>text</i> to consider</dd></blockquote>
<b>Returns</b>
<blockquote> A newly created string object which contains <i>text</i>.
</blockquote>
</div> <a name="api:mono_string_new_size"></a>
<div class="api">
<div class="api-entry">mono_string_new_size</div>
<div class="prototype">MonoString*
mono_string_new_size (MonoDomain *domain, gint32 len)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>text:</i></dt><dd> a pointer to an utf16 string</dd><dt><i>len:</i></dt><dd> the length of the string</dd></blockquote>
<b>Returns</b>
<blockquote> A newly created string object of <i>len</i>
</blockquote>
</div> <a name="api:mono_string_new_utf16"></a>
<div class="api">
<div class="api-entry">mono_string_new_utf16</div>
<div class="prototype">MonoString*
mono_string_new_utf16 (MonoDomain *domain, const guint16 *text, gint32 len)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>text:</i></dt><dd> a pointer to an utf16 string</dd><dt><i>len:</i></dt><dd> the length of the string</dd></blockquote>
<b>Returns</b>
<blockquote> A newly created string object which contains <i>text</i>.
</blockquote>
</div> <a name="api:mono_string_from_utf16"></a>
<div class="api">
<div class="api-entry">mono_string_from_utf16</div>
<div class="prototype">MonoString*
mono_string_from_utf16 (gunichar2 *data)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>data:</i></dt><dd> the UTF16 string (LPWSTR) to convert</dd></blockquote>
<b>Returns</b>
<blockquote> a MonoString.
</blockquote>
<b>Remarks</b>
<p />
Converts a NULL terminated UTF16 string (LPWSTR) to a MonoString.
</div><h3>Conversions</h3>
<a name="api:mono_string_to_byvalstr"></a>
<div class="api">
<div class="api-entry">mono_string_to_byvalstr</div>
<div class="prototype">void
mono_string_to_byvalstr (gpointer dst, MonoString *src, int size)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>dst:</i></dt><dd> Where to store the null-terminated utf8 decoded string.</dd><dt><i>src:</i></dt><dd> the MonoString to copy.</dd><dt><i>size:</i></dt><dd> the maximum number of bytes to copy.</dd></blockquote>
<b>Remarks</b>
<p />
Copies the MonoString pointed to by <i>src</i> as a utf8 string
into <i>dst</i>, it copies at most <i>size</i> bytes into the destination.
</div> <a name="api:mono_string_to_byvalwstr"></a>
<div class="api">
<div class="api-entry">mono_string_to_byvalwstr</div>
<div class="prototype">void
mono_string_to_byvalwstr (gpointer dst, MonoString *src, int size)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>dst:</i></dt><dd> Where to store the null-terminated utf16 decoded string.</dd><dt><i>src:</i></dt><dd> the MonoString to copy.</dd><dt><i>size:</i></dt><dd> the maximum number of bytes to copy.</dd></blockquote>
<b>Remarks</b>
<p />
Copies the MonoString pointed to by <i>src</i> as a utf16 string into
<i>dst</i>, it copies at most <i>size</i> bytes into the destination (including
a terminating 16-bit zero terminator).
</div> <a name="api:mono_string_to_utf16"></a>
<div class="api">
<div class="api-entry">mono_string_to_utf16</div>
<div class="prototype">gunichar2*
mono_string_to_utf16 (MonoString *s)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s:</i></dt><dd> a MonoString</dd></blockquote>
<b>Remarks</b>
<p />
Return an null-terminated array of the utf-16 chars
contained in <i>s</i>. 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.
</div> <a name="api:mono_string_to_utf8"></a>
<div class="api">
<div class="api-entry">mono_string_to_utf8</div>
<div class="prototype">char*
mono_string_to_utf8 (MonoString *s)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s:</i></dt><dd> a System.String</dd></blockquote>
<b>Remarks</b>
<p />
Return the UTF8 representation for <i>s</i>.
the resulting buffer nedds to be freed with g_free().
</div> <a name="api:mono_string_utf16_to_builder"></a>
<div class="api">
<div class="api-entry">mono_string_utf16_to_builder</div>
<div class="prototype">Prototype: mono_string_utf16_to_builder</div>
<p />
</div> <a name="api:mono_string_utf8_to_builder"></a>
<div class="api">
<div class="api-entry">mono_string_utf8_to_builder</div>
<div class="prototype">Prototype: mono_string_utf8_to_builder</div>
<p />
</div><h3>Methods</h3>
<a name="api:mono_string_equal"></a>
<div class="api">
<div class="api-entry">mono_string_equal</div>
<div class="prototype">gboolean
mono_string_equal (MonoString *s1, MonoString *s2)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s1:</i></dt><dd> First string to compare</dd><dt><i>s2:</i></dt><dd> Second string to compare</dd></blockquote>
<b>Remarks</b>
<p />
Returns FALSE if the strings differ.
</div> <a name="api:mono_string_hash"></a>
<div class="api">
<div class="api-entry">mono_string_hash</div>
<div class="prototype">guint
mono_string_hash (MonoString *s)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s:</i></dt><dd> the string to hash</dd></blockquote>
<b>Remarks</b>
<p />
Returns the hash for the string.
</div> <a name="api:mono_string_intern"></a>
<div class="api">
<div class="api-entry">mono_string_intern</div>
<div class="prototype">MonoString*
mono_string_intern (MonoString *str)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>o:</i></dt><dd> String to intern</dd></blockquote>
<b>Returns</b>
<blockquote> The interned string.
</blockquote>
<b>Remarks</b>
<p />
Interns the string passed.
</div> <a name="api:mono_string_is_interned"></a>
<div class="api">
<div class="api-entry">mono_string_is_interned</div>
<div class="prototype">MonoString*
mono_string_is_interned (MonoString *o)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>o:</i></dt><dd> String to probe</dd></blockquote>
<b>Remarks</b>
<p />
Returns whether the string has been interned.
</div> <a name="api:mono_string_new_wrapper"></a>
<div class="api">
<div class="api-entry">mono_string_new_wrapper</div>
<div class="prototype">MonoString*
mono_string_new_wrapper (const char *text)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>text:</i></dt><dd> pointer to utf8 characters.</dd></blockquote>
<b>Remarks</b>
<p />
Helper function to create a string object from <i>text</i> in the current domain.
</div> <a name="api:mono_string_chars"></a>
<div class="api">
<div class="api-entry">mono_string_chars</div>
<div class="prototype">gunichar2*
mono_string_chars(MonoString *s)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s:</i></dt><dd> a MonoString</dd></blockquote>
<b>Remarks</b>
<p />
Returns a pointer to the UCS16 characters stored in the MonoString
</div> <a name="api:mono_string_length"></a>
<div class="api">
<div class="api-entry">mono_string_length</div>
<div class="prototype">int
mono_string_length (MonoString *s)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>s:</i></dt><dd> MonoString</dd></blockquote>
<b>Remarks</b>
<p />
Returns the lenght in characters of the string
</div><h3>String Builders</h3>
<p />These routines are used to work with the managed types
<tt>System.Text.StringBuilder</tt>.
<a name="api:mono_string_builder_to_utf16"></a>
<div class="api">
<div class="api-entry">mono_string_builder_to_utf16</div>
<div class="prototype">gpointer
mono_string_builder_to_utf16 (MonoStringBuilder *sb)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>sb:</i></dt><dd> the string builder</dd></blockquote>
<b>Returns</b>
<blockquote> a utf16 string with the contents of the StringBuilder.
The return value must not be freed.</blockquote>
<b>Remarks</b>
<p />
Converts to utf16 the contents of the MonoStringBuilder.
</div> <a name="api:mono_string_builder_to_utf8"></a>
<div class="api">
<div class="api-entry">mono_string_builder_to_utf8</div>
<div class="prototype">gpointer
mono_string_builder_to_utf8 (MonoStringBuilder *sb)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>sb:</i></dt><dd> the string builder</dd></blockquote>
<b>Returns</b>
<blockquote> a utf8 string with the contents of the StringBuilder.
The return value must be released with g_free.</blockquote>
<b>Remarks</b>
<p />
Converts to utf8 the contents of the MonoStringBuilder.
</div><h3>Other Encodings</h3>
<p />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.
<p />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).
<p />These routines try a number of encodings, those specified
in the <tt>MONO_ENCODINGS</tt> environment variable and return
unicode strings that can be used internally.
<p />See the mono(1) man page for more details.
<a name="api:mono_unicode_from_external"></a>
<div class="api">
<div class="api-entry">mono_unicode_from_external</div>
<div class="prototype">gunichar2*
mono_unicode_from_external (const gchar *in, gsize *bytes)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>in:</i></dt><dd> pointers to the buffer.</dd><dt><i>bytes:</i></dt><dd> number of bytes in the string.</dd></blockquote>
<b>Remarks</b>
<p />
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.
</div> <a name="api:mono_unicode_to_external"></a>
<div class="api">
<div class="api-entry">mono_unicode_to_external</div>
<div class="prototype">gchar*mono_unicode_to_external (const gunichar2 *uni)
</div>
<p />
<b>Parameters</b>
<blockquote><dt><i>uni:</i></dt><dd> an UTF16 string to conver to an external representation.</dd></blockquote>
<b>Remarks</b>
<p />
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.
</div></body>
</html>
</span>
distrib
>
Mandriva
>
2009.1
>
x86_64
>
media
>
main-backports
>
by-pkgid
>
ec081eb1f0fb87b7640153d3a3340fac
>
files
>
69
