/* * Copyright (c) 2008-2024 Jonathan Schleifer * * All rights reserved. * * This program is free software: you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License version 3.0 only, * as published by the Free Software Foundation. * * This program is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License * version 3.0 for more details. * * You should have received a copy of the GNU Lesser General Public License * version 3.0 along with this program. If not, see * . */ #import "OFObject.h" #import "OFMessagePackRepresentation.h" OF_ASSUME_NONNULL_BEGIN @class OFString; @class OFConstantString; /** * @class OFDate OFDate.h ObjFW/OFDate.h * * @brief A class for storing, accessing and comparing dates. */ @interface OFDate: OFObject #ifdef OF_HAVE_CLASS_PROPERTIES @property (class, readonly, nonatomic) OFDate *distantFuture; @property (class, readonly, nonatomic) OFDate *distantPast; #endif /** * @brief The microsecond of the date. */ @property (readonly, nonatomic) unsigned long microsecond; /** * @brief The second of the date. */ @property (readonly, nonatomic) unsigned char second; /** * @brief The minute of the date. */ @property (readonly, nonatomic) unsigned char minute; /** * @brief The minute of the date in local time. */ @property (readonly, nonatomic) unsigned char localMinute; /** * @brief The hour of the date. */ @property (readonly, nonatomic) unsigned char hour; /** * @brief The hour of the date in local time. */ @property (readonly, nonatomic) unsigned char localHour; /** * @brief The day of the month of the date. */ @property (readonly, nonatomic) unsigned char dayOfMonth; /** * @brief The day of the month of the date in local time. */ @property (readonly, nonatomic) unsigned char localDayOfMonth; /** * @brief The month of the year of the date. */ @property (readonly, nonatomic) unsigned char monthOfYear; /** * @brief The month of the year of the date in local time. */ @property (readonly, nonatomic) unsigned char localMonthOfYear; /** * @brief The year of the date. */ @property (readonly, nonatomic) unsigned short year; /** * @brief The year of the date in local time. */ @property (readonly, nonatomic) unsigned short localYear; /** * @brief The day of the week of the date. */ @property (readonly, nonatomic) unsigned char dayOfWeek; /** * @brief The day of the week of the date in local time. */ @property (readonly, nonatomic) unsigned char localDayOfWeek; /** * @brief The day of the year of the date. */ @property (readonly, nonatomic) unsigned short dayOfYear; /** * @brief The day of the year of the date in local time. */ @property (readonly, nonatomic) unsigned short localDayOfYear; /** * @brief The seconds since 1970-01-01T00:00:00Z. */ @property (readonly, nonatomic) OFTimeInterval timeIntervalSince1970; /** * @brief The seconds the date is in the future. */ @property (readonly, nonatomic) OFTimeInterval timeIntervalSinceNow; /** * @brief Creates a new OFDate with the current date and time. * * @return A new, autoreleased OFDate with the current date and time */ + (instancetype)date; /** * @brief Creates a new OFDate with the specified date and time since * 1970-01-01T00:00:00Z. * * @param seconds The seconds since 1970-01-01T00:00:00Z * @return A new, autoreleased OFDate with the specified date and time */ + (instancetype)dateWithTimeIntervalSince1970: (OFTimeInterval)seconds; /** * @brief Creates a new OFDate with the specified date and time since now. * * @param seconds The seconds since now * @return A new, autoreleased OFDate with the specified date and time */ + (instancetype)dateWithTimeIntervalSinceNow: (OFTimeInterval)seconds; /** * @brief Creates a new OFDate with the specified string in the specified * format. * * The time zone used is UTC. See @ref dateWithLocalDateString:format: if you * want local time. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%a, %%b, %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%z, %%, %%n and * %%t. * * @param string The string describing the date * @param format The format of the string describing the date * @return A new, autoreleased OFDate with the specified date and time * @throw OFInvalidFormatException The specified format is invalid */ + (instancetype)dateWithDateString: (OFString *)string format: (OFString *)format; /** * @brief Creates a new OFDate with the specified string in the specified * format. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%a, %%b, %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%z, %%, %%n and * %%t. * * @param string The string describing the date * @param format The format of the string describing the date * @return A new, autoreleased OFDate with the specified date and time * @throw OFInvalidFormatException The specified format is invalid */ + (instancetype)dateWithLocalDateString: (OFString *)string format: (OFString *)format; /** * @brief Returns a date in the distant future. * * The date is system-dependent. * * @return A date in the distant future */ + (instancetype)distantFuture; /** * @brief Returns a date in the distant past. * * The date is system-dependent. * * @return A date in the distant past */ + (instancetype)distantPast; /** * @brief Initializes an already allocated OFDate with the specified date and * time since 1970-01-01T00:00:00Z. * * @param seconds The seconds since 1970-01-01T00:00:00Z * @return An initialized OFDate with the specified date and time */ - (instancetype)initWithTimeIntervalSince1970: (OFTimeInterval)seconds OF_DESIGNATED_INITIALIZER; /** * @brief Initializes an already allocated OFDate with the specified date and * time since now. * * @param seconds The seconds since now * @return An initialized OFDate with the specified date and time */ - (instancetype)initWithTimeIntervalSinceNow: (OFTimeInterval)seconds; /** * @brief Initializes an already allocated OFDate with the specified string in * the specified format. * * The time zone used is UTC. If a time zone is specified anyway, an * OFInvalidFormatException is thrown. See @ref initWithLocalDateString:format: * if you want to specify a time zone. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t. * * @param string The string describing the date * @param format The format of the string describing the date * @return An initialized OFDate with the specified date and time * @throw OFInvalidFormatException The specified format is invalid */ - (instancetype)initWithDateString: (OFString *)string format: (OFString *)format; /** * @brief Initializes an already allocated OFDate with the specified string in * the specified format. * * If no time zone is specified, local time is assumed. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%, %%n and %%t. * * @param string The string describing the date * @param format The format of the string describing the date * @return An initialized OFDate with the specified date and time * @throw OFInvalidFormatException The specified format is invalid */ - (instancetype)initWithLocalDateString: (OFString *)string format: (OFString *)format; /** * @brief Compares the date to another date. * * @param date The date to compare the date to * @return The result of the comparison */ - (OFComparisonResult)compare: (OFDate *)date; /** * @brief Creates a string of the date with the specified format. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%a, %%b, %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%z, %%, %%n and * %%t. * * @param format The format for the date string * @return A new, autoreleased OFString * @throw OFInvalidFormatException The specified format is invalid */ - (OFString *)dateStringWithFormat: (OFConstantString *)format; /** * @brief Creates a string of the local date with the specified format. * * See the man page for `strftime` for information on the format. * * @warning The format is currently limited to the following format specifiers: * %%a, %%b, %%d, %%e, %%H, %%m, %%M, %%S, %%y, %%Y, %%z, %%, %%n and * %%t. * * @param format The format for the date string * @return A new, autoreleased OFString * @throw OFInvalidFormatException The specified format is invalid */ - (OFString *)localDateStringWithFormat: (OFConstantString *)format; /** * @brief Returns the earlier of the two dates. * * If the argument is `nil`, it returns the receiver. * * @param otherDate Another date * @return The earlier date of the two dates */ - (OFDate *)earlierDate: (nullable OFDate *)otherDate; /** * @brief Returns the later of the two dates. * * If the argument is `nil`, it returns the receiver. * * @param otherDate Another date * @return The later date of the two dates */ - (OFDate *)laterDate: (nullable OFDate *)otherDate; /** * @brief Returns the seconds the receiver is after the date. * * @param otherDate Date date to generate the difference with receiver * @return The seconds the receiver is after the date. */ - (OFTimeInterval)timeIntervalSinceDate: (OFDate *)otherDate; /** * @brief Creates a new date with the specified time interval added. * * @param seconds The seconds after the date * @return A new, autoreleased OFDate */ - (OFDate *)dateByAddingTimeInterval: (OFTimeInterval)seconds; @end OF_ASSUME_NONNULL_END