mget проверяет числа в двоичом файле и возвращает их в виде десятичных чисел

## Синтаксис

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

mgeti проверяет числа в двоичом файле и возвращает их в виде кодированных целых чисел

## Синтаксис

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

## Аргументы

fileID

  идентификатор файла (целое число типа single), возвращаемое функцией `mopen` при открытии файла. По умолчанию используется последний открытый файл.

  Файл должен быть открыт в режиме чтения двоичных данных с помощью инструкции `fileID = mopen(filename,'rb')`.
nNumb

  Целое положительное число типа single: количество чисел, которые следует проверить и вернуть. Каждое число закодировано одним или несколькими байтами, в соответствии с используемым форматом `binFormat`.

  Чтобы прочитать все числа, оставшиеся в файле, используйте достаточно большое значение `nNumb`.
binFormat

  текстовое значение составленное из одного, двух или трёх символов-кодов: двоичный формат, используемый для проверки чисел в двоичном файле. Доступны следующие двоичные коды:

  c | : индивидуальные байты проверяются как целые числа типа `int8`;
  uc | : индивидуальные байты проверяются как целые беззнаковые положительные числа типа `uint8`;
  s | : двухбайтные блоки проверяются как целые числа типа `int16`;
  us | : двухбайтные блоки проверяются как целые беззнаковые положительные числа типа `uint16`;
  i | : четырёхбайтные блоки проверяются как целые числа типа `int32` (режим по умолчанию).
  ui | : четырёхбайтные блоки проверяются как целые беззнаковые положительные числа типа `uint32`;
  l | : восьмибайтные блоки проверяются как целые числа типа `int64`;
  ul | : восьмибайтные блоки проверяются как целые беззнаковые положительные числа типа `uint64`;
  | Только с `mget()` :
  f | : четырёхбайтные блоки проверяются как десятичные числа "одинарной точности" (так называемые "числа с плавающей запятой", "floats")
  d | : восьмибайтные блоки проверяются как десятичные ("decimal") числа.

  По умолчанию порядок байтов в блоке может быть установлен с помощью опции функции `mopen` при открытии файла. Этот порядок затем может принудительно быть использован с помощью настроечного флага функции `mget` или `mgeti`, который добавляется к `binFormat`:

  ..l : | прямой порядок байтов ( little endian (младший байт идёт в начале блока);
  ..b : | обратный порядок байтов ( big endian (старший байт идёт в начале блока).

D

  Ряд из `nNumb` десятичных чисел (или имеющихся чисел, если достигнут конец файла).

I

  Ряд из `nNumb` закодированных целых чисел (или имеющихся чисел, если достигнут конец файла). Функция `inttype` возвращённых целых чисел зависит от используемого формата `binFormat`.

## Описание

Функции `mget` и `mgeti` начинают чтение байтов в указанном файле с текущей позиции внутреннего файлового указателя. После чтения блока из `N` байтов (`N==1,2,4,8` в соответствии с выбранным форматом `binFormat`),

- файловый указатель увеличивается на `N` байтов и устанавливается в начало следующего блока;
- блоки чтения идут в порядке, соответствующем выбранному или установленному по умолчанию режиму порядка байтов. Проверяемый блок затем сохраняется для возврата.

Эти действия повторяются `nNumb` раз до тех пор, пока не будет достигнут конец файла: в этом случае проверка файла прекращается, неполный блок остаётся (если он есть), взводится статус `EOF` и уже проверенные числа возвращаются.

Когда используется функция `mgeti()`, проверяемые числа преобразуются в тип целого числа `inttype` в соответствии с выбранным форматом `binFormat`, а затем возвращаются.

Когда используется функция `mget()`, двоичные числа проверяются в соответствии с форматом `binFormat`, то в конце преобразуюся в восьмибайтные десятичные числа и затем возвращаются.

Если, благодаря формату `"ul*"` или `"l*"`, проверялись целые числа `int64` или `uint64`, то их конечное преобразование в десятичные числа усекает их мантиссу до 53 старших битов.

## Примеры

    binfile = TMPDIR+"/mgetest.bin";
    idF = mopen(binfile, "w+b");
    mput(int8(0:16),"uc");
    mseek(0);
    mgeti(1,"uc")  // ожидается 0
    mgeti(2,"uc")  // ожидается 1, 2
    [mgeti(1,"us"),  uint16(3 + 4*256)]
    mseek(3);      // возврат к предыдущей позиции на "3"
    [mgeti(1,"usb"), uint16(4 + 3*256)] // байты с изменёным порядком (прямой порядок)
    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 и int64 iс относительной точностью 1/2^64 = %eps/2^12
    // обрабатываются лучше, чем десятичные:
        // Формирование n 64-битных чисел с битами №0-№63, установленными случайным образом:
    n = 5;
    b = grand(64,n,"uin",0,1);
    p = uint64(2).^ndgrid(0:63,1:n);
    x0 = sum(b.*p, "r");
        // Запишем их в файл, а затем вновь прочитем их с помощью 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" принудительно управляет всеми 64 битами
            // Теперь прочитаем их в том же режиме:
            mseek(0);
            xr = mgeti(n, usign+"l"+endian);
            mclose(idF);
            // Отобразим:
            wrParse = usign + "l" + endian;
            printf("    Запись в виде  ""%s""       Чтение в виде ""%s""\n", wrParse, wrParse);
            [x' xr']
        end
    end

## Смотрите также

- mopen
- mclose
- mput
- mseek
- mtell
- meof
- inttype

## История

6.1.1 внедрена mgeti(,"ul*"|"l*") для чтения чисел типа uint64 или int64 больше 252.