Escritura y lectura de variables (archivos de texto)

Los archivos de texto tienen su propio conjunto de funciones para el almacenamiento atómico (elemento por elemento) y para la lectura de datos. Es ligeramente diferente de los archivos binarios establecidos en la sección anterior. También hay que tener en cuenta que no existen funciones analógicas para escribir/leer una estructura o un array de estructuras en un archivo de texto. Si intenta utilizar cualquiera de estas funciones con un archivo de texto, no tendrán ningún efecto, sino que emitirán un código de error interno 5011 (FILE_NOTBIN).

Como ya sabemos, los archivos de texto en MQL5 tienen dos formas: texto plano y texto en formato CSV. El modo correspondiente, FILE_TXT o FILE_CSV, se establece cuando se abre el archivo y no se puede cambiar sin cerrar y volver a adquirir el manejador. La diferencia entre ellos sólo aparece al leer archivos. Ambos modos se graban de la misma manera.

En el modo TXT, cada llamada a la función de lectura (cualquiera de las funciones que veremos en esta sección) encuentra la siguiente nueva línea en el archivo (un carácter '\n' o un par de '\r\n') y procesa todo hasta ella. El objetivo del tratamiento es convertir el texto del archivo en un valor de un tipo específico correspondiente a la función llamada. En el caso más sencillo, si se llama a la función FileReadString no se realiza ningún procesamiento (la cadena se devuelve «tal cual»).

En el modo CSV, cada vez que se llama a la función de lectura, el texto del archivo se divide de manera lógica, no sólo por nuevas líneas, sino también por un delimitador adicional especificado al abrir el archivo. El resto del procesamiento del fragmento desde la posición actual del archivo hasta el delimitador más cercano es similar.

En otras palabras: la lectura del texto y la transferencia de la posición interna dentro del archivo se realiza en fragmentos de delimitador a delimitador, donde delimitador significa no sólo el carácter delimiter de la lista de parámetros FileOpen, sino también una nueva línea ('\n', '\r\n'), así como el principio y el final del archivo.

El delimitador adicional tiene el mismo efecto al escribir texto en archivos FILE_TXT y FILE_CSV, pero sólo cuando se utiliza la función FileWrite: inserta automáticamente este carácter entre los elementos grabados. El separador de funciones FileWriteString se ignora.

Veamos las descripciones formales de las funciones y, a continuación, un ejemplo en FileTxtCsv.mq5.

uint FileWrite(int handle, ...)

La función pertenece a la categoría de funciones que toman un número variable de parámetros. Estos parámetros se indican en el prototipo de la función con una elipsis. Sólo se admiten los tipos de datos integrados. Para escribir estructuras u objetos de clase, debe «desreferenciar» sus elementos y pasarlos individualmente.

La función escribe todos los argumentos pasados después del primero en un archivo de texto con el descriptor handle. Los argumentos se separan por comas, como en una lista de argumentos normal. El número de argumentos que se envían al archivo no puede ser superior a 63.

En la salida, los datos numéricos se convierten a formato de texto según las reglas de la conversión estándar a (string). Los valores o el tipo double tienen salida a 16 dígitos significativos, ya sea en formato tradicional o en formato de exponente científico (se elige la opción más compacta). Los datos del tipo float se muestran con una precisión de 7 dígitos significativos. Para mostrar números reales con una precisión diferente o en un formato especificado explícitamente, utilice la función DoubleToString (véase De números a cadenas y viceversa).

Los valores del tipo datetime se imprimen en el formato «AAAA.MM.DD hh:mm:ss» (véase Fecha y hora).

Un color estándar (de la lista de colores web) se muestra como un nombre, un color no estándar se muestra como un triple de valores de componentes RGB (véase Color), separados por comas (nota: la coma es el carácter separador más común en CSV).

En el caso de las enumeraciones se muestra un número entero que denota el elemento en lugar de su identificador (nombre). Por ejemplo, al escribir VIERNES (de ENUM_DAY_OF_WEEK, véase Enumeraciones) obtenemos el número 5 en el archivo.

Los valores del tipo bool se muestran como cadenas «true» o «false».

Si al abrir el archivo se ha especificado un carácter delimitador distinto de 0, éste se insertará entre dos líneas adyacentes resultantes de la conversión de los argumentos correspondientes.

Una vez que todos los argumentos se escriben en el archivo, se añade un terminador de línea '\r\n'.

La función devuelve el número de bytes escritos, o 0 en caso de error.

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

