summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
author卜部昌平 <shyouhei@ruby-lang.org>2021-02-08 11:32:11 +0900
committer卜部昌平 <shyouhei@ruby-lang.org>2021-09-10 20:00:06 +0900
commita88bd246cafc584ddaccef45b31b35a42f3cdd50 (patch)
treeef683fce582070d9e3b1f55777690c1708c0e3e5
parentcbf9fc6b0210488713750ca7b53de2b83d667e05 (diff)
include/ruby/internal/intern/time.h: add doxygen
Must not be a bad idea to improve documents. [ci skip]
Notes
Notes: Merged: https://github.com/ruby/ruby/pull/4815
-rw-r--r--include/ruby/internal/intern/time.h120
-rw-r--r--time.c5
2 files changed, 115 insertions, 10 deletions
diff --git a/include/ruby/internal/intern/time.h b/include/ruby/internal/intern/time.h
index b0e368b0cf..df482862eb 100644
--- a/include/ruby/internal/intern/time.h
+++ b/include/ruby/internal/intern/time.h
@@ -26,6 +26,7 @@
# include <time.h> /* for time_t */
#endif
+#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
@@ -35,15 +36,124 @@ struct timespec;
struct timeval;
/* time.c */
-void rb_timespec_now(struct timespec *);
-VALUE rb_time_new(time_t, long);
-VALUE rb_time_nano_new(time_t, long);
-VALUE rb_time_timespec_new(const struct timespec *, int);
-VALUE rb_time_num_new(VALUE, VALUE);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Fills the current time into the given struct.
+ *
+ * @param[out] ts Return buffer.
+ * @exception rb_eSystemCallError Access denied for hardware clock.
+ * @post Current time is stored in `*ts`.
+ */
+void rb_timespec_now(struct timespec *ts);
+
+/**
+ * Creates an instance of ::rb_cTime with the given time and the local
+ * timezone.
+ *
+ * @param[in] sec Seconds since the UNIX epoch.
+ * @param[in] usec Subsecond part, in microseconds resolution.
+ * @exception rb_eRangeError Cannot express the time.
+ * @return An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_new(time_t sec, long usec);
+
+/**
+ * Identical to rb_time_new(), except it accepts the time in nanoseconds
+ * resolution.
+ *
+ * @param[in] sec Seconds since the UNIX epoch.
+ * @param[in] nsec Subsecond part, in nanoseconds resolution.
+ * @exception rb_eRangeError Cannot express the time.
+ * @return An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_nano_new(time_t sec, long nsec);
+
+RBIMPL_ATTR_NONNULL(())
+/**
+ * Creates an instance of ::rb_cTime, with given time and offset.
+ *
+ * @param[in] ts Time specifier.
+ * @param[in] offset Offset specifier, can take following values:
+ * - `INT_MAX`: `ts` is in local time.
+ * - `INT_MAX - 1`: `ts` is in UTC.
+ * - `-86400` to `86400`: fixed timezone.
+ * @exception rb_eArgError Malformed `offset`.
+ * @return An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_timespec_new(const struct timespec *ts, int offset);
+
+/**
+ * Identical to rb_time_timespec_new(), except it takes Ruby values instead of
+ * C structs.
+ *
+ * @param[in] timev Something numeric. Currently Integers, Rationals,
+ * and Floats are accepted.
+ * @param[in] off Offset specifier. As of 2.7 this argument is
+ * heavily extended to take following kinds of
+ * objects:
+ * - ::RUBY_Qundef ... means UTC.
+ * - ::rb_cString ... "+12:34" etc.
+ * - A mysterious "zone" object. This is largely
+ * undocumented. However the initial intent was
+ * that we want to accept
+ * `ActiveSupport::TimeZone` here. Other gems
+ * could also be possible... But how to make an
+ * acceptable class is beyond this document.
+ * @exception rb_eArgError Malformed `off`.
+ * @return An allocated instance of ::rb_cTime.
+ */
+VALUE rb_time_num_new(VALUE timev, VALUE off);
+
+/**
+ * Creates a "time interval". This basically converts an instance of
+ * ::rb_cNumeric into a struct `timeval`, but for instance negative time
+ * interval must not exist.
+ *
+ * @param[in] num An instance of ::rb_cNumeric.
+ * @exception rb_eArgError `num` is negative.
+ * @exception rb_eRangeError `num` is out of range of `timeval::tv_sec`.
+ * @return A struct that represents the identical time to `num`.
+ */
struct timeval rb_time_interval(VALUE num);
+
+/**
+ * Converts an instance of rb_cTime to a struct timeval that represents the
+ * identical point of time. It can also take something numeric; would consider
+ * it as a UNIX time then.
+ *
+ * @param[in] time Instance of either ::rb_cTime or ::rb_cNumeric.
+ * @exception rb_eRangeError `time` is out of range of `timeval::tv_sec`.
+ * @return A struct that represents the identical time to `num`.
+ */
struct timeval rb_time_timeval(VALUE time);
+
+/**
+ * Identical to rb_time_timeval(), except for return type.
+ *
+ * @param[in] time Instance of either ::rb_cTime or ::rb_cNumeric.
+ * @exception rb_eRangeError `time` is out of range of `timeval::tv_sec`.
+ * @return A struct that represents the identical time to `num`.
+ */
struct timespec rb_time_timespec(VALUE time);
+
+/**
+ * Identical to rb_time_interval(), except for return type.
+ *
+ * @param[in] num An instance of ::rb_cNumeric.
+ * @exception rb_eArgError `num` is negative.
+ * @exception rb_eRangeError `num` is out of range of `timespec::tv_sec`.
+ * @return A struct that represents the identical time to `num`.
+ */
struct timespec rb_time_timespec_interval(VALUE num);
+
+/**
+ * Queries the offset, in seconds between the time zone of the time and the
+ * UTC.
+ *
+ * @param[in] time An instance of ::rb_cTime.
+ * @return Numeric offset.
+ */
VALUE rb_time_utc_offset(VALUE time);
RBIMPL_SYMBOL_EXPORT_END()
diff --git a/time.c b/time.c
index fb2f671fe0..a459f56dc2 100644
--- a/time.c
+++ b/time.c
@@ -2474,11 +2474,6 @@ rb_time_nano_new(time_t sec, long nsec)
return time_new_timew(rb_cTime, nsec2timew(sec, nsec));
}
-/**
- * Returns a time object with UTC/localtime/fixed offset
- *
- * offset is -86400 < fixoff < 86400 or INT_MAX (localtime) or INT_MAX-1 (utc)
- */
VALUE
rb_time_timespec_new(const struct timespec *ts, int offset)
{