ASORT()
 Ordena os elementos de um vetor
------------------------------------------------------------------------------

 Sintaxe

     ASORT(<aDestino>, [<nInicio>],
        [<nCont>], [<bOrdem>]) --> aDestino

 Argumentos

     <aDestino> é o vetor cujos elementos serao colocados em ordem.

     <nInicio> é o primeiro dos elementos que serao colocados em ordem.
     Caso nao seja especificada, a posiçao inicial assumida é um.

     <nCont> é a quantidade de elementos que serao colocados em ordem.
     Se nao for especificada, todos os elementos no vetor que começam com o
     elemento inicial sao ordenados.

     <bOrdem> é um bloco de código opcional utilizado para determinar
     qual a ordem que será seguida.  Caso nao seja especificada, a ordem
     padrao é ascendente.

 Retorno

     ASORT() retorna uma referência ao vetor <aDestino>.

 Descriçao

     ASORT() é uma funçao de vetor que coloca em ordem todo ou parte de um
     vetor que contém elementos de um único tipo de dados.  Os tipos de
     dados que podem ser ordenados incluem caractere, data, lógico e
     numérico.

     Se o argumento <bOrdem> nao for especificado, a ordem padrao é
     ascendente.  Elementos com valores baixos sao colocados no início do
     vetor (primeiro elemento), enquanto elementos com valores altos sao
     colocados no final do vetor (último elemento).

     Caso o argumento de bloco <bOrdem> seja especificado, ele é utilizado
     para determinar a ordem em que os elementos serao colocados.  Cada vez
     que o bloco é avaliado, dois elementos do vetor destino sao passados
     como parâmetros de bloco.  O bloco deve retornar verdadeiro (.T.) se os
     elementos estiverem ordenados.  Isto pode ser usado para criar uma
     ordem descendente ou de dicionário.  Veja os exemplos abaixo.

     Quando ordenadas, as cadeias de caracteres sao colocadas na sequência
     ASCII; valores lógicos sao ordenados com falso (.F.) sendo considerado
     o valor menor; valores data sao ordenados cronologicamente; e numéricos
     sao ordenados por magnitude.

     -----------------------------------------------------------------------
     . Nota

     Sendo os vetores multi-dimensionais em Clipper implementados através do
     aninhamento de sub-vetores dentro de outros vetores, ASORT() nao ordena
     diretamente vetores deste tipo.  Para ordenar um vetor aninhado, você
     deve fornecer um bloco de código que dará o tratamento adequado aos
     sub-vetores.
     -----------------------------------------------------------------------

 Exemplos

       Este exemplo cria um vetor de 5 elementos nao ordenados.
        ordena o vetor de forma ascendente, e depois em ordem descendente
        utilizando um bloco de código:

        aArray := { 3, 5, 1, 2, 4 }
        ASORT(aArray)                         // Resulta: { 1, 2, 3, 4, 5 }
        ASORT(aArray,,, { |x, y| x > y })     // Resulta: { 5, 4, 3, 2, 1 }

       Este exemplo coloca um vetor de cadeia de caracteres em ordem
        ascendente, sem importar se há letras maiúsculas ou minúsculas.
        Isto é feito através de um bloco de código que converte os elementos
        para letras maiúsculas antes de serem comparados:

        aArray := { "Fred", Kate", "ALVIN", "friend" }
        ASORT(aArray,,, { |x, y| UPPER(x) < UPPER(y) })

       Este exemplo coloca em ordem um vetor aninhado utilizando o
        segundo elemento de cada sub-vetor:

        aKids := { {"Mary", 14}, {"Joe", 23}, {"Art", 16} }
        aSortKids := ASORT(aKids,,, { |x, y| x[2] < y[2] })

        Resulta:

        { {"Mary", 14}, {"Art", 16}, {"Joe", 23} }

 Arquivos:  Biblioteca EXTEND.LIB.
 To download this example - click here.

See Also: ASCAN() EVAL() SORT