La función escribe el parámetro de cadena text en un archivo de texto con el descriptor handle. El parámetro length sólo es aplicable a archivos binarios y se ignora en este contexto (la línea se escribe completa).

La función FileWriteString también puede trabajar con archivos binarios. Esta aplicación de la función se describe en el apartado anterior.

Los separadores (entre elementos de una línea) y las nuevas líneas deben ser insertados o añadidos por el programador.

La función devuelve el número de bytes escritos (en modo FILE_UNICODE será 2 veces la longitud de la cadena en caracteres) o 0 en caso de error.

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

La función lee una cadena hasta el siguiente delimitador de un archivo con el descriptor handle (carácter delimitador en un archivo CSV, carácter de salto de línea en cualquier archivo, o hasta el final del archivo). El parámetro length sólo se aplica a los archivos binarios y se ignora en este contexto.

La cadena resultante se puede convertir en un valor del tipo requerido utilizando normas de reducción estándar o mediante funciones de conversión. Como alternativa, se pueden utilizar funciones de lectura especializadas, como FileReadBool, FileReadDatetime, FileReadNumber, que se describen a continuación.

En caso de error, se devolverá una cadena vacía. El código de error puede encontrarse por medio de la variable _LastError o de la función GetLastError. En concreto, cuando se alcance el final del archivo, el código de error será 5027 (FILE_ENDOFFILE).

bool FileReadBool(int handle)

La función lee un fragmento de un archivo CSV hasta el siguiente delimitador, o hasta el final de la línea y lo convierte en un valor del tipo bool. Si el fragmento contiene el texto «true» (ya sea en minúsculas, mayúsculas o una combinación de ambas, como en «True»), o un número distinto de cero, obtenemos true. En otros casos, obtenemos false.

La palabra «true» debe ocupar todo el elemento de lectura. Aun cuando la cadena empiece por «true» y tenga una continuación (por ejemplo, «True Volume»), obtendremos false.

datetime FileReadDatetime(int handle)

La función lee en un archivo CSV una cadena de uno de los siguientes formatos: «AAAA.MM.DD hh:mm:ss», «AAAA.MM.DD» o «hh:mm:ss», y lo convierte en un valor del tipo datetime. Si el fragmento no contiene una representación textual válida de la fecha y/o la hora, la función devolverá cero o una hora «rara», dependiendo de los caracteres que pueda interpretar como fragmentos de fecha y hora. Para cadenas vacías o no numéricas, obtenemos la fecha actual con hora cero.

Se puede conseguir una lectura más flexible de la fecha y la hora (con más formatos admitidos) combinando dos funciones: StringToTime(FileReadString(handle)). Para obtener más información sobre StringToTime, consulte Fecha y hora.

double FileReadNumber(int handle)

La función lee un fragmento del archivo CSV hasta el siguiente delimitador o hasta el final de la línea, y lo convierte en un valor de tipo double según las normas estándar de conversión de tipos.

Tenga en cuenta que double puede perder la precisión de valores muy grandes, lo que puede afectar a la lectura de números grandes de los tipos long/ulong (el valor a partir del cual se distorsionan los enteros dentro de double es 9007199254740992; se ofrece un ejemplo de este fenómeno en la sección Uniones).

Las funciones analizadas en la sección anterior, incluidas FileReadDouble, FileReadFloat, FileReadInteger, FileReadLong y FileReadStruct, no pueden aplicarse a archivos de texto.

El script FileTxtCsv.mq5 demuestra cómo trabajar con archivos de texto. La última vez cargamos las cotizaciones en un archivo binario. Ahora vamos a hacerlo en formatos TXT y CSV.

Básicamente, MetaTrader 5 permite exportar e importar cotizaciones en formato CSV desde el cuadro de diálogo «Símbolos». Sin embargo, a efectos educativos, reproduciremos este proceso. Además, la aplicación informática le permite desviarse del formato exacto que se genera por defecto. A continuación se muestra un fragmento del historial XAUUSD H1 exportado de la forma estándar.

Aquí, en concreto, puede que no estemos satisfechos con el carácter separador por defecto (tabulador, denotado como «»), el orden de las columnas o el hecho de que la fecha y la hora estén divididas en dos campos.

En nuestro script, elegiremos la coma como separador y generaremos las columnas en el orden de los campos de la estructura MqlRates. La descarga y posterior lectura de prueba se realizará en los modos FILE_TXT y FILE_CSV.

Las cotizaciones se solicitarán al principio de la función OnStart de la forma habitual:

