timeserial - Datetime - VB6Parse Library Reference

VB6 TimeSerial Function

The TimeSerial function returns a Variant (Date) containing the time for a specific hour, minute, and second.

Syntax

TimeSerial(hour, minute, second)

Parameters

hour: Required. Integer from 0 to 23, representing the hour. Values outside this range are normalized.
minute: Required. Integer representing the minute. Values outside 0-59 are normalized.
second: Required. Integer representing the second. Values outside 0-59 are normalized.

Returns

Returns a Variant of subtype Date containing a time value. The date portion is set to zero (December 30, 1899).

Remarks

The TimeSerial function creates time values from component parts:

24-hour format: Hour parameter uses 24-hour format (0-23)
Normalization: Values outside normal ranges are automatically adjusted
Date portion: Always returns zero date (12/30/1899)
Overflow handling: Excess values roll over (e.g., 90 seconds = 1 minute 30 seconds)
Negative values: Can use negative values to subtract time
Calculation flexibility: Can use expressions for any parameter
Time arithmetic: Ideal for adding/subtracting time intervals
Companion to DateSerial: TimeSerial for time, DateSerial for dates
Type returned: Returns Variant (Date), not a numeric type

Normalization Examples

' These all produce valid times through normalization:
TimeSerial(0, 0, 90)      ' = 00:01:30 (90 seconds = 1 min 30 sec)
TimeSerial(0, 90, 0)      ' = 01:30:00 (90 minutes = 1 hour 30 min)
TimeSerial(25, 0, 0)      ' = 01:00:00 (25 hours = 1 AM next day)
TimeSerial(0, -30, 0)     ' = 23:30:00 (previous day)
TimeSerial(12, 30, -60)   ' = 12:29:00 (subtract 60 seconds)

Time Arithmetic

' Add 2 hours to current time
newTime = Time + TimeSerial(2, 0, 0)

' Subtract 30 minutes
newTime = Time + TimeSerial(0, -30, 0)

' Add 1 hour 15 minutes
newTime = Time + TimeSerial(1, 15, 0)

Creating Specific Times

' 8:30 AM
morning = TimeSerial(8, 30, 0)

' Noon
noon = TimeSerial(12, 0, 0)

' 11:59:59 PM
lastSecond = TimeSerial(23, 59, 59)

' Midnight
midnight = TimeSerial(0, 0, 0)

Typical Uses

Create Time Values: Build time from components
Time Arithmetic: Add/subtract hours, minutes, seconds
Schedule Times: Define specific times for scheduling
Time Comparison: Create reference times for comparison
Time Calculations: Calculate time differences
Business Hours: Define opening/closing times
Time Intervals: Represent durations
Alarm Times: Set specific alarm or reminder times

Basic Examples

Example 1: Create Specific Time

Sub CreateTime()
Dim businessOpen As Date
businessOpen = TimeSerial(9, 0, 0)  ' 9:00 AM
MsgBox "Opens at: " & Format$(businessOpen, "hh:mm AM/PM")
End Sub

Example 2: Add Time to Current Time

Function AddHours(hours As Integer) As Date
AddHours = Time + TimeSerial(hours, 0, 0)
End Function

Example 3: Calculate Time Difference

Function GetTimeDuration(hours As Integer, minutes As Integer) As Date
GetTimeDuration = TimeSerial(hours, minutes, 0)
End Function

Example 4: Check If Time Is Between Range

Function IsInTimeRange(checkTime As Date, startHour As Integer, endHour As Integer) As Boolean
Dim startTime As Date
Dim endTime As Date

startTime = TimeSerial(startHour, 0, 0)
endTime = TimeSerial(endHour, 0, 0)

IsInTimeRange = (checkTime >= startTime And checkTime < endTime)
End Function

Common Patterns

Pattern 1: Add Minutes to Time

Function AddMinutes(baseTime As Date, minutes As Integer) As Date
AddMinutes = baseTime + TimeSerial(0, minutes, 0)
End Function

Pattern 2: Add Seconds to Time

