@ygracs/xobj-lib-js 0.1.2 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +25 -65
- package/LICENSE +1 -1
- package/README.md +5 -2
- package/doc/xObj.md +927 -144
- package/lib/xObj-lib.js +866 -668
- package/package.json +3 -3
package/doc/xObj.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
>|***rev.*:**|0.1.
|
|
1
|
+
>|***rev.*:**|0.1.43|
|
|
2
2
|
>|:---|---:|
|
|
3
|
-
>|date:|
|
|
3
|
+
>|date:|2025-01-28|
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Introduction
|
|
6
6
|
|
|
7
7
|
This paper describes a functions provided by `xObj.js` module.
|
|
8
8
|
|
|
@@ -10,6 +10,32 @@ This paper describes a functions provided by `xObj.js` module.
|
|
|
10
10
|
|
|
11
11
|
## Content
|
|
12
12
|
|
|
13
|
+
### Base type definitions
|
|
14
|
+
|
|
15
|
+
This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function descriptions.
|
|
16
|
+
|
|
17
|
+
<a name="typedef+OPT_valtostr"></a>
|
|
18
|
+
#### `OPT_valtostr` - options set
|
|
19
|
+
|
|
20
|
+
This options set is an `object` which defines how a value transforms to a 'string' type.
|
|
21
|
+
|
|
22
|
+
| option name | option type | default value | description |
|
|
23
|
+
|:---|---|---:|:---|
|
|
24
|
+
| `useTrim` | `boolean` | `false` | defines whether or not the resulting string must to be trimmed |
|
|
25
|
+
| `letterCase` | `string` | --- | if given defines a function behavior on the resulting string |
|
|
26
|
+
| `numberToString` | `boolean` | `false` | if set a values of `number` types will be converted to a string |
|
|
27
|
+
| `boolToString` | `boolean` | `false` | if set a values of `boolean` types will be converted to a string |
|
|
28
|
+
| `boolToUpperCase` | `boolean` | `false` | if set a values of `boolean` types when converted to a string will be present in upper case |
|
|
29
|
+
| `defValue` | `string` | `EMPTY_STRING` | if given represents a value which will be returned in case the function failed |
|
|
30
|
+
|
|
31
|
+
The behavior for `letterCase` settings defined in the table below:
|
|
32
|
+
|
|
33
|
+
| option value | description |
|
|
34
|
+
|:---|:---|
|
|
35
|
+
| `upper` | the resulting string must to be present in upper case |
|
|
36
|
+
| `lower` | the resulting string must to be present in lower case |
|
|
37
|
+
| any other values | the resulting string will be not transformed |
|
|
38
|
+
|
|
13
39
|
### Base constants
|
|
14
40
|
|
|
15
41
|
|name|type|value|
|
|
@@ -47,256 +73,1032 @@ The settings listed in the table below:
|
|
|
47
73
|
|trim|`boolean`|`true`|
|
|
48
74
|
|spaces|`number`|`2`|
|
|
49
75
|
|
|
50
|
-
### Base functions for read
|
|
76
|
+
### Base functions for read an object parameter value
|
|
51
77
|
|
|
52
78
|
> Note:
|
|
53
|
-
> If a `key` parameter
|
|
54
|
-
|
|
55
|
-
|
|
79
|
+
> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
|
|
80
|
+
|
|
81
|
+
<a name="readXObjParam"></a>
|
|
82
|
+
#### **readXObjParam(object\[, key])** => `string`
|
|
83
|
+
|
|
84
|
+
This function returns a value of an object parameter as a string.
|
|
85
|
+
|
|
86
|
+
##### ***parameters***
|
|
56
87
|
|
|
57
|
-
|
|
88
|
+
| parameter name | value type | default value | description |
|
|
89
|
+
|:---|---|---:|:---|
|
|
90
|
+
| `object` | `object` | --- | some object |
|
|
91
|
+
| `key` | `string` | --- | some key |
|
|
92
|
+
|
|
93
|
+
##### ***exceptions***
|
|
94
|
+
|
|
95
|
+
The function throws a `TypeError` exception in case:
|
|
58
96
|
|
|
59
|
-
|
|
97
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
98
|
+
+ if `object` parameter is not an `Object` instance.
|
|
60
99
|
|
|
61
|
-
|
|
100
|
+
<a name="readXObjParamAsBool"></a>
|
|
101
|
+
#### **readXObjParamAsBool(object\[, defValue \[, key]])** => `boolean`
|
|
62
102
|
|
|
63
103
|
This function reads a value of an object parameter and returns it as a `boolean`.
|
|
64
104
|
|
|
65
|
-
|
|
105
|
+
##### ***parameters***
|
|
106
|
+
|
|
107
|
+
| parameter name | value type | default value | description |
|
|
108
|
+
|:---|---|---:|:---|
|
|
109
|
+
| `object` | `object` | --- | some object |
|
|
110
|
+
| `defValue` | `boolean` | `false` | default value |
|
|
111
|
+
| `key` | `string` | --- | some key |
|
|
112
|
+
|
|
113
|
+
##### ***exceptions***
|
|
66
114
|
|
|
67
|
-
|
|
115
|
+
The function throws a `TypeError` exception in case:
|
|
116
|
+
|
|
117
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
118
|
+
+ if `object` parameter is not an `Object` instance.
|
|
119
|
+
|
|
120
|
+
<a name="readXObjParamAsNum"></a>
|
|
121
|
+
#### **readXObjParamAsNum(object\[, defValue \[, key])** => `number`
|
|
68
122
|
|
|
69
123
|
This function reads a value of an object parameter and returns it as a `number`.
|
|
70
124
|
|
|
71
|
-
|
|
125
|
+
##### ***parameters***
|
|
72
126
|
|
|
73
|
-
|
|
127
|
+
| parameter name | value type | default value | description |
|
|
128
|
+
|:---|---|---:|:---|
|
|
129
|
+
| `object` | `object` | --- | some object |
|
|
130
|
+
| `defValue` | `number` | `0` | default value |
|
|
131
|
+
| `key` | `string` | --- | some key |
|
|
74
132
|
|
|
75
|
-
|
|
133
|
+
##### ***exceptions***
|
|
76
134
|
|
|
77
|
-
The
|
|
135
|
+
The function throws a `TypeError` exception in case:
|
|
78
136
|
|
|
79
|
-
|
|
137
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
138
|
+
+ if `object` parameter is not an `Object` instance.
|
|
139
|
+
|
|
140
|
+
<a name="readXObjParamAsIndex"></a>
|
|
141
|
+
#### **readXObjParamAsIndex(object\[, key])** => `number`
|
|
80
142
|
|
|
81
143
|
This function reads a value of an object parameter and try to convert it to a valid index value. If function failed, `-1` is returned.
|
|
82
144
|
|
|
83
145
|
> Note: *for use in this case, index is validated as a non-negative integer number.*
|
|
84
146
|
|
|
85
|
-
|
|
147
|
+
##### ***parameters***
|
|
148
|
+
|
|
149
|
+
| parameter name | value type | default value | description |
|
|
150
|
+
|:---|---|---:|:---|
|
|
151
|
+
| `object` | `object` | --- | some object |
|
|
152
|
+
| `key` | `string` | --- | some key |
|
|
153
|
+
|
|
154
|
+
##### ***exceptions***
|
|
155
|
+
|
|
156
|
+
The function throws a `TypeError` exception in case:
|
|
157
|
+
|
|
158
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
159
|
+
+ if `object` parameter is not an `Object` instance.
|
|
160
|
+
|
|
161
|
+
#### **readXObjParamAsStr(object\[, defValue \[, key])** => `string`
|
|
162
|
+
|
|
163
|
+
> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjParam`](#readxobjparamobject-key--string) or [`readXObjParamEx`](#readxobjparamexobject-opt-key--string) instead.*
|
|
164
|
+
|
|
165
|
+
This function reads a value of an object parameter and returns it as a `string`.
|
|
166
|
+
|
|
167
|
+
The `defValue` must be of a `string` type, if else the empty string is used.
|
|
168
|
+
|
|
169
|
+
<a name="readXObjParamEx"></a>
|
|
170
|
+
#### **readXObjParamEx(object\[, options \[, key])** => `string`
|
|
171
|
+
|
|
172
|
+
> since: \[v0.2.0]
|
|
173
|
+
|
|
174
|
+
This function reads a value of an object parameter and returns it as a `string`.
|
|
175
|
+
|
|
176
|
+
##### ***parameters***
|
|
177
|
+
|
|
178
|
+
| parameter name | value type | default value | description |
|
|
179
|
+
|:---|---|---:|:---|
|
|
180
|
+
| `object` | `object` | --- | some object |
|
|
181
|
+
| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
|
|
182
|
+
| `key` | `string` | --- | some key |
|
|
183
|
+
|
|
184
|
+
An `options` parameter must be a `string` or an `object`.
|
|
185
|
+
|
|
186
|
+
> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
|
|
187
|
+
|
|
188
|
+
If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
|
|
189
|
+
|
|
190
|
+
If `options` is of a `string` type the function treats it as a value of `options.defValue`.
|
|
191
|
+
|
|
192
|
+
If `options` is not given the settings listed in table below are used by default:
|
|
193
|
+
|
|
194
|
+
| option name | option type | value |
|
|
195
|
+
|:---|---|---:|
|
|
196
|
+
| `useTrim` | `boolean` | `false` |
|
|
197
|
+
| `numberToString` | `boolean` | `true` |
|
|
198
|
+
| `boolToString` | `boolean` | `true` |
|
|
199
|
+
| `defValue` | `string` | `EMPTY_STRING` |
|
|
200
|
+
|
|
201
|
+
##### ***exceptions***
|
|
202
|
+
|
|
203
|
+
The function throws a `TypeError` exception in case:
|
|
204
|
+
|
|
205
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
206
|
+
+ if `object` parameter is not an `Object` instance.
|
|
207
|
+
|
|
208
|
+
### Base functions for write an object parameter value
|
|
209
|
+
|
|
210
|
+
> Note:
|
|
211
|
+
> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
|
|
212
|
+
|
|
213
|
+
<a name="writeXObjParam"></a>
|
|
214
|
+
#### **writeXObjParam(object, value\[, key])** => `boolean`
|
|
86
215
|
|
|
87
216
|
This function sets object parameter to a given value and if succeed returns `true`.
|
|
88
217
|
|
|
89
|
-
|
|
218
|
+
##### ***parameters***
|
|
219
|
+
|
|
220
|
+
| parameter name | value type | default value | description |
|
|
221
|
+
|:---|---|---:|:---|
|
|
222
|
+
| `object` | `object` | --- | some object |
|
|
223
|
+
| `value` | `any` | --- | some value to write |
|
|
224
|
+
| `key` | `string` | --- | some key |
|
|
225
|
+
|
|
226
|
+
##### ***exceptions***
|
|
227
|
+
|
|
228
|
+
The function throws a `TypeError` exception in case:
|
|
229
|
+
|
|
230
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
231
|
+
+ if `object` parameter is not an `Object` instance.
|
|
232
|
+
|
|
233
|
+
<a name="writeXObjParamAsBool"></a>
|
|
234
|
+
#### **writeXObjParamAsBool(object, value\[, defValue\[, key]])** => `boolean`
|
|
90
235
|
|
|
91
236
|
This function writes a given `boolean` value of an object parameter.
|
|
92
237
|
|
|
93
|
-
|
|
238
|
+
##### ***parameters***
|
|
239
|
+
|
|
240
|
+
| parameter name | value type | default value | description |
|
|
241
|
+
|:---|---|---:|:---|
|
|
242
|
+
| `object` | `object` | --- | some object |
|
|
243
|
+
| `value` | `any` | --- | some value to write |
|
|
244
|
+
| `defValue` | `boolean` | `false` | default value |
|
|
245
|
+
| `key` | `string` | --- | some key |
|
|
246
|
+
|
|
247
|
+
##### ***exceptions***
|
|
94
248
|
|
|
95
|
-
|
|
249
|
+
The function throws a `TypeError` exception in case:
|
|
250
|
+
|
|
251
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
252
|
+
+ if `object` parameter is not an `Object` instance.
|
|
253
|
+
|
|
254
|
+
<a name="writeXObjParamAsNum"></a>
|
|
255
|
+
#### **writeXObjParamAsNum(object, value\[, defValue\[, key]])** => `boolean`
|
|
96
256
|
|
|
97
257
|
This function writes a given `number` value of an object parameter.
|
|
98
258
|
|
|
99
|
-
|
|
259
|
+
##### ***parameters***
|
|
260
|
+
|
|
261
|
+
| parameter name | value type | default value | description |
|
|
262
|
+
|:---|---|---:|:---|
|
|
263
|
+
| `object` | `object` | --- | some object |
|
|
264
|
+
| `value` | `any` | --- | some value to write |
|
|
265
|
+
| `defValue` | `number` | `0` | default value |
|
|
266
|
+
| `key` | `string` | --- | some key |
|
|
267
|
+
|
|
268
|
+
##### ***exceptions***
|
|
269
|
+
|
|
270
|
+
The function throws a `TypeError` exception in case:
|
|
100
271
|
|
|
101
|
-
|
|
272
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
273
|
+
+ if `object` parameter is not an `Object` instance.
|
|
274
|
+
|
|
275
|
+
<a name="writeXObjParamAsIndex"></a>
|
|
276
|
+
#### **writeXObjParamAsIndex(object, value\[, key])** => `boolean`
|
|
102
277
|
|
|
103
278
|
This function try to interpret a given value as a valid index value and, if succeed, writes it into an object parameter.
|
|
104
279
|
|
|
105
|
-
|
|
280
|
+
##### ***parameters***
|
|
281
|
+
|
|
282
|
+
| parameter name | value type | default value | description |
|
|
283
|
+
|:---|---|---:|:---|
|
|
284
|
+
| `object` | `object` | --- | some object |
|
|
285
|
+
| `value` | `any` | --- | some value to write |
|
|
286
|
+
| `key` | `string` | --- | some key |
|
|
287
|
+
|
|
288
|
+
##### ***exceptions***
|
|
289
|
+
|
|
290
|
+
The function throws a `TypeError` exception in case:
|
|
291
|
+
|
|
292
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
293
|
+
+ if `object` parameter is not an `Object` instance.
|
|
294
|
+
|
|
295
|
+
<a name="writeXObjParamEx"></a>
|
|
296
|
+
#### **writeXObjParamEx(object, value\[, options\[, key]])** => `boolean`
|
|
106
297
|
|
|
107
298
|
This function sets object parameter to a given value and if succeed returns `true`.
|
|
108
299
|
|
|
109
|
-
|
|
300
|
+
##### ***parameters***
|
|
301
|
+
|
|
302
|
+
| parameter name | value type | default value | description |
|
|
303
|
+
|:---|---|---:|:---|
|
|
304
|
+
| `object` | `object` | --- | some object |
|
|
305
|
+
| `value` | `any` | --- | some value to write |
|
|
306
|
+
| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
|
|
307
|
+
| `key` | `string` | --- | some key |
|
|
308
|
+
|
|
309
|
+
An `options` parameter must be a `string` or an `object`.
|
|
310
|
+
|
|
311
|
+
> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
|
|
312
|
+
|
|
313
|
+
If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
|
|
314
|
+
|
|
315
|
+
If `options` is of a `string` type the function treats it as a value of `options.defValue`.
|
|
316
|
+
|
|
317
|
+
If `options` is not given the settings listed in table below are used by default:
|
|
318
|
+
|
|
319
|
+
| option name | option type | value |
|
|
320
|
+
|:---|---|---:|
|
|
321
|
+
| `useTrim` | `boolean` | `false` |
|
|
322
|
+
| `numberToString` | `boolean` | `true` |
|
|
323
|
+
| `boolToString` | `boolean` | `true` |
|
|
324
|
+
| `defValue` | `string` | `EMPTY_STRING` |
|
|
325
|
+
|
|
326
|
+
##### ***exceptions***
|
|
327
|
+
|
|
328
|
+
The function throws a `TypeError` exception in case:
|
|
329
|
+
|
|
330
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
331
|
+
+ if `object` parameter is not an `Object` instance.
|
|
332
|
+
|
|
333
|
+
### Base functions for read an object attributes value
|
|
110
334
|
|
|
111
335
|
> Note:
|
|
112
|
-
> If a `key` parameter
|
|
113
|
-
>
|
|
114
|
-
> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception.
|
|
115
|
-
>
|
|
116
|
-
> If an `attr` parameter given to the function is not a 'string' type, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
|
|
336
|
+
> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
|
|
117
337
|
|
|
118
|
-
|
|
338
|
+
<a name="readXObjAttr"></a>
|
|
339
|
+
#### **readXObjAttr(object, attr\[, key])** => `string`
|
|
119
340
|
|
|
120
341
|
This function returns a value of an object attribute. The value is of a `string` type.
|
|
121
342
|
|
|
122
|
-
|
|
343
|
+
##### ***parameters***
|
|
344
|
+
|
|
345
|
+
| parameter name | value type | default value | description |
|
|
346
|
+
|:---|---|---:|:---|
|
|
347
|
+
| `object` | `object` | --- | some object |
|
|
348
|
+
| `attr` | `string` | --- | some attribute |
|
|
349
|
+
| `key` | `string` | --- | some key |
|
|
350
|
+
|
|
351
|
+
##### ***exceptions***
|
|
352
|
+
|
|
353
|
+
The function throws a `TypeError` exception in case:
|
|
354
|
+
|
|
355
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
356
|
+
+ if `object` parameter is not an `Object` instance.
|
|
357
|
+
|
|
358
|
+
<a name="readXObjAttrAsBool"></a>
|
|
359
|
+
#### **readXObjAttrAsBool(object, attr\[, defValue\[, key]])** => `boolean`
|
|
123
360
|
|
|
124
361
|
This function reads a value of an object attribute and returns it as a `boolean`.
|
|
125
362
|
|
|
126
|
-
|
|
363
|
+
##### ***parameters***
|
|
127
364
|
|
|
128
|
-
|
|
365
|
+
| parameter name | value type | default value | description |
|
|
366
|
+
|:---|---|---:|:---|
|
|
367
|
+
| `object` | `object` | --- | some object |
|
|
368
|
+
| `attr` | `string` | --- | some attribute |
|
|
369
|
+
| `defValue` | `boolean` | `false` | default value |
|
|
370
|
+
| `key` | `string` | --- | some key |
|
|
371
|
+
|
|
372
|
+
##### ***exceptions***
|
|
373
|
+
|
|
374
|
+
The function throws a `TypeError` exception in case:
|
|
375
|
+
|
|
376
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
377
|
+
+ if `object` parameter is not an `Object` instance.
|
|
378
|
+
|
|
379
|
+
<a name="readXObjAttrAsNum"></a>
|
|
380
|
+
#### **readXObjAttrAsNum(object, attr\[, defValue\[, key]])** => `number`
|
|
129
381
|
|
|
130
382
|
This function reads a value of an object attribute and returns it as a `number`.
|
|
131
383
|
|
|
132
|
-
|
|
384
|
+
##### ***parameters***
|
|
133
385
|
|
|
134
|
-
|
|
386
|
+
| parameter name | value type | default value | description |
|
|
387
|
+
|:---|---|---:|:---|
|
|
388
|
+
| `object` | `object` | --- | some object |
|
|
389
|
+
| `attr` | `string` | --- | some attribute |
|
|
390
|
+
| `defValue` | `number` | `0` | default value |
|
|
391
|
+
| `key` | `string` | --- | some key |
|
|
135
392
|
|
|
136
|
-
|
|
393
|
+
##### ***exceptions***
|
|
137
394
|
|
|
138
|
-
The
|
|
395
|
+
The function throws a `TypeError` exception in case:
|
|
139
396
|
|
|
140
|
-
|
|
397
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
398
|
+
+ if `object` parameter is not an `Object` instance.
|
|
399
|
+
|
|
400
|
+
<a name="readXObjAttrAsIndex"></a>
|
|
401
|
+
#### **readXObjAttrAsIndex(object, attr\[, key])** => `number`
|
|
141
402
|
|
|
142
403
|
This function reads a value of an object attribute and try to convert it to a valid index value. If function failed, `-1` is returned.
|
|
143
404
|
|
|
144
405
|
> Note: *for use in this case, index is validated as a non-negative integer number.*
|
|
145
406
|
|
|
146
|
-
|
|
407
|
+
##### ***parameters***
|
|
408
|
+
|
|
409
|
+
| parameter name | value type | default value | description |
|
|
410
|
+
|:---|---|---:|:---|
|
|
411
|
+
| `object` | `object` | --- | some object |
|
|
412
|
+
| `attr` | `string` | --- | some attribute |
|
|
413
|
+
| `key` | `string` | --- | some key |
|
|
414
|
+
|
|
415
|
+
##### ***exceptions***
|
|
416
|
+
|
|
417
|
+
The function throws a `TypeError` exception in case:
|
|
418
|
+
|
|
419
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
420
|
+
+ if `object` parameter is not an `Object` instance.
|
|
421
|
+
|
|
422
|
+
#### **readXObjAttrAsStr(object, attr\[, defValue\[, key]])** => `string`
|
|
423
|
+
|
|
424
|
+
> WARNING: `[since: v0.2.0]` ***this function deprecated.** Use [`readXObjAttr`](#readxobjattrobject-attr-key--string) or [`readXObjAttrEx`](#readxobjattrexobject-attr-opt-key--string) instead.*
|
|
425
|
+
|
|
426
|
+
This function returns a value of an object attribute. The value is of a `string` type.
|
|
427
|
+
|
|
428
|
+
The `defValue` must be of a `string` type, if else the empty string is used.
|
|
429
|
+
|
|
430
|
+
<a name="readXObjAttrEx"></a>
|
|
431
|
+
#### **readXObjAttrEx(object, attr\[, options\[, key]])** => `string`
|
|
432
|
+
|
|
433
|
+
> since: \[v0.2.0]
|
|
434
|
+
|
|
435
|
+
This function returns a value of an object attribute. The value is of a `string` type.
|
|
436
|
+
|
|
437
|
+
##### ***parameters***
|
|
438
|
+
|
|
439
|
+
| parameter name | value type | default value | description |
|
|
440
|
+
|:---|---|---:|:---|
|
|
441
|
+
| `object` | `object` | --- | some object |
|
|
442
|
+
| `attr` | `string` | --- | some attribute |
|
|
443
|
+
| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
|
|
444
|
+
| `key` | `string` | --- | some key |
|
|
445
|
+
|
|
446
|
+
An `options` parameter must be a `string` or an `object`.
|
|
447
|
+
|
|
448
|
+
> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
|
|
449
|
+
|
|
450
|
+
If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
|
|
451
|
+
|
|
452
|
+
If `options` is of a `string` type the function treats it as a value of `options.defValue`.
|
|
453
|
+
|
|
454
|
+
If `options` is not given the settings listed in table below are used by default:
|
|
455
|
+
|
|
456
|
+
| option name | option type | value |
|
|
457
|
+
|:---|---|---:|
|
|
458
|
+
| `useTrim` | `boolean` | `true` |
|
|
459
|
+
| `numberToString` | `boolean` | `true` |
|
|
460
|
+
| `boolToString` | `boolean` | `true` |
|
|
461
|
+
| `defValue` | `string` | `EMPTY_STRING` |
|
|
462
|
+
|
|
463
|
+
##### ***exceptions***
|
|
464
|
+
|
|
465
|
+
The function throws a `TypeError` exception in case:
|
|
466
|
+
|
|
467
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
468
|
+
+ if `object` parameter is not an `Object` instance.
|
|
469
|
+
|
|
470
|
+
### Base functions for write an object attributes value
|
|
471
|
+
|
|
472
|
+
> Note:
|
|
473
|
+
> If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
|
|
474
|
+
|
|
475
|
+
<a name="writeXObjAttr"></a>
|
|
476
|
+
#### **writeXObjAttr(object, attr, value\[, key])** => `boolean`
|
|
147
477
|
|
|
148
478
|
This function sets object attribute to a given value and if succeed returns `true`.
|
|
149
479
|
|
|
150
|
-
|
|
151
|
-
>
|
|
480
|
+
##### ***parameters***
|
|
152
481
|
|
|
153
|
-
|
|
482
|
+
| parameter name | value type | default value | description |
|
|
483
|
+
|:---|---|---:|:---|
|
|
484
|
+
| `object` | `object` | --- | some object |
|
|
485
|
+
| `attr` | `string` | --- | some attribute |
|
|
486
|
+
| `value` | `any` | --- | some value |
|
|
487
|
+
| `key` | `string` | --- | some key |
|
|
488
|
+
|
|
489
|
+
> Note: a value must be of a `string` type or can be converted to a string
|
|
490
|
+
|
|
491
|
+
##### ***exceptions***
|
|
492
|
+
|
|
493
|
+
The function throws a `TypeError` exception in case:
|
|
494
|
+
|
|
495
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
496
|
+
+ if `object` parameter is not an `Object` instance.
|
|
497
|
+
|
|
498
|
+
<a name="writeXObjAttrAsBool"></a>
|
|
499
|
+
#### **writeXObjAttrAsBool(object, attr, value\[, defValue\[, key]])** => `boolean`
|
|
154
500
|
|
|
155
501
|
This function writes a given `boolean` value of an object attribute.
|
|
156
502
|
|
|
157
|
-
|
|
503
|
+
##### ***parameters***
|
|
504
|
+
|
|
505
|
+
| parameter name | value type | default value | description |
|
|
506
|
+
|:---|---|---:|:---|
|
|
507
|
+
| `object` | `object` | --- | some object |
|
|
508
|
+
| `attr` | `string` | --- | some attribute |
|
|
509
|
+
| `value` | `any` | --- | some value |
|
|
510
|
+
| `defValue` | `boolean` | `false` | default value |
|
|
511
|
+
| `key` | `string` | --- | some key |
|
|
512
|
+
|
|
513
|
+
##### ***exceptions***
|
|
514
|
+
|
|
515
|
+
The function throws a `TypeError` exception in case:
|
|
516
|
+
|
|
517
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
518
|
+
+ if `object` parameter is not an `Object` instance.
|
|
158
519
|
|
|
159
|
-
|
|
520
|
+
<a name="writeXObjAttrAsNum"></a>
|
|
521
|
+
#### **writeXObjAttrAsNum(object, attr, value\[, defValue\[, key]])** => `boolean`
|
|
160
522
|
|
|
161
523
|
This function writes a given `number` value of an object attribute.
|
|
162
524
|
|
|
163
|
-
|
|
525
|
+
##### ***parameters***
|
|
164
526
|
|
|
165
|
-
|
|
527
|
+
| parameter name | value type | default value | description |
|
|
528
|
+
|:---|---|---:|:---|
|
|
529
|
+
| `object` | `object` | --- | some object |
|
|
530
|
+
| `attr` | `string` | --- | some attribute |
|
|
531
|
+
| `value` | `any` | --- | some value |
|
|
532
|
+
| `defValue` | `number` | `0` | default value |
|
|
533
|
+
| `key` | `string` | --- | some key |
|
|
534
|
+
|
|
535
|
+
##### ***exceptions***
|
|
536
|
+
|
|
537
|
+
The function throws a `TypeError` exception in case:
|
|
538
|
+
|
|
539
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
540
|
+
+ if `object` parameter is not an `Object` instance.
|
|
541
|
+
|
|
542
|
+
<a name="writeXObjAttrAsIndex"></a>
|
|
543
|
+
#### **writeXObjAttrAsIndex(object, attr, value\[, key])** => `boolean`
|
|
166
544
|
|
|
167
545
|
This function try to interpret a given value as a valid index value and, if succeed, writes it into an object attribute.
|
|
168
546
|
|
|
169
|
-
|
|
547
|
+
##### ***parameters***
|
|
548
|
+
|
|
549
|
+
| parameter name | value type | default value | description |
|
|
550
|
+
|:---|---|---:|:---|
|
|
551
|
+
| `object` | `object` | --- | some object |
|
|
552
|
+
| `attr` | `string` | --- | some attribute |
|
|
553
|
+
| `value` | `any` | --- | some value |
|
|
554
|
+
| `key` | `string` | --- | some key |
|
|
555
|
+
|
|
556
|
+
##### ***exceptions***
|
|
557
|
+
|
|
558
|
+
The function throws a `TypeError` exception in case:
|
|
559
|
+
|
|
560
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
561
|
+
+ if `object` parameter is not an `Object` instance.
|
|
562
|
+
|
|
563
|
+
<a name="writeXObjAttrEx"></a>
|
|
564
|
+
#### **writeXObjAttrEx(object, attr, value\[, options\[, key]])** => `boolean`
|
|
170
565
|
|
|
171
566
|
This function sets object attribute to a given value and if succeed returns `true`.
|
|
172
567
|
|
|
173
|
-
|
|
568
|
+
##### ***parameters***
|
|
174
569
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
570
|
+
| parameter name | value type | default value | description |
|
|
571
|
+
|:---|---|---:|:---|
|
|
572
|
+
| `object` | `object` | --- | some object |
|
|
573
|
+
| `attr` | `string` | --- | some attribute |
|
|
574
|
+
| `value` | `any` | --- | some value |
|
|
575
|
+
| `options` | `string`, `object` | --- | options that defines how a value must be transformed |
|
|
576
|
+
| `key` | `string` | --- | some key |
|
|
577
|
+
|
|
578
|
+
An `options` parameter must be a `string` or an `object`.
|
|
579
|
+
|
|
580
|
+
> \[!] NOTE: `[since v0.2.1]` a use of a `string` type a as values of an `options` are deprecated and will be dropped soon.
|
|
581
|
+
|
|
582
|
+
If `options` is an `object` it contains the settings (see [OPT_valtostr](#typedef+OPT_valtostr)).
|
|
583
|
+
|
|
584
|
+
If `options` is of a `string` type the function treats it as a value of `options.defValue`.
|
|
585
|
+
|
|
586
|
+
If `options` is not given the settings listed in table below are used by default:
|
|
587
|
+
|
|
588
|
+
| option name | option type | value |
|
|
589
|
+
|:---|---|---:|
|
|
590
|
+
| `useTrim` | `boolean` | `true` |
|
|
591
|
+
| `numberToString` | `boolean` | `true` |
|
|
592
|
+
| `boolToString` | `boolean` | `true` |
|
|
593
|
+
| `defValue` | `string` | `EMPTY_STRING` |
|
|
594
|
+
|
|
595
|
+
##### ***exceptions***
|
|
179
596
|
|
|
180
|
-
|
|
597
|
+
The function throws a `TypeError` exception in case:
|
|
598
|
+
|
|
599
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
600
|
+
+ if `object` parameter is not an `Object` instance.
|
|
601
|
+
|
|
602
|
+
### Special functions for read and write an object parameter value
|
|
603
|
+
|
|
604
|
+
<a name="readXObjParamRaw"></a>
|
|
605
|
+
#### **readXObjParamRaw(object\[, key])** => `any`
|
|
181
606
|
|
|
182
607
|
This is a special function that returns a value of an object parameter as "IT IS".
|
|
183
608
|
|
|
184
|
-
|
|
609
|
+
##### ***parameters***
|
|
610
|
+
|
|
611
|
+
| parameter name | value type | default value | description |
|
|
612
|
+
|:---|---|---:|:---|
|
|
613
|
+
| `object` | `object` | --- | some object |
|
|
614
|
+
| `key` | `string` | --- | some key |
|
|
615
|
+
|
|
616
|
+
> NOTE:
|
|
617
|
+
> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
|
|
618
|
+
|
|
619
|
+
##### ***exceptions***
|
|
620
|
+
|
|
621
|
+
The function throws a `TypeError` exception in case:
|
|
622
|
+
|
|
623
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
624
|
+
+ if `object` parameter is not an `Object` instance;
|
|
625
|
+
- code: `ERR_XOBJ_NSTR`
|
|
626
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
627
|
+
|
|
628
|
+
<a name="writeXObjParamRaw"></a>
|
|
629
|
+
#### **writeXObjParamRaw(object, value\[, key])** => `boolean`
|
|
185
630
|
|
|
186
631
|
This is a special function that writes a given value of an object parameter as "IT IS".
|
|
187
632
|
|
|
188
|
-
|
|
633
|
+
##### ***parameters***
|
|
189
634
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
635
|
+
| parameter name | value type | default value | description |
|
|
636
|
+
|:---|---|---:|:---|
|
|
637
|
+
| `object` | `object` | --- | some object |
|
|
638
|
+
| `value` | `any` | --- | some value |
|
|
639
|
+
| `key` | `string` | --- | some key |
|
|
640
|
+
|
|
641
|
+
> NOTE:
|
|
642
|
+
> - If `value` parameter not given, the function failed.
|
|
643
|
+
> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_PARAM_TNAME`.
|
|
644
|
+
|
|
645
|
+
##### ***exceptions***
|
|
646
|
+
|
|
647
|
+
The function throws a `TypeError` exception in case:
|
|
648
|
+
|
|
649
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
650
|
+
+ if `object` parameter is not an `Object` instance;
|
|
651
|
+
- code: `ERR_XOBJ_NSTR`
|
|
652
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
653
|
+
|
|
654
|
+
### Special functions for read or write object attributes value
|
|
194
655
|
|
|
195
|
-
|
|
656
|
+
<a name="readXObjAttrRaw"></a>
|
|
657
|
+
#### **readXObjAttrRaw(object, attr\[, key])** => `any`
|
|
196
658
|
|
|
197
659
|
This is a special function that returns a value of an object attribute as "IT IS".
|
|
198
660
|
|
|
199
|
-
|
|
661
|
+
##### ***parameters***
|
|
662
|
+
|
|
663
|
+
| parameter name | value type | default value | description |
|
|
664
|
+
|:---|---|---:|:---|
|
|
665
|
+
| `object` | `object` | --- | some object |
|
|
666
|
+
| `attr` | `string` | --- | some attribute |
|
|
667
|
+
| `key` | `string` | --- | some key |
|
|
668
|
+
|
|
669
|
+
> NOTE:
|
|
670
|
+
> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
|
|
671
|
+
|
|
672
|
+
##### ***exceptions***
|
|
673
|
+
|
|
674
|
+
The function throws a `TypeError` exception in case:
|
|
675
|
+
|
|
676
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
677
|
+
+ if `object` parameter is not an `Object` instance;
|
|
678
|
+
- code: `ERR_XOBJ_NSTR`
|
|
679
|
+
+ if `attr` parameter given and is not a type of a `string`;
|
|
680
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
681
|
+
|
|
682
|
+
<a name="writeXObjAttrRaw"></a>
|
|
683
|
+
#### **writeXObjAttrRaw(object, attr, value\[, key])** => `boolean`
|
|
200
684
|
|
|
201
685
|
This is a special function that writes a given value of an object attribute as "IT IS".
|
|
202
686
|
|
|
687
|
+
##### ***parameters***
|
|
688
|
+
|
|
689
|
+
| parameter name | value type | default value | description |
|
|
690
|
+
|:---|---|---:|:---|
|
|
691
|
+
| `object` | `object` | --- | some object |
|
|
692
|
+
| `attr` | `string` | --- | some attribute |
|
|
693
|
+
| `value` | `any` | --- | some value |
|
|
694
|
+
| `key` | `string` | --- | some key |
|
|
695
|
+
|
|
696
|
+
> NOTE:
|
|
697
|
+
> - If `value` parameter not given, the function failed.
|
|
698
|
+
> - If a `key` parameter not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
|
|
699
|
+
|
|
700
|
+
##### ***exceptions***
|
|
701
|
+
|
|
702
|
+
The function throws a `TypeError` exception in case:
|
|
703
|
+
|
|
704
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
705
|
+
+ if `object` parameter is not an `Object` instance;
|
|
706
|
+
- code: `ERR_XOBJ_NSTR`
|
|
707
|
+
+ if `attr` parameter given and is not a type of a `string`;
|
|
708
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
709
|
+
|
|
203
710
|
### Other functions for deal with an object attributes
|
|
204
711
|
|
|
205
712
|
> Note:
|
|
206
|
-
> If a `key` parameter given
|
|
207
|
-
>
|
|
208
|
-
> If an `object` parameter given to the function is not a plain object, the function will throw a `TypeError` exception (*error code: `ERR_XOBJ_NOBJ`*).
|
|
713
|
+
> If a `key` parameter given not given, the function will use a default value defined by `XOBJ_DEF_ATTR_TNAME`.
|
|
209
714
|
|
|
210
|
-
|
|
715
|
+
<a name="getXObjAttributes"></a>
|
|
716
|
+
#### **getXObjAttributes(object\[, key])** => `?object`
|
|
211
717
|
|
|
212
718
|
This function returns an object which represents a set of the element attributes for a given object or `null` if failed.
|
|
213
719
|
|
|
214
|
-
|
|
720
|
+
##### ***parameters***
|
|
721
|
+
|
|
722
|
+
| parameter name | value type | default value | description |
|
|
723
|
+
|:---|---|---:|:---|
|
|
724
|
+
| `object` | `object` | --- | some object |
|
|
725
|
+
| `key` | `string` | --- | some key |
|
|
726
|
+
|
|
727
|
+
##### ***exceptions***
|
|
728
|
+
|
|
729
|
+
The function throws a `TypeError` exception in case:
|
|
730
|
+
|
|
731
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
732
|
+
+ if `object` parameter is not an `Object` instance.
|
|
733
|
+
|
|
734
|
+
<a name="checkXObjAttribute"></a>
|
|
735
|
+
#### **checkXObjAttribute(object, attr\[, key])** => `boolean`
|
|
215
736
|
|
|
216
737
|
This function tries to check whether or not an attribute with a name given by `attr` parameter exists for the element given by `object` parameter. If attribute exists `true` is returned.
|
|
217
738
|
|
|
218
|
-
|
|
739
|
+
##### ***parameters***
|
|
740
|
+
|
|
741
|
+
| parameter name | value type | default value | description |
|
|
742
|
+
|:---|---|---:|:---|
|
|
743
|
+
| `object` | `object` | --- | some object |
|
|
744
|
+
| `attr` | `string` | --- | some attribute |
|
|
745
|
+
| `key` | `string` | --- | some key |
|
|
746
|
+
|
|
747
|
+
##### ***exceptions***
|
|
748
|
+
|
|
749
|
+
The function throws a `TypeError` exception in case:
|
|
219
750
|
|
|
220
|
-
|
|
751
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
752
|
+
+ if `object` parameter is not an `Object` instance;
|
|
753
|
+
- code: `ERR_XOBJ_NSTR`
|
|
754
|
+
+ if `attr` parameter given and is not a type of a `string`;
|
|
755
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
756
|
+
|
|
757
|
+
<a name="deleteXObjAttribute"></a>
|
|
758
|
+
#### **deleteXObjAttribute(object, attr\[, key])** => `boolean`
|
|
221
759
|
|
|
222
760
|
This function tries to delete an attribute with a name given by `attr` parameter. If succeed `true` is returned.
|
|
223
761
|
|
|
224
|
-
|
|
762
|
+
##### ***parameters***
|
|
225
763
|
|
|
226
|
-
|
|
764
|
+
| parameter name | value type | default value | description |
|
|
765
|
+
|:---|---|---:|:---|
|
|
766
|
+
| `object` | `object` | --- | some object |
|
|
767
|
+
| `attr` | `string` | --- | some attribute |
|
|
768
|
+
| `key` | `string` | --- | some key |
|
|
227
769
|
|
|
228
|
-
|
|
770
|
+
##### ***exceptions***
|
|
229
771
|
|
|
230
|
-
|
|
772
|
+
The function throws a `TypeError` exception in case:
|
|
231
773
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
774
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
775
|
+
+ if `object` parameter is not an `Object` instance;
|
|
776
|
+
- code: `ERR_XOBJ_NSTR`
|
|
777
|
+
+ if `attr` parameter given and is not a type of a `string`;
|
|
778
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
779
|
+
|
|
780
|
+
<a name="renameXObjElement"></a>
|
|
781
|
+
#### **renameXObjAttribute(object, attr, value\[, key])** => `boolean`
|
|
239
782
|
|
|
240
|
-
|
|
783
|
+
> since: \[v0.2.0]
|
|
784
|
+
|
|
785
|
+
This function tries to rename an attribute with a name given by `attr` parameter to its new name. If succeed `true` is returned.
|
|
786
|
+
|
|
787
|
+
##### ***parameters***
|
|
788
|
+
|
|
789
|
+
| parameter name | value type | default value | description |
|
|
790
|
+
|:---|---|---:|:---|
|
|
791
|
+
| `object` | `object` | --- | some object |
|
|
792
|
+
| `attr` | `string` | --- | some attribute |
|
|
793
|
+
| `value` | `string` | --- | new attribute ID |
|
|
794
|
+
| `key` | `string` | --- | some key |
|
|
795
|
+
|
|
796
|
+
##### ***exceptions***
|
|
797
|
+
|
|
798
|
+
The function throws a `TypeError` exception in case:
|
|
799
|
+
|
|
800
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
801
|
+
+ if `object` parameter is not an `Object` instance;
|
|
802
|
+
- code: `ERR_XOBJ_NSTR`
|
|
803
|
+
+ if `attr` parameter given and is not a type of a `string`;
|
|
804
|
+
+ if `value` parameter given and is not a type of a `string`;
|
|
805
|
+
+ if `key` parameter given and is not a type of a `string`.
|
|
806
|
+
|
|
807
|
+
### Other functions
|
|
808
|
+
|
|
809
|
+
<a name="getXObjElement"></a>
|
|
810
|
+
#### **getXObjElement(object, name)** => `?any`
|
|
241
811
|
|
|
242
812
|
This function returns an element from a given object by its name or `null` if that element not found.
|
|
243
813
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
814
|
+
##### ***parameters***
|
|
815
|
+
|
|
816
|
+
| parameter name | value type | default value | description |
|
|
817
|
+
|:---|---|---:|:---|
|
|
818
|
+
| `object` | `object` | --- | some object |
|
|
819
|
+
| `name` | `string` | --- | some child element ID |
|
|
820
|
+
|
|
821
|
+
##### ***exceptions***
|
|
247
822
|
|
|
248
|
-
|
|
823
|
+
The function throws a `TypeError` exception in case:
|
|
824
|
+
|
|
825
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
826
|
+
+ if `object` parameter is not an `Object` instance;
|
|
827
|
+
- code: `ERR_XOBJ_NSTR`
|
|
828
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
829
|
+
- code: `ERR_XOBJ_INVARG_KEY`
|
|
830
|
+
+ if `name` parameter given and is an empty string.
|
|
831
|
+
|
|
832
|
+
<a name="addXObjElement"></a>
|
|
833
|
+
#### **addXObjElement(object, name)** => `object`
|
|
249
834
|
|
|
250
835
|
This function adds an element given by `name` parameter to a members of the given object and returns an `object` that represents a status of the operation.
|
|
251
836
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
837
|
+
##### ***parameters***
|
|
838
|
+
|
|
839
|
+
| parameter name | value type | default value | description |
|
|
840
|
+
|:---|---|---:|:---|
|
|
841
|
+
| `object` | `object` | --- | some object |
|
|
842
|
+
| `name` | `string` | --- | some child element ID |
|
|
843
|
+
|
|
844
|
+
##### ***result***
|
|
255
845
|
|
|
256
846
|
The status of an operation contains 2 fields:
|
|
257
847
|
|
|
258
848
|
- `isSucceed` - `boolean` value;
|
|
259
849
|
- `item` - an item which was added or a `null`.
|
|
260
850
|
|
|
261
|
-
|
|
851
|
+
> <!> The function will fail if a target element exists and it is not an object or an array or not a `null`.
|
|
852
|
+
|
|
853
|
+
##### ***exceptions***
|
|
854
|
+
|
|
855
|
+
The function throws a `TypeError` exception in case:
|
|
856
|
+
|
|
857
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
858
|
+
+ if `object` parameter is not an `Object` instance;
|
|
859
|
+
- code: `ERR_XOBJ_NSTR`
|
|
860
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
861
|
+
- code: `ERR_XOBJ_INVARG_KEY`
|
|
862
|
+
+ if `name` parameter given and is an empty string.
|
|
863
|
+
|
|
864
|
+
<a name="insertXObjElement"></a>
|
|
865
|
+
#### **insertXObjElement(object, name\[, options])** => `null`\|`object`\|`object[]`
|
|
262
866
|
|
|
263
867
|
This function inserts an empty element named by a `name` parameter into a given object. If succeed the element will be returned or `null` in opposite.
|
|
264
868
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
869
|
+
##### ***parameters***
|
|
870
|
+
|
|
871
|
+
| parameter name | value type | default value | description |
|
|
872
|
+
|:---|---|---:|:---|
|
|
873
|
+
| `object` | `object` | --- | some object |
|
|
874
|
+
| `name` | `string` | --- | some child element ID |
|
|
875
|
+
| `options` | `object` | --- | options |
|
|
876
|
+
|
|
877
|
+
For details of an `options` parameter read the appropriate section in the description of the [`insertXObjElementEx`](#insertXObjElementEx) function.
|
|
878
|
+
|
|
879
|
+
##### ***exceptions***
|
|
880
|
+
|
|
881
|
+
The function throws a `TypeError` exception in case:
|
|
882
|
+
|
|
883
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
884
|
+
+ if `object` parameter is not an `Object` instance.
|
|
885
|
+
|
|
886
|
+
<a name="insertXObjElementEx"></a>
|
|
887
|
+
#### **insertXObjElementEx(object, name\[, options])** => `object`
|
|
888
|
+
|
|
889
|
+
> since: \[v0.2.0]
|
|
890
|
+
|
|
891
|
+
This function inserts an empty element named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
|
|
892
|
+
|
|
893
|
+
##### ***parameters***
|
|
894
|
+
|
|
895
|
+
| parameter name | value type | default value | description |
|
|
896
|
+
|:---|---|---:|:---|
|
|
897
|
+
| `object` | `object` | --- | some object |
|
|
898
|
+
| `name` | `string` | --- | some child element ID |
|
|
899
|
+
| `options` | `object` | --- | options |
|
|
268
900
|
|
|
269
901
|
An `options` parameter contains the following parameters:
|
|
270
902
|
|
|
271
|
-
|option name|value type|default value|description|
|
|
903
|
+
| option name | value type | default value | description |
|
|
272
904
|
|:---|---|---:|:---|
|
|
273
|
-
|
|
274
|
-
|
|
905
|
+
| `force` | `boolean` | `false` | modifies the functions behavior |
|
|
906
|
+
| `ripOldies` | `boolean` | `false` | it prevents a replacement of an element which exists and is an object or an array. Applied only if `force` option is set to `true` |
|
|
907
|
+
| `acceptIfList` | `boolean` | `false` | it defines whether a list elements is treated as a type of an `object` |
|
|
275
908
|
|
|
276
909
|
An `options.force` parameter modifies the functions behavior as follows:
|
|
277
910
|
- when set to `true`, the addressed element will be replaced with an empty element.
|
|
278
|
-
- when set to `false`, if the target element exists and is not
|
|
911
|
+
- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
|
|
912
|
+
|
|
913
|
+
##### ***result***
|
|
914
|
+
|
|
915
|
+
The status of an operation contains 2 fields:
|
|
916
|
+
|
|
917
|
+
- `isSucceed` - `boolean` value;
|
|
918
|
+
- `item` - an item which was inserted or a `null`.
|
|
279
919
|
|
|
280
|
-
|
|
920
|
+
> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
|
|
921
|
+
|
|
922
|
+
##### ***exceptions***
|
|
923
|
+
|
|
924
|
+
The function throws a `TypeError` exception in case:
|
|
925
|
+
|
|
926
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
927
|
+
+ if `object` parameter is not an `Object` instance;
|
|
928
|
+
- code: `ERR_XOBJ_NSTR`
|
|
929
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
930
|
+
- code: `ERR_XOBJ_INVARG_KEY`
|
|
931
|
+
+ if `name` parameter given and is an empty string.
|
|
932
|
+
|
|
933
|
+
<a name="deleteXObjElement"></a>
|
|
934
|
+
#### **deleteXObjElement(object, name)** => `boolean`
|
|
281
935
|
|
|
282
936
|
This function deletes an element addressed by `name` parameter from a given object. If succeed `true` is returned.
|
|
283
937
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
938
|
+
##### ***parameters***
|
|
939
|
+
|
|
940
|
+
| parameter name | value type | default value | description |
|
|
941
|
+
|:---|---|---:|:---|
|
|
942
|
+
| `object` | `object` | --- | some object |
|
|
943
|
+
| `name` | `string` | --- | some child element ID |
|
|
944
|
+
|
|
945
|
+
##### ***exceptions***
|
|
946
|
+
|
|
947
|
+
The function throws a `TypeError` exception in case:
|
|
948
|
+
|
|
949
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
950
|
+
+ if `object` parameter is not an `Object` instance.
|
|
951
|
+
|
|
952
|
+
<a name="deleteXObjElementEx"></a>
|
|
953
|
+
#### **deleteXObjElementEx(object, name)** => `object`
|
|
954
|
+
|
|
955
|
+
This function deletes an element addressed by `name` parameter from a given object and returns an `object` that represents a status of the operation.
|
|
956
|
+
|
|
957
|
+
##### ***parameters***
|
|
958
|
+
|
|
959
|
+
| parameter name | value type | default value | description |
|
|
960
|
+
|:---|---|---:|:---|
|
|
961
|
+
| `object` | `object` | --- | some object |
|
|
962
|
+
| `name` | `string` | --- | some child element ID |
|
|
963
|
+
|
|
964
|
+
##### ***result***
|
|
965
|
+
|
|
966
|
+
The status of an operation contains 2 fields:
|
|
967
|
+
|
|
968
|
+
- `isSucceed` - `boolean` value;
|
|
969
|
+
- `item` - an item which was deleted or a `null`.
|
|
970
|
+
|
|
971
|
+
##### ***exceptions***
|
|
972
|
+
|
|
973
|
+
The function throws a `TypeError` exception in case:
|
|
974
|
+
|
|
975
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
976
|
+
+ if `object` parameter is not an `Object` instance;
|
|
977
|
+
- code: `ERR_XOBJ_NSTR`
|
|
978
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
979
|
+
- code: `ERR_XOBJ_INVARG_KEY`
|
|
980
|
+
+ if `name` parameter given and is an empty string.
|
|
981
|
+
|
|
982
|
+
<a name="renameXObjElement"></a>
|
|
983
|
+
#### **renameXObjElement(object, name, value)** => `boolean`
|
|
984
|
+
|
|
985
|
+
This function renames an element addressed by `name` for the given object. If succeed `true` is returned.
|
|
986
|
+
|
|
987
|
+
##### ***parameters***
|
|
988
|
+
|
|
989
|
+
| parameter name | value type | default value | description |
|
|
990
|
+
|:---|---|---:|:---|
|
|
991
|
+
| `object` | `object` | --- | some object |
|
|
992
|
+
| `name` | `string` | --- | some child element ID |
|
|
993
|
+
| `value` | `string` | --- | new element ID |
|
|
994
|
+
|
|
995
|
+
##### ***exceptions***
|
|
996
|
+
|
|
997
|
+
The function throws a `TypeError` exception in case:
|
|
998
|
+
|
|
999
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
1000
|
+
+ if `object` parameter is not an `Object` instance;
|
|
1001
|
+
- code: `ERR_XOBJ_NSTR`
|
|
1002
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
1003
|
+
+ id `value` parameter given and is not a type of a `string`.
|
|
1004
|
+
|
|
1005
|
+
### Other special functions
|
|
1006
|
+
|
|
1007
|
+
<a name="evalXObjEName"></a>
|
|
1008
|
+
#### **evalXObjEName(value)** => `null`\|`number`\|`string`
|
|
1009
|
+
|
|
1010
|
+
This function evaluates a given value whether it can be accepted as a valid element ID and returns a result.
|
|
1011
|
+
|
|
1012
|
+
##### ***parameters***
|
|
1013
|
+
|
|
1014
|
+
| parameter name | value type | default value | description |
|
|
1015
|
+
|:---|---|---:|:---|
|
|
1016
|
+
| `value` | `any` | --- | some value to evaluate |
|
|
1017
|
+
|
|
1018
|
+
##### ***result***
|
|
1019
|
+
|
|
1020
|
+
The dependencies of a resulted value returned by the function given in the following table:
|
|
1021
|
+
|
|
1022
|
+
| given value | value type of the result |
|
|
1023
|
+
|:---|---|
|
|
1024
|
+
| value is an integer positive number or a string that can be converted to a such number | `number` |
|
|
1025
|
+
| any other string that can\'t be converted to a number | `string` |
|
|
1026
|
+
| any other cases | `null` |
|
|
1027
|
+
|
|
1028
|
+
<a name="insertXObjEList"></a>
|
|
1029
|
+
#### **insertXObjEList(object, name\[, options])** => `null`\|`object[]`
|
|
287
1030
|
|
|
288
|
-
|
|
1031
|
+
This function inserts an elements list named by a `name` parameter into a given object. If succeed the list will be returned or `null` in opposite.
|
|
1032
|
+
|
|
1033
|
+
##### ***parameters***
|
|
1034
|
+
|
|
1035
|
+
| parameter name | value type | default value | description |
|
|
1036
|
+
|:---|---|---:|:---|
|
|
1037
|
+
| `object` | `object` | --- | some object |
|
|
1038
|
+
| `name` | `string` | --- | some child element ID |
|
|
1039
|
+
| `options` | `object` | --- | options |
|
|
1040
|
+
|
|
1041
|
+
For details of an `options` parameter read the appropriate section in the description of the [`insertXObjEListEx`](#insertXObjEListEx) function.
|
|
1042
|
+
|
|
1043
|
+
##### ***exceptions***
|
|
1044
|
+
|
|
1045
|
+
The function throws a `TypeError` exception in case:
|
|
1046
|
+
|
|
1047
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
1048
|
+
+ if `object` parameter is not an `Object` instance.
|
|
1049
|
+
|
|
1050
|
+
<a name="insertXObjEListEx"></a>
|
|
1051
|
+
#### **insertXObjEListEx(object, name\[, options])** => `object`
|
|
1052
|
+
|
|
1053
|
+
> since: \[v0.2.0]
|
|
1054
|
+
|
|
1055
|
+
This function inserts an elements list named by a `name` parameter into a given object and returns an `object` that represents a status of the operation.
|
|
1056
|
+
|
|
1057
|
+
##### ***parameters***
|
|
1058
|
+
|
|
1059
|
+
| parameter name | value type | default value | description |
|
|
1060
|
+
|:---|---|---:|:---|
|
|
1061
|
+
| `object` | `object` | --- | some object |
|
|
1062
|
+
| `name` | `string` | --- | some child element ID |
|
|
1063
|
+
| `options` | `object` | --- | options |
|
|
1064
|
+
|
|
1065
|
+
An `options` parameter contains the following parameters:
|
|
1066
|
+
|
|
1067
|
+
| option name|value type|default value|description|
|
|
1068
|
+
|:---|---|---:|:---|
|
|
1069
|
+
| `force` | `boolean` | `false` | modifies the functions behavior |
|
|
1070
|
+
| `ripOldies` | `boolean` | `false` | it prevents a replacement of an element which exists and has a type of an `array`. Applied only if `force` option is set to `true` |
|
|
1071
|
+
|
|
1072
|
+
An `options.force` parameter modifies the functions behavior as follows:
|
|
1073
|
+
- when set to `true`, the addressed element will be replaced with an empty elements list.
|
|
1074
|
+
- when set to `false`, if the target element type is an `object`, the function will wraps it in the list.
|
|
1075
|
+
- when set to `false`, if the target element exists and is not an object or an array, the function will failed.
|
|
1076
|
+
|
|
1077
|
+
##### ***result***
|
|
1078
|
+
|
|
1079
|
+
The status of an operation contains 2 fields:
|
|
1080
|
+
|
|
1081
|
+
- `isSucceed` - `boolean` value;
|
|
1082
|
+
- `item` - an item which was inserted or a `null`.
|
|
289
1083
|
|
|
290
|
-
|
|
1084
|
+
> <!> If a target element exists and it is not a `null`, the function behavior defined by the given options. When a required conditions not met, the function failed.
|
|
291
1085
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
1086
|
+
##### ***exceptions***
|
|
1087
|
+
|
|
1088
|
+
The function throws a `TypeError` exception in case:
|
|
1089
|
+
|
|
1090
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
1091
|
+
+ if `object` parameter is not an `Object` instance;
|
|
1092
|
+
- code: `ERR_XOBJ_NSTR`
|
|
1093
|
+
+ if `name` parameter given and is not a type of a `string`;
|
|
1094
|
+
- code: `ERR_XOBJ_INVARG_KEY`
|
|
1095
|
+
+ if `name` parameter given and is an empty string.
|
|
295
1096
|
|
|
296
1097
|
### Experimental functions
|
|
297
1098
|
|
|
298
1099
|
> Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
|
|
299
1100
|
|
|
1101
|
+
<a name="genXObjENameDescr"></a>
|
|
300
1102
|
#### **genXObjENameDescr(name)**
|
|
301
1103
|
|
|
302
1104
|
This function creates a object that contains description of the value given by a `name` parameter.
|
|
@@ -317,64 +1119,45 @@ The returned object has following attributes:
|
|
|
317
1119
|
|:---|---|---|
|
|
318
1120
|
|`isERR`|`boolean`|set to `true` if error happend|
|
|
319
1121
|
|`name`|`string`|contains a name of the element|
|
|
320
|
-
|`conditions`|`object
|
|
1122
|
+
|`conditions`|`object`|contains conditions applied to that element|
|
|
321
1123
|
|
|
322
1124
|
The object `conditions` property (*if present*) contains following attributes:
|
|
323
1125
|
|
|
324
1126
|
|attribute|value type|description|
|
|
325
1127
|
|:---|---|---|
|
|
326
1128
|
|`type`|`string`||
|
|
327
|
-
|`name
|
|
328
|
-
|`value
|
|
1129
|
+
|`name`|`string`||
|
|
1130
|
+
|`value`|`any`||
|
|
329
1131
|
|
|
330
|
-
|
|
1132
|
+
<a name="insertXObjElements"></a>
|
|
1133
|
+
#### **insertXObjElements(object, name\[...name_N\[, options]])** => `number`
|
|
331
1134
|
|
|
332
|
-
This function inserts an elements given by the
|
|
1135
|
+
This function inserts an elements given by the list of names and returns a quantity of the inserted elements.
|
|
333
1136
|
|
|
334
|
-
|
|
335
|
-
>
|
|
336
|
-
> The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options).
|
|
1137
|
+
##### ***parameters***
|
|
337
1138
|
|
|
338
|
-
|
|
1139
|
+
The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertXObjElement).
|
|
339
1140
|
|
|
340
|
-
|
|
1141
|
+
##### ***exceptions***
|
|
341
1142
|
|
|
342
|
-
|
|
343
|
-
> - `object` parameter is not a plain object;
|
|
344
|
-
> - `name` parameter is not a non-empty string.
|
|
1143
|
+
The function throws a `TypeError` exception in case:
|
|
345
1144
|
|
|
346
|
-
|
|
1145
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
1146
|
+
+ if `object` parameter is not an `Object` instance.
|
|
347
1147
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|`force`|`boolean`|`false`|modifies the functions behavior|
|
|
351
|
-
|`ripOldies`|`boolean`|`false`|it prevents a replacement of an element which exists and has a type of an `array`. Applied only if `force` option is set to `true`|
|
|
1148
|
+
<a name="insertXObjEChain"></a>
|
|
1149
|
+
#### **insertXObjEChain(object, name\[, ...name_N\[, options])**
|
|
352
1150
|
|
|
353
|
-
|
|
354
|
-
- when set to `true`, the addressed element will be replaced with an empty elements list.
|
|
355
|
-
- when set to `false`, if the target element type is an `object`, the function will wraps it in the list.
|
|
356
|
-
- when set to `false`, if the target element exists and is not a type of an `array` or an `object`, the function will failed.
|
|
357
|
-
|
|
358
|
-
#### **insertXObjEChain(object, names_list\[, options])**
|
|
359
|
-
|
|
360
|
-
This function inserts a chain of the elements listed by `names_list`. If succeed the last inserted element will be returned or `null` if failed.
|
|
1151
|
+
This function inserts a chain of the elements listed as a function arguments. If succeed the last inserted element will be returned or `null` if failed.
|
|
361
1152
|
|
|
362
|
-
>
|
|
363
|
-
>
|
|
364
|
-
> The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options).
|
|
1153
|
+
> The `options` parameter if given must be an object. For details see [`insertXObjElement`](#insertxobjelementobject-name-options--objectarray).
|
|
365
1154
|
|
|
366
|
-
|
|
1155
|
+
##### ***exceptions***
|
|
367
1156
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
> the function will throw a `TypeError` if:
|
|
371
|
-
> - `object` parameter is not a plain object (*error code: `ERR_XOBJ_NOBJ`*);
|
|
372
|
-
> - `name` parameter is not a non-empty string.
|
|
1157
|
+
The function throws a `TypeError` exception in case:
|
|
373
1158
|
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
- `isSucceed` - `boolean` value;
|
|
377
|
-
- `item` - an item which was deleted (*only for objects*) or a `null`.
|
|
1159
|
+
- code: `ERR_XOBJ_NPOBJ`
|
|
1160
|
+
+ if `object` parameter is not an `Object` instance.
|
|
378
1161
|
|
|
379
1162
|
### Base class
|
|
380
1163
|
|