Changed string_pos to return -1 on arg error

Added a check to PartyControl::OrderAttackPatch().
Updated function documents.

artifacts/scripting/functions.yml

@@ -1098,7 +1098,7 @@
     detail: string substr(string text, int start, int length)
     doc: |
       Cuts a substring from a string starting at "start" up to "length" characters. The first character position is 0 (zero).
-      - If start is negative - it indicates starting position from the end of the string (for example `substr("test", -2, 2)` will return last 2 charactes: "st").
+      - If start is negative - it indicates a position starting from the end of the string (for example `substr("test", -2, 2)` will return last 2 charactes: "st").
       - If length is negative - it means so many characters will be omitted from the end of string (example: `substr("test", 0, -2)` will return string without last 2 characters: "te").
       - If length is zero - it will return a string from the starting position to the end of the string. **New behavior** for sfall 4.2.2/3.8.22
     opcode: 0x824e
@@ -1117,14 +1117,14 @@
       - __NOTE:__ this function is intended for use only in `HOOK_DESCRIPTIONOBJ`. Starting from sfall 4.4/3.8.40, you can return normal strings directly in the hook without calling the function
     macro: sfall.h
   - name: string_pos
-    detail: string string_pos(string haystack, string needle)
-    doc: Returns position of a first occurance of a needle string in a haystack string, or -1 if not found.
+    detail: int string_pos(string haystack, string needle)
+    doc: Returns the position of the first occurrence of a `needle` string in a `haystack` string, or -1 if not found. The first character position is 0 (zero).
     macro: sfall.h
   - name: string_pos_from
-    detail: string string_pos_from(string haystack, string needle, int pos)
+    detail: int string_pos_from(string haystack, string needle, int pos)
     doc: |
-      Returns position of a first occurance of a needle string in a haystack string (starting from a given 0-based position), or -1 if not found.
-      - If pos is negative - it indicates starting position from the end of the string, similar to substr().
+      Works the same as `string_pos`, except you can specify the position to start the search.
+      - If `pos` is negative - it indicates a position starting from the end of the string, similar to `substr()`.
     macro: sfall.h
   - name: string_format
     detail: string string_format(string format, any val1, any val2, ...)

artifacts/scripting/sfall function notes.md

@@ -327,11 +327,11 @@ FUNCTION REFERENCE
 - You can use this to search for a substring in a string like this: `strlen(get_array(string_split(haystack, needle), 0))`
 
 -----
-##### `string substr(string text, start, length)`
+##### `string substr(string text, int start, int length)`
 - Cuts a substring from a string starting at `start` up to `length` characters. The first character position is 0 (zero).
-- If `start` is negative - it indicates starting position from the end of the string (for example, `substr("test", -2, 2)` will return last 2 charactes: "st").
+- If `start` is negative - it indicates a position starting from the end of the string (for example, `substr("test", -2, 2)` will return last 2 charactes: "st").
 - If `length` is negative - it means so many characters will be omitted from the end of string (example: `substr("test", 0, -2)` will return string without last 2 characters: "te").
-- If `length` is zero - it will return a string from the starting position to the end of the string (new behavior for sfall 4.2.2/3.8.22).
+- If `length` is zero - it will return a string from the starting position to the end of the string (**new behavior** since sfall 4.2.2/3.8.22).
 
 -----
 ##### `int strlen(string text)`
@@ -1107,6 +1107,7 @@ sfall_funcX metarule functions
 - Allows changing "bonus move" points (yellow lights on the interface bar) that can only be used for movement, not attacking
 - Can be called from `HOOK_COMBATTURN` at the start of the turn (will not work on `dude_obj`)
 - Can be called from `HOOK_STDPROCEDURE` with `combat_proc` event (will work on both NPCs and `dude_obj`)
+
 ----
 #### get_ini_config
 `array sfall_func2("get_ini_config", string file, bool searchDB)`
@@ -1116,6 +1117,16 @@ sfall_funcX metarule functions
     True - searches the file in database (DAT) files. If not found, then it will try the regular file system
 - Subsequent calls for the same file will return the same array, unless it was disposed using `free_array`
 
+----
+#### string_pos
+`int sfall_func2("string_pos", string haystack, string needle)`
+`int sfall_func3("string_pos", string haystack, string needle, int pos)`
+
+- Returns the position of the first occurrence of a `needle` string in a `haystack` string, or -1 if not found. The first character position is 0 (zero)
+
+**Optional argument:**
+- `pos`: the position at which to start the search. If negative, it indicates a position starting from the end of the string
+
 
 ****
 _See other documentation files (arrays.md, hookscripts.md) for related functions reference._