godotengine
/
godot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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 cd25d184a5)
This commit is contained in:
Rémi Verschelde 2020-06-09 13:05:58 +02:00
parent 7200a0eac5
commit 3202df9b5c
1 changed files with 28 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/classes/File.xml
View File

@ -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">