Rename specvar integer-info to *integer-info*

[maxima.git] / doc / info / es / numericalio.texi

@c English version: 2008-04-23
@menu
* Introducción a numericalio::
* Funciones y variables para entrada y salida en formato texto::
* Funciones y variables para entrada y salida en formato binario::
@end menu

@node Introducción a numericalio, Funciones y variables para entrada y salida en formato texto, numericalio, numericalio
@section Introducción a numericalio

El paquete @code{numericalio} define funciones para leer y escribir ficheros de datos
y flujos. Las funciones de entrada y salida en formato texto pueden leer y escribir
números (enteros, decimales o decimales grandes), símbolos y cadenas.
Las funciones de entrada y salida en formato binario sólo pueden leer y escribir
números decimales.

Si ya existe una lista, matriz o array para almacenar los datos de entrada,
las funciones de entrada de @code{numericalio} pueden escribir los datos
directamente en estos objetos. En caso contrario, @code{numericalio} tratará
de generar el objeto apropiado para almacenar estos datos.

@subsection Entrada y salida en formato texto

In plain-text input and output,
it is assumed that each item to read or write is an atom:

En la entrada y salida de datos en formato texto se supone que cada dato es un átomo:
un número entero, decimal, decimal grande, una cadena o un símbolo;
no se admiten fracciones, números complejos o cualquier otra expresión no
atómica. Estas funciones pueden llegar a realizar operaciones válidas con
expresiones no atómicas, pero estos resultados no se documentan y están sujetos
a cambios ulteriores.

Los átomos, tanto en los ficheros de entrada como en los de salida, tienen el 
mismo formato que en los ficheros por lotes de Maxima o en la consola
interactiva. En particular, las cadenas deben encerrarse entre comillas
dobles, la barra invertida @code{\} evita cualquier interpretación
especial del carácter siguiente, y el símbolo de
interrogación @code{?} se reconoce como el comienzo de un 
símbolo de Lisp. No se reconoce ningún carácter de
continuación de línea interrumpida.

@subsection Separadores válidos para lectura


Las funciones para la entrada y salida de datos en formato texto tiene un 
argumento opcional, @var{separator_flag}, para indicar qué carácter
se utiliza como separador.

Para la entrada de texto se reconocen los siguientes valores de la
variable @var{separator_flag}: @code{comma} para los valores separados por
comas, @code{pipe} para los valores separados por el carácter de la barra
vertical @code{|}, @code{semicolon} para los valores separados por punto y
coma @code{;}, y @code{space} para cuando los valores se separan por espacios
o tabulaciones. Si el nombre del fichero tiene extensión @code{.csv} y no se
especifica el argumento @var{separator_flag}, se tomará por defecto @code{comma}.
Si el fichero tiene cualquier otra extensión diferente de @code{.csv} y no se
especifica @code{separator_flag}, se usará por defecto @code{space}.

En la entrada de texto, varios espacios y tabulaciones sucesivos cuentan como un
único separador. Sin embargo, varias comas, barras verticales o punto y comas 
sucesivos se interpretan que tienen el símbolo @code{false} entre
ellos; por ejemplo, @code{1234,,Foo} se interpreta lo mismo que si fuese
@code{1234,false,Foo}. En la salida, los átomos @code{false} deben
escribirse explícitamente, por lo que la lista 
@code{[1234, false, Foo]} debe escribirse @code{1234,false,Foo}.

@subsection Separadores válidos para escritura

Para la entrada de texto se acepta @code{tab} como valor de @var{separator_flag}
 para datos separados por tabuladores, así como
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.

En la escritura de texto, el átomo@code{false} se escribe tal cual y
una lista @code{[1234, false, Foo]} se escribe @code{1234,false,Foo}.






@subsection Entrada y salida de decimales en formato binario

Las funciones de @code{numericalio} pueden leer y escribir números decimales en
coma flotante de 8 bytes del estándar IEEE 754. Estos números se pueden escribir
empezando por el byte menos significativo o por el más significativo, según lo
indique la variable global @code{assume_external_byte_order}. Por defecto, @code{numericalio}
los almacena con el byte más significativo primero.

Cualesquiera otros tipos de decimales son transformados a 8 bytes. El paquete
@code{numericalio} no puede leer ni escribir datos binarios no numéricos.

Ciertos entornos Lisp no reconocen valores especiales del estándar IEEE 754
(más o menos infinito, valores no numéricos, valores no normales). El efecto
que pueda producir la lectura de tales valores por parte de @code{numericalio}
es imprevisible.

@code{numericalio} incluye funciones para abrir un flujo de lectura o escritura 
de flujos de bytes.


