SpanAddHour

See Also: Time and Date Functions

Purpose

The SpanAddHour function adds or subtracts a given number of hours to a given TimeSpan variable tsVar.

Return Type

TimeSpan

If the added unit exceeds the range of a TimeSpan section, the entire TimeSpan is adjusted. For example, adding 48 to hours would add 2 days to the TimeSpan variable. The returned TimeSpan variable is always valid.

The TimeSpan variable passed to the function must be valid and non-null. If this is not the case, a DFERR_INVALID_TIMESPAN error will be raised.

This is part of a family of TimeSpan manipulation functions, which includes SpanAddDay, SpanAddHour, SpanAddMillisecond, SpanAddMinute, and SpanAddSecond.

Syntax

Use GlobalDateTimeFunctions.pkg
SpanAddHour( {tsVar}, {iHoursToAdd} )

Where:

• {tsVar} is a value of type TimeSpan.
• {iHoursToAdd} is an integer value representing the number of hours to add to or subtract from tsVar.

Example

This example adds 1 hour to a TimeSpan variable.

Procedure Test
    TimeSpan tsVar
    Move (SpanAddHour(tsVar, 1)) to tsVar
    // This will print:
    // 0:1:0:0
    Showln tsVar
End_Procedure

Example

This example adds 1 day to a TimeSpan variable, then subtracts one hour.

Procedure Test
    TimeSpan tsVar
    Move (SpanAddDay(tsVar, 1)) to tsVar
    Move (SpanAddHour(tsVar, -1)) to tsVar
    // This will print:
    // 0:23:0:0
    Showln tsVar
End_Procedure

SpanAddXxx Functions vs. SpanXxx

The SpanAddXxx functions differ from the SpanXxx functions, which do not perform TimeSpan arithmetic (i.e., they just set one TimeSpan section) and neither the incoming nor outgoing TimeSpan variable is tested for validity.

In most cases, the SpanAddXxx (SpanAddDay, SpanAddHour, SpanAddMillisecond, SpanAddMinute, SpanAddSecond) functions can be used in preference to the SpanXxx (SpanDays, SpanHours, SpanMilliseconds, SpanMinutes, SpanSeconds) functions. The SpanXxx functions are lower level and should be rarely used.