Ported: Improve documentation related to Pool*Array value passing caveats - Calinou

b47466bc59
This commit is contained in:
Relintai 2022-07-27 18:17:30 +02:00
parent 71d20ea670
commit ead2208a84
7 changed files with 101 additions and 10 deletions

View File

@ -5,7 +5,20 @@
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold bytes. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold bytes. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolByteArray] or mutating a [PoolByteArray] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolByteArray()]
array[0].push_back(123)
print(array) # [[]] (empty PoolByteArray within an empty Array)
[/codeblock]
Instead, the entire [PoolByteArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolByteArray()]
var pool_array = array[0]
pool_array.push_back(123)
array[0] = pool_array
print(array) # [[123]] (PoolByteArray with 1 element inside an Array)
[/codeblock]
</description> </description>
<tutorials> <tutorials>
</tutorials> </tutorials>

View File

@ -1,11 +1,24 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<class name="PoolColorArray" version="3.5"> <class name="PoolColorArray" version="3.5">
<brief_description> <brief_description>
A pooled Array of [Color]. A pooled Array of [Color]s.
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold [Color]. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold [Color]. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolColorArray] or mutating a [PoolColorArray] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolColorArray()]
array[0].push_back(Color(0.1, 0.2, 0.3, 0.4))
print(array) # [[]] (empty PoolColorArray within an empty Array)
[/codeblock]
Instead, the entire [PoolColorArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolColorArray()]
var pool_array = array[0]
pool_array.push_back(Color(0.1, 0.2, 0.3, 0.4))
array[0] = pool_array
print(array) # [[(0.1, 0.2, 0.3, 0.4)]] (PoolColorArray with 1 element inside an Array)
[/codeblock]
</description> </description>
<tutorials> <tutorials>
</tutorials> </tutorials>

View File

@ -5,7 +5,20 @@
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold integer values ([int]). Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold integer values ([int]). Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolIntArray] or mutating a [PoolIntArray] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolIntArray()]
array[0].push_back(1234)
print(array) # [[]] (empty PoolIntArray within an empty Array)
[/codeblock]
Instead, the entire [PoolIntArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolIntArray()]
var pool_array = array[0]
pool_array.push_back(1234)
array[0] = pool_array
print(array) # [[1234]] (PoolIntArray with 1 element inside an Array)
[/codeblock]
[b]Note:[/b] This type is limited to signed 32-bit integers, which means it can only take values in the interval [code][-2^31, 2^31 - 1][/code], i.e. [code][-2147483648, 2147483647][/code]. Exceeding those bounds will wrap around. In comparison, [int] uses signed 64-bit integers which can hold much larger values. [b]Note:[/b] This type is limited to signed 32-bit integers, which means it can only take values in the interval [code][-2^31, 2^31 - 1][/code], i.e. [code][-2147483648, 2147483647][/code]. Exceeding those bounds will wrap around. In comparison, [int] uses signed 64-bit integers which can hold much larger values.
</description> </description>
<tutorials> <tutorials>

View File

@ -1,11 +1,24 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<class name="PoolRealArray" version="3.5"> <class name="PoolRealArray" version="3.5">
<brief_description> <brief_description>
A pooled Array of reals ([float]). A pooled Array of real numbers ([float]).
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold floating-point values. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold floating-point values. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolRealArray] or mutating a [PoolRealArray] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolRealArray()]
array[0].push_back(12.34)
print(array) # [[]] (empty PoolRealArray within an empty Array)
[/codeblock]
Instead, the entire [PoolRealArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolRealArray()]
var pool_array = array[0]
pool_array.push_back(12.34)
array[0] = pool_array
print(array) # [[12.34]] (PoolRealArray with 1 element inside an Array)
[/codeblock]
[b]Note:[/b] Unlike primitive [float]s which are 64-bit, numbers stored in [PoolRealArray] are 32-bit floats. This means values stored in [PoolRealArray] have lower precision compared to primitive [float]s. If you need to store 64-bit floats in an array, use a generic Array with [float] elements as these will still be 64-bit. However, using a generic Array to store [float]s will use roughly 6 times more memory compared to a [PoolRealArray]. [b]Note:[/b] Unlike primitive [float]s which are 64-bit, numbers stored in [PoolRealArray] are 32-bit floats. This means values stored in [PoolRealArray] have lower precision compared to primitive [float]s. If you need to store 64-bit floats in an array, use a generic Array with [float] elements as these will still be 64-bit. However, using a generic Array to store [float]s will use roughly 6 times more memory compared to a [PoolRealArray].
</description> </description>
<tutorials> <tutorials>

View File

@ -5,7 +5,20 @@
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold [String]s. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold [String]s. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolStringArray] or mutating a [PoolStringArray] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolStringArray()]
array[0].push_back("hello")
print(array) # [[]] (empty PoolStringArray within an empty Array)
[/codeblock]
Instead, the entire [PoolStringArray] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolStringArray()]
var pool_array = array[0]
pool_array.push_back("hello")
array[0] = pool_array
print(array) # [[hello]] (PoolStringArray with 1 element inside an Array)
[/codeblock]
</description> </description>
<tutorials> <tutorials>
<link title="OS Test Demo">https://godotengine.org/asset-library/asset/677</link> <link title="OS Test Demo">https://godotengine.org/asset-library/asset/677</link>

View File

@ -1,11 +1,24 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<class name="PoolVector2Array" version="3.5"> <class name="PoolVector2Array" version="3.5">
<brief_description> <brief_description>
A pooled Array of [Vector2]. A pooled Array of [Vector2]s.
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold [Vector2]. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold [Vector2]. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolVector2Array] or mutating a [PoolVector2Array] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolVector2Array()]
array[0].push_back(Vector2(12, 34))
print(array) # [[]] (empty PoolVector2Array within an empty Array)
[/codeblock]
Instead, the entire [PoolVector2Array] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolVector2Array()]
var pool_array = array[0]
pool_array.push_back(Vector2(12, 34))
array[0] = pool_array
print(array) # [[(12, 34)]] (PoolVector2Array with 1 element inside an Array)
[/codeblock]
</description> </description>
<tutorials> <tutorials>
<link title="2D Navigation Astar Demo">https://godotengine.org/asset-library/asset/519</link> <link title="2D Navigation Astar Demo">https://godotengine.org/asset-library/asset/519</link>

View File

@ -5,7 +5,20 @@
</brief_description> </brief_description>
<description> <description>
An Array specifically designed to hold [Vector3]. Optimized for memory usage, does not fragment the memory. An Array specifically designed to hold [Vector3]. Optimized for memory usage, does not fragment the memory.
[b]Note:[/b] This type is passed by value and not by reference. [b]Note:[/b] This type is passed by value and not by reference. This means that when [i]mutating[/i] a class property of type [PoolVector3Array] or mutating a [PoolVector3Array] within an [Array] or [Dictionary], changes will be lost:
[codeblock]
var array = [PoolVector3Array()]
array[0].push_back(Vector3(12, 34, 56))
print(array) # [[]] (empty PoolVector3Array within an empty Array)
[/codeblock]
Instead, the entire [PoolVector3Array] property must be [i]reassigned[/i] with [code]=[/code] for it to be changed:
[codeblock]
var array = [PoolVector3Array()]
var pool_array = array[0]
pool_array.push_back(Vector3(12, 34, 56))
array[0] = pool_array
print(array) # [[(12, 34, 56)]] (PoolVector3Array with 1 element inside an Array)
[/codeblock]
</description> </description>
<tutorials> <tutorials>
</tutorials> </tutorials>