@node Funciones y variables para entrada y salida en formato texto, Funciones y variables para entrada y salida en formato binario, Introducción a numericalio, numericalio
@section Funciones y variables para entrada y salida en formato texto

@deffn {Función} read_matrix (@var{S})
@deffnx {Función} read_matrix (@var{S}, @var{M})
@deffnx {Función} read_matrix (@var{S}, @var{separator_flag})
@deffnx {Función} read_matrix (@var{S}, @var{M}, @var{separator_flag})

@code{read_matrix(@var{S})} lee la fuente @var{S} y devuelve su contenido completo en forma
de matriz. El tamaño de la matriz se deduce de los datos de entrada: 
cada fila del fichero forma una fila de la matriz. Si hay filas con diferente número de elementos,
@code{read_matrix} emite un mensaje de error.

@code{read_matrix(@var{S}, @var{M})} lee la fuente @var{S} y va almacenando su contenido
en la matriz @var{M}, hasta que @var{M} esté llena o hasta que se consuma la fuente.
Los datos se almacenan fila a fila. Los datos de entrada no necesitan tener el
mismo número de filas y columnas que @var{M}.

La fuente @var{S} puede ser el nombre de un fichero o de un flujo.

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.

@end deffn

@deffn {Función} read_array (@var{S}, @var{A})
@deffnx {Función} read_array (@var{S}, @var{A}, @var{separator_flag})

Guarda el contenido de la fuente @var{S} en el array @var{A},
hasta que @var{A} esté lleno o hasta que se consuma la fuente.
Los datos se almacenan fila a fila. Los datos de entrada no necesitan tener el
mismo número de filas y columnas que @var{A}.

La fuente @var{S} puede ser el nombre de un fichero o de un flujo.

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.

@end deffn


@deffn {Función} read_hashed_array (@var{S}, @var{A})
@deffnx {Función} read_hashed_array (@var{S}, @var{A}, @var{separator_flag})

Lee la fuente @var{S} y devuelve su contenido completo en forma de array de claves.
La fuente @var{S} puede ser el nombre de un fichero o de un flujo.

@code{read_hashed_array} interpreta el primer elemento de cada fila como una clave,
asociando el resto de la fila, en formato de lista, a la clave. Por ejemplo,
la secuencia @code{567 12 17 32 55} equivale a @code{A[567]: [12, 17, 32, 55]$}.
Las filas no necesitan tener todas ellas el mismo número de elementos.

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.
@end deffn

@deffn {Función} read_nested_list (@var{S})
@deffnx {Función} read_nested_list (@var{S}, @var{separator_flag})

Lee la fuente @var{S} y devuelve su contenido completo en forma de lista anidada.
La fuente @var{S} puede ser el nombre de un fichero o de un flujo.

@code{read_nested_list} devuelve una lista que tiene una sublista por cada fila
de entrada. Los filas de entrada no necesitan tener todas ellas el mismo número
de elementos. Las filas en blanco no se ignoran, sino que se convierten 
en listas vacías

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.
@end deffn

@deffn {Función} read_list (@var{S})
@deffnx {Función} read_list (@var{S}, @var{L})
@deffnx {Función} read_list (@var{S}, @var{separator_flag})
@deffnx {Función} read_list (@var{S}, @var{L}, @var{separator_flag})

@code{read_list(@var{S})} lee la fuente @var{S} y devuelve su contenido como una lista simple.

@code{read_list(@var{S}, @var{L})} guarda el contenido de la fuente @var{S} en la lista @var{L},
hasta que @var{L} esté llena o hasta que se consuma la fuente.

La fuente @var{S} puede ser el nombre de un fichero o de un flujo.

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.
@end deffn

@deffn {Función} write_data (@var{X}, @var{D})
@deffnx {Función} write_data (@var{X}, @var{D}, @var{separator_flag})

Escribe el objeto @var{X} en el destino @var{D}.

@code{write_data} escribe una matriz fila a fila; cada línea de
entrada se corresponde con una fila.

@code{write_data} escribe un array creado por @code{array} o @code{make_array}
fila a fila, con una nueva línea al final de cada bloque de datos.
Los bloques de mayores dimensiones se separan con líneas adicionales.

@code{write_data} escribe un array de claves con cada clave seguida de su lista
asociada en una sola línea.

@code{write_data} escribe una lista anidada con una sublista por línea.

@code{write_data} escribe una lista simple en una única fila.

El destino @var{D} puede ser el nombre de un fichero o un flujo; en el primer caso,
la variable global @code{file_output_append} controla si el fichero de salida es
ampliado con la nueva información o si se borra antes; en el segundo caso,
no se realiza ningún tipo de acción por parte de @code{write_data} después
de que se hayan escrito los datos; en particular, el flujo se mantiene abierto.

