# string::pad-left

[This is preliminary documentation and subject to change.]

Returns the given string left-padded to the given length.

### Usage

`string string::pad-left(s, totalWidth, paddingChar)`

### Parameters

Name | Type | Description
--- | --- | ---
s | string | The String that needs to be left-padded.
totalWidth | int | The number of characters in the resulting string, equal to the number of original characters plus any additional padding characters.
paddingChar | string | A Unicode padding character.

### Return Value

If the length of s is at least totalWidth, then a new String identical to s is returned. Otherwise, s will be padded on the left with as many paddingChar characters as needed to create a length of totalWidth.

### Exceptions

The function will fail in any of the following circumstances:

- totalWidth is less than zero.

### Remarks

Note that only the first character of paddingChar will be used when padding the result.

### Examples

-     string::pad-left('test', 10, ' ') ==> '      test'

-     string::pad-left('test', 10, 'test') ==> 'tttttttest'

-     string::pad-left('test', 3, ' ') ==> 'test'

-     string::pad-left('test', -4, ' ') ==> ERROR

### Requirements

Assembly: NAnt.Core (0.91.3881.0)