# string::substring

[This is preliminary documentation and subject to change.]

Returns a substring of the specified string.

### Usage

`string string::substring(str, startIndex, length)`

### Parameters

Name | Type | Description
--- | --- | ---
str | string | input string
startIndex | int | position of the start of the substring
length | int | the length of the substring

### Return Value

If the length is greater than zero, the function returns a substring starting at character position startIndex with a length of length characters.

If the length is equal to zero, the function returns an empty string.

### Exceptions

The function will fail in any of the following circumstances:

- startIndex or length is less than zero.
- startIndex is greater than the length of str.
- startIndex plus length indicates a position not within str.

### Examples

-     string::substring('testing string', 0, 4) ==> 'test'

-     string::substring('testing string', 8, 3) ==> 'str'

-     string::substring('testing string', 8, 0) ==> ''

-     string::substring('testing string', -1, 5) ==> ERROR

-     string::substring('testing string', 8, -1) ==> ERROR

-     string::substring('testing string', 5, 17) ==> ERROR

### Requirements

Assembly: NAnt.Core (0.91.3881.0)