47.55. $strToTime

$strToTime produces a MAINSAIL time given a STRING. The time specified may be in any of the formats produced by $timeToStr. In addition, if s represents a time difference, the hours specified may exceed 24 and the minutes and seconds 60; e.g., +45:75:75 means a time difference of 46 hours, 16 minutes, and 15 seconds.

s need only start with a valid 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 time, 0L is returned, success is set to FALSE, and the value of remS is unspecified. 0L is a valid return value if the STRING represents a time difference, so success must be examined if an invalid time difference STRING may be input.

The valid ctrlBits bits are $localTime, $gmt, and errorOK.

$localTime and $gmt are ignored if a time zone abbreviation (either GMT or the abbreviation of the local time zone) appears in s; in this case, the returned value is in the specified format. If no time zone abbreviation appears in s, then if $localTime is specified (or if neither $localTime nor $gmt is specified), the STRING is interpreted as a local time and returned in local time format; if $gmt is specified, a GMT format time is returned.

Unless errorOK is specified, an error message is generated for erroneous input values.

The standard MAINSAIL date and time formats are described in Section 24.1.