String natives

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_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,_}:...);
native String:str_format_s(StringTag: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_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,_}:...);

native List:str_split(StringTag:str, const delims[]);
native List:str_split_s(StringTag:str, StringTag:delims);

Separates the input string using delimiter characters. The result is a list of strings (non-dynamic).

native String:str_join(List:list, const delim[]);
native String:str_join_s(List:list, StringTag:delim);

Joins a list of values with a delimiter. The values may be any type, in which case str_val is used on them.