lua_std/string_.rs
1use crate::{any, boolean, function, number, option, Repeatable};
2
3/// The type of immutable sequences of bytes.
4///
5/// Strings in Lua can contain any 8-bit value, including embedded zeros,
6/// and are used both for text and for arbitrary binary data. Strings are
7/// immutable: functions like [`upper`](string::upper) return *new*
8/// strings and never modify their argument.
9///
10/// The string library sets a metatable for strings where the `__index`
11/// field points to the library itself, so every string function can be
12/// called in object style:
13///
14/// ```lua
15/// print(string.upper("lua")) --> LUA
16/// print(("lua"):upper()) --> LUA
17/// ```
18///
19/// String indices count from 1; negative indices count backwards from the
20/// end of the string, so −1 is the last byte.
21pub struct string;
22
23/// # Method form
24///
25/// These functions receive the string as `self`, so the string
26/// metatable makes them callable in method form: `("lua"):upper()`
27/// is the same as `string.upper("lua")`.
28impl string {
29
30 /// Returns the internal numeric codes of characters in a string.
31 ///
32 /// # Parameters
33 ///
34 /// - **`i`**: position of the first character (default 1).
35 /// - **`j`**: position of the last character (default `i`).
36 ///
37 /// # Return value
38 ///
39 /// The internal numeric codes of the characters `s[i]`, `s[i+1]`,
40 /// ..., `s[j]`, as integers.
41 ///
42 /// # Examples
43 ///
44 /// ```lua
45 /// print(("A"):byte()) --> 65
46 /// print(("Lua"):byte(1, 3)) --> 76 117 97
47 /// print(("Lua"):byte(-1)) --> 97
48 /// ```
49 ///
50 /// # See also
51 ///
52 /// [`char`](string::char)
53 pub fn byte(&self, i: option<number>, j: option<number>) -> Repeatable<number> {
54 todo!()
55 }
56
57 /// Finds the first match of a pattern in a string.
58 ///
59 /// # Parameters
60 ///
61 /// - **`pattern`**: the pattern to search for.
62 /// - **`init`**: where to start the search (default 1; may be
63 /// negative).
64 /// - **`plain`**: when true, turns off the pattern matching
65 /// facilities: a plain "find substring" is performed, with no
66 /// characters being considered magic.
67 ///
68 /// # Return value
69 ///
70 /// The indices of `s` where the occurrence starts and ends, or `nil`
71 /// if the pattern is not found. If the pattern has captures, the
72 /// captured values are also returned, after the two indices.
73 ///
74 /// # Examples
75 ///
76 /// ```lua
77 /// print(("hello Lua"):find("Lua")) --> 7 9
78 /// print(("hello"):find("l+")) --> 3 4
79 /// print(("a.b"):find(".", 1, true)) --> 2 2 (plain search)
80 /// print(("key=val"):find("(%w+)=(%w+)")) --> 1 7 key val
81 /// ```
82 ///
83 /// # See also
84 ///
85 /// `string.match`, [`gmatch`](string::gmatch), [`gsub`](string::gsub)
86 pub fn find(&self, pattern: string, init: option<number>, plain: option<boolean>) -> option<(number, number)> {
87 todo!()
88 }
89
90 /// Returns a formatted string.
91 ///
92 /// # Parameters
93 ///
94 /// - **`formatstring`**: a format description following the same
95 /// rules as the ISO C function `sprintf`, plus the extra specifier
96 /// `%q`.
97 /// - **`···`**: the values to format.
98 ///
99 /// # Return value
100 ///
101 /// The formatted string. The specifier `%q` formats booleans, nil,
102 /// numbers and strings in a way that the result can be safely read
103 /// back by the Lua interpreter.
104 ///
105 /// # Examples
106 ///
107 /// ```lua
108 /// print(string.format("%s scored %.1f%%", "Ana", 97.5))
109 /// --> Ana scored 97.5%
110 /// print(string.format("%5d|%-5d|", 42, 42)) --> 42|42 |
111 /// print(string.format("%q", 'he said "hi"')) --> "he said \"hi\""
112 /// print(string.format("%x", 255)) --> ff
113 /// ```
114 pub fn format(&self, values: Repeatable<any>) -> string {
115 todo!()
116 }
117
118 /// Returns an iterator over the matches of a pattern in a string.
119 ///
120 /// # Parameters
121 ///
122 /// - **`pattern`**: the pattern to search for.
123 /// - **`init`**: where to start the search (default 1).
124 ///
125 /// # Return value
126 ///
127 /// An iterator function that, each time it is called, returns the
128 /// next captures from `pattern` over `s`. If the pattern specifies no
129 /// captures, the whole match is produced in each call. Anchors (`^`)
130 /// do not work in `gmatch`, as that would prevent iteration.
131 ///
132 /// # Examples
133 ///
134 /// ```lua
135 /// for word in ("one two three"):gmatch("%a+") do
136 /// print(word) --> one / two / three
137 /// end
138 /// for k, v in ("a=1, b=2"):gmatch("(%w+)=(%w+)") do
139 /// print(k, v) --> a 1 / b 2
140 /// end
141 /// ```
142 ///
143 /// # See also
144 ///
145 /// `string.match`, [`find`](string::find)
146 pub fn gmatch(&self, pattern: string, init: option<number>) -> function {
147 todo!()
148 }
149
150 /// Returns a copy of a string with pattern matches replaced.
151 ///
152 /// # Parameters
153 ///
154 /// - **`pattern`**: the pattern to search for.
155 /// - **`repl`**: the replacement — a string (where `%1` to `%9` stand
156 /// for captures and `%0` for the whole match), a table (queried
157 /// with the first capture as key), or a function (called with all
158 /// captures as arguments). A false or `nil` result keeps the
159 /// original match.
160 /// - **`n`**: the maximum number of substitutions (default:
161 /// unlimited).
162 ///
163 /// # Return value
164 ///
165 /// A copy of `s` with the replacements made, plus the total number
166 /// of matches that occurred.
167 ///
168 /// # Examples
169 ///
170 /// ```lua
171 /// print(("hello world"):gsub("o", "0")) --> hell0 w0rld 2
172 /// print(("hello world"):gsub("o", "0", 1)) --> hell0 world 1
173 /// print(("hello"):gsub("(l+)", "[%1]")) --> he[ll]o 1
174 /// print(("2+3"):gsub("%d", function(d)
175 /// return d * 10
176 /// end)) --> 20+30 2
177 /// ```
178 ///
179 /// # See also
180 ///
181 /// [`find`](string::find), [`gmatch`](string::gmatch)
182 pub fn gsub(&self, pattern: string, repl: any, n: option<number>) -> (string, number) {
183 todo!()
184 }
185
186 /// Returns the length of a string.
187 ///
188 /// # Return value
189 ///
190 /// The length of the string in bytes — equivalent to the `#`
191 /// operator. Embedded zeros are counted.
192 ///
193 /// # Examples
194 ///
195 /// ```lua
196 /// print(("hello"):len()) --> 5
197 /// print(#"hello") --> 5
198 /// print(("a\0b"):len()) --> 3
199 /// ```
200 pub fn len(&self) -> number {
201 todo!()
202 }
203
204 /// Converts a string to lowercase.
205 ///
206 /// # Return value
207 ///
208 /// A copy of the string with all uppercase letters changed to
209 /// lowercase; all other characters are left unchanged. The definition
210 /// of what an uppercase letter is depends on the current locale.
211 ///
212 /// # Examples
213 ///
214 /// ```lua
215 /// print(("Hello, World!"):lower()) --> hello, world!
216 /// ```
217 ///
218 /// # See also
219 ///
220 /// [`upper`](string::upper)
221 pub fn lower(&self) -> string {
222 todo!()
223 }
224
225 /// Finds the first match of a pattern and returns its captures.
226 ///
227 /// # Parameters
228 ///
229 /// - **`pattern`**: the pattern to search for.
230 /// - **`init`**: where to start the search (default 1).
231 ///
232 /// # Return value
233 ///
234 /// The captures from the first match of `pattern` in `s`; if the
235 /// pattern specifies no captures, the whole match is returned.
236 /// Returns `nil` when there is no match.
237 ///
238 /// # Examples
239 ///
240 /// ```lua
241 /// print(("hello 42 world"):match("%d+")) --> 42
242 /// print(("key = value"):match("(%w+)%s*=%s*(%w+)")) --> key value
243 /// print(("hello"):match("%d+")) --> nil
244 /// ```
245 ///
246 /// # See also
247 ///
248 /// [`find`](string::find), [`gmatch`](string::gmatch)
249 pub fn r#match(&self, pattern: string, init: option<number>) -> Repeatable<any> {
250 todo!()
251 }
252
253 /// Repeats a string.
254 ///
255 /// # Parameters
256 ///
257 /// - **`n`**: the number of copies.
258 /// - **`sep`**: a separator inserted between copies (default: the
259 /// empty string).
260 ///
261 /// # Return value
262 ///
263 /// A string that is the concatenation of `n` copies of `s` separated
264 /// by `sep`. If `n` is not positive, the empty string.
265 ///
266 /// # Examples
267 ///
268 /// ```lua
269 /// print(("ab"):rep(3)) --> ababab
270 /// print(("ab"):rep(3, "-")) --> ab-ab-ab
271 /// print(("ab"):rep(0)) --> (empty string)
272 /// ```
273 pub fn rep(&self, n: number, sep: option<string>) -> string {
274 todo!()
275 }
276
277 /// Reverses a string.
278 ///
279 /// # Return value
280 ///
281 /// A string with the bytes of `s` in reverse order.
282 ///
283 /// # Examples
284 ///
285 /// ```lua
286 /// print(("Lua"):reverse()) --> auL
287 /// ```
288 pub fn reverse(&self) -> string {
289 todo!()
290 }
291
292 /// Extracts a substring.
293 ///
294 /// # Parameters
295 ///
296 /// - **`i`**: position of the first character. Negative values count
297 /// from the end of the string.
298 /// - **`j`**: position of the last character (default −1, the end of
299 /// the string).
300 ///
301 /// # Return value
302 ///
303 /// The substring of `s` that starts at `i` and continues until `j`,
304 /// inclusive. If `i` is greater than `j` (after normalising negative
305 /// indices), the empty string.
306 ///
307 /// # Examples
308 ///
309 /// ```lua
310 /// print(("hello"):sub(2, 4)) --> ell
311 /// print(("hello"):sub(2)) --> ello
312 /// print(("hello"):sub(-3)) --> llo
313 /// print(("hello"):sub(2, -2)) --> ell
314 /// ```
315 pub fn sub(&self, i: number, j: option<number>) -> string {
316 todo!()
317 }
318
319 /// Converts a string to uppercase.
320 ///
321 /// # Return value
322 ///
323 /// A copy of the string with all lowercase letters changed to
324 /// uppercase; all other characters are left unchanged. The definition
325 /// of what a lowercase letter is depends on the current locale.
326 ///
327 /// # Examples
328 ///
329 /// ```lua
330 /// print(("Hello, World!"):upper()) --> HELLO, WORLD!
331 /// ```
332 ///
333 /// # See also
334 ///
335 /// [`lower`](string::lower)
336 pub fn upper(&self) -> string {
337 todo!()
338 }
339
340}
341
342/// # Library functions
343///
344/// These functions take no string `self` and are only reachable
345/// through the library table itself, e.g. `string.char(76, 117, 97)`.
346impl string {
347 /// Builds a string from numeric character codes.
348 ///
349 /// # Parameters
350 ///
351 /// - **`···`**: zero or more integers, one per character.
352 ///
353 /// # Return value
354 ///
355 /// A string with length equal to the number of arguments, in which
356 /// each character has the internal numeric code equal to its
357 /// corresponding argument.
358 ///
359 /// # Examples
360 ///
361 /// ```lua
362 /// print(string.char(76, 117, 97)) --> Lua
363 /// print(string.char()) --> (empty string)
364 /// ```
365 ///
366 /// # See also
367 ///
368 /// [`byte`](string::byte)
369 pub fn char(codes: Repeatable<number>) -> string {
370 todo!()
371 }
372
373 /// Serializes a function into a binary string.
374 ///
375 /// # Parameters
376 ///
377 /// - **`function`**: a Lua function without upvalues... or with —
378 /// upvalues are saved only by their *number*, with fresh ones
379 /// created on load.
380 /// - **`strip`**: when true, the binary may not include debug
381 /// information (line numbers, local names).
382 ///
383 /// # Return value
384 ///
385 /// A binary string that, passed to [`load`](crate::load), returns a
386 /// copy of the function. Functions defined in C cannot be dumped.
387 ///
388 /// # Examples
389 ///
390 /// ```lua
391 /// local f = function(x) return x * 2 end
392 /// local bin = string.dump(f)
393 /// local g = load(bin)
394 /// print(g(21)) --> 42
395 /// ```
396 pub fn dump(f: function, strip: option<boolean>) -> string {
397 todo!()
398 }
399
400 /// Serializes values into a binary string.
401 ///
402 /// # Parameters
403 ///
404 /// - **`fmt`**: a format string describing the layout — e.g. `"i4"`
405 /// for a 4-byte signed integer, `"d"` for a double, `"z"` for a
406 /// zero-terminated string, with `<` and `>` selecting endianness
407 /// (§6.4.2 of the manual lists all options).
408 /// - **`v1, v2, ···`**: the values to serialize.
409 ///
410 /// # Return value
411 ///
412 /// A binary string containing the values packed according to `fmt`.
413 ///
414 /// # Examples
415 ///
416 /// ```lua
417 /// local bin = string.pack("<i4i4", 1, 2)
418 /// print(#bin) --> 8
419 /// print(string.unpack("<i4i4", bin)) --> 1 2 9
420 /// ```
421 ///
422 /// # See also
423 ///
424 /// [`unpack`](string::unpack), [`packsize`](string::packsize)
425 pub fn pack(fmt: string, values: Repeatable<any>) -> string {
426 todo!()
427 }
428
429 /// Returns the size of a pack format.
430 ///
431 /// # Parameters
432 ///
433 /// - **`fmt`**: a format string as in [`pack`](string::pack). It
434 /// must not contain variable-size options (`s` or `z`).
435 ///
436 /// # Return value
437 ///
438 /// The total size in bytes of a string produced by
439 /// [`pack`](string::pack) with the given format.
440 ///
441 /// # Examples
442 ///
443 /// ```lua
444 /// print(string.packsize("i4i4")) --> 8
445 /// print(string.packsize("dd")) --> 16
446 /// ```
447 pub fn packsize(fmt: string) -> number {
448 todo!()
449 }
450
451 /// Deserializes values from a binary string.
452 ///
453 /// # Parameters
454 ///
455 /// - **`fmt`**: a format string as in [`pack`](string::pack).
456 /// - **`s`**: the binary string to read.
457 /// - **`pos`**: where to start reading (default 1).
458 ///
459 /// # Return value
460 ///
461 /// The values packed in `s` according to `fmt`, followed by the
462 /// index of the first unread byte.
463 ///
464 /// # Examples
465 ///
466 /// ```lua
467 /// local bin = string.pack("i4z", 7, "hi")
468 /// print(string.unpack("i4z", bin)) --> 7 hi 8
469 /// ```
470 ///
471 /// # See also
472 ///
473 /// [`pack`](string::pack), [`packsize`](string::packsize)
474 pub fn unpack(fmt: string, s: string, pos: option<number>) -> Repeatable<any> {
475 todo!()
476 }
477}