La función Number.ToText devuelve un valor numérico como cadena de texto de acuerdo con el formato especificado, permitiéndose establecer la configuración regional a aplicar.
Number.ToText(
number as nullable number,
optional format as nullable text,
optional culture as nullable text
) as nullable text
- number: valor numérico a convertir a texto
- format: (opcional) formato del texto a devolver
- culture: (opcional) cadena de texto con información sobre la configuración regional a aplicar
El argumento format es un código de un único carácter que puede estar opcionalmente seguido por un especificador que define la precisión numérica. La función acepta los siguientes códigos:
- "D" (decimal): en teoría, aplica al valor un formato de número entero. El especificador controla el número de dígitos a devolver. En la práctica, este argumento devuelve un error.
- "E" (exponencial o científico): aplica formato de número con representación científica. El especificador controla el número máximo de cifras decimales.
- "F" (fijo): aplica formato de número real. El especificador de precisión controla el número de cifras decimales a devolver (añadiendo ceros si es necesario).
- "G" (general): aplica la forma más compacta a escoger entre el formato fijo (número real) y exponencial.
- "N" (número): aplica formato de número real con separador de miles y coma decimal.
- "P" (porcentaje): multiplica el número por 100 y añade un símbolo de porcentaje. El especificador controla el número de cifras decimales a incluir en el resultado.
- "R" (recorrido de ida y vuelta): utilidad no suficientemente documentada por parte de Microsoft.
- "X" (hexadecimal): Valor de texto hexadecimal. El especificador de precisión controla el número de caracteres a devolver, añadiéndose ceros por la izquierda si es necesario.
Estos caracteres pueden escribirse tanto en mayúsculas como en minúsculas.
El argumento culture es un string del tipo "es", "es-ES" o "en-US" que determina la configuración regional a usar. La lista completa de códigos está accesible en esta página web de la documentación de Microsoft.
Podemos convertir un número entero en texto con la función
Number.ToText(18)
"18"
Si se trata de un número decimal:
Number.ToText(18.56)
"18.56"
Si el argumento number no es numérico, la función devuelve un error:
Number.ToText("a")
Error
Y esto ocurre aunque el argumento represente un número:
Number.ToText("3")
Error
Formato "D"
En teoría, este formato convierte el número en su representación entera. Sin embargo, la función devuelve un error si se utiliza este argumento:
Number.ToText(15.234, "D")
Error
Formato "E"
El argumento "E" convierte el número en formato exponencial o científico:
Number.ToText(3.14159265359, "E")
"3,141593E+000"
En este caso, el especificador controla el número de cifras en la parte decimal:
Number.ToText(3.14159265359, "E4")
"3,1416E+000"
Formato "F"
En este caso, el número se devuelve con formato de número real ("fijo" ):
Number.ToText(3.14159265359, "F")
"3,14"
El especificador controla el número de cifras en la parte decimal:
Number.ToText(3.14159265359, "F5")
"3,14159"
Obsérvese que la función añadirá ceros por la derecha si es necesario:
Number.ToText(3.14, "F5")
"3,14000"
Formato "G"
Con el formato "G", la función devuelve el formato más compacto resultante de aplicar el formato fijo o el científico, aunque la mayor parte de (¿todos?) los resultados se decantan por la primera opción:
Number.ToText(0,000314159265359, "G")
"0,000314159265359"
Curiosamente, si añadimos el especificador, se limita el número de decimales "significativos", es decir, el que se mostraría como parte decimal si se aplicase el formato exponencial:
Number.ToText(0.000314159265359, "G5")
"0,00031416"
Formato "N"
El resultado devuelto es de tipo número real con parte entera y parte decimal, añadiendo el separador de miles y la coma decimal:
Number.ToText(314159265.359, "N")
"314.159.265,36"
Formato "P"
Con este formato, el número se multiplica por 100 y se añade el símbolo de porcentaje ("%"):
Number.ToText(0.1234, "P")
"12,34 %"
El especificador controla el número de cifras decimales a incluir en el resultado:
Number.ToText(0.1234, "P4")
"12,3400 %"
Formato "R"
Según la documentación en español de Microsoft, con este argumento la función devuelve "Valor de texto que puede realizar un recorrido de ida y vuelta por un número idéntico. El especificador de precisión se omite", lo que resulta imposible de interpretar. Lo único que queda claro es que el especificador de precisión se ignora. En la práctica, el valor devuelto es semejante al obtenido con la opción "fija":
Number.ToText(3.1415, "R")
"3,1415"
Formato "X"
En este caso, el string resultante contiene la representación del valor number en hexadecimal:
Number.ToText(15, "X")
"F"
Number.ToText(512, "X")
"200"
El especificador de precisión controla el número de caracteres a devolver, añadiéndose ceros a la izquierda si es necesario:
Number.ToText(15, "X2")
"0F"
Si la representación en hexadecimal exige más caracteres que los indicados por el especificador, éste se ignora:
Number.ToText(468125, "X2")
"7249D"
El número a transformar deberá ser entero. En otro caso la función devuelve un error:
Number.ToText(15.234, "X2")
Error
Configuración regional
Por defecto, la configuración regional que se aplica es la de nuestro equipo (o la del informe, si lo hemos configurado de otra forma), pero podemos aplicar otra configuración con el parámetro culture. Por ejemplo, tal y como hemos visto, con el argumento "N" se devuelve el valor con separador de miles y coma decimal. En mi caso particular la configuración regional que se aplica es la correspondiente a España:
Number.ToText(314159265.359, "N")
"314.159.265,36"
...es decir, se usa el punto como separador de miles y la coma como separador decimal. Pero podría especificar otra configuración. Así, si desease aplicar la configuración inglesa correspondiente a los Estados Unidos, podría hacerlo de la siguiente forma:
Number.ToText(314159265.359, "N", "en-US")
314,159,265.36
Vemos que, en este caso, se ha utilizado la coma como separador de miles, y el punto como separador decimal.
