CurrencyFormatter  - AS3

O nome do ID da localidade real usado por este objeto de CurrencyFormatter.

Há três possibilidades para o valor do nome, dependendo do sistema operacional e do valor do parâmetro requestedLocaleIDName passado para o construtor CurrencyFormatter().

1. Se o idioma solicitado não for LocaleID.DEFAULT e o sistema operacional oferecer suporte para o idioma solicitado, o nome retornado será o mesmo da propriedade requestedLocaleIDName.
2. Se LocaleID.DEFAULT foi usado como o valor do parâmetro requestedLocaleIDName para o construtor, o nome do idioma atual especificado pelo sistema operacional do usuário será usado. O valor LocaleID.DEFAULT preserva a configuração personalizada do usuário no sistema operacional. Observe que a passagem de um valor explícito como o parâmetrorequestedLocaleIDName não tem necessariamente o mesmo resultado que o uso de LocaleID.DEFAULT, mesmo que os dois nomes de ID de idioma sejam iguais. O usuário poderia ter personalizado as configurações de local na máquina dele e, ao solicitar um nome de ID de local explícito em vez de usar LocaleID.DEFAULT, o aplicativo não recuperaria as configurações personalizadas.
3. Se o sistema não suporta o requestedLocaleIDName especificado no construtor, é fornecido um nome de ID de local de retrocesso.

Elementos da API relacionados

O código monetário ISO 4217 com três letras referente ao local real que está sendo usado.

Este código será usado para determinar o símbolo de moeda ou a string ao formatar valores de moeda usando o método format() com o parâmetro withCurrencySymbol definido como false.

Esta propriedade é inicializada pelo construtor com base na localidade real que é usada. Quando um idioma de retorno for usado, esta propriedade refletirá o código de moeda padrão preferencial do idioma de retorno.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O símbolo de moeda ou string da localidade real que é usada.

Este código será usado para determinar o símbolo de moeda ou a string ao formatar valores de moeda usando o método format() com o parâmetro withCurrencySymbol definido como true.

Esta propriedade é inicializada pelo construtor com base na localidade real que é usada. Quando um idioma de retorno for usado, esta propriedade refletirá o código de moeda padrão preferencial do idioma de retorno.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O caractere de separador decimal usado para formatar ou analisar montantes monetários que têm uma parte decimal.

Esta propriedade é inicialmente estabelecida com base na localidade que é selecionada quando o objeto de formatter é construído.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

Define o conjunto de caracteres de dígitos usados ao formatar valores monetários.

Idiomas e regiões diferentes usam cojuntos de caracteres diferentes para representar os dígitos de 0 a 9. Esta propriedade define o conjunto de dígitos a serem usados.

O valor desta propriedade representa o valor Unicode do dígito nulo de um conjunto de dígitos decimais. Os valores válidos desta propriedade são definidos na classe NationalDigitsType.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O número máximo de dígitos que podem aparecer depois do separador decimal.

Os números serão arredondados para o número de dígitos especificados por esta propriedade. O esquema de arredondamento varia de acordo com o sistema operacional do usuário.

Quando a propriedade trailingZeros é definida como true, a porção fracionária do número (depois do ponto decimal) será preenchida com zeros à direita até que o seu comprimento corresponda ao valor desta propriedade fractionalDigits.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é 0.

Elementos da API relacionados

Descreve o posicionamento dos separadores de agrupamento dentro da string de montante monetário formatada.

Quando a propriedade useGrouping é definida como true, a propriedade groupingPattern é usada para definir a posição e o padrão usados pelo separador de agrupamento.

O padrão de agrupamento é definido como uma string que contém números separados por pontos-e-vírgulas e, opcionalmente, pode terminar com um asterisco. Por exemplo: "3;2;*". Cada número da string representa a quantidade de dígitos de um grupo. O separador de agrupamento é posicionado antes de cada grupo de dígitos. Um asterisco no fim da string indica que os grupos com aquele número de dígitos devem ser repetidos para o resto da string formatada. Se não houver nenhum asterisco, não haverá nenhum grupo adicional ou separadores para o resto da string formatada.

