Nasal library/io: Difference between revisions

Nasal library/io (view source)

761 bytes added , 23 October 2016

2,732

edits

@@ Line 167: / Line 167: @@
 }}
-=== read(filehandle, buf, len) ===
+=== read() ===
-Attempts to read length bytes from the filehandle into the beginning of the mutable string buf. Failures (including overruns when length > size(buf)) are thrown as runtime errors as per die(). Returns the number of bytes successfully read.
+{{Nasal doc
+|syntax = io.read(file, buf, len);
+|text = Reads a given number of bytes from the given file and places those bytes into the given buffer. The bytes will be read from the position of the position indicator (this can be changed using {{func link|seek}}). Failures are thrown as runtime errors. Returns the number of bytes successfully read.
+|param1 = file
+|param1text = File object as returned by {{func link|open}}.
+|param2 = buf
+|param2text = Buffer to read bytes into. A new buffer can be created using <code>bits.buf(size)</code>. Must not be smaller than '''len'''.
+|param3 = len
+|param3text = Number of bytes to read as an integer. The position indicator will be advanced by this number of bytes. Must not be greater than the size of '''buf'''.
+|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas';
+var file = io.open(path);
+var len = 5;
+var buf = bits.buf(len);
+io.read(file, buf, len);
+print(buf); # prints "# geo"
+io.read(file, buf, len);
+print(buf); # prints " func"
+io.close(file);
+}}
 === read_airport_properties() ===