@openui5/sap.ui.core 1.99.0 → 1.100.0

package/src/sap/ui/core/format/DateFormat.js

@@ -52,6 +52,7 @@ sap.ui.define([
 	 *
 	 * @public
 	 * @hideconstructor
+	 * @see {@link topic:91f2eba36f4d1014b6dd926db0e91070 Date Format}
 	 * @see http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
 	 * @alias sap.ui.core.format.DateFormat
 	 */
@@ -73,6 +74,18 @@ sap.ui.define([
 	// Cache for parsed CLDR DatePattern
 	var mCldrDatePattern = {};
 
+	/**
+	 * Timezone parameter type check
+	 *
+	 * @param {string} sTimezone The timezone to check
+	 * @throws {TypeError} Thrown if the parameter <code>sTimezone</code> is provided and has the wrong type.
+	 */
+	var checkTimezoneParameterType = function (sTimezone) {
+		if (typeof sTimezone !== "string" && !(sTimezone instanceof String) && sTimezone != null) {
+			throw new TypeError("The given timezone must be a string.");
+		}
+	};
+
 	DateFormat.oDateInfo = {
 		type: mDateFormatTypes.DATE,
 		oDefaultFormatOptions: {
@@ -288,8 +301,10 @@ sap.ui.define([
 	 *
 	 * @param {Date} oJSDate The date to format
 	 * @param {string} [sTimezone] The IANA timezone ID in which the date will be calculated and
-	 *   formatted e.g. "America/New_York". If omitted, the timezone will be taken from {@link sap.ui.core.Configuration#getTimezone}.
-	 * @return {string} the formatted output value. If an invalid date is given, an empty string is returned.
+	 *   formatted e.g. "America/New_York". If the parameter is omitted, <code>null</code> or an empty string, the timezone
+	 *   will be taken from {@link sap.ui.core.Configuration#getTimezone}. For an invalid IANA timezone ID, an empty string will be returned.
+	 * @throws {TypeError} Thrown if the parameter <code>sTimezone</code> is provided and has the wrong type.
+	 * @return {string} the formatted output value. If an invalid date or timezone is given, an empty string is returned.
 	 * @name sap.ui.core.format.DateFormat.DateTimeWithTimezone.format
 	 * @function
 	 * @public
@@ -322,11 +337,13 @@ sap.ui.define([
 	 *
 	 * @param {string} sValue the string containing a formatted date/time value
 	 * @param {string} [sTimezone] The IANA timezone ID which should be used to convert the date
-	 *   e.g. "America/New_York". If omitted, the timezone will be taken from {@link sap.ui.core.Configuration#getTimezone}.
+	 *   e.g. "America/New_York". If the parameter is omitted, <code>null</code> or an empty string, the timezone will be taken
+	 *   from {@link sap.ui.core.Configuration#getTimezone}. For an invalid IANA timezone ID, <code>null</code> will be returned.
 	 * @param {boolean} [bStrict] Whether to be strict with regards to the value ranges of date fields,
 	 * e.g. for a month pattern of <code>MM</code> and a value range of [1-12]
 	 * <code>strict</code> ensures that the value is within the range;
 	 * if it is larger than <code>12</code> it cannot be parsed and <code>null</code> is returned
+	 * @throws {TypeError} Thrown if the parameter <code>sTimezone</code> is provided and has the wrong type.
 	 * @return {Array} the parsed values
 	 * <ul>
 	 *   <li>An array containing datetime and timezone depending on the showTimezone option
@@ -349,23 +366,6 @@ sap.ui.define([
 	/**
 	 * Get a datetimeWithTimezone instance of the DateFormat, which can be used for formatting.
 	 *
-	 * @example
-	 * // Timezone difference -5 hours, UTC Zulu
-	 * var sTimezone = "America/New_York";
-	 * var oDate = new Date("2021-11-13T13:22:33Z");
-	 *
-	 * // Show (default)
-	 * DateFormat.getDateTimeWithTimezoneInstance({showTimezone: "Show"}).format(oDate, false, sTimezone);
-	 * // Result: "Nov 13, 2021, 8:22:33 AM America/New_York"
-	 *
-	 * // Hide
-	 * DateFormat.getDateTimeWithTimezoneInstance({showTimezone: "Hide"}).format(oDate, false, sTimezone);
-	 * // Result: "Nov 13, 2021, 8:22:33 AM"
-	 *
-	 * // Only
-	 * DateFormat.getDateTimeWithTimezoneInstance({showTimezone: "Only"}).format(oDate, false, sTimezone);
-	 * // Result: "America/New_York"
-	 *
 	 * @param {object} [oFormatOptions] An object which defines the format options
 	 * @param {string} [oFormatOptions.format] A string containing pattern symbols (e.g. "yMMMd" or "Hms") which will be converted into a pattern for the used locale that matches the wanted symbols best.
 	 *  The symbols must be in canonical order, that is: Era (G), Year (y/Y), Quarter (q/Q), Month (M/L), Week (w), Day-Of-Week (E/e/c), Day (d), Hour (h/H/k/K/j/J), Minute (m), Second (s), Timezone (z/Z/v/V/O/X/x)
@@ -390,6 +390,7 @@ sap.ui.define([
 	 * @static
 	 * @public
 	 * @since 1.99.0
+	 * @experimental As of 1.99.0 certain aspects of this API are not settled yet, i.e. the defaulting for the timezone parameter might change.
 	 */
 	DateFormat.getDateTimeWithTimezoneInstance = function(oFormatOptions, oLocale) {
 		return this.createInstance(oFormatOptions, oLocale, this.oDateTimeWithTimezoneInfo);
@@ -694,27 +695,87 @@ sap.ui.define([
 
 			return sValue.substr(0, iLength);
 		},
-		findEntry: function (sValue, aList) {
+
+		/**
+		 * Returns if the given string starts with another given string ignoring the case.
+		 *
+		 * Takes the locale into account to ensure the characters are interpreted the right way.
+		 *
+		 * First, an exact case check is performed to remain backward compatible, then a case-insensitive check
+		 * based on the locale is done.
+		 *
+		 * When during the case conversion the length of the string changes we cannot safely match
+		 * it and return <code>false</code>.
+		 *
+		 * @param {string} sValue the value to check, e.g. "März 2013"
+		 * @param {string} sSubstring the string to compare it with, e.g. "MÄRZ"
+		 * @param {string} sLocale the locale, e.g. "de-DE"
+		 * @returns {boolean} true if the given string <code>sValue</code> starts with <code>sSubstring</code>
+		 * @private
+		 */
+		startsWithIgnoreCase: function (sValue, sSubstring, sLocale) {
+			// exact case comparison (backward compatible)
+			if (sValue.startsWith(sSubstring)) {
+				return true;
+			}
+			try {
+				// Use String#toLocaleUpperCase instead of String#toLocaleLowerCase because there
+				// are known cases where an upper case letter has 2 lower case variants, e.g. Greek sigma.
+				var sSubToLocaleUpperCase = sSubstring.toLocaleUpperCase(sLocale);
+				var sValueUpperCase = sValue.toLocaleUpperCase(sLocale);
+
+				// During the upper-case conversion there are cases where length changes, e.g. ß -> SS.
+				// This cannot be properly determined without probing therefore we do not support this case.
+				if (sSubToLocaleUpperCase.length !== sSubstring.length || sValueUpperCase.length !== sValue.length) {
+					return false;
+				}
+				return sValueUpperCase.startsWith(sSubToLocaleUpperCase);
+			} catch (e) {
+				// Can fail for String#toLocaleUpperCase with an invalid locale
+				// the API fails in the case with: Incorrect locale information provided
+				return false;
+			}
+		},
+
+		/**
+		 * Finds the longest matching entry for which the following applies:
+		 * * <code>sValue</code> starts with the found entry
+		 *
+		 * The index of the finding in <code>aList</code> and the length of the match is returned.
+		 * The case is ignored and the given locale is used for the string comparison.
+		 *
+		 * @example
+		 * findEntry("MÄRZ 2013", ["Januar", "Februar", "März", "April", ...], "de-DE");
+		 * // {length: 4, index: 2}
+		 *
+		 * @param {string} sValue the input value, e.g. "MÄRZ 2013"
+		 * @param {string[]} aList, the list of values to check, e.g. ["Januar", "Februar", "März", "April", ...]
+		 * @param {string} sLocale the locale which is used for the string comparison, e.g. "de-DE"
+		 * @returns {{length: number, index: number}} the length of the match in sValue, the index in the list of values
+		 *   e.g. length: 4, index: 2 ("MÄRZ")
+		 * @private
+		 */
+		findEntry: function (sValue, aList, sLocale) {
 			var iFoundIndex = -1,
 				iMatchedLength = 0;
-
 			for (var j = 0; j < aList.length; j++) {
-				if (aList[j] && aList[j].length > iMatchedLength && sValue.indexOf(aList[j]) === 0) {
+				if (aList[j] && aList[j].length > iMatchedLength && this.startsWithIgnoreCase(sValue, aList[j], sLocale)) {
 					iFoundIndex = j;
 					iMatchedLength = aList[j].length;
 				}
 			}
 			return {
 				index: iFoundIndex,
-				value: iFoundIndex === -1 ? null : aList[iFoundIndex]
+				length: iMatchedLength
 			};
 		},
+
 		/**
 		 * Parses a given timezone
 		 *
-		 * @param {string} sValue, e.g. "-0800", "-08:00", "-08"
-		 * @param {boolean} bColonSeparated whether or not the values are colon separated, e.g. "-08:00"
-		 * @returns {{tzDiff: number, length: number}} object containing the timezone difference in seconds and the length of the parsed segment
+		 * @param {string} sValue String to parse, e.g. "-0800", "-08:00", "-08"
+		 * @param {boolean} bColonSeparated Whether or not the values are colon separated, e.g. "-08:00"
+		 * @returns {{tzDiff: number, length: number}} Object containing the timezone difference in seconds and the length of the parsed segment
 		 */
 		parseTZ: function (sValue, bColonSeparated) {
 			var iLength = 0;
@@ -832,11 +893,11 @@ sap.ui.define([
 
 				for (var i = 0; i < aErasVariants.length; i++) {
 					var aVariants = aErasVariants[i];
-					var oFound = oParseHelper.findEntry(sValue, aVariants);
+					var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 					if (oFound.index !== -1) {
 						return {
 							era: oFound.index,
-							length: oFound.value.length
+							length: oFound.length
 						};
 					}
 				}
@@ -942,7 +1003,7 @@ sap.ui.define([
 					sPart = oParseHelper.findNumbers(sValue, oPart.digits);
 				}
 				var iYear = parseInt(sPart);
-				var iWeekYear;
+				var iWeekYear = iYear;
 				// Find the right century for two-digit years
 				if (sCalendarType != CalendarType.Japanese && sPart.length <= 2) {
 					var oCurrentDate = UniversalDate.getInstance(new Date(), sCalendarType),
@@ -995,11 +1056,11 @@ sap.ui.define([
 				} else {
 					for (var i = 0; i < aMonthsVariants.length; i++) {
 						var aVariants = aMonthsVariants[i];
-						var oFound = oParseHelper.findEntry(sValue, aVariants);
+						var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 						if (oFound.index !== -1) {
 							return {
 								month: oFound.index,
-								length: oFound.value.length
+								length: oFound.length
 							};
 						}
 					}
@@ -1042,11 +1103,11 @@ sap.ui.define([
 				} else {
 					for (var i = 0; i < aMonthsVariants.length; i++) {
 						var aVariants = aMonthsVariants[i];
-						var oFound = oParseHelper.findEntry(sValue, aVariants);
+						var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 						if (oFound.index !== -1) {
 							return {
 								month: oFound.index,
-								length: oFound.value.length
+								length: oFound.length
 							};
 						}
 					}
@@ -1174,11 +1235,11 @@ sap.ui.define([
 				} else {
 					for (var i = 0; i < aQuartersVariants.length; i++) {
 						var aVariants = aQuartersVariants[i];
-						var oFound = oParseHelper.findEntry(sValue, aVariants);
+						var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 						if (oFound.index !== -1) {
 							return {
 								quarter: oFound.index,
-								length: oFound.value.length
+								length: oFound.length
 							};
 						}
 					}
@@ -1222,11 +1283,11 @@ sap.ui.define([
 				} else {
 					for (var i = 0; i < aQuartersVariants.length; i++) {
 						var aVariants = aQuartersVariants[i];
-						var oFound = oParseHelper.findEntry(sValue, aVariants);
+						var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 						if (oFound.index !== -1) {
 							return {
 								quarter: oFound.index,
-								length: oFound.value.length
+								length: oFound.length
 							};
 						}
 					}
@@ -1269,12 +1330,12 @@ sap.ui.define([
 
 				for (var i = 0; i < aDaysVariants.length; i++) {
 					var aVariants = aDaysVariants[i];
-					var oFound = oParseHelper.findEntry(sValue, aVariants);
+					var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 					if (oFound.index !== -1) {
 						return {
 							// gets translated to dayOfWeek where the day of week is relative to the week
 							dayOfWeek: oFound.index,
-							length: oFound.value.length
+							length: oFound.length
 						};
 					}
 				}
@@ -1299,11 +1360,11 @@ sap.ui.define([
 
 				for (var i = 0; i < aDaysVariants.length; i++) {
 					var aVariants = aDaysVariants[i];
-					var oFound = oParseHelper.findEntry(sValue, aVariants);
+					var oFound = oParseHelper.findEntry(sValue, aVariants, oFormat.oLocaleData.sCLDRLocaleId);
 					if (oFound.index !== -1) {
 						return {
 							day: oFound.index,
-							length: oFound.value.length
+							length: oFound.length
 						};
 					}
 				}
@@ -1804,7 +1865,10 @@ sap.ui.define([
 	 * Uses the timezone from {@link sap.ui.core.Configuration#getTimezone}, which falls back to the
 	 * browser's local timezone to convert the given date.
 	 *
-	 * @example <caption>DateTime (with timezone "Europe/Berlin")</caption>
+	 * When using instances from getDateTimeWithTimezoneInstance, please see the corresponding documentation:
+	 * {@link sap.ui.core.format.DateFormat.getDateTimeWithTimezoneInstance#format}.
+	 *
+	 * @example <caption>DateTime (assuming timezone "Europe/Berlin")</caption>
 	 * var oDate = new Date(Date.UTC(2021, 11, 24, 13, 37));
 	 * DateFormat.getDateTimeInstance().format(oDate);
 	 * // output: "Dec 24, 2021, 2:37:00 PM"
@@ -1821,8 +1885,8 @@ sap.ui.define([
 			sTimezone = bUTC;
 			bUTC = false;
 
-			// timezone is required to calculate the timezone offset therefore it must be a valid IANA timezone ID
-			if (sTimezone != null && !TimezoneUtil.isValidTimezone(sTimezone)) {
+			checkTimezoneParameterType(sTimezone);
+			if (sTimezone && !TimezoneUtil.isValidTimezone(sTimezone)) {
 				Log.error("The given timezone isn't valid.");
 				return "";
 			}
@@ -1849,10 +1913,7 @@ sap.ui.define([
 				return "";
 			}
 			vJSDate = vJSDate.map(function(oJSDate) {
-				if (oJSDate && !isNaN(oJSDate.getTime())) {
-					return convertToTimezone(oJSDate, sTimezone, bUTC);
-				}
-				return oJSDate;
+				return convertToTimezone(oJSDate, sTimezone, bUTC);
 			});
 
 			if (this.oFormatOptions.singleIntervalValue) {
@@ -1867,11 +1928,7 @@ sap.ui.define([
 			}
 
 			if (sResult === undefined) {
-				var bValid = vJSDate.every(function(oJSDate) {
-					return oJSDate && !isNaN(oJSDate.getTime());
-				});
-
-				if (!bValid) {
+				if (!vJSDate.every(isValidDateObject)) {
 					Log.error("At least one date instance which is passed to the interval DateFormat isn't valid.");
 					return "";
 				}
@@ -1879,7 +1936,7 @@ sap.ui.define([
 				sResult = this._formatInterval(vJSDate, bUTC);
 			}
 		} else {
-			if (!vJSDate || isNaN(vJSDate.getTime())) {
+			if (!isValidDateObject(vJSDate)) {
 				// Although an invalid date was given, the DATETIME_WITH_TIMEZONE instance might
 				// have a pattern with the timezone (VV) inside then the IANA timezone ID is returned
 				if (this.type === mDateFormatTypes.DATETIME_WITH_TIMEZONE && this.oFormatOptions.pattern.includes("VV")) {
@@ -2116,8 +2173,7 @@ sap.ui.define([
 	 */
 	var convertToTimezone = function(oJSDate, sTimezone, bUTC) {
 		// Convert to timezone if provided and a valid date is supplied
-		if (!bUTC
-			&& oJSDate && !isNaN(oJSDate.getTime())) {
+		if (!bUTC && isValidDateObject(oJSDate)) {
 			// convert given date to a date in the target timezone
 			return TimezoneUtil.convertToTimezone(oJSDate, sTimezone);
 		}
@@ -2219,19 +2275,27 @@ sap.ui.define([
 		return true;
 	}
 
+	// the expectation is that a valid Date has a getTime function which returns a valid number
+	function isValidDateObject(oDate) {
+		return oDate && typeof oDate.getTime === "function" && !isNaN(oDate.getTime());
+	}
+
 	/**
 	 * Parse a string which is formatted according to the given format options.
 	 *
 	 * Uses the timezone from {@link sap.ui.core.Configuration#getTimezone}, which falls back to the
 	 * browser's local timezone to convert the given date.
 	 *
-	 * @example <caption>DateTime (with timezone "Europe/Berlin")</caption>
+	 * When using instances from getDateTimeWithTimezoneInstance, please see the corresponding documentation:
+	 * {@link sap.ui.core.format.DateFormat.getDateTimeWithTimezoneInstance#parse}.
+	 *
+	 * @example <caption>DateTime (assuming timezone "Europe/Berlin")</caption>
 	 * var oDate = new Date(Date.UTC(2021, 11, 24, 13, 37));
 	 * DateFormat.getDateTimeInstance().parse("Dec 24, 2021, 2:37:00 PM");
 	 * // output: oDate
 	 *
 	 * @param {string} sValue the string containing a formatted date/time value
-	 * @param {boolean} bUTC whether to use UTC, if no timezone is contained
+	 * @param {boolean} bUTC whether to use UTC
 	 * @param {boolean} bStrict whether to use strict value check
 	 * @return {Date|Date[]} the parsed value(s)
 	 * @public
@@ -2249,8 +2313,8 @@ sap.ui.define([
 			sTimezone = bUTC;
 			bUTC = false;
 
-			// timezone is required to calculate the timezone offset therefore it must be a valid IANA timezone ID
-			if (sTimezone != null && !TimezoneUtil.isValidTimezone(sTimezone)) {
+			checkTimezoneParameterType(sTimezone);
+			if (sTimezone && !TimezoneUtil.isValidTimezone(sTimezone)) {
 				Log.error("The given timezone isn't valid.");
 				return null;
 			}

package/src/sap/ui/core/format/DateFormatTimezoneDisplay.js

@@ -16,6 +16,7 @@ sap.ui.define([], function() {
 	 * @public
 	 * @since 1.99.0
 	 * @ui5-metamodel This enumeration also will be described in the UI5 (legacy) designtime metamodel
+	 * @alias sap.ui.core.format.DateFormatTimezoneDisplay
 	 */
 	var DateFormatTimezoneDisplay = {