-
Notifications
You must be signed in to change notification settings - Fork 18
Natives
native pp_hook_strlen(bool:hook);Dynamic strings can hold the null character, but AMX API function amx_StrLen ignores the characters that come after it. It is hooked by default to take null characters into account for dynamic strings, but it can be toggled.
native pp_hook_check_ref_args(bool:hook);Variadic functions (with ...) pass all arguments by reference, meaning amx_GetAddr will be used on the actual variable and not on the string address. It is possible to look into the variable if it contains a string address, but this decreases performance of every call and may misinterpret normal values. This function enables this behaviour.
native pawn_call_native(const function[], const format[], AnyTag:...);You can use this function to call a native function specified by its name. The native function must be used at least once in the whole script, or it will not be found. format accepts the same specifiers as CallLocalFunction, but enhanced with a couple of new ones. -1 is returned if the function cannot be found, and -2 is returned in case of an error.
native callback:pawn_register_callback(const callback[], const handler[], const additional_format[], {_,Float}:...);Registers a new handler for a callback specified by its name. The handler must be a public function, which will be called every time before callback is to be called in the script. Additional parameters may be prepended to the parameters of the callback, which could be used to keep a "state" together with the handler instance.
In addition to common CallLocalFunction specifiers, additional_format also supports a (array, its size is implied as the next argument), and e (the new event ID, the same that the function returns).
native pawn_unregister_callback(callback:id);Removes the handler specified by its ID so it will not be triggered anymore.
native String:str_new(const str[], str_create_mode:mode=str_preserve);Creates a new (local) dynamic string from a string buffer (packed or unpacked). The mode parameter specifies the combination of operations that should be performed on the string after creation. If str_truncate is set, the function will trim the cells to single bytes. If str_no_nulls is set, it will replace all occurences of the null character with 0x00FFFF00 (the highest byte is 0 so that it is not recognized as a packed string, but it is not a null character as understood by amx_StrLen.
native String:str_new_arr(const arr[], size=sizeof(arr), str_create_mode:mode=str_preserve);Creates a new (local) dynamic string from an array of cells. mode works the same way as for str_new.
native String:str_new_static(const str[], str_create_mode:mode=str_preserve, size=sizeof(str));This function is intended to be used for "static" strings, i.e. string literals ("abc") or auto-sized const strings (new const str[] = "abc";). It uses the size of the array to determine the length of the string. Thanks to this, null characters in the string are correctly included in the new string. This works for packed strings too, but null characters at the end may not be recognized.
By default, this native has an alias @ (if PP_NO_ALIASES is not defined).
native String:str_new_buf(size);Creates a new string constructed from the null character repeated size times. Intended for use as an output buffer.
native AmxString:str_addr(StringTag:str);This function is called by every assignment to an AmxString variable. It obtains the address of the string object relative to the data section of the AMX machine, so that it will be rejected by amx_GetAddr and handled by its hook.
native AmxStringBuffer:str_buf_addr(StringTag:str);Like str_addr, but returns the address of the character data of the string instead of the string instance itself. Useful for SA-MP native functions that do not call amx_GetAddr to obtain the address. Automatically called when a conversion to AmxStringBuffer occurs.
native GlobalString:str_to_global(StringTag:str);Moves a string to the global string pool, so that it will not be collected at the end of the top-level callback. It returns the argument (now a global string). Every assignment to GlobalString automatically calls it.
native String:str_to_local(StringTag:str);Moves the string back to the local string pool in the same manner as str_to_global. It is not called when an assignment from GlobalString to String occurs.
native bool:str_delete(StringTag:str);Frees the memory containing the string object. Works on local strings too, but it is not recommended. Returns true on success.
native bool:str_is_valid(StringTag:str);Returns true if the string pointer points to a valid (local or global) string. Should be only used as a last resort.
native str_len(StringTag:str);Returns the length of the string (in cells).
native str_get(StringTag:str, buffer[], size=sizeof(buffer), start=0, end=cellmax);Copies the cells from a dynamic string to a buffer. Start and end index in the string may be specified to copy only a part of the string. Returns the number of characters copied. start and end may be negative, meaning the offset from the end of the string.
native str_getc(StringTag:str, pos);Returns the cell/character at the specified position in the string, or INVALID_CHAR if pos is invalid.
native str_setc(StringTag:str, pos, value);Sets the cell/character at the specified position. Returns the original character, or INVALID_CHAR on failure.
native str_cmp(StringTag:str1, StringTag:str2);Compares two strings for (case-sensitive) equality. Returns a negative value if the first string precedes the second, a positive number if the first string follows the second, or 0 if they are equal. Used by the == operator.
native bool:str_empty(StringTag:str);Returns true if the string is empty (i.e. its length is zero).
native bool:str_equal(StringTag:str1, StringTag:str2);Return true if the two strings are equal (if they contain the same characters). Used by operator==(StringTag:,StringTag:).
native str_findc(StringTag:str, value, offset=0);Attempts to find a character in the string. Returns the first position of the character (starting from offset), or -1 on failure.
native str_find(StringTag:str, StringTag:value, offset=0);
Attempts to find a substring in the string. Returns the first position of the substring (starting from offset), or -1 on failure.
native String:str_int(val);Converts the specified integer value to a string (in base 10).
native String:str_float(Float:val);Converts the specified floating-point value to a string.
stock String:str_val({_,StringTags,Float}:val, tag=tagof(val));Returns a new string from the argument (can be integer, float or another string), or STRING_NULL if another tag is used. This function as an alias @@ but it is enabled only if PP_MORE_ALIASES is defined.
native String:str_cat(StringTag:str1, StringTag:str2);Concatenates two strings together, always producing a new string. Used by the + operator.
native String:str_sub(StringTag:str, start=0, end=cellmax);Returns a substring from the specified string.
native String:str_clone(StringTag:str);Clones the specified string, producing a new instance. Equivalent to str_sub with the default values.
native String:str_set(StringTag:target, StringTag:other);Modifies the characters of the first string to match the second string.
native String:str_append(StringTag:target, StringTag:other);Appends the characters of the second string to the first one.
native String:str_del(StringTag:target, start=0, end=cellmax);Deletes a part of the string as [start, end). If end is smaller than start, it leaves the specified range and deletes the surrounding parts.
native String:str_clear(StringTag:str);Removes all characters from the string. Equivalent to str_del with the default values.
native String:str_resize(StringTag:str, size, padding=0);Sets the length of the string. If the string will be longer, padding will fill the new cells.
native String:str_format(const format[], {StringTags,Float,_}:...);Analogous to standard format, except that it returns a dynamic string. All standard formatting specifiers are usable, and several new ones can be used. %S and %Q behave the same way as %s and %q, but they accept dynamic strings (String: and GlobalString:, not AmxString:). In addition, %o is included to format a number using base 8.
native String:str_format_s(StringTag:format, {StringTags,Float,_}:...);The same as above, but the format string is represented by a dynamic string.
native String:str_set_format(StringTag:target, const format[], {StringTags,Float,_}:...);Instead of creating a new string instance, this uses an existing instance to store the output.
native String:str_set_format_s(StringTag:target, StringTag:format, {StringTags,Float,_}:...);The same as above, but the format string is represented by a dynamic string.
native wait_ticks(ticks);Performs a non-blocking wait for the specified number of server ticks. If ticks is zero, returns immediately. If ticks is negative, waits forever.
native wait_ms(interval);Performs a non-blocking wait for the specified number of milliseconds. If interval is zero, returns immediately. If interval is negative, waits forever.
native task:task_new();Creates a new non-finished task and returns its ID.
native task_set_result(task:task, {_,Float,StringTags}:result);Sets the result of a task.
native task_get_result(task:task);Returns the result of a task as an untagged value. Use Float: for floating-point values.
native task:task_ticks(ticks);Creates a new task that will be completed after the specified number of ticks passes. If ticks is 0, the task is created as completed, or it is never completed if ticks is negative.
native task:task_ms(interval);Creates a new task that will be completed after the specified number of milliseconds passes. If interval is 0, the task is created as completed, or it is never completed if interval is negative.
native task_await(task:task);Performs a non-blocking waiting for the completion of the specified task. Returns the result of the task after it is completed. Aliased as await if PP_NO_ALIASES is not defined.
native task_yield({_,Float,StringTags}:value);Sets the result of the immediate containing public function after the execution is paused. Aliased as yield if PP_NO_ALIASES is not defined.
native thread_detach(sync_flags:flags);Detaches the execution of the code from the main thread, executing it in a new thread on the next tick. flags may specify how outer synchronisation happens in the new thread.
native thread_attach();Attachs the execution back to the main thread.
The two functions above are wrapped in the threaded pseudo-statement which calls them automatically when appropriate.
native thread_sync();If the thread was created with sync_explicit, callbacks to the code are delayed after the thread ends. Calling this function executes them immediately.
native thread_sleep(ms);Pauses the thread for the specified number of milliseconds. Works in the main thread too (will pause the server).
native thread_id(id[], size=sizeof id);Returns the identifier of the current thread, usually numeric.
native String:thread_id_s();The same as above, but using a dynamic string.