Delete (Json function): Difference between revisions
Jump to navigation
Jump to search
(Automatically generated page update) |
|||
| (6 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Json:Delete subtitle}} | {{Template:Json:Delete subtitle}} | ||
This function deletes an item from a Json array or object. | |||
This | |||
==Syntax== | ==Syntax== | ||
{{Template:Json:Delete syntax}} | {{Template:Json:Delete syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>%number</th><td>number</td></tr> | <tr><th nowrap>%number</th><td>The number of items left on the array or object after the delete.</td></tr> | ||
<tr><th>Json</th> | <tr><th>Json</th> | ||
<td>Json object, which | <td>Json object, which must be either an array or obvject.</td></tr> | ||
<tr><th> | <tr><th>index</th> | ||
<td> | <td>A value to be used as the index of the item to be deleted. If the Json object is an array this value is treated as a number. If the Json object is an object, this value is treated as a (unicode) string.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==Usage notes== | ||
<ul> | |||
<li>If the Json object is neither an array nor an object an InvalidJsonType exception is thrown.</li> | |||
<li>Attempting to delete an item number not in an array results in request cancellation whereas deleting an object name not in the object is simply a no-op.</li> | |||
<li>Deleting an item from the middle of an array or object simply shifts subsequent items down. This means that subsequent items after a delete are accessed by a number one less than before. This only affects objects (as opposed to arrays) when their items are accessed by the [[ItemByNumber (Json function)|ItemByNumber function]] and does not affect the more common case where they are accessed by name.</li> | |||
<li>Deleting an item from an array or object does not delete that object unless the only reference to the object is the one being deleted.</li> | |||
<li>If a non-numeric string is used in a Delete call on an array, that string would be converted to a zero (as non-numeric strings are always converted to numbers in SOUL) and that 0 would be an invalid index so result in request cancellation.</li> | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following example deletes the third item from an array: | |||
<p class="code">b | |||
%json is object json | |||
%json = array(true, "Philly", 654321, array(4, null, "hello")) | |||
printText {~=%json} | |||
%json:delete(3) | |||
printText {~=%json} | |||
end | |||
</p> | |||
It prints: | |||
<p class="code">%json=[true,"Philly",654321,[4,null,"hello"]] | |||
%json=[true,"Philly",[4,null,"hello"]] | |||
</p> | |||
The following example deletes the item named "Shemp" from an object: | |||
<p class="code">b | |||
%json is object json | |||
%json = object | |||
%json("Moe") = "Why I oughta" | |||
%json("Larry") = "Porcupine" | |||
%json("Shemp") = "Mi-mi-mi-mi" | |||
%json("Curly") = "Nyuck-nyuck" | |||
printText {~=%json} | |||
%json:delete("Shemp") | |||
printText {~=%json} | |||
end | |||
</p> | |||
It prints: | |||
<p class="code">%json={"Moe":"Why I oughta","Larry":"Porcupine","Shemp":"Mi-mi-mi-mi","Curly":"Nyuck-nyuck"} | |||
%json={"Moe":"Why I oughta","Larry":"Porcupine","Curly":"Nyuck-nyuck"} | |||
</p> | |||
==See also== | ==See also== | ||
{{Template:Json:Delete footer}} | {{Template:Json:Delete footer}} | ||
Latest revision as of 15:49, 23 August 2016
Delete a JSON object/array item value (Json class)
[Introduced in Model 204 7.6]
This function deletes an item from a Json array or object.
Syntax
[%number =] json:Delete( index) Throws InvalidJsonType
Syntax terms
| %number | The number of items left on the array or object after the delete. |
|---|---|
| Json | Json object, which must be either an array or obvject. |
| index | A value to be used as the index of the item to be deleted. If the Json object is an array this value is treated as a number. If the Json object is an object, this value is treated as a (unicode) string. |
Usage notes
- If the Json object is neither an array nor an object an InvalidJsonType exception is thrown.
- Attempting to delete an item number not in an array results in request cancellation whereas deleting an object name not in the object is simply a no-op.
- Deleting an item from the middle of an array or object simply shifts subsequent items down. This means that subsequent items after a delete are accessed by a number one less than before. This only affects objects (as opposed to arrays) when their items are accessed by the ItemByNumber function and does not affect the more common case where they are accessed by name.
- Deleting an item from an array or object does not delete that object unless the only reference to the object is the one being deleted.
- If a non-numeric string is used in a Delete call on an array, that string would be converted to a zero (as non-numeric strings are always converted to numbers in SOUL) and that 0 would be an invalid index so result in request cancellation.
Examples
The following example deletes the third item from an array:
b %json is object json %json = array(true, "Philly", 654321, array(4, null, "hello")) printText {~=%json} %json:delete(3) printText {~=%json} end
It prints:
%json=[true,"Philly",654321,[4,null,"hello"]] %json=[true,"Philly",[4,null,"hello"]]
The following example deletes the item named "Shemp" from an object:
b %json is object json %json = object %json("Moe") = "Why I oughta" %json("Larry") = "Porcupine" %json("Shemp") = "Mi-mi-mi-mi" %json("Curly") = "Nyuck-nyuck" printText {~=%json} %json:delete("Shemp") printText {~=%json} end
It prints:
%json={"Moe":"Why I oughta","Larry":"Porcupine","Shemp":"Mi-mi-mi-mi","Curly":"Nyuck-nyuck"} %json={"Moe":"Why I oughta","Larry":"Porcupine","Curly":"Nyuck-nyuck"}