strutil.c

   1 /*
   2  * This file is part of the libsigrok project.
   3  *
   4  * Copyright (C) 2010 Uwe Hermann <uwe@hermann-uwe.de>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19  */
  20
  21 #include <stdint.h>
  22 #include <stdlib.h>
  23 #include <string.h>
  24 #include <errno.h>
  25 #include "libsigrok.h"
  26 #include "libsigrok-internal.h"
  27
  28 /** @cond PRIVATE */
  29 #define LOG_PREFIX "strutil"
  30 /** @endcond */
  31
  32 /**
  33  * @file
  34  *
  35  * Helper functions for handling or converting libsigrok-related strings.
  36  */
  37
  38 /**
  39  * @defgroup grp_strutil String utilities
  40  *
  41  * Helper functions for handling or converting libsigrok-related strings.
  42  *
  43  * @{
  44  */
  45
  46 /**
  47  * @private
  48  *
  49  * Convert a string representation of a numeric value (base 10) to a long integer. The
  50  * conversion is strict and will fail if the complete string does not represent
  51  * a valid long integer. The function sets errno according to the details of the
  52  * failure.
  53  *
  54  * @param str The string representation to convert.
  55  * @param ret Pointer to long where the result of the conversion will be stored.
  56  *
  57  * @retval SR_OK Conversion successful.
  58  * @retval SR_ERR Failure.
  59  *
  60  * @since 0.3.0
  61  */
  62 SR_PRIV int sr_atol(const char *str, long *ret)
  63 {
  64         long tmp;
  65         char *endptr = NULL;
  66
  67         errno = 0;
  68         tmp = strtol(str, &endptr, 10);
  69
  70         if (!endptr || *endptr || errno) {
  71                 if (!errno)
  72                         errno = EINVAL;
  73                 return SR_ERR;
  74         }
  75
  76         *ret = tmp;
  77         return SR_OK;
  78 }
  79
  80 /**
  81  * @private
  82  *
  83  * Convert a string representation of a numeric value (base 10) to an integer. The
  84  * conversion is strict and will fail if the complete string does not represent
  85  * a valid integer. The function sets errno according to the details of the
  86  * failure.
  87  *
  88  * @param str The string representation to convert.
  89  * @param ret Pointer to int where the result of the conversion will be stored.
  90  *
  91  * @retval SR_OK Conversion successful.
  92  * @retval SR_ERR Failure.
  93  *
  94  * @since 0.3.0
  95  */
  96 SR_PRIV int sr_atoi(const char *str, int *ret)
  97 {
  98         long tmp;
  99
 100         if (sr_atol(str, &tmp) != SR_OK)
 101                 return SR_ERR;
 102
 103         if ((int) tmp != tmp) {
 104                 errno = ERANGE;
 105                 return SR_ERR;
 106         }
 107
 108         *ret = (int) tmp;
 109         return SR_OK;
 110 }
 111
 112 /**
 113  * @private
 114  *
 115  * Convert a string representation of a numeric value to a double. The
 116  * conversion is strict and will fail if the complete string does not represent
 117  * a valid double. The function sets errno according to the details of the
 118  * failure.
 119  *
 120  * @param str The string representation to convert.
 121  * @param ret Pointer to double where the result of the conversion will be stored.
 122  *
 123  * @retval SR_OK Conversion successful.
 124  * @retval SR_ERR Failure.
 125  *
 126  * @since 0.3.0
 127  */
 128 SR_PRIV int sr_atod(const char *str, double *ret)
 129 {
 130         double tmp;
 131         char *endptr = NULL;
 132
 133         errno = 0;
 134         tmp = strtof(str, &endptr);
 135
 136         if (!endptr || *endptr || errno) {
 137                 if (!errno)
 138                         errno = EINVAL;
 139                 return SR_ERR;
 140         }
 141
 142         *ret = tmp;
 143         return SR_OK;
 144 }
 145
 146 /**
 147  * @private
 148  *
 149  * Convert a string representation of a numeric value to a float. The
 150  * conversion is strict and will fail if the complete string does not represent
 151  * a valid float. The function sets errno according to the details of the
 152  * failure.
 153  *
 154  * @param str The string representation to convert.
 155  * @param ret Pointer to float where the result of the conversion will be stored.
 156  *
 157  * @retval SR_OK Conversion successful.
 158  * @retval SR_ERR Failure.
 159  *
 160  * @since 0.3.0
 161  */
 162 SR_PRIV int sr_atof(const char *str, float *ret)
 163 {
 164         double tmp;
 165
 166         if (sr_atod(str, &tmp) != SR_OK)
 167                 return SR_ERR;
 168
 169         if ((float) tmp != tmp) {
 170                 errno = ERANGE;
 171                 return SR_ERR;
 172         }
 173
 174         *ret = (float) tmp;
 175         return SR_OK;
 176 }
 177
 178 /**
 179  * @private
 180  *
 181  * Convert a string representation of a numeric value to a float. The
 182  * conversion is strict and will fail if the complete string does not represent
 183  * a valid float. The function sets errno according to the details of the
 184  * failure. This version ignores the locale.
 185  *
 186  * @param str The string representation to convert.
 187  * @param ret Pointer to float where the result of the conversion will be stored.
 188  *
 189  * @retval SR_OK Conversion successful.
 190  * @retval SR_ERR Failure.
 191  *
 192  * @since 0.3.0
 193  */
 194 SR_PRIV int sr_atof_ascii(const char *str, float *ret)
 195 {
 196         double tmp;
 197         char *endptr = NULL;
 198
 199         errno = 0;
 200         tmp = g_ascii_strtod(str, &endptr);
 201
 202         if (!endptr || *endptr || errno) {
 203                 if (!errno)
 204                         errno = EINVAL;
 205                 return SR_ERR;
 206         }
 207
 208         /* FIXME This fails unexpectedly. Some other method to safel downcast
 209          * needs to be found. Checking against FLT_MAX doesn't work as well. */
 210         /*
 211         if ((float) tmp != tmp) {
 212                 errno = ERANGE;
 213                 sr_dbg("ERANGEEEE %e != %e", (float) tmp, tmp);
 214                 return SR_ERR;
 215         }
 216         */
 217
 218         *ret = (float) tmp;
 219         return SR_OK;
 220 }
 221
 222 /**
 223  * Convert a numeric value value to its "natural" string representation
 224  * in SI units.
 225  *
 226  * E.g. a value of 3000000, with units set to "W", would be converted
 227  * to "3 MW", 20000 to "20 kW", 31500 would become "31.5 kW".
 228  *
 229  * @param x The value to convert.
 230  * @param unit The unit to append to the string, or NULL if the string
 231  *             has no units.
 232  *
 233  * @return A g_try_malloc()ed string representation of the samplerate value,
 234  *         or NULL upon errors. The caller is responsible to g_free() the
 235  *         memory.
 236  *
 237  * @since 0.2.0
 238  */
 239 SR_API char *sr_si_string_u64(uint64_t x, const char *unit)
 240 {
 241         uint8_t i;
 242         uint64_t quot, divisor[] = {
 243                 SR_HZ(1), SR_KHZ(1), SR_MHZ(1), SR_GHZ(1),
 244                 SR_GHZ(1000), SR_GHZ(1000 * 1000), SR_GHZ(1000 * 1000 * 1000),
 245         };
 246         const char *p, prefix[] = "\0kMGTPE";
 247         char fmt[16], fract[20] = "", *f;
 248
 249         if (unit == NULL)
 250                 unit = "";
 251
 252         for (i = 0; (quot = x / divisor[i]) >= 1000; i++);
 253
 254         if (i) {
 255                 sprintf(fmt, ".%%0%d"PRIu64, i * 3);
 256                 f = fract + sprintf(fract, fmt, x % divisor[i]) - 1;
 257
 258                 while (f >= fract && strchr("0.", *f))
 259                         *f-- = 0;
 260         }
 261
 262         p = prefix + i;
 263
 264         return g_strdup_printf("%" PRIu64 "%s %.1s%s", quot, fract, p, unit);
 265 }
 266
 267 /**
 268  * Convert a numeric samplerate value to its "natural" string representation.
 269  *
 270  * E.g. a value of 3000000 would be converted to "3 MHz", 20000 to "20 kHz",
 271  * 31500 would become "31.5 kHz".
 272  *
 273  * @param samplerate The samplerate in Hz.
 274  *
 275  * @return A g_try_malloc()ed string representation of the samplerate value,
 276  *         or NULL upon errors. The caller is responsible to g_free() the
 277  *         memory.
 278  *
 279  * @since 0.1.0
 280  */
 281 SR_API char *sr_samplerate_string(uint64_t samplerate)
 282 {
 283         return sr_si_string_u64(samplerate, "Hz");
 284 }
 285
 286 /**
 287  * Convert a numeric frequency value to the "natural" string representation
 288  * of its period.
 289  *
 290  * E.g. a value of 3000000 would be converted to "3 us", 20000 to "50 ms".
 291  *
 292  * @param frequency The frequency in Hz.
 293  *
 294  * @return A g_try_malloc()ed string representation of the frequency value,
 295  *         or NULL upon errors. The caller is responsible to g_free() the
 296  *         memory.
 297  *
 298  * @since 0.1.0
 299  */
 300 SR_API char *sr_period_string(uint64_t frequency)
 301 {
 302         char *o;
 303         int r;
 304
 305         /* Allocate enough for a uint64_t as string + " ms". */
 306         if (!(o = g_try_malloc0(30 + 1))) {
 307                 sr_err("%s: o malloc failed", __func__);
 308                 return NULL;
 309         }
 310
 311         if (frequency >= SR_GHZ(1))
 312                 r = snprintf(o, 30, "%" PRIu64 " ns", frequency / 1000000000);
 313         else if (frequency >= SR_MHZ(1))
 314                 r = snprintf(o, 30, "%" PRIu64 " us", frequency / 1000000);
 315         else if (frequency >= SR_KHZ(1))
 316                 r = snprintf(o, 30, "%" PRIu64 " ms", frequency / 1000);
 317         else
 318                 r = snprintf(o, 30, "%" PRIu64 " s", frequency);
 319
 320         if (r < 0) {
 321                 /* Something went wrong... */
 322                 g_free(o);
 323                 return NULL;
 324         }
 325
 326         return o;
 327 }
 328
 329 /**
 330  * Convert a numeric voltage value to the "natural" string representation
 331  * of its voltage value. The voltage is specified as a rational number's
 332  * numerator and denominator.
 333  *
 334  * E.g. a value of 300000 would be converted to "300mV", 2 to "2V".
 335  *
 336  * @param v_p The voltage numerator.
 337  * @param v_q The voltage denominator.
 338  *
 339  * @return A g_try_malloc()ed string representation of the voltage value,
 340  *         or NULL upon errors. The caller is responsible to g_free() the
 341  *         memory.
 342  *
 343  * @since 0.2.0
 344  */
 345 SR_API char *sr_voltage_string(uint64_t v_p, uint64_t v_q)
 346 {
 347         int r;
 348         char *o;
 349
 350         if (!(o = g_try_malloc0(30 + 1))) {
 351                 sr_err("%s: o malloc failed", __func__);
 352                 return NULL;
 353         }
 354
 355         if (v_q == 1000)
 356                 r = snprintf(o, 30, "%" PRIu64 "mV", v_p);
 357         else if (v_q == 1)
 358                 r = snprintf(o, 30, "%" PRIu64 "V", v_p);
 359         else
 360                 r = snprintf(o, 30, "%gV", (float)v_p / (float)v_q);
 361
 362         if (r < 0) {
 363                 /* Something went wrong... */
 364                 g_free(o);
 365                 return NULL;
 366         }
 367
 368         return o;
 369 }
 370
 371 /**
 372  * Convert a "natural" string representation of a size value to uint64_t.
 373  *
 374  * E.g. a value of "3k" or "3 K" would be converted to 3000, a value
 375  * of "15M" would be converted to 15000000.
 376  *
 377  * Value representations other than decimal (such as hex or octal) are not
 378  * supported. Only 'k' (kilo), 'm' (mega), 'g' (giga) suffixes are supported.
 379  * Spaces (but not other whitespace) between value and suffix are allowed.
 380  *
 381  * @param sizestring A string containing a (decimal) size value.
 382  * @param size Pointer to uint64_t which will contain the string's size value.
 383  *
 384  * @return SR_OK upon success, SR_ERR upon errors.
 385  *
 386  * @since 0.1.0
 387  */
 388 SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
 389 {
 390         int multiplier, done;
 391         double frac_part;
 392         char *s;
 393
 394         *size = strtoull(sizestring, &s, 10);
 395         multiplier = 0;
 396         frac_part = 0;
 397         done = FALSE;
 398         while (s && *s && multiplier == 0 && !done) {
 399                 switch (*s) {
 400                 case ' ':
 401                         break;
 402                 case '.':
 403                         frac_part = g_ascii_strtod(s, &s);
 404                         break;
 405                 case 'k':
 406                 case 'K':
 407                         multiplier = SR_KHZ(1);
 408                         break;
 409                 case 'm':
 410                 case 'M':
 411                         multiplier = SR_MHZ(1);
 412                         break;
 413                 case 'g':
 414                 case 'G':
 415                         multiplier = SR_GHZ(1);
 416                         break;
 417                 default:
 418                         done = TRUE;
 419                         s--;
 420                 }
 421                 s++;
 422         }
 423         if (multiplier > 0) {
 424                 *size *= multiplier;
 425                 *size += frac_part * multiplier;
 426         } else
 427                 *size += frac_part;
 428
 429         if (*s && strcasecmp(s, "Hz"))
 430                 return SR_ERR;
 431
 432         return SR_OK;
 433 }
 434
 435 /**
 436  * Convert a "natural" string representation of a time value to an
 437  * uint64_t value in milliseconds.
 438  *
 439  * E.g. a value of "3s" or "3 s" would be converted to 3000, a value
 440  * of "15ms" would be converted to 15.
 441  *
 442  * Value representations other than decimal (such as hex or octal) are not
 443  * supported. Only lower-case "s" and "ms" time suffixes are supported.
 444  * Spaces (but not other whitespace) between value and suffix are allowed.
 445  *
 446  * @param timestring A string containing a (decimal) time value.
 447  * @return The string's time value as uint64_t, in milliseconds.
 448  *
 449  * @todo Add support for "m" (minutes) and others.
 450  * @todo Add support for picoseconds?
 451  * @todo Allow both lower-case and upper-case? If no, document it.
 452  *
 453  * @since 0.1.0
 454  */
 455 SR_API uint64_t sr_parse_timestring(const char *timestring)
 456 {
 457         uint64_t time_msec;
 458         char *s;
 459
 460         /* TODO: Error handling, logging. */
 461
 462         time_msec = strtoull(timestring, &s, 10);
 463         if (time_msec == 0 && s == timestring)
 464                 return 0;
 465
 466         if (s && *s) {
 467                 while (*s == ' ')
 468                         s++;
 469                 if (!strcmp(s, "s"))
 470                         time_msec *= 1000;
 471                 else if (!strcmp(s, "ms"))
 472                         ; /* redundant */
 473                 else
 474                         return 0;
 475         }
 476
 477         return time_msec;
 478 }
 479
 480 /** @since 0.1.0 */
 481 SR_API gboolean sr_parse_boolstring(const char *boolstr)
 482 {
 483         if (!boolstr)
 484                 return FALSE;
 485
 486         if (!g_ascii_strncasecmp(boolstr, "true", 4) ||
 487             !g_ascii_strncasecmp(boolstr, "yes", 3) ||
 488             !g_ascii_strncasecmp(boolstr, "on", 2) ||
 489             !g_ascii_strncasecmp(boolstr, "1", 1))
 490                 return TRUE;
 491
 492         return FALSE;
 493 }
 494
 495 /** @since 0.2.0 */
 496 SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
 497 {
 498         char *s;
 499
 500         *p = strtoull(periodstr, &s, 10);
 501         if (*p == 0 && s == periodstr)
 502                 /* No digits found. */
 503                 return SR_ERR_ARG;
 504
 505         if (s && *s) {
 506                 while (*s == ' ')
 507                         s++;
 508                 if (!strcmp(s, "fs"))
 509                         *q = 1000000000000000ULL;
 510                 else if (!strcmp(s, "ps"))
 511                         *q = 1000000000000ULL;
 512                 else if (!strcmp(s, "ns"))
 513                         *q = 1000000000ULL;
 514                 else if (!strcmp(s, "us"))
 515                         *q = 1000000;
 516                 else if (!strcmp(s, "ms"))
 517                         *q = 1000;
 518                 else if (!strcmp(s, "s"))
 519                         *q = 1;
 520                 else
 521                         /* Must have a time suffix. */
 522                         return SR_ERR_ARG;
 523         }
 524
 525         return SR_OK;
 526 }
 527
 528 /** @since 0.2.0 */
 529 SR_API int sr_parse_voltage(const char *voltstr, uint64_t *p, uint64_t *q)
 530 {
 531         char *s;
 532
 533         *p = strtoull(voltstr, &s, 10);
 534         if (*p == 0 && s == voltstr)
 535                 /* No digits found. */
 536                 return SR_ERR_ARG;
 537
 538         if (s && *s) {
 539                 while (*s == ' ')
 540                         s++;
 541                 if (!strcasecmp(s, "mv"))
 542                         *q = 1000L;
 543                 else if (!strcasecmp(s, "v"))
 544                         *q = 1;
 545                 else
 546                         /* Must have a base suffix. */
 547                         return SR_ERR_ARG;
 548         }
 549
 550         return SR_OK;
 551 }
 552
 553 /** @} */