Especificaremos los nombres de las columnas del array por separado, y también los combinaremos utilizando la función de ayuda StringCombine. Los títulos separados son necesarios porque los combinamos en un título común utilizando un carácter delimitador seleccionable (una solución alternativa podría basarse en StringReplace). Le animamos a que trabaje con el código fuente StringCombine de forma independiente: realiza la operación inversa con respecto al StringSplit integrado.

La última columna debería haberse llamado «Volume», pero utilizaremos su ejemplo para comprobar el rendimiento de la función FileReadBool. Puede suponer que el nombre actual implica «True Volume» (pero tal cadena no se interpretaría como true).

A continuación vamos a abrir dos archivos en los modos FILE_TXT y FILE_CSV, y a escribir en ellos el encabezado preparado.

Como la función FileWriteString no añade automáticamente una nueva línea, hemos añadido «\r\n» a la variable caption.

La escritura de campos de estructura desde el array rates se realiza de la misma manera, llamando a FileWrite en un bucle para cada uno de los dos archivos. Recuerde que la función FileWrite inserta automáticamente un carácter delimitador entre los argumentos y añade «\r\n» al final de la cadena. Por supuesto, era posible convertir independientemente todos los valores de salida en cadenas y enviarlos a un archivo utilizando FileWriteString, pero entonces tendríamos que ocuparnos nosotros mismos de los separadores y las nuevas líneas. En algunos casos no son necesarios, por ejemplo, si está escribiendo en formato JSON de forma compacta (esencialmente en una línea gigante).

Así, en la fase de grabación, ambos archivos se gestionaron de la misma manera y resultaron ser iguales. He aquí un ejemplo de su contenido para XAUUSD,H1 (sus resultados pueden variar):

Las diferencias a la hora de trabajar con estos archivos empezarán a aparecer en la fase de lectura.

Vamos a abrir un archivo de texto para leerlo y «escaneémoslo» utilizando la función FileReadString en un bucle, hasta que devuelva una cadena vacía (es decir, hasta el final del archivo).

El registro mostrará algo como esto:

Cada llamada de FileReadString lee la línea completa (hasta '\r\n') en el modo FILE_TXT. Para separarlo en elementos, debemos aplicar un tratamiento adicional. Opcionalmente, podemos utilizar el modo FILE_CSV.

Hagamos lo mismo con el archivo CSV.

Esta vez habrá muchas más entradas en el registro:

La cuestión es que la función FileReadString en el modo FILE_CSV tiene en cuenta el carácter delimitador y divide las cadenas en elementos. Cada llamada a FileReadString devuelve un único valor (celda) de una tabla CSV. Obviamente, las cadenas resultantes deben convertirse posteriormente a los tipos adecuados.

Este problema puede resolverse de forma generalizada utilizando las funciones especializadas FileReadDatetime, FileReadNumber, FileReadBool. Sin embargo, en cualquier caso, el desarrollador debe llevar un registro del número de la columna legible actual y determinar su significado práctico. En el tercer paso de la prueba se ofrece un ejemplo de un algoritmo de este tipo. Utiliza el mismo archivo CSV (para simplificar, lo cerramos al final de cada paso y lo abrimos al principio del siguiente).

Para simplificar la asignación del siguiente campo en la estructura MqlRates por el número de columna, hemos creado una estructura hija MqlRates que contiene un método de plantilla set:

En la función OnStart hemos descrito un array de una estructura de este tipo, donde añadiremos los valores entrantes. El array se requiere para simplificar el registro con ArrayPrint (no hay ninguna función ya preparada en MQL5 para imprimir una estructura por sí misma).

La variable count que cuenta los registros era necesaria no sólo para las estadísticas, sino también como medio para omitir la primera línea, que contiene encabezados y no datos. El número de columna actual se registra en la variable column. Su valor máximo no debe superar el número de columnas maxColumn.

Ahora sólo tenemos que abrir el archivo y leer elementos del mismo en un bucle utilizando varias funciones hasta que se produzca un error; en concreto, un error esperado como 5027 (FILE_ENDOFFILE), es decir, que se llegue al final del archivo.

Cuando el número de columna es 0, aplicamos la función FileReadDatetime. Para otras columnas, utilice FileReadNumber. La excepción es el caso de la primera línea con encabezados: para ello llamamos a la función FileReadBool a fin de demostrar cómo reaccionaría ante el encabezado «True» añadido deliberadamente a la última columna.

Esto es lo que se registra:

Como ve, de todos los encabezados, sólo el último se convierte al valor true, y todos los anteriores son false.

El contenido de las estructuras leídas es el mismo que el de los datos originales.