From b34f3a17777e0f26b1fbd2ac84ada5991a41677a Mon Sep 17 00:00:00 2001 From: Fang Xing Date: Thu, 18 Apr 2024 14:08:39 -0400 Subject: [PATCH] type conversion functions --- .../functions/examples/to_datetime.asciidoc | 6 ++ .../functions/examples/to_double.asciidoc | 6 ++ .../functions/examples/to_integer.asciidoc | 6 ++ .../esql/functions/examples/to_ip.asciidoc | 6 ++ .../esql/functions/examples/to_long.asciidoc | 6 ++ .../examples/to_unsigned_long.asciidoc | 6 ++ .../esql/functions/to_datetime.asciidoc | 62 ------------------- .../esql/functions/to_double.asciidoc | 50 --------------- .../esql/functions/to_integer.asciidoc | 50 --------------- docs/reference/esql/functions/to_ip.asciidoc | 41 ------------ .../type-conversion-functions.asciidoc | 12 ++-- .../function/scalar/convert/ToDatetime.java | 14 ++++- .../function/scalar/convert/ToDouble.java | 12 +++- .../function/scalar/convert/ToIP.java | 12 +++- .../function/scalar/convert/ToInteger.java | 12 +++- .../function/scalar/convert/ToLong.java | 12 +++- .../scalar/convert/ToUnsignedLong.java | 13 +++- 17 files changed, 111 insertions(+), 215 deletions(-) delete mode 100644 docs/reference/esql/functions/to_datetime.asciidoc delete mode 100644 docs/reference/esql/functions/to_double.asciidoc delete mode 100644 docs/reference/esql/functions/to_integer.asciidoc delete mode 100644 docs/reference/esql/functions/to_ip.asciidoc diff --git a/docs/reference/esql/functions/examples/to_datetime.asciidoc b/docs/reference/esql/functions/examples/to_datetime.asciidoc index 0790ff1f4f157..d68e09890a5c5 100644 --- a/docs/reference/esql/functions/examples/to_datetime.asciidoc +++ b/docs/reference/esql/functions/examples/to_datetime.asciidoc @@ -10,6 +10,12 @@ include::{esql-specs}/date.csv-spec[tag=to_datetime-str] |=== include::{esql-specs}/date.csv-spec[tag=to_datetime-str-result] |=== + +NOTE: Note that in this example, the last value in the source multi-valued field has not been converted. The reason being that if the date format is not respected, the conversion will result in a *null* value. When this happens a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"` + If the input parameter is of a numeric type, its value will be interpreted as milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example: [source.merge.styled,esql] ---- diff --git a/docs/reference/esql/functions/examples/to_double.asciidoc b/docs/reference/esql/functions/examples/to_double.asciidoc index ba629bcbaae98..26cd94573794c 100644 --- a/docs/reference/esql/functions/examples/to_double.asciidoc +++ b/docs/reference/esql/functions/examples/to_double.asciidoc @@ -11,3 +11,9 @@ include::{esql-specs}/floats.csv-spec[tag=to_double-str] include::{esql-specs}/floats.csv-spec[tag=to_double-str-result] |=== +NOTE: Note that in this example, the last conversion of the string isn't possible. When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"java.lang.NumberFormatException: For input string: \"foo\""` + + diff --git a/docs/reference/esql/functions/examples/to_integer.asciidoc b/docs/reference/esql/functions/examples/to_integer.asciidoc index 9169e873a39cf..78e15f8b7d8a6 100644 --- a/docs/reference/esql/functions/examples/to_integer.asciidoc +++ b/docs/reference/esql/functions/examples/to_integer.asciidoc @@ -11,3 +11,9 @@ include::{esql-specs}/ints.csv-spec[tag=to_int-long] include::{esql-specs}/ints.csv-spec[tag=to_int-long-result] |=== +NOTE: Note that in this example, the last value of the multi-valued field cannot be converted as an integer. When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"` + + diff --git a/docs/reference/esql/functions/examples/to_ip.asciidoc b/docs/reference/esql/functions/examples/to_ip.asciidoc index 23310a489810d..5f92fa457c01f 100644 --- a/docs/reference/esql/functions/examples/to_ip.asciidoc +++ b/docs/reference/esql/functions/examples/to_ip.asciidoc @@ -11,3 +11,9 @@ include::{esql-specs}/ip.csv-spec[tag=to_ip] include::{esql-specs}/ip.csv-spec[tag=to_ip-result] |=== +NOTE: Note that in this example, the last conversion of the string isn't possible. When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."` + + diff --git a/docs/reference/esql/functions/examples/to_long.asciidoc b/docs/reference/esql/functions/examples/to_long.asciidoc index b4d643ae8a583..c31e256b3997a 100644 --- a/docs/reference/esql/functions/examples/to_long.asciidoc +++ b/docs/reference/esql/functions/examples/to_long.asciidoc @@ -11,3 +11,9 @@ include::{esql-specs}/ints.csv-spec[tag=to_long-str] include::{esql-specs}/ints.csv-spec[tag=to_long-str-result] |=== +NOTE: Note that in this example, the last conversion of the string isn't possible. When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:113: evaluation of [TO_LONG(str3)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"java.lang.NumberFormatException: For input string: \"foo\""` + + diff --git a/docs/reference/esql/functions/examples/to_unsigned_long.asciidoc b/docs/reference/esql/functions/examples/to_unsigned_long.asciidoc index 8c5035efa3207..d259f414e4f9a 100644 --- a/docs/reference/esql/functions/examples/to_unsigned_long.asciidoc +++ b/docs/reference/esql/functions/examples/to_unsigned_long.asciidoc @@ -11,3 +11,9 @@ include::{esql-specs}/ints.csv-spec[tag=to_unsigned_long-str] include::{esql-specs}/ints.csv-spec[tag=to_unsigned_long-str-result] |=== +NOTE: Note that in this example, the last conversion of the string isn't possible. When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. The header will provide information on the source of the failure: +`"Line 1:133: evaluation of [TO_UL(str3)] failed, treating result as null. Only first 20 failures recorded."` +A following header will contain the failure reason and the offending value: +`"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, nor \"e\" notation exponential mark."` + + diff --git a/docs/reference/esql/functions/to_datetime.asciidoc b/docs/reference/esql/functions/to_datetime.asciidoc deleted file mode 100644 index 37247b8d57279..0000000000000 --- a/docs/reference/esql/functions/to_datetime.asciidoc +++ /dev/null @@ -1,62 +0,0 @@ -[discrete] -[[esql-to_datetime]] -=== `TO_DATETIME` - -*Alias* - -`TO_DT` - -*Syntax* - -[.text-center] -image::esql/functions/signature/to_datetime.svg[Embedded,opts=inline] - -*Parameters* - -`v`:: -Input value. The input can be a single- or multi-valued column or an expression. - -*Description* - -Converts an input value to a date value. - -A string will only be successfully converted if it's respecting the format -`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. To convert dates in other formats, use -<>. - -include::types/to_datetime.asciidoc[] - -*Examples* - -[source.merge.styled,esql] ----- -include::{esql-specs}/date.csv-spec[tag=to_datetime-str] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/date.csv-spec[tag=to_datetime-str-result] -|=== - -Note that in this example, the last value in the source multi-valued -field has not been converted. The reason being that if the date format is not -respected, the conversion will result in a *null* value. When this happens a -_Warning_ header is added to the response. The header will provide information -on the source of the failure: - -`"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"` - -If the input parameter is of a numeric type, its value will be interpreted as -milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example: - -[source.merge.styled,esql] ----- -include::{esql-specs}/date.csv-spec[tag=to_datetime-int] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/date.csv-spec[tag=to_datetime-int-result] -|=== diff --git a/docs/reference/esql/functions/to_double.asciidoc b/docs/reference/esql/functions/to_double.asciidoc deleted file mode 100644 index 984f9ee212339..0000000000000 --- a/docs/reference/esql/functions/to_double.asciidoc +++ /dev/null @@ -1,50 +0,0 @@ -[discrete] -[[esql-to_double]] -=== `TO_DOUBLE` - -*Alias* - -`TO_DBL` - -*Syntax* - -[.text-center] -image::esql/functions/signature/to_double.svg[Embedded,opts=inline] - -*Parameters* - -`v`:: -Input value. The input can be a single- or multi-valued column or an expression. - -*Description* - -Converts an input value to a double value. - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to double. - -Boolean *true* will be converted to double *1.0*, *false* to *0.0*. - -include::types/to_double.asciidoc[] - -*Example* - -[source.merge.styled,esql] ----- -include::{esql-specs}/floats.csv-spec[tag=to_double-str] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/floats.csv-spec[tag=to_double-str-result] -|=== - -Note that in this example, the last conversion of the string isn't possible. -When this happens, the result is a *null* value. In this case a _Warning_ header -is added to the response. The header will provide information on the source of -the failure: - -`"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"java.lang.NumberFormatException: For input string: \"foo\""` diff --git a/docs/reference/esql/functions/to_integer.asciidoc b/docs/reference/esql/functions/to_integer.asciidoc deleted file mode 100644 index d0c1a906698a7..0000000000000 --- a/docs/reference/esql/functions/to_integer.asciidoc +++ /dev/null @@ -1,50 +0,0 @@ -[discrete] -[[esql-to_integer]] -=== `TO_INTEGER` - -*Alias* - -`TO_INT` - -*Syntax* - -[.text-center] -image::esql/functions/signature/to_integer.svg[Embedded,opts=inline] - -*Parameters* - -`v`:: -Input value. The input can be a single- or multi-valued column or an expression. - -*Description* - -Converts an input value to an integer value. - -If the input parameter is of a date type, its value will be interpreted as -milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to integer. - -Boolean *true* will be converted to integer *1*, *false* to *0*. - -include::types/to_integer.asciidoc[] - -*Example* - -[source.merge.styled,esql] ----- -include::{esql-specs}/ints.csv-spec[tag=to_int-long] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/ints.csv-spec[tag=to_int-long-result] -|=== - -Note that in this example, the last value of the multi-valued field cannot -be converted as an integer. When this happens, the result is a *null* value. -In this case a _Warning_ header is added to the response. The header will -provide information on the source of the failure: - -`"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range"` diff --git a/docs/reference/esql/functions/to_ip.asciidoc b/docs/reference/esql/functions/to_ip.asciidoc deleted file mode 100644 index 412e91f60f589..0000000000000 --- a/docs/reference/esql/functions/to_ip.asciidoc +++ /dev/null @@ -1,41 +0,0 @@ -[discrete] -[[esql-to_ip]] -=== `TO_IP` - -*Syntax* - -[.text-center] -image::esql/functions/signature/to_ip.svg[Embedded,opts=inline] - -*Parameters* - -`v`:: -Input value. The input can be a single- or multi-valued column or an expression. - -*Description* - -Converts an input string to an IP value. - -include::types/to_ip.asciidoc[] - -*Example* - -[source.merge.styled,esql] ----- -include::{esql-specs}/ip.csv-spec[tag=to_ip] ----- -[%header.monospaced.styled,format=dsv,separator=|] -|=== -include::{esql-specs}/ip.csv-spec[tag=to_ip-result] -|=== - -Note that in this example, the last conversion of the string isn't possible. -When this happens, the result is a *null* value. In this case a _Warning_ header -is added to the response. The header will provide information on the source of -the failure: - -`"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. Only first 20 failures recorded."` - -A following header will contain the failure reason and the offending value: - -`"java.lang.IllegalArgumentException: 'foo' is not an IP string literal."` diff --git a/docs/reference/esql/functions/type-conversion-functions.asciidoc b/docs/reference/esql/functions/type-conversion-functions.asciidoc index 71a13b82d1a54..207df3d271cf6 100644 --- a/docs/reference/esql/functions/type-conversion-functions.asciidoc +++ b/docs/reference/esql/functions/type-conversion-functions.asciidoc @@ -32,15 +32,15 @@ include::layout/to_base64.asciidoc[] include::layout/to_boolean.asciidoc[] include::layout/to_cartesianpoint.asciidoc[] include::layout/to_cartesianshape.asciidoc[] -include::to_datetime.asciidoc[] +include::layout/to_datetime.asciidoc[] include::layout/to_degrees.asciidoc[] -include::to_double.asciidoc[] +include::layout/to_double.asciidoc[] include::layout/to_geopoint.asciidoc[] include::layout/to_geoshape.asciidoc[] -include::to_integer.asciidoc[] -include::to_ip.asciidoc[] -include::to_long.asciidoc[] +include::layout/to_integer.asciidoc[] +include::layout/to_ip.asciidoc[] +include::layout/to_long.asciidoc[] include::layout/to_radians.asciidoc[] include::layout/to_string.asciidoc[] -include::to_unsigned_long.asciidoc[] +include::layout/to_unsigned_long.asciidoc[] include::layout/to_version.asciidoc[] diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java index 0484523d34144..a14a55daa4786 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDatetime.java @@ -47,7 +47,19 @@ public class ToDatetime extends AbstractConvertFunction { + "A string will only be successfully converted if it's respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. " + "To convert dates in other formats, use <>.", examples = { - @Example(file = "date", tag = "to_datetime-str"), + @Example( + file = "date", + tag = "to_datetime-str", + note = "Note that in this example, the last value in the source multi-valued field has not been converted. " + + "The reason being that if the date format is not respected, the conversion will result in a *null* value. " + + "When this happens a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:112: evaluation of [TO_DATETIME(string)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] " + + "with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']\"`" + ), @Example( description = "If the input parameter is of a numeric type, " + "its value will be interpreted as milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example:", diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java index 581e3ecfc77fd..c43dc6ee3b940 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToDouble.java @@ -50,7 +50,17 @@ public class ToDouble extends AbstractConvertFunction { description = "Converts an input value to a double value.\nIf the input parameter is of a date type, " + "its value will be interpreted as milliseconds since the {wikipedia}/Unix_time[Unix epoch], " + "converted to double. Boolean *true* will be converted to double *1.0*, *false* to *0.0*.", - examples = @Example(file = "floats", tag = "to_double-str") + examples = @Example( + file = "floats", + tag = "to_double-str", + note = "Note that in this example, the last conversion of the string isn't possible. " + + "When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:115: evaluation of [TO_DOUBLE(str2)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"java.lang.NumberFormatException: For input string: \\\"foo\\\"\"`" + ) ) public ToDouble( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java index a9d81890c9ea5..a0e933af2cb8a 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToIP.java @@ -36,7 +36,17 @@ public class ToIP extends AbstractConvertFunction { @FunctionInfo( returnType = "ip", description = "Converts an input string to an IP value.", - examples = @Example(file = "ip", tag = "to_ip") + examples = @Example( + file = "ip", + tag = "to_ip", + note = "Note that in this example, the last conversion of the string isn't possible. " + + "When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:68: evaluation of [TO_IP(str2)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"java.lang.IllegalArgumentException: 'foo' is not an IP string literal.\"`" + ) ) public ToIP( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java index e74d473551eaf..4eba5387f5e72 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToInteger.java @@ -52,7 +52,17 @@ public class ToInteger extends AbstractConvertFunction { + "If the input parameter is of a date type, its value will be interpreted as milliseconds " + "since the {wikipedia}/Unix_time[Unix epoch], converted to integer.\n" + "Boolean *true* will be converted to integer *1*, *false* to *0*.", - examples = @Example(file = "ints", tag = "to_int-long") + examples = @Example( + file = "ints", + tag = "to_int-long", + note = "Note that in this example, the last value of the multi-valued field cannot be converted as an integer. " + + "When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:61: evaluation of [TO_INTEGER(long)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"org.elasticsearch.xpack.ql.InvalidArgumentException: [501379200000] out of [integer] range\"`" + ) ) public ToInteger( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java index bf3011e047a60..49643d802a65d 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToLong.java @@ -52,7 +52,17 @@ public class ToLong extends AbstractConvertFunction { + "its value will be interpreted as milliseconds since the {wikipedia}/Unix_time[Unix epoch], " + "converted to long.\n" + "Boolean *true* will be converted to long *1*, *false* to *0*.", - examples = @Example(file = "ints", tag = "to_long-str") + examples = @Example( + file = "ints", + tag = "to_long-str", + note = "Note that in this example, the last conversion of the string isn't possible. " + + "When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:113: evaluation of [TO_LONG(str3)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"java.lang.NumberFormatException: For input string: \\\"foo\\\"\"`" + ) ) public ToLong( Source source, diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java index a7a84b0a122e2..da6df1191c833 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/convert/ToUnsignedLong.java @@ -54,7 +54,18 @@ public class ToUnsignedLong extends AbstractConvertFunction { + "its value will be interpreted as milliseconds since the {wikipedia}/Unix_time[Unix epoch], " + "converted to unsigned long.\n" + "Boolean *true* will be converted to unsigned long *1*, *false* to *0*.", - examples = @Example(file = "ints", tag = "to_unsigned_long-str") + examples = @Example( + file = "ints", + tag = "to_unsigned_long-str", + note = "Note that in this example, the last conversion of the string isn't possible. " + + "When this happens, the result is a *null* value. In this case a _Warning_ header is added to the response. " + + "The header will provide information on the source of the failure:\n" + + "`\"Line 1:133: evaluation of [TO_UL(str3)] failed, treating result as null. " + + "Only first 20 failures recorded.\"`\n" + + "A following header will contain the failure reason and the offending value:\n" + + "`\"java.lang.NumberFormatException: Character f is neither a decimal digit number, decimal point, " + + "nor \\\"e\\\" notation exponential mark.\"`" + ) ) public ToUnsignedLong( Source source,