name: str
long_name: String
description: |
All [strings](Syntax.md#strings) have the following methods. Strings
are immutable, all operations return their results as a new string.
methods:
# str.format(fmt, value...)
- name: format
returns: str
description: |
Strings can be built using the string formatting functionality.
See [the Meson syntax entry](Syntax.md#string-formatting) for more
information.
*Since 1.3.0* values other than strings, integers, bools, options,
dictionaries and lists thereof are deprecated. They were previously printing
the internal representation of the raw Python object.
example: |
```meson
template = 'string: @0@, number: @1@, bool: @2@'
res = template.format('text', 1, true)
# res now has value 'string: text, number: 1, bool: true'
```
arg_flattening: false
posargs:
fmt:
description: |
The string to format.
The formatting works by replacing placeholders of type `@number@` with
the corresponding varargs.
type: str
varargs:
name: value
description: The values to replace the @number@ placeholders in the format string.
type: int | bool | str
# str.replace(old, new)
- name: replace
description: Search all occurrences of `old` and replace it with `new`
returns: str
since: 0.58.0
example: |
```meson
# Replaces all instances of one substring with another
s = 'semicolons;as;separators'
s = s.replace('as', 'are')
# 's' now has the value of 'semicolons;are;separators'
```
posargs:
old:
description: The substring to search
type: str
new:
description: The replacement string
type: str
# str.strip()
- name: strip
description: |
Removes leading/ending characters from the string.
By default the characters to remove are spaces and newlines.
returns: str
example: |
```meson
# Similar to the Python str.strip(). Removes leading/ending spaces and newlines
define = ' -Dsomedefine '
stripped_define = define.strip()
# 'stripped_define' now has the value '-Dsomedefine'
```
optargs:
strip_chars:
type: str
since: 0.43.0
description: Instead of whitespace, strip all the characters in this string.
# str.to_lower()
- name: to_lower
description: Converts all characters to lower case
returns: str
example: |
```meson
target = 'x86_FreeBSD'
lower = target.to_lower() # t now has the value 'x86_freebsd'
```
# str.to_upper()
- name: to_upper
description: Converts all characters to upper case
returns: str
example: |
```meson
target = 'x86_FreeBSD'
upper = target.to_upper() # t now has the value 'X86_FREEBSD'
```
# str.to_int()
- name: to_int
description: Converts the string to an int and throws an error if it can't be
returns: int
example: |
```meson
version = '1'
# Converts the string to an int and throws an error if it can't be
ver_int = version.to_int()
```
# str.contains()
- name: contains
returns: bool
description: Returns `true` if string contains the string specified as the argument.
example: |
```meson
target = 'x86_FreeBSD'
is_fbsd = target.to_lower().contains('freebsd')
# is_fbsd now has the boolean value 'true'
```
posargs:
fragment:
type: str
description: The string fragment to check
# str.startswith()
- name: startswith
returns: bool
description: Returns true if string starts with the string specified as the argument.
posargs_inherit: str.contains
example: |
```meson
target = 'x86_FreeBSD'
is_x86 = target.startswith('x86') # boolean value 'true'
```
# str.endswith()
- name: endswith
returns: bool
description: Returns true if string ends with the string specified as the argument.
posargs_inherit: str.contains
example: |
```meson
target = 'x86_FreeBSD'
is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'
```
# str.substring()
- name: substring
returns: str
since: 0.56.0
description: |
Returns a substring specified from `start` to `end`.
Both `start` and `end` arguments are optional, so, for example, `'foobar'.substring()` will return `'foobar'`.
The method accepts negative values where negative `start` is relative to the end of
string `len(string) - start` as well as negative `end`.
If `start` or `end` are out of bounds, the position of the closest character will be used.
If `start` is bigger than `end`, the result will be an empty substring.
example: |
```meson
# Similar to the Python str[start:end] syntax
target = 'x86_FreeBSD'
platform = target.substring(0, 3) # prefix string value 'x86'
system = target.substring(4) # suffix string value 'FreeBSD'
```
Example with negative values:
```meson
string = 'foobar'
string.substring(-5, -3) # => 'oo'
string.substring(1, -1) # => 'ooba'
```
Example with out of bound values:
```meson
string = 'foobar'
string.substring(64) # => ''
string.substring(0, 64) # => 'foobar'
string.substring(64, 0) # => ''
```
optargs:
start:
type: int
description: The start position
end:
type: int
description: The end position
# str.split
- name: split
returns: list[str]
description: |
Splits the string at the specified character
(or whitespace if not set) and returns the parts in an
array.
example: |
```meson
# Similar to the Python str.split()
components = 'a b c d '.split()
# components now has the value ['a', 'b', 'c', 'd']
components = 'a b c d '.split(' ')
# components now has the value ['a', 'b', '', '', 'c', 'd', '']
```
optargs:
split_string:
type: str
description: Specifies the character / substring where to split the string.
- name: splitlines
returns: list[str]
since: 1.2.0
description: |
Splits the string into an array of lines.
Unlike .split('\n'), the empty string produced an empty array,
and if the string ends in a newline, splitlines() doesn't split
on that last newline.
'\n', '\r' and '\r\n' are all considered newlines.
example: |
```meson
output = 'hello\nworld\n'.splitlines()
# Output value is ['hello', 'world']
output = ''.splitlines()
# Output value is []
fs = import('fs')
paths = fs.read('my_paths.list').splitlines()
# paths is now the paths listed in 'my_paths.list', or an empty list
# if 'my_paths.list' is empty
```
# str.join()
- name: join
returns: str
description: |
The opposite of split,
for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`.
example: |
```meson
# Similar to the Python str.join()
output = ' '.join(['foo', 'bar'])
# Output value is 'foo bar'
pathsep = ':'
path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
# path now has the value '/usr/bin:/bin:/usr/local/bin'
```
varargs:
name: strings
type: str
since: 0.60.0
description: |
The strings to join with the current string.
Before Meson *0.60.0* this function only accepts a single positional
argument of the type [[list[str]]].
# str.underscorify
- name: underscorify
returns: str
description: Creates a string where every non-alphabetical non-number character is replaced with `_`.
example: |
```meson
name = 'Meson Docs.txt#Reference-manual'
# Replaces all characters other than `a-zA-Z0-9` with `_` (underscore)
# Useful for substituting into #defines, filenames, etc.
underscored = name.underscorify()
# underscored now has the value 'Meson_Docs_txt_Reference_manual'
```
# str.version_compare
- name: version_compare
returns: bool
description: Does semantic version comparison.
example: |
```meson
version = '1.2.3'
# Compare version numbers semantically
is_new = version.version_compare('>=2.0')
# is_new now has the boolean value false
# Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
```
Meson version comparison conventions include:
```meson
'3.6'.version_compare('>=3.6.0') == false
```
It is best to be unambiguous and specify the full revision level to compare.
posargs:
compare_string:
type: str
description: The string to compare to.