2
0
Эх сурвалжийг харах

doc: Make File store/get integer methods clearer

Add an example on how to store signed integers on less than 64 bits,
using one bit for the signedness.

(cherry picked from commit cd25d184a5f547d7e7b6332a255908aa00f4ddc7)
Rémi Verschelde 5 жил өмнө
parent
commit
3202df9b5c
1 өөрчлөгдсөн 28 нэмэгдсэн , 7 устгасан
  1. 28 7
      doc/classes/File.xml

+ 28 - 7
doc/classes/File.xml

@@ -54,28 +54,28 @@
 			<return type="int">
 			</return>
 			<description>
-				Returns the next 16 bits from the file as an integer.
+				Returns the next 16 bits from the file as an integer. See [method store_16] for details on what values can be stored and retrieved this way.
 			</description>
 		</method>
 		<method name="get_32" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Returns the next 32 bits from the file as an integer.
+				Returns the next 32 bits from the file as an integer. See [method store_32] for details on what values can be stored and retrieved this way.
 			</description>
 		</method>
 		<method name="get_64" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Returns the next 64 bits from the file as an integer.
+				Returns the next 64 bits from the file as an integer. See [method store_64] for details on what values can be stored and retrieved this way.
 			</description>
 		</method>
 		<method name="get_8" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Returns the next 8 bits from the file as an integer.
+				Returns the next 8 bits from the file as an integer. See [method store_8] for details on what values can be stored and retrieved this way.
 			</description>
 		</method>
 		<method name="get_as_text" qualifiers="const">
@@ -297,7 +297,26 @@
 			</argument>
 			<description>
 				Stores an integer as 16 bits in the file.
-				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^16 - 1][/code].
+				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^16 - 1][/code]. Any other value will overflow and wrap around.
+				To store a signed integer, use [method store_64] or store a signed integer from the interval [code][-2^15, 2^15 - 1][/code] (i.e. keeping one bit for the signedness) and compute its sign manually when reading. For example:
+				[codeblock]
+				const MAX_15B = 1 &lt;&lt; 15
+				const MAX_16B = 1 &lt;&lt; 16
+
+				func unsigned16_to_signed(unsigned):
+				    return (unsigned + MAX_15B) % MAX_16B - MAX_15B
+
+				func _ready():
+				    var f = File.new()
+				    f.open("user://file.dat", File.WRITE_READ)
+				    f.store_16(-42) # This wraps around and stores 65494 (2^16 - 42).
+				    f.store_16(121) # In bounds, will store 121.
+				    f.seek(0) # Go back to start to read the stored value.
+				    var read1 = f.get_16() # 65494
+				    var read2 = f.get_16() # 121
+				    var converted1 = unsigned16_to_signed(read1) # -42
+				    var converted2 = unsigned16_to_signed(read2) # 121
+				[/codeblock]
 			</description>
 		</method>
 		<method name="store_32">
@@ -307,7 +326,8 @@
 			</argument>
 			<description>
 				Stores an integer as 32 bits in the file.
-				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^32 - 1][/code].
+				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 2^32 - 1][/code]. Any other value will overflow and wrap around.
+				To store a signed integer, use [method store_64], or convert it manually (see [method store_16] for an example).
 			</description>
 		</method>
 		<method name="store_64">
@@ -327,7 +347,8 @@
 			</argument>
 			<description>
 				Stores an integer as 8 bits in the file.
-				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 255][/code].
+				[b]Note:[/b] The [code]value[/code] should lie in the interval [code][0, 255][/code]. Any other value will overflow and wrap around.
+				To store a signed integer, use [method store_64], or convert it manually (see [method store_16] for an example).
 			</description>
 		</method>
 		<method name="store_buffer">