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`. 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' ``` 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.