From f5a3ce687dc5eeebc9fd08578be4307507a8a7d8 Mon Sep 17 00:00:00 2001
From: Chris Peterson <cpeterson@mozilla.com>
Date: Mon, 21 Jan 2013 20:50:01 -0800
Subject: [PATCH] Add Timespec comment and assert about negative nsec

---
 src/libstd/time.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/libstd/time.rs b/src/libstd/time.rs
index e1aea994db1..940a4940879 100644
--- a/src/libstd/time.rs
+++ b/src/libstd/time.rs
@@ -20,6 +20,8 @@ use core::prelude::*;
 use core::result::{Result, Ok, Err};
 use core::str;
 
+const NSEC_PER_SEC: i32 = 1_000_000_000_i32;
+
 #[abi = "cdecl"]
 extern mod rustrt {
     #[legacy_exports]
@@ -40,8 +42,17 @@ extern mod rustrt {
 #[auto_decode]
 pub struct Timespec { sec: i64, nsec: i32 }
 
+/*
+ * Timespec assumes that pre-epoch Timespecs have negative sec and positive
+ * nsec fields. Darwin's and Linux's struct timespec functions handle pre-
+ * epoch timestamps using a "two steps back, one step forward" representation,
+ * though the man pages do not actually document this. For example, the time
+ * -1.2 seconds before the epoch is represented by `Timespec { sec: -2_i64,
+ * nsec: 800_000_000_i32 }`.
+ */
 impl Timespec {
     static pure fn new(sec: i64, nsec: i32) -> Timespec {
+        assert nsec >= 0 && nsec < NSEC_PER_SEC;
         Timespec { sec: sec, nsec: nsec }
     }
 }