-
Notifications
You must be signed in to change notification settings - Fork 18
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_SYNTAX_@ is defined).
native String:str_new_buf(size);Creates a new string constructed from the null character repeated size - 1 times. Intended for use as an output buffer.
native AmxString:str_addr(StringTag:str, amx_buffer_options:options=amx_buffer_default);
native ConstAmxString:str_addr_const(ConstStringTag:str, amx_buffer_options:options=amx_buffer_default);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. This makes it rejected by the amx_GetAddr API function, and handled by the PawnPlus hook instead, which retrieves the character data. This function is intended to be called right before a call to a native function expecting a string, through the tag conversion. It is unsafe to store the resulting address past the call, so its only use is directly as an argument to a native function.
From v1.4.2 onwards, the address returned by this function is identical to str_buf_addr for non-null strings.
native AmxStringBuffer:str_buf_addr(StringTag:str, amx_buffer_options:options=amx_buffer_default);Like str_addr, but the resulting address is guaranteed to point to the actual character data of the string (relative to the AMX data). Useful for SA-MP native functions that do not call amx_GetAddr to obtain the address. Automatically called when a conversion to AmxStringBuffer occurs. This function cannot be used for null strings.
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:val, TagTag:tag_id=tagof(value), const format[]="");
native String:str_val_arr(const AnyTag:value[], size=sizeof(value), TagTag:tag_id=tagof(value), const format[]="");
native String:str_val_var(ConstVariantTag:value, const format[]="");Converts a value to its string representation. The str_val function has an alias @@, enabled if PP_SYNTAX_@@ is defined. The returned value is affected by the tag of the value (specified via tag_id or inside the variant) and format, which, if specified corresponds to a specifier format as in str_format. If format is specified, results in a call to the format tag operation, and string otherwise.
native str_len(ConstStringTag:str);Returns the length of the string (in cells).
native str_capacity(ConstStringTag:str);Returns the internal capacity of the string's buffer, i.e. the total amount of cells it can hold before memory reallocation is necessary. Might be useful for optimizations.
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.
native str_count_chars(ConstStringTag:str, const encoding[]="", offset=0);Counts the number of Unicode characters stored in the string. For well-formed strings, the result should be equal to str_len(str_convert(str, encoding, "utf32")).
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, const encoding[]="");
native String:str_to_upper(ConstStringTag:str, const encoding[]="");Creates a copy of the string with all characters converted to lowercase/uppercase. The encoding may be specified, otherwise the function uses the current locale (if pp_locale was used).
native String:str_convert(ConstStringTag:str, const from_encoding[], const to_encoding[]);Creates a new string using the characters from str with a different encoding. The characters in the original string are interpreted in from_encoding, and encoded via to_encoding.
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_reserve(StringTag:str, size);Increases the internal buffer's capacity (obtainable via str_capacity) to allow storing at least size cells. Note that this is not normally needed as strings reallocate automatically, but it might be useful in some optimization scenarios. This should not be used in interop with native functions, where str_resize should be used to allocate the necessary size for the output.
native String:str_set_to_lower(StringTag:str);
native String:str_set_to_upper(StringTag:str);Converts all characters in the string to lowercase/uppercase. The encoding may be specified, otherwise the function uses the current locale (if pp_locale was used).
native String:str_set_convert(StringTag:str, const from_encoding[], const to_encoding[]);Converts the string to a different encoding. The characters in the string are interpreted in from_encoding, and encoded via to_encoding.
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_register_format(selector, TagTag:tag_id, bool:is_string=false, bool:overwrite=false);Associates a specific tag with selector, making it eligible for use in str_val, str_format and similar. Using the selector results in a call to the format operation of the tag, and if that fails and the format is empty, to the string operation. If the selector is already associated with a tag and overwrite is false, does not do anything and returns false. If is_string is true, a Pawn string will be expected as an argument and converted to a dynamic string before passed to the operation.
native tag_uid:str_get_format_tag(selector, &bool:is_string=false);Returns the tag associated with a specific format selector, or tag_uid_unknown if there is none.
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_replace_expr(ConstStringTag:str, const pattern[], Expression:expr, &pos=0, regex_options:options=regex_default);
native String:str_replace_expr_s(ConstStringTag:str, ConstStringTag:pattern, Expression:expr, &pos=0, regex_options:options=regex_default);Executes expr for each matched occurence of pattern in the string. The expression's arguments will be bound to strings corresponding to all groups of the match, matched or unmatched. 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.
native String:str_set_replace_expr(StringTag:target, ConstStringTag:str, const pattern[], Expression:expr, &pos=0, regex_options:options=regex_default);
native String:str_set_replace_expr_s(StringTag:target, ConstStringTag:str, ConstStringTag:pattern, Expression:expr, &pos=0, regex_options:options=regex_default);Like str_replace_expr, but modifies the contents of target instead of creating a new string.