Delete (Json function): Difference between revisions

From m204wiki
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 page is [[under construction]].
==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 may be <var>Null</var></td></tr>
<td>Json object, which must be either an array or obvject.</td></tr>
<tr><th>nonObject</th>
<tr><th>index</th>
<td>NonObject</td></tr>
<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

%numberThe 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"}

See also