https://wiki.frictionalgames.com/page?title=HPL2/ScriptReference/Functions_Part_2&feed=atom&action=historyHPL2/ScriptReference/Functions Part 2 - Revision history2024-03-28T13:35:44ZRevision history for this page on the wikiMediaWiki 1.34.2https://wiki.frictionalgames.com/page?title=HPL2/ScriptReference/Functions_Part_2&diff=3470&oldid=prevDarkfire: Darkfire moved page Hpl2:Amnesia:script language reference and guide:funcions - part 2 to HPL2/ScriptReference/Functions Part 2 without leaving a redirect: Moving to the main namespace2020-08-05T13:17:17Z<p>Darkfire moved page <a href="/page?title=Hpl2:Amnesia:script_language_reference_and_guide:funcions_-_part_2&action=edit&redlink=1" class="new" title="Hpl2:Amnesia:script language reference and guide:funcions - part 2 (page does not exist)">Hpl2:Amnesia:script language reference and guide:funcions - part 2</a> to <a href="/page/HPL2/ScriptReference/Functions_Part_2" title="HPL2/ScriptReference/Functions Part 2">HPL2/ScriptReference/Functions Part 2</a> without leaving a redirect: Moving to the main namespace</p>
<table class="diff diff-contentalign-left" data-mw="interface">
<tr class="diff-title" lang="en">
<td colspan="1" style="background-color: #fff; color: #222; text-align: center;">← Older revision</td>
<td colspan="1" style="background-color: #fff; color: #222; text-align: center;">Revision as of 13:17, 5 August 2020</td>
</tr><tr><td colspan="2" class="diff-notice" lang="en"><div class="mw-diff-empty">(No difference)</div>
</td></tr></table>Darkfirehttps://wiki.frictionalgames.com/page?title=HPL2/ScriptReference/Functions_Part_2&diff=3442&oldid=prevDarkfire: /* Const Function Parameters */ Link update2020-08-05T12:44:42Z<p><span dir="auto"><span class="autocomment">Const Function Parameters: </span> Link update</span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class="diff-marker" />
<col class="diff-content" />
<col class="diff-marker" />
<col class="diff-content" />
<tr class="diff-title" lang="en">
<td colspan="2" style="background-color: #fff; color: #222; text-align: center;">← Older revision</td>
<td colspan="2" style="background-color: #fff; color: #222; text-align: center;">Revision as of 12:44, 5 August 2020</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l55" >Line 55:</td>
<td colspan="2" class="diff-lineno">Line 55:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>Just as you can [[<del class="diffchange diffchange-inline">hpl2:amnesia:script_language_reference_and_guide:constants_and_enumerations</del>|turn a variable into a constant]] by prepending it's declaration with the ''const'' keyword, you can, by applying the same keyword, turn a normal function parameter to a constant parameter (const-parameter). As a scripter, by doing so, you're making a statement (to the compiler, to yourself, and to other people who might use your code in their projects) that the value of that particular parameter will not be modified for the duration of the function. If you try to change it by accident, you'll receive an error message. This can be useful, especially if the code you're writing is complicated or sensitive, where making accidental changes to values that are supposed to remain constant can cause hard-to-solve problems. Declaring parameters const effectively lets the compiler spot any errors for you.</div></td><td class='diff-marker'>+</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>Just as you can [[<ins class="diffchange diffchange-inline">HPL2/ScriptReference/Constants And Enumerations</ins>|turn a variable into a constant]] by prepending it's declaration with the ''const'' keyword, you can, by applying the same keyword, turn a normal function parameter to a constant parameter (const-parameter). As a scripter, by doing so, you're making a statement (to the compiler, to yourself, and to other people who might use your code in their projects) that the value of that particular parameter will not be modified for the duration of the function. If you try to change it by accident, you'll receive an error message. This can be useful, especially if the code you're writing is complicated or sensitive, where making accidental changes to values that are supposed to remain constant can cause hard-to-solve problems. Declaring parameters const effectively lets the compiler spot any errors for you.</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>The following example is trivial, and there's no real need for ''const'' in this function, but it serves the purpose of demonstrating the syntax:</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>The following example is trivial, and there's no real need for ''const'' in this function, but it serves the purpose of demonstrating the syntax:</div></td></tr>
<tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l73" >Line 73:</td>
<td colspan="2" class="diff-lineno">Line 73:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>}</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>}</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div></syntaxhighlight></div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div></syntaxhighlight></div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div><del style="font-weight: bold; text-decoration: none;"></del></div></td><td colspan="2"> </td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>=== Function Overloading ===</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>=== Function Overloading ===</div></td></tr>
</table>Darkfirehttps://wiki.frictionalgames.com/page?title=HPL2/ScriptReference/Functions_Part_2&diff=1796&oldid=prevDarkfire: Syntax highlighting fix2020-07-23T16:24:49Z<p>Syntax highlighting fix</p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class="diff-marker" />
<col class="diff-content" />
<col class="diff-marker" />
<col class="diff-content" />
<tr class="diff-title" lang="en">
<td colspan="2" style="background-color: #fff; color: #222; text-align: center;">← Older revision</td>
<td colspan="2" style="background-color: #fff; color: #222; text-align: center;">Revision as of 16:24, 23 July 2020</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l199" >Line 199:</td>
<td colspan="2" class="diff-lineno">Line 199:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>For completeness, the output of each of these, respectively, is:</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>For completeness, the output of each of these, respectively, is:</div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div><<del class="diffchange diffchange-inline">syntaxhighlight lang=""</del>></div></td><td class='diff-marker'>+</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div><<ins class="diffchange diffchange-inline">pre</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Planets: 8</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>Planets: 8</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>200</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>200</div></td></tr>
<tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l205" >Line 205:</td>
<td colspan="2" class="diff-lineno">Line 205:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>1.0</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>1.0</div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>========================================</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>========================================</div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div></<del class="diffchange diffchange-inline">syntaxhighlight</del>></div></td><td class='diff-marker'>+</td><td style="color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div></<ins class="diffchange diffchange-inline">pre</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>=== When to use Overloads? Any Other Tips? ===</div></td><td class='diff-marker'> </td><td style="background-color: #f8f9fa; color: #222; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #eaecf0; vertical-align: top; white-space: pre-wrap;"><div>=== When to use Overloads? Any Other Tips? ===</div></td></tr>
</table>Darkfirehttps://wiki.frictionalgames.com/page?title=HPL2/ScriptReference/Functions_Part_2&diff=741&oldid=prevMaintenance script: Upload from wiki2020-07-09T13:47:55Z<p>Upload from wiki</p>
<p><b>New page</b></p><div>= Functions - Part 2: Beyond the Basics =<br />
<br />
<br />
----<br />
<br />
<br />
== At a Glance ==<br />
<br />
<br />
'''Const-Parameters'''<br />
<syntaxhighlight lang="c++"><br />
void ConstParamFunc(const int val1, int val2)<br />
{<br />
val1++; // ERROR: Changing the value of a const parameter is not allowed!<br />
val2++; // OK.<br />
}<br />
</syntaxhighlight><br />
<br />
'''Function Overloading & Wrapping'''<br />
<syntaxhighlight lang="c++"><br />
// Note: The compiler uses function signatures to determine which function to call.<br />
<br />
<br />
// Below are 3 valid overloads of the WriteLine() function<br />
<br />
// (1) A convenience method, to get rid of the second parameter of AddDebugMessage()<br />
void WriteLine(string text)<br />
{<br />
AddDebugMessage(text, false); // <--- WriteLine() wraps AddDebugMessage()<br />
}<br />
<br />
// (2) Shows the value of 'data' as a debug message, with some extra info<br />
void WriteLine(int data, string text)<br />
{<br />
WriteLine(text + ": " + data); // calls (1)<br />
}<br />
<br />
// (3) Shows the value of 'data' as a debug message<br />
void WriteLine(int data)<br />
{<br />
WriteLine(data, ""); // calls (2)<br />
}<br />
<br />
// PROBLEM - return type doesn't make a difference<br />
int WriteLine(int data) // ERROR: signature same as for (3)!<br />
{<br />
WriteLine(data, "");<br />
return data;<br />
}<br />
</syntaxhighlight><br />
<br />
== Discussion ==<br />
<br />
=== Const Function Parameters ===<br />
<br />
<br />
Just as you can [[hpl2:amnesia:script_language_reference_and_guide:constants_and_enumerations|turn a variable into a constant]] by prepending it's declaration with the ''const'' keyword, you can, by applying the same keyword, turn a normal function parameter to a constant parameter (const-parameter). As a scripter, by doing so, you're making a statement (to the compiler, to yourself, and to other people who might use your code in their projects) that the value of that particular parameter will not be modified for the duration of the function. If you try to change it by accident, you'll receive an error message. This can be useful, especially if the code you're writing is complicated or sensitive, where making accidental changes to values that are supposed to remain constant can cause hard-to-solve problems. Declaring parameters const effectively lets the compiler spot any errors for you.<br />
<br />
The following example is trivial, and there's no real need for ''const'' in this function, but it serves the purpose of demonstrating the syntax:<br />
<syntaxhighlight lang="c++"><br />
float GetCircleArea(const float radius) // makes sure 'radius' is not changed<br />
{<br />
return 3.14f * radius * radius;<br />
}<br />
</syntaxhighlight><br />
<br />
You can choose to make only some parameters constant, and leave others as they are:<br />
<syntaxhighlight lang="c++"><br />
// makes sure 'lastItemFoundID' is constant, but 'itemsLeft' is free to change<br />
void UpdateQuest(const int lastItemFoundID, int itemsLeft) <br />
{<br />
// implementation omitted...<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
=== Function Overloading ===<br />
<br />
Function overloading is a rather useful feature of the language. It enables you to define several functions with the same name, provided that all of them have different parameter lists. You'd want to do this if you have several functions which all do related things, but on different data types, or if all of those functions differ only slightly. Also, if you have a function which accepts a large number of parameters, but most of them are rarely used, or mostly receive the same set of values on a call, you might want to provide a version of the function which does the same thing, but takes fewer parameters. Overloading makes this possible by letting you define such a function, which can then internally call the original version, passing along its own parameters, and filling the rest with default values.<br />
<br />
For example, if you've used the predefined AddDebugMessage() function before, you know that this function takes two parameters: the message itself, and a bool parameter which indicates whether the engine should check if the debug message you're trying to show has already been shown, so that duplicates can be avoided. That's a neat feature, but most of the time, you won't care. That being the case, the chore of passing an extra parameter you don't even use quickly becomes annoying. Luckily, you can ''overload'' the AddDebugMessage() function, by providing your own version which takes only one parameter, like this:<br />
<syntaxhighlight lang="c++"><br />
void AddDebugMessage(string text) // your version which accepts a single string<br />
{<br />
// it simply calls the original version, always passing 'false' as the 2nd param<br />
AddDebugMessage(text, false); <br />
}<br />
</syntaxhighlight><br />
<br />
Now you have available for use two versions, or two ''overloads'' of AddDebugMessage(). Their declarations are:<br />
<syntaxhighlight lang="c++"><br />
void AddDebugMessage(string& text, bool checkForDuplicates); // original version; ignore the '&' for now<br />
void AddDebugMessage(string text); // your version<br />
</syntaxhighlight><br />
<br />
When you use one in a script, the compiler determines which one you called by looking at ''how many parameters you've passed'', as well as ''what are the types of those parameters''. Note that the actual names of the parameters are not important in this regard; only the types, position, and number of parameters make a difference. This is why, when you refer to different overloads in discussions, you can omit the actual parameter names.<br />
<syntaxhighlight lang="c++"><br />
void AddDebugMessage(string&, bool); // original; ignore the '&' for now<br />
void AddDebugMessage(string); // your version<br />
</syntaxhighlight><br />
<br />
Using these in code is pretty straightforward. In this case, it's essentially as if the second parameter to the original function was optional:<br />
<syntaxhighlight lang="c++"><br />
AddDebugMessage("Player collided with Area6", false); // calls the original version<br />
<br />
// vs<br />
<br />
AddDebugMessage("Player collided with Area6"); // calls your version<br />
</syntaxhighlight><br />
<br />
So, to determine what function you intended to call, a compiler will take a look at the name of the function, and then at the parameters you've passed to it. Then it will try to match these to one of the declared functions, by checking the ''signature'' of each function. <br />
<br />
<note tip>''Function signature'' consists of a function name, and a parameter list (where the names of the parameters are irrelevant, as previously discussed).</note> <br />
<br />
The function which has the matching signature gets called. This is important to know, because it means that you ''can't'' overload a function by just specifying a different return type for the new version. It also means that you ''cannot'' create an overload by simply changing the names of the parameters.<br />
<syntaxhighlight lang="c++"><br />
// Note: function bodies omitted, only declarations shown<br />
<br />
void AddDebugMessage(string& text, bool checkForDuplicates); // (1) original version; ignore the '&' for now<br />
void AddDebugMessage(string& msg, bool checkDuplicates); // (2) won't work - exactly the same as (1) <br />
string AddDebugMessage(string& text, bool checkForDuplicates); // (3) won't work - in a call, cant distinguish from (1) <br />
<br />
//All of these can be the target of this call:<br />
AddDebugMessage("Music started.", false);<br />
</syntaxhighlight><br />
<br />
=== Wrapping Functions ===<br />
<br />
I've demonstrated how to overload a predefined function, but this is not a requirement. You can overload any function, including the ones you made yourself. When writing debug messages, there's often a need to print out the value of some variable you used in your script, so that you can track what's going on as your code executes. Let's say that you're keeping track of the number of items the Player found, and that you've grown tired of always passing ''"Items#: " + numItems'' to AddDebugMessage() (whichever version). You can write a specialized function of your own that is easier to use, which then calls AddDebugMessage() in turn. This technique was already demonstrated in the previous section, and it's called ''wrapping''. When you wrap a function, you delegate all or most of the work to it, but you enclose it into another function which is than free to have any name and format you chose. Essentially, you adapt the original function to a new format (or ''interface''), one that matches your new needs.<br />
<br />
The WriteLine() function in the example below accepts an int and a string, and wraps the AddDebugMessage() function. The wrapper displays a text message, followed by the value of the ''data'' parameter.<br />
<syntaxhighlight lang="c++"><br />
void WriteLine(int data, string text)<br />
{<br />
AddDebugMessage(text + ": " + data, false);<br />
}<br />
<br />
// Calling the function:<br />
numItems = 3;<br />
WriteLine(numItems, "Items#"); // outputs: "Items#: 3"<br />
</syntaxhighlight><br />
<br />
WriteLine(int, string) is somewhat more convenient than AddDebugMessage(string&, bool) because you don't have to bother with string concatenation, ''and'' you can use the second parameter to WriteLine(int, string) to pass along any info text you might want. <br />
<br />
<br />
=== More Overloading ===<br />
<br />
Now let's make an overload which just accepts the variable itself, and prints it's value alone:<br />
<syntaxhighlight lang="c++"><br />
void WriteLine(int data)<br />
{<br />
WriteLine(numItems, "");<br />
}<br />
<br />
// Calling the function:<br />
numItems = 3;<br />
WriteLine(numItems); // outputs: "3"<br />
</syntaxhighlight><br />
<br />
Note that this function simply makes a call to the previously defined overload. Next, maybe you want to print the values of some floats? No problem, add two more overloads:<br />
<syntaxhighlight lang="c++"><br />
// Note: function bodies omitted, only declarations shown<br />
void WriteLine(float data, string text);<br />
void WriteLine(float data);<br />
</syntaxhighlight><br />
<br />
Here's another overload which can be used to create horizontal separators, which can be used to logically separate various debug messages:<br />
<syntaxhighlight lang="c++"><br />
void WriteLine(int length, bool wide)<br />
{<br />
string separator = "";<br />
<br />
string separatorChar = "-";<br />
<br />
<br />
if (wide)<br />
separatorChar = "=";<br />
<br />
for (int i = 0; i < length; ++i)<br />
separator += separatorChar;<br />
<br />
AddDebugMessage(separator, true);<br />
}<br />
</syntaxhighlight><br />
<br />
Using all of these functions your script:<br />
<syntaxhighlight lang="c++"><br />
int anInt = 8;<br />
float aFloat = 1.0f;<br />
<br />
WriteLine(anInt, "Planets"); // WriteLine(int, string) called<br />
WriteLine(200); // WriteLine(int) called<br />
<br />
WriteLine(3.14f, "Pi"); // WriteLine(float, string) called<br />
WriteLine(aFloat); // WriteLine(float) called<br />
<br />
WriteLine(40, true); // WriteLine(int, bool) called<br />
</syntaxhighlight><br />
<br />
For completeness, the output of each of these, respectively, is:<br />
<syntaxhighlight lang=""><br />
Planets: 8<br />
200<br />
Pi: 3.14<br />
1.0<br />
========================================<br />
</syntaxhighlight><br />
<br />
=== When to use Overloads? Any Other Tips? ===<br />
<br />
Overloading functions is great, but there are some guidelines to be considered. As always, strive to create functions which, when called, provide a good idea of what they do. In the example above, the call "WriteLine(40, true)" doesn't really tell you what the function does. If you had to guess just by looking at that call, you'd probably get it wrong. This indicates bad function design - in this case, it is much better to rename that overload to something like WriteSeparator(), at which point it would stop being an overload, but it would be much more user friendly. So, overloads can be very useful, but don't go overboard with them.<br />
<br />
Provide overloads when you want to simulate optional parameters. With such overloads, always try to maintain the same parameter order in all overloads. Keep the most commonly used parameters near the front of the list, and push those used rarely to the back. Also create overloads to support the same operation on different data types, but be mindful that the purpose of the function remains clear. In different overloads, try to keep the logically equivalent parameters of different types in the same place in the parameter lists. If an overload feels too cryptic when used in code, consider changing it's name to something that better communicates it's purpose.</div>Maintenance script