lua_std/table_.rs
1use crate::{any, function, number, option, string, Repeatable};
2
3/// The type of associative arrays — the sole data-structuring mechanism
4/// in Lua.
5///
6/// Tables can be indexed with any value except `nil` and NaN, and can hold
7/// values of any type. They are used to represent arrays, sequences,
8/// records, sets, modules and objects alike. Like functions, tables are
9/// *objects*: variables hold references to tables, and assignment,
10/// parameter passing and returns never cause copies.
11///
12/// ```lua
13/// local point = { x = 10, y = 20 }
14/// local list = { "a", "b", "c" }
15/// print(point.x, list[2], #list) --> 10 b 3
16/// ```
17///
18/// Most functions in the table library assume the table is a *sequence*:
19/// its positive numeric keys form the set 1..#t without holes.
20pub struct table;
21
22/// # Method form
23///
24/// These functions operate on a table passed as their first argument
25/// (`self` in the signatures). Unlike strings, plain tables have no
26/// default metatable, so the usual call is `table.insert(t, v)`; the
27/// method form `t:insert(v)` only works if you point a table's
28/// `__index` at the table library yourself.
29impl table {
30
31 /// Joins the elements of a sequence into a string.
32 ///
33 /// # Parameters
34 ///
35 /// - **`sep`**: a string placed between elements (default: the empty
36 /// string).
37 /// - **`i`**: index of the first element (default 1).
38 /// - **`j`**: index of the last element (default `#list`).
39 ///
40 /// # Return value
41 ///
42 /// The string `list[i] .. sep .. list[i+1] .. sep .. ... .. sep ..
43 /// list[j]`. All elements in the range must be strings or numbers.
44 /// If `i` is greater than `j`, the empty string.
45 ///
46 /// # Examples
47 ///
48 /// ```lua
49 /// print(table.concat({"a", "b", "c"})) --> abc
50 /// print(table.concat({"a", "b", "c"}, ", ")) --> a, b, c
51 /// print(table.concat({1, 2, 3}, "+", 2, 3)) --> 2+3
52 /// ```
53 pub fn concat(&self, sep: option<string>, i: option<number>, j: option<number>) -> string {
54 todo!()
55 }
56
57 /// Inserts an element into a sequence.
58 ///
59 /// # Parameters
60 ///
61 /// - **`pos`**: the position for the new element, from 1 to
62 /// `#list + 1` (default `#list + 1`, i.e. append).
63 /// - **`value`**: the value to insert.
64 ///
65 /// # Description
66 ///
67 /// Inserts `value` at position `pos`, shifting up the elements
68 /// `list[pos], list[pos+1], ..., list[#list]`. The two-argument form
69 /// appends `value` at the end of the sequence.
70 ///
71 /// # Examples
72 ///
73 /// ```lua
74 /// local t = {"a", "c"}
75 /// table.insert(t, "d") -- {"a", "c", "d"}
76 /// table.insert(t, 2, "b") -- {"a", "b", "c", "d"}
77 /// print(table.concat(t)) --> abcd
78 /// ```
79 ///
80 /// # See also
81 ///
82 /// [`remove`](table::remove)
83 pub fn insert(&self, pos: option<number>, value: any) {
84 todo!()
85 }
86
87 /// Removes an element from a sequence.
88 ///
89 /// # Parameters
90 ///
91 /// - **`pos`**: the position of the element to remove (default
92 /// `#list`, i.e. the last element).
93 ///
94 /// # Return value
95 ///
96 /// The removed value. The elements `list[pos+1], ..., list[#list]`
97 /// are shifted down to close the gap.
98 ///
99 /// # Examples
100 ///
101 /// ```lua
102 /// local t = {"a", "b", "c"}
103 /// print(table.remove(t)) --> c
104 /// print(table.remove(t, 1)) --> a
105 /// print(table.concat(t)) --> b
106 /// ```
107 ///
108 /// # See also
109 ///
110 /// [`insert`](table::insert)
111 pub fn remove(&self, pos: option<number>) -> any {
112 todo!()
113 }
114
115 /// Sorts a sequence in place.
116 ///
117 /// # Parameters
118 ///
119 /// - **`comp`**: a function that receives two list elements and
120 /// returns true when the first must come before the second in the
121 /// final order. When absent, the standard `<` operator is used.
122 /// `comp` must define a strict order: `comp(a, a)` must be false.
123 ///
124 /// # Description
125 ///
126 /// Sorts the elements from `list[1]` to `list[#list]` in place. The
127 /// sort algorithm is not stable: elements considered equal by the
128 /// given order may have their relative positions changed by the sort.
129 ///
130 /// # Examples
131 ///
132 /// ```lua
133 /// local t = {3, 1, 2}
134 /// table.sort(t)
135 /// print(table.concat(t, ",")) --> 1,2,3
136 /// table.sort(t, function(a, b) return a > b end)
137 /// print(table.concat(t, ",")) --> 3,2,1
138 /// ```
139 pub fn sort(&self, comp: option<function>) {
140 todo!()
141 }
142
143 /// Returns the elements of a sequence as multiple values.
144 ///
145 /// # Parameters
146 ///
147 /// - **`i`**: index of the first element (default 1).
148 /// - **`j`**: index of the last element (default `#list`).
149 ///
150 /// # Return value
151 ///
152 /// The values `list[i], list[i+1], ..., list[j]`.
153 ///
154 /// # Examples
155 ///
156 /// ```lua
157 /// print(table.unpack({"a", "b", "c"})) --> a b c
158 /// print(table.unpack({"a", "b", "c"}, 2)) --> b c
159 /// local function sum3(x, y, z) return x + y + z end
160 /// print(sum3(table.unpack({1, 2, 3}))) --> 6
161 /// ```
162 ///
163 /// # See also
164 ///
165 /// [`pack`](table::pack)
166 pub fn unpack(&self, i: option<number>, j: option<number>) -> Repeatable<any> {
167 todo!()
168 }
169
170}
171
172/// # Library functions
173///
174/// These functions do not operate on a single table `self` and are
175/// only reachable through the library table, e.g. `table.pack(...)`.
176impl table {
177 /// Creates a preallocated table. **New in Lua 5.5.**
178 ///
179 /// # Parameters
180 ///
181 /// - **`nseq`**: a hint for how many elements the table will have as
182 /// a sequence.
183 /// - **`nrec`**: a hint for how many *other* elements the table will
184 /// have (default 0).
185 ///
186 /// # Return value
187 ///
188 /// A new empty table with memory preallocated for `nseq` sequence
189 /// elements and `nrec` other elements. Preallocation avoids
190 /// incremental growth and rehashing, which helps performance when
191 /// the final size of the table is known in advance.
192 ///
193 /// # Examples
194 ///
195 /// ```lua
196 /// local t = table.create(3)
197 /// t[1], t[2], t[3] = "a", "b", "c" -- no reallocation happens
198 /// print(#t) --> 3
199 /// ```
200 ///
201 /// # See also
202 ///
203 /// [`pack`](table::pack)
204 pub fn create(nseq: number, nrec: option<number>) -> table {
205 todo!()
206 }
207
208 /// Moves a range of elements from one table to another.
209 ///
210 /// # Parameters
211 ///
212 /// - **`a1`**: the source table.
213 /// - **`f`**: index of the first element to move.
214 /// - **`e`**: index of the last element to move.
215 /// - **`t`**: the destination index.
216 /// - **`a2`**: the destination table (default `a1`).
217 ///
218 /// # Return value
219 ///
220 /// The destination table. Performs the equivalent of the multiple
221 /// assignment `a2[t], ··· = a1[f], ···, a1[e]`. The ranges may
222 /// overlap, and the number of elements moved must fit in an integer.
223 ///
224 /// # Examples
225 ///
226 /// ```lua
227 /// local a = {1, 2, 3, 4}
228 /// local b = table.move(a, 2, 4, 1, {})
229 /// print(table.concat(b, ",")) --> 2,3,4
230 /// table.move(a, 1, 3, 2) -- shift right inside a
231 /// print(table.concat(a, ",")) --> 1,1,2,3
232 /// ```
233 pub fn r#move(a1: table, f: number, e: number, t: number, a2: option<table>) -> table {
234 todo!()
235 }
236
237 /// Packs its arguments into a new table.
238 ///
239 /// # Parameters
240 ///
241 /// - **`···`**: any number of values.
242 ///
243 /// # Return value
244 ///
245 /// A new table with all arguments stored into keys 1, 2, etc. and
246 /// with a field `n` holding the total number of arguments. The
247 /// resulting table may not be a sequence, if some arguments are
248 /// `nil`.
249 ///
250 /// # Examples
251 ///
252 /// ```lua
253 /// local t = table.pack("a", "b", "c")
254 /// print(t.n, t[1], t[3]) --> 3 a c
255 /// local u = table.pack(1, nil, 3)
256 /// print(u.n) --> 3 (n counts the nil too)
257 /// ```
258 ///
259 /// # See also
260 ///
261 /// [`unpack`](table::unpack), [`select`](crate::select)
262 pub fn pack(values: Repeatable<any>) -> table {
263 todo!()
264 }
265}