String (str)

All strings have the following methods. Strings are immutable, all operations return their results as a new string.

Returned by

String objects are returned by the following functions and methods:

• get_option()
• join_paths()
• bool.to_string()
• build_machine.cpu()
• build_machine.cpu_family()
• build_machine.endian()
• build_machine.kernel()
• build_machine.subsystem()
• build_machine.system()
• build_tgt.full_path()
• build_tgt.name()
• build_tgt.path()
• cfg_data.get()
• cfg_data.get_unquoted()
• compiler.get_argument_syntax()
• compiler.get_define()
• compiler.get_id()
• compiler.get_linker_id()
• compiler.version()
• custom_idx.full_path()
• custom_tgt.full_path()
• dep.get_configtool_variable()
• dep.get_pkgconfig_variable()
• dep.get_variable()
• dep.include_type()
• dep.name()
• dep.type_name()
• dep.version()
• external_program.full_path()
• external_program.path()
• external_program.version()
• file.full_path()
• int.to_string()
• meson.backend()
• meson.build_options()
• meson.build_root()
• meson.current_build_dir()
• meson.current_source_dir()
• meson.global_build_root()
• meson.global_source_root()
• meson.project_build_root()
• meson.project_name()
• meson.project_source_root()
• meson.project_version()
• meson.source_root()
• meson.version()
• runresult.stderr()
• runresult.stdout()
• str.format()
• str.join()
• str.replace()
• str.strip()
• str.substring()
• str.to_lower()
• str.to_upper()
• str.underscorify()

String methods

str.contains()

Returns true if string contains the string specified as the argument.

# Returns `true` if string contains the string specified as the argument
bool contains(
  str fragment,     # The string fragment to check
)

Example

target = 'x86_FreeBSD'
is_fbsd = target.to_lower().contains('freebsd')
# is_fbsd now has the boolean value 'true'

Arguments

The method str.contains() accepts the following positional arguments:

Name	Type	Description	Tags
fragment	str	The string fragment to check

---

str.endswith()

Returns true if string ends with the string specified as the argument.

# Returns true if string ends with the string specified as the argument
bool endswith(
  str fragment,     # The string fragment to check
)

Example

target = 'x86_FreeBSD'
is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'

Arguments

The method str.endswith() accepts the following positional arguments:

Name	Type	Description	Tags
fragment	str	The string fragment to check

---

str.format()

Strings can be built using the string formatting functionality.

See the Meson syntax entry 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.

# Strings can be built using the string formatting functionality
str format(
  str              fmt,       # The string to format
  int | bool | str value...,  # The values to replace the @number@ placeholders in the format string
)

Example

template = 'string: @0@, number: @1@, bool: @2@'
res = template.format('text', 1, true)
# res now has value 'string: text, number: 1, bool: true'

Arguments

Argument flattening is NOT SUPPORTED by this function.

The method str.format() accepts the following positional arguments:

Name	Type	Description	Tags
fmt	str	The string to format. The formatting works by replacing placeholders of type @number@ with the corresponding varargs.

Additionally, the method accepts between 0 and infinity variadic arguments (value...) of type int | bool | str.

The values to replace the @number@ placeholders in the format string.

---

str.join()

The opposite of split, for example '.'.join(['a', 'b', 'c'] yields 'a.b.c'.

# The opposite of split,
str join(
  str strings...,  # The strings to join with the current string
)

Example

# 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'

Arguments

The method accepts between 0 and infinity variadic arguments (strings...) of type str.

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.replace()

Search all occurrences of old and replace it with new

# Search all occurrences of `old` and replace it with `new`
str replace(
  str old,     # The substring to search
  str new,     # The replacement string
)

Example

# 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'

Arguments

The method str.replace() accepts the following positional arguments:

Name	Type	Description	Tags
old	str	The substring to search
new	str	The replacement string

---

str.split()

Splits the string at the specified character (or whitespace if not set) and returns the parts in an array.

# Splits the string at the specified character
list[str] split(
  str [split_string],   # Specifies the character / substring where to split the string
)

Example

# 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', '']

Arguments

The method str.split() accepts the following positional arguments:

Name	Type	Description	Tags
split_string	str	Specifies the character / substring where to split the string.	[optional]

---

str.splitlines()

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.

list[str] splitlines()

Example

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.startswith()

Returns true if string starts with the string specified as the argument.

# Returns true if string starts with the string specified as the argument
bool startswith(
  str fragment,     # The string fragment to check
)

Example

target = 'x86_FreeBSD'
is_x86 = target.startswith('x86') # boolean value 'true'

Arguments

The method str.startswith() accepts the following positional arguments:

Name	Type	Description	Tags
fragment	str	The string fragment to check

---

str.strip()

Removes leading/ending characters from the string.

By default the characters to remove are spaces and newlines.

# Removes leading/ending characters from the string
str strip(
  str [strip_chars],   # Instead of whitespace, strip all the characters in this string
)

Example

# 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'

Arguments

The method str.strip() accepts the following positional arguments:

Name	Type	Description	Tags
strip_chars	str	Instead of whitespace, strip all the characters in this string.	(since 0.43.0) [optional]

---

str.substring()

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.

# Returns a substring specified from `start` to `end`
str substring(
  int [start],   # The start position
  int [end],     # The end position
)

Example

# 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:

string = 'foobar'
string.substring(-5, -3) # => 'oo'
string.substring(1, -1) # => 'ooba'

Example with out of bound values:

string = 'foobar'
string.substring(64) # => ''
string.substring(0, 64) # => 'foobar'
string.substring(64, 0) # => ''

Arguments

The method str.substring() accepts the following positional arguments:

Name	Type	Description	Tags
start	int	The start position	[optional]
end	int	The end position	[optional]

---

str.to_int()

Converts the string to an int and throws an error if it can't be

int to_int()

Example

version = '1'
# Converts the string to an int and throws an error if it can't be
ver_int = version.to_int()

---

str.to_lower()

Converts all characters to lower case

str to_lower()

Example

target = 'x86_FreeBSD'
lower = target.to_lower() # t now has the value 'x86_freebsd'

---

str.to_upper()

Converts all characters to upper case

str to_upper()

Example

target = 'x86_FreeBSD'
upper = target.to_upper() # t now has the value 'X86_FREEBSD'

---

str.underscorify()

Creates a string where every non-alphabetical non-number character is replaced with _.

str underscorify()

Example

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()

Does semantic version comparison.

# Does semantic version comparison
bool version_compare(
  str compare_string,     # The string to compare to
)

Example

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:

'3.6'.version_compare('>=3.6.0') == false

It is best to be unambiguous and specify the full revision level to compare.

Arguments

The method str.version_compare() accepts the following positional arguments:

Name	Type	Description	Tags
compare_string	str	The string to compare to.

---