====== fread ======

===== Description =====

Read an object from a file.

===== Function prototype =====

<code>
bool fread <voidptr:hFile> <varref:Data>
</code>


===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //hFile//  |  voidptr  | A handle to a file created by [[plugins:general:zeoscript:reference:functions:fopen]] or [[plugins:general:zeoscript:reference:functions:fopen_s]]. |
|  //Data//  |  varref  | A reference to an initialised variable, the value of which is to be read from the file. The type of the variable determines the number of bytes to be read. |

===== Return value =====

True if success, false otherwise.


===== Example =====

<code>
//
// Ask user for filename
//

string FileName
set FileName <zs:file.OpenDlg "txt" NULL "Text files (*.txt)|*.txt|All files (*.*)|*.*|">
if <zs:iseq 0 <zs:strlen FileName>>
  return 0
endif

//
// Open file
//

voidptr fp
assert <zs:fopen_s fp FileName "r"> "Cannot open file!"

//
// Prepare some variables
//

char c
string s
bool FileDone
set FileDone false

//
// Read file character-by-character using 'fread', and add to string
//

do
  if <zs:fread fp c>
    set s <zs:strcat s c>
  else
    set FileDone true
  endif
while <zs:not FileDone>

//
// Write file contents (in string) to event log
//

echo s

//
// Report file length using ftell
//

echo <zs:strcat <zs:strcat "File length was " <zs:ftell fp>> " bytes">

//
// Close file
//

fclose fp
</code>

... the output of which is written to the event log by [[plugins:general:zeoscript:reference:functions:echo]] as:

<file>
This is the contents of an example text file.

File length was 45 bytes
</file>

===== Comments =====

None.


===== See also =====

  * [[plugins:general:zeoscript:reference:functions:fopen]]
  * [[plugins:general:zeoscript:reference:functions:fopen_s]]
  * [[plugins:general:zeoscript:reference:functions:fclose]]
  * [[plugins:general:zeoscript:reference:functions:fwrite]]
  * [[plugins:general:zeoscript:reference:functions:fgetc]]
  * [[plugins:general:zeoscript:reference:functions:fputc]]
  * [[plugins:general:zeoscript:reference:functions:fseek]]
  * [[plugins:general:zeoscript:reference:functions:ftell]]
  * [[plugins:general:zeoscript:reference:functions:rewind]]