Запись и чтение переменных (текстовые файлы)

Для текстовых файлов имеется свой набор функций атомарного (поэлементного) сохранения и чтения данных. Он несколько отличается от набора для бинарных файлов из предыдущего раздела. Также следует отметить отсутствие функций-аналогов для записи/чтения структуры или массива структур в текстовый файл. Если вы попытаетесь использовать какие-либо из этих функций с текстовым файлом, они не произведут никакого эффекта, но взведут внутренний код ошибки 5011 (FILE_NOTBIN).

Как мы уже знаем, у текстовых файлов в MQL5 существует две ипостаси: простой текст, и текст в формате CSV. Соответствующий режим — FILE_TXT или FILE_CSV — задается при открытии файла и не может быть изменен без закрытия и повторного получения дескриптора. Разница между ними проявляется только при чтении файлов. Запись обоих режимов производится одинаково.

В режиме TXT каждый вызов функции чтения (любой функции из тех, что мы рассмотрим в этом разделе) находит в файле следующий перевод строки (символ '\n' или пару '\r\n') и обрабатывает все данные вплоть до него. Суть обработки заключается в преобразовании текста из файла в значение конкретного типа, соответствующего вызванной функции. В простейшем случае, если вызвана функция FileReadString, обработка не производится (строка возвращается "как есть").

В режиме CSV при каждом вызове функции чтения текст в файле логически разбивается не только переводами строк, но и дополнительным разделителем, указанным при открытии файла. В остальном обработка фрагмента от текущей позиции файла до ближайшего разделителя происходит аналогично.

Иными словами, чтение текста и перевод внутренней позиции внутри файла производится фрагментами от разделителя к разделителю, где под "разделителем" понимается не только символ delimiter в списке параметров FileOpen, но и перевод строки ('\n', '\r\n'), а также начало и конец файла.

На запись текста в файлы FILE_TXT и FILE_CSV дополнительный разделитель влияет одинаково, но только при использовании функции FileWrite: она этот символ автоматически вставляет между записываемыми элементами. Функция FileWriteString разделитель не учитывает.

Приведем формальное описание функций, а затем рассмотрим пример FileTxtCsv.mq5.

uint FileWrite(int handle, ...)

Функция относится к категории функций, которые принимают переменное количество параметров. Такие параметры обозначаются в прототипе функции многоточием. Поддерживаются только встроенные типы данных. Для записи структур или объектов классов необходимо разыменовывать их элементы и передавать по отдельности.

Функция записывает в текстовый файл с дескриптором handle все аргументы, переданные после первого. Аргументы разделяются запятыми, как в обычном списке аргументов. Количество выводимых в файл аргументов не может превышать 63.

При выводе числовые данные преобразуются в текстовый формат по правилам стандартного приведения к (string). Значения типа double выводятся с точностью до 16 значащих цифр: либо в традиционном, либо в научном формате с показателем степени (выбирается более компактный вариант). Данные типа float выводятся с точностью до 7 значащих цифр. Для вывода вещественных чисел с другой точностью или в явно указанном формате необходимо использовать функцию DoubleToString (см. раздел Числа в строки и обратно).

Значения типа datetime выводятся в формате "YYYY.MM.DD hh:mm:ss" (см. раздел Дата и время).

Стандартный цвет (из списка web-цветов) выводится в виде названия, нестандартный — как тройка значений компонентов RGB (см. раздел Цвет), разделенных запятыми (внимание: запятая — наиболее частый символ-разделитель в CSV).

Для перечислений выводится целое число, обозначающее элемент, а не его идентификатор (название). Например, при записи FRIDAY (из ENUM_DAY_OF_WEEK, см. раздел Перечисления) получим в файле число 5.

Значения типа bool выводятся в виде строк "true" или "false".

Если при открытии файла был указан символ-разделитель, отличный от 0, он будет вставляться между двумя соседними строками, получившимися после конвертации соответствующих аргументов.

После записи всех аргументов в файл добавляется признак конца строки '\r\n'.

Функция возвращает количество записанных байтов или 0 в случае ошибки.

uint FileWriteString(int handle, const string text, int length = -1)

