There is, in my opinion, a pretty annoying discrepancy between the rclcpp::Time object member functions and the Builtin Interface Time message. It's annoying in that it can easily catch out developers. It caught me out.

RCLCPP Time Object

The rclcpp::Time object has the following constructors and member functions (only constructors and member functions relevant to the issue are provided):

Constructors:

• Time::Time(int32_t seconds, uint32_t nanoseconds, rcl_clock_type_t clock_type) : rcl_time_(init_time_point(clock_type)) source
• Time::Time(int64_t nanoseconds, rcl_clock_type_t clock_type) : rcl_time_(init_time_point(clock_type)) source
• Time::Time(const builtin_interfaces::msg::Time & time_msg, rcl_clock_type_t clock_type) : rcl_time_(init_time_point(clock_type)) source

Member Functions:

• int64_t Time::nanoseconds() constsource returns total time since epoch (seconds + nanoseconds)
• double Time::seconds() constsource returns total time since epoch (seconds + nanoseconds)

Builtin Interface Time Message

The Builtin Interfaces Time message documentation is as follows:

# Time indicates a specific point in time, relative to a clock's 0 point.

# The seconds component, valid over all int32 values.
int32 sec

# The nanoseconds component, valid in the range [0, 10e9).
uint32 nanosec

Discrepancy

After utilising the Builtin Interface Time Message, and given the first constructor listed in the rclcpp::Time object takes in seconds and nanoseconds separately, one may accidentally assume the seconds and nanoseconds member function returns their component values only and not the total time since epoch.

Potential Fixes

I understand this is a minor issue. However, discrepancies like this cause confusion. Many pieces of code are likely built upon the rclcpp::Time::seconds and rclcpp::Time::nanoseconds functions. However, would any of the following fixes have potential?

1. Swapping the order of the rclcpp::Time constructors so the nanoseconds only constructor comes first?
2. Improving the member function documentation for the rclcpp::Time::seconds and rclcpp::Time::nanoseconds functions. For example, "returns the total time since epoch in seconds (seconds + nanoseconds)".
3. Add member functions to return only the seconds or nanoseconds components, not the total, since epoch?