Parses a string into a time.
Time = SRP_Time("Parse", Text, Format = "Short", Locale = "")
Returns
A time in OI internal format.
Parameters
| Parameter | Description |
|---|---|
| Text | A string containing a time in human readable format. (REQUIRED) |
| Format | A custom or predefined format. (OPTIONAL) |
| Locale | A locale for culture specific names and formatting. (OPTIONAL) |
Remarks
The "Parse" service converts human readable text into an OI time, much like IConv. IConv is rather limited on the kinds of strings you can parse. This service provides a very optimistic parser that can successfully parse any well formed time while taking cultural formatting into account.
Guiding the Parser
To guide the parser, you set Format to any value described in the Format service. The Parser will use it only to identify the order in which to find time components. The parser is smart enough to find the right numbers so long as they are in the right place in the order you specify.
If you set Format to "Short" or "Long", then the order is determined by Locale. Locale can be set to Windows Locale Name to target a specific language or left blank to use the user's current locale settings.
Suppose you want a very specific order. In that case, you can set Format to something like "h:mm:ss". Remember, only order matters. When you use this format in the Parse service, it can handle "15:30:34", "3:30 pm", and anything else so long as the order is Hour, Minute, Second.
Default Order
The parser will attempt to succeed in parsing a time even if you don't supply the entire order. The default order is always Hour, Minute, and Second. If your format is just "mm:ss", then it will look for Minute and Second first, then it will look Hour. If your format is just "ss", this it will look for Second first, then it will look for Hour followed by Minute.
Default Components
The parser is very optimistic, so if the incoming text is missing some components, it will attempt to reasonably fill the gaps. For example, let's say the format is "h:mm:ss", but the user just types, "12", the parser will succeed, producing a time of 12:00:00pm. Here are the defaults used when a component is omitted.
| Component | Default | Reason |
|---|---|---|
| Hour | n/a | If the hour is missing, the parse will fail. |
| Minute | 0 | Defaulting to the top of the hour allows parsing of just the hour, e.g., "3/15 at 12am" |
| Second | 0 | Defaulting to the top of the minute allows parsing of just the hour and minute, e.g., "3/15 7:30" |
Examples
// Parse a time using the default format and the current locale as a guide
Time = SRP_Time("Parse", "9:58 AM")
// Parse a time using the long format and the current locale as a guide
Time = SRP_Time("Parse", "9:58:22 AM", "Long")
// Parse a time using the long format and the Spanish language as a guide
Time = SRP_Time("Parse", "15:17:43", "Long", "es")
// Parse a time using a custom format and the Spanish-MEXICAN language as a guide
Time = SRP_Time("Parse", "3:17:43 p. m.", "h:mm:ss tt", "es-MX")
