substring() — rsyslog 8.2412.0 documentation

# 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

    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.

    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.

    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:

    substring("123456789", 2, -3)

See also

Help with configuring/using `Rsyslog`:

- Mailing list - best route for general questions

- GitHub: rsyslog source project - detailed questions, reporting issues that are believed to be bugs with `Rsyslog`

See also

Contributing to `Rsyslog`:

- Source project: rsyslog project README.

- Documentation: rsyslog-doc project README

Copyright 2008-2023 Rainer Gerhards (Großrinderfeld), and Others.