Deukhoofd
/
Angelscript
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Angelscript/docs/manual/doc_strings.html

149 lines
15 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.18"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>AngelScript: Custom string type</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">AngelScript
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.18 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('doc_strings.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Custom string type </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Almost all applications have some need to manipulate text strings in one way or another. However most applications have very different needs, and also different ways of representing their string types. For that reason, AngelScript doesn't come with its own built-in string type that the application would be forced to adapt to, instead AngelScript allows the application to <a class="el" href="doc_register_api.html">register its own string type</a>.</p>
<p>This article presents the options for customizing the script language to the application's needs with regards to strings. If you do not want, or do not need to have AngelScript use your own string type, then I suggest you use the standard add-on for <a class="el" href="doc_addon_std_string.html">std::string registration</a>.</p>
<h1><a class="anchor" id="doc_string_register"></a>
Registering the custom string type</h1>
<p>To make the script language support strings, the string type must first be <a class="el" href="doc_register_type.html">registered as type</a> with the engine. The application is free to use any valid type name, not necessarily 'string', though it is probably the most commonly used name. The custom string type can also be either value type or a reference type at the preference of the application developer.</p>
<p>Once the string type is registered, the application must also provide a string factory to allow the scripts to use literal string constants. The string factory must implement the <a class="el" href="classas_i_string_factory.html">asIStringFactory</a> interface, and be registered with the <a class="el" href="classas_i_script_engine.html#ac6598c07c36652b0270b4c2d61db1f01">asIScriptEngine::RegisterStringFactory</a> method.</p>
<p>The string factory must implement all 3 methods of the <a class="el" href="classas_i_string_factory.html" title="The interface for the string factory.">asIStringFactory</a> interface. The <a class="el" href="classas_i_string_factory.html#a59d5d4d13a21105791e34bef5cb57e6b">GetStringConstant</a> method receives the raw string data by the compiler and should return a pointer to the custom string object that represents that string. The <a class="el" href="classas_i_string_factory.html#ae4ca9e666eb711671a765dba8debe8b1">ReleaseStringConstant</a> is called when the engine no longer needs the string constant, e.g. when discarding a module. The <a class="el" href="classas_i_string_factory.html#ae798179f4d90b30371416f8c5c522333">GetRawStringData</a> is called by the engine when the raw string data is needed, e.g. when saving bytecode or when requesting a copy of a string constant.</p>
<p>Although not necessary, the application should preferably implement caching of the string constants, so that if two calls to GetStringConstant with the same raw string data is received the string factory returns the address of the same string instance in both calls. This will reduce the amount of memory needed to store the string constants, especially when scripts use the same string constants in many places. Remember, when using caching, the ReleaseStringConstant must only free the string object when the last call for that same object is done.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_addon_std_string.html">The standard string add-on</a></dd></dl>
<h1><a class="anchor" id="doc_strings_1"></a>
Unicode vs ASCII</h1>
<p>Is your application using Unicode or plain ASCII for the text? If you use Unicode, then you'll want to encode the scripts in UTF-8, which the AngelScript compiler supports natively. By default AngelScript expects the scripts to have been encoded in UTF-8, but should you prefer ASCII you can turn this off by setting the engine property <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a> to 0 right after creating the engine.</p>
<div class="fragment"><div class="line"><span class="comment">// Set engine to use ASCII scanner for script code</span></div>
<div class="line">engine-&gt;<a class="code" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a>, 0);</div>
</div><!-- fragment --><p>If you do use Unicode, then you'll also want to choose the desired encoding for the string literals, either UTF-8 or UTF-16. By default the string literals in AngelScript are encoded with UTF-8, but if your application is better prepared for UTF-16 then you'll want to change this by setting the engine property <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab6daa2ae0c712da7f6f16d698305fba1">asEP_STRING_ENCODING</a> to 1 before compiling your scripts.</p>
<div class="fragment"><div class="line"><span class="comment">// Set engine to use UTF-16 encoding for string literals</span></div>
<div class="line">engine-&gt;<a class="code" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab6daa2ae0c712da7f6f16d698305fba1">asEP_STRING_ENCODING</a>, 1);</div>
</div><!-- fragment --><p>Observe that the <a class="el" href="classas_i_script_engine.html#ac6598c07c36652b0270b4c2d61db1f01">string factory</a> called by the engine to create new strings gives the size of the string data in bytes even for UTF-16 encoded strings, so you'll need to divide the size by two to get the number of characters in the string.</p>
<h1><a class="anchor" id="doc_string_2"></a>
Multiline string literals</h1>
<p>There is also a couple of options that affect the script language itself a bit. If you like the convenience of allowing string literals to span multiple lines of code, then you can turn this on by setting the engine property <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa218fdf7e181bf9ee0498112f5a87c415">asEP_ALLOW_MULTILINE_STRINGS</a> to true. Without this the compiler will give an error if it encounters a line break before the end of the string.</p>
<div class="fragment"><div class="line"><span class="comment">// Set engine to allow string literals with line breaks</span></div>
<div class="line">engine-&gt;<a class="code" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa218fdf7e181bf9ee0498112f5a87c415">asEP_ALLOW_MULTILINE_STRINGS</a>, <span class="keyword">true</span>);</div>
</div><!-- fragment --><p>Observe that the line ending encoding of the source file will not be modified by the script compiler, so depending on how the file has been saved, you may get strings using different line endings.</p>
<p>The <a class="el" href="doc_datatypes_strings.html">heredoc strings</a> are not affected by this setting, as they are designed to support multiline text sections.</p>
<h1><a class="anchor" id="doc_string_3"></a>
Character literals</h1>
<p>By default AngelScript doesn't have character literals as C and C++ does. A string literal can be written with double quotes or single quotes and still have the same meaning. This makes it convenient to embed scripts in XML files or C/C++ source files where double quotes would otherwise end the script code.</p>
<p>If you want to have single quoted literals mean a single character literal instead of a string, then you can do so by setting the engine property <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6dc1c33f9227c66f18fc0f95a0c798b2">asEP_USE_CHARACTER_LITERALS</a> to true. The compiler will then convert single quoted literals to an integer number representing the first character.</p>
<div class="fragment"><div class="line"><span class="comment">// Set engine to use character literals </span></div>
<div class="line">engine-&gt;<a class="code" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6dc1c33f9227c66f18fc0f95a0c798b2">asEP_USE_CHARACTER_LITERALS</a>, <span class="keyword">true</span>);</div>
</div><!-- fragment --><p>Observe that the <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a> property has great importance in this case, as an ASCII character can only represent values between 0 and 255, whereas a Unicode character can represent values between 0 and 1,114,111. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<div class="ttc" id="aangelscript_8h_html_a53c2e8a74ade77c928316396394ebe0fab6daa2ae0c712da7f6f16d698305fba1"><div class="ttname"><a href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fab6daa2ae0c712da7f6f16d698305fba1">asEP_STRING_ENCODING</a></div><div class="ttdeci">@ asEP_STRING_ENCODING</div><div class="ttdoc">Select string encoding for literals: 0 - UTF8/ASCII, 1 - UTF16. Default: 0 (UTF8)</div><div class="ttdef"><b>Definition:</b> angelscript.h:180</div></div>
<div class="ttc" id="aangelscript_8h_html_a53c2e8a74ade77c928316396394ebe0fa6dc1c33f9227c66f18fc0f95a0c798b2"><div class="ttname"><a href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa6dc1c33f9227c66f18fc0f95a0c798b2">asEP_USE_CHARACTER_LITERALS</a></div><div class="ttdeci">@ asEP_USE_CHARACTER_LITERALS</div><div class="ttdoc">Interpret single quoted strings as character literals. Default: false.</div><div class="ttdef"><b>Definition:</b> angelscript.h:164</div></div>
<div class="ttc" id="aangelscript_8h_html_a53c2e8a74ade77c928316396394ebe0fa218fdf7e181bf9ee0498112f5a87c415"><div class="ttname"><a href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa218fdf7e181bf9ee0498112f5a87c415">asEP_ALLOW_MULTILINE_STRINGS</a></div><div class="ttdeci">@ asEP_ALLOW_MULTILINE_STRINGS</div><div class="ttdoc">Allow linebreaks in string constants. Default: false.</div><div class="ttdef"><b>Definition:</b> angelscript.h:166</div></div>
<div class="ttc" id="aclassas_i_script_engine_html_a1bce4e5f573a2ca0ff55163e28f761dd"><div class="ttname"><a href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">asIScriptEngine::SetEngineProperty</a></div><div class="ttdeci">virtual int SetEngineProperty(asEEngineProp property, asPWORD value)=0</div><div class="ttdoc">Dynamically change some engine properties.</div></div>
<div class="ttc" id="aangelscript_8h_html_a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2"><div class="ttname"><a href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0fa02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a></div><div class="ttdeci">@ asEP_SCRIPT_SCANNER</div><div class="ttdoc">Select scanning method: 0 - ASCII, 1 - UTF8. Default: 1 (UTF8).</div><div class="ttdef"><b>Definition:</b> angelscript.h:176</div></div>
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on Sat Dec 5 2020 23:20:25 for AngelScript by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink