diff options
Diffstat (limited to 'source/rainerscript/functions/rs-substring.rst')
-rw-r--r-- | source/rainerscript/functions/rs-substring.rst | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/source/rainerscript/functions/rs-substring.rst b/source/rainerscript/functions/rs-substring.rst new file mode 100644 index 0000000..b295abf --- /dev/null +++ b/source/rainerscript/functions/rs-substring.rst @@ -0,0 +1,75 @@ +*********** +substring() +*********** + +Purpose +======= + +`substring(str, start, subStringLength)` + +Creates a substring from `str`. The substring begins at `start` and is +at most `subStringLength` characters long. If `start` is higher than the +length of the string, the result will always be an empty string. The +same is the case if `subStringLength` is zero. + +.. note:: + + The first character of the string has the value 0. So if you set + start to '2', the substring will start with the third character. + +If you want to drop only some characters at the beginning of the string, +select an overlay large `subStringLength`, e.g. 1000000. As the length is +then always larger as any normal string, the function will return all but +the first part of the string. + +In order to aid removing `n` characters from the end of the string, you +can specify a **negative** `subStringLength`. This will result in an +actual `subStringLength` that is the string-length minus the specified +`subStringLength`. This is actually a shortcut for + +.. code-block:: none + + subStringLength = strlen(str) - n + +Specifying a negative `subStringLength` does not only offer a more +compact expression, it also has some performance benefits over the +use of `strlen()`. + + +Examples +======== + +In the following example a substring from the string is created, +starting with the 4th character and being 5 characters long. + +.. code-block:: none + + substring("123456789", 3, 5) + + +This example will result in the substring "45678". + +In the following example the first and the last character +of the string will be removed. + +.. code-block:: none + + substring("123456789", 1, -2) + + +This example will result in the substring "2345678". + +Note the `-2` value for `subStringLength`. As the extraction skips the +first character, you only need a substring of `strlen("123456789") - 2` +characters, as you want to remove the last character as well. In other +words: if you want to remove the first **and** last character from the +string, the substring in question is **two** characters shorter than the +original string! We know this is a bit counter-intuitive, this we +wanted to make you aware. + +As another example let us assume you want to drop the first two and the +last character. In this case you would use `subStringLength` of three: + +.. code-block:: none + + substring("123456789", 2, -3) |