Function AddSeconds(baseTime As Date, seconds As Integer) As Date
AddSeconds = baseTime + TimeSerial(0, 0, seconds)
End Function

Pattern 3: Create Time from Total Seconds

Function SecondsToTime(totalSeconds As Long) As Date
Dim hours As Long
Dim minutes As Long
Dim seconds As Long

hours = totalSeconds \ 3600
minutes = (totalSeconds Mod 3600) \ 60
seconds = totalSeconds Mod 60

SecondsToTime = TimeSerial(hours, minutes, seconds)
End Function

Pattern 4: Round Time to Nearest Interval

Function RoundToNearestMinutes(t As Date, intervalMinutes As Integer) As Date
Dim totalMinutes As Long
Dim roundedMinutes As Long

totalMinutes = Hour(t) * 60 + Minute(t)
roundedMinutes = ((totalMinutes + intervalMinutes \ 2) \ intervalMinutes) * intervalMinutes

RoundToNearestMinutes = TimeSerial(roundedMinutes \ 60, roundedMinutes Mod 60, 0)
End Function

Pattern 5: Calculate Elapsed Time

Function CalculateElapsedTime(startTime As Date, endTime As Date) As Date
Dim diffSeconds As Long

diffSeconds = DateDiff("s", startTime, endTime)
CalculateElapsedTime = TimeSerial(0, 0, diffSeconds)
End Function

Pattern 6: Get Noon Time

Function GetNoon() As Date
GetNoon = TimeSerial(12, 0, 0)
End Function

Pattern 7: Get Midnight Time

Function GetMidnight() As Date
GetMidnight = TimeSerial(0, 0, 0)
End Function

Pattern 8: Create Business Hours Range

Sub GetBusinessHours(ByRef openTime As Date, ByRef closeTime As Date)
openTime = TimeSerial(9, 0, 0)    ' 9 AM
closeTime = TimeSerial(17, 0, 0)  ' 5 PM
End Sub

Pattern 9: Add Time Duration

Function AddDuration(baseTime As Date, hours As Integer, minutes As Integer, seconds As Integer) As Date
AddDuration = baseTime + TimeSerial(hours, minutes, seconds)
End Function

Pattern 10: Normalize Time Components

Function NormalizeTime(hours As Integer, minutes As Integer, seconds As Integer) As Date
NormalizeTime = TimeSerial(hours, minutes, seconds)
End Function

Advanced Usage

Example 1: Time Calculator Class

' Class: TimeCalculator
' Performs various time calculations and manipulations
Option Explicit

Public Function AddTime(baseTime As Date, hours As Integer, minutes As Integer, seconds As Integer) As Date
AddTime = baseTime + TimeSerial(hours, minutes, seconds)
End Function

Public Function SubtractTime(baseTime As Date, hours As Integer, minutes As Integer, seconds As Integer) As Date
SubtractTime = baseTime + TimeSerial(-hours, -minutes, -seconds)
End Function

Public Function GetTimeBetween(startTime As Date, endTime As Date) As Date
Dim diffSeconds As Long
Dim hours As Long
Dim minutes As Long
Dim seconds As Long

diffSeconds = DateDiff("s", startTime, endTime)

hours = diffSeconds \ 3600
minutes = (diffSeconds Mod 3600) \ 60
seconds = diffSeconds Mod 60

GetTimeBetween = TimeSerial(hours, minutes, seconds)
End Function

Public Function RoundToQuarterHour(t As Date) As Date
Dim totalMinutes As Long
Dim roundedMinutes As Long

totalMinutes = Hour(t) * 60 + Minute(t)
roundedMinutes = ((totalMinutes + 7) \ 15) * 15

RoundToQuarterHour = TimeSerial(roundedMinutes \ 60, roundedMinutes Mod 60, 0)
End Function

Public Function TruncateToMinute(t As Date) As Date
TruncateToMinute = TimeSerial(Hour(t), Minute(t), 0)
End Function

Public Function TruncateToHour(t As Date) As Date
TruncateToHour = TimeSerial(Hour(t), 0, 0)
End Function

Public Function CreateTimeFromSeconds(totalSeconds As Long) As Date
CreateTimeFromSeconds = TimeSerial(0, 0, totalSeconds)
End Function

