Module: @nginstack/engine/lib/string/toFormattedString


(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 uma string de 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 ao d, 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 especificador m for seguido do especificador h ou hh, 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 especificador mm for seguido do especificador h ou hh, 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).
  • m: exibe os minutos como um número não precedido de zero (0-59).
  • mm: 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'