Los valores aceptados para @var{separator_flag} son:
@code{comma}, @code{pipe}, @code{semicolon} y @code{space}.
Si no se especifica un valor para @var{separator_flag},
se supone que los datos están separados por espacios.
@end deffn




@node Funciones y variables para entrada y salida en formato binario, , Funciones y variables para entrada y salida en formato texto, numericalio
@section Funciones y variables para entrada y salida en formato binario

@deffn {Función} assume_external_byte_order (@var{byte_order_flag})

Le indica a @code{numericalio} el orden de los bytes en que debe leer y escribir los datos.
Los valores que reconoce @var{byte_order_flag} son dos:
@code{lsb}, que indica que el byte menos significativo debe ser el primero, y @code{msb},
que indica que el byte más significativo es el que debe ir en primer lugar.

En caso de no hacer ninguna selección, @code{numericalio} interpreta que es el byte
más significativo el que se debe leer o escribir primero.
@end deffn

@deffn {Función} openr_binary (@var{file_name})
Devuelve un flujo de entrada de bytes no signados para la lectura del fichero de nombre @var{file_name}.

@end deffn

@deffn {Función} openw_binary (@var{file_name})
Devuelve un flujo de entrada de bytes no signados para la escritura en el fichero de nombre @var{file_name}.

@end deffn

@deffn {Función} opena_binary (@var{file_name})
Devuelve un flujo de entrada de bytes no signados para añadir datos al fichero de nombre @var{file_name}.

@end deffn

@deffn {Función} read_binary_matrix (@var{S}, @var{M})
Lee números decimales en coma flotante de 8 bytes desde la fuente @var{S} y los
va almacenando en la matriz @var{M}, bien hasta que @var{M} se llene, o bien hasta que
la fuente se haya consumido. La matriz @var{M} se rellena fila a fila.

La fuente @var{S} puede ser el nombre de un fichero o un flujo.

El orden de los bytes de los datos procedentes de la fuente se especifican
mediante @code{assume_external_byte_order}.

@end deffn

@deffn {Función} read_binary_array (@var{S}, @var{A})
Lee números decimales en coma flotante de 8 bytes desde la fuente @var{S} y los
va almacenando en el array @var{A}, bien hasta que @var{A} se llene, o bien hasta que
la fuente se haya consumido. @var{A} debe ser un array creado por @code{array}
o por @code{make_array}. El array @var{A} se rellena fila a fila.

La fuente @var{S} puede ser el nombre de un fichero o un flujo.

El orden de los bytes de los datos procedentes de la fuente se especifican
mediante @code{assume_external_byte_order}.

@end deffn

@deffn {Función} read_binary_list (@var{S})
@deffnx {Función} read_binary_list (@var{S}, @var{L})
@code{read_binary_list(@var{S})} lee el contenido completo de la fuente de datos @var{S}
como una secuencia de números decimales en coma flotante de 8 bytes en formato binario,
devolviéndolos en forma de lista.

La fuente @var{S} puede ser el nombre de un fichero o un flujo.

@code{read_binary_list(@var{S}, @var{L})} lee números decimales en coma flotante de 8 bytes en
formato binario desde la fuente @var{S} y los almacena en la lista @var{L}, bien hasta que
ésta esté llena, o bien hasta que se consuman los datos de la fuente.

El orden de los bytes de los datos procedentes de la fuente se especifican
mediante @code{assume_external_byte_order}.
@end deffn

@deffn {Función} write_binary_data (@var{X}, @var{D})

Escribe el objeto @var{X}, que contiene números decimales en
coma flotante de 8 bytes del estándar IEEE 754, en el destino @var{D}.
Cualesquiera otros tipos de decimales son transformados a 8 bytes. 
@code{write_binary_data} no puede escribir datos no numéricos.

El objeto @var{X} puede ser una lista, una lista anidada, una matriz, o un
array creado con @code{array} o @code{make_array}; @var{X} no puede ser
ni un array no declarado ni cualquier otro tipo de objeto distinto a los citados.
@code{write_binary_data} escribe las listas anidadas, las matrices y los arrays
fila a fila.

El destino @var{D} puede ser el nombre de un fichero o un flujo; en el primer caso,
la variable global @code{file_output_append} controla si el fichero de salida es
ampliado con la nueva información o si se borra antes; en el segundo caso,
no se realiza ningún tipo de acción por parte de @code{write_binary_data} después
de que se hayan escrito los datos; en particular, el flujo se mantiene abierto.

El orden de los bytes de los datos procedentes de la fuente se especifican
mediante @code{assume_external_byte_order}.

@end deffn