From ead2208a845c375a9ceecf0553cfb42111347baa Mon Sep 17 00:00:00 2001 From: Relintai Date: Wed, 27 Jul 2022 18:17:30 +0200 Subject: [PATCH] Ported: Improve documentation related to Pool*Array value passing caveats - Calinou https://github.com/godotengine/godot/commit/b47466bc59b5722e6e713c738c26794567897e7a --- doc/classes/PoolByteArray.xml | 15 ++++++++++++++- doc/classes/PoolColorArray.xml | 17 +++++++++++++++-- doc/classes/PoolIntArray.xml | 15 ++++++++++++++- doc/classes/PoolRealArray.xml | 17 +++++++++++++++-- doc/classes/PoolStringArray.xml | 15 ++++++++++++++- doc/classes/PoolVector2Array.xml | 17 +++++++++++++++-- doc/classes/PoolVector3Array.xml | 15 ++++++++++++++- 7 files changed, 101 insertions(+), 10 deletions(-) diff --git a/doc/classes/PoolByteArray.xml b/doc/classes/PoolByteArray.xml index 90088226e..48b7dd281 100644 --- a/doc/classes/PoolByteArray.xml +++ b/doc/classes/PoolByteArray.xml @@ -5,7 +5,20 @@ 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] diff --git a/doc/classes/PoolColorArray.xml b/doc/classes/PoolColorArray.xml index 07caead25..312560fa1 100644 --- a/doc/classes/PoolColorArray.xml +++ b/doc/classes/PoolColorArray.xml @@ -1,11 +1,24 @@ - A pooled Array of [Color]. + A pooled Array of [Color]s. 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] diff --git a/doc/classes/PoolIntArray.xml b/doc/classes/PoolIntArray.xml index c0a89964d..69fedbd9e 100644 --- a/doc/classes/PoolIntArray.xml +++ b/doc/classes/PoolIntArray.xml @@ -5,7 +5,20 @@ 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. diff --git a/doc/classes/PoolRealArray.xml b/doc/classes/PoolRealArray.xml index e8ca4ca55..bdeaa38c0 100644 --- a/doc/classes/PoolRealArray.xml +++ b/doc/classes/PoolRealArray.xml @@ -1,11 +1,24 @@ - A pooled Array of reals ([float]). + A pooled Array of real numbers ([float]). 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]. diff --git a/doc/classes/PoolStringArray.xml b/doc/classes/PoolStringArray.xml index df5e9e7bb..7e4321671 100644 --- a/doc/classes/PoolStringArray.xml +++ b/doc/classes/PoolStringArray.xml @@ -5,7 +5,20 @@ 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] https://godotengine.org/asset-library/asset/677 diff --git a/doc/classes/PoolVector2Array.xml b/doc/classes/PoolVector2Array.xml index 194e74bdb..58740b4be 100644 --- a/doc/classes/PoolVector2Array.xml +++ b/doc/classes/PoolVector2Array.xml @@ -1,11 +1,24 @@ - A pooled Array of [Vector2]. + A pooled Array of [Vector2]s. 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] https://godotengine.org/asset-library/asset/519 diff --git a/doc/classes/PoolVector3Array.xml b/doc/classes/PoolVector3Array.xml index b93189b61..ac9e664b9 100644 --- a/doc/classes/PoolVector3Array.xml +++ b/doc/classes/PoolVector3Array.xml @@ -5,7 +5,20 @@ 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]