stdlib_strings:local:
:depth: 2
The stdlib_strings module provides basic string handling and manipulation routines.
The generated API reference for this pilot module is available in
[the Sphinx API section](/stdlib/doc/api/stdlib_strings.rst).
stripRemove leading and trailing whitespace characters.
string = strip ` (string)`
Experimental
Pure function.
string: Character scalar or string_type.
This argument is intent(in).The result is of the same type as string.
```{literalinclude} ../../example/strings/example_strip.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `chomp`
#### Description
Remove trailing characters in *set* or *substring* from *string*.
If no character *set* or *substring* is provided trailing whitespace is removed.
#### Syntax
`string = ` `chomp` ` (string[, set|substring])`
#### Status
Experimental
#### Class
Pure function.
#### Argument
- `string`: Character scalar or `string_type`.
This argument is intent(in).
- `set`: Array of length one character. This argument is intent(in).
- `substring`: Character scalar or `string_type`.
This argument is intent(in).
#### Result value
The result is of the same type as `string`.
#### Example
```{literalinclude} ../../example/strings/example_chomp.f90
:language: fortran
starts_withCheck if a string starts with a given substring.
string = starts_with ` (string, substring)`
Experimental
Pure function.
string: Character scalar or string_type.
This argument is intent(in).substring: Character scalar or string_type.
This argument is intent(in).The result is of scalar logical type.
```{literalinclude} ../../example/strings/example_starts_with.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `ends_with`
#### Description
Check if a *string* ends with a given *substring*.
#### Syntax
`string = ` `ends_with` ` (string, substring)`
#### Status
Experimental
#### Class
Pure function.
#### Argument
- `string`: Character scalar or `string_type`.
This argument is intent(in).
- `substring`: Character scalar or `string_type`.
This argument is intent(in).
#### Result value
The result is of scalar logical type.
#### Example
```{literalinclude} ../../example/strings/example_ends_with.f90
:language: fortran
sliceExtracts the characters from the defined region of the input string by taking strides.
Argument first and last defines this region for extraction by function slice.
Argument stride defines the magnitude and direction (+/-) of stride to be taken while extraction.
stride when given invalid value 0, is converted to +1.
Deduction Process:
Function first automatically deduces the optional arguments that are not provided by the user.
Deduced first and last argument take +infinity or -infinity value and deduced stride argument
takes value +1 or -1 depending upon the actual argument(s) provided by the user.
Extraction Process:
Extraction starts only if last is crossable from first with stride of stride.
Extraction starts from the first valid index in the defined region to take stride of stride
and ends when the last valid index in the defined region is crossed.
If no valid index exists in the defined region, empty string is returned.
string = slice ` (string [, first, last, stride])`
Experimental
Pure function.
string: Character scalar or string_type.
This argument is intent(in).first: integer.
This argument is intent(in) and optional.last: integer.
This argument is intent(in) and optional.stride: integer.
This argument is intent(in) and optional.The result is of the same type as string.
```{literalinclude} ../../example/strings/example_slice.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `find`
#### Description
Returns the starting index of the `occurrence`th occurrence of the substring `pattern`
in the input string `string`.
Default value of `occurrence` is set to `1`.
If `consider_overlapping` is not provided or is set to `.true.` the function counts two overlapping occurrences of substring `pattern` as two different occurrences.
If `occurrence`th occurrence is not found, function returns `0`.
#### Syntax
`string = ` `find` ` (string, pattern [, occurrence, consider_overlapping])`
#### Status
Experimental
#### Class
Elemental function
#### Argument
- `string`: Character scalar or `string_type`.
This argument is intent(in).
- `pattern`: Character scalar or `string_type`.
This argument is intent(in).
- `occurrence`: integer.
This argument is intent(in) and optional.
- `consider_overlapping`: logical.
This argument is intent(in) and optional.
#### Result value
The result is a scalar of integer type or an integer array of rank equal to the highest rank among all dummy arguments.
#### Example
```{literalinclude} ../../example/strings/example_find.f90
:language: fortran
replace_allReplaces all occurrences of substring pattern in the input string with the replacement replacement.
Occurrences overlapping on a base occurrence will not be replaced.
string = replace_all ` (string, pattern, replacement)`
Experimental
Pure function
string: Character scalar or string_type.
This argument is intent(in).pattern: Character scalar or string_type.
This argument is intent(in).replacement: Character scalar or string_type.
This argument is intent(in).The result is of the same type as string.
```{literalinclude} ../../example/strings/example_replace_all.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `padl`
#### Description
Returns a string of length `output_length` left padded with `pad_with` character if it is provided, otherwise with `" "` (1 whitespace).
If `output_length` is less than or equal to the length of `string`, padding is not performed.
#### Syntax
`string = ` `padl` ` (string, output_length [, pad_with])`
#### Status
Experimental
#### Class
Pure function
#### Argument
- `string`: Character scalar or `string_type`.
This argument is intent(in).
- `output_length`: integer.
This argument is intent(in).
- `pad_with`: Character scalar of length 1.
This argument is intent(in) and optional.
#### Result value
The result is of the same type as `string`.
#### Example
```{literalinclude} ../../example/strings/example_padl.f90
:language: fortran
padrReturns a string of length output_length right padded with pad_with character if it is provided, otherwise with " " (1 whitespace).
If output_length is less than or equal to the length of string, padding is not performed.
string = padr ` (string, output_length [, pad_with])`
Experimental
Pure function
string: Character scalar or string_type.
This argument is intent(in).output_length: integer.
This argument is intent(in).pad_with: Character scalar of length 1.
This argument is intent(in) and optional.The result is of the same type as string.
```{literalinclude} ../../example/strings/example_padr.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `count`
#### Description
Returns the number of times the substring `pattern` has occurred in the input string `string`.
If `consider_overlapping` is not provided or is set to `.true.` the function counts two overlapping occurrences of substring `pattern` as two different occurrences.
#### Syntax
`string = ` `count` ` (string, pattern [, consider_overlapping])`
#### Status
Experimental
#### Class
Elemental function
#### Argument
- `string`: Character scalar or `string_type`.
This argument is intent(in).
- `pattern`: Character scalar or `string_type`.
This argument is intent(in).
- `consider_overlapping`: logical.
This argument is intent(in) and optional.
#### Result value
The result is a scalar of integer type or an integer array of rank equal to the highest rank among all dummy arguments.
#### Example
```{literalinclude} ../../example/strings/example_count.f90
:language: fortran
zfillReturns a string of length output_length left-padded with zeros.
If output_length is less than or equal to the length of string, padding is not performed.
string = zfill ` (string, output_length)`
Experimental
Pure function
string: Character scalar or string_type.
This argument is intent(in).output_length: integer.
This argument is intent(in).The result is of the same type as string.
```{literalinclude} ../../example/strings/example_zfill.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `join`
#### Description
Joins an array of strings into a single string. This function concatenates the strings from the input array,
inserting a separator between each string (default: space). A user-defined separator may be provided, The resulting string is returned.
#### Syntax
`joined = ` `join` ` (strings, separator)`
#### Status
Experimental
#### Class
Pure function
#### Argument
- `strings`: Array of strings (either `type(string_type)` or `character(len=*)`).
This argument is `intent(in)`. It is an array of strings that will be concatenated together.
- `separator`: `character(len=*)` scalar (optional).
This argument is `intent(in)`. It specifies the separator to be used between the strings. If not provided, the default separator (a space) is used.
#### Result value
The result is of the same type as the elements of `strings` (`type(string_type)` or `character(len=:), allocatable`).
#### Example
```{literalinclude} ../../example/strings/example_join.f90
:language: fortran
to_stringFormat or transfer a integer/real/complex/logical scalar as a string.
Input a wrong format that cause the internal-IO to fail, the result value is a string of [*].
string = to_string ` (value [, format])`
Experimental
Pure function.
value: Shall be an integer/real/complex/logical scalar.
This is an intent(in) argument.format: Shall be a character(len=*) scalar like '(F6.2)' or just 'F6.2'.
This is an intent(in) and optional argument.value into a string, for example '(F6.2)' or '(f6.2)'.
to_string will automatically enclose format in a set of parentheses, so passing F6.2 or f6.2 as format is possible as well.The result is an allocatable length character scalar with up to 128 cached character length.
```{literalinclude} ../../example/strings/example_to_string.f90 :language: fortran
<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
### `to_c_char`
#### Description
Convert a Fortran `character` string or a `type(string_type)` variable to a C character array.
This function converts a Fortran string into a C-style array of characters, ensuring proper null-termination for use in C functions or libraries.
#### Syntax
`cstr = ` `to_c_char` ` (value)`
#### Status
Experimental
#### Class
Pure function.
#### Argument
- `value`: Shall be a `character(len=*)` string or a `type(string_type)` variable. It is an `intent(in)` argument.
This Fortran variable will be converted to a C character array.
#### Result value
The result is a `character(kind=c_char)` array with a dimension of `len(value) + 1` to accommodate the null terminator.
#### Example
```{literalinclude} ../../example/strings/example_to_c_char.f90
:language: fortran