Debian Codegraph @

subprojects/meson-docs/docs/yaml/elementary/str.yml

raw
1 name: str
2 long_name: String
3 description: |
4 All [strings](Syntax.md#strings) have the following methods. Strings
5 are immutable, all operations return their results as a new string.
6
7 methods:
8
9 # str.format(fmt, value...)
10 - name: format
11 returns: str
12 description: |
13 Strings can be built using the string formatting functionality.
14
15 See [the Meson syntax entry](Syntax.md#string-formatting) for more
16 information.
17
18 *Since 1.3.0* values other than strings, integers, bools, options,
19 dictionaries and lists thereof are deprecated. They were previously printing
20 the internal representation of the raw Python object.
21 example: |
22 ```meson
23 template = 'string: @0@, number: @1@, bool: @2@'
24 res = template.format('text', 1, true)
25 # res now has value 'string: text, number: 1, bool: true'
26 ```
27
28 arg_flattening: false
29
30 posargs:
31 fmt:
32 description: |
33 The string to format.
34
35 The formatting works by replacing placeholders of type `@number@` with
36 the corresponding varargs.
37 type: str
38
39 varargs:
40 name: value
41 description: The values to replace the @number@ placeholders in the format string.
42 type: int | bool | str
43
44 # str.replace(old, new)
45 - name: replace
46 description: Search all occurrences of `old` and replace it with `new`
47 returns: str
48 since: 0.58.0
49 example: |
50 ```meson
51 # Replaces all instances of one substring with another
52 s = 'semicolons;as;separators'
53 s = s.replace('as', 'are')
54 # 's' now has the value of 'semicolons;are;separators'
55 ```
56
57 posargs:
58 old:
59 description: The substring to search
60 type: str
61
62 new:
63 description: The replacement string
64 type: str
65
66 # str.strip()
67 - name: strip
68 description: |
69 Removes leading/ending characters from the string.
70
71 By default the characters to remove are spaces and newlines.
72 returns: str
73 example: |
74 ```meson
75 # Similar to the Python str.strip(). Removes leading/ending spaces and newlines
76 define = ' -Dsomedefine '
77 stripped_define = define.strip()
78 # 'stripped_define' now has the value '-Dsomedefine'
79 ```
80
81 optargs:
82 strip_chars:
83 type: str
84 since: 0.43.0
85 description: Instead of whitespace, strip all the characters in this string.
86
87 # str.to_lower()
88 - name: to_lower
89 description: Converts all characters to lower case
90 returns: str
91 example: |
92 ```meson
93 target = 'x86_FreeBSD'
94 lower = target.to_lower() # t now has the value 'x86_freebsd'
95 ```
96
97 # str.to_upper()
98 - name: to_upper
99 description: Converts all characters to upper case
100 returns: str
101 example: |
102 ```meson
103 target = 'x86_FreeBSD'
104 upper = target.to_upper() # t now has the value 'X86_FREEBSD'
105 ```
106
107 # str.to_int()
108 - name: to_int
109 description: Converts the string to an int and throws an error if it can't be
110 returns: int
111 example: |
112 ```meson
113 version = '1'
114 # Converts the string to an int and throws an error if it can't be
115 ver_int = version.to_int()
116 ```
117
118 # str.contains()
119 - name: contains
120 returns: bool
121 description: Returns `true` if string contains the string specified as the argument.
122 example: |
123 ```meson
124 target = 'x86_FreeBSD'
125 is_fbsd = target.to_lower().contains('freebsd')
126 # is_fbsd now has the boolean value 'true'
127 ```
128
129 posargs:
130 fragment:
131 type: str
132 description: The string fragment to check
133
134 # str.startswith()
135 - name: startswith
136 returns: bool
137 description: Returns true if string starts with the string specified as the argument.
138 posargs_inherit: str.contains
139 example: |
140 ```meson
141 target = 'x86_FreeBSD'
142 is_x86 = target.startswith('x86') # boolean value 'true'
143 ```
144
145 # str.endswith()
146 - name: endswith
147 returns: bool
148 description: Returns true if string ends with the string specified as the argument.
149 posargs_inherit: str.contains
150 example: |
151 ```meson
152 target = 'x86_FreeBSD'
153 is_bsd = target.to_lower().endswith('bsd') # boolean value 'true'
154 ```
155
156 # str.substring()
157 - name: substring
158 returns: str
159 since: 0.56.0
160 description: |
161 Returns a substring specified from `start` to `end`.
162 Both `start` and `end` arguments are optional, so, for example, `'foobar'.substring()` will return `'foobar'`.
163
164 The method accepts negative values where negative `start` is relative to the end of
165 string `len(string) - start` as well as negative `end`.
166
167 If `start` or `end` are out of bounds, the position of the closest character will be used.
168 If `start` is bigger than `end`, the result will be an empty substring.
169
170 example: |
171 ```meson
172 # Similar to the Python str[start:end] syntax
173 target = 'x86_FreeBSD'
174 platform = target.substring(0, 3) # prefix string value 'x86'
175 system = target.substring(4) # suffix string value 'FreeBSD'
176 ```
177
178 Example with negative values:
179
180 ```meson
181 string = 'foobar'
182 string.substring(-5, -3) # => 'oo'
183 string.substring(1, -1) # => 'ooba'
184 ```
185
186 Example with out of bound values:
187
188 ```meson
189 string = 'foobar'
190 string.substring(64) # => ''
191 string.substring(0, 64) # => 'foobar'
192 string.substring(64, 0) # => ''
193 ```
194
195 optargs:
196 start:
197 type: int
198 description: The start position
199
200 end:
201 type: int
202 description: The end position
203
204 # str.split
205 - name: split
206 returns: list[str]
207 description: |
208 Splits the string at the specified character
209 (or whitespace if not set) and returns the parts in an
210 array.
211
212 example: |
213 ```meson
214 # Similar to the Python str.split()
215 components = 'a b c d '.split()
216 # components now has the value ['a', 'b', 'c', 'd']
217 components = 'a b c d '.split(' ')
218 # components now has the value ['a', 'b', '', '', 'c', 'd', '']
219 ```
220
221 optargs:
222 split_string:
223 type: str
224 description: Specifies the character / substring where to split the string.
225
226 - name: splitlines
227 returns: list[str]
228 since: 1.2.0
229 description: |
230 Splits the string into an array of lines.
231 Unlike .split('\n'), the empty string produced an empty array,
232 and if the string ends in a newline, splitlines() doesn't split
233 on that last newline.
234 '\n', '\r' and '\r\n' are all considered newlines.
235
236 example: |
237 ```meson
238 output = 'hello\nworld\n'.splitlines()
239 # Output value is ['hello', 'world']
240 output = ''.splitlines()
241 # Output value is []
242 fs = import('fs')
243 paths = fs.read('my_paths.list').splitlines()
244 # paths is now the paths listed in 'my_paths.list', or an empty list
245 # if 'my_paths.list' is empty
246 ```
247
248 # str.join()
249 - name: join
250 returns: str
251 description: |
252 The opposite of split,
253 for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`.
254
255 example: |
256 ```meson
257 # Similar to the Python str.join()
258 output = ' '.join(['foo', 'bar'])
259 # Output value is 'foo bar'
260 pathsep = ':'
261 path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin'])
262 # path now has the value '/usr/bin:/bin:/usr/local/bin'
263 ```
264
265 varargs:
266 name: strings
267 type: str
268 since: 0.60.0
269 description: |
270 The strings to join with the current string.
271
272 Before Meson *0.60.0* this function only accepts a single positional
273 argument of the type [[list[str]]].
274
275 # str.underscorify
276 - name: underscorify
277 returns: str
278 description: Creates a string where every non-alphabetical non-number character is replaced with `_`.
279 example: |
280 ```meson
281 name = 'Meson Docs.txt#Reference-manual'
282 # Replaces all characters other than `a-zA-Z0-9` with `_` (underscore)
283 # Useful for substituting into #defines, filenames, etc.
284 underscored = name.underscorify()
285 # underscored now has the value 'Meson_Docs_txt_Reference_manual'
286 ```
287
288 # str.version_compare
289 - name: version_compare
290 returns: bool
291 description: Does semantic version comparison.
292 example: |
293 ```meson
294 version = '1.2.3'
295 # Compare version numbers semantically
296 is_new = version.version_compare('>=2.0')
297 # is_new now has the boolean value false
298 # Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
299 ```
300
301 Meson version comparison conventions include:
302
303 ```meson
304 '3.6'.version_compare('>=3.6.0') == false
305 ```
306
307 It is best to be unambiguous and specify the full revision level to compare.
308
309 posargs:
310 compare_string:
311 type: str
312 description: The string to compare to.