Функция записывает в текстовый файл с дескриптором handle строковый параметр text. Параметр length применим только для бинарных файлов и в данном контексте игнорируется (строка записывается полностью).

Функция FileWriteString может работать и с бинарными файлами. Такое её применение описано в предыдущем разделе.

Любые разделители (между элементами в строке) и переводы строк программист должен вставить/добавить самостоятельно, если они требуются.

Функция возвращает количество записанных байтов (в режиме FILE_UNICODE это будет в 2 раза больше длины строки в символах) или 0 в случае ошибки.

string FileReadString(int handle, int length = -1)

Функция читает из файла с дескриптором handle строку вплоть до следующего разделителя (символа-разделителя в файле CSV, символа перевода строки в любом файле или до конца файла). Параметр length применим только для бинарных файлов и в данном контексте игнорируется.

Полученную строку можно преобразовать в значение требуемого типа по стандартным правилам приведения или с помощью функций конвертации. Альтернативно можно использовать специализированные функции чтения: FileReadBool, FileReadDatetime, FileReadNumber, описанные далее.

В случае ошибки будет возвращена пустая строка. Код ошибки можно узнать через переменную _LastError или функцию GetLastError. В частности, по достижении конца файла код ошибки будет равен 5027 (FILE_ENDOFFILE).

bool FileReadBool(int handle)

Функция читает из CSV-файла фрагмент до следующего разделителя или до конца строки и преобразует его в значение типа bool. Если фрагмент содержит текст "true" (в любом регистре, в том числе смешанном, например, "True") или ненулевое число, получим true. В остальных случаях получим false.

Слово "true" должно занимать весь прочитанный элемент. Даже если строка начинается на "true", но имеет продолжение (например "True Volume"), получим false.

datetime FileReadDatetime(int handle)

Функция читает из CSV-файла строку одного из форматов: "YYYY.MM.DD hh:mm:ss", "YYYY.MM.DD" или "hh:mm:ss" и преобразует ее в значение типа datetime. Если фрагмент не содержит корректного текстового представления даты и/или времени, функция вернет нулевое или "странное" время, в зависимости от того, какие символы её удастся интерпретировать как фрагменты даты и времени. Для пустых или нечисловых строк получим текущую дату с нулевым временем.

Более гибкого чтения даты и времени (с большим числом поддерживаемых форматов) можно добиться, скомбинировав две функции: StringToTime(FileReadString(handle)). Про StringToTime см. раздел Дата и время.

double FileReadNumber(int handle)

Функция читает из CSV-файла фрагмент до следующего разделителя или до конца строки и преобразует его в значение типа double по стандартным правилами приведения типов.

Обратите внимание, что тип double обладает свойством потери точности при достаточно больших значениях, что может сказаться на чтении больших чисел типов long/ulong (значение, после которого начинаются искажения целых внутри double, равно 9007199254740992: пример такого явления приведен в разделе Объединения).

Функции, рассмотренные в предыдущем разделе — FileReadDouble, FileReadFloat, FileReadInteger, FileReadLong, FileReadStruct — нельзя использовать с текстовыми файлами.

Для демонстрации работы с текстовыми файлами подготовлен скрипт FileTxtCsv.mq5. В прошлый раз мы выгружали котировки в двоичный файл. Теперь сделаем это в форматах TXT и CSV.

В принципе, MetaTrader 5 позволяет экспортировать и импортировать котировки в CSV-формате из диалога "Символы". Но в образовательных целях мы воспроизведем данный процесс. Кроме того, программная реализация позволяет отойти от точного формата, генерируемого по умолчанию. Фрагмент истории XAUUSD H1, экспортированный стандартным способом, приведен ниже.

Здесь нас, в частности, может не устраивать используемый по умолчанию символ-разделитель (табуляция, обозначен как '»'), порядок колонок или то, что дата и время разделены на два поля.

В своем скрипте выберем запятую в качестве разделителя, а колонки будем генерировать в порядке полей структуры MqlRates. Выгрузку и последующее проверочное чтение произведем в режимах FILE_TXT и FILE_CSV.

Котировки запросим в начале функции OnStart привычным способом:

