Contact Us 1-800-596-4880
  1. Homepage
  2. DataWeave (2.5)
  3. DataWeave Reference
  4. dw::util::Coercions

  5. toString

toString

toString(number: Number, format: String | Null = null, locale: String | Null = null, roundMode: RoundingMode | Null = null): String

A variant of toString that transforms a Number value (whole or decimal) into a String value and accepts a format, locale, and rounding mode value.

Introduced in DataWeave version 2.4.0.

Parameters

Name Description

number

The Number value to format.

format

The formatting to apply to the Number value. A format accepts # or 0 (but not both) as placeholders for decimal values, and only one decimal point is permitted. A null or empty String value has no effect on the Number value. Most other values are treated as literals, but you must escape special characters, such as a dollar sign (for example, \$). Inner quotations must be closed and differ from the surrounding quotations.

locale

Optional ISO 3166 country code to use, such as US, AR, or ES. A null or absent value uses your JVM default. When you pass a translatable format, such as eeee and MMMM, a locale (such as "ES) transforms the corresponding numeric values to a localized string.

roundMode

Optional parameter for rounding decimal values when the formatting presents a rounding choice, such as a format of 0.# for the decimal 0.15. The default is HALF_UP, and a null value behaves like HALF_UP. Only one of the following values is permitted:

  • UP: Always rounds away from zero (for example, 0.01 to "0.1" and -0.01 to "-0.1"). Increments the preceding digit to a non-zero fraction and never decreases the magnitude of the calculated value.

  • DOWN: Always rounds towards zero (for example, 0.19 to "0.1" and -0.19 to "-0.1"). Never increments the digit before a discarded fraction (which truncates to the preceding digit) and never increases the magnitude of the calculated value.

  • CEILING: Rounds towards positive infinity and behaves like UP if the result is positive (for example, 0.35 to "0.4"). If the result is negative, this mode behaves like DOWN (for example, -0.35 to "-0.3"). This mode never decreases the calculated value.

  • FLOOR: Rounds towards negative infinity and behaves like DOWN if the result is positive (for example, 0.35 to "0.3"). If the result is negative, this mode behaves like UP (for example, -0.35 to "-0.4"). The mode never increases the calculated value.

  • HALF_UP: Default mode, which rounds towards the nearest "neighbor" unless both neighbors are equidistant, in which case, this mode rounds up. For example, 0.35 rounds to "0.4", 0.34 rounds to "0.3", and 0.36 rounds to "0.4". Negative decimals numbers round similarly. For example, -0.35 rounds to `"-0.4`".

  • HALF_DOWN: Rounds towards the nearest numeric "neighbor" unless both neighbors are equidistant, in which case, this mode rounds down. For example, 0.35 rounds to "0.3", 0.34 rounds to "0.3", and 0.36 rounds to "0.4". Negative decimals numbers round similarly. For example, -0.35 rounds to "-0.3".

  • HALF_EVEN: For decimals that end in a 5 (such as, 1.125 and 1.135), the behavior depends on the number that precedes the 5. HALF_EVEN rounds up when the next-to-last digit before the 5 is an odd number but rounds down when the next-to-last digit is even. For example, 0.225 rounds to "0.22", 0.235 and 0.245 round to "0.24", and 0.255 rounds to "0.26". Negative decimals round similarly, for example, -0.225 to "-0.22". When the last digit is not 5, the setting behaves like HALF_UP. Rounding of monetary values sometimes follows the HALF_EVEN pattern.

Example

This example shows how toString behaves with different inputs.

Source

%dw 2.0
import * from dw::util::Coercions
output application/json
---
{
    a: toString(1.0),
    b: toString(0.005,".00"),
    c: toString(0.035,"#.##","ES"),
    d: toString(0.005,"#.##","ES","HALF_EVEN"),
    e: toString(0.035,"#.00",null,"HALF_EVEN"),
    f: toString(1.1234,"\$.## 'in my account'")
}

Output

{
  "a": "1",
  "b": ".01",
  "c": "0,04",
  "d": "0",
  "e": ".04",
  "f": "$1.12 in my account"
}

toString(date: Date | DateTime | LocalDateTime | LocalTime | Time, format: String | Null = null, locale: String | Null = null): String

A variant of toString that transforms a Date, DateTime, LocalTime, LocalDateTime, or Time value into a String value.

Introduced in DataWeave version 2.4.0.

Parameters

Name Description

date

The Date, DateTime, LocalTime, LocalDateTime, or Time value to coerce to a String type.

format

The ISO-8601 formatting to use on the date or time. For example, this parameter accepts character patterns based on the Java 8 java.time.format. A null value has no effect on the value. Defaults:

  • Date example: 2011-12-03 (equivalent format: uuuu-MM-dd)

  • DateTime example: 2011-12-03T10:15:30.000000+01:00 (equivalent format: uuuu-MM-dd HH:mm:ssz)

  • LocalDateTime example: 2011-12-03T10:15:30.000000 (equivalent format: uuuu-MM-dd HH:mm:ss)

  • LocalTime example: 10:15:30.000000 (equivalent format: HH:mm:ss.n)

  • Time example: 10:15:30.000000Z (equivalent format: HH:mm:ss.nxxxz)

locale

Optional ISO 3166 country code to use, such as US, AR, or ES. A null or absent value uses your JVM default. When you pass a translatable format, such as eeee and MMMM, a locale (such as "ES) transforms the corresponding numeric values to a localized string.

Example

This example shows how toString behaves with different inputs.

Source

%dw 2.0
import * from dw::util::Coercions
output application/json
---
{
   aDate: toString(|2003-10-01|, "uuuu/MM/dd"),
   aDateTime: toString(|2018-09-17T22:13:00-03:00|),
   aLocalTime: toString(|23:57:59|, "HH-mm-ss"),
   aLocalDateTime : toString(|2015-10-01T23:57:59|),
   aLocalDateTimeFormatted: toString(|2003-10-01T23:57:59|, "uuuu-MM-dd HH:mm:ss a"),
   aLocalDateTimeFormattedAndLocalizedSpain: toString(|2003-01-01T23:57:59|, "eeee, dd MMMM, uuuu HH:mm:ss a", "ES"),
   aTime: typeOf(|22:10:18Z|),
   aTimeZone: toString(|-03:00|)
}

Output

{
  "aDate": "2003/10/01",
  "aDateTime": "2018-09-17T22:13:00-03:00",
  "aLocalTime": "23-57-59",
  "aLocalDateTime": "2015-10-01T23:57:59",
  "aLocalDateTimeFormatted": "2003-10-01 23:57:59 PM",
  "aLocalDateTimeFormattedAndLocalizedSpain": "miércoles, 01 enero, 2003 23:57:59 p. m.",
  "aTime": "Time",
  "aTimeZone": "-03:00"
}

toString(binary: Binary, encoding: String): String

A variant of toString that transforms a Binary value into a String value with the specified encoding.

Introduced in DataWeave version 2.4.0.

Parameters

Name Description

binary

The Binary value to coerce to a String value.

encoding

The encoding to apply to the String value. Accepts encodings that are supported by your JDK. For example, encoding accepts Java canonical names and aliases for the basic and extended encoding sets in Oracle JDK 8 and JDK 11.

Example

This example shows how toString behaves with different inputs.

Source

%dw 2.0
import * from dw::util::Coercions
var binaryData= "DW Test" as Binary {encoding: "UTF-32"}
output application/json
---
{
  a: toString(binaryData, "UTF-32"),
}

Output

{
  "a": "DW Test"
}

toString(data: TimeZone | Uri | Boolean | Period | Regex | Key): String

A variant of toString that transforms a TimeZone, Uri, Boolean, Period, Regex, or Key value into a string.

Introduced in DataWeave version 2.4.0.

Parameters

Name Description

data

The TimeZone, Uri, Boolean, Period, Regex, or Key value to coerce to a String value.

Example

This example shows how toString behaves with different inputs.

Source

%dw 2.0
import * from dw::util::Coercions
output application/json
---
{
  transformTimeZone: toString(|Z|),
  transformBoolean: toString(true),
  transformPeriod: toString(|P1D|),
  transformRegex: toString(/a-Z/),
  transformPeriod: toString(|PT8M10S|),
  transformUri: toString("https://docs.mulesoft.com/" as Uri)
}  ++
{ transformKey : toString((keysOf({ "aKeyToString" : "aValue"})[0])) }

Output

{
  "transformTimeZone": "Z",
  "transformBoolean": "true",
  "transformPeriod": "P1D",
  "transformRegex": "a-Z",
  "transformPeriod": "PT8M10S",
  "transformUri": "https://docs.mulesoft.com/",
  "transformKey": "aKeyToString"
}

toString(arr: Array<String>): String

A variant of toString that joins an Array of characters into a single String value.

Introduced in DataWeave version 2.4.0.

Parameters

Name Description

arr

The Array of characters to transform into a String value.

Example

This example shows how toString behaves with different inputs.

Source

%dw 2.0
import * from dw::util::Coercions
output application/json
---
{
  a: toString([]),
  b: toString(["h", "o", "l", "a"])
}

Output

{
  "a": "",
  "b": "hola"
}