Browse Source

[DOCS] parse_json: Objects do not keep key order

Document JSON not guaranteeing key order.
Max Hilbrunner 7 years ago
parent
commit
82b8f1729d
3 changed files with 4 additions and 2 deletions
  1. 1 0
      doc/classes/@GDScript.xml
  2. 1 1
      doc/classes/JSON.xml
  3. 2 1
      doc/classes/JSONParseResult.xml

+ 1 - 0
doc/classes/@GDScript.xml

@@ -608,6 +608,7 @@
 			<description>
 				Parse JSON text to a Variant (use [method typeof] to check if it is what you expect).
 				Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to [float] types.
+				Note that JSON objects do not preserve key order like Godot dictionaries, thus you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:
 				[codeblock]
 				p = parse_json('["a", "b", "c"]')
 				if typeof(p) == TYPE_ARRAY:

+ 1 - 1
doc/classes/JSON.xml

@@ -4,7 +4,7 @@
 		Helper class for parsing JSON data.
 	</brief_description>
 	<description>
-		Helper class for parsing JSON data. For usage example, see [JSONParseResult].
+		Helper class for parsing JSON data. For usage example and other important hints, see [JSONParseResult].
 	</description>
 	<tutorials>
 	</tutorials>

+ 2 - 1
doc/classes/JSONParseResult.xml

@@ -24,7 +24,8 @@
 		</member>
 		<member name="result" type="Variant" setter="set_result" getter="get_result">
 			A [Variant] containing the parsed JSON. Use typeof() to check if it is what you expect. For example, if JSON source starts with curly braces ([code]{}[/code]) a [Dictionary] will be returned, if JSON source starts with braces ([code][][/code]) an [Array] will be returned.
-			[i]Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to float types.[/i]
+			[i]Be aware that the JSON specification does not define integer or float types, but only a number type. Therefore, parsing a JSON text will convert all numerical values to float types.
+			Note that JSON objects do not preserve key order like Godot dictionaries, thus you should not rely on keys being in a certain order if a dictionary is constructed from JSON. In contrast, JSON arrays retain the order of their elements:[/i]
 			[codeblock]
 			p = JSON.parse('["hello", "world", "!"]')
 			if typeof(p) == TYPE_ARRAY: