Arguments

fileID

file identifier (single integer) returned by mopen when opening the file. By default, the last opened file is considered.

The file must be priorly opened in read binary mode with fileID = mopen(filename,'rb').

nNumb

Single integer > 0: number of numbers to be parsed and returned. Each number is encoded over one or several bytes, according to the used binFormat.

To read all numbers remaining in the file, use a value nNumb big enough.

binFormat

a text word made of one, 2 or 3 character codes: the binary format used to parse numbers in the binary file. Available binary codes are the following:

c	: individual bytes parsed as int8 integers
uc	: individual bytes parsed as uint8 unsigned integers >0
s	: 2-byte blocks parsed as int16 integers
us	: 2-byte blocks parsed as uint16 unsigned integers >0
i	: 4-byte blocks parsed as int32 integers (default mode).
ui	: 4-byte blocks parsed as uint32 unsigned integers >0
l	: 8-byte blocks parsed as int64 integers
ul	: 8-byte blocks parsed as uint64 unsigned integers >0
	Only with mget() :
f	: 4-byte blocks parsed as "single precision" decimal numbers (so-called "floats" in oldies)
d	: 8-byte blocks parsed as decimal numbers

The default order of bytes in a block can be set using a mopen option when opening the file. This order may be forced afterwards using an optional mget or mgeti flag to be appended to binFormat:

..l :	little endian (first byte in the block = low power byte)
..b :	big endian (first byte in the block = high power byte)

D

Row of nNumb Decimal numbers (or available ones if the End Of File has been reached).

I

Row of nNumb encoded Integers (or available ones if the End Of File has been reached). The inttype of returned integers depends on the used binFormat.

Description

mget and mgeti start reading bytes in the specified file from the current position of the inner file pointer. After reading a block of N bytes (N==1,2,4,8 according to the chosen binFormat),

• the file pointer is increased by N bytes and set to the beginning of next block.
• the read block is ordered according to the default or chosen swapping endian mode. The parsed block is then stored to be returned.

When mgeti() is used, parsed numbers are converted into the inttype corresponding to the chosen binFormat and then returned.

When mget() is used, binary numbers are parsed according to binFormat but are finally converted into 8-byte decimal numbers and then returned.

If int64 or uint64 integers > 253 were parsed thanks to the "ul*" or "l*" format, their final conversion into decimal numbers truncates their mantissa to their 53 highest bits.

Examples

binfile = TMPDIR+"/mgetest.bin";
idF = mopen(binfile, "w+b");
mput(int8(0:16),"uc");

 mseek(0);
 mgeti(1,"uc")  // 0 expected
 mgeti(2,"uc")  // 1, 2 expected
[mgeti(1,"us"),  uint16(3 + 4*256)]
 mseek(3);      // back to the previous position on "3"
[mgeti(1,"usb"), uint16(4 + 3*256)] // swapped bytes (big endian)
 mseek(0);
[mgeti(1,"ui") , uint32(0 + 256*(1 + 256*(2 + 256*3)))]
 mseek(0);
[mgeti(1,"uib"), uint32(3 + 256*(2 + 256*(1 + 256*0)))]
mclose(idF);

// uint64 and int64 integers with a relative accuracy of 1/2^64 = %eps/2^12
// better than decimals one are well handled:
    // Generating n 64-bit long integers with bits #0-#63 set randomly:
n = 5;
b = grand(64,n,"uin",0,1);
p = uint64(2).^ndgrid(0:63,1:n);
x0 = sum(b.*p, "r");

    // We write them in a file, and then re-read them with mgeti():
for usign = ["u" ""]
    for endian = ["l" "b"]
        binfile = TMPDIR+"/mgetiTestInt64.dat";
        idF = mopen(binfile, "w+b");
        x = x0;
        if usign==""
            x = int64(x);
        end
        mput(x,usign+"l"+endian)   // "l" is mandatory to manage all the 64 bits

        // Now, read them in the same mode:
        mseek(0);
        xr = mgeti(n, usign+"l"+endian);
        mclose(idF);

        // Display:
        wrParse = usign + "l" + endian;
        printf("    Write as  ""%s""       Read as ""%s""\n", wrParse, wrParse);
        [x' xr']
    end
end

See also

• mopen — opens files in Scilab
• mclose — closes opened files
• mput — writes byte or word in a given binary format
• mseek — sets current position in a binary file
• mtell — Returns the offset of the current byte relative to the beginning of a file
• meof — checks if end of file has been reached
• inttype — type des entiers utilisés dans les types entiers de données.

History