path: root/docs/yaml/elementary/str.yml

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.