Add new API functions pa_volume_snprint() and pa_sw_volume_snprint_dB()

src/map-file

@@ -234,6 +234,7 @@ pa_sw_volume_divide;
 pa_sw_volume_from_dB;
 pa_sw_volume_from_linear;
 pa_sw_volume_multiply;
+pa_sw_volume_snprint_dB;
 pa_sw_volume_to_dB;
 pa_sw_volume_to_linear;
 pa_threaded_mainloop_accept;
@@ -259,6 +260,7 @@ pa_usec_to_bytes;
 pa_utf8_filter;
 pa_utf8_to_locale;
 pa_utf8_valid;
+pa_volume_snprint;
 pa_xfree;
 pa_xmalloc;
 pa_xmalloc0;

src/pulse/volume.c

@@ -179,6 +179,21 @@ char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c) {
     return s;
 }
 
+char *pa_volume_snprint(char *s, size_t l, pa_volume_t v) {
+    pa_assert(s);
+    pa_assert(l > 0);
+
+    pa_init_i18n();
+
+    if (v == (pa_volume_t) -1) {
+        pa_snprintf(s, l, _("(invalid)"));
+        return s;
+    }
+
+    pa_snprintf(s, l, "%3u%%", (v*100)/PA_VOLUME_NORM);
+    return s;
+}
+
 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c) {
     unsigned channel;
     pa_bool_t first = TRUE;
@@ -198,10 +213,12 @@ char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c) {
     *(e = s) = 0;
 
     for (channel = 0; channel < c->channels && l > 1; channel++) {
+        double f = pa_sw_volume_to_dB(c->values[channel]);
+
         l -= pa_snprintf(e, l, "%s%u: %0.2f dB",
-                      first ? "" : " ",
-                      channel,
-                      pa_sw_volume_to_dB(c->values[channel]));
+                         first ? "" : " ",
+                         channel,
+                         isinf(f) < 0 || f <= -USER_DECIBEL_RANGE ? -INFINITY : f);
 
         e = strchr(e, 0);
         first = FALSE;
@@ -210,6 +227,26 @@ char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c) {
     return s;
 }
 
+char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v) {
+    double f;
+
+    pa_assert(s);
+    pa_assert(l > 0);
+
+    pa_init_i18n();
+
+    if (v == (pa_volume_t) -1) {
+        pa_snprintf(s, l, _("(invalid)"));
+        return s;
+    }
+
+    f = pa_sw_volume_to_dB(v);
+    pa_snprintf(s, l, "%0.2f dB",
+                isinf(f) < 0 || f <= -USER_DECIBEL_RANGE ?  -INFINITY : f);
+
+    return s;
+}
+
 /** Return non-zero if the volume of all channels is equal to the specified value */
 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) {
     unsigned c;

src/pulse/volume.h

@@ -150,6 +150,26 @@ char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 /** Pretty print a volume structure but show dB values. \since 0.9.13 */
 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
 
+/** Maximum length of the strings returned by
+ * pa_volume_snprint(). Please note that this value can change with
+ * any release without warning and without being considered API or ABI
+ * breakage. You should not use this definition anywhere where it
+ * might become part of an ABI. \since 0.9.14 */
+#define PA_VOLUME_SNPRINT_MAX 10
+
+/** Pretty print a volume \since 0.9.14 */
+char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
+
+/** Maximum length of the strings returned by
+ * pa_volume_snprint_dB(). Please note that this value can change with
+ * any release without warning and without being considered API or ABI
+ * breakage. You should not use this definition anywhere where it
+ * might become part of an ABI. \since 0.9.14 */
+#define PA_SW_VOLUME_SNPRINT_DB_MAX 10
+
+/** Pretty print a volume but show dB values. \since 0.9.14 */
+char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
+
 /** Return the average volume of all channels */
 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;