<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="VB6Parse Library Reference - timevalue - Datetime">
<title>timevalue - Datetime - VB6Parse Library Reference</title>
<link rel="stylesheet" href="../../../assets/css/style.css">
<link rel="stylesheet" href="../../../assets/css/docs-style.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
<script src="../../../assets/js/theme-switcher.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/vbnet.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<header class="docs-header">
<div class="container">
<h1><a href="../../../index.html">VB6Parse</a> / <a href="../../../library/index.html">Library</a> / <a href="../../../library/functions/datetime/index.html">Datetime</a> / timevalue</h1>
<p class="tagline">VB6 Library Reference</p>
</div>
</header>
<nav class="docs-nav">
<div class="container">
<a href="../../../index.html">Home</a>
<a href="../../../library/index.html">Library Reference</a>
<a href="../../../documentation.html">Documentation</a>
<a href="https://docs.rs/vb6parse" target="_blank">API Docs</a>
<a href="https://github.com/scriptandcompile/vb6parse" target="_blank">GitHub</a>
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
<span class="theme-icon">🌙</span>
</button>
</div>
</nav>
<main class="container">
<article class="library-item">
<p>VB6 TimeValue Function
The <code>TimeValue</code> function returns a Variant (Date) containing the time value represented by a string.</p>
<h2 id="syntax">Syntax</h2>
<pre><code class="language-vbnet">TimeValue(time)</code></pre>
<h2 id="parameters">Parameters</h2>
<ul>
<li><code>time</code>: Required. String expression representing a time (e.g., "14:30:00", "2:30 PM"). Can also be a Variant containing a string or a numeric value representing a time.</li>
</ul>
<h2 id="returns">Returns</h2>
<p>Returns a <code>Variant</code> of subtype <code>Date</code> containing the time value. The date portion is set to zero (December 30, 1899).</p>
<h2 id="remarks">Remarks</h2>
<p>The <code>TimeValue</code> function parses a string and returns the corresponding time value:
- <strong>String input</strong>: Accepts time strings in various formats (e.g., "14:30", "2:30 PM", "23:59:59")
- <strong>Date portion</strong>: Always returns zero date (12/30/1899)
- <strong>Locale aware</strong>: Accepts time formats based on system locale
- <strong>Numeric input</strong>: Accepts numeric values representing fractional days (e.g., 0.5 = 12:00 PM)
- <strong>Null handling</strong>: Returns Null if input is Null
- <strong>Error handling</strong>: Error 13 (Type mismatch) if string cannot be parsed as a time
- <strong>No milliseconds</strong>: Only parses up to seconds
- <strong>Companion to <code>DateValue</code></strong>: Use <code>DateValue</code> for date-only parsing
- <strong>Type returned</strong>: Returns Variant (Date), not a string</p>
<h3 id="accepted-time-formats">Accepted Time Formats</h3>
<ul>
<li>24-hour: "14:30", "23:59:59"</li>
<li>12-hour: "2:30 PM", "11:59:59 PM"</li>
<li>With/without seconds: "8:00", "8:00:00"</li>
<li>With/without AM/PM: "7:15", "7:15 AM"</li>
<li>Numeric: 0.75 (6:00 PM)</li>
</ul>
<h3 id="invalid-inputs">Invalid Inputs</h3>
<ul>
<li>"25:00" (invalid hour)</li>
<li>"13:60" (invalid minute)</li>
<li>"not a time" (not parseable)</li>
</ul>
<h2 id="typical-uses">Typical Uses</h2>
<ol>
<li><strong>Parse User Input</strong>: Convert time strings to time values</li>
<li><strong>Time Comparison</strong>: Compare parsed times to other time values</li>
<li><strong>Scheduling</strong>: Store and use times from configuration or user entry</li>
<li><strong>Time Calculations</strong>: Perform arithmetic with parsed times</li>
<li><strong>Validation</strong>: Check if input is a valid time</li>
<li><strong>Database Import</strong>: Parse time strings from data sources</li>
<li><strong>Time Filtering</strong>: Filter records by parsed time</li>
<li><strong>Time Formatting</strong>: Convert string to time for display or calculation</li>
</ol>
<h2 id="basic-examples">Basic Examples</h2>
<h3 id="example-1-parse-time-string">Example 1: Parse Time String</h3>
<pre><code class="language-vbnet">Sub ParseTime()
Dim t As Date
t = TimeValue("14:30:00")
MsgBox "Parsed time: " & Format$(t, "hh:mm AM/PM")
End Sub</code></pre>
<h3 id="example-2-parse-12-hour-time">Example 2: Parse 12-hour Time</h3>
<pre><code class="language-vbnet">Function ParseNoon() As Date
ParseNoon = TimeValue("12:00 PM")
End Function</code></pre>
<h3 id="example-3-validate-time-input">Example 3: Validate Time Input</h3>
<pre><code class="language-vbnet">Function IsValidTime(inputStr As String) As Boolean
On Error Resume Next
Dim t As Date
t = TimeValue(inputStr)
IsValidTime = (Err.Number = 0)
On Error GoTo 0
End Function</code></pre>
<h3 id="example-4-compare-parsed-time">Example 4: Compare Parsed Time</h3>
<pre><code class="language-vbnet">Function IsAfterNoon(timeStr As String) As Boolean
IsAfterNoon = (TimeValue(timeStr) > TimeValue("12:00 PM"))
End Function</code></pre>
<h2 id="common-patterns">Common Patterns</h2>
<h3 id="pattern-1-parse-and-add-minutes">Pattern 1: Parse and Add Minutes</h3>
<pre><code class="language-vbnet">Function AddMinutes(timeStr As String, minutes As Integer) As Date
AddMinutes = TimeValue(timeStr) + TimeSerial(0, minutes, 0)
End Function</code></pre>
<h3 id="pattern-2-parse-and-compare-to-now">Pattern 2: Parse and Compare to Now</h3>
<pre><code class="language-vbnet">Function IsPast(timeStr As String) As Boolean
IsPast = (TimeValue(timeStr) < Time)
End Function</code></pre>
<h3 id="pattern-3-parse-and-format">Pattern 3: Parse and Format</h3>
<pre><code class="language-vbnet">Function FormatParsedTime(timeStr As String) As String
FormatParsedTime = Format$(TimeValue(timeStr), "hh:mm:ss")
End Function</code></pre>
<h3 id="pattern-4-parse-with-error-handling">Pattern 4: Parse with Error Handling</h3>
<pre><code class="language-vbnet">Function TryParseTime(timeStr As String, ByRef result As Date) As Boolean
On Error Resume Next
result = TimeValue(timeStr)
TryParseTime = (Err.Number = 0)
On Error GoTo 0
End Function</code></pre>
<h3 id="pattern-5-parse-numeric-time">Pattern 5: Parse Numeric Time</h3>
<pre><code class="language-vbnet">Function ParseNumericTime(numericValue As Double) As Date
ParseNumericTime = TimeValue(numericValue)
End Function</code></pre>
<h3 id="pattern-6-parse-and-set-property">Pattern 6: Parse and Set Property</h3>
<pre><code class="language-vbnet">Sub SetStartTime(obj As Object, timeStr As String)
obj.StartTime = TimeValue(timeStr)
End Sub</code></pre>
<h3 id="pattern-7-parse-array-of-times">Pattern 7: Parse Array of Times</h3>
<pre><code class="language-vbnet">Function ParseTimeArray(timeStrings() As String) As Variant
Dim i As Integer
Dim times() As Date
ReDim times(LBound(timeStrings) To UBound(timeStrings))
For i = LBound(timeStrings) To UBound(timeStrings)
times(i) = TimeValue(timeStrings(i))
Next i
ParseTimeArray = times
End Function</code></pre>
<h3 id="pattern-8-filter-valid-times">Pattern 8: Filter Valid Times</h3>
<pre><code class="language-vbnet">Function FilterValidTimes(timeStrings() As String) As Collection
Dim validTimes As New Collection
Dim i As Integer
For i = LBound(timeStrings) To UBound(timeStrings)
If IsValidTime(timeStrings(i)) Then
validTimes.Add TimeValue(timeStrings(i))
End If
Next i
Set FilterValidTimes = validTimes
End Function</code></pre>
<h3 id="pattern-9-parse-and-use-in-schedule">Pattern 9: Parse and Use in Schedule</h3>
<pre><code class="language-vbnet">Sub AddScheduleEntry(schedule As Collection, timeStr As String, description As String)
Dim entry As New Collection
entry.Add TimeValue(timeStr), "Time"
entry.Add description, "Description"
schedule.Add entry
End Sub</code></pre>
<h3 id="pattern-10-parse-and-compare-range">Pattern 10: Parse and Compare Range</h3>
<pre><code class="language-vbnet">Function IsWithinRange(timeStr As String, startStr As String, endStr As String) As Boolean
Dim t As Date
t = TimeValue(timeStr)
IsWithinRange = (t >= TimeValue(startStr) And t <= TimeValue(endStr))
End Function</code></pre>
<h2 id="advanced-usage">Advanced Usage</h2>
<h3 id="example-1-time-parser-class">Example 1: Time Parser Class</h3>
<pre><code class="language-vbnet">' Class: TimeParser
' Parses and validates time strings
Option Explicit
Public Function Parse(timeStr As String) As Date
Parse = TimeValue(timeStr)
End Function
Public Function TryParse(timeStr As String, ByRef result As Date) As Boolean
On Error Resume Next
result = TimeValue(timeStr)
TryParse = (Err.Number = 0)
On Error GoTo 0
End Function
Public Function IsValid(timeStr As String) As Boolean
On Error Resume Next
Dim t As Date
t = TimeValue(timeStr)
IsValid = (Err.Number = 0)
On Error GoTo 0
End Function
Public Function Format(timeStr As String, formatStr As String) As String
Format = Format$(TimeValue(timeStr), formatStr)
End Function</code></pre>
<h3 id="example-2-schedule-importer-module">Example 2: Schedule Importer Module</h3>
<pre><code class="language-vbnet">' Module: ScheduleImporter
' Imports and parses schedule times from data
Option Explicit
Public Function ImportSchedule(times() As String, descriptions() As String) As Collection
Dim schedule As New Collection
Dim i As Integer
For i = LBound(times) To UBound(times)
Dim entry As New Collection
entry.Add TimeValue(times(i)), "Time"
entry.Add descriptions(i), "Description"
schedule.Add entry
Next i
Set ImportSchedule = schedule
End Function
Public Function GetEarliestTime(times() As String) As Date
Dim minTime As Date
Dim i As Integer
minTime = TimeValue(times(LBound(times)))
For i = LBound(times) + 1 To UBound(times)
If TimeValue(times(i)) < minTime Then minTime = TimeValue(times(i))
Next i
GetEarliestTime = minTime
End Function
Public Function GetLatestTime(times() As String) As Date
Dim maxTime As Date
Dim i As Integer
maxTime = TimeValue(times(LBound(times)))
For i = LBound(times) + 1 To UBound(times)
If TimeValue(times(i)) > maxTime Then maxTime = TimeValue(times(i))
Next i
GetLatestTime = maxTime
End Function</code></pre>
<h3 id="example-3-time-validator-class">Example 3: Time Validator Class</h3>
<pre><code class="language-vbnet">' Class: TimeValidator
' Validates and normalizes time strings
Option Explicit
Public Function IsValid(timeStr As String) As Boolean
On Error Resume Next
Dim t As Date
t = TimeValue(timeStr)
IsValid = (Err.Number = 0)
On Error GoTo 0
End Function
Public Function Normalize(timeStr As String) As String
On Error Resume Next
Dim t As Date
t = TimeValue(timeStr)
If Err.Number = 0 Then
Normalize = Format$(t, "hh:mm:ss")
Else
Normalize = ""
End If
On Error GoTo 0
End Function</code></pre>
<h3 id="example-4-time-range-analyzer-module">Example 4: Time Range Analyzer Module</h3>
<pre><code class="language-vbnet">' Module: TimeRangeAnalyzer
' Analyzes and compares time ranges
Option Explicit
Public Function GetTimeRange(times() As String) As String
Dim minTime As Date, maxTime As Date
Dim i As Integer
minTime = TimeValue(times(LBound(times)))
maxTime = minTime
For i = LBound(times) + 1 To UBound(times)
If TimeValue(times(i)) < minTime Then minTime = TimeValue(times(i))
If TimeValue(times(i)) > maxTime Then maxTime = TimeValue(times(i))
Next i
GetTimeRange = Format$(minTime, "hh:mm") & " - " & Format$(maxTime, "hh:mm")
End Function
Public Function IsWithinRange(timeStr As String, startStr As String, endStr As String) As Boolean
Dim t As Date
t = TimeValue(timeStr)
IsWithinRange = (t >= TimeValue(startStr) And t <= TimeValue(endStr))
End Function</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>The <code>TimeValue</code> function can raise the following errors:
- <strong>Error 13 (Type mismatch)</strong>: If the string cannot be parsed as a time
- <strong>Returns Null</strong>: If the input is Null (not an error)</p>
<h2 id="performance-notes">Performance Notes</h2>
<ul>
<li>Fast operation - simple parsing</li>
<li>Constant time O(1) complexity for valid strings</li>
<li>Locale-dependent parsing speed</li>
<li>Safe to call repeatedly</li>
</ul>
<h2 id="best-practices">Best Practices</h2>
<ol>
<li><strong>Validate input</strong> before calling if user-provided</li>
<li><strong>Handle Null</strong> explicitly when working with nullable fields</li>
<li><strong>Use Format$</strong> for display after parsing</li>
<li><strong>Test with different locales</strong> for internationalization</li>
<li><strong>Use <code>TryParse</code> pattern</strong> for robust error handling</li>
<li><strong>Document expected formats</strong> for maintainability</li>
<li><strong>Store as Date type</strong> for calculations</li>
<li><strong>Use with <code>TimeSerial</code></strong> for arithmetic</li>
<li><strong>Test edge cases</strong> (midnight, noon, invalid times)</li>
<li><strong>Combine with <code>DateValue</code></strong> for full date/time parsing</li>
</ol>
<h2 id="comparison-table">Comparison Table</h2>
<table>
<thead>
<tr>
<th>Function</th>
<th>Purpose</th>
<th>Input</th>
<th>Returns</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>TimeValue</code></td>
<td>Parse time from string</td>
<td>time string</td>
<td>Date (time only)</td>
</tr>
<tr>
<td><code>DateValue</code></td>
<td>Parse date from string</td>
<td>date string</td>
<td>Date (date only)</td>
</tr>
<tr>
<td><code>TimeSerial</code></td>
<td>Create time from components</td>
<td>hour, minute, second</td>
<td>Date (time only)</td>
</tr>
<tr>
<td><code>DateSerial</code></td>
<td>Create date from components</td>
<td>year, month, day</td>
<td>Date (date only)</td>
</tr>
<tr>
<td><code>CDate</code></td>
<td>Convert to date</td>
<td>expression</td>
<td>Date</td>
</tr>
</tbody>
</table>
<h2 id="platform-notes">Platform Notes</h2>
<ul>
<li>Available in VB6, VBA, and <code>VBScript</code></li>
<li>Consistent behavior across platforms</li>
<li>Locale-aware parsing</li>
<li>Date portion always zero (12/30/1899)</li>
<li>Compatible with all date/time functions</li>
</ul>
<h2 id="limitations">Limitations</h2>
<ul>
<li>Only parses up to seconds (no milliseconds)</li>
<li>Locale-dependent parsing (may fail on some formats)</li>
<li>Cannot parse date and time together (use <code>CDate</code> for full datetime)</li>
<li>No timezone support</li>
<li>No daylight saving time handling</li>
<li>Returns only time portion (date is zero)</li>
<li>Error on invalid input (not Null)</li>
</ul>
</article>
<div style="margin-top: 3rem; padding-top: 2rem; border-top: 1px solid var(--border-color);">
<p>
<a href="index.html">← Back to Datetime</a> |
<a href="../index.html">View all functions</a>
</p>
</div>
</main>
<footer>
<div class="container">
<p>© 2024-2026 VB6Parse Contributors. Licensed under the MIT License.</p>
</div>
</footer>
</body>
</html>