parseLongWithPicAndLcid
parseLongWithPicAndLcid(source: String;
pic: String;
lcid: Integer;
errOffset: Integer output): Integer updating;
The parseLongWithPicAndLcid method of the Date primitive type parses the string specified in the source parameter to ensure that it matches the long date picture string specified in the pic parameter in terms of element (day, month, year) order and separators.
Text such as day and month names must match the appropriate values for the locale specified in the lcid parameter. If the source string contains a valid date, it is assigned to the receiver; otherwise the invalid date value is assigned to the receiver (the isValid method of the Date primitive type will return false).
If the value of the pic parameter is null, the long date format picture of the locale specified in the lcid parameter is used. If the value of the lcid parameter is zero (0), the long date format picture of the current locale is used.
If the value of the source parameter matches the format rules, the method returns zero (0) and sets the receiver to the parsed value. If it does not match the format rules, it returns a JADE error code (parse errors are in the range 1800 through 1869), indicates the first offending character returning its zero-based offset using the output errOffset parameter, and sets the receiver to the invalid date value.
The picture element is defined in the picture parameter of the Date primitive type format method.
The following table shows examples of valid matches between source text and format in the English (NZ) locale.
| Date Value (Specified by the source Parameter) | Format (Specified by the pic Parameter) |
|---|---|
| Thursday, 1/July/2010 | dddd, d/MMMM/yyyy |
| 1/July/2010 | d/MMMM/yyyy |
| 1/7/2010 | d/M/yyyy |
| 1 July 2010, Thursday | d MMMM yyyy, dddd |
| 1/7/2010, Thu | d/M/yyyy, ddd |
| 1/Jul/2001 | d/MMM/yyyy |
| 1 Jul 2001 | d MMM yyyy |
Day and month names are matched with the locale table entries using a locale-driven case-insensitive comparison. Abbreviated names are considered to be valid matches for full name specifiers.
The date is assumed to be localized Gregorian. Other calendars such as Hebrew Lunar are not supported.
If the first character of the source is a digit, the characters in the long date format picture up to but not including the first day number, month, or year specifier are considered optional. The source can include a month number, where a month name specifier occurs. Leading zeros for day and month numbers are optional when day number, month, and year have intervening separators.
Provided the source text includes values for each of day number, month, and year and the source text ends with the last element, any trailing text in the format picture (for example, separators and day name) is considered optional.
If the year designator is "yy", exactly two digits must be present for the year number. The two-digit value is upgraded to a four-digit value using the CAL_ITWODIGITYEARMAX setting, which you can set and modify in the Regional settings of the Windows Control Panel. Its default value is 2029, which gives the following conversions.
-
00…29 becomes 2000…2029
-
30…99 becomes 1930…1999
All other year designators require that exactly four digits must be specified for the year number and its value must be in the range zero (0) through 30,000. Negative values (implying the Gregorian BC era) are not supported. If the locale is Thai, the year is assumed to include the Thai year offset (that is, 543), which is subtracted from the date assigned to the receiver.
If native digits are allowed, if the first digit found in the source is a native digit, all subsequent digits must also be native. Similarly, if the first digit found is ASCII, all subsequent digits must also be ASCII.
All characters in the picture string other than the format specifiers (d, M, y, and g) must be matched exactly in the source string. For example, if the format picture string includes some characters before the first specifier, the source must include those exact characters before the first day digit.
Single quote characters (') can be used to enclose literal characters, including the format specifier characters. A pair of single quotes occurring in single quoted text is treated as one character. For example, to display the date as "May '93", the format string is "MMMM ''''yy". The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence, to allow the single quotation mark to be displayed before the century.
If you do not define the
