<html><!-- #BeginTemplate "/Templates/Body Text.dwt" -->
<head>
<title> Discworld Documentation </title>
</head>
<body bgcolor="#ffffff" TEXT="#000030" LINK="#4a529c" VLINK="#b57339">
<table width="75%" border="0">
<tr>
<td><font face="arial,helvetica"><img align=left src="http://discworld.imaginary.com/external//pics/dw4.gif"></font></td>
<td><font face="arial,helvetica">
<h2>Discworld Documentation:</h2>
<h2>LPC for Dummies</h2>
</font>
<p><font size="+1"><!-- #BeginEditable "Title" --><font size="+1"><b>Chapter Two:
LPC Data Types</b></font><!-- #EndEditable --></font></p>
<p><i>N.B - This is a work in progress... a living document if you like.
If it appears to be dead when you view it, don't worry. It's most likely
just playing possum.</i></p>
<p>Comments on these chapters and tutorials can be e-mailed to <a href="mailto:drakkos@cableinet.co.uk">Drakkos.</a></p>
</td>
</tr>
</table>
<br>
<!-- #BeginEditable "Body" -->
<p>Most objects have a need to store data from time to time... this is done through
the use of containers within the object that are called 'variables'. As the
name suggests, these containers hold information that can change from time to
time... each container has a label of sorts allowing the creator to refer to
the data within.
<p> Each of these variables is initialised by declaring the 'type' of the variable,
and the name of the variable itself. For example, to declare an integer variable
called 'Bing', you would use the following line:</p>
<blockquote>
<p> <code>int bing; </code></p>
</blockquote>
<p>Easy! This means that you can then refer to the information within that variable
by using the name 'bing'. You can add to bing, subtract from it... multiply,
divide, calculate exponentially... anything you could do with a normal integer
value, you can do with bing. </p>
<p>The following basic data types are available within LPC: int, string, float,
and object. We'll take each of these and discuss them a little more.</p>
<p> <b>Int</b></p>
<p>An int is a variable of the integer data type. Integers are whole numbers such
as 1, 10, 50, -24, etc, etc. The range of values that an integer variable can
hold range from the extremes of -2147483648 to 2147483647... any whole number
between these values is suitable for the integer data type.</p>
<p> We can add, subtract, multiply, and divide variables of the integer data type
just as if they were real, concrete numbers. For example:</p>
<blockquote>
<p> <code>int bing, bong;</code></p>
<p><code>bing = 2 + 2;<br>
bong = bing + 5; </code></p>
</blockquote>
<p> Which would set bing as 4 and bong as 9.</p>
<p> We can increment the value of an integer data type by one using the ++ incrementation
operator:</p>
<blockquote>
<p> <code>bing = 4;</code></p>
<p><code> bing++;</code></p>
</blockquote>
<p> At which point bing would equal five. It also possible to do ++bing, but as
far as the example above goes, they are equivilent. We will perhaps have cause
to return to ++bing and bing++ in another chapter.</p>
<p> We can also use the division (/) and multiplication (*) operators on our variable:</p>
<blockquote>
<p> <code>int bing, bong;</code></p>
<p><code> bing = 4; </code></p>
<p><code>bing = bing * 5;<br>
bong = bing / 4;</code></p>
</blockquote>
<p> This would make bing equal (4 * 5 = 20) twenty, and bong equal to (20 / 4)
five.</p>
<p> <b>Float </b></p>
<p>Floating point numbers are decimal numbers between two Very Large extremes.
These extremes vary from MUD to MUD. Both positive and negative numbers can
be represented by a float, so it's suitable for values such as 2.42, 3.141,
-2.76, -35.321, and so on. We use floats in a similar way to ints:</p>
<blockquote>
<p> <code>float bing, bong;</code></p>
<p><code> bing = -2.045;<br>
bong = bing + 1.34;</code></p>
</blockquote>
<p> Note however, that you cannot use ++bong or bong++ to increase a float value
by one whole number.</p>
<p> <b>String</b></p>
<p> Strings are sequences of alphadecimal characters enclosed in quotation marks.
Strings can also contain 'control codes' that determine the formatting of a
string. A string could be, for example, "This is a string", or "This is a longer
string!". The '\n' control code puts text on a 'new line', so the line: "This
is a string!\nThis is a string on another line." would produce: </p>
<blockquote>
<p><code>This is a string!<br>
This is a string on another line.</code></p>
</blockquote>
<p> As above, we declare a string variable like so: </p>
<blockquote>
<p><code>string bing, bong, bang;</code></p>
</blockquote>
<p> Then we assign it to a text value. Please note that you must enclose the text
in quotation marks: </p>
<blockquote>
<p><code>bing = "This is a string!\n";<br>
</code><code>bong = "This is a longer string!\n";</code></p>
</blockquote>
<p> Again, we manipulate strings in a similar way. We can add two strings together
using the + operator: </p>
<blockquote>
<p><code>bang = bing + bong;</code> </p>
</blockquote>
<p>Which would make bang equal to "This is a string!\nThis is a longer string!\n".</p>
<p> However, we cannot use the - operator to subtract from a string. There are
a number of specialised efuns that can be used to manipulate strings, however,
such as sscanf, strsrch, and strlen. Each of these have help files assosciated.
But don't worry about that at the moment... we may have cause to return to manipulating
strings later.</p>
<p> <b>Object</b></p>
<p> A variable of the object data type is simply a 'pointer' to an object loaded
in memory. Rather than making a direct copy of the object, a variable of of
the object data type simply contains the memory location of the object. Sound
complicated? Maybe... but you don't really need to understand the specifics
of what this means. Essentially, when you a create a variable of type object,
then assign it to a specific object, you can then access the reference of that
object using your variable... think of it as a tracking signal you can use to
home in on any object on the MUD For example:</p>
<blockquote>
<p> <code>object ob;<br>
ob = find_player ("drakkos");</code></p>
</blockquote>
<p> Find_player() is an efun (more on this later) that checks through all the
interactive objects on the MUD until it finds one with the name 'drakkos', It
then makes the variable 'ob' point to that object. So you could then use:</p>
<blockquote>
<p> <code>tell_object (ob, "Your pants are on fire!\n");</code></p>
</blockquote>
<p> tell_object() is another efun (again, more on this later), and this specific
piece of code would print the string "Your pants are on fire!" on the screen
of the object pointed to by 'ob'... in this case, the player called Drakkos.</p>
<p> Note that we cannot use mathematical operators on object variables. </p>
<p><b>Mixed </b></p>
<p>This is a general, all purpose data type that can deal with any of the data
that the other data types cannot. It must be stressed, however, that using a
mixed data type when another is more appropriate is Bad Form, and should be
avoided... the driver spends a fair bit of time trying to work out exactly what
data a 'mixed' variable contains, which has an obvious negative effect on the
efficiency of your code.</p>
<p> For example, all of the following are valid mixed assignments:</p>
<blockquote>
<p> <code>mixed bing;</code></p>
<p><code> bing = "Bong!\n";<br>
bing = 1;<br>
bing = 2.453;<br>
bing = find_player ("drakkos");</code></p>
</blockquote>
<p> Where applicable, we can perform mathematical operators on mixed variables.
So if our variable contained an integer, we could use +, -, /, and * on it as
normal. Likewise, we would get a parse error if we attempted to use these operators
on a mixed variable containing an object reference. </p>
<p><b>Advanced Data Types</b></p>
<p> There are other data types available within LPC, although these are a little
more complicated than the above basic data types. These are: arrays, mappings,
functions, and classes. Again, we'll go into these in a little more depth.</p>
<p> <b>Array</b></p>
<p> All of the above basic data types can be placed into lists which are known
as arrays. An array is simply a contextually linked sequence of a particular
data type. For example, it is possible to declare an array of integers, so that
a single variable can refer to that list of numbers. For example:</p>
<blockquote>
<p> <code>int *bing = ({ 1 , 5, 10, 20 });</code></p>
</blockquote>
<p> The int *bing means that you wish to create an array of type integer called
'bing'. The ({ }) braces are used to link the values together, and simply mean
that the array bing contains the values 1, 5, 10, and 20.</p>
<p> Once values have been entered into the array, they can be accessed through
the use of an index value, which determines which member of the array you are
interested in. In LPC, as with C, the numbering for an array begins at 0, so
the first element of the array is referred to with index 0. This seems complicated,
but will eventually come naturally. The index value of an array is referenced
using a pair of square brackets after the variable name:</p>
<blockquote>
<p> <code>bing [0]</code> (represents the value 1)<br>
<code>bing [1]</code> (represents the value 5)<br>
<code>bing [2]</code>(represents the value 10)<br>
<code>bing [3]</code> (represents the value 20)</p>
</blockquote>
<p> Arrays are very useful for dealing with large amounts of contextual information...
for example, an array of objects may refer to all the players standing in a
current room, and then each element of the array can be stepped through to allow
for information to be gathered or code to be executed on each player.</p>
<p> You can add to arrays using the += operator... if I wanted to add the value
'50' to the end of the array 'bing', I would use:</p>
<blockquote>
<p> <code>bing += ({50});</code></p>
</blockquote>
<p> Note that what we are actually doing is adding an array containing only the
value 50 to our original array. Attempting to simply add the integer 50 to the
array will give a parse error. </p>
<p>Likewise, members of an array can be deleted using the -= operator:</p>
<blockquote>
<p> <code>bing -= ({50});</code></p>
</blockquote>
<p> We can add arrays together in this way, also:</p>
<blockquote>
<p> <code>int *bing = ({ 1, 5, 10, 20 });<br>
int *bong = ({ 2, 3, 4 });</code></p>
<p> <code>bing += bong;</code></p>
</blockquote>
<p> Which would leave bing containing ({1, 5, 10, 20, 2, 3, 4}).</p>
<p> If you need to get the index of a particular element of an array, you can use
the member_array() efun. This will return the index of the element, or -1 if the
element is not in the array. It takes the value you are searching for as the
first argument, and the array you wish to search as the second:</p>
<blockquote>
<p> <code>int *bing = ({ 1, 5, 10, 20 });<br>
int bong = member_array (5, bing);</code></p>
</blockquote>
<p>Bong at this point equals 1 (remember, arrays count from 0, so index 1 is the
second element of the array). If we did instead:</p>
<blockquote>
<p> <code>int *bing = ({ 1, 5, 10, 20 });<br>
int bong = member_array (100, bing);</code></p>
</blockquote>
<p>Then bong would equal -1, because the element 100 is not in the array.</p>
<p>Member array will return only the index of the first occurrence of an element in
an array... any occurences of the element after the first are not returned.</p>
<p> Finally, an efun (see the later section on functions) exists that will give
you the current number of elements in an array... this is called sizeof(), and
can be used:</p>
<blockquote>
<p> <code>int *bing = ({ 1 , 5, 10, 20 });</code></p>
<p><code> int elements;</code></p>
<p><code> elements = sizeof(bing);</code></p>
</blockquote>
<p> The variable 'elements' would then contains an integer value equal to the
current number of elements in the array. In this case, elements would be equal
to 4.</p>
<p> <b>Mappings</b></p>
<p> LPC also provides a data type called a 'mapping'. Essentially, it is a more
specialised type of array composed of 'values', and 'keys'. Each key may have
a specific value, and this value is indexed using the key rather than an integer
value. This all sounds very complex, but is very simple to use in practice.
For example:</p>
<blockquote>
<p> <code>mapping myMap = ([</code><br>
<code>"Sojan" : "Bing!",<br>
"Pinkfish" : "Fluff!",<br>
"Turrican" : "Frog!",<br>
"Saffra" : "Womble!",<br>
]);</code></p>
</blockquote>
<p> The values on the left hand side of the ':' are the 'keys' of the mapping.
The values on the right hand side are the 'values'. The key 'Sojan', for example,
has the value "Bing!". If we wanted the value of the key 'Turrican', we would
refer to it as:</p>
<blockquote>
<p> <code>string value;<br>
value = myMap ["Turrican"];</code></p>
</blockquote>
<p> Value would then equal 'Frog!'.</p>
<p> Mappings are very powerful data types, but this power comes at an expense
in CPU and memory cost... mapping data types are of type 'mixed' by default,
and so keys and values can be of any type all the way through the array (although,
for the sake of programming style, you should really only use one type unless
entirely necessary).</p>
<p> We can also use the + operator on a pair of mappings to produce a single mapping
containing all elements:</p>
<blockquote>
<p> <code>myMap = myMap + ([ "Drakkos" : "Wibble!"]);</code></p>
</blockquote>
<p> Would make myMap equal:</p>
<blockquote>
<p> <code>"Sojan" : "Bing!",<br>
"Pinkfish" : "Fluff!",<br>
"Turrican" : "Frog!",<br>
"Saffra" : "Womble!",<br>
"Drakkos" : "Wibble!"</code><br>
</p>
</blockquote>
<p> We cannot use the - operator to remove entries from the mapping, but we can
use the map_delete()efun:</p>
<blockquote>
<p> <code>map_delete(myMap, "Drakkos");</code></p>
</blockquote>
<p> Which would return myMap to the state it was before we added Drakkos. </p>
<p> There are a couple of very useful efuns that can be used in conjunction with
mappings in order to convert them into arrays. The keys() efun will take a
mapping and return an array of all the left hand values of that mapping:</p>
<blockquote>
<p> <code>myArray= keys (myMap);</code></p>
</blockquote>
<p> Which would make myArray equal to ({"Sojan", "Pinkfish", "Turrican",
"Saffra"}).</p>
<p> The second of these efuns is values(), and works exactly the same way. The
difference is that this efun will return the right hand side of the
mapping:</p>
<blockquote>
<p> <code>myArray= values (myMap);</code></p>
</blockquote>
<p> Which would make myArray equal to ({"Bing!", "Fluff!", "Frog!",
"Womble!"}).</p>
<p><b>Functions</b></p>
<p> There is a data type in LPC called 'function', and as you can probably imagine,
is used to reference to a function. The use of functions as a data type is a
little complex to explain, and the chances are you will not really need to do
so until you have much more experience as a creator... so for the moment, it
is enough to know that it exists.</p>
<p> <b>Classes</b></p>
<p> A class in LPC is much like a database record containing numerous pieces of
information. For example, a database of player names, their guilds, and their
levels. One way to do it would be to have an array for each piece of information,
accessed by a common index value: </p>
<blockquote>
<p><code>string *names = ({"bert", "fred", "john"});<br>
string *guilds = ({"wizard", "priest", "warrior"});<br>
int *levels = ({111, 222, 333});</code></p>
</blockquote>
<p> If we assume that the player referred to by names[x] is equivalent to the
player referred to by guilds[x], which is equivalent to the player referred
to by levels[x], then we can make use of a database like query to reference
the information.</p>
<p> However, this is a rather clunky way of doing it... a much better way would
be to define the information in a 'class', and set the information contextually:</p>
<blockquote>
<p> <code>class player_details {<br>
string name;<br>
string guild;<br>
int level;<br>
}</code></p>
</blockquote>
<p> Essentially, what you are doing is creating a custom data-type of your very
own which you can then use in the same way you would use an int or a float.
The class declaration shown above is just that... a declaration that the name
'player_details' can be used to create variables of that type. Please note that
you have not actually created a variable yet... you have just outlined the form
any variables of type 'player_details' will take. You can use classed in conjunction
with arrays and mappings, meaning that you can have an array of classes (which
is suitable for a database), or a class could be a value in a mapping... this
makes the combination of such data types extremely powerful.</p>
<p> We declare a variable of our player_details class by using the 'new' operator,
passing in the values of the variables contained within:</p>
<blockquote>
<p> <code>class player_details one_player;</code></p>
<p><code> one_player = new(class player_details,<br>
</code><code>name: "fred",<br>
guild : "priest",<br>
level : 222<br>
);</code></p>
</blockquote>
<p> We can then access the details in the 'one_player' variable using -> to access
the data member: </p>
<blockquote>
<p><code>string name = one_player->name;</code></p>
</blockquote>
<p> Which would set the variable 'name' as 'fred'.</p>
<p> To declare an array of your new class, you would use a statement similar to:</p>
<blockquote>
<p> <code>class player_details *player_database = ({ });</code></p>
</blockquote>
<p> This creates an array of 'player_details' classes called 'player_database',
and initialises it so that it is empty (the = ({ }) part of the statement).
You can then access individual elements of the array with the [] index as above.</p>
<p> A full tutorial into how classes can be created and utilised is beyond the
scope of this initial document... again, it is sufficient to realise that the
data type exists, and that you understand what the data type is for if you see
it in an object. </p>
<p><b>Variable Scope </b></p>
<p>Now that we've covered the data types available in LPC, we can talk a little
about how they work within an object. </p>
<p>Each variable in an object has a 'scope'... a sphere of influence, if you like,
where the variable holds true. Variables are either 'global', or 'local' within
an object. If they are global, it means that the variable can be used anywhere
in that object... global declaration of variables is normally done at the top
of the code.</p>
<p> Local variables can only be used in the function in which they are defined.
We'll talk more about functions a little later, but for now let's see an example:</p>
<blockquote>
<p> <code>/*<br>
Example of scope<br>
*/<br>
<br>
int bing; <br>
<br>
int function_one() {<br>
int bong;<br>
return bong; <br>
}</code></p>
<p><code> int function_two() { <br>
return bing;<br>
}</code></p>
<p><code> int function_three() {<br>
return (bing + bong);<br>
}</code></p>
</blockquote>
<p> 'bing' is a object variable... it is defined outside of any of the functions,
and therefore can be used in any of them.</p>
<p> 'bong' is a local variable... it can only be used within the function it is
defined... in this case, function_one().</p>
<p> function_one() can access the variable bong, because it is declared locally
within that function. Function_two can access 'bing', because 'bing' is an object
variable, and therefore all functions can access it.</p>
<p> Function_three(), however, will not work. Although the function has access
to the variable 'bing', it has no idea what 'bong' refers to... 'bong' is outside
the 'scope' of function_three() since it is only defined locally in function_one().</p>
<p> <b>Chapter Summary</b></p>
<p> After reading this chapter, you should hopefully feel comfortable with data
types, how to declare them, and how to utilise them. You should also hopefully
understand the concept of variable scope, and how this can affect the way your
code operates. </p>
<ul>
<li><code>Basic data types are declared by giving first the type of variable,
and then the label for that variable.</code></li>
<li><code> Integer variables hold whole numbers, and can be manipulated mathematically
the same way as normal numbers can be.</code></li>
<li><code> The mathematical operators are + (addition), - (subtraction), / (division),
and * (multiplication). </code></li>
<li><code>Float variables contain real numbers rather than natural numbers.
- String variables hold alphanumerical values, and can be used to hold blocks
of text. </code></li>
<li><code>Object variables are references to the memory location of loaded objects.
Essentially a pointer to where the object exists in the memory of the MUD.
</code></li>
<li><code>Mixed data types can contain any of other data types, but because
of the associated CPU overhead, they should only be used when genuinely required.
</code></li>
<li><code>Arrays are conceptually linked lists of information, and are initialised
by prefacing the name of the variable with a *.</code></li>
<li><code> Individual members of an array are accessed by using the name of
the variable and the index of the variable enclosed in []. </code></li>
<li><code>Arrays begin counting from 0, so the first element of the array is
at index 0. </code></li>
<li><code>Mappings are associative arrays composed of keys and values. Each
key indexes a specific value.</code></li>
<li><code> Mappings are of typed 'mixed' by default, and so can contain any
type of data. </code></li>
<li><code>Classes can be used to create database-like data types containing
collections of related data. </code></li>
<li><code>Variables have a scope when initialised. If initialised outside of
a function, their scope is the whole object. If initialised within a function,
they are known as local variables and may only be used within that function.</code></li>
</ul>
<!-- #EndEditable -->
<p>
<hr>
<center><font size="-1"><a href="/login.html">Discworld MUD</a>'s world wide web pages.<br>brought to you by<br>
<strong>Cut Me Own Throat Dibbler's <a href="/sausages.html">Sensational Sausages</a>; buy
one while they are hot.</strong> <br>
<hr>Lost? Try Discworld's <a href="/">home page</a>.</font></center><font size="-1"><i><a href="mailto:drakkos@cableinet.co.uk"><font size="-2">Mail Drakkos!</font></a></i>
</font>
</body>
<!-- #EndTemplate --></html>