Public Function CreateTimeFromMinutes(totalMinutes As Long) As Date
CreateTimeFromMinutes = TimeSerial(0, totalMinutes, 0)
End Function

Example 2: Schedule Manager Module

' Module: ScheduleManager
' Manages schedules and time-based operations
Option Explicit

Private Type ScheduleEntry
Name As String
StartTime As Date
EndTime As Date
Active As Boolean
End Type

Private m_Schedules() As ScheduleEntry
Private m_ScheduleCount As Long

Public Sub AddSchedule(name As String, startHour As Integer, startMinute As Integer, _
endHour As Integer, endMinute As Integer)
ReDim Preserve m_Schedules(m_ScheduleCount)

m_Schedules(m_ScheduleCount).Name = name
m_Schedules(m_ScheduleCount).StartTime = TimeSerial(startHour, startMinute, 0)
m_Schedules(m_ScheduleCount).EndTime = TimeSerial(endHour, endMinute, 0)
m_Schedules(m_ScheduleCount).Active = True

m_ScheduleCount = m_ScheduleCount + 1
End Sub

Public Function IsScheduleActive(name As String) As Boolean
Dim i As Long
Dim currentTime As Date

currentTime = Time

For i = 0 To m_ScheduleCount - 1
If m_Schedules(i).Name = name And m_Schedules(i).Active Then
If m_Schedules(i).StartTime <= m_Schedules(i).EndTime Then
' Normal schedule (same day)
IsScheduleActive = (currentTime >= m_Schedules(i).StartTime And _
currentTime < m_Schedules(i).EndTime)
Else
' Overnight schedule
IsScheduleActive = (currentTime >= m_Schedules(i).StartTime Or _
currentTime < m_Schedules(i).EndTime)
End If
Exit Function
End If
Next i

IsScheduleActive = False
End Function

Public Function GetScheduleDuration(name As String) As Date
Dim i As Long
Dim diffSeconds As Long

For i = 0 To m_ScheduleCount - 1
If m_Schedules(i).Name = name Then
diffSeconds = DateDiff("s", m_Schedules(i).StartTime, m_Schedules(i).EndTime)
If diffSeconds < 0 Then diffSeconds = diffSeconds + 86400  ' Add 24 hours
GetScheduleDuration = TimeSerial(0, 0, diffSeconds)
Exit Function
End If
Next i

GetScheduleDuration = TimeSerial(0, 0, 0)
End Function

Example 3: Time Range Validator Class

' Class: TimeRangeValidator
' Validates times against allowed ranges
Option Explicit

Private m_AllowedStart As Date
Private m_AllowedEnd As Date
Private m_AllowOvernight As Boolean

Public Sub SetAllowedRange(startHour As Integer, startMinute As Integer, _
endHour As Integer, endMinute As Integer)
m_AllowedStart = TimeSerial(startHour, startMinute, 0)
m_AllowedEnd = TimeSerial(endHour, endMinute, 0)
m_AllowOvernight = (m_AllowedStart > m_AllowedEnd)
End Sub

Public Function IsTimeAllowed(checkTime As Date) As Boolean
If m_AllowOvernight Then
' Overnight range (e.g., 10 PM to 6 AM)
IsTimeAllowed = (checkTime >= m_AllowedStart Or checkTime < m_AllowedEnd)
Else
' Normal range (e.g., 9 AM to 5 PM)
IsTimeAllowed = (checkTime >= m_AllowedStart And checkTime < m_AllowedEnd)
End If
End Function

Public Function GetNextAllowedTime(fromTime As Date) As Date
If IsTimeAllowed(fromTime) Then
GetNextAllowedTime = fromTime
Else
' Return start of next allowed window
If fromTime < m_AllowedStart Then
GetNextAllowedTime = m_AllowedStart
Else
' Must wait until tomorrow's start time
GetNextAllowedTime = DateAdd("d", 1, Date) + m_AllowedStart
End If
End If
End Function

