@c Language: Brazilian Portuguese, Encoding: iso-8859-1
@c /numericalio.texi/1.2/Sat Jun  2 00:13:28 2007//
@menu
* Introdu@value{cedilha}@~{a}o a numericalio::
* Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para numericalio::
@end menu

@node Introdu@value{cedilha}@~{a}o a numericalio, Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para numericalio, numericalio, numericalio
@section Introdu@value{cedilha}@~{a}o a numericalio

@code{numericalio} @'{e} uma cole@value{cedilha}@~{a}o de fun@value{cedilha}@~{o}es para ler e escrever arquivos de dados.
O arquivo @'{e} lido completamente para construir um objeto;
leituras parciais n@~{a}o s@~{a}o suportadas.

@'{E} assumido que cada item a ler ou escrever @'{e} at@^{o}mico:
um n@'{u}mero inteiro, n@'{u}mero em ponto flutuante, grande n@'{u}mero em ponto flutuante, seq@"{u}@^{e}ncia de caracteres, ou s@'{i}mbolo,
e n@~{a}o um n@'{u}mero racional ou um n@'{u}mero complexo ou qualquer outro tipo de express@~{a}o n@~{a}o at@^{o}mica.
Essas fun@value{cedilha}@~{o}es podem tentar fazer alguma coisa levemente parecida com express@~{o}es n@~{a}o at@^{o}micas,
mas os resultados n@~{a}o s@~{a}o especificados aqui e s@~{a}o sujeitos a mudan@value{cedilha}as.

@'{A}tomos em ambos os arquivos de entrada e sa@'{i}da possuem o mesmo formato que
em arquivos de lote do Maxima ou no console interativo.
Em particular, seq@"{u}@^{e}ncia de caracteres s@~{a}o contidas dentro de aspas duplas,
contrabarra @code{\} evita qualquer interpreta@value{cedilha}@~{a}o especial do caractere seguinte,
e o ponto de interroga@value{cedilha}@~{a}o @code{?} @'{e} reconhecido no in@'{i}cio de um s@'{i}mbolo
para significar um s@'{i}mbolo do Lisp (em oposi@value{cedilha}@~{a}o a um s@'{i}mbolo do Maxima).
Nenhum caractere de continua@value{cedilha}@~{a}o (para continuar linhas quebradas) @'{e} reconhecido.

@var{separator_flag} diz que caracteres separa elementos.
@var{separator_flag} @'{e} um argumento opcional para todas as fun@value{cedilha}@~{o}es de leitura e escrita.

Para entrada, os valores de @var{separator_flag} reconhecidos s@~{a}o:
@code{comma} para valores separados por v@'{i}rgula,
@code{pipe} para valores separados pelo caractere barra vertical @code{|},
@code{semicolon} para valores separados por ponto e v@'{i}rgula @code{;}, 
e @code{space} para valores separados pelos caracteres de espa@value{cedilha}o e de tabula@value{cedilha}@~{a}o.
Se o nome do arquivo a ser lido/escrito termina em @code{.csv} e @var{separator_flag} n@~{a}o for especificado,
@code{comma} @'{e} assumido.
Se o nome do arquivo termina em alguma outra coisa que n@~{a}o @code{.csv} e @code{separator_flag} n@~{a}o for especificado,
@code{space} @'{e} assumido.

Para sa@'{i}da, os mesmos quatro sinalizadores s@~{a}o reconhecidos como na entrada,
e tamb@'{e}m @code{tab}, para valores separados pelo caractere de tabula@value{cedilha}ao.

Em entrada, m@'{u}ltiplos espa@value{cedilha}os e multiplas tabula@value{cedilha}@~{o}es sucessivas contam como um separador simples.
Todavia, m@'{u}ltiplas v@'{i}rgulas, barras verticais, ou ponto-e-v@'{i}rgulas s@~{a}o significativos.
Sucessivas v@'{i}rgulas, barras verticais, ou ponto-e-v@'{i}rgulas (com ou sem intercala@value{cedilha}@~{a}o de espa@value{cedilha}os ou tabula@value{cedilha}@~{o}es)
s@~{a}o considerados como tendo @code{false} entre os separadores.
Por exemplo, @code{1234,,Foo} @'{e} tratado da mesma forma que @code{1234,false,Foo}.
Em sa@'{i}das, os @'{a}tomos @code{false} s@~{a}o escritos como tais;
uma lista @code{[1234, false, Foo]} @'{e} escrita @code{1234,false,Foo},
e n@~{a}o @'{e} tentado colapsar a sa@'{i}da para @code{1234,,Foo}.

@node Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para numericalio,  , Introdu@value{cedilha}@~{a}o a numericalio, numericalio
@section Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para numericalio

