AlliedModders Wiki - User contributions [en]

Handle API (SourceMod)

2022-12-11T21:10:51Z

Nergal: /* Reading/Checking Handles */

The SourceMod [[Handles (SourceMod Scripting)|Handle System]] marshals pointers into typed, unique, 32-bit integers. This makes coding in SourceMod more cross-platform compatible, type safe, and mistake safe than its predecessor, [[AMX Mod X]]. It also allows for safe object sharing and reference count based object destruction.

The fundamental aspect of Handles is that they encapsulate a single pointer. This pointer is private data, and can only be read by the Handle's creator. When the Handle is freed, the pointer is automatically freed (via a special interface), thus ensuring that memory is not leaked.

Handles also provide a simple "security" system for restricting which areas of SourceMod are allowed to directly call certain functions on Handles under a given type.

=Basic Types=
==Handle_t==
The <tt>Handle_t</tt> type is a 32bit integer. Currently, it is composed of two 16-bit integers, a serial number and a handle index. The serial number is private and used for integrity checking. The index is the internal ID of the Handle, which is tied to the encapsulated pointer and security information.

Each <tt>Handle_t</tt> is a unique Handle, however, there are ''cloned'' Handles which are copies of another Handle. They have their own unique signatures, but they refer to another Handle internally. Each Handle is also associated with a ''type'', explained below.

==HandleType_t==
The <tt>HandleType_t</tt> describes a type under which Handles can be created. Types can have up to 15 sub-types; sub-types can also have their own sub-types, called child types. When Handles are being read, they are "type checked," to make sure they are being read under a given type. When a type is destroyed, all Handles under the type are destroyed. If the type has child types, each child type is also destroyed.

Handle types also allow overloading of various Handle operations. Currently, the only overloaded action is for overloading when a Handle is destroyed. This allows the encapsulated pointer to be safely destroyed by the type interface. The interface which overloads type operations is called <tt>IHandleTypeDispatch</tt>.

Lastly, types provide a "default security" system which lets programmers restrict which functions can be accessed by other areas in SourceMod. This is explained later.

=Security=
'''Note:''' Type defaults can be set via <tt>IHandleSys::InitAccessDefaults()</tt>.

==Type Security==
Often, extensions may want to share HandleType_t values with each other, so they can create Handles of external types. However, the owner of the handle type may not want other extensions to perform certain actions. Thus, types can be ''secured'' by an <tt>IdentityToken_t</tt> when created. Unless the same <tt>IdentityToken</tt> is provided, a function may fail if restricted.

Type permissions are declared in a <tt>TypeAccess</tt> struct, which has the following user-set members:
*<tt>ident</tt>: The <tt>IdentityToken_t</tt> owner of this type.
*<tt>access</tt>: An array where each index is a <tt>HTypeAccessRight</tt> enumeration member. If an index is set to false, functions requiring that right will fail unless the correct <tt>IdentityToken_t</tt> is passed in.

The <tt>HTypeAccessRight</tt> enumeration has the following values:
*<tt>HTypeAccess_Create</tt>: Handle creation using this type; default is false.
*<tt>HTypeAccess_Inherit</tt>: Inheriting this type for child types; default is false.

Below is a list of each Handle System function that requires type permissions, and which permissions may be required:
*<tt>CreateType</tt>: <tt>HTypeAccess_Inherit</tt> if a parent is specified
*<tt>RemoveType</tt>: (none, always secured)
*<tt>CreateHandle</tt>: <tt>HTypeAccess_Create</tt>

==Handle Security==
Handle security permissions inherit from their parent type unless given an alternate set of permissions. Handles are "secured" by two properties, unlike handle types, which just have one. When verifying your identity with a secured Handle function, you must use the <tt>HandleSecurity</tt> struct, which has two properties:
*<tt>pOwner</tt>: The owner of the Handle, which is usually a plugin <tt>IdentityToken_t</tt>.
*<tt>pIdentity</tt>: The owner of the Handle's type, or the <tt>IdentityToken_t</tt> securing its type.

Handle permissions are specified via the <tt>HandleAccess</tt> struct. It is passed either through <tt>CreateType</tt> for default settings in a given type, or through <tt>CreateHandleEx</tt> for explicit per-Handle permissions. This struct has the following members:
*<tt>access</tt>: An array where each index is a <tt>HandleAccessRight</tt> enumeration member. If set to 0, an access right is allowed without a <tt>HandleSecurity</tt> instance. Otherwise, the following bitwise flags are checked:
**<tt>HANDLE_RESTRICT_IDENTITY</tt>: If flagged, this access right is only granted if the <tt>pIdentity</tt> member of the <tt>HandleSecurity</tt> struct matches the Handle's '''type's''' owner.
**<tt>HANDLE_RESTRICT_OWNER</tt>: If flagged, this access right is only granted if the <tt>pOwner</tt> member of the <tt>Handlesecurity</tt> struct matches the Handle's owner.

The following access rights exist for Handles:
*<tt>HandleAccess_Read</tt>: This Handle's encapsulated pointer can be retrieved. Defaults to <tt>HANDLE_RESTRICT_IDENTITY</tt>.
*<tt>HandleAccess_Delete</tt>: This Handle can be removed or freed. Defaults to <tt>HANDLE_RESTRICT_OWNER</tt>.
*<tt>HandleAccess_Clone</tt>: This Handle can be cloned. Defaults to 0.

Below is a list of each Handle system function that requires permissions, and which permissions may be required:
*<tt>FreeHandle</tt>: <tt>HandleAccess_Delete</tt>
*<tt>CloneHandle/CloneHandleEx</tt>: <tt>HandleAccess_Clone</tt>
*<tt>ReadHandle</tt>: <tt>HandleAccess_Read</tt>

SourceMod's generic native wrappers assume follow these rules, however, they assume certain access rights, and will return <tt>INVALID_HANDLE</tt> or 0 if these rights are denied. Thus, you should make sure your permissions are compatible, unless you explicitly want to deny usage of these functions.
*<tt>CloneHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity</tt>, meaning <tt>HandleAccess_Clone</tt> must be 0.
*<tt>CloseHandle()</tt>: Passes <tt>NULL</tt> for <tt>HandleSecurity::pIdentity</tt>, and the plugin's <tt>IdentityToken_t</tt> for <tt>HandleSecurity::pOwner</tt/>. This means that at most, the only restriction can be <tt>HANDLE_RESTRICT_OWNER</tt> for <tt>HandleAccess_Delete</tt>.

=Usage Examples=
Here are some examples of Handle usages.

==Basic Handles==
The most basic use of Handles is to encapsulate a data structure and allow <tt>CloseHandle</tt> to universally destroy it. Let's say we want to implement two natives - <tt>CreateFile</tt> for creating an empty file, and <tt>WriteLine</tt> for writing a line to this file. How could we implement this using the Handle system?

After reading this, it is tempting to think, "Why can't we just return the <tt>FILE</tt> pointer as a <tt>cell_t</tt>?" The reason is that a <tt>cell_t</tt> is guaranteed to be a 32bit integer. There is no guarantee that a pointer will always be this size, however, and thus casting on future platforms could break. This problem happened in [[AMX Mod X]] and greatly restricted flexibility.

===Creating the type===
First, we have to create the type and its Dispatch interface.
<cpp>HandleType_t g_FileType = 0; /* Holds the HandleType ID */

class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
/* :TODO: implement this */
}
};

