CFile:Read


The Read method reads data from a CFile object in which the file was opened in binary mode ("rb"). This method can read 1 value or a table of values of a specified pixel type. The number of values to read is given by nCount. If nCount is not specified, then 1 value is read. However, reading a character string is a special case, as described below. Also see the ReadBswap method for reading data using a reversed byte order

Syntax

nValue = CFile:Read( sPixelType )

sString = CFile:Read( "str", nCount* )

nTable = CFile:Read( sPixelType, nCount )

 

bullet.gif    The sPixelType parameter specifies the kind of data to read, such as "short", "long", or "double". One value will be returned as a number or string, depending on the pixel type (see Remarks below).

bullet.gif    If sPixelType is "str", then nCount is an optional argument that specifies the number of characters to return. If not specified, the string will read up to the first null character that terminates the string.

bullet.gif    If nCount is specified and sPixelType is not "str", as in the last form, then nCount values are returned in a 1-dimensional array.

Remarks

See Pixel Types for a description of the options for the sPixelType parameter. The pixel type determines whether a value is returned as a number or a string:

bullet.gif    Pixel types that return a number or table of numbers are:

"byte", "short", "ushort", "long", "float", and "double".

bullet.gif    Pixel types that return a string or a table or strings:

"rgb", "urgb", "lrgb", "frgb", and "drgb", and "str".

Reading strings

Reading a "str" value is a special case in which multiple values (characters) are not returned as a 1-dimensional array. In addition, a string may be self-terminated by a null character or you can specify the number of characters to read. If you do not specify the nCount value, then Mira reads the string until the first null-character is read, which indicates the end of the string. If nCount is specified, then nCount characters will be returned unless a null-character is encountered first. If you want to read just one character, use Read("str",1). Do not use Read("byte") to read 1 character, since that returns a numeric value rather than a character.

Example

The following script shows how to read values from the beginning of a raw 2-dimensional data file. The number of columns and rows are stored as 32-bit integer values at the beginning of the file, followed by the data as 32-bit float values. The values inside the if-end bock are defined as "local" because they are use only inside the block. Assume that the file named sFileName exists:

F = FileOpen( sFileName, "rb" )

-- open the file and create a CFile object

if F ~= nil then

-- file was opened successfully

  local nCols = F:Read("long")

-- read a 32-bit integer value

  local nRows = F:Read("long")

-- read a 32-bit integer value

  local t = F:Read("float", nCols*nRows)

-- read (nCols*nRows) values into a table

end

 

Related Topics

CFile Class, ReadBswap, Write


Mira Pro x64 Script User's Guide, Copyright Ⓒ 2024 Mirametrics, Inc. All Rights Reserved.