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.
This commit is contained in:
Rémi Verschelde 2020-06-09 13:05:58 +02:00
parent 201d5a7fc5
commit cd25d184a5
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">