Handle corner cases more appropriately.

(1) Color channels which may fall outside the valid ranges due rounding
    errors caused by floating point arithmetics are now clamped into
    their respective ranges.

    Fixes #8.

(2) Make rgb2hpluv() return integer indicating whether the result falls
    into the valid HPLuv color space or not. Also improve documentation
    of the function to make clear the returned saturation is outside
    the expected range for RGB triplets not representable in HPLuv.

    Fixes #6.

src/hsluv.c

@@ -32,6 +32,10 @@
 #include <math.h>
 
 
+#define CLAMP(val, min_val, max_val)        \
+    ((val) < (min_val) ? (min_val) : ((val) > (max_val) ? (max_val) : (val)))
+
+
 typedef struct Triplet_tag Triplet;
 struct Triplet_tag {
     double a;
@@ -402,9 +406,9 @@ hsluv2rgb(double h, double s, double l, double* pr, double* pg, double* pb)
     luv2xyz(&tmp);
     xyz2rgb(&tmp);
 
-    *pr = tmp.a;
-    *pg = tmp.b;
-    *pb = tmp.c;
+    *pr = CLAMP(tmp.a, 0.0, 1.0);
+    *pg = CLAMP(tmp.b, 0.0, 1.0);
+    *pb = CLAMP(tmp.c, 0.0, 1.0);
 }
 
 void
@@ -417,9 +421,9 @@ hpluv2rgb(double h, double s, double l, double* pr, double* pg, double* pb)
     luv2xyz(&tmp);
     xyz2rgb(&tmp);
 
-    *pr = tmp.a;
-    *pg = tmp.b;
-    *pb = tmp.c;
+    *pr = CLAMP(tmp.a, 0.0, 1.0);
+    *pg = CLAMP(tmp.b, 0.0, 1.0);
+    *pb = CLAMP(tmp.c, 0.0, 1.0);
 }
 
 void
@@ -432,12 +436,12 @@ rgb2hsluv(double r, double g, double b, double* ph, double* ps, double* pl)
     luv2lch(&tmp);
     lch2hsluv(&tmp);
 
-    *ph = tmp.a;
-    *ps = tmp.b;
-    *pl = tmp.c;
+    *ph = CLAMP(tmp.a, 0.0, 360.0);
+    *ps = CLAMP(tmp.b, 0.0, 100.0);
+    *pl = CLAMP(tmp.c, 0.0, 100.0);
 }
 
-void
+int
 rgb2hpluv(double r, double g, double b, double* ph, double* ps, double* pl)
 {
     Triplet tmp = { r, g, b };
@@ -447,7 +451,11 @@ rgb2hpluv(double r, double g, double b, double* ph, double* ps, double* pl)
     luv2lch(&tmp);
     lch2hpluv(&tmp);
 
-    *ph = tmp.a;
+    *ph = CLAMP(tmp.a, 0.0, 360.0);
+    /* Do NOT clamp the saturation. Application may want to have an idea
+     * how much off the valid range the given RGB color is. */
     *ps = tmp.b;
-    *pl = tmp.c;
+    *pl = CLAMP(tmp.c, 0.0, 100.0);
+
+    return (0.0 <= tmp.b  &&  tmp.b <= 100.0) ? 0 : -1;
 }

src/hsluv.h

@@ -73,17 +73,37 @@ void hpluv2rgb(double h, double s, double l, double* pr, double* pg, double* pb)
 /**
  * Convert RGB to HPLuv.
  *
+ * Note that HPLuv color space does not cover all the colors of RGB color
+ * space. More specifically, some valid RGB triplets may correspond to colors
+ * whose saturation is not representable in the HPLuv color space and falls
+ * outside the valid range between 0.0 and 100.0.
+ *
+ * Application can still get closest color correctly representable in the HPLuv
+ * color space by clamping the saturation into the valid range:
+ *
+ * @code C
+ * ...
+ * if(rgb2hpluv(r, g, b, &h, &s, &v) != 0) {
+ *     if(s < 0.0)
+ *         s = 0.0;
+ *     if(s > 100.0)
+ *         s = 100.0;
+ * }
+ * ...
+ * @endcode
+ *
  * @param r Red component. Between 0.0 and 1.0.
  * @param g Green component. Between 0.0 and 1.0.
  * @param b Blue component. Between 0.0 and 1.0.
  * @param[out] ph Hue. Between 0.0 and 360.0.
- * @param[out] ps Saturation. Between 0.0 and 100.0.
+ * @param[out] ps Saturation. Between 0.0 and 100.0 if the input is
+ * representable in HPLuv color space; and outside the range if it's not.
  * @param[out] pl Lightness. Between 0.0 and 100.0.
  *
- * Note that HPLuv does not contain all the colors of RGB, so converting
- * arbitrary RGB to it may generate invalid HPLuv colors.
+ * @return Returns 0 if the RGB triplet is representable in the HPLuv color
+ * space, -1 otherwise.
  */
-void rgb2hpluv(double r, double g, double b, double* ph, double* ps, double* pl);
+int rgb2hpluv(double r, double g, double b, double* ph, double* ps, double* pl);
 
 
 #ifdef __cplusplus