Skip to content

Commit d64c654

Browse files
JoelBergstrandJoelBergstrand
authored
Deprecate temporal formatting (#841)
1 parent e97bba5 commit d64c654

File tree

5 files changed

+267
-96
lines changed

5 files changed

+267
-96
lines changed

‎core/src/main/java/apoc/date/Date.java‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,6 +204,26 @@ private ChronoField chronoField(String unit) {
204204
}
205205

206206
@UserFunction("apoc.date.format")
207+
@QueryLanguageScope(scope = QueryLanguage.CYPHER_5)
208+
@Description(
209+
"Returns a `STRING` representation of the time value.\n"
210+
+ "The time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.")
211+
public String formatCypher5(
212+
final @Name(value = "time", description = "The timestamp since epoch to format.") Long time,
213+
@Name(value = "unit", defaultValue = "ms", description = "The unit of the given timestamp.") String unit,
214+
@Name(
215+
value = "format",
216+
defaultValue = DEFAULT_FORMAT,
217+
description = "The format to convert the given temporal value to.")
218+
String format,
219+
@Name(value = "timezone", defaultValue = "", description = "The timezone the given timestamp is in.")
220+
String timezone) {
221+
return time == null ? null : parse(unit(unit).toMillis(time), format, timezone);
222+
}
223+
224+
@Deprecated
225+
@UserFunction(value = "apoc.date.format", deprecatedBy = "Cypher's format function; format(input, format)")
226+
@QueryLanguageScope(scope = QueryLanguage.CYPHER_25)
207227
@Description(
208228
"Returns a `STRING` representation of the time value.\n"
209229
+ "The time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.")

‎core/src/main/java/apoc/temporal/TemporalProcedures.java‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@
2525

2626
import java.time.*;
2727
import java.time.format.DateTimeFormatter;
28+
import org.neo4j.kernel.api.QueryLanguage;
29+
import org.neo4j.kernel.api.procedure.QueryLanguageScope;
2830
import org.neo4j.procedure.Description;
2931
import org.neo4j.procedure.Name;
3032
import org.neo4j.procedure.UserFunction;
@@ -39,8 +41,9 @@ public class TemporalProcedures {
3941
* @return
4042
*/
4143
@UserFunction("apoc.temporal.format")
44+
@QueryLanguageScope(scope = {QueryLanguage.CYPHER_5})
4245
@Description("Formats the given temporal value into the given time format.")
43-
public String format(
46+
public String formatCypher5(
4447
@Name(value = "temporal", description = "A temporal value to be formatted.") Object input,
4548
@Name(
4649
value = "format",
@@ -71,15 +74,72 @@ public String format(
7174
}
7275
return input.toString();
7376
}
74-
7577
/**
76-
* Convert a Duration into a LocalTime and format the value as a String
78+
* Format a temporal value to a String
7779
*
78-
* @param input
79-
* @param format
80+
* @param input Any temporal type
81+
* @param format A valid DateTime format pattern (ie yyyy-MM-dd'T'HH:mm:ss.SSSS)
8082
* @return
8183
*/
84+
@Deprecated
85+
@UserFunction(value = "apoc.temporal.format", deprecatedBy = "Cypher's format function; format(input, format)")
86+
@QueryLanguageScope(scope = {QueryLanguage.CYPHER_25})
87+
@Description("Formats the given temporal value into the given time format.")
88+
public String format(
89+
@Name(value = "temporal", description = "A temporal value to be formatted.") Object input,
90+
@Name(
91+
value = "format",
92+
defaultValue = "yyyy-MM-dd",
93+
description = "The format to return the temporal value in.")
94+
String format) {
95+
96+
try {
97+
DateTimeFormatter formatter = getOrCreate(format);
98+
99+
if (input instanceof LocalDate) {
100+
return ((LocalDate) input).format(formatter);
101+
} else if (input instanceof ZonedDateTime) {
102+
return ((ZonedDateTime) input).format(formatter);
103+
} else if (input instanceof LocalDateTime) {
104+
return ((LocalDateTime) input).format(formatter);
105+
} else if (input instanceof LocalTime) {
106+
return ((LocalTime) input).format(formatter);
107+
} else if (input instanceof OffsetTime) {
108+
return ((OffsetTime) input).format(formatter);
109+
} else if (input instanceof DurationValue) {
110+
return formatDuration(input, format);
111+
}
112+
} catch (Exception e) {
113+
throw new RuntimeException("Available formats are:\n" + String.join("\n", getTypes())
114+
+ "\nSee also: https://www.elastic.co/guide/en/elasticsearch/reference/5.5/mapping-date-format.html#built-in-date-formats "
115+
+ "and https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html");
116+
}
117+
return input.toString();
118+
}
119+
82120
@UserFunction("apoc.temporal.formatDuration")
121+
@QueryLanguageScope(scope = {QueryLanguage.CYPHER_5})
122+
@Description("Formats the given duration into the given time format.")
123+
public String formatDurationCypher5(
124+
@Name(value = "input", description = "The duration value to be formatted into a string.") Object input,
125+
@Name(value = "format", description = "The format to return the duration in.") String format) {
126+
DurationValue duration = ((DurationValue) input);
127+
128+
try {
129+
String pattern = getOrCreateDurationPattern(format);
130+
return getDurationFormat(duration, pattern);
131+
} catch (Exception e) {
132+
throw new RuntimeException("Available formats are:\n" + String.join("\n", getTypes())
133+
+ "\nSee also: https://www.elastic.co/guide/en/elasticsearch/reference/5.5/mapping-date-format.html#built-in-date-formats "
134+
+ "and https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html");
135+
}
136+
}
137+
138+
@Deprecated
139+
@UserFunction(
140+
value = "apoc.temporal.formatDuration",
141+
deprecatedBy = "Cypher's format function; format(input, format)")
142+
@QueryLanguageScope(scope = {QueryLanguage.CYPHER_25})
83143
@Description("Formats the given duration into the given time format.")
84144
public String formatDuration(
85145
@Name(value = "input", description = "The duration value to be formatted into a string.") Object input,

‎core/src/test/resources/functions/common/functions.json‎

Lines changed: 0 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -1733,46 +1733,6 @@
17331733
}
17341734
]
17351735
},
1736-
{
1737-
"isDeprecated": false,
1738-
"aggregating": false,
1739-
"signature": "apoc.date.format(time :: INTEGER, unit = ms :: STRING, format = yyyy-MM-dd HH:mm:ss :: STRING, timezone = :: STRING) :: STRING",
1740-
"name": "apoc.date.format",
1741-
"description": "Returns a `STRING` representation of the time value.\nThe time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.",
1742-
"returnDescription": "STRING",
1743-
"deprecatedBy": null,
1744-
"category": "",
1745-
"isBuiltIn": false,
1746-
"argumentDescription": [
1747-
{
1748-
"name": "time",
1749-
"description": "The timestamp since epoch to format.",
1750-
"isDeprecated": false,
1751-
"type": "INTEGER"
1752-
},
1753-
{
1754-
"name": "unit",
1755-
"description": "The unit of the given timestamp.",
1756-
"isDeprecated": false,
1757-
"default": "DefaultParameterValue{value=ms, type=STRING}",
1758-
"type": "STRING"
1759-
},
1760-
{
1761-
"name": "format",
1762-
"description": "The format to convert the given temporal value to.",
1763-
"isDeprecated": false,
1764-
"default": "DefaultParameterValue{value=yyyy-MM-dd HH:mm:ss, type=STRING}",
1765-
"type": "STRING"
1766-
},
1767-
{
1768-
"name": "timezone",
1769-
"description": "The timezone the given timestamp is in.",
1770-
"isDeprecated": false,
1771-
"default": "DefaultParameterValue{value=, type=STRING}",
1772-
"type": "STRING"
1773-
}
1774-
]
1775-
},
17761736
{
17771737
"isDeprecated": false,
17781738
"aggregating": false,
@@ -3756,57 +3716,6 @@
37563716
}
37573717
]
37583718
},
3759-
{
3760-
"isDeprecated": false,
3761-
"aggregating": false,
3762-
"signature": "apoc.temporal.format(temporal :: ANY, format = yyyy-MM-dd :: STRING) :: STRING",
3763-
"name": "apoc.temporal.format",
3764-
"description": "Formats the given temporal value into the given time format.",
3765-
"returnDescription": "STRING",
3766-
"deprecatedBy": null,
3767-
"category": "",
3768-
"isBuiltIn": false,
3769-
"argumentDescription": [
3770-
{
3771-
"name": "temporal",
3772-
"description": "A temporal value to be formatted.",
3773-
"isDeprecated": false,
3774-
"type": "ANY"
3775-
},
3776-
{
3777-
"name": "format",
3778-
"description": "The format to return the temporal value in.",
3779-
"isDeprecated": false,
3780-
"default": "DefaultParameterValue{value=yyyy-MM-dd, type=STRING}",
3781-
"type": "STRING"
3782-
}
3783-
]
3784-
},
3785-
{
3786-
"isDeprecated": false,
3787-
"aggregating": false,
3788-
"signature": "apoc.temporal.formatDuration(input :: ANY, format :: STRING) :: STRING",
3789-
"name": "apoc.temporal.formatDuration",
3790-
"description": "Formats the given duration into the given time format.",
3791-
"returnDescription": "STRING",
3792-
"deprecatedBy": null,
3793-
"category": "",
3794-
"isBuiltIn": false,
3795-
"argumentDescription": [
3796-
{
3797-
"name": "input",
3798-
"description": "The duration value to be formatted into a string.",
3799-
"isDeprecated": false,
3800-
"type": "ANY"
3801-
},
3802-
{
3803-
"name": "format",
3804-
"description": "The format to return the duration in.",
3805-
"isDeprecated": false,
3806-
"type": "STRING"
3807-
}
3808-
]
3809-
},
38103719
{
38113720
"isDeprecated": false,
38123721
"aggregating": false,

‎core/src/test/resources/functions/cypher25/functions.json‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -485,6 +485,46 @@
485485
}
486486
]
487487
},
488+
{
489+
"isDeprecated": true,
490+
"aggregating": false,
491+
"signature": "apoc.date.format(time :: INTEGER, unit = ms :: STRING, format = yyyy-MM-dd HH:mm:ss :: STRING, timezone = :: STRING) :: STRING",
492+
"name": "apoc.date.format",
493+
"description": "Returns a `STRING` representation of the time value.\nThe time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.",
494+
"returnDescription": "STRING",
495+
"deprecatedBy": "Cypher's format function; format(input, format)",
496+
"category": "",
497+
"isBuiltIn": false,
498+
"argumentDescription": [
499+
{
500+
"name": "time",
501+
"description": "The timestamp since epoch to format.",
502+
"isDeprecated": false,
503+
"type": "INTEGER"
504+
},
505+
{
506+
"name": "unit",
507+
"description": "The unit of the given timestamp.",
508+
"isDeprecated": false,
509+
"default": "DefaultParameterValue{value=ms, type=STRING}",
510+
"type": "STRING"
511+
},
512+
{
513+
"name": "format",
514+
"description": "The format to convert the given temporal value to.",
515+
"isDeprecated": false,
516+
"default": "DefaultParameterValue{value=yyyy-MM-dd HH:mm:ss, type=STRING}",
517+
"type": "STRING"
518+
},
519+
{
520+
"name": "timezone",
521+
"description": "The timezone the given timestamp is in.",
522+
"isDeprecated": false,
523+
"default": "DefaultParameterValue{value=, type=STRING}",
524+
"type": "STRING"
525+
}
526+
]
527+
},
488528
{
489529
"isDeprecated": true,
490530
"aggregating": false,
@@ -753,5 +793,56 @@
753793
"type": "STRING"
754794
}
755795
]
796+
},
797+
{
798+
"isDeprecated": true,
799+
"aggregating": false,
800+
"signature": "apoc.temporal.format(temporal :: ANY, format = yyyy-MM-dd :: STRING) :: STRING",
801+
"name": "apoc.temporal.format",
802+
"description": "Formats the given temporal value into the given time format.",
803+
"returnDescription": "STRING",
804+
"deprecatedBy": "Cypher's format function; format(input, format)",
805+
"category": "",
806+
"isBuiltIn": false,
807+
"argumentDescription": [
808+
{
809+
"name": "temporal",
810+
"description": "A temporal value to be formatted.",
811+
"isDeprecated": false,
812+
"type": "ANY"
813+
},
814+
{
815+
"name": "format",
816+
"description": "The format to return the temporal value in.",
817+
"isDeprecated": false,
818+
"default": "DefaultParameterValue{value=yyyy-MM-dd, type=STRING}",
819+
"type": "STRING"
820+
}
821+
]
822+
},
823+
{
824+
"isDeprecated": true,
825+
"aggregating": false,
826+
"signature": "apoc.temporal.formatDuration(input :: ANY, format :: STRING) :: STRING",
827+
"name": "apoc.temporal.formatDuration",
828+
"description": "Formats the given duration into the given time format.",
829+
"returnDescription": "STRING",
830+
"deprecatedBy": "Cypher's format function; format(input, format)",
831+
"category": "",
832+
"isBuiltIn": false,
833+
"argumentDescription": [
834+
{
835+
"name": "input",
836+
"description": "The duration value to be formatted into a string.",
837+
"isDeprecated": false,
838+
"type": "ANY"
839+
},
840+
{
841+
"name": "format",
842+
"description": "The format to return the duration in.",
843+
"isDeprecated": false,
844+
"type": "STRING"
845+
}
846+
]
756847
}
757848
]

0 commit comments

Comments
 (0)