@deffn {Fun@value{cedilha}@~{a}o} read_matrix (@var{nomearquivo})
@deffnx {Fun@value{cedilha}@~{a}o} read_matrix (@var{nomearquivo}, @var{separator_flag})
L@^{e} o arquivo @var{nomearquivo} e retorna seu conte@'{u}do completo como uma matriz.
Se @var{separator_flag} n@~{a}o for especificado, o arquivo @'{e} assumido como delimitado por espa@value{cedilha}os em branco.

@code{read_matrix} infere o tamanho da matriz dos dados de entrada.
Cada linha do arquivo inicia uma linha da matriz.
Se algumas linhas possuirem diferentes comprimentos, @code{read_matrix} reclama.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} read_lisp_array (@var{nomearquivo}, @var{A})
@deffnx {Fun@value{cedilha}@~{a}o} read_lisp_array (@var{nomearquivo}, @var{A}, @var{separator_flag})

@code{read_lisp_array} exige que o array
seja declarado atrav@'{e}s de @code{make_array} antes de chamar
a fun@value{cedilha}@~{a}o de leitura. (Isso obviamente @'{e} necess@'{a}rio para inferir a dimens@~{a}o 
do array, que pode ser um problema para arrays com m@'{u}ltiplas dimens@~{o}es.)

@code{read_lisp_array} n@~{a}o verifica para ver se o 
arquivo de entrada est@'{a} de acordo com as dimens@~{a}oes do array; a entrada
@'{e} lida como uma lista mon@'{o}tona, ent@~{a}o o array @'{e} preenchido usando @code{fillarray}.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} read_maxima_array (@var{nomearquivo}, @var{A})
@deffnx {Fun@value{cedilha}@~{a}o} read_maxima_array (@var{nomearquivo}, @var{A}, @var{separator_flag})

@code{read_maxima_array} requer que o array
seja declarado atrav@'{e}s de @code{array} antes de chamar
a fun@value{cedilha}@~{a}o de leitura. (Isso obviamente @'{e} necess@'{a}rio para inferir a dimens@~{a}o 
do array, que pode ser uma hassle para arrays com m@'{u}ltiplas dimens@~{o}es.)

@code{read_maxima_array} n@~{a}o verifica para ver se o 
arquivo de entrada est@'{a} de acordo com as dimens@~{a}oes do array; a entrada
@'{e} lida como uma lista mon@'{o}tona, ent@~{a}o o array @'{e} preenchido usando @code{fillarray}.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} read_hashed_array (@var{nomearquivo}, @var{A})
@deffnx {Fun@value{cedilha}@~{a}o} read_hashed_array (@var{nomearquivo}, @var{A}, @var{separator_flag})

@code{read_hashed_array} trata o primeiro item sobre uma linha como uma
chave hash, e associa o restante da linha (como uma lista) com a chava.
Por exemplo,
a linha @code{567 12 17 32 55} @'{e} equivalente a @code{A[567]: [12, 17, 32, 55]$}.
Linhas n@~{a}o precisam ter o mesmo n@'{u}mero de elementos.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} read_nested_list (@var{nomearquivo})
@deffnx {Fun@value{cedilha}@~{a}o} read_nested_list (@var{nomearquivo}, @var{separator_flag})

@code{read_nested_list} retorna uma lista que tem uma sublista para cada
linha de entrada. Linhas n@~{a}o precisam ter o mesmo n@'umero de elementos.
Linhas vazias @i{n@~{a}o} s@~{a}o ignoradas: uma linha vazia retorna uma sublista vazia.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} read_list (@var{nomearquivo})
@deffnx {Fun@value{cedilha}@~{a}o} read_list (@var{nomearquivo}, @var{separator_flag})

@code{read_list} l@^{e} todas as entradas em uma lista mon@'{o}tona.
@code{read_list} ignora o caractere de fim de linha.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} write_data (@var{X}, @var{nomearquivo})
@deffnx {Fun@value{cedilha}@~{a}o} write_data (@var{object}, @var{nomearquivo}, @var{separator_flag})

@code{write_data} escreve o objeto @var{X} no arquivo @var{nomearquivo}.

@code{write_data} escreve matrizes da forma usual,
com uma linha por fileira.

@code{write_data} escreve arrays declarados do Lisp e do Maxima da
forma usual, com um caractere de nova linha no final de todo peda@value{cedilha}o.
Peda@value{cedilha}os dimensionais muito grandes s@~{a}o separados por meio de novas linhas adicionais.

@code{write_data} escreve arrays desordenados com uma chave seguida por
a lista associada sobre cada linha.

@code{write_data} escreve a lista seguinte com cada sublista em uma linha.

@code{write_data} escreve uma lista mon@'{o}tona toda em uma linha.

Se @code{write_data} anexa ao final ou abandona os excessos em seus arquivos de sa@'{i}da
@'{e} governado atrav@'{e}s da vari@'{a}vel global @code{file_output_append}.

@end deffn