Названия колонок укажем в массиве по отдельности, а также "склеим" их вместе с помощью вспомогательной функции StringCombine. Раздельные названия требуются, поскольку мы объединяем их в общий заголовок, используя выбираемый символ-разделитель (альтернативное решение могло бы строиться на StringReplace). С исходным кодом StringCombine предлагается ознакомиться самостоятельно: она делает обратную операцию по отношению к встроенной StringSplit.

Последняя колонка должна была бы называться "Volume", но мы на её примере проверим работу функции FileReadBool. Вы можете считать, что текущее название подразумевает "True Volume" (но такая строка не интерпретировалась бы как true).

Далее открываем два файла в режимах FILE_TXT и FILE_CSV, и записываем в них подготовленный заголовок.

Поскольку функция FileWriteString не добавляет автоматически перевод строки, мы предварительно приплюсовали "\r\n" к переменной caption.

Запись полей структур из массива rates делается одинаково — вызовом в цикле FileWrite для каждого из двух файлов. Напомним, что функция FileWrite автоматически вставляет символ-разделитель между аргументами и добавляет "\r\n" в конце строки. Разумеется, можно было самостоятельно преобразовывать все выводимые значения в строки и отправлять в файл с помощью FileWriteString, но тогда мы сами должны были бы заботиться о разделителях и переводах строк. В некоторых случаях они бывают не нужны: например, если производится запись в формате JSON в компактном виде (фактически, в одну гигантскую строку).

Таким образом, на стадии записи оба файла управлялись одинаково и получились одинаковыми. Вот пример их содержимого для XAUUSD,H1 (ваши результаты могут быть другими):

Различия в работе с этими файлами начнут проявляться на стадии чтения.

Откроем текстовый файл для чтения и "просканируем" его функцией FileReadString в цикле, пока она не вернет пустую строку (т.е. до конца файла).

В журнал будет выведено примерно следующее:

Каждый вызов FileReadString читает в режиме FILE_TXT всю строку целиком (вплоть до '\r\n'). Чтобы разделить её на элементы, следовало бы позаботиться о дополнительной обработке. Или выбрать режим FILE_CSV.

Сделаем то же самое для CSV-файла.

На этот раз записей в журнале появится гораздо больше:

Все дело в том, что функция FileReadString в режиме FILE_CSV учитывает символ-разделитель и дробит строки на элементы. Каждый вызов FileReadString возвращает отдельное значение (ячейку) из таблицы CSV. Очевидно, что полученные строки нужно впоследствии преобразовать к соответствующим типам.

Эту задачу можно в обобщенном виде решить с помощью специализированных функций FileReadDatetime, FileReadNumber, FileReadBool. Однако разработчик в любом случае должен сам отслеживать номер текущей читаемой колонки и определять её прикладной смысл. Пример такого алгоритма приведен на третьем шаге теста. Он использует тот же CSV-файл (для простоты мы его закрываем в конце каждого шага и открываем в начале следующего).

Чтобы упростить присвоение очередного поля в структуре MqlRates по номеру колонки, была создана структура-наследник MqlRates, содержащая один шаблонный метод set:

В функции OnStart мы описали массив из одной такой структуры, куда будем складывать поступающие значения. Массив потребовался, чтобы упростить вывод в журнал с помощью ArrayPrint (для печати структуры самой по себе — готовой функции в MQL5 нет).

Переменная count для подсчета записей потребовалась не только для статистики, но и как средство пропустить первую строку, которая содержит заголовки, а не данные. Номер текущей колонки отслеживается в переменной column. Её максимальное значение не должно превышать количества колонок maxColumn.

Теперь нам осталось лишь открыть файл и считывать из него элементы в цикле с помощью разных функций, пока не случится ошибка, в особенности такая ожидаемая ошибка, как 5027 (FILE_ENDOFFILE), то есть достижение конца файла.

Когда номер колонки равен 0, мы применяем функцию FileReadDatetime. Для остальных колонок используется FileReadNumber. Исключение составляет случай первой строки с заголовками: для него мы вызываем функцию FileReadBool, чтобы продемонстрировать, как она отреагирует на заголовок "True", который был специально сделан у последней колонки.

Вот что выводится в журнал:

Легко заметить, что из всех заголовков только последний преобразован в значение true, а предыдущие — false.

Содержимое прочитанных структур совпадает с исходными данными.