PageRenderTime 26ms CodeModel.GetById 13ms app.highlight 7ms RepoModel.GetById 2ms app.codeStats 0ms

/xbmc/visualizations/Vortex/angelscript/docs/manual/doc_strings.html

http://github.com/xbmc/xbmc
HTML | 39 lines | 38 code | 0 blank | 1 comment | 0 complexity | 498cc8fadf29d4d9e99d2b763a8daf8d MD5 | raw file
 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
 3<title>AngelScript: The string type</title>
 4<link href="tabs.css" rel="stylesheet" type="text/css">
 5<link href="doxygen.css" rel="stylesheet" type="text/css">
 6</head><body>
 7<!-- Generated by Doxygen 1.5.9 -->
 8<div class="contents">
 9<h1><a class="anchor" name="doc_strings">The string type </a></h1>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>
10This 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 one of the standard string add-ons, either the <a class="el" href="doc_addon_std_string.html">std::string registration</a>, or the <a class="el" href="doc_addon_string.html">reference counted string type</a>.<h2><a class="anchor" name="doc_strings_1">
11Unicode vs ASCII</a></h2>
12Is you're 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#53c2e8a74ade77c928316396394ebe0f02405d96a12b81aa816986b22bf752c2">asEP_SCRIPT_SCANNER</a> to 0 right after creating the engine.<p>
13<div class="fragment"><pre class="fragment"><span class="comment">// Set engine to use ASCII scanner for script code</span>
14engine-&gt;<a class="code" href="classas_i_script_engine.html#1bce4e5f573a2ca0ff55163e28f761dd" title="Dynamically change some engine properties.">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#53c2e8a74ade77c928316396394ebe0f02405d96a12b81aa816986b22bf752c2" title="Select scanning method: 0 - ASCII, 1 - UTF8. Default: 1 (UTF8).">asEP_SCRIPT_SCANNER</a>, 0);
15</pre></div><p>
16If 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 you're 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#53c2e8a74ade77c928316396394ebe0fb6daa2ae0c712da7f6f16d698305fba1">asEP_STRING_ENCODING</a> to 1 before compiling your scripts.<p>
17<div class="fragment"><pre class="fragment"><span class="comment">// Set engine to use UTF-16 encoding for string literals</span>
18engine-&gt;<a class="code" href="classas_i_script_engine.html#1bce4e5f573a2ca0ff55163e28f761dd" title="Dynamically change some engine properties.">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#53c2e8a74ade77c928316396394ebe0fb6daa2ae0c712da7f6f16d698305fba1" title="Select string encoding for literals: 0 - UTF8/ASCII, 1 - UTF16. Default: 0 (UTF8)...">asEP_STRING_ENCODING</a>, 1);
19</pre></div><p>
20Observe that the <a class="el" href="classas_i_script_engine.html#95ad30812d89dee425240b49675017a4">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.<h2><a class="anchor" name="doc_string_2">
21Multiline string literals</a></h2>
22There 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#53c2e8a74ade77c928316396394ebe0f218fdf7e181bf9ee0498112f5a87c415">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>
23<div class="fragment"><pre class="fragment"><span class="comment">// Set engine to allow string literals with line breaks</span>
24engine-&gt;<a class="code" href="classas_i_script_engine.html#1bce4e5f573a2ca0ff55163e28f761dd" title="Dynamically change some engine properties.">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#53c2e8a74ade77c928316396394ebe0f218fdf7e181bf9ee0498112f5a87c415" title="Allow linebreaks in string constants. Default: false.">asEP_ALLOW_MULTILINE_STRINGS</a>, <span class="keyword">true</span>);
25</pre></div><p>
26Observe 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>
27The <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.<h2><a class="anchor" name="doc_string_3">
28Character literals</a></h2>
29By 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>
30If 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#53c2e8a74ade77c928316396394ebe0f6dc1c33f9227c66f18fc0f95a0c798b2">asEP_USE_CHARACTER_LITERALS</a> to true. The compiler will then convert single quoted literals to an integer number representing the first character.<p>
31<div class="fragment"><pre class="fragment"><span class="comment">// Set engine to use character literals </span>
32engine-&gt;<a class="code" href="classas_i_script_engine.html#1bce4e5f573a2ca0ff55163e28f761dd" title="Dynamically change some engine properties.">SetEngineProperty</a>(<a class="code" href="angelscript_8h.html#53c2e8a74ade77c928316396394ebe0f6dc1c33f9227c66f18fc0f95a0c798b2" title="Interpret single quoted strings as character literals. Default: false.">asEP_USE_CHARACTER_LITERALS</a>, <span class="keyword">true</span>);
33</pre></div><p>
34Observe that the <a class="el" href="angelscript_8h.html#53c2e8a74ade77c928316396394ebe0f02405d96a12b81aa816986b22bf752c2">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. </div>
35<hr size="1"><address style="text-align: right;"><small>Generated on Wed Dec 16 19:34:51 2009 for AngelScript by&nbsp;
36<a href="http://www.doxygen.org/index.html">
37<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address>
38</body>
39</html>