47.54. $strToDateAndTime

$strToDateAndTime produces a MAINSAIL date and time given a STRING. The date and time may be specified in any of the formats output by $dateAndTimeToStr. If the STRING includes a time zone name, it must be GMT, the name of the local Standard or Daylight Savings time zone, or the name of a time zone defined to MAINSAIL with the DEFINETIMEZONE MAINEX subcommand (see the description of MAINEX in Chapter 21 of the MAINSAIL Utilities User's Guide). If the STRING does not have the format of a time difference and no time zone is included in the STRING, local time is assumed by default (either Daylight Savings or Standard Time, depending on the date part of the STRING). $strToDateAndTime returns TRUE if successful.

s need only start with a valid date and time STRING. remS is that part of s that remains after the part containing the time STRING has been removed.

If s does not begin with a valid date and time, FALSE is returned, and the value of remS is unspecified.

Valid ctrlBits bits are errorOK, $localTime, $localTimeToGMT, $GMTtoLocalTime, and $gmt. errorOK suppresses error messages for invalid input values. The other four values are ignored if the STRING has the format of a time difference; otherwise, at most one of the four bits may be specified, and the bits have the following effects:

$localTime is the default if none of the four bits is specified. If a time zone name is included in s, it overrides the assumption about the time zone of the input STRING as specified by the ctrlBits bit.