1 files changed, 262 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_Time.h b/libparc/parc/algol/parc_Time.h
new file mode 100644
index 00000000..2a68144e
--- /dev/null
+++ b/libparc/parc/algol/parc_Time.h
@@ -0,0 +1,262 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file parc_Time.h
+ * @ingroup inputoutput
+ * @brief Time Manipulation
+ *
+ * Different platforms have different ways to express time-of-day, elapsed-time, clock-time.
+ * In some cases multiple ways to express the same semantic value have evolved over time,
+ * for example `struct timeval` and `struct timespec`.
+ *
+ */
+#ifndef libparc_parc_Time_h
+#define libparc_parc_Time_h
+
+#include <sys/time.h>
+#include <stdint.h>
+
+/**
+ * Create a nul-terminated C string containing the formatted representation of a `struct timeval`.
+ *
+ * The minimum length of the result is 8 characters consisting of the `struct timeval`
+ * formatted as a decimal string consisting of the number of seconds since midnight (0 hour), January 1, 1970.
+ *
+ * @param [in] timeval The instance of the struct `timeval` to convert to a C string.
+ * @return An allocated, null-terminated C string that must be freed via {@link parcMemory_Deallocate()}.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval timeval;
+ *     gettimeofday(&timeval, NULL);
+ *
+ *     char *string = parcTime_TimevalAsString(timeval);
+ *
+ *     parcMemory_Deallocate(&string);
+ * }
+ * @endcode
+ */
+char *parcTime_TimevalAsString(struct timeval timeval);
+
+/**
+ * Format an ISO8601 date from the given struct timeval into the given character array, @p result.
+ *
+ * @param [in] utcTime A pointer to a valid struct timeval instance with the time in UTC.
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval theTime;
+ *     gettimeofday(&theTime, NULL);
+ *
+ *     char result[64];
+ *     parcTime_TimevalAsISO8601(&theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_TimevalAsISO8601(const struct timeval *utcTime, char *result);
+
+/**
+ * Format an RFC3339 compliant date from the given struct timeval into the given character array.
+ *
+ * @param [in] utcTime A pointer to a valid struct timeval instance with the time in UTC.
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval theTime;
+ *     gettimeofday(&theTime, NULL);
+ *
+ *     char result[64];
+ *     parcTime_TimevalAsRFC3339(&theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_TimevalAsRFC3339(const struct timeval *utcTime, char *result);
+
+/**
+ * Format an ISO8601 date from the given `time_t` value into the given character array, @p result.
+ *
+ * @param [in] utcTime `time_t` value representing the time in UTC.
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     time_t theTime = time(0);
+ *
+ *     char result[64];
+ *     parcTime_TimeAsISO8601(theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_TimeAsISO8601(const time_t utcTime, char *result);
+
+/**
+ * Format the current time as an ISO8601 date into the given character array, @p result.
+ *
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     char result[64];
+ *     parcTime_NowAsISO8601(theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_NowAsISO8601(char *result);
+
+/**
+ * Format an RFC3339 compliant date from the given `time_t` value into the given character array.
+ *
+ * @param [in] utcTime `time_t` value of the time in UTC.
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval theTime;
+ *     time_t theTime = time(0);
+ *
+ *     char result[64];
+ *     parcTime_TimeAsRFC3339(&theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_TimeAsRFC3339(const time_t utcTime, char *result);
+
+/**
+ * Format the current time as an RFC3339 compliant date into the given character array.
+ *
+ * @param [out] result A pointer to the 64 element nul-terminated character array, @p result.
+ *
+ * @return The same value as @p result.
+ *
+ * Example:
+ * @code
+ * {
+ *     char result[64];
+ *     parcTime_NowAsRFC3339(&theTime, result);
+ *
+ * }
+ * @endcode
+ */
+char *parcTime_NowAsRFC3339(char *result);
+
+/**
+ * Add two `struct timeval` values together.
+ *
+ * @param [in] addend1 The first value.
+ * @param [in] addend2 The second value.
+ *
+ * @return The sum of the first and second values.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval now;
+ *     gettimeofday(&now, NULL);
+ *
+ *     struct timeval theEnd = parcTime_TimevalAdd(&now, timeout);
+ * }
+ * @endcode
+ */
+struct timeval parcTime_TimevalAdd(const struct timeval *addend1, const struct timeval *addend2);
+
+/**
+ * Subtract two `struct timeval` values.
+ *
+ * @param [in] minuend The number from which the subtrahend is to be subtracted.
+ * @param [in] subtrahend The subtrahend.
+ *
+ * @return The difference between the first and second values.
+ *
+ * Example:
+ * @code
+ * {
+ *     struct timeval now;
+ *     gettimeofday(&now, NULL);
+ *
+ *     struct timeval result = parcTime_TimevalSubtract(&now, timeout);
+ * }
+ * @endcode
+ */
+struct timeval parcTime_TimevalSubtract(const struct timeval *minuend, const struct timeval *subtrahend);
+
+/**
+ * The current time as a `struct timeval`.
+ *
+ * @return The current time as a `struct timeval`.
+ *
+ * Example:
+ * @code
+ * {
+ *
+ *     struct timeval now = parcTime_NowTimeval();
+ * }
+ * @endcode
+ */
+struct timeval parcTime_NowTimeval(void);
+
+/**
+ * The current time in microseconds since midnight (0 hour), January 1, 1970 as a `uint64_t`.
+ *
+ * @return The current time in microseconds since midnight (0 hour), January 1, 1970 as a `uint64_t`.
+ *
+ * Example:
+ * @code
+ * {
+ *
+ *     uint64_t now = parcTime_NowMicroseconds();
+ * }
+ * @endcode
+ */
+uint64_t parcTime_NowMicroseconds(void);
+
+/**
+ * The current time in nanoseconds since midnight (0 hour), January 1, 1970 as a `uint64_t`.
+ *
+ * @return The current time in nanoseconds since midnight (0 hour), January 1, 1970 as a `uint64_t`.
+ *
+ * Example:
+ * @code
+ * {
+ *
+ *     uint64_t now = parcTime_NowNanoseconds();
+ * }
+ * @endcode
+ */
+uint64_t parcTime_NowNanoseconds(void);
+#endif // libparc_parc_Time_h