Natives (SourceMod Development) - Revision history

Nergal: Updating pawn examples to newer syntax

2021-03-10T15:54:49Z

Updating pawn examples to newer syntax

DJ Tsunami: /* When to use By Ref */

2020-07-30T16:58:23Z

‎When to use By Ref

Backup at 09:33, 31 March 2015

2015-03-31T09:33:30Z

Brainstorm: /* By Reference */

2007-08-24T10:17:51Z

‎By Reference

Brainstorm: /* By Reference */

2007-08-24T10:17:33Z

‎By Reference

Pimpinjuice: /* Strings */

2007-08-08T00:09:31Z

‎Strings

Pimpinjuice: /* Strings */

2007-08-07T23:46:26Z

‎Strings

BAILOPAN: /* When to use By Ref */

2007-07-14T02:39:27Z

‎When to use By Ref

FlyingMongoose: Undo revision 4742 by Special:Contributions/PydPcp (User talk:PydPcp)

2007-06-11T04:53:11Z

Undo revision 4742 by Special:Contributions/PydPcp (User talk:PydPcp)

Show changes

PydPcp at 19:48, 10 June 2007

2007-06-10T19:48:23Z

Show changes

@@ Line 19: / Line 19: @@
   * @return		Decremented number.
   */
-native Decrement(num);</pawn>
+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
-Example(num)
+int Example(int num)
+{
 	num = Decrement(num);
@@ Line 43: / Line 43: @@
   * @noreturn
   */
-native Decrement(&num);</pawn>
+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>Example(num)
+<pawn>
+{
 	Decrement(num);
@@ Line 59: / Line 60: @@
 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>Example(&num)
+<pawn>int Example(int& num)
+{
 	Decrement(num);
@@ Line 86: / Line 87: @@
   * @return		Computed exponent result as a Float.
   */
-native Float:FloatIntPower(Float:fNum, exp);</pawn>
+native float FloatIntPower(float fNum, int exp);</pawn>
 An implementation of this native might look like:
@@ Line 107: / Line 108: @@
 ==By Reference==
 By reference is a little more tricky.  Let's first implement our <tt>Decrement</tt> native from earlier.  A refresher:
-<pawn>native Decrement(&num);</pawn>
+<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.
@@ Line 134: / Line 135: @@
   * @noreturn
   */
-native Decrement(&Float:fNum, decamt);
+native void Decrement(float& fNum, int decamt);
 </pawn>
@@ Line 170: / Line 171: @@
   * @return		Average number as a Float.
   */
-native Float:Average(array[], num);</pawn>
+native float Average(int[] array, int num);</pawn>
 Usage might look like:
-<pawn>Example()
+<pawn>float Example()
+{
-	new numbers[5] = {5, 6, 1, 3, 8};
+	int numbers[5] = {5, 6, 1, 3, 8};
 	return Average(numbers, 5);
 }</pawn>
@@ Line 212: / Line 213: @@
   * @noreturn
   */
-native AddVectors(Float:r[3], const Float:v1[3], const Float:v2[3]);</pawn>
+native void AddVectors(float r[3], const float v1[3], const float v2[3]);</pawn>
 The implementation is straightforward:
@@ Line 238: / Line 239: @@
 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>new Float:origin[3];
+<pawn>float origin[3];
 AddVectors(origin, origin, origin);</pawn>
@@ Line 255: / Line 256: @@
   * @return		Number of bytes in the string.
   */
-native strlen(const String:string[]);</pawn>
+native int strlen(const char[] string);</pawn>
 Implementation:
@@ Line 276: / Line 277: @@
   * @noreturn
   */
-native StringCopy(String:dest[], length, const String:source);</pawn>
+native void StringCopy(char[] dest, int length, const char[] source);</pawn>
 Implementation using <tt>memmove</tt> for safety:
@@ Line 324: / Line 325: @@
 ==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 RandomStuff(a=0, Float:b=1.0f, &c=0, const String:d[]="", e[3] = {0,1,2});</pawn>
+<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.
+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 RandomStuff(a, b, c=0, d=0);
+<pawn>native void RandomStuff(int a, int b, int c=0, int d=0);
-Example()
+void Example()
+{
 	RandomStuff(1, 2, _, d);
@@ Line 340: / Line 341: @@
 ==Variable Arguments==
 Variable arguments means any number of arguments can be passed.  An example of this looks like:
-<pawn>native FormatText(const String:format[], {Float,String,_}:...);</pawn>
+<pawn>native FormatText(const char[] format, any ...);</pawn>
-The <tt>{Float,Handle_}:</tt> is a multi-tag specifier that means any extra parameters must be either a <tt>Float</tt>, <tt>String</tt>, or have no tag at all.  The <tt>...</tt> characters mean any number of parameters can follow.
+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.
@@ Line 350: / Line 351: @@
 For example, consider the following native:
-<pawn>native DoSomething(index);</pawn>
+<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:
@@ Line 357: / Line 358: @@
 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 DoSomething(index, newparam = 0);</pawn>
+<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.

@@ Line 69: / Line 69: @@
 ==When to use By Ref==
-There is a misconception that passing by reference is always better then 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.
+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).

@@ Line 86: / Line 86: @@
   * @return		Computed exponent result as a Float.
   */
-native FloatIntPower(Float:fNum, exp);</pawn>
+native Float:FloatIntPower(Float:fNum, exp);</pawn>
 An implementation of this native might look like:

@@ Line 121: / Line 121: @@
 	*addr -= 1;
-	/* We have to return something, even if the plugin doesn't the value */
+	/* We have to return something, even if the plugin doesn't use the value */
 	return 1;
 }</cpp>

@@ Line 153: / Line 153: @@
 	*addr = sp_ftoc(val);
-	/* We have to return something, even if the plugin doesn't the value */
+	/* 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=

@@ Line 311: / Line 311: @@
 	char buffer[2048];
 	size_t len;
-−
 	pContext->LocalToString(params[3], &src);
-−
-	pContext->StringToLocal(params[1], params[2], src);
+	snprintf(buffer, sizeof(buffer), "%s", src);
+	pContext->StringToLocal(params[1], params[2], buffer);
 	return 1;
 }</cpp>

@@ Line 71: / Line 71: @@
 There is a misconception that passing by reference is always better then 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 value 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).
+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=