## `stringlib::format` -- Formatting a string

#### Introduction

`stringlib::format` adjusts the length of a string.

#### Call(s)

`stringlib::format(string1, width, <, alignment> <, fill_char>)`

#### Parameters

`string1` | - | string
`width` | - | integer that determines the length of the returned string
`alignment` | - | Left, Center, or Right
`fill_char` | - | one-character string to fill up the result string

#### Options

`Left` | - | determines that the string will be aligned left
`Center` | - | determines that the string will be centered
`Right` | - | determines that the string will be aligned right

#### Returns

a string of length `width` containing the given string

#### Related Functions

`stringlib::formatf`

#### Details

- If `width` is less than the length of the given string `string1`, the substring consisting of the first `width` characters of `string1` is returned.
- If `width` exceeds the length of `string1`, the given string will be filled with the necessary number of spaces or the optional `fill_char`. These are inserted at the end in case of left alignment, or at the beginning in case of right alignment. In case of centering, the same number of filling characters is placed at the beginning and at the end, but one more is placed at the end if their total number is odd.
- If `alignment` is not given, left alignment is used by default.

#### Example 1

By default, a string of length 5 is adjusted to length 10 by inserting five space characters at the end.

    >> stringlib::format("abcde", 10)

                                   "abcde     "

In the case of centering, three spaces are inserted at the end and two at the beginning.

    >> stringlib::format("abcde", 10, Center)

                                   "  abcde   "

Instead of the space character, also any other character may be used as a filling character.

    >> stringlib::format("abcde", 10, Right, ".")

                                   ".....abcde"

    >> stringlib::format("abcde", 10, ".")

                                   "abcde....."

#### Changes

- used to be called `string::format`

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