/* Create an instance of the handler */
FileTypeHandler g_FileTypeHandler;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);
}

Shutdown()
{
/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

===Creating Handles===
Creating the Handles is fairly easy once we have a valid pointer to stuff in it.
<cpp>/* native CreateFile(const String:file[]) */
static cell_t sm_CreateFile(IPluginContext *pContext, const cell_t *params)
{
char path[PLATFORM_MAX_PATH];
char *filename;

/* Get the filename */
pContext->LocalToString(params[1], &filename);
/* Build a full path */
g_pSM->BuildPath(Path_SM, path, sizeof(path), "%s", filename);

/* Open for writing */
FILE *fp = fopen(path, "wt");
if (!fp)
{
return BAD_HANDLE;
}

/* Create the Handle with our type, the FILE pointer, the plugin's identity, and our identity */
return g_pHandleSys->CreateHandle(g_FileType,
fp,
pContext->GetIdentity(),
myself->GetIdentity(),
NULL);
}</cpp>

===Reading/Checking Handles===
Handles aren't very useful unless you have natives to use them. Let's say we want to write lines of text to our File type.
<cpp>/* native bool WriteLine(Handle hndl, const char[] line); */
static cell_t sm_WriteLine(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = nullptr; /* Not needed, owner access is not checked */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp = nullptr;
if ((err = g_pHandleSys->ReadHandle(hndl, g_FileType, &sec, (void **)&fp))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

/* Get the text */
char *text = nullptr;
pContext->LocalToString(params[2], &text);

/* Write it */
fputs(text, fp);

return 1;
}</cpp>

===CloseHandle Support===
Lastly, we need to make it so <tt>CloseHandle()</tt> or <tt>FreeHandle()</tt> will close our file pointer when removing the Handle, which we skipped before.
<cpp>class FileTypeHandler : public IHandleTypeDispatch
{
public:
void OnHandleDestroy(HandleType_t type, void *object)
{
fclose( (FILE *)object );
}
};</cpp>

==Restricting CloseHandle==
Let's say that, for various reasons, you don't want users to be able to call CloseHandle(). An example of this might be a data type that is non-temporary, or is being called from a forward, and thus should not be touched. Or, you might have a special deconstructor that takes extra parameters, and thus you need a separate destroy function.

For example, let's create a separate function called <tt>CloseFile</tt>. It doesn't do anything particularly special, but we are going to force its usage over CloseHandle().

===New Security Rules===
<cpp>Initialize()
{
/* Create default access rights */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);

/* Restrict delete to only our identity */
rules.access[HandleAccess_Delete] = HANDLE_RESTRICT_IDENTITY;

/* Register the type with our security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
&rules,
myself->GetIdentity(),
NULL);
}</cpp>

===Implementing the Native===
<cpp>/* native Closefile(Handle:hndl); */
static cell_t sm_CloseFile(IPluginContext *pContext, const cell_t *params)
{
Handle_t hndl = static_cast<Handle_t>(params[1]);
HandleError err;
HandleSecurity sec;

/* Build our security descriptor */
sec.pOwner = pContext->GetIdentity(); /* Needed, HANDLE_RESTRICT_OWNER is default */
sec.pIdentity = myself->GetIdentity(); /* But only this extension can read */

/* Attempt to read the given handle as our type, using our security info.
* Note that we read the pointer directly in with a little cast.
* This type of cast is safe since sizeof(void **) == sizeof(void *) == sizeof(T *) in almost all cases.
*/
FILE *fp;
if ((err = g_pHandleSys->FreeHandle(hndl, &sec))
!= HandleError_None)
{
return pContext->ThrowNativeError("Invalid file handle %x (error %d)", hndl, err);
}

return 1;
}</cpp>

==Restricting CloseHandle Per-Handle==
Taking our above example, it is possible that we might want some Handles to be closed via CloseHandle(), but others not. Again, this is useful if you wish to pass a Handle as read-only to a plugin, commonly done when using non-temporary structures or Handles used in Forwards.

In this example, we'll create a global instance of our file type, and this instance will be denied access to CloseHandle(), whereas files returned by OpenFile() will not.

===Implementation===
<cpp>Handle_t g_GlobalFile;

Initialize()
{
/* Register the type with default security permissions */
g_FileType = g_pHandleSys->CreateType("File",
&g_FileTypeHandler,
0,
NULL,
NULL,
myself->GetIdentity(),
NULL);

/* Create our 'global' file */
FILE *fp = tmpfile();

/* Set up the security descriptor */
HandleSecurity sec;
sec.pOwner = NULL; /* No owner for this Handle */
sec.pIdentity = myself->GetIdentity(); /* Only this identity will be allowed */

/* Set up the access permissions */
HandleAccess rules;
g_pHandleSys->InitAccessDefaults(NULL, &rules);
rules.access[HandleAccess_Delete] |= HANDLE_RESTRICT_IDENTITY;

/* Finally, create the Handle with our rules */
g_GlobalFile = g_pHandleSys->CreateHandleEx(g_FileType, fp, &sec, &rules, NULL);
}

Shutdown()
{
/* Remove our global Handle (not needed, but we do it for clarity */
HandleSecurity sec;
sec.pOwner = NULL;
sec.pIdentity = myself->GetIdentity();

g_pHandleSys->FreeHandle(g_GlobalFile, &sec);

/* Remove the type on shutdown */
g_pHandleSys->RemoveType(g_FileType, myself->GetIdentity());
}</cpp>

[[Category:SourceMod Development]]

Natives (SourceMod Development)

2021-03-10T15:54:49Z

Nergal: Updating pawn examples to newer syntax

Natives are functions which are available to plugins via Core itself, or a C++ extension. They are called "natives" because they must be translated via a ''native interface''. This article explains the various parameter passing conventions in SourcePawn, as well as how to use them in your own natives.

To understand the contents of this article, you will need to read [[Writing_Extensions#Creating_Native_Functions|Creating Natives]], the Native section in the introductory article on creating extensions.

In this article, <tt>float</tt> refers to the C/C++ data type, and <tt>Float</tt> (note capital 'F') refers to the SourcePawn [[Tags (Scripting)|tag]].

=By Value versus By Reference=
There are two ways to pass integers/Floats to native implementations. They are ''by value'' (ByVal) and ''by reference'' (ByRef). ByVal means that a copy of the value is passed to the native. This is the default behaviour. ByRef means a ''reference'' is passed to the native, and this reference points to the value. Both will be explained below.

Note that arrays and strings, as will be explained later, are always passed by reference. This is because they are usually larger structures, and passing them ByVal would require copying their data, wasting CPU cycles.

==By Value==
Passing by value is the default behaviour for primitive data types (integers, Floats, or any tag that's cell-based). Data is treated normally as raw, copied input. Observe the following native:

<pawn>/**
* Returns the number decremented by one.
*
* @param num Number to decrement.
* @return Decremented number.
*/
native int Decrement(int num);</pawn>

How would we use this native? Since <tt>num</tt> is passed as a value, it cannot change in the native code. This means we have to use the return value as such:

<pawn>//Decrements a number 5 times
int Example(int num)
{
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
return num;
}</pawn>

==By Reference==
Let's reuse the above example to use reference passing. Observe the new native below:

<pawn>/**
* Subtracts one from the given number, by reference.
*
* @param num Number to subtract, by reference.
* @noreturn
*/
native int Decrement(int& num);</pawn>

Note the ampersand ('&') before the parameter name -- this specifies that it is passed by reference. Now, let's see how this would look in our script:

<pawn>
int Example(int num)
{
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
return num;
}</pawn>

In this example, <tt>Decrement</tt> is acting on the <tt>num</tt> variable ''itself'', not a copy of it. Thus, num will decrease 5 times. In fact, scripts can even do this internally. We can shorten the example even more:

<pawn>int Example(int& num)
{
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
}</pawn>

==When to use By Ref==
There is a misconception that passing by reference is always better than by value. After all, copying data sounds excessive. However, by value in SourcePawn only works on 32bit values, and thus copying the value is inherent to the processor, and trivial.

On the other hand, passing by reference is slightly more expensive. First, the compiler has to generate a little extra code to compute the local address of the variable. Second, the native code itself has to translate the local address to a ''real virtual address'' (native memory).

It is a good idea to only use by reference when you need it. A common usage is when you need to return more than one piece of data, and you can't fit it into the return value of your native or function. In this case, by reference is ideal.

=Integers/Floats=

==By Value==
Natives based purely on by-value floating point or integer input are generally the easiest to make. Let's take a simple function which takes in a Float and an integer, and returns a Float:
<pawn>/**
* Raises a number to an integer power.
*
* @param fNum Base number (Float).
* @param exp Exponent (integer).
* @return Computed exponent result as a Float.
*/
native float FloatIntPower(float fNum, int exp);</pawn>

An implementation of this native might look like:
<cpp>#include <stdlib.h>

static cell_t sm_FloatIntPower(IPluginContext *pContext, const cell_t *params)
{
float f1 = sp_ctof(params[1]);
int num = params[2];

float result = (float)pow(f1, (double)f2);
return sp_ftoc(result);
}</cpp>

Integers, as we saw in the introduction, are accessed from the parameter stack normally. Floats, however, must be ''reinterpret casted'' from a <tt>cell_t</tt> to <tt>float</tt>. Two inline functions are provided for this:
*<tt>sp_ctof</tt>: Convert a <tt>cell_t</tt> to a <tt>float</tt>.
*<tt>sp_ftoc</tt>: Convert a <tt>float</tt> to a <tt>cell_t</tt>.

==By Reference==
By reference is a little more tricky. Let's first implement our <tt>Decrement</tt> native from earlier. A refresher:
<pawn>native void Decrement(int& num);</pawn>

If we try to use our above code, <tt>params[1]</tt> will no longer hold a value. Instead, it holds a ''local address'' in the plugin. We must use the <tt>LocalToPhysAddr</tt> function to translate this. It takes in a local address and returns back a physical pointer, which we can then modify. This will modify the value in the script.

<cpp>static cell_t sm_Decrement(IPluginContext *pContext, const cell_t *params)
{
cell_t *addr;

/* Translate the address. */
pContext->LocalToPhysAddr(params[1], &addr);

/* Decrement the number */
*addr -= 1;

/* We have to return something, even if the plugin doesn't use the value */
return 1;
}</cpp>
''Note: LocalToPhysAddr can return an error code. For all practical purposes, this will never error, unless there is some memory or corruption issue, so checking it isn't necessary.''

This works the same way for floats. Let's say we change our native to this:
<pawn>/**
* Decrements a Float by an integer, and stores the result by reference.
*
* @param fNum Float number to decrement (by ref).
* @param decamt Amount to decrement by.
* @noreturn
*/
native void Decrement(float& fNum, int decamt);
</pawn>

This example is fairly contrived -- our native simply performs a subtract operation. But let's look at the implementation:

<cpp>static cell_t sm_Decrement(IPluginContext *pContext, const cell_t *params)
{
cell_t *addr;

/* Translate the address. */
pContext->LocalToPhysAddr(params[1], &addr);

/* Get the value */
float val = sp_ctof(*addr);
/* Decrement */
val -= params[2];
/* Store back */
*addr = sp_ftoc(val);

/* We have to return something, even if the plugin doesn't use the value */
return 1;
}</cpp>

Note that even though the first parameter was passed by reference, the second was not, and is accessed normally.

=Arrays=

==Basic Arrays==
Arrays are always passed by reference. The first example is an array which contains a list of numbers to sum. Observe the native:
<pawn>/**
* Averages an array of numbers.
*
* @param array Array of numbers to average.
* @param num Number of slots in the array.
* @return Average number as a Float.
*/
native float Average(int[] array, int num);</pawn>

Usage might look like:
<pawn>float Example()
{
int numbers[5] = {5, 6, 1, 3, 8};
return Average(numbers, 5);
}</pawn>

The implementation, like the by ref examples above, requires <tt>LocalToPhysAddr</tt>:
<cpp>static cell_t sm_Average(IPluginContext *pContext, cell_t *params)
{
cell_t *array;
float sum = 0.0f, average;

if (params[2] < 1)
{
/* 0 works without sp_ftoc() */
return 0;
}

pContext->LocalToPhysAddr(params[1], &array);
for (cell_t i=0; i<params[2]; i++)
{
sum += array[i];
}

average = sum / params[2];

return sp_ftoc(average);
}</cpp>

==Float Arrays==
This works similarly for Float arrays. Let's take Vectors an example, with the following native:
<pawn>/**
* Adds two vectors together.
*
* @param r Array to store the result in.
* @param v1 First vector to add.
* @param v2 Second vector to add.
* @noreturn
*/
native void AddVectors(float r[3], const float v1[3], const float v2[3]);</pawn>

The implementation is straightforward:
<cpp>static cell_t sm_AddVectors(IPluginContext *pContext, cell_t *params)
{
cell_t *v1, *v2;
float result[3];

pContext->LocalToPhysAddr(params[2], &v1);
pContext->LocalToPhysAddr(params[3], &v2);

result[0] = sp_ctof(v1[0]) + sp_ctof(v2[0]);
result[1] = sp_ctof(v1[1]) + sp_ctof(v2[1]);
result[2] = sp_ctof(v1[2]) + sp_ctof(v2[2]);

cell_t *r;
pContext->LocalToPhysAddr(params[1], &r);
r[0] = sp_ftoc(result[0]);
r[1] = sp_ftoc(result[1]);
r[2] = sp_ftoc(result[2]);

return 1;
}</cpp>

Note that we only store the result after we have computed the input, rather than store directly. This is a bit more work, but is good practice in case users re-use data inputs, and risk overwriting inputs as they are written. For example:

<pawn>float origin[3];
AddVectors(origin, origin, origin);</pawn>

=Strings=
Strings are just like arrays, in that they are passed by reference. The only difference is that each character is stored in a byte, not a 32bit <tt>cell_t</tt>. However, to make coding a bit easier for you, the coder, there are separate functions.
*<tt>LocalToString</tt>: Converts a local address to a physical string address.
*<tt>StringToLocal</tt>: Copies a physical string into a local address buffer.
*<tt>StringToLocalUTF8</tt>: Same as <tt>StringToLocal</tt>, but only copies the maximum amount possible without cutting off any multi byte characters.

First, let's take an easy example: the infamous strlen.
<pawn>/**
* Returns the length of a string.
*
* @param string String to calculate.
* @return Number of bytes in the string.
*/
native int strlen(const char[] string);</pawn>

Implementation:
<cpp>static cell_t sm_StrLen(IPluginContext *pContext, cell_t *params)
{
char *str;
pContext->LocalToString(params[1], &str);
return strlen(str);
}</cpp>

Now, let's say we want to modify the string. There is an important note here: since the string is passed by reference, when you modify the string, it is also modified in the plugin. This is a huge difference from AMX Mod X, where strings were essentially by value in most cases, and you had to copy results back.

Thus, if we wanted to copy a new result into <tt>str</tt> in the above implementation, it would be very easy. If we were implementing <tt>strcpy()</tt>, we would have to use <tt>memmove()</tt> to make sure there are no overlaps. Let's do this:
<pawn>/**
* Copies one string onto another.
*
* @param dest Destination buffer to copy to.
* @param length Maximum length of the buffer.
* @param source Source to copy from.
* @noreturn
*/
native void StringCopy(char[] dest, int length, const char[] source);</pawn>

Implementation using <tt>memmove</tt> for safety:
<cpp>static cell_t sm_StringCopy(IPluginContext *pContext, cell_t *params)
{
char *dest, *src;
size_t len;

pContext->LocalToString(params[1], &dest);
pContext->LocalToString(params[3], &src);

/* Perform bounds checking */
len = strlen(src);
if (len >= params[2])
{
len = params[2] - 1;
} else {
len = params[2];
}

/* Copy */
memmove(dest, src, len);

dest[len] = '\0';

return 1;
}</cpp>

We can also use <tt>StringToLocal</tt>, which would requires a temporary buffer for the original string:
<cpp>static cell_t sm_StringCopy(IPluginContext *pContext, cell_t *params)
{
char *src;
char buffer[2048];
size_t len;

pContext->LocalToString(params[3], &src);

snprintf(buffer, sizeof(buffer), "%s", src);
pContext->StringToLocal(params[1], params[2], buffer);

return 1;
}</cpp>

Generally, you will be using <tt>StringToLocal</tt> for setting strings from outside sources, because it calculates addresses and overflows for you. However, you must make sure that you are not overwriting memory as you are reading it, or else programmers who are using certain types of array slicing may find themselves getting unexpected results.

=Advanced=
==Default Arguments==
Any type of parameter can have a default argument. For example, here is a native where every argument has a default parameter:
<pawn>native void RandomStuff(int a=0, float b=1.0, int& c=0, const char[] d="", int e[3] = {0,1,2});</pawn>

Note that even by-reference parameters can have default arguments, as shown above. This does not change the code; it just means the address will contain the default value.

Scripts can force default values. Example:
<pawn>native void RandomStuff(int a, int b, int c=0, int d=0);

void Example()
{
RandomStuff(1, 2, _, d);
}</pawn>

The underscore ('_') means "use the default value for this argument."

==Variable Arguments==
Variable arguments means any number of arguments can be passed. An example of this looks like:
<pawn>native FormatText(const char[] format, any ...);</pawn>

The <tt>...</tt> characters mean any number of parameters can follow.

'''There is one important note about variable arguments. They are always passed by reference.''' This means if you have a function which supports variable arguments, and an integer is passed, you will need to use <tt>LocalToPhysAddr</tt> as required with by reference parameters.

==Argument Counts/Backwards Compatibility==
In native handlers, the <tt>params</tt> array has a 0th index which stores the number of parameters it contains. This is useful for both Default Arguments and Variable Arguments.

For example, consider the following native:
<pawn>native void DoSomething(int index);</pawn>

Let's say that this native exists in plugins for six months. After that, you decide to add a new parameter. You want two conditions to be true after you release this update:
*Old plugins in binary form should still work on newer installations.
*Old plugins should still compile fine on the new API.

The second condition is solved by using default arguments. You should choose a value that will mimic the old functionality of the native.
<pawn>native void DoSomething(int index, int newparam = 0);</pawn>

Next, when changing the implementation, you should detect whether <tt>params[0]</tt> contains ''one parameter'' or ''two parameters''. If it only contains one, you know to use the old version. If it contains two, you know to use the later version and accept the second parameter.

Similarly, you can use the <tt>params[0]</tt> count to detect how many arguments were passed to a variable argument native. This is used primarily in [[Format Class Functions (SourceMod Scripting)|Format Class Functions]] for parameter-count validation.

=Throwing Errors/Invoking the Debugger=
Often, you will write a native and realize that you need to tell the plugin that a serious error has occurred. A good example of this is if you are writing a function which requires a player index, but that index is beyond the reasonable bounds for the maximum players in the server.

In this case, it is a good idea to throw a ''runtime error''. This is an error that halts the plugin and invokes a call trace from the debugger. The halt is not permanent, but it does break the execution flow of the current callback.

There are two ways to throw a native error: <tt>ThrowNativeErrorEx()</tt> or <tt>ThrowNativeError()</tt>. The former lets you specify a detailed error code from <tt>sp_vm_types.h</tt>. The latter is a helper function for generic errors, and it returns 0, allowing you to return with the function itself. For example:

<cpp>static cell_t GetPlayerFrags(IPluginContext *pContext, const cell_t *params)
{
if (params[1] < 0 || params[1] > maxplayers)
{
return pContext->ThrowNativeError("Invalid client index: %d", params[1]);
}
/* ... rest of code ... */
}</cpp>

Don't worry about including extra information, such as your native name or the module name. The debugger knows all of this information and will decide what to print to the user.

[[Category:SourceMod Development]]

Introduction to SourcePawn 1.7

2015-03-09T13:19:55Z

Nergal: /* Expressions */

This guide is designed to give you a very basic overview to fundamentals of scripting in SourcePawn. [[Pawn]] is a "scripting" language used to embed functionality in other programs. That means it is not a standalone language, like C++ or Java, and its details will differ based on the application. SourcePawn is the version of Pawn used in [[SourceMod]].

This guide does not tell you how to write SourceMod plugins; it is intended as an overview of the syntax and semantics of the language instead. Read the separate article, [[Introduction to SourceMod Plugins]] for SourceMod API specifics.

=Non-Programmer Intro=
This section is intended for non-programmers. If you're still confused, you may want to pick up a book on another language, such as PHP, Python, or Java, to get a better idea of what programming is like.

==Symbols/Keywords==
A symbol is a series of letters, numbers, and/or underscores, that uniquely represents something. Symbols are case-sensitive, and usually start with a letter.

There are a few reserved symbols that have special meaning. For example, <tt>if</tt>, <tt>for</tt>, and <tt>return</tt> are special constructs in the language that will explained later. They cannot be used as symbol names.

==Variables==
There a few important constructs you should know before you begin to script. The first is a '''variable'''. A variable is a symbol, or name, that holds data. For example, the variable "a" could hold the number "2", "16", "0", et cetera. Since a variable holds data, it also allocates the memory needed to store that data.

In addition to a name, variables have a '''type'''. A type tells the program how to interpret the data, and how much memory the data will use. Pawn has three types of data that are most commonly used:
* Integers, using the <tt>int</tt> type. Integer types may store a whole number from -2147483648 to 2147483647.
* Floats, using the <tt>float</tt> type. Float types may store fractional numbers in a huge range, though they are not as precise as integers.
* Characters, using the <tt>char</tt> type. Character types store one byte of character information, typically an [http://www.asciitable.com/ ASCII] character.
* Booleans, using the <tt>bool</tt> type. Booleans store either true or false.

Example of creating variables and assigning values:

<pawn>int money = 5400;
float percent = 67.3;
bool enabled = false;
</pawn>

==Functions==
The next important concept is '''functions'''. Functions are symbols or names that perform an action. When you invoke, or call them, they carry out a specific sequence of code and then return a result. There are a few types of functions, but every function is activated the same way. Example:

<pawn>
show(56); // Calls the "show" function, and gives it the number 56.
enable(); // Calls the "s "enable" function with no values.
bool visible = show(a); //Calls the "show" function, stores its result in a variable.
</pawn>

Every piece of data passed to a function is called a '''parameter'''. A function can have any number of parameters (there is a "reasonable" limit of 32 in SourceMod). Parameters will be explained further in the article.

==Comments==
Note any text that appears after a "//" is considered a "comment" and is not actual code. There are two comment styles:
*<tt>//</tt> - Double slash, everything following on that line is ignored.
*<tt>/* */</tt> - Multi-line comment, everything in between the asterisks is ignored. You cannot nest these.

==Block Coding==
The next concept is block coding. You can group code into "blocks" separated by { and }. This effectively makes one large block of code act as one statement. For example:

<pawn>{
here;
is;
some;
code;
}</pawn>

Block coding using braces is used everywhere in programming. Blocks of code can be nested within each other. It is a good idea to adapt a consistent and readable indentation style early on to prevent spaghetti-looking code.

=Language Paradigms=
Pawn may seem similar to other languages, like C, but it has fundamental differences. It is not important that you immediately understand these differences, but they may be helpful if you're familiar with another language already.
*'''Pawn is sort of typed.''' Before SourceMod 1.7, Pawn did not have types. Older code and older natives will reflect this by using tags and the <tt>new</tt> keyword. As of SourceMod 1.7, we recommend that all code use types. For more information see [[SourcePawn Transitional Syntax]].
*'''Pawn is not garbage collected.''' Pawn, as a language, has no built-in memory allocation, and thus has no garbage. If a function allocates memory, you may be responsible for freeing it.
*'''Pawn is not object oriented.''' Pawn does not have structs or objects. As of SourceMod 1.7, it has limited sugaring for treating some data types as objects, but users cannot create their own objects or classes.
*'''Pawn is single-threaded.''' As of this writing, Pawn is not thread safe.
*'''Pawn is compiled.''' Pawn is compiled to an intermediate, machine-independent code, which is stored in a ".smx" file. When loading .smx files, SourceMod translates this code to machine code for the platform and CPU it's running on.

Early language design decisions were made by ITB CompuPhase. It is designed for low-level embedded devices and is thus very small and very fast.

=Variables=
Pawn currently supports the following basic variable types:
*<tt>bool</tt> - true or false.
*<tt>char</tt> - an 8-bit ASCII character.
*<tt>int</tt> - a 32-bit signed integer.
*<tt>float</tt> - a 32-bit IEEE-754 floating point number.
*<tt>Handle</tt> - the base type of a SourceMod object

Other types may exist when defined in include files - for example, enums create new types for named integers, and many types derive from <tt>Handle</tt>.

Strings, currently, are 0-terminated arrays of <tt>char</tt>s. They're described a little further ahead.

==Declaration==
Below we include some examples of variable declarations, both valid and invalid. Keep in mind that SourcePawn has recently added new syntax, and that's what's documented below. Older code may use older declaration syntax, which is no longer supported.

<pawn>
int a = 5;
float b = 5.0;
bool c = true;
bool d = false;
</pawn>

Invalid variable usage:
<pawn>
int a = 5.0; // Type mismatch. 5.0 is a float.
float b = 5; // Type mismatch. 5 is an integer.
</pawn>

If a variable is not assigned upon declaration, it will be set to 0. For example:
<pawn>
int a; // Set to 0
float b; // Set to 0.0
bool c; // Set to false
</pawn>

==Assignment==
Variables can be re-assigned data after they are created. For example:
<pawn>int a;
float b;
bool c;

a = 5;
b = 5.0;
c = true;
</pawn>

=Arrays=
An array is a sequence of data in a list. Arrays are useful for storing multiple pieces of data in one variable, or mapping one type of data to another.

==Declaration==
An array is declared using brackets. Some examples of arrays:
<pawn>
int players[32]; // Stores 32 integers.
float origin[3]; // Stores 3 floating point numbers
</pawn>

By default, arrays are initialized to 0. You can assign them different default values, however:
<pawn>
int numbers[5] = {1, 2, 3, 4, 5}; // Stores 1, 2, 3, 4, 5.
float origin[3] = {1.0, 2.0, 3.0}; // Stores 1.0, 2.0, 3.0.
</pawn>

You can leave out the array size if you're going to pre-assign data to it. For example:
<pawn>
int numbers[] = {1, 3, 5, 7, 9};
</pawn>

The compiler will automatically deduce that you intended an array of size 5.

When array is declared with brackets after its name, Pawn considers that array to have a '''fixed size'''. The size of a fixed-size array is always known. Some arrays can be '''dynamically sized''', by putting the brackets before the name. For example,

<pawn>
int[] numbers = new int[MaxClients]
</pawn>

This creates an array of size <tt>MaxClients</tt>, which could be anything, so the size of the array is not known until the array is allocated.

==Usage==
Using an array is just like using a normal variable. The only difference is the array must be '''indexed'''. Indexing an array means choosing the element which you wish to use.

For example, here is an example of the above code using indexes:
<pawn>
int numbers[5];
float origin[3];

numbers[0] = 1;
numbers[1] = 2;
numbers[2] = 3;
numbers[3] = 4;
numbers[4] = 5;
origin[0] = 1.0;
origin[1] = 2.0;
origin[2] = 3.0;
</pawn>

Note that the '''index''' is what's in between the brackets. The index always starts from 0. That is, if an array has N elements, its valid indexes are from 0 to N-1. Accessing the data at these indexes works like a normal variable.

Using an incorrect index will cause an error. For example:
<pawn>
int numbers[5];

numbers[5] = 20;</pawn>

This may look correct, but 5 is not a valid index. The highest valid index is 4.

You can use any expression as an index. For example:
<pawn>int a, numbers[5];

a = 1; // Set a = 1
numbers[a] = 4; // Set numbers[1] = 4
numbers[numbers[a]] = 2; // Set numbers[4] = 2
</pawn>

Expressions will be discussed in depth later in the article.

=Strings=
Strings are a construct for storing text (or even raw binary data). A string is just an array of characters, except that the final character must be 0 (called the null terminator). Without a null terminator, Pawn would not know where to stop reading the string. All strings are [http://en.wikipedia.org/wiki/UTF-8 UTF-8] in SourcePawn.

In general, you must have an idea of how large a string will be before you store it. SourcePawn does not yet have the capability of pre-determining storage space for strings.

==Usage==
Strings are usually declared as arrays. For example:
<pawn>
char message[] = "Hello!";
char clams[6] = "Clams";
</pawn>

These are equivalent to doing:
<pawn>
char message[7];
char clams[6];

message[0] = 'H';
message[1] = 'e';
message[2] = 'l';
message[3] = 'l';
message[4] = 'o';
message[5] = '!';
message[6] = 0;
clams[0] = 'C';
clams[1] = 'l';
clams[2] = 'a';
clams[3] = 'm';
clams[4] = 's';
clams[5] = 0;
</pawn>

Although strings are rarely initialized in this manner, it is very important to remember the concept of the null terminator, which signals the end of a string. The compiler, and most SourceMod functions will automatically null-terminate for you, so it is mainly important when manipulating strings directly.

Note that a string is enclosed in double-quotes, but a character is enclosed in single quotes.

==Characters==
A character of text can be used in either a String or a cell. For example:
<pawn>char text[] = "Crab";
char clam'

clam = 'D'; //Set clam to 'D'
text[0] = 'A'; //Change the 'C' to 'A', it is now 'Arab'
clam = text[0]; //Set clam to 'A'
text[1] = clam; //Change the 'r' to 'A', is is now 'AAab'
</pawn>

What you can't do is mix character arrays with strings. The internal storage is different. For example:
<pawn>
int clams[] = "Clams"; // Invalid.
int clams[] = {'C', 'l', 'a', 'm', 's', 0}; // Valid, but NOT A STRING.
</pawn>

=Functions=
Functions, as stated before, are isolated blocks of code that perform an action. They can be invoked, or '''called''', with '''parameters''' that give specific options.

There are two types of ways functions are called:
*'''direct call''' - You specifically call a function in your code.
*'''callback''' - The application calls a function in your code, as if it were an event trigger.

There are six types of functions:
*'''native''': A direct, internal function provided by the application.
*'''public''': A callback function that is visible to the application and other scripts.
*'''normal''': A normal function that only you can call.
*'''static''': The scope of this function is restricted to the current file, can be used in combination with stock.
*'''stock''': A normal function provided by an include file. If unused, it won't be compiled.
*'''forward''': This function is a global event provided by the application. If you implement it, it will be a callback.

All code in Pawn must exist in functions. This is in contrast to languages like PHP, Perl, and Python which let you write global code. That is because Pawn is a callback-based language: it responds to actions from a parent application, and functions must be written to handle those actions. Although our examples often contain free-floating code, this is purely for demonstration purposes. Free-floating code in our examples implies the code is part of some function.

==Declaration==
Unlike variables, functions do not need to be declared before you use them. Functions have two pieces, the '''signature''' and the '''body'''. The signature contains the name of your function and the parameters it will accept. The body is the contents of its code.

Example of a function:
<pawn>
void AddTwoNumbers(int first, int second)
{
int sum = first + second;
return sum;
}</pawn>

This is a simple function. The prototype is this line:
<pawn>void AddTwoNumbers(int first, int second)</pawn>

Broken down, it means:
*<tt>int</tt> - Return value type (integer).
*<tt>AddTwoNumbers</tt> - Name of the function.
*<tt>int first</tt> - First parameter, an integer.
*<tt>int second</tt> - Second parameter, an integer.

The body is a block of code. It creates a new variable, called <tt>sum</tt>, and assigns it the value of the two parameters added together (more on expressions later). The important thing to notice is the <tt>return</tt> statement, which tells the function to end and return a value to the caller of the function. All functions return something on completion, unless they return a special type called <tt>void</tt>.

A function can accept any type of input, and it can return any non-array type.

You can, of course, pass variables to functions:
<pawn>int numbers[3] = {1, 2, 0};

numbers[2] = AddTwoNumbers(numbers[0], numbers[1]);</pawn>

Note that cells are passed '''by value'''. That is, their value cannot be changed by the function. For example:
<pawn>int a = 5;

ChangeValue(a);

ChangeValue(b)
{
b = 5;
}</pawn>

This code would not change the value of <tt>a</tt>. That is because a copy of the value in <tt>a</tt> is passed instead of <tt>a</tt> itself.

More examples of functions will be provided throughout the article.

==Publics==
Public functions are used to implement callbacks. You should not create a public function unless it is specifically implementing a callback. For example, here are two callbacks from <tt>sourcemod.inc</tt>:

<pawn>forward void OnPluginStart();
forward void OnClientDisconnected(int client);</pawn>

To implement and receive these two events, you would write functions as such:

<pawn>public void OnPluginStart()
{
/* Code here */
}

public void OnClientDisconnected(int client)
{
/* Code here */
}</pawn>

The '''public''' keyword signals to the parent application that it should attach the function to the appropriate forwarded event.

==Natives==
Natives are builtin functions provided by SourceMod. You can call them as if they were a normal function. For example, SourceMod has the following function:

<pawn>native float FloatRound(float num);</pawn>

It can be called like so:
<pawn>int rounded = FloatRound(5.2); // rounded will be 5</pawn>

==Array Parameters==
You can pass arrays or Strings as parameters. It is important to note that these are passed '''by reference'''. That is, rather than making a copy of the data, the data is referenced directly. There is a simple way of explaining this more concretely.

<pawn>
int example[] = {1, 2, 3, 4, 5};

ChangeArray(example, 2, 29);

void ChangeArray(int[] array, int index, int value)
{
array[index] = value;
}</pawn>

The function sets the given index in the array to a given value. When it is run on our example array, it changes index 2 to from the value 3 to 29. I.e.:
<pawn>example[2] = 29;</pawn>

Note two important things here. First, arrays are not copied when they are passed to functions - they are passed ''by reference'', so the view of the array is consistent at all times. Second, the brackets changed position in our function signature. This is because our function accepts an array of any size, and since we don't know the size, we must use the dynamic array syntax.

To prevent an array from being modified in a function, you can mark it as <tt>const</tt>. This will raise an error on code that attempts to modify it. For example:

<pawn>void CantChangeArray(const array[], int index, int value)
{
array[index] = value; //Won't compile
}</pawn>

It is a good idea to use <tt>const</tt> in array parameters if you know the array won't be modified; this can prevent coding mistakes.

=Expressions=
Expressions are exactly the same as they are in mathematics. They are groups of operators/symbols which evaluate to one piece of data. They are often parenthetical (comprised of parenthesis). They contain a strict "order of operations." They can contain variables, functions, numbers, and expressions themselves can be nested inside other expressions, or even passed as parameters.

The simplest expression is a single number. For example:
<pawn>
0; //Returns the number 0
(0); //Returns the number 0 as well
</pawn>

Although expressions can return any value, they are also said to either return ''zero or non-zero''. In that sense, ''zero'' is ''false'', and ''non-zero'' is ''true''. For example, -1 is '''true''' in Pawn, since it is non-zero. Do not assume negative numbers are false.

The order of operations for expressions is similar to C. PMDAS: Parenthesis, Multiplication, Division, Addition, Subtraction. Here are some example expressions:
<pawn>
5 + 6; //Evaluates to 11
5 * 6 + 3; //Evaluates to 33
5 * (6 + 3); //Evaluates to 45
5.0 + 2.3; //Evaluates to 7.3
(5 * 6) % 7; //Modulo operator, evaluates to 2
(5 + 3) / 2 * 4 - 9; //Evaluates to -8
</pawn>

As noted, expressions can contain variables, or even functions:
<pawn>
int a = 5 * 6;
int b = a * 3; //Evaluates to 90
int c = AddTwoNumbers(a, b) + (a * b);
</pawn>

Note: String manipulation routines may be found in the string.inc file located in the include subdirectory. They may be browsed through the [http://docs.sourcemod.net/api/ API Reference] as well.

==Operators==
There are a few extra helpful operators in Pawn. The first set simplifies self-aggregation expressions. For example:
<pawn>new a = 5;

a = a + 5;</pawn>

Can be rewritten as:
<pawn>int a = 5;
a += 5;</pawn>

This is true of the following operators in Pawn:
*Four-function: *, /, -, +
*Bit-wise: |, &, ^, ~, <<, >>

Additionally, there are increment/decrement operators:
<pawn>a = a + 1;
a = a - 1;</pawn>

Can be simplified as:
<pawn>a++;
a--;</pawn>

As an advanced note, the ++ or -- can come before the variable (pre-increment, pre-decrement) or after the variable (post-increment, post-decrement). The difference is in how the rest of the expression containing them sees their result.

* ''Pre:'' The variable is incremented before evaluation, and the rest of the expression sees the new value.
* ''Post:'' The variable is incremented after evaluation, and the rest of the expression sees the old value.

In other words, <tt>a++</tt> evaluates to the value of <tt>a</tt> while <tt>++a</tt> evaluates to the value of <tt>a + 1</tt>. In both cases <tt>a</tt> is incremented by <tt>1</tt>.

For example:

<pawn>int a = 5;
int b = a++; // b = 5, a = 6 (1)
int c = ++a; // a = 7, c = 7 (2)
</pawn>

In (1) <tt>b</tt> is assigned <tt>a</tt>'s ''old'' value ''before'' it is incremented to <tt>6</tt>, but in (2) <tt>c</tt> is assigned <tt>a</tt>'s ''int'' value ''after'' it is incremented to <tt>7</tt>.

==Comparison Operators==
There are six operators for comparing two values numerically, and the result is either true (non-zero) or false (zero):
*<tt>a == b</tt> - True if a and b have the same value.
*<tt>a != b</tt> - True if a and b have different values.
*<tt>a > b</tt> - True if a is greater than b
*<tt>a >= b</tt> - True if a is greater than or equal to b
*<tt>a < b</tt> - True if a is less than b
*<tt>a <= b</tt> - True if a is less than or equal to b

For example:
<pawn>
(1 != 3); //Evaluates to true because 1 is not equal to 3.
(3 + 3 == 6); //Evaluates to true because 3+3 is 6.
(5 - 2 >= 4); //Evaluates to false because 3 is less than 4.
</pawn>

Note that these operators do not work on arrays or strings. That is, you cannot compare either using <tt>==</tt>.

==Truth Operators==
These truth values can be combined using three boolean operators:
*<tt>a && b</tt> - True if both a and b are true. False if a or b (or both) is false.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>&&</tt> !! 0 !! 1
|-
! 0
| 0 || 0
|-
! 1
| 0 || 1
|}
*<tt>a || b</tt> - True if a or b (or both) is true. False if both a and b are false.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt><nowiki>||</nowiki></tt> !! 0 !! 1
|-
! 0
| 0 || 1
|-
! 1
| 1 || 1
|}
*<tt>!a</tt> - True if a is false. False if a is true.
{| border="1" cellpadding="2" cellspacing="0" align="center"
! <tt>!</tt> !! 0 !! 1
|-
!
| 1 || 0
|}

For example:
<pawn>
(1 || 0); //Evaluates to true because the expression 1 is true
(1 && 0); //Evaluates to false because the expression 0 is false
(!1 || 0); //Evaluates to false because !1 is false.
</pawn>

==Left/Right Values==
Two important concepts are left-hand and right-hand values, or l-values and r-values. An l-value is what appears on the left-hand side of a variable assignment, and an r-value is what appears on the right side of a variable assignment.

For example:
<pawn>
int a = 5;</pawn>

In this example <tt>a</tt> is an l-value and <tt>5</tt> is an r-value.

The rules:
*'''Expressions are never l-values'''.
*'''Variables are both l-values and r-values'''.

=Conditionals=
Conditional statements let you only run code if a certain condition is matched.

==If Statements==
If statements test one or more conditions. For example:

<pawn>
if (a == 5)
{
/* Code that will run if the expression was true */
}</pawn>

They can be extended to handle more cases as well:
<pawn>
if (a == 5)
{
/* Code */
}
else if (a == 6)
{
/* Code */
}
else if (a == 7)
{
/* Code */
}</pawn>

You can also handle the case of no expression being matched. For example:
<pawn>
if (a == 5)
{
/* Code */
}
else
{
/* Code that will run if no expressions were true */
}</pawn>

==Switch Statements==
Switch statements are restricted if statements. They test one expression for a series of possible values. For example:

<pawn>
switch (a)
{
case 5:
{
/* code */
}
case 6:
{
/* code */
}
case 7:
{
/* code */
}
case 8, 9, 10:
{
/* Code */
}
default:
{
/* will run if no case matched */
}
}</pawn>

Unlike some other languages, switches are not fall-through. That is, multiple cases will never be run. When a case matches its code is executed, and the switch is then immediately terminated.

=Loops=
Loops allow you to conveniently repeat a block of code while a given condition remains true.

==For Loops==
For loops are loops which have four parts:
*The '''initialization''' statement - run once before the first loop.
*The '''condition''' statement - checks whether the next loop should run, including the first one. The loop terminates when this expression evaluates to false.
*The '''iteration''' statement - run after each loop.
*The '''body''' block - run each time the '''condition''' statement evaluates to true.

<pawn>
for ( /* initialization */ ; /* condition */ ; /* iteration */ )
{
/* body */
}
</pawn>

A simple example is a function to sum an array:
<pawn>
new array[10] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
new sum = SumArray(array, 10);

SumArray(const array[], count)
{
new total;

for (new i = 0; i < count; i++)
{
total += array[i];
}

return total;
}</pawn>

Broken down:
*<tt>new i = 0</tt> - Creates a new variable for the loop, sets it to 0.
*<tt>i < count</tt> - Only runs the loop if <tt>i</tt> is less than <tt>count</tt>. This ensures that the loop stops reading at a certain point. In this case, we don't want to read invalid indexes in the array.
*<tt>i++</tt> - Increments <tt>i</tt> by one after each loop. This ensures that the loop doesn't run forever; eventually <tt>i</tt> will become too big and the loop will end.

Thus, the <tt>SumArray</tt> function will loop through each valid index of the array, each time adding that value of the array into a sum. For loops are very common for processing arrays like this.

==While Loops==
While loops are less common than for loops but are actually the simplest possible loop. They have only two parts:
*The '''condition''' statement - checked before each loop. The loop terminates when it evaluates to false.
*The '''body''' block - run each time through the loop.

<pawn>
while ( /* condition */ )
{
/* body */
}
</pawn>

As long as the condition expression remains true, the loop will continue. Every for loop can be rewritten as a while loop:

<pawn>
/* initialization */
while ( /* condition */ )
{
/* body */
/* iteration */
}
</pawn>

Here is the previous for loop rewritten as a while loop:
<pawn>
SumArray(const array[], count)
{
new total, i;

while (i < count)
{
total += array[i];
i++;
}

return total;
}</pawn>

There are also '''do...while''' loops which are even less common. These are the same as while loops except the condition check is AFTER each loop, rather than before. This means the loop is always run at least once. For example:

<pawn>
do
{
/* body */
}
while ( /* condition */ );
</pawn>

==Loop Control==
There are two cases in which you want to selectively control a loop:
*'''skipping''' one iteration of the loop but continuing as normal, or;
*'''breaking''' the loop entirely before it's finished.

Let's say you have a function which takes in an array and searches for a matching number. You want it to stop once the number is found:
<pawn>
/**
* Returns the array index where the value is, or -1 if not found.
*/
SearchInArray(const array[], count, value)
{
new index = -1;

for (new i = 0; i < count; i++)
{
if (array[i] == value)
{
index = i;
break;
}
}

return index;
}</pawn>

Certainly, this function could simply <tt>return i</tt> instead, but the example shows how <tt>break</tt> will terminate the loop.

Similarly, the <tt>continue</tt> keyword skips an iteration of a loop. For example, let's say we wanted to sum all even numbers:
<pawn>
SumEvenNumbers(const array[], count)
{
new sum;

for (new i = 0; i < count; i++)
{
/* If divisibility by 2 is 1, we know it's odd */
if (array[i] % 2 == 1)
{
/* Skip the rest of this loop iteration */
continue;
}
sum += array[i];
}

return sum;
}</pawn>

=Scope=
Scope refers to the '''visibility''' of code. That is, code at one level may not be "visible" to code at another level. For example:

<pawn>
new A, B, C;

Function1()
{
new B;

Function2();
}

Function2()
{
new C;
}</pawn>

In this example, <tt>A</tt>, <tt>B</tt>, and <tt>C</tt> exist at '''global scope'''. They can be seen by any function. However, the <tt>B</tt> in <tt>Function1</tt> is not the same variable as the <tt>B</tt> at the global level. Instead, it is at '''local scope''', and is thus a '''local variable'''.

Similarly, <tt>Function1</tt> and <tt>Function2</tt> know nothing about each other's variables.

Not only is the variable private to <tt>Function1</tt>, but it is re-created each time the function is invoked. Imagine this:
<pawn>
Function1()
{
new B;

Function1();
}</pawn>

In the above example, <tt>Function1</tt> calls itself. Of course, this is infinite recursion (a bad thing), but the idea is that each time the function runs, there is a new copy of <tt>B</tt>. When the function ends, <tt>B</tt> is destroyed, and the value is lost.

This property can be simplified by saying that a variable's scope is equal to the nesting level it is in. That is, a variable at global scope is visible globally to all functions. A variable at local scope is visible to all code blocks "beneath" its nesting level. For example:

<pawn>Function1()
{
new A;

if (A)
{
A = 5;
}
}</pawn>

The above code is valid since A's scope extends throughout the function. The following code, however, is not valid:
<pawn>
Function1()
{
new A;

if (A)
{
new B = 5;
}

B = 5;
}</pawn>

Notice that <tt>B</tt> is declared in a new code block. That means <tt>B</tt> is only accessible to that code block (and all sub-blocks nested within). As soon as the code block terminates, <tt>B</tt> is no longer valid.

=Dynamic Arrays=
Dynamic arrays are arrays which don't have a hardcoded size. For example:

<pawn>Function1(size)
{
new array[size];

/* Code */
}</pawn>

Dynamic arrays can have any expression as their size as long as the expression evaluates to a number larger than 0. Like normal arrays, SourcePawn does not know the array size after it is created; you have to save it if you want it later.

Dynamic arrays are only valid at the local scope level, since code cannot exist globally.

=Extended Variable Declarations=
Variables can be declared in more ways than simply <tt>new</tt>.

==decl==
===Purpose===
By default, all variables in Pawn are initialized to zero. If there is an explicit initializer, the variable is initialized to the expression after the <tt>=</tt> token. At a local scope, this can be a run-time expense. The <tt>decl</tt> keyword (which is only valid at local scope) was introduced to let users decide if they want variables initialized or not.

Note: <tt>decl</tt> should not be used on single cell variables. There is almost never any benefit.

===Explanation===
For example:

<pawn>
new c = 5;
new d;
new String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

In this code, <tt>c</tt> is equal to 5 and <tt>d</tt> is equal to 0. The run-time expense of this initialization is negligible. However, <tt>blah</tt> is a large array, and the expense of initializing the entire array to 0s could be detrimental in certain situations.

Note that <tt>blah</tt> does not need to be zeroed. In between being declared with <tt>new</tt> and stored with <tt>Format()</tt>, <tt>blah</tt> is never loaded or read. Thus this code would be more efficiently written as:

<pawn>
new c = 5;
new d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

===Caveats===
The downside to <tt>decl</tt> is that it means its variables will start with "garbage" contents. For example, if we were to use:

<pawn>
new c = 5;
new d;
decl String:blah[512];

PrintToServer("%s", blah);

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

This code may crash the server, because <tt>blah</tt> may be completely corrupt (strings require a terminator, and that may not be present). Similarly, if we did:

<pawn>
new c = 5;
decl d;
decl String:blah[512];

Format(blah, sizeof(blah), "%d %d", c, d);
</pawn>

The value of <tt>d</tt> is now undefined. It could be any value, negative or positive.

Note that it is easy to efficiently make strings safe. The example below shows how to terminate a garbage string:
<pawn>
decl String:blah[512];

blah[0] = '\0';
</pawn>

===Golden Rules===
*'''Only use decl if in between declaring and loading/reading the value, you are absolutely sure there is at least one store/set operation that gives the variable valid data.'''
*'''Do not prematurely optimize.''' Likewise, there is no need to use <tt>decl</tt> on non-arrays, because there is no added expense for initializing a single cell value.

===Notes===
This example is NOT as efficient as a <tt>decl</tt>:
<pawn>
new String:blah[512] = "a";
</pawn>

Even though the string is only one character, the <tt>new</tt> operator guarantees the rest of the array will be zeroed as well.

Also note, it is valid to explicitly initialize a <tt>decl</tt> '''ONLY''' with strings:
<pawn>decl String:blah[512] = "a";</pawn>

However, any other tag will fail to compile, because the purpose of <tt>decl</tt> is to avoid any initialization:
<pawn>decl Float:blah[512] = {1.0};</pawn>

==static==
The <tt>static</tt> keyword is available at global and local scope. It has different meanings in each.

===Global static===
A global static variable can only be accessed from within the same file. For example:

<pawn>//file1.inc
static Float:g_value1 = 0.15f;

//file2.inc
static Float:g_value2 = 0.15f;</pawn>

If a plugin includes both of these files, it will not be able to use either <tt>g_value1</tt> or <tt>g_value2</tt>. This is a simple information hiding mechanism, and is similar to declaring member variables as <tt>private</tt> in languages like C++, Java, or C#.

===Local static===
A local static variable is a global variable that is only visible from its local lexical scope. For example:

<pawn>
MyFunction(inc)
{
static counter = -1;

counter += inc;

return counter;
}</pawn>

In this example, <tt>counter</tt> is technically a global variable -- it is initialized once to -1 and is never initialized again. It does not exist on the stack. That means each time <tt>MyFunction</tt> runs, the <tt>counter</tt> variable and its storage in memory is the same.

Take this example:
<pawn>MyFunction(5);
MyFunction(6);
MyFunction(10);</pawn>

In this example, <tt>counter</tt> will be <tt>-1 + 5 + 6 + 10</tt>, or <tt>20</tt>, because it persists beyond the frame of the function. Note this may pose problems for recursive functions: if your function may be recursive, then <tt>static</tt> is usually not a good idea unless your code is re-entrant.

The benefit of a local static variable is that you don't have to clutter your script with global variables. As long as the variable doesn't need to be read by another function, you can squirrel it inside the function and its persistence will be guaranteed.

Note that statics can exist in any local scope:

<pawn>
MyFunction(inc)
{
if (inc > 0)
{
static counter;
return (counter += inc);
}
return -1;
}</pawn>

[[Category:SourceMod Scripting]]

{{LanguageSwitch}}