@c Language: Brazilian Portuguese, Encoding: iso-8859-1
@c /Program.texi/1.26/Sat Jun  9 01:31:20 2007/-ko/
@menu
* Introdu@value{cedilha}@~{a}o a Fluxo de Programa::  
* Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para Fluxo de Programa::  
@end menu

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

Maxima fornece um @code{do} para ciclos iterativos, tamb@'{e}m contru@value{cedilha}@~{o}es mais
primitivas tais como @code{go}.

@c end concepts Fluxo de Programa
@node Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para Fluxo de Programa,  , Introdu@value{cedilha}@~{a}o a Fluxo de Programa, Fluxo de Programa
@section Fun@value{cedilha}@~{o}es e Vari@'{a}veis Definidas para Fluxo de Programa

@deffn {Fun@value{cedilha}@~{a}o} backtrace ()
@deffnx {Fun@value{cedilha}@~{a}o} backtrace (@var{n})
Imprime a pilha de chamadas, que @'{e}, a lista de fun@value{cedilha}@~{o}es que
foram chamadas pela fun@value{cedilha}@~{a}o correntemente ativa.

@code{backtrace()} imprime toda a pilha de chamadas.

@code{backtrace (@var{n})} imprime as @var{n} mais recentes chamadas a
fun@value{cedilha}@~{o}es, incluindo a fun@value{cedilha}@~{a}o correntemente ativa.

@c IS THIS STATMENT REALLY NEEDED ?? 
@c (WHY WOULD ANYONE BELIEVE backtrace CANNOT BE CALLED OUTSIDE A DEBUGGING CONTEXT??)
@code{backtrace} pode ser chamada por um script, uma fun@value{cedilha}@~{a}o, ou a partir da linha de comando interativa
(n@~{a}o somente em um contexto de depura@value{cedilha}@~{a}o).

Exemplos:

@itemize @bullet
@item
@code{backtrace()} imprime toda a pilha de chamadas.

@example
(%i1) h(x) := g(x/7)$
(%i2) g(x) := f(x-11)$
(%i3) f(x) := e(x^2)$
(%i4) e(x) := (backtrace(), 2*x + 13)$
(%i5) h(10);
#0: e(x=4489/49)
#1: f(x=-67/7)
#2: g(x=10/7)
#3: h(x=10)
                              9615
(%o5)                         ----
                               49
@end example
@end itemize

@itemize @bullet
@item
@code{backtrace (@var{n})} imprime as @var{n} mais recentes chamadas a
fun@value{cedilha}@~{o}es, incluindo a fun@value{cedilha}@~{a}o correntemente ativa.

@example
(%i1) h(x) := (backtrace(1), g(x/7))$
(%i2) g(x) := (backtrace(1), f(x-11))$
(%i3) f(x) := (backtrace(1), e(x^2))$
(%i4) e(x) := (backtrace(1), 2*x + 13)$
(%i5) h(10);
#0: h(x=10)
#0: g(x=10/7)
#0: f(x=-67/7)
#0: e(x=4489/49)
                              9615
(%o5)                         ----
                               49
@end example
@end itemize

@end deffn

@deffn {Operador especial} do
A declara@value{cedilha}@~{a}o @code{do} @'{e} usada para executar itera@value{cedilha}@~{a}o.  Devido @`a sua
grande generalidade a declara@value{cedilha}@~{a}o @code{do} ser@'{a}  descrita em duas partes.
Primeiro a forma usual ser@'{a} dada que @'{e} an@'{a}loga @`a forma que @'{e} usada em
muitas outras linguagens de programa@value{cedilha}@~{a}o (Fortran, Algol, PL/I, etc.); em segundo lugar
os outros recursos ser@~{a}o mencionados.

Existem tr@^{e}s variantes do operador especial @code{do} que diferem somente por suas
condi@value{cedilha}@~{o}es de encerramento.  S@~{a}o elas:

@itemize @bullet
@item
@code{for @var{Vari@'{a}vel}: @var{valor_inicial} step @var{incremento}
      thru @var{limite} do @var{corpo}}
@item
@code{for @var{Vari@'{a}vel}: @var{valor_inicial} step @var{incremento}
      while @var{condi@value{cedilha}@~{a}o} do @var{corpo}}
@item
@code{for @var{Vari@'{a}vel}: @var{valor_inicial} step @var{incremento}
      unless @var{condi@value{cedilha}@~{a}o} do @var{corpo}}
@end itemize

@c UGH.  DO WE REALLY NEED TO MENTION THIS??
(Alternativamente, o @code{step} pode ser dado ap@'{o}s a @var{condi@value{cedilha}@~{a}o} de encerramento
ou limite.)

@var{valor_inicial}, @var{incremento}, @var{limite}, e @var{corpo} podem ser quaisquer
express@~{o}es.  Se o incremento for 1 ent@~{a}o "@code{step 1}" pode ser omitido.

A execu@value{cedilha}@~{a}o da declara@value{cedilha}@~{a}o @code{do} processa-se primeiro atribuindo o
@code{valor_inicial} para a vari@'{a}vel (daqui em diante chamada a
vari@'{a}vel de controle).  Ent@~{a}o: (1) Se a vari@'{a}vel de controle excede
o limite de uma especifica@value{cedilha}@~{a}o @code{thru}, ou se a condi@value{cedilha}@~{a}o de @code{unless} for
@code{true}, ou se a condi@value{cedilha}@~{a}o de @code{while} for @code{false} ent@~{a}o o @code{do}
ser@'{a} encerrado.  (2) O @var{corpo} @'{e} avaliado.  (3) O incremento @'{e} adicionado @`a
vari@'{a}vel de controle.  O processo de (1) a (3) @'{e} executado
repetidamente at@'{e} que a condi@value{cedilha}@~{a}o de encerramento seja satisfeita.  Pode-se tamb@'{e}m
dar muitas condi@value{cedilha}@~{o}es de encerramento e nesse caso o @code{do} termina
quando qualquer delas for satisfeita.

Em geral o teste @code{thru} @'{e} satisfeito quando a vari@'{a}vel de controle for
maior que o @var{limite} se o incremento for n@~{a}o negativo, ou quando a
vari@'{a}vel de controle for menor que o @var{limite} se o @var{incremento} for negativo.
O @var{incremento} e o @var{limite} podem ser express@~{o}es n@~{a}o num@'{e}ricas enquanto essa
desigualdade puder ser determinada.  Todavia, a menos que o @var{incremento} seja
sintaticamente negativo (e.g. for um n@'{u}mero negativo) na hora em que a declara@value{cedilha}@~{a}o @code{do}
for iniciada, Maxima assume que o incremento e o limite ser@~{a}o positivos quando o @code{do} for
executado.  Se o limite e o incremento n@~{a}o forem positivos, ent@~{a}o o @code{do} pode n@~{a}o terminar
propriamente.

Note que o @var{limite}, @var{incremento}, e @var{condi@value{cedilha}@~{a}o} de encerramento s@~{a}o
avaliados cada vez que ocorre um ciclo.  Dessa forma se qualquer desses for respons@'{a}vel por
muitos c@'{a}lculos, e retornar um resultado que n@~{a}o muda durante todas
as execu@value{cedilha}@~{o}es do @var{corpo}, ent@~{a}o @'{e} mais eficiente escolher uma
vari@'{a}vel para seu valor pr@'{e}vio para o @code{do} e usar essa vari@'{a}vel na
forma @code{do}.

O valor normalmente retornado por uma declara@value{cedilha}@~{a}o @code{do} @'{e} o @'{a}tomo @code{done}.
Todavia, a fun@value{cedilha}@~{a}o
@code{return} pode ser usada dentro do @var{corpo} para sair da delcara@value{cedilha}@~{a}o @code{do} prematuramente e dar
a isso qualquer valor desejado.
Note todavia que um @code{return} dentro de um @code{do} que
ocorre em um @code{block} encerrar@'{a} somente o @code{do} e n@~{a}o o @code{block}.  Note tamb@'{e}m
que a fun@value{cedilha}@~{a}o @code{go} n@~{a}o pode ser usada para sair de dentro de um @code{do} dentro de um
@code{block} que o envolve.

A vari@'{a}vel de controle @'{e} sempre local para o @code{do} e dessa forma qualquer
vari@'{a}vel pode ser usada sem afetar o valor de uma vari@'{a}vel com
o mesmo nome fora da declara@value{cedilha}@~{a}o @code{do}.  A vari@'{a}vel de controle @'{e} liberada
ap@'{o}s o encerramento da declara@value{cedilha}@~{a}o @code{do}.

@example
(%i1) for a:-3 thru 26 step 7 do display(a)$
                             a = - 3

                              a = 4

                             a = 11

                             a = 18

                             a = 25
@end example

@example
(%i1) s: 0$
(%i2) for i: 1 while i <= 10 do s: s+i;
(%o2)                         done
(%i3) s;
(%o3)                          55
@end example

Note que a condi@value{cedilha}@~{a}o @code{while i <= 10}
@'{e} equivalente a @code{unless i > 10} e tamb@'{e}m @code{thru 10}.

@example
(%i1) series: 1$
(%i2) term: exp (sin (x))$
(%i3) for p: 1 unless p > 7 do
          (term: diff (term, x)/p, 
           series: series + subst (x=0, term)*x^p)$
(%i4) series;
                  7    6     5    4    2
                 x    x     x    x    x
(%o4)            -- - --- - -- - -- + -- + x + 1
                 90   240   15   8    2
@end example

que fornece 8 termos da s@'{e}rie de Taylor para @code{e^sin(x)}.

@example
(%i1) poly: 0$
(%i2) for i: 1 thru 5 do
          for j: i step -1 thru 1 do
              poly: poly + i*x^j$
(%i3) poly;
                  5      4       3       2
(%o3)          5 x  + 9 x  + 12 x  + 14 x  + 15 x
(%i4) guess: -3.0$
(%i5) for i: 1 thru 10 do
          (guess: subst (guess, x, 0.5*(x + 10/x)),
           if abs (guess^2 - 10) < 0.00005 then return (guess));
(%o5)                  - 3.162280701754386
@end example

Esse exemplo calcula a ra@'{i}z quadrada negativa de 10 usando a
itera@value{cedilha}@~{a}o de Newton- Raphson um maximum de 10 vezes.  Caso o crit@'{e}rio de
converg@^{e}cia n@~{a}o tenha sido encontrado o valor retornado pode ser @code{done}.
Em lugar de sempre adicionar uma quantidade @`a vari@'{a}vel de controle pode-se
algumas vezes desejar alterar isso de alguma outra forma para cada itera@value{cedilha}@~{a}o.
Nesse caso pode-se usar @code{next @var{express@~{a}o}} em lugar de @code{step @var{incremento}}.
Isso far@'{a} com que a vari@'{a}vel de controle seja escolhida para o
resultado de avalia@value{cedilha}@~{a}o da @var{express@~{a}o} cada vez que o ciclo de repeti@value{cedilha}@~{a}o for executado.

@example
(%i6) for count: 2 next 3*count thru 20 do display (count)$
                            count = 2

                            count = 6

                           count = 18
@end example

@c UGH.  DO WE REALLY NEED TO MENTION THIS??
Como uma alternativa para @code{for @var{Vari@'{a}vel}: @var{valor} ...do...} a sintaxe
@code{for @var{Vari@'{a}vel} from @var{valor} ...do...}  pode ser usada.  Isso permite o
@code{from @var{valor}} ser colocado ap@'{o}s o @code{step} ou ap@'{o}s o @var{next} valor ou ap@'{o}s a
@var{condi@value{cedilha}@~{a}o} de encerramento.  Se @code{from @var{valor}} for omitido ent@~{a}o 1 @'{e} usado como
o valor inicial.

Algumas vezes se pode estar interessado em executar uma itera@value{cedilha}@~{a}o onde
a vari@'{a}vel de controle nunca seja usada.  Isso @'{e} permiss@'{i}vel
para dar somente as condi@value{cedilha}@~{o}es de encerramento omitindo a inicializa@value{cedilha}@~{a}o
e a informa@value{cedilha}@~{a}o de atualiza@value{cedilha}@~{a}o como no exemplo seguinte para para calcular a
ra@'{i}z quadrada de 5 usando uma fraca suposi@value{cedilha}@~{a}o inicial.

@example
(%i1) x: 1000$
(%i2) thru 20 do x: 0.5*(x + 5.0/x)$
(%i3) x;
(%o3)                   2.23606797749979
(%i4) sqrt(5), numer;
(%o4)                   2.23606797749979
@end example

Se isso for desejado pode-se sempre omitir as condi@value{cedilha}@~{o}es de encerramento
inteiramente e apenas dar o @code{do @var{corpo}} que o @var{corpo} continuar@'{a} a ser 
avaliado indefinidamente.  Nesse caso a fun@value{cedilha}@~{a}o @code{return} ser@'{a} usada para
encerrar a execu@value{cedilha}@~{a}o da declara@value{cedilha}@~{a}o @code{do}.

@example
(%i1) newton (f, x):= ([y, df, dfx], df: diff (f ('x), 'x),
          do (y: ev(df), x: x - f(x)/y, 
              if abs (f (x)) < 5e-6 then return (x)))$
(%i2) sqr (x) := x^2 - 5.0$
(%i3) newton (sqr, 1000);
(%o3)                   2.236068027062195
@end example

@c DUNNO IF WE NEED THIS LEVEL OF DETAIL; THIS ARTICLE IS GETTING PRETTY LONG
(Note que @code{return}, quando executado, faz com que o valor corrente de
@code{x} seja retornado como o valor da declara@value{cedilha}@~{a}o @code{do}.  O @code{block} @'{e} encerrado e
esse valor da declara@value{cedilha}@~{a}o @code{do} @'{e} retornado como o valor do @code{block} porque o
@code{do} @'{e} a @'{u}ltima declara@value{cedilha}@~{a}o do @code{block}.)

Uma outra forma de @code{do} @'{e} dispon@'{i}vel no Maxima.  A sintaxe @'{e}:

@example
for @var{Vari@'{a}vel} in @var{list} @var{end_tests} do @var{corpo}
@end example

Os elementos de @var{list} s@~{a}o quaisquer express@~{o}es que ir@~{a}o
sucessivamente ser atribu@'{i}das para a @var{vari@'{a}vel} a cada itera@value{cedilha}@~{a}o do
@var{corpo}.  O teste opcional @var{end_tests} pode ser usado para encerrar a execu@value{cedilha}@~{a}o da
declara@value{cedilha}@~{a}o @code{do}; de outra forma o @code{do} terminar@'{a} quando a @var{lista} for exaurida ou quando
um @code{return} for executado no @var{corpo}.  (De fato, a @var{lista} pode ser qualquer
express@~{a}o n@~{a}o at@^{o}mica, e partes sucessivas s@~{a}o usadas.)

@example
(%i1)  for f in [log, rho, atan] do ldisp(f(1))$
(%t1)                                  0
(%t2)                                rho(1)
                                     %pi
(%t3)                                 ---
                                      4
(%i4) ev(%t3,numer);
(%o4)                             0.78539816
@end example

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} errcatch (@var{expr_1}, ..., @var{expr_n})
Avalia @var{expr_1}, ..., @var{expr_n} uma por uma e
retorna @code{[@var{expr_n}]} (uma lista) se nenhum erro ocorrer.  Se um
erro ocorrer na avalia@value{cedilha}@~{a}o de qualquer argumento, @code{errcatch}
evita que o erro se propague e
retorna a lista vazia @code{[]} sem avaliar quaisquer mais argumentos.

@code{errcatch}
@'{e} @'{u}til em arquivos @code{batch} onde se suspeita que um erro possa estar ocorrendo o @code{errcatch}
terminar@'{a} o @code{batch} se o erro n@~{a}o for detectado.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} error (@var{expr_1}, ..., @var{expr_n})
@deffnx {Vari@'{a}vel de sistema} error
Avalia e imprime @var{expr_1}, ..., @var{expr_n},
e ent@~{a}o causa um retorno de erro para o n@'{i}vel mais alto do Maxima
ou para o mais pr@'{o}ximo contendo @code{errcatch}.

A vari@'{a}vel @code{error} @'{e} escolhida para uma lista descrevendo o erro.
O primeiro elemento de @code{error} @'{e} uma seq@"{u}@^{e}ncia de caracteres de formato,
que junta todas as seq@"{u}@^{e}ncias de caracteres entre os argumentos @var{expr_1}, ..., @var{expr_n},
e os elementos restantes s@~{a}o os valores de quaisquer argumentos que n@~{a}o s@~{a}o seq@"{u}@^{e}ncias de caracteres.

@code{errormsg()} formata e imprime @code{error}.
Isso efetivamente reimprime a mais recente mensagem de erro.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} errormsg ()
Reimprime a mais recente mensagem de erro.
A vari@'{a}vel @code{error} recebe a mensagem,
e @code{errormsg} formata e imprime essa mensagem.

@end deffn

@c REPHRASE
@c AT LEAST SHOULD LIST VARIANTS HERE
@deffn {Operador especial} for
Usado em itera@value{cedilha}@~{o}es.  Veja @code{do} para uma descri@value{cedilha}@~{a}o das
facilidades de itera@value{cedilha}@~{a}o do Maxima.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} go (@var{tag})
@'{e} usada dentro de um @code{block} para transferir o controle para a declara@value{cedilha}@~{a}o
do bloco que for identificada com o argumento para @code{go}.  Para identificar uma
declara@value{cedilha}@~{a}o, coloque antes dessa declara@value{cedilha}@~{a}o um argumento at@^{o}mico como outra declara@value{cedilha}@~{a}o no
@code{block}.  Por exemplo:

@example
block ([x], x:1, loop, x+1, ..., go(loop), ...)
@end example

O argumento para @code{go} deve ser o nome de um identificardor aparecendo no mesmo
@code{block}.  N@~{a}o se pode usar @code{go} para transferir para um identificador em um outro @code{block} que n@~{a}o seja
o pr@'{o}prio contendo o @code{go}.

@end deffn

@c NEEDS CLARIFICATION, EXPANSION, EXAMPLES
@c THIS ITEM IS IMPORTANT
@deffn {Operador especial} if
Representa avalia@value{cedilha}@~{a}o condicional. V@'{a}rias formas de express@~{o}es @code{if} s@~{a}o reconhecidas.
@code{if @var{cond_1} then @var{expr_1} else @var{expr_0}}
avalia para @var{expr_1} se @var{cond_1} avaliar para @code{true},
de outra forma a express@~{a}o avalia para @code{expr_0}.

@code{if @var{cond_1} then @var{expr_1} elseif @var{cond_2} then @var{expr_2} elseif ... else @var{expr_0}}
avalia para @var{expr_k} se @var{cond_k} for @code{true} e todas as condi@value{cedilha}@~{o}es precedentes forem @code{false}.
Se nenhuma das condi@value{cedilha}@~{o}es forem @code{true}, a express@~{a}o avalia para @code{expr_0}.

O comportamento @code{else false} @'{e} assumido se @code{else} for omitido.
Isso @'{e}, @code{if @var{cond_1} then @var{expr_1}} @'{e} equivalente a
@code{if @var{cond_1} then @var{expr_1} else false},
e @code{if @var{cond_1} then @var{expr_1} elseif ... elseif @var{cond_n} then @var{expr_n}}
@'{e} equivalente a
@code{if @var{cond_1} then @var{expr_1} elseif ... elseif @var{cond_n} then @var{expr_n} else false}.

As alternativas @var{expr_0}, ..., @var{expr_n} podem ser quaisquer express@~{o}es do Maxima,
inclu@'{i}ndo express@~{o}es @code{if} aninhadas ( if dentro de if).
As alternativas n@~{a}o s@~{a}o nem simplificadas nem avaliadas a menos que a correspondente condi@value{cedilha}@~{a}o seja @code{true}.

As condi@value{cedilha}@~{o}es @var{cond_1}, ..., @var{cond_n} s@~{a}o express@~{o}es as quais potencialmente ou atualmente
avaliem para @code{true} ou para @code{false}.
Quando uma condi@value{cedilha}@~{a}o n@~{a}o avalia atualmente para para @code{true} ou para @code{false},
o comportamento de @code{if} @'{e} governado pelo sinalizador global @code{prederror}.
Quando @code{prederror} for @code{true},
isso @'{e} um erro se qualquer condi@value{cedilha}@~{a}o avaliada n@~{a}o avaliar para @code{true} ou @code{false}.
De outra forma, condi@value{cedilha}@~{o}es que n@~{a}o avaliem para @code{true} ou @code{false} s@~{a}o aceitas,
e o resultado @'{e} uma express@~{a}o condicional.

Entre outros elementos, condi@value{cedilha}@~{o}es podem compreender operadores l@'{o}gicos e relacionais como segue.

@c - SEEMS LIKE THIS TABLE WANTS TO BE IN A DISCUSSION OF PREDICATE FUNCTIONS; PRESENT LOCATION IS OK I GUESS
@c - REFORMAT THIS TABLE USING TEXINFO MARKUP (MAYBE)
@example
Opera@value{cedilha}@~{a}o             S@'{i}mbolo      Tipo
 
menor que            <           infixo relacional
menor que            <=
  ou igual a                     infixo relacional
igualdade            =
  (sint@'{a}tica)                    infixo relacional
nega@value{cedilha}@~{a}o de =         #           infixo relacional
igualdade (valor)    equal       fun@value{cedilha}@~{a}o relacional
nega@value{cedilha}@~{a}o de           notequal
  igualdade                      fun@value{cedilha}@~{a}o relacional
maior que            >=
  ou igual a                     infixo relacional
maior que            >           infixo relacional
e                    and         infixo l@'{o}gico
ou                   or          infixo l@'{o}gico
n@~{a}o                  not         prefixo l@'{o}gico
@end example

@end deffn

@c NEEDS CLARIFICATION
@c THIS ITEM IS IMPORTANT
@deffn {Fun@value{cedilha}@~{a}o} map (@var{f}, @var{expr_1}, ..., @var{expr_n})
Retorna uma express@~{a}o cujo operador principal
@'{e} o mesmo que o das express@~{o}es
@var{expr_1}, ..., @var{expr_n} mas cujas subpartes s@~{a}o os resultados da
aplica@value{cedilha}@~{a}o de @var{f} nas correspondentes subpartes das express@~{o}es.  @var{f} @'{e} ainda
o nome de uma fun@value{cedilha}@~{a}o de @math{n} argumentos
ou @'{e} uma forma @code{lambda} de @math{n} argumentos.

@code{maperror} - se @code{false} far@'{a} com que todas as fun@value{cedilha}@~{o}es mapeadas
(1) parem quando elas terminarem retornando a menor @var{exp_i} se n@~{a}o forem todas as
@var{exp_i} do mesmo comprimento e (2) aplique fn a [exp1, exp2,...]
se @var{exp_i} n@~{a}o forem todas do mesmo tipo de objeto.  Se @code{maperror} for @code{true}
ent@~{a}o uma mensagem de erro ser@'{a} dada nas duas inst@^{a}ncias acima.

Um dos usos dessa fun@value{cedilha}@~{a}o @'{e} para mapear (@code{map}) uma fun@value{cedilha}@~{a}o (e.g. @code{partfrac})
sobre cada termo de uma express@~{a}o muito larga onde isso comumente n@~{a}o poderia
ser poss@'{i}vel usar a fun@value{cedilha}@~{a}o sobre a express@~{a}o inteira devido a uma
exaust@~{a}o de espa@value{cedilha}o da lista de armazenamento no decorrer da computa@value{cedilha}@~{a}o.

@c IN THESE EXAMPLES, SPELL OUT WHAT IS THE MAIN OPERATOR 
@c AND SHOW HOW THE RESULT FOLLOWS FROM THE DESCRIPTION STATED IN THE FIRST PARAGRAPH
@example
(%i1) map(f,x+a*y+b*z);
(%o1)                        f(b z) + f(a y) + f(x)
(%i2) map(lambda([u],partfrac(u,x)),x+1/(x^3+4*x^2+5*x+2));
                           1       1        1
(%o2)                     ----- - ----- + -------- + x
                         x + 2   x + 1          2
                                         (x + 1)
(%i3) map(ratsimp, x/(x^2+x)+(y^2+y)/y);
                                      1
(%o3)                            y + ----- + 1
                                    x + 1
(%i4) map("=",[a,b],[-0.5,3]);
(%o4)                          [a = - 0.5, b = 3]


@end example
@end deffn

@deffn {Fun@value{cedilha}@~{a}o} mapatom (@var{expr})
Retorna @code{true} se e somente se @var{expr} for tratada pelas rotinas de
mapeamento como um @'{a}tomo.  "Mapatoms" s@~{a}o @'{a}tomos, n@'{u}meros
(inclu@'{i}ndo n@'{u}meros racioanais), e vari@'{a}veis subscritas.
@c WHAT ARE "THE MAPPING ROUTINES", AND WHY DO THEY HAVE A SPECIALIZED NOTION OF ATOMS ??

@end deffn

@c NEEDS CLARIFICATION
@defvr {Vari@'{a}vel de op@value{cedilha}@~{a}o} maperror
Valor padr@~{a}o: @code{true}

Quando @code{maperror} @'{e} @code{false}, faz com que todas as fun@value{cedilha}@~{o}es mapeadas, por exemplo

@example
map (f, @var{expr_1}, @var{expr_2}, ...)
@end example

para (1) parar quando elas terminarem
retornando a menor @var{exp_i} se n@~{a}o forem todas as @var{exp_i} do mesmo
comprimento e (2) aplique @code{f} a @code{[@var{expr_1}, @var{expr_2}, ...]} se @code{expr_i} n@~{a}o forem todas
do mesmo tipo de objeto.

Se @code{maperror} for @code{true} ent@~{a}o uma ,mensagem de erro
@'{e} mostrada nas duas inst@^{a}ncias acima.

@end defvr

@c NEEDS CLARIFICATION
@deffn {Fun@value{cedilha}@~{a}o} maplist (@var{f}, @var{expr_1}, ..., @var{expr_n})
Retorna uma lista de aplica@value{cedilha}@~{o}es de @var{f}
em todas as partes das express@~{o}es @var{expr_1}, ..., @var{expr_n}.
@var{f} @'{e} o nome de uma fun@value{cedilha}@~{a}o, ou uma express@~{a}o lambda.

@code{maplist} difere de @code{map (@var{f}, @var{expr_1}, ..., @var{expr_n})}
que retorna uma express@~{a}o com o mesmo operador principal que @var{expr_i} tem
(exceto para simplifica@value{cedilha}@~{o}es  e o caso onde @code{map} faz um @code{apply}).

@end deffn

@c NEEDS CLARIFICATION
@defvr {Vari@'{a}vel de op@value{cedilha}@~{a}o} prederror
Valor padr@~{a}o: @code{true}

Quando @code{prederror} for @code{true}, uma mensagem de erro @'{e} mostrada
sempre que o predicado de uma declara@value{cedilha}@~{a}o @code{if} ou uma fun@value{cedilha}@~{a}o @code{is} falha em
avaliar ou para @code{true} ou para  @code{false}.

Se @code{false}, @code{unknown} @'{e} retornado
no lugar nesse caso.  O modo @code{prederror: false} n@~{a}o @'{e} suportado no
c@'{o}digo traduzido;
todavia, @code{maybe} @'{e} suportado no c@'{o}digo traduzido.

Veja tamb@'{e}m @code{is} e @code{maybe}.

@end defvr

@deffn {Fun@value{cedilha}@~{a}o} return (@var{valor})
Pode ser usada para sair explicitamente de um bloco, levando
seu argumento.  Veja @code{block} para mais informa@value{cedilha}@~{a}o.

@end deffn

@c NEEDS CLARIFICATION
@deffn {Fun@value{cedilha}@~{a}o} scanmap (@var{f}, @var{expr})
@deffnx {Fun@value{cedilha}@~{a}o} scanmap (@var{f}, @var{expr}, bottomup)
Recursivamente aplica @var{f} a @var{expr}, de cima
para baixo.  Isso @'{e} muito @'{u}til quando uma fatora@value{cedilha}@~{a}o completa @'{e}
desejada, por exemplo:

@example
(%i1) exp:(a^2+2*a+1)*y + x^2$
(%i2) scanmap(factor,exp);
                                    2      2
(%o2)                         (a + 1)  y + x
@end example

Note o caminho atrav@'{e}s do qual @code{scanmap} aplica a dada fun@value{cedilha}@~{a}o @code{factor} para as
subexpress@~{o}es constituintes de @var{expr}; se outra forma de @var{expr} @'{e} apresentada
para @code{scanmap} ent@~{a}o o resultado pode ser diferente.  Dessa forma, @code{%o2} n@~{a}o @'{e}
recuperada quando @code{scanmap} @'{e} aplicada para a forma expandida de @var{exp}:

@example
(%i3) scanmap(factor,expand(exp));
                           2                  2
(%o3)                      a  y + 2 a y + y + x
@end example

Aqui est@'{a} um outro exemplo do caminho no qual @code{scanmap} aplica
recursivamente uma fun@value{cedilha}@~{a}o dada para todas as subexpress@~{o}es, incluindo expoentes:

@example
(%i4) expr : u*v^(a*x+b) + c$
(%i5) scanmap('f, expr);
                    f(f(f(a) f(x)) + f(b))
(%o5) f(f(f(u) f(f(v)                      )) + f(c))
@end example

@code{scanmap (@var{f}, @var{expr}, bottomup)} aplica @var{f} a @var{expr} de
baixo para cima.  E.g., para @code{f} indefinida,

@example
scanmap(f,a*x+b) ->
   f(a*x+b) -> f(f(a*x)+f(b)) -> f(f(f(a)*f(x))+f(b))
scanmap(f,a*x+b,bottomup) -> f(a)*f(x)+f(b)
    -> f(f(a)*f(x))+f(b) ->
     f(f(f(a)*f(x))+f(b))
@end example

Nesse caso, voc@^{e} pega a mesma resposta em ambos os
caminhos.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} throw (@var{expr})
Avalia @var{expr} e descarta o valor retornado para o mais recente
@code{catch}.  @code{throw} @'{e} usada com @code{catch} como um mecanismo de retorno
n@~{a}o local.

@end deffn

@c NEED MORE HERE !!
@c AT LEAST SHOULD LIST ACCEPTABLE VARIANTS
@deffn {Operador especial} while
Veja @code{do}.

@end deffn

@deffn {Fun@value{cedilha}@~{a}o} outermap (@var{f}, @var{a_1}, ..., @var{a_n})
Aplica a fun@value{cedilha}@~{a}o @var{f} para cada um dos elementos do produto externo
@var{a_1} vezes @var{a_2} ... vezes @var{a_n}.

@var{f} @'{e} o nome de uma fun@value{cedilha}@~{a}o de @math{n} argumentos
ou uma express@~{a}o lambda de @math{n} argumentos.
Cada argumento @var{a_k} pode ser uma lista simples ou lista aninhada ( lista contendo listas como elementos ), ou uma matrz, ou qualquer outro tip de express@~{a}o.

O valor de retorno de @code{outermap} @'{e} uma estrutura aninhada.
Tomemos @var{x} como sendo o valor de retorno.
Ent@~{a}o @var{x} tem a mesma estrutura da primeira lista, lista aninhada, ou argumento matriz,
@code{@var{x}[i_1]...[i_m]} tem a mesma estrutura que a segunda lista, lista aninhada, ou argumento matriz,
@code{@var{x}[i_1]...[i_m][j_1]...[j_n]} tem a mesma estrutura que a terceira lista, lista aninhada, ou argumento matriz,
e assim por diante,
onde @var{m}, @var{n}, ... s@~{a}o os n@'{u}meros dos @'{i}ndices requeridos para acessar os
elementos de cada argumento (um para uma lista, dois para uma matriz, um ou mais para uma lista aninhada).
Argumentos que n@~{a}o forem listas ou matrizes n@~{a}o afetam a estrutura do valor de retorno.

Note que o efeito de @code{outermap} @'{e} diferente daquele de aplicar @var{f}
a cada um dos elementos do produto externo retornado por @code{cartesian_product}.
@code{outermap} preserva a estrutura dos argumentos no valor de retorno,
enquanto @code{cartesian_product} n@~{a}o reserva essa mesma estrutura.

@code{outermap} avalia seus argumentos.

Veja tamb@'{e}m @code{map}, @code{maplist}, e @code{apply}.
@c CROSS REF OTHER FUNCTIONS HERE ??

Exemplos:
Exemplos elementares de @code{outermap}.
Para mostrar a a combina@value{cedilha}@~{a}o de argumentos mais claramente, @code{F} est@'{a} indefinida @`a esquerda.

@c ===beg===
@c outermap (F, [a, b, c], [1, 2, 3]);
@c outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
@c outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
@c outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
@c outermap ("+", [a, b, c], [1, 2, 3]);
@c ===end===
@example
(%i1) outermap (F, [a, b, c], [1, 2, 3]);
(%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)], 
                                     [F(c, 1), F(c, 2), F(c, 3)]]
(%i2) outermap (F, matrix ([a, b], [c, d]), matrix ([1, 2], [3, 4]));
         [ [ F(a, 1)  F(a, 2) ]  [ F(b, 1)  F(b, 2) ] ]
         [ [                  ]  [                  ] ]
         [ [ F(a, 3)  F(a, 4) ]  [ F(b, 3)  F(b, 4) ] ]
(%o2)    [                                            ]
         [ [ F(c, 1)  F(c, 2) ]  [ F(d, 1)  F(d, 2) ] ]
         [ [                  ]  [                  ] ]
         [ [ F(c, 3)  F(c, 4) ]  [ F(d, 3)  F(d, 4) ] ]
(%i3) outermap (F, [a, b], x, matrix ([1, 2], [3, 4]));
       [ F(a, x, 1)  F(a, x, 2) ]  [ F(b, x, 1)  F(b, x, 2) ]
(%o3) [[                        ], [                        ]]
       [ F(a, x, 3)  F(a, x, 4) ]  [ F(b, x, 3)  F(b, x, 4) ]
(%i4) outermap (F, [a, b], matrix ([1, 2]), matrix ([x], [y]));
       [ [ F(a, 1, x) ]  [ F(a, 2, x) ] ]
(%o4) [[ [            ]  [            ] ], 
       [ [ F(a, 1, y) ]  [ F(a, 2, y) ] ]
                              [ [ F(b, 1, x) ]  [ F(b, 2, x) ] ]
                              [ [            ]  [            ] ]]
                              [ [ F(b, 1, y) ]  [ F(b, 2, y) ] ]
(%i5) outermap ("+", [a, b, c], [1, 2, 3]);
(%o5) [[a + 1, a + 2, a + 3], [b + 1, b + 2, b + 3], 
                                           [c + 1, c + 2, c + 3]]
@end example

Uma explana@value{cedilha}@~{a}o final do valor de retorno de @code{outermap}.
Os argumentos primeiro, segundo, e terceiro s@~{a}o matriz, lista, e matriz, respectivamente.
O valor de retorno @'{e} uma matriz.
Cada elementos daquela matriz @'{e} uma lista,
e cada elemento de cada lista @'{e} uma matriz.

@c ===beg===
@c arg_1 :  matrix ([a, b], [c, d]);
@c arg_2 : [11, 22];
@c arg_3 : matrix ([xx, yy]);
@c xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1, arg_2, arg_3);
@c xx_1 : xx_0 [1][1];
@c xx_2 : xx_0 [1][1] [1];
@c xx_3 : xx_0 [1][1] [1] [1][1];
@c [op (arg_1), op (arg_2), op (arg_3)];
@c [op (xx_0), op (xx_1), op (xx_2)];
@c ===end===
@example
(%i1) arg_1 :  matrix ([a, b], [c, d]);
                            [ a  b ]
(%o1)                       [      ]
                            [ c  d ]
(%i2) arg_2 : [11, 22];
(%o2)                       [11, 22]
(%i3) arg_3 : matrix ([xx, yy]);
(%o3)                      [ xx  yy ]
(%i4) xx_0 : outermap (lambda ([x, y, z], x / y + z), arg_1, arg_2, arg_3);
               [  [      a        a  ]  [      a        a  ]  ]
               [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
               [  [      11       11 ]  [      22       22 ]  ]
(%o4)  Col 1 = [                                              ]
               [  [      c        c  ]  [      c        c  ]  ]
               [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
               [  [      11       11 ]  [      22       22 ]  ]
                 [  [      b        b  ]  [      b        b  ]  ]
                 [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                 [  [      11       11 ]  [      22       22 ]  ]
         Col 2 = [                                              ]
                 [  [      d        d  ]  [      d        d  ]  ]
                 [ [[ xx + --  yy + -- ], [ xx + --  yy + -- ]] ]
                 [  [      11       11 ]  [      22       22 ]  ]
(%i5) xx_1 : xx_0 [1][1];
           [      a        a  ]  [      a        a  ]
(%o5)     [[ xx + --  yy + -- ], [ xx + --  yy + -- ]]
           [      11       11 ]  [      22       22 ]
(%i6) xx_2 : xx_0 [1][1] [1];
                      [      a        a  ]
(%o6)                 [ xx + --  yy + -- ]
                      [      11       11 ]
(%i7) xx_3 : xx_0 [1][1] [1] [1][1];
                                  a
(%o7)                        xx + --
                                  11
(%i8) [op (arg_1), op (arg_2), op (arg_3)];
(%o8)                  [matrix, [, matrix]
(%i9) [op (xx_0), op (xx_1), op (xx_2)];
(%o9)                  [matrix, [, matrix]
@end example

@code{outermap} preserves the structure of the arguments in the return value,
while @code{cartesian_product} does not.

@c ===beg===
@c outermap (F, [a, b, c], [1, 2, 3]);
@c setify (flatten (%));
@c map (lambda ([L], apply (F, L)), cartesian_product ({a, b, c}, {1, 2, 3}));
@c is (equal (%, %th (2)));
@c ===end===
@example
(%i1) outermap (F, [a, b, c], [1, 2, 3]);
(%o1) [[F(a, 1), F(a, 2), F(a, 3)], [F(b, 1), F(b, 2), F(b, 3)], 
                                     [F(c, 1), F(c, 2), F(c, 3)]]
(%i2) setify (flatten (%));
(%o2) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3), 
                                       F(c, 1), F(c, 2), F(c, 3)@}
(%i3) map (lambda ([L], apply (F, L)), cartesian_product (@{a, b, c@}, @{1, 2, 3@}));
(%o3) @{F(a, 1), F(a, 2), F(a, 3), F(b, 1), F(b, 2), F(b, 3), 
                                       F(c, 1), F(c, 2), F(c, 3)@}
(%i4) is (equal (%, %th (2)));
(%o4)                         true
@end example

@end deffn
