## `stringlib::subs` -- Substitution in a string

#### Introduction

`stringlib::subs` substitutes a substring by another string.

#### Call(s)

`stringlib::subs(string, substring = replacement, <First>)`

#### Parameters

`string` | - | non empty string
`substring` | - | non empty string that should be replaced
`replacement` | - | any string that replaced `substring`

#### Options

`First` | - | determines, that only the first appearance of `substring` in `string` will be replaced

#### Returns

the given string with `substring` replaced by `replacement`

#### Related Functions

`subs`, `stringlib::subsop`, `stringlib::pos`, `stringlib::remove`

#### Details

- By default, every occurrence of the string `substring` in `string` is replaced by `replacement`. The option First causes only the first appearance of `substring` to be replaced.
- The result is not searched again for instances of `substring`. See Example 3.
- Among several overlapping occurrences of `substring`, the leftmost one is replaced.

#### Example 1

The string `replacement` may be empty.

    >> stringlib::subs("abcdeabcdeabcde", "bc" = "")

                                    "adeadeade"

#### Example 2

Every `substring` is replaced unless the option `First` is given.

    >> stringlib::subs("abcdeabcdeabcde", "bc" = "xxx")

                               "axxxdeaxxxdeaxxxde"

    >> stringlib::subs("abcdeabcdeabcde", "bc" = "xxx", First)

                                "axxxdeabcdeabcde"

#### Example 3

The substitution may produce a new instance of `substring`, but this one is not replaced.

    >> stringlib::subs("aab", "ab"="b")

                                       "ab"

#### Changes

- used to be called `string::subs`

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000