An advanced DateTime manipulation library for OutSystems Developer Cloud (ODC) that extends the built-in DateTime functions with comprehensive date and time operations.
DateTimePlusPlus provides a rich set of functions designed to simplify and enhance DateTime operations in OutSystems ODC applications. Whether you need to calculate business days, parse custom date formats, perform timezone conversions, or execute complex date arithmetic, this library offers the tools you need.
Description: Converts a UTC date time to the specified time zone. The input DateTime is treated as UTC regardless of its Kind property (any existing timezone information is stripped). Returns the equivalent local time in the target timezone, accounting for Daylight Saving Time rules if applicable.
Parameters:
Original(DateTime): The DateTime value to convert. Will be treated as UTC regardless of its Kind property.TimeZone(TimeZone): The target timezone to convert to. Must be a valid TimeZone structure obtained from GetTimeZoneById or GetTimeZones.
Returns: DateTime in the target timezone with Kind set to Unspecified
Description: Converts a date time from a specified time zone to UTC. The input DateTime is treated as being in the source timezone regardless of its Kind property (any existing timezone information is stripped and the TimeZone parameter becomes the source of truth). Converts to UTC accounting for Daylight Saving Time if applicable in the source timezone.
Parameters:
Original(DateTime): The DateTime value to convert. Will be treated as being in the source timezone regardless of its Kind property.TimeZone(TimeZone): The source timezone where the DateTime value originates. Must be a valid TimeZone structure.
Returns: DateTime converted to UTC with Kind set to Utc
Description: Returns a new TimeZones structure instance. This is a factory method that creates and returns an initialized TimeZones object containing all available system time zones.
Parameters: None
Returns: Initialized TimeZones structure containing all system timezones
Description: Converts a date time directly from one time zone to another in a single operation. The input DateTime is treated as being in the source timezone regardless of its Kind property (any existing timezone information is stripped). Performs a direct conversion between the two timezones, automatically accounting for Daylight Saving Time rules in both source and target timezones.
Parameters:
Original(DateTime): The DateTime value to convert. Will be treated as being in the source timezone regardless of its Kind property.SourceTimeZone(TimeZone): The source timezone where the DateTime value currently exists. Must be a valid TimeZone structure.TargetTimeZone(TimeZone): The target timezone to convert to. Must be a valid TimeZone structure.
Returns: DateTime in the target timezone with Kind set to Unspecified
Description: Retrieves all system time zones that have a specific base UTC offset. The search uses the BaseUtcOffset property, which represents the standard time offset without considering Daylight Saving Time. Returns an array of TimeZone objects, each containing the timezone ID and display name. Multiple timezones may share the same base offset.
Parameters:
OffsetHours(double): The base UTC offset in decimal hours to filter by. Examples: -5.0 for EST, +1.0 for CET, +5.5 for IST. This matches the standard time offset, not the DST-adjusted offset.
Returns: Array of TimeZone objects with matching base UTC offset
Description: Calculates the current UTC offset for a specific time zone at the current moment. The returned offset accounts for Daylight Saving Time if it is currently active in the timezone. Returns the offset as a decimal number of hours (e.g., -5.0 for EST, +5.5 for IST, -4.0 for EDT during DST).
Parameters:
TimeZone(TimeZone): The timezone to query for its current UTC offset. Must be a valid TimeZone structure.
Returns: Current UTC offset in decimal hours (DST-adjusted)
Description: Calculates the UTC offset for a specific time zone at a given historical or future date and time. The input DateTime's Kind property is ignored (timezone information is stripped). Accounts for Daylight Saving Time if it was/will be active at that specific moment. Useful for historical analysis or future planning. Returns the offset as decimal hours.
Parameters:
SpecificDateTime(DateTime): The specific date and time to evaluate. The Kind property is ignored - this is treated as an unspecified moment in time.TimeZone(TimeZone): The timezone to query for its UTC offset at the specified moment. Must be a valid TimeZone structure.
Returns: UTC offset in decimal hours at the specified moment (DST-adjusted)
Description: Determines whether a specific date and time falls within the Daylight Saving Time period for a given time zone. The input DateTime's Kind property is ignored (timezone information is stripped). Returns true if DST is active at that moment in the specified timezone, false otherwise. For timezones that don't observe DST, always returns false.
Parameters:
DateTimeToCheck(DateTime): The date and time to check for DST status. The Kind property is ignored - treated as an unspecified moment in time.TimeZone(TimeZone): The timezone to evaluate for DST status at the specified moment. Must be a valid TimeZone structure.
Returns: True if DST is active at that moment, false otherwise
Description: Retrieves a time zone object by its system timezone ID. Searches the system's timezone database and returns a TimeZone structure containing the ID and display name. Throws TimeZoneNotFoundException if the ID doesn't exist. Use IsValidTimeZoneId to check validity before calling this method if you're unsure.
Parameters:
TimeZoneId(string): The system timezone identifier to look up. Examples: 'Eastern Standard Time', 'Pacific Standard Time', 'UTC', 'Central European Standard Time'. Case-sensitive.
Returns: TimeZone structure with ID and display name
Description: Validates whether a given timezone ID exists in the system's timezone database. This is a safe validation method that catches both TimeZoneNotFoundException and InvalidTimeZoneException internally and returns a boolean result instead of throwing exceptions. Use this method to verify timezone IDs before using them in other operations.
Parameters:
TimeZoneId(string): The timezone identifier string to validate. Should be a system timezone ID like 'Eastern Standard Time' or 'UTC'.
Returns: True if timezone ID exists, false otherwise
Description: Formats a date time according to a custom format string and appends the appropriate timezone name. The input DateTime's Kind property is ignored (timezone information is stripped). Determines whether DST is active at that moment and appends either the Standard or Daylight timezone name accordingly. Returns the formatted string with timezone abbreviation appended (e.g., '2024-03-15 14:30:00 Eastern Daylight Time').
Parameters:
DateTimeToFormat(DateTime): The date and time to format. The Kind property is ignored - treated as an unspecified moment in time.TimeZone(TimeZone): The timezone used to determine which timezone name to append (Standard or Daylight). Must be a valid TimeZone structure.FormatString(string): The .NET DateTime format string for the date/time portion. Examples: 'yyyy-MM-dd HH:mm:ss', 'MM/dd/yyyy h:mm tt', 'dddd, MMMM dd, yyyy'.
Returns: Formatted date/time string with timezone name appended
Description: Calculates the time difference in hours between two time zones at a specific moment in time. The input DateTime's Kind property is ignored (timezone information is stripped). Gets the UTC offset for both timezones at the specified date/time (accounting for DST if active in either timezone) and returns the difference as decimal hours. The result is TimeZone1's offset minus TimeZone2's offset (positive if TimeZone1 is ahead).
Parameters:
TimeZone1(TimeZone): The first timezone for the comparison. Must be a valid TimeZone structure.TimeZone2(TimeZone): The second timezone for the comparison. Must be a valid TimeZone structure.AtDateTime(DateTime): The date and time at which to calculate the difference. The Kind property is ignored. This is used to determine DST status for both timezones.
Returns: Time difference in decimal hours (TimeZone1 - TimeZone2)
Description: Finds the next Daylight Saving Time transition date for a time zone starting from a given date. Returns null if the timezone doesn't support DST. Searches forward up to 366 days (one year) and returns the exact hour when the DST transition occurs (either entering or exiting DST). The input DateTime's Kind property is ignored. Uses a day-by-day search followed by hour-by-hour refinement to pinpoint the exact transition moment.
Parameters:
TimeZone(TimeZone): The timezone to search for DST transitions. Must be a valid TimeZone structure.FromDate(DateTime): The starting date to begin searching forward from. The Kind property is ignored. Search will continue up to 366 days ahead.
Returns: DateTime of next DST transition, or null if none within 1 year
- OutSystems Developer Cloud (ODC)
- ODC Studio
Contributions are welcome! If you'd like to contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
If you encounter any issues or have questions:
- Open an Issue
- Check existing Discussions
- Review the Wiki documentation
This project is licensed under the MIT License - see the LICENSE file for details.
Ricardo Costa
- Built for the OutSystems Developer Cloud platform
- Inspired by the need for enhanced DateTime operations in low-code development
- Thanks to the OutSystems community for feedback and suggestions
See CHANGELOG.md for a list of changes in each version.
⭐ If you find this library helpful, please consider giving it a star!
📢 Share your feedback and suggestions through Issues