O primeiro número da string corresponde ao primeiro grupo de dígitos à esquerda do separador decimal. Os números subsequentes definem a quantidade de dígitos nos grupos subsequentes à esquerda. Assim a string "3; 2; *" indica que um separador de agrupamento é inserido depois do primeiro grupo de 3 dígitos, seguidos por grupos de 2 dígitos. Por exemplo: 98,76,54,321

A seguinte tabela mostra exemplos de formatação do valor de moeda 123456789.12 com vários padrões de agrupamento. O separador de agrupamento é uma vírgula, o separador decimal é um ponto, e um sinal de cifrão ($) é o símbolo de moeda.

Só um número limitado de tamanhos de agrupamento pode ser definido. Em alguns sistemas operacionais, os padrões de agrupamento só podem conter dois números e um asterisco. Outros sistemas operacionais podem dar suporte a até quatro números e um asterisco. Para padrões sem um asterisco, alguns sistemas operacionais só suportam um número enquanto os outros suportam até três números. Se o número máximo de elementos de agrupamento padrão for excedido, então os elementos adicionais não serão ignorados e a propriedade lastOperationStatus será definida como descrito abaixo.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Elementos da API relacionados

O caractere ou a string usados para o separador de agrupamento.

O valor desta propriedade é usado como sob o separador que se agrupa formatando quantidades de moeda quando o useGrouping a propriedade é definida como true. Esta propriedade é inicialmente estabelecida com base na localidade que é selecionada quando o objeto de formatter é construído.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O status da operação mais recente que este objeto CurrencyFormatter executou. A propriedade lastOperationStatus será definida sempre que o construtor ou um método desta classe forem chamados ou sempre que outra propriedade for definida. Para ver os valores possíveis, consulte a descrição de cada método.

Elementos da API relacionados

Especifica se um zero à esquerda estará incluído em um número formatado quando não houver nenhum dígito de número inteiro à esquerda do separador decimal.

Quando esta propriedade é definida como true, é incluído um zero à esquerda do separador decimal ao formatar valores numéricos entre -1.0 e 1.0. Quando esta propriedade é definida como false, não se inclui o zero à esquerda.

Por exemplo se a quantidade da moeda for 0,321 e esta propriedade for definida como true, o zero à esquerda estará incluído na string formatada. Se a propriedade for definida como false, o zero à esquerda não será incluído. Neste caso, a cadeia incluiria somente o separador decimal seguido pelos dígitos decimais, como $.321.

A seguinte tabela mostra exemplos de como os valores de moeda são formatados com base nos valores desta propriedade e as propriedades relacionadas fractionalDigits e trailingZeros.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

Um valor numérico que indica um padrão de formatação para valores negativos de moeda. Este padrão define o local do símbolo de moeda e o símbolo negativo ou parênteses em relação à porção numérica do valor da moeda.

O valor desta propriedade deve ser uma das constantes definidas na tabela abaixo.

A tabela abaixo resume os padrões de formato possíveis de valores de moeda negativos. Quando um montante monetário é formatado com o método format():

• O símbolo "¤" é substituído pelo valor da propriedade currencyISOCode ou currencySymbol, dependendo do valor do parâmetro withCurrencySymbol passado ao método format();
• O caractere '-' é substituído pelo valor da propriedade negativeNumberSymbol;
• O caractere "n" é substituído pelo valor de moeda que é passado para o método format().

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O símbolo de negativo usado ao formatar valores monetários negativos.

Este símbolo será usado em conjunto com o formato de moeda negativo ao formatar um valor de moeda menor que zero. Não é usado em formatos de moeda negativos que não incluem um sinal de negativo (p. ex. quando valores de moeda negativos ficarem entre parênteses).

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

Um valor numérico que indica um padrão de formatação para valores monetários positivos. Este formato define o local do símbolo de moeda quanto à porção numérica do valor da moeda.

O valor desta propriedade deve ser uma das constantes definidas na tabela abaixo.

A tabela abaixo resume os padrões de formato possíveis de valores de moeda positivos. Quando um montante monetário é formatado com o método format():

• O símbolo "¤" é substituído pelo valor da propriedade currencyISOCode ou currencySymbol, dependendo do valor do parâmetro withCurrencySymbol passado ao método format();
• O caractere "n" é substituído pelo valor de moeda que é passado para o método format().

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

O nome do ID de localidade solicitado que foi passado ao construtor deste objeto CurrencyFormatter.

Se o valor LocaleID.DEFAULT tiver sido usado, então o nome retornado será "i-default". A localidade real usada pode diferenciar-se da localidade solicitada quando uma localidade de retorno é aplicada. É possível recuperar nome do local real pode ser recuperado usando o actualLocaleIDName propriedade.

Elementos da API relacionados

Especifica se os zeros à direita serão incluídos no valor monetário formatado.

Quando esta propriedade é definida como true, os zeros à direita são incluídos na parte fracionária do número formatado, até o limite especificado pela propriedade fractionalDigits. Quando esta propriedade é definida como false, nenhum zero à direita será exibido.

Por exemplo, se a quantidade de moeda for 123.4, e esta propriedade for definida como verdadeira, e a propriedade fractionalDigits for definida como 3, a cadeia formatada mostraria zeros à direita, como $123.400. Se esta propriedade for false, os zeros à direita não serão incluídos, e a string mostrará somente o separador decimal seguido pelos dígitos decimais diferentes de zero, como $123.4.

A seguinte tabela mostra exemplos de como as quantidades de moeda são formatadas com base nos valores desta propriedade e as propriedades fractionalDigits e leadingZero propriedades.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

O valor padrão é dependent on the actual locale and operating system.

Elementos da API relacionados

Ativa o uso do separador de agrupamento ao formatar montantes monetários.

Quando a propriedade useGrouping é definida como true, os dígitos são agrupados e delimitados pelo caractere de separador de agrupamento. Por exemplo, $123,456,789

Quando a propriedade useGrouping é definida como false, os dígitos não são agrupados ou separados. Por exemplo, $123456789

A propriedade groupingSeparator define o símbolo a ser usado como um separador de agrupamento. A propriedade groupingPattern define o número de dígitos entre os separadores de agrupamento.

Quando um valor é atribuído a esta propriedade e não há erros nem avisos, a propriedade lastOperationStatus é definida como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Elementos da API relacionados

Constrói um novo objeto de CurrencyFormatter para formatar números que representam quantidades de moeda segundo as convenções de um determinado local.

Este construtor determinará se o sistema operacional atual suporta o local o nome de ID de localidade solicitado. Se não suportar, será usado um idioma de retorno. Se um idioma de retorno for usado, a propriedade lastOperationStatus indicará o tipo de retorno, e a propriedade actualLocaleIDName conterá o nome do ID do idioma de retorno.

Certas propriedades, tais como as propriedades currencySymbol e currencyISOCode serão definidas automaticamente com base no idioma.

OBSERVAÇÃO: Quando uma localidade de emergência é usada, as propriedades da moeda são definidas par aos valores padrão e, portanto, as propriedades currencySymbol ou currencyISOCode poderão receber valores inesperados. É recomendável examinar os valores de propriedade currencySymbol e currencyISOCode antes de formatar um valor em moeda.

Para formatar de acordo com as preferências de sistema operacional atuais do usuário, passe o valor LocaleID.DEFAULT no parâmetro requestedLocaleIDName para o construtor.

Quando o construtor é invocado e conclui com sucesso, a propriedade lastOperationStatus é configurada como:

• LastOperationStatus.NO_ERROR

Quando o nome de ID de local solicitado não está disponível, lastOperationStatus é configurado como uma das alternativas a seguir:

• LastOperationStatus. USING_FALLBACK_WARNING
• LastOperationStatus. USING_DEFAULT_WARNING

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Para ver detalhes sobre os avisos citados acima e outros valores possíveis da propriedade lastOperationStatus, consulte as descrições na classe LastOperationStatus.

Elementos da API relacionados

Cria uma string que representa uma quantidade monetária formatada segundo as propriedades atuais deste objeto CurrencyFormatter, inclusive a localidade, símbolo de moeda e código ISO de moeda.

Por padrão, este método usa a propriedade currencyISOCode para determinar o símbolo de moeda e outras configurações usadas na formatação.

Muitos países e regiões usam os mesmos símbolos de moeda para moedas diferentes. Por exemplo os Estados Unidos, a Austrália, a Nova Zelândia, o Canadá e o México usam o mesmo símbolo de cifrão ($) de valores de moeda locais. Quando a formatação da moeda for diferente da moeda local do usuário, normalmente será melhor usar o código ISO como a string da moeda. Você pode usar o método formattingWithCurrencySymbolIsSafe() para testar se o código de ISO da moeda a ser formatado corresponde à propriedade currencyISOCode do formatador.

Este método pode formatar números de magnitudes muito grandes e muito pequenas. Contudo o número de dígitos significativos é limitado à precisão fornecida pelo tipo de dados Número.

Parâmetros

Elementos da API relacionados

 
         var cf:CurrencyFormatter = new CurrencyFormatter("fr-CA");  
         
         trace(cf.actualLocaleIDName);               // "fr-CA"  
         trace(cf.currencyISOCode);                // "CAD"
         trace(cf.currencySymbol);                // "$"
         
         trace(cf.format(1254.56));                // "1 254,56 CAD"
         trace(cf.format(1254.56, true));            // "1 254,56 $"
         

 
         var cf:CurrencyFormatter = new CurrencyFormatter(LocaleID.DEFAULT);  
         
         if (cf.formattingWithCurrencySymbolIsSafe("CAD")) {
           trace(cf.actualLocaleIDName);     // "fr-CA French (Canada)"
           trace(cf.format(1254.56, false)); // "1 254,56 $"
         }
         else {
           trace(cf.actualLocaleIDName);     // "en-US English (USA)"
           cf.setCurrency("CAD", "C$")
           trace(cf.format(1254.56, true));  // "C$ 1,254.56"
         }
         

Determina se o símbolo de moeda especificado atualmente pode ser usado ao formatar valores monetários.

Muitas regiões e países usam os mesmos símbolos de moeda. Este método pode ser usado para proteger contra o uso de um símbolo de moeda ambíguo, ou um símbolo de moeda ou código ISO diferente do esperado devido ao uso de uma localidade de retorno.

Um caso de uso comum deste método é determinar se é preciso mostrar um símbolo de moeda local (se a quantidade será formatada na moeda padrão do usuário), ou uma string de código de ISO mais específica (se a quantidade será formatada em uma moeda diferente do padrão do usuário).

Este método compara-se o requestedISOCode parâmetro contra a corrente currencyISOCode propriedade, voltando true se os cadeias são iguais e false se eles não são. Quando as strings são iguais, usar o método format() com o conjunto de parâmetros withCurrencySymbol definido como true resulta em uma string de valor de moeda formatada com um símbolo de moeda exclusivo do idioma. Se este método retornar false, o uso do método format() com o parâmetro withCurrencySymbol definido como verdadeiro poderá resultar no uso de um símbolo de moeda incorreto ou ambíguo.

Quando este método é invocado e conclui com sucesso, a propriedade lastOperationStatus é configurada como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Parâmetros

Elementos da API relacionados

Lista todos os nomes de ID de local suportados por essa classe.

Se esta classe não for suportada no sistema operacional atual, este método retornará um valor nulo.

Quando este método é invocado e conclui com sucesso, a propriedade lastOperationStatus é configurada como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Analisa uma string em um montante monetário e símbolo de moeda.

O algoritmo de análise usa o valor da propriedade decimalSeparator para determinar a porção integral e fracionária do número. Ele usa os valores das propriedades negativeCurrencyFormat e positiveCurrencyFormat para determinar o local do símbolo de moeda ou cadeia relacionada ao valor da moeda. Para quantidades negativas, o valor da propriedade negativeCurrencyFormat determina o local do símbolo de negativo e se os parênteses serão usados.

Se a ordem do símbolo de moeda, sinal de subtração e número na string de entrada não corresponderem ao padrão identificado pelas propriedadesnegativeCurrencyFormat e positiveCurrencyFormat, então:

1. A propriedade value do objeto CurrencyParseResult retornado será definida como NaN.
2. A propriedade currencyString do objeto CurrencyParseResult retornado será definida como null.
3. A propriedade lastOperationStatus será definida para indicar que a análise foi reprovada.

A string de entrada pode incluir caracteres de espaço, que serão ignorados durante a análise.

A análise pode ter sucesso mesmo se não houver nenhum símbolo de moeda. Nenhuma validação é feita da parte da cadeia correspondente ao símbolo de moeda. Se não houver nenhum símbolo de moeda ou string, a propriedade currencyString no objeto CurrencyParseResult devolvido será definida como uma string vazia.

Quando este método é invocado e conclui com sucesso, a propriedade lastOperationStatus é configurada como:

• LastOperationStatus.NO_ERROR

Do contrário, a propriedade lastOperationStatus é configurada como uma das constantes definidas na classe LastOperationStatus.

Parâmetros

Elementos da API relacionados

Define as propriedades currencyISOCode e currencySymbol propriedades do objeto CurrencyFormatter.

Quando este método é invocado e conclui com sucesso, a propriedade lastOperationStatus é configurada como:

• LastOperationStatus.NO_ERROR

Caso contrário, as propriedades currencyISOCode e currencySymbol não são modificadas e a propriedade lastOperationStatus é definida como uma das constantes definidas na classe LastOperationStatus.

Parâmetros

Elementos da API relacionados

Este exemplo usa as seguintes localidades:

• A localidade padrão do sistema operacional para formatação de moeda (LocaleID.DEFAULT)
• Japonês (Japão)
• Inglês (EUA)
• Francês (França)

O exemplo realiza o seguinte para cada idioma na lista:

1. Cria um objeto CurrencyFormatter
2. Usa o método formattingWithCurrencySymbolIsSafe() para verificar se a moeda padrão da localidade é Euros ("EUR") e se ele formata a string que usa o símbolo de moeda. De outra maneira, ele formata a string que usa o código ISO.

  
package {
    import flash.display.Sprite;
    import flash.globalization.CurrencyFormatter;
    import flash.globalization.LocaleID;
    
    public class CurrencyFormatterExample1 extends Sprite
    {
        public function CurrencyFormatterExample1():void
        {
            var cf:CurrencyFormatter;
            var amountWithSymbol:String;
            var amountWithISOCode:String
            
            var localeNames:Array = [LocaleID.DEFAULT, "ja-JP", "en-US", "fr-FR"];
            
            for each (var localeName:String in localeNames) 
            {
                cf = new CurrencyFormatter(localeName);
                
                trace('\n' + "LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                
                trace("Last Operation Status: " + cf.lastOperationStatus );
                
                trace("Currency ISO Code: " + cf.currencyISOCode);
                
                if (cf.formattingWithCurrencySymbolIsSafe("EUR")) 
                {
                    amountWithSymbol = cf.format(123456789.19, true);
                    trace("Format using Symbol: "+ amountWithSymbol);
                }
                else 
                {
                    amountWithISOCode = cf.format(123456789.19); 
                    trace("Format using ISO Code: " + amountWithISOCode);
                }
            }
        }
    }
}

Este exemplo toma as seguintes medidas:

1. Cria um objeto CurrencyFormatter da localidade para o inglês (dos Estados Unidos).
2. Usa o método parse() para analisar a string de entrada.
3. Exibe os valores da string de quantidade e moeda do objeto CurrencyParseResult resultante.

 
package {
      import flash.display.Sprite;
      import flash.globalization.CurrencyFormatter;
      import flash.globalization.CurrencyParseResult;
      import flash.globalization.LastOperationStatus;
      import flash.globalization.LocaleID;

      public class CurrencyFormatterParseExample extends Sprite
      {
            public function CurrencyFormatterParseExample()
            {
                var cf:CurrencyFormatter = new CurrencyFormatter( "en_US" );
                
                trace("LocaleID requested=" + cf.requestedLocaleIDName 
                    + "; actual=" + cf.actualLocaleIDName);
                trace("Last Operation Status: " + cf.lastOperationStatus );

                var inputString:String = "Dollar 123,567,89,0.254";
                
                var result:CurrencyParseResult = cf.parse(inputString);
                
                if (cf.lastOperationStatus == LastOperationStatus.NO_ERROR ) {
                    trace("Amount value: " + result.value); 
                    trace("Currency string: " + result.currencyString); 
                }
            }
      }
}