<?xml version="1.0" encoding="utf-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>mono-api-string.html</title>
<style type="text/css">
.mapi-docs {
line-height: 1.5;
padding-left: 2em;
padding-right: 2em;
}
.mapi-docs p {
max-width: 60em;
}
.mapi-docs .mapi-body {
max-width: 60em;
}
.mapi-docs code {
border: 1px solid rgba(214,214,214,1);
background-color: rgba(249,249,249,1);
padding: 0.1em 0.5em;
}
.mapi-description code {
font-family: "Consolas", "Courier", monospace;
border: 1px solid rgba(214,214,214,1);
background-color: rgba(249,249,249,1);
padding: 0.1em 0.2em;
}
.mapi-header {
padding: 0 0 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
border: 1px solid rgba(233,233,233,1);
background-color: rgba(249,249,249,1);
}
.mapi-code {
padding: 5pt 5pt;
margin: 10pt;
white-space: pre;
font-family: monospace;
border: 1px solid rgba(233,233,233,1);
background-color: rgba(249,249,249,1);
}
.mapi-code:first-line {
line-height: 0px;
}
.mapi-entry code {
border: none;
background-color: transparent;
}
.mapi-parameters {
border-collapse: collapse;
border-spacing: 0;
empty-cells: hide;
border: 0;
margin: 5px 0 26px;
}
.mapi-parameters td {
border: 1px solid rgba(214,214,214,1);
border-left-style: none;
padding: 5px 25px 5px 10px;
}
.mapi-parameters tr>td:last-child {
border-right: 0;
}
.mapi-parameters td:first-of-type {
text-align: right;
padding: 7px;
vertical-align: top;
word-break: normal;
width: 40px;
}
.mapi-parameters tr:last-child>td {
border-bottom: 0;
}
.mapi-parameters tr:first-child>td {
border-top: 0;
}
.mapi-parameters tr td:first-of-type {
text-align: right;
padding: 7px;
vertical-align: top;
word-break: normal;
width: 40px;
}
.mapi {
left: -25px;
margin: 0;
padding: 13px 25px 0;
position: relative;
width: 100%;
}
.mapi-description {
background: rgba(249,249,249,1);
border-bottom: 1px solid rgba(233,233,233,1);
left: -25px;
margin: 0;
padding: 13px 25px 0;
position: relative;
width: 100%;
}
.mapi-entry {
background: transparent;
}
.mapi-docs {
}
.mapi-prototype {
border-left: 5px solid rgba(205,233,244,1);
padding: .5em;
margin-top: 5pt;
margin-bottom: 5pt;
font-family: "Consolas", "Courier", monospace;
display: block;
overflow: auto;
background-color: #f9f9f9;
}
.mapi-declaration {
margin-top: 21px;
}
.mapi-section {
font-size: smaller;
font-weight: bold;
margin-top: 21px;
line-height: 1.5;
}
.mapi-strike {
text-decoration: line-through;
}
.mapi-deprecated {
color: red;
}
.mapi-ptr-container {
background: white;
border-bottom: 1px solid rgba(233,233,233,1);
left: -25px;
padding-left: 25px;
padding-right: 25px;
padding-bottom: 13px;
position: relative;
width: 100%;
}
.mapi-ptr {
background: rgba(249,249,249,1);
border-left: 1px solid rgba(233,233,233,1);
border-top: 1px solid rgba(233,233,233,1);
height: 12px;
left: 37px;
top: -7px;
-webkit-transform: rotate(45deg);
-moz-transform: rotate(45deg);
-o-transform: rotate(45deg);
transform: rotate(45deg);
position: absolute;
width: 12px;
}
.mapi-height-container {
left: -25px;
padding: 0 25px;
position: relative;
width: 100%;
}
</style>
</head>
<body>
<div class="mapi-docs">
<h2>Strings</h2>
<p />Strings representation inside the Mono runtime.
<h3>Synopsis</h3>
<div class="mapi-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_new_utf32">mono_string_new_utf32</a> (MonoDomain *domain,
const mono_unichar4 *text,
gint32 len);
MonoString* <a href="#api:mono_string_from_utf16">mono_string_from_utf16</a> (gunichar2 *data);
MonoString* <a href="#api:mono_string_from_utf32">mono_string_from_utf32</a> (mono_unichar4 *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);
char* <a href="#api:mono_string_to_utf8_checked">mono_string_to_utf8_checked</a> (MonoString *s,
MonoError *error);
mono_unichar4* <a href="#api:mono_string_to_utf32">mono_string_to_utf32</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);
</div>
<p />All of the operations on strings are done on pointers to
`MonoString` objects, like this:
<div class="mapi-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="mapi">
<div class="mapi-entry "><code>mono_string_new</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new (MonoDomain *domain, const char *text)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> a pointer to an utf8 string</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> A newly created string object which contains <i>text</i>.
<p />
This function asserts if it cannot allocate a new string.
<p />
<i>deprecated</i> Use mono_string_new_checked in new code.</div>
<div class="mapi-section">Description</div>
<div> <p /> </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_new_len"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_new_len</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new_len (MonoDomain *domain, const char *text, guint length)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> a pointer to an utf8 string</td></td></tr><tr><td><i>length</i><td> number of bytes in <i>text</i> to consider</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> A newly created string object which contains <i>text</i>.
</div>
<div class="mapi-section">Description</div>
<div> <p /> </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_new_size"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_new_size</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new_size (MonoDomain *domain, gint32 len)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> a pointer to an utf16 string</td></td></tr><tr><td><i>len</i><td> the length of the string</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> A newly created string object of <i>len</i>
</div>
<div class="mapi-section">Description</div>
<div> <p /> </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_new_utf16"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_new_utf16</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new_utf16 (MonoDomain *domain, const guint16 *text, gint32 len)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> a pointer to an utf16 string</td></td></tr><tr><td><i>len</i><td> the length of the string</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> A newly created string object which contains <i>text</i>.
</div>
<div class="mapi-section">Description</div>
<div> <p /> </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_new_utf32"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_new_utf32</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new_utf32 (MonoDomain *domain, const mono_unichar4 *text, gint32 len)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> a pointer to an utf32 string</td></td></tr><tr><td><i>len</i><td> the length of the string</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> A newly created string object which contains <i>text</i>.
</div>
<div class="mapi-section">Description</div>
<div> <p /> </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_from_utf16"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_from_utf16</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_from_utf16 (gunichar2 *data)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>data</i><td> the UTF16 string (LPWSTR) to convert</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> a MonoString.
</div>
<div class="mapi-section">Description</div>
<div> <p />
Converts a <code>NULL</code> terminated UTF16 string (LPWSTR) to a MonoString.
<p /></div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_from_utf32"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_from_utf32</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_from_utf32 (mono_unichar4 *data)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>data</i><td> the UTF32 string (LPWSTR) to convert</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> a MonoString.
</div>
<div class="mapi-section">Description</div>
<div> <p />
Converts a UTF32 (UCS-4)to a MonoString.
<p /></div>
</div><!--mapi-description -->
</div><!--height container -->
<h3>Conversions</h3>
</div> <!-- class=mapi -->
<a name="api:mono_string_to_utf16"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_to_utf16</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">mono_unichar2*
mono_string_to_utf16 (MonoString *s)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> a MonoString</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <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>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_to_utf8"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_to_utf8</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">char*
mono_string_to_utf8 (MonoString *s)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> a System.String</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Returns the UTF8 representation for <i>s</i>.
The resulting buffer needs to be freed with mono_free().
<p />
<i>deprecated</i> Use mono_string_to_utf8_checked to avoid having an exception arbritraly raised.</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_to_utf8_checked"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_to_utf8_checked</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">char*
mono_string_to_utf8_checked (MonoString *s, MonoError *error)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> a System.String</td></td></tr><tr><td><i>error</i><td> a MonoError.</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Converts a MonoString to its UTF8 representation. May fail; check
<i>error</i> to determine whether the conversion was successful.
The resulting buffer should be freed with mono_free().</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_to_utf32"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_to_utf32</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">mono_unichar4*
mono_string_to_utf32 (MonoString *s)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> a MonoString</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Return an null-terminated array of the UTF-32 (UCS-4) chars
contained in <i>s</i>. The result must be freed with g_free().</div>
</div><!--mapi-description -->
</div><!--height container -->
<h3>Methods</h3>
</div> <!-- class=mapi -->
<a name="api:mono_string_equal"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_equal</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">gboolean
mono_string_equal (MonoString *s1, MonoString *s2)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s1</i><td> First string to compare</td></td></tr><tr><td><i>s2</i><td> Second string to compare</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Compares two <code>MonoString*</code> instances ordinally for equality.
<p />
Returns <code>FALSE</code> if the strings differ.</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_hash"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_hash</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">guint
mono_string_hash (MonoString *s)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> the string to hash</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Compute the hash for a <code>MonoString*</code>
Returns the hash for the string.</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_intern"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_intern</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_intern (MonoString *str)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>o</i><td> String to intern</td></td></tr></tbody></table> <div class="mapi-section">Return value</div>
<div> The interned string.
</div>
<div class="mapi-section">Description</div>
<div> <p />
Interns the string passed. </div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_is_interned"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_is_interned</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_is_interned (MonoString *o)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>o</i><td> String to probe</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Returns whether the string has been interned.</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_new_wrapper"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_new_wrapper</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">MonoString*
mono_string_new_wrapper (const char *text)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>text</i><td> pointer to utf8 characters.</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Helper function to create a string object from <i>text</i> in the current domain.</div>
</div><!--mapi-description -->
</div><!--height container -->
</div> <!-- class=mapi -->
<a name="api:mono_string_chars"></a>
<div class="mapi">
<div class="mapi-entry "><code>mono_string_chars</code></div>
<div class="mapi-height-container">
<div class="mapi-ptr-container"></div>
<div class="mapi-description">
<div class="mapi-ptr"></div>
<div class="mapi-declaration mapi-section">Syntax</div>
<div class="mapi-prototype">gunichar2*
mono_string_chars (MonoString *s)
</div>
<p />
<div class="mapi-section">Parameters</div>
<table class="mapi-parameters"><tbody><tr><td><i>s</i><td> a MonoString</td></td></tr></tbody></table> <div class="mapi-section">Description</div>
<div> <p />
Returns a pointer to the UCS16 characters stored in the MonoString</div>
</div><!--mapi-description -->
</div><!--height container -->
</div>
</div></body>
</html>