-
Notifications
You must be signed in to change notification settings - Fork 19
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);
native ConstAmxString:str_addr_const(ConstStringTag:str);This function is called by every assignment to an AmxString or ConstAmxString 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 String:str_acquire(StringTag:str);Increases the reference count stored in the string instance. If the reference count was 0 previously (which it is for newly created strings), the string instance is moved to the global pool and will not be collected automatically. See garbage collection and resource management.
native String:str_release(StringTag:str);Decreases the reference count stored in the string instance. If the reference count was 1 previously, the string is moved to the local pool, making it eligible for automatic collection. If the reference count was 0, an error is raised. See garbage collection and resource management.
native str_delete(StringTag:str);Frees the memory containing the string object. Not recommended to use if you pass the string to other functions that may store the reference, since if the string isn't acquired, it will be collected eventually.
native bool:str_valid(ConstStringTag:str);Returns true if the string pointer points to a valid string. Shouldn't be necessary to use.
native String:str_clone(ConstStringTag:str);Creates a new string with the copy of characters from str.
native String:str_val(AnyTag:value, TagTag:tag_id=tagof(value));Converts a value to a string. The tag of the value determines its format. This function has an alias @@, enabled if PP_SYNTAX_@@ is defined.
native String:str_val_arr(AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value));Converts an array to a string. The tag of the array determines its format.
native str_len(ConstStringTag:str);Returns the length of the string (in cells).
native str_get(ConstStringTag: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(ConstStringTag: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(ConstStringTag:str1, ConstStringTag: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(ConstStringTag:str);Returns true if the string is empty (i.e. its length is zero).
native bool:str_eq(ConstStringTag:str1, ConstStringTag:str2);Return true if the two strings are equal (if they contain the same characters). Used by operator==(StringTag:,StringTag:).
native str_findc(ConstStringTag: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(ConstStringTag:str, ConstStringTag: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.
These functions create a new string every time they are used.
native String:str_cat(ConstStringTag:str1, ConstStringTag:str2);Concatenates two strings together, always producing a new string. Used by the + operator.
native String:str_sub(ConstStringTag:str, start=0, end=cellmax);Returns a substring from the specified string.
native List:str_split(ConstStringTag:str, const delims[]);
native List:str_split_s(ConstStringTag:str, ConstStringTag: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, ConstStringTag:delim);Joins a list of values with a delimiter. The values may be any type, in which case str_val is used on them.
native String:str_to_lower(ConstStringTag:str);Creates a copy of the string with all characters converted to lowercase. For ANSI characters, this function takes into account the current locale (if pp_locale was used).
native String:str_to_upper(ConstStringTag:str);Creates a copy of the string with all characters converted to upperase. For ANSI characters, this function takes into account the current locale (if pp_locale was used).
These functions return the target string, without creating a new one.
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_ins(StringTag:target, StringTag:other, pos);Inserts a string into another string on the specified position.
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_set_to_lower(StringTag:str);Converts all characters in the string to lowercase. For ANSI characters, this function takes into account the current locale (if pp_locale was used).
native String:str_set_to_upper(StringTag:str);Converts all characters in the string to uppercase. For ANSI characters, this function takes into account the current locale (if pp_locale was used).
native String:str_format(const format[], AnyTag:...);
native String:str_format_s(ConstStringTag:format, AnyTag:...);Creates a new string with the specified format with its components provided in the variable number of arguments. More in string formatting.
native String:str_set_format(StringTag:target, const format[], AnyTag:...);
native String:str_set_format_s(StringTag:target, ConstStringTag:format, AnyTag:...);Sets the contents of target to be in the specified format with its components provided in the variable number of arguments. More in string formatting.
native String:str_append_format(StringTag:target, const format[], AnyTag:...);
native String:str_append_format_s(StringTag:target, ConstStringTag:format, AnyTag:...);Appends to the contents of target a string in the specified format with its components provided in the variable number of arguments. More in string formatting.
native bool:str_match(ConstStringTag:str, const pattern[], &pos=0, regex_options:options=regex_default);
native bool:str_match_s(ConstStringTag:str, ConstStringTag:pattern, &pos=0, regex_options:options=regex_default);Performs a regular expression match on str with the specified pattern. More in regular expressions.
native List:str_extract(ConstStringTag:str, const pattern[], &pos=0, regex_options:options=regex_default);
native List:str_extract_s(ConstStringTag:str, ConstStringTag:pattern, &pos=0, regex_options:options=regex_default);Performs a regular expression match on str with the specified pattern, and returns a list of all captured groups in the string (or List:0 if the pattern was not found). More in regular expressions.
native String:str_replace(ConstStringTag:str, const pattern[], const replacement[], &pos=0, regex_options:options=regex_default);
native String:str_replace_s(ConstStringTag:str, ConstStringTag:pattern, ConstStringTag:replacement, &pos=0, regex_options:options=regex_default);Replaces a portion of the string that matches pattern with replacement. Variables like $1, $2 etc. in the replacement can be used to refer to captured groups. More in regular expressions.
native String:str_replace_list(ConstStringTag:str, const pattern[], List:replacement, &pos=0, regex_options:options=regex_default);
native String:str_replace_list_s(ConstStringTag:str, ConstStringTag:pattern, List:replacement, &pos=0, regex_options:options=regex_default);Replaces a portion of the string that matches pattern with a string in replacement. The replacement is selected based on the index of the first successfully matched group, i.e. a pattern (a)|(b) will select replacement[0] if a was matched, or replacement[1] if b was matched. Variables like $1, $2 etc. in the replacement can be used to refer to captured groups that begin at the first matched one. More in regular expressions.
native String:str_replace_func(ConstStringTag:str, const pattern[], const function[], &pos=0, regex_options:options=regex_default, const additional_format[]="", AnyTag:...);
native String:str_replace_func_s(ConstStringTag:str, ConstStringTag:pattern, const function[], &pos=0, regex_options:options=regex_default, const additional_format[]="", AnyTag:...);Calls function for each matched occurence of pattern in the string. The public function shall receive the contents of all groups in the match as sequential arguments in the form of group[], group_length for all groups, matched or unmatched (group_length will be 0 then). Moreover, the function is expected to return a String-tagged value containing the replacement. More in regular expressions.
native String:str_set_replace(StringTag:target, ConstStringTag:str, const pattern[], const replacement[], &pos=0, regex_options:options=regex_default);
native String:str_set_replace_s(StringTag:target, ConstStringTag:str, ConstStringTag:pattern, ConstStringTag:replacement, &pos=0, regex_options:options=regex_default);Like str_replace, but modifies the contents of target instead of creating a new string.
native String:str_set_replace_list(StringTag:target, ConstStringTag:str, const pattern[], List:replacement, &pos=0, regex_options:options=regex_default);
native String:str_set_replace_list_s(StringTag:target, ConstStringTag:str, ConstStringTag:pattern, List:replacement, &pos=0, regex_options:options=regex_default);Like str_replace_list, but modifies the contents of target instead of creating a new string.
native String:str_set_replace_func(StringTag:target, ConstStringTag:str, const pattern[], const function[], &pos=0, regex_options:options=regex_default, const additional_format[]="", AnyTag:...);
native String:str_set_replace_func_s(StringTag:target, ConstStringTag:str, ConstStringTag:pattern, const function[], &pos=0, regex_options:options=regex_default, const additional_format[]="", AnyTag:...);Like str_replace_func, but modifies the contents of target instead of creating a new string.