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  * Parse a trigger specification string.
 373  *
 374  * @param sdi The device instance for which the trigger specification is
 375  *            intended. Must not be NULL. Also, sdi->driver and
 376  *            sdi->driver->info_get must not be NULL.
 377  * @param triggerstring The string containing the trigger specification for
 378  *        one or more channels of this device. Entries for multiple channels are
 379  *        comma-separated. Triggers are specified in the form key=value,
 380  *        where the key is a channel number (or channel name) and the value is
 381  *        the requested trigger type. Valid trigger types currently
 382  *        include 'r' (rising edge), 'f' (falling edge), 'c' (any pin value
 383  *        change), '0' (low value), or '1' (high value).
 384  *        Example: "1=r,sck=f,miso=0,7=c"
 385  *
 386  * @return Pointer to a list of trigger types (strings), or NULL upon errors.
 387  *         The pointer list (if non-NULL) has as many entries as the
 388  *         respective device has channels (all physically available channels,
 389  *         not just enabled ones). Entries of the list which don't have
 390  *         a trigger value set in 'triggerstring' are NULL, the other entries
 391  *         contain the respective trigger type which is requested for the
 392  *         respective channel (e.g. "r", "c", and so on).
 393  *
 394  * @since 0.2.0
 395  */
 396 SR_API char **sr_parse_triggerstring(const struct sr_dev_inst *sdi,
 397                                      const char *triggerstring)
 398 {
 399         GSList *l;
 400         GVariant *gvar;
 401         struct sr_channel *ch;
 402         int max_channels, channelnum, i;
 403         char **tokens, **triggerlist, *trigger, *tc;
 404         const char *trigger_types;
 405         gboolean error;
 406
 407         max_channels = g_slist_length(sdi->channels);
 408         error = FALSE;
 409
 410         if (!(triggerlist = g_try_malloc0(max_channels * sizeof(char *)))) {
 411                 sr_err("%s: triggerlist malloc failed", __func__);
 412                 return NULL;
 413         }
 414
 415         if (sdi->driver->config_list(SR_CONF_TRIGGER_TYPE,
 416                                 &gvar, sdi, NULL) != SR_OK) {
 417                 sr_err("%s: Device doesn't support any triggers.", __func__);
 418                 return NULL;
 419         }
 420         trigger_types = g_variant_get_string(gvar, NULL);
 421
 422         tokens = g_strsplit(triggerstring, ",", max_channels);
 423         for (i = 0; tokens[i]; i++) {
 424                 channelnum = -1;
 425                 for (l = sdi->channels; l; l = l->next) {
 426                         ch = (struct sr_channel *)l->data;
 427                         if (ch->enabled
 428                                 && !strncmp(ch->name, tokens[i],
 429                                         strlen(ch->name))) {
 430                                 channelnum = ch->index;
 431                                 break;
 432                         }
 433                 }
 434
 435                 if (channelnum < 0 || channelnum >= max_channels) {
 436                         sr_err("Invalid channel.");
 437                         error = TRUE;
 438                         break;
 439                 }
 440
 441                 if ((trigger = strchr(tokens[i], '='))) {
 442                         for (tc = ++trigger; *tc; tc++) {
 443                                 if (strchr(trigger_types, *tc) == NULL) {
 444                                         sr_err("Unsupported trigger "
 445                                                "type '%c'.", *tc);
 446                                         error = TRUE;
 447                                         break;
 448                                 }
 449                         }
 450                         if (!error)
 451                                 triggerlist[channelnum] = g_strdup(trigger);
 452                 }
 453         }
 454         g_strfreev(tokens);
 455         g_variant_unref(gvar);
 456
 457         if (error) {
 458                 for (i = 0; i < max_channels; i++)
 459                         g_free(triggerlist[i]);
 460                 g_free(triggerlist);
 461                 triggerlist = NULL;
 462         }
 463
 464         return triggerlist;
 465 }
 466
 467 /**
 468  * Convert a "natural" string representation of a size value to uint64_t.
 469  *
 470  * E.g. a value of "3k" or "3 K" would be converted to 3000, a value
 471  * of "15M" would be converted to 15000000.
 472  *
 473  * Value representations other than decimal (such as hex or octal) are not
 474  * supported. Only 'k' (kilo), 'm' (mega), 'g' (giga) suffixes are supported.
 475  * Spaces (but not other whitespace) between value and suffix are allowed.
 476  *
 477  * @param sizestring A string containing a (decimal) size value.
 478  * @param size Pointer to uint64_t which will contain the string's size value.
 479  *
 480  * @return SR_OK upon success, SR_ERR upon errors.
 481  *
 482  * @since 0.1.0
 483  */
 484 SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
 485 {
 486         int multiplier, done;
 487         double frac_part;
 488         char *s;
 489
 490         *size = strtoull(sizestring, &s, 10);
 491         multiplier = 0;
 492         frac_part = 0;
 493         done = FALSE;
 494         while (s && *s && multiplier == 0 && !done) {
 495                 switch (*s) {
 496                 case ' ':
 497                         break;
 498                 case '.':
 499                         frac_part = g_ascii_strtod(s, &s);
 500                         break;
 501                 case 'k':
 502                 case 'K':
 503                         multiplier = SR_KHZ(1);
 504                         break;
 505                 case 'm':
 506                 case 'M':
 507                         multiplier = SR_MHZ(1);
 508                         break;
 509                 case 'g':
 510                 case 'G':
 511                         multiplier = SR_GHZ(1);
 512                         break;
 513                 default:
 514                         done = TRUE;
 515                         s--;
 516                 }
 517                 s++;
 518         }
 519         if (multiplier > 0) {
 520                 *size *= multiplier;
 521                 *size += frac_part * multiplier;
 522         } else
 523                 *size += frac_part;
 524
 525         if (*s && strcasecmp(s, "Hz"))
 526                 return SR_ERR;
 527
 528         return SR_OK;
 529 }
 530
 531 /**
 532  * Convert a "natural" string representation of a time value to an
 533  * uint64_t value in milliseconds.
 534  *
 535  * E.g. a value of "3s" or "3 s" would be converted to 3000, a value
 536  * of "15ms" would be converted to 15.
 537  *
 538  * Value representations other than decimal (such as hex or octal) are not
 539  * supported. Only lower-case "s" and "ms" time suffixes are supported.
 540  * Spaces (but not other whitespace) between value and suffix are allowed.
 541  *
 542  * @param timestring A string containing a (decimal) time value.
 543  * @return The string's time value as uint64_t, in milliseconds.
 544  *
 545  * @todo Add support for "m" (minutes) and others.
 546  * @todo Add support for picoseconds?
 547  * @todo Allow both lower-case and upper-case? If no, document it.
 548  *
 549  * @since 0.1.0
 550  */
 551 SR_API uint64_t sr_parse_timestring(const char *timestring)
 552 {
 553         uint64_t time_msec;
 554         char *s;
 555
 556         /* TODO: Error handling, logging. */
 557
 558         time_msec = strtoull(timestring, &s, 10);
 559         if (time_msec == 0 && s == timestring)
 560                 return 0;
 561
 562         if (s && *s) {
 563                 while (*s == ' ')
 564                         s++;
 565                 if (!strcmp(s, "s"))
 566                         time_msec *= 1000;
 567                 else if (!strcmp(s, "ms"))
 568                         ; /* redundant */
 569                 else
 570                         return 0;
 571         }
 572
 573         return time_msec;
 574 }
 575
 576 /** @since 0.1.0 */
 577 SR_API gboolean sr_parse_boolstring(const char *boolstr)
 578 {
 579         if (!boolstr)
 580                 return FALSE;
 581
 582         if (!g_ascii_strncasecmp(boolstr, "true", 4) ||
 583             !g_ascii_strncasecmp(boolstr, "yes", 3) ||
 584             !g_ascii_strncasecmp(boolstr, "on", 2) ||
 585             !g_ascii_strncasecmp(boolstr, "1", 1))
 586                 return TRUE;
 587
 588         return FALSE;
 589 }
 590
 591 /** @since 0.2.0 */
 592 SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
 593 {
 594         char *s;
 595
 596         *p = strtoull(periodstr, &s, 10);
 597         if (*p == 0 && s == periodstr)
 598                 /* No digits found. */
 599                 return SR_ERR_ARG;
 600
 601         if (s && *s) {
 602                 while (*s == ' ')
 603                         s++;
 604                 if (!strcmp(s, "fs"))
 605                         *q = 1000000000000000ULL;
 606                 else if (!strcmp(s, "ps"))
 607                         *q = 1000000000000ULL;
 608                 else if (!strcmp(s, "ns"))
 609                         *q = 1000000000ULL;
 610                 else if (!strcmp(s, "us"))
 611                         *q = 1000000;
 612                 else if (!strcmp(s, "ms"))
 613                         *q = 1000;
 614                 else if (!strcmp(s, "s"))
 615                         *q = 1;
 616                 else
 617                         /* Must have a time suffix. */
 618                         return SR_ERR_ARG;
 619         }
 620
 621         return SR_OK;
 622 }
 623
 624 /** @since 0.2.0 */
 625 SR_API int sr_parse_voltage(const char *voltstr, uint64_t *p, uint64_t *q)
 626 {
 627         char *s;
 628
 629         *p = strtoull(voltstr, &s, 10);
 630         if (*p == 0 && s == voltstr)
 631                 /* No digits found. */
 632                 return SR_ERR_ARG;
 633
 634         if (s && *s) {
 635                 while (*s == ' ')
 636                         s++;
 637                 if (!strcasecmp(s, "mv"))
 638                         *q = 1000L;
 639                 else if (!strcasecmp(s, "v"))
 640                         *q = 1;
 641                 else
 642                         /* Must have a base suffix. */
 643                         return SR_ERR_ARG;
 644         }
 645
 646         return SR_OK;
 647 }
 648
 649 /** @} */