Public Function GetTimeUntilAllowed(fromTime As Date) As Date
Dim nextAllowed As Date
Dim diffSeconds As Long

nextAllowed = GetNextAllowedTime(fromTime)
diffSeconds = DateDiff("s", fromTime, nextAllowed)

GetTimeUntilAllowed = TimeSerial(0, 0, diffSeconds)
End Function

Example 4: Time Interval Generator Module

' Module: TimeIntervalGenerator
' Generates time intervals for scheduling
Option Explicit

Public Function GenerateTimeIntervals(startHour As Integer, endHour As Integer, _
intervalMinutes As Integer) As Collection
Dim intervals As New Collection
Dim currentTime As Date
Dim endTime As Date

currentTime = TimeSerial(startHour, 0, 0)
endTime = TimeSerial(endHour, 0, 0)

Do While currentTime < endTime
intervals.Add currentTime
currentTime = currentTime + TimeSerial(0, intervalMinutes, 0)
Loop

Set GenerateTimeIntervals = intervals
End Function

Public Function GenerateWorkDaySchedule(startHour As Integer, endHour As Integer, _
taskDurationMinutes As Integer) As Variant
Dim schedule() As Date
Dim currentTime As Date
Dim endTime As Date
Dim index As Long
Dim maxSlots As Long

currentTime = TimeSerial(startHour, 0, 0)
endTime = TimeSerial(endHour, 0, 0)

maxSlots = DateDiff("n", currentTime, endTime) \ taskDurationMinutes
ReDim schedule(maxSlots - 1)

index = 0
Do While currentTime < endTime And index < maxSlots
schedule(index) = currentTime
currentTime = currentTime + TimeSerial(0, taskDurationMinutes, 0)
index = index + 1
Loop

GenerateWorkDaySchedule = schedule
End Function

Public Function CreateAppointmentSlots(startHour As Integer, endHour As Integer, _
slotDuration As Integer, breakDuration As Integer) As Collection
Dim slots As New Collection
Dim currentTime As Date
Dim endTime As Date

currentTime = TimeSerial(startHour, 0, 0)
endTime = TimeSerial(endHour, 0, 0)

Do While currentTime + TimeSerial(0, slotDuration, 0) <= endTime
slots.Add currentTime
currentTime = currentTime + TimeSerial(0, slotDuration + breakDuration, 0)
Loop

Set CreateAppointmentSlots = slots
End Function

Error Handling

The TimeSerial function can raise the following errors:

Error 5 (Invalid procedure call): If parameters result in invalid time after normalization
Error 13 (Type mismatch): If non-numeric arguments provided
Error 6 (Overflow): If extreme values cause numeric overflow

Performance Notes

Fast operation - simple calculation
Constant time O(1) complexity
No significant overhead from normalization
Efficient for time arithmetic
Safe to call repeatedly

Best Practices

Use for time creation rather than parsing strings
Leverage normalization for time arithmetic (e.g., negative minutes to subtract)
Store as Date type for compatibility with other date/time functions
Use 24-hour format for hour parameter (0-23)
Combine with Date for complete date/time values
Use for relative times (intervals, durations)
Format for display with Format$ function
Document time assumptions (e.g., time zone, 24-hour format)
Validate inputs if accepting user-provided values
Use DateAdd for more complex date/time arithmetic

Comparison Table

Function	Purpose	Parameters	Returns
`TimeSerial`	Create time from components	hour, minute, second	Date (time only)
`DateSerial`	Create date from components	year, month, day	Date (date only)
`TimeValue`	Parse time from string	time string	Date (time only)
`DateValue`	Parse date from string	date string	Date (date only)
`CDate`	Convert to date	expression	Date

Platform Notes

Available in VB6, VBA, and VBScript
Consistent behavior across platforms
Automatic normalization of values
Date portion always zero (12/30/1899)
Works with standard Date type
Compatible with all date/time functions

Limitations

Returns only time portion (date is zero)
Cannot directly create date and time together (use DateSerial + TimeSerial)
No timezone support
No daylight saving time handling
Limited to standard time resolution (seconds)
Cannot create times with milliseconds
Normalization may produce unexpected results if not understood