nginstack(require("@nginstack/engine/lib/string/toFormattedString"))(value, format)
Converte um valor numérico ou uma data para uma string, aplicando uma máscara de formatação.
Este método implementa o mesmo comportamento do método toString() do runtime JavaScript Ije
quando informado o parâmetro adicional de formatação, parâmetro esse uma extensão
implementada apenas nesse runtime, que não faz parte da especificação do ECMAScript.
Para valores do tipo number ou DBKey, a máscara de formatação deve ter a seguinte estrutura:
"%" ["-"] [tamanho] ["." precisão] tipo
Tipos suportados:
d: decimal. O argumento será truncado para um inteiro de 32 bits e convertido em umastringde dígitos decimais. Se o formato especificar uma precisão, ela indicará que a string resultante deve conter ao menos essa quantidade de dígitos. Se o valor tiver menos dígitos, ele será complementado com zeros à esquerda.u: decimal sem sinal. Similar aod, mas os valores são truncados e convertidos em inteiros de 32 bits sem sinal antes de serem formatados.e: científico. O valor é convertido para uma string no formato "-d,ddd...E+ddd". O número total de dígitos é determinado pela precisão e inclui os dígitos que precedem o ponto decimal. A precisão será 15 se uma não for informada. O caractere "E" é sempre seguido de um sinal e de ao menos 3 dígitos.f: fixo. O valor é convertido para uma string no formato "-dddd,ddd...". O número de dígitos é determinado pela precisão, e será assumido 2 se uma não for informada.g: geral. O valor é convertido para a menor representação decimal possível, utilizado o formato fixo ou o científico. O número de dígitos significativos é dado pela precisão, e será assumido 15 caso não seja informada uma. Os zeros não significativos serão removidos e um ponto decimal será inserido apenas se for necessário. Será retornada uma string no formato fixo se o número de dígitos à esquerda do ponto decimal for menor ou igual que a precisão especificada e se o valor for maior ou igual que 0,00001. Nos demais casos, será utilizado o formato científico.n: numérico. O valor é convertido para uma string no formato "-d.ddd.ddd,ddd...", similar ao formato fixo, exceto que a string retornada conterá separadores de milhares.x: hexadecimal. O argumento será truncado para um inteiro de 32 bits e convertido em uma string com a sua representação hexadecimal. Se o formato especificar uma precisão, ela indicará qua string resultante deve conter ao menos essa quantidade de dígitos. Se o valor tiver menos dígitos, ele será complementado com zeros à esquerda.
Para valores do tipo Date, o formato é definido por uma expressão contendo um ou vários
especificadores de exibição, como 'hh:nn:ss'. Especificadores suportados:
d: exibe o dia como um número não precedido de zero (1-31).dd: exibe o dia como um número precedido de zero (01-31).ddd: exibe a abreviação do dia da semana (Dom-Sab).dddd: exibe o nome do dia da semana (Domingo-Sábado).m: exibe o mês como um número não precedido de zero (1-12). Se o especificadormfor seguido do especificadorhouhh, serão exibidos os minutos em vez do mês.mm: exibe o mês como um número precedido de zero (01-12). Se o especificadormmfor seguido do especificadorhouhh, serão exibidos os minutos em vez do mês.mmm: exibe a abreviação do mês (Jan-Dez).mmmm: exibe o nome completo do mês (Janeiro-Dezembro).yy: exibe o ano como um número de dois dígitos (00-99).yyyy: exibe o ano como um número de quatro dígitos (0000-9999).h: exibe as horas como um número não precedido de zero (0-23).hh: exibe as horas como um número precedido de zero (00-23).n: exibe os minutos como um número não precedido de zero (0-59).nn: exibe os minutos como um número precedido de zero (00-59).s: exibe os segundos como um número não precedido de zero (0-59).ss: exibe os segundos como um número precedido de zero (00-59).z: exibe os milissegundos como um número não precedido de zero (0-999).zzz: exibe os milissegundos como um número precedido de zeros (000-999)./: exibe o caractere separador de data.:: exibe o caractere separador de hora.'xx'ou"xx": exibe os caracteres delimitados pelas aspas de forma literal.
Ao formatar os valores, serão adotadas as configurações regionais do sistema operacional para determinar os separadores decimal e de milhares, além dos formatos de data e hora. Atualmente, essas configurações são fixas no padrão "pt-br", mas esse comportamento poderá ser modificado no futuro.
Esta função também é publicada como ngin.text.toFormattedString() no escopo global, sendo
preferível essa forma de uso em scripts da Virtual File System que não são módulos
JavaScript.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
* | Valor a ser formato. |
format |
string | Formato a ser aplicado. |
Returns:
Valor convertido em uma string de acordo com format. Se não for
informado um formato, ou se value não for numérico ou uma data, será realizada a conversão
para uma string por meio do método value.toString(), exceto quando o valor for null. Nesse
caso específico, será retornada uma string vazia.
- Type
- string
Examples
const toFormattedString = require('@nginstack/engine/lib/string/toFormattedString');
toFormattedString(10.578, '%.3n'); // => '10,578'
toFormattedString(10.578, '%.2n'); // => '10,58'
toFormattedString(10.578, '%.1n'); // => '10,6'
toFormattedString(10.578, '%.0n'); // => '11'
toFormattedString(10.578, '%4.0n'); // => ' 11'
const toFormattedString = require('@nginstack/engine/lib/string/toFormattedString');
toFormattedString(Math.PI, '%f'); // '3,14'
toFormattedString(Math.PI, '%g'); // '3,14159265358979'
toFormattedString(Math.PI, '%n'); // '3,14'
toFormattedString(Math.PI, '%e'); // '3,14159265358979E+000'
const toFormattedString = require('@nginstack/engine/lib/string/toFormattedString');
toFormattedString(Math.pow(2, 16) - 1, '%.8x'); // => '0000FFFF'
const toFormattedString = require('@nginstack/engine/lib/string/toFormattedString');
const dt = new Date(2019, 1, 2, 3, 4, 5, 6);
toFormattedString(dt, 'dddd, dd "de" mmmm "de" yyyy'); // => 'Sábado, 02 de Fevereiro de 2019'