405 lines
12 KiB
HTML
405 lines
12 KiB
HTML
<?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);
|
|
mono_unichar2* <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);
|
|
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);
|
|
gunichar2* <a href="#api:mono_string_chars">mono_string_chars</a> (MonoString *s);
|
|
int <a href="#api:mono_string_length">mono_string_length</a> (MonoString *s);
|
|
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_utf16"></a>
|
|
<div class="api">
|
|
<div class="api-entry">mono_string_to_utf16</div>
|
|
|
|
<div class="prototype">mono_unichar2*
|
|
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 />
|
|
Returns the UTF8 representation for <i>s</i>.
|
|
The resulting buffer needs to be freed with mono_free().
|
|
|
|
<i>deprecated</i> Use mono_string_to_utf8_checked to avoid having an exception arbritraly raised.
|
|
|
|
|
|
</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>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> |