mget parses numbers in a binary file and returns them as decimals

## Syntax

                D = mget(nNumb)
                D = mget(nNumb, binFormat)
                D = mget(nNumb, binFormat, fileID)

mgeti parses numbers in a binary file and returns them as encoded integers

## Syntax

                I = mgeti(nNumb)
                I = mgeti(nNumb, binFormat)
                I = mgeti(nNumb, binFormat, fileID)

## 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.

This is iterated `nNumb` times, unless the End Of File is reached: In this case, parsing the file is stopped, the uncomplete block is left (if any), the EOF status is set, and already parsed numbers are 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
- mclose
- mput
- mseek
- mtell
- meof
- readb
- read4b
- inttype

## History

6.1.1 mgeti(,"ul*"|"l*") is implemented to read uint64 or int64 integers > 252.