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