docs: document out of bounds behavior in str.substring

Signed-off-by: Filipe Laíns <lains@riseup.net>

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/yaml/elementary/str.yml b/docs/yaml/elementary/str.yml
index 83ab3dd64..9d059cc09 100644
--- a/docs/yaml/elementary/str.yml
+++ b/docs/yaml/elementary/str.yml
@@ -164,6 +164,9 @@ methods:
     The method accepts negative values where negative `start` is relative to the end of
     string `len(string) - start` as well as negative `end`.
 
+    If `start` or `end` are out of bounds, the position of the closest character will be used.
+    If `start` is bigger than `end`, the result will be an empty substring.
+
   example: |
     ```meson
     # Similar to the Python str[start:end] syntax
@@ -180,6 +183,15 @@ methods:
     string.substring(1, -1) # => 'ooba'
     ```
 
+    Example with out of bound values:
+
+    ```meson
+    string = 'foobar'
+    string.substring(64) # => ''
+    string.substring(0, 64) # => 'foobar'
+    string.substring(64, 0) # => ''
+    ```
+
   optargs:
     start:
       type: int