src/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, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /* Needed for POSIX.1-2008 locale functions */
  21 /** @cond PRIVATE */
  22 #define _XOPEN_SOURCE 700
  23 /** @endcond */
  24 #include <config.h>
  25 #include <ctype.h>
  26 #include <locale.h>
  27 #if defined(__FreeBSD__) || defined(__APPLE__)
  28 #include <xlocale.h>
  29 #endif
  30 #if defined(__FreeBSD__)
  31 #include <sys/param.h>
  32 #endif
  33 #include <stdint.h>
  34 #include <stdlib.h>
  35 #include <string.h>
  36 #include <strings.h>
  37 #include <errno.h>
  38 #include <libsigrok/libsigrok.h>
  39 #include "libsigrok-internal.h"
  40
  41 /** @cond PRIVATE */
  42 #define LOG_PREFIX "strutil"
  43 /** @endcond */
  44
  45 /**
  46  * @file
  47  *
  48  * Helper functions for handling or converting libsigrok-related strings.
  49  */
  50
  51 /**
  52  * @defgroup grp_strutil String utilities
  53  *
  54  * Helper functions for handling or converting libsigrok-related strings.
  55  *
  56  * @{
  57  */
  58
  59 /**
  60  * Convert a string representation of a numeric value (base 10) to a long integer. The
  61  * conversion is strict and will fail if the complete string does not represent
  62  * a valid long integer. The function sets errno according to the details of the
  63  * failure.
  64  *
  65  * @param str The string representation to convert.
  66  * @param ret Pointer to long where the result of the conversion will be stored.
  67  *
  68  * @retval SR_OK Conversion successful.
  69  * @retval SR_ERR Failure.
  70  *
  71  * @private
  72  */
  73 SR_PRIV int sr_atol(const char *str, long *ret)
  74 {
  75         long tmp;
  76         char *endptr = NULL;
  77
  78         errno = 0;
  79         tmp = strtol(str, &endptr, 10);
  80
  81         while (endptr && isspace(*endptr))
  82                 endptr++;
  83
  84         if (!endptr || *endptr || errno) {
  85                 if (!errno)
  86                         errno = EINVAL;
  87                 return SR_ERR;
  88         }
  89
  90         *ret = tmp;
  91         return SR_OK;
  92 }
  93
  94 /**
  95  * Convert a text to a number including support for non-decimal bases.
  96  * Also optionally returns the position after the number, where callers
  97  * can either error out, or support application specific suffixes.
  98  *
  99  * @param[in] str The input text to convert.
 100  * @param[out] ret The conversion result.
 101  * @param[out] end The position after the number.
 102  * @param[in] base The number format's base, can be 0.
 103  *
 104  * @retval SR_OK Conversion successful.
 105  * @retval SR_ERR Conversion failed.
 106  *
 107  * @private
 108  *
 109  * This routine is more general than @ref sr_atol(), which strictly
 110  * expects the input text to contain just a decimal number, and nothing
 111  * else in addition. The @ref sr_atol_base() routine accepts trailing
 112  * text after the number, and supports non-decimal numbers (bin, hex),
 113  * including automatic detection from prefix text.
 114  */
 115 SR_PRIV int sr_atol_base(const char *str, long *ret, char **end, int base)
 116 {
 117         long num;
 118         char *endptr;
 119
 120         /* Add "0b" prefix support which strtol(3) may be missing. */
 121         while (str && isspace(*str))
 122                 str++;
 123         if (!base && strncmp(str, "0b", strlen("0b")) == 0) {
 124                 str += strlen("0b");
 125                 base = 2;
 126         }
 127
 128         /* Run the number conversion. Quick bail out if that fails. */
 129         errno = 0;
 130         endptr = NULL;
 131         num = strtol(str, &endptr, base);
 132         if (!endptr || errno) {
 133                 if (!errno)
 134                         errno = EINVAL;
 135                 return SR_ERR;
 136         }
 137         *ret = num;
 138
 139         /* Advance to optional non-space trailing suffix. */
 140         while (endptr && isspace(*endptr))
 141                 endptr++;
 142         if (end)
 143                 *end = endptr;
 144
 145         return SR_OK;
 146 }
 147
 148 /**
 149  * Convert a text to a number including support for non-decimal bases.
 150  * Also optionally returns the position after the number, where callers
 151  * can either error out, or support application specific suffixes.
 152  *
 153  * @param[in] str The input text to convert.
 154  * @param[out] ret The conversion result.
 155  * @param[out] end The position after the number.
 156  * @param[in] base The number format's base, can be 0.
 157  *
 158  * @retval SR_OK Conversion successful.
 159  * @retval SR_ERR Conversion failed.
 160  *
 161  * @private
 162  *
 163  * This routine is more general than @ref sr_atol(), which strictly
 164  * expects the input text to contain just a decimal number, and nothing
 165  * else in addition. The @ref sr_atoul_base() routine accepts trailing
 166  * text after the number, and supports non-decimal numbers (bin, hex),
 167  * including automatic detection from prefix text.
 168  */
 169 SR_PRIV int sr_atoul_base(const char *str, unsigned long *ret, char **end, int base)
 170 {
 171         unsigned long num;
 172         char *endptr;
 173
 174         /* Add "0b" prefix support which strtol(3) may be missing. */
 175         while (str && isspace(*str))
 176                 str++;
 177         if (!base && strncmp(str, "0b", strlen("0b")) == 0) {
 178                 str += strlen("0b");
 179                 base = 2;
 180         }
 181
 182         /* Run the number conversion. Quick bail out if that fails. */
 183         errno = 0;
 184         endptr = NULL;
 185         num = strtoul(str, &endptr, base);
 186         if (!endptr || errno) {
 187                 if (!errno)
 188                         errno = EINVAL;
 189                 return SR_ERR;
 190         }
 191         *ret = num;
 192
 193         /* Advance to optional non-space trailing suffix. */
 194         while (endptr && isspace(*endptr))
 195                 endptr++;
 196         if (end)
 197                 *end = endptr;
 198
 199         return SR_OK;
 200 }
 201
 202 /**
 203  * Convert a string representation of a numeric value (base 10) to an integer. The
 204  * conversion is strict and will fail if the complete string does not represent
 205  * a valid integer. The function sets errno according to the details of the
 206  * failure.
 207  *
 208  * @param str The string representation to convert.
 209  * @param ret Pointer to int where the result of the conversion will be stored.
 210  *
 211  * @retval SR_OK Conversion successful.
 212  * @retval SR_ERR Failure.
 213  *
 214  * @private
 215  */
 216 SR_PRIV int sr_atoi(const char *str, int *ret)
 217 {
 218         long tmp;
 219
 220         if (sr_atol(str, &tmp) != SR_OK)
 221                 return SR_ERR;
 222
 223         if ((int) tmp != tmp) {
 224                 errno = ERANGE;
 225                 return SR_ERR;
 226         }
 227
 228         *ret = (int) tmp;
 229         return SR_OK;
 230 }
 231
 232 /**
 233  * Convert a string representation of a numeric value to a double. The
 234  * conversion is strict and will fail if the complete string does not represent
 235  * a valid double. The function sets errno according to the details of the
 236  * failure.
 237  *
 238  * @param str The string representation to convert.
 239  * @param ret Pointer to double where the result of the conversion will be stored.
 240  *
 241  * @retval SR_OK Conversion successful.
 242  * @retval SR_ERR Failure.
 243  *
 244  * @private
 245  */
 246 SR_PRIV int sr_atod(const char *str, double *ret)
 247 {
 248         double tmp;
 249         char *endptr = NULL;
 250
 251         errno = 0;
 252         tmp = strtof(str, &endptr);
 253
 254         while (endptr && isspace(*endptr))
 255                 endptr++;
 256
 257         if (!endptr || *endptr || errno) {
 258                 if (!errno)
 259                         errno = EINVAL;
 260                 return SR_ERR;
 261         }
 262
 263         *ret = tmp;
 264         return SR_OK;
 265 }
 266
 267 /**
 268  * Convert a string representation of a numeric value to a float. The
 269  * conversion is strict and will fail if the complete string does not represent
 270  * a valid float. The function sets errno according to the details of the
 271  * failure.
 272  *
 273  * @param str The string representation to convert.
 274  * @param ret Pointer to float where the result of the conversion will be stored.
 275  *
 276  * @retval SR_OK Conversion successful.
 277  * @retval SR_ERR Failure.
 278  *
 279  * @private
 280  */
 281 SR_PRIV int sr_atof(const char *str, float *ret)
 282 {
 283         double tmp;
 284
 285         if (sr_atod(str, &tmp) != SR_OK)
 286                 return SR_ERR;
 287
 288         if ((float) tmp != tmp) {
 289                 errno = ERANGE;
 290                 return SR_ERR;
 291         }
 292
 293         *ret = (float) tmp;
 294         return SR_OK;
 295 }
 296
 297 /**
 298  * Convert a string representation of a numeric value to a double. The
 299  * conversion is strict and will fail if the complete string does not represent
 300  * a valid double. The function sets errno according to the details of the
 301  * failure. This version ignores the locale.
 302  *
 303  * @param str The string representation to convert.
 304  * @param ret Pointer to double where the result of the conversion will be stored.
 305  *
 306  * @retval SR_OK Conversion successful.
 307  * @retval SR_ERR Failure.
 308  *
 309  * @private
 310  */
 311 SR_PRIV int sr_atod_ascii(const char *str, double *ret)
 312 {
 313         double tmp;
 314         char *endptr = NULL;
 315
 316         errno = 0;
 317         tmp = g_ascii_strtod(str, &endptr);
 318
 319         if (!endptr || *endptr || errno) {
 320                 if (!errno)
 321                         errno = EINVAL;
 322                 return SR_ERR;
 323         }
 324
 325         *ret = tmp;
 326         return SR_OK;
 327 }
 328
 329 /**
 330  * Convert text to a floating point value, and get its precision.
 331  *
 332  * @param[in] str The input text to convert.
 333  * @param[out] ret The conversion result, a double precision float number.
 334  * @param[out] digits The number of significant decimals.
 335  *
 336  * @returns SR_OK in case of successful text to number conversion.
 337  * @returns SR_ERR when conversion fails.
 338  *
 339  * @since 0.6.0
 340  */
 341 SR_PRIV int sr_atod_ascii_digits(const char *str, double *ret, int *digits)
 342 {
 343         const char *p;
 344         int *dig_ref, m_dig, exp;
 345         char c;
 346         double f;
 347
 348         /*
 349          * Convert floating point text to the number value, _and_ get
 350          * the value's precision in the process. Steps taken to do it:
 351          * - Skip leading whitespace.
 352          * - Count the number of decimals after the mantissa's period.
 353          * - Get the exponent's signed value.
 354          *
 355          * This implementation still uses common code for the actual
 356          * conversion, but "violates API layers" by duplicating the
 357          * text scan, to get the number of significant digits.
 358          */
 359         p = str;
 360         while (*p && isspace(*p))
 361                 p++;
 362         if (*p == '-' || *p == '+')
 363                 p++;
 364         m_dig = 0;
 365         exp = 0;
 366         dig_ref = NULL;
 367         while (*p) {
 368                 c = *p++;
 369                 if (toupper(c) == 'E') {
 370                         exp = strtol(p, NULL, 10);
 371                         break;
 372                 }
 373                 if (c == '.') {
 374                         m_dig = 0;
 375                         dig_ref = &m_dig;
 376                         continue;
 377                 }
 378                 if (isdigit(c)) {
 379                         if (dig_ref)
 380                                 (*dig_ref)++;
 381                         continue;
 382                 }
 383                 /* Need not warn, conversion will fail. */
 384                 break;
 385         }
 386         sr_spew("atod digits: txt \"%s\" -> m %d, e %d -> digits %d",
 387                 str, m_dig, exp, m_dig + -exp);
 388         m_dig += -exp;
 389
 390         if (sr_atod_ascii(str, &f) != SR_OK)
 391                 return SR_ERR;
 392         if (ret)
 393                 *ret = f;
 394         if (digits)
 395                 *digits = m_dig;
 396
 397         return SR_OK;
 398 }
 399
 400 /**
 401  * Convert a string representation of a numeric value to a float. The
 402  * conversion is strict and will fail if the complete string does not represent
 403  * a valid float. The function sets errno according to the details of the
 404  * failure. This version ignores the locale.
 405  *
 406  * @param str The string representation to convert.
 407  * @param ret Pointer to float where the result of the conversion will be stored.
 408  *
 409  * @retval SR_OK Conversion successful.
 410  * @retval SR_ERR Failure.
 411  *
 412  * @private
 413  */
 414 SR_PRIV int sr_atof_ascii(const char *str, float *ret)
 415 {
 416         double tmp;
 417         char *endptr = NULL;
 418
 419         errno = 0;
 420         tmp = g_ascii_strtod(str, &endptr);
 421
 422         if (!endptr || *endptr || errno) {
 423                 if (!errno)
 424                         errno = EINVAL;
 425                 return SR_ERR;
 426         }
 427
 428         /* FIXME This fails unexpectedly. Some other method to safel downcast
 429          * needs to be found. Checking against FLT_MAX doesn't work as well. */
 430         /*
 431         if ((float) tmp != tmp) {
 432                 errno = ERANGE;
 433                 sr_dbg("ERANGEEEE %e != %e", (float) tmp, tmp);
 434                 return SR_ERR;
 435         }
 436         */
 437
 438         *ret = (float) tmp;
 439         return SR_OK;
 440 }
 441
 442 /**
 443  * Compose a string with a format string in the buffer pointed to by buf.
 444  *
 445  * It is up to the caller to ensure that the allocated buffer is large enough
 446  * to hold the formatted result.
 447  *
 448  * A terminating NUL character is automatically appended after the content
 449  * written.
 450  *
 451  * After the format parameter, the function expects at least as many additional
 452  * arguments as needed for format.
 453  *
 454  * This version ignores the current locale and uses the locale "C" for Linux,
 455  * FreeBSD, OSX and Android.
 456  *
 457  * @param buf Pointer to a buffer where the resulting C string is stored.
 458  * @param format C string that contains a format string (see printf).
 459  * @param ... A sequence of additional arguments, each containing a value to be
 460  *        used to replace a format specifier in the format string.
 461  *
 462  * @return On success, the number of characters that would have been written,
 463  *         not counting the terminating NUL character.
 464  *
 465  * @since 0.6.0
 466  */
 467 SR_API int sr_sprintf_ascii(char *buf, const char *format, ...)
 468 {
 469         int ret;
 470         va_list args;
 471
 472         va_start(args, format);
 473         ret = sr_vsprintf_ascii(buf, format, args);
 474         va_end(args);
 475
 476         return ret;
 477 }
 478
 479 /**
 480  * Compose a string with a format string in the buffer pointed to by buf.
 481  *
 482  * It is up to the caller to ensure that the allocated buffer is large enough
 483  * to hold the formatted result.
 484  *
 485  * Internally, the function retrieves arguments from the list identified by
 486  * args as if va_arg was used on it, and thus the state of args is likely to
 487  * be altered by the call.
 488  *
 489  * In any case, args should have been initialized by va_start at some point
 490  * before the call, and it is expected to be released by va_end at some point
 491  * after the call.
 492  *
 493  * This version ignores the current locale and uses the locale "C" for Linux,
 494  * FreeBSD, OSX and Android.
 495  *
 496  * @param buf Pointer to a buffer where the resulting C string is stored.
 497  * @param format C string that contains a format string (see printf).
 498  * @param args A value identifying a variable arguments list initialized with
 499  *        va_start.
 500  *
 501  * @return On success, the number of characters that would have been written,
 502  *         not counting the terminating NUL character.
 503  *
 504  * @since 0.6.0
 505  */
 506 SR_API int sr_vsprintf_ascii(char *buf, const char *format, va_list args)
 507 {
 508 #if defined(_WIN32)
 509         int ret;
 510
 511 #if 0
 512         /*
 513          * TODO: This part compiles with mingw-w64 but doesn't run with Win7.
 514          *       Doesn't start because of "Procedure entry point _create_locale
 515          *       not found in msvcrt.dll".
 516          *       mingw-w64 should link to msvcr100.dll not msvcrt.dll!
 517          * See: https://msdn.microsoft.com/en-us/en-en/library/1kt27hek.aspx
 518          */
 519         _locale_t locale;
 520
 521         locale = _create_locale(LC_NUMERIC, "C");
 522         ret = _vsprintf_l(buf, format, locale, args);
 523         _free_locale(locale);
 524 #endif
 525
 526         /* vsprintf() uses the current locale, may not work correctly for floats. */
 527         ret = vsprintf(buf, format, args);
 528
 529         return ret;
 530 #elif defined(__APPLE__)
 531         /*
 532          * See:
 533          * https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man3/printf_l.3.html
 534          * https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man3/xlocale.3.html
 535          */
 536         int ret;
 537         locale_t locale;
 538
 539         locale = newlocale(LC_NUMERIC_MASK, "C", NULL);
 540         ret = vsprintf_l(buf, locale, format, args);
 541         freelocale(locale);
 542
 543         return ret;
 544 #elif defined(__FreeBSD__) && __FreeBSD_version >= 901000
 545         /*
 546          * See:
 547          * https://www.freebsd.org/cgi/man.cgi?query=printf_l&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE
 548          * https://www.freebsd.org/cgi/man.cgi?query=xlocale&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE
 549          */
 550         int ret;
 551         locale_t locale;
 552
 553         locale = newlocale(LC_NUMERIC_MASK, "C", NULL);
 554         ret = vsprintf_l(buf, locale, format, args);
 555         freelocale(locale);
 556
 557         return ret;
 558 #elif defined(__ANDROID__)
 559         /*
 560          * The Bionic libc only has two locales ("C" aka "POSIX" and "C.UTF-8"
 561          * aka "en_US.UTF-8"). The decimal point is hard coded as "."
 562          * See: https://android.googlesource.com/platform/bionic/+/master/libc/bionic/locale.cpp
 563          */
 564         int ret;
 565
 566         ret = vsprintf(buf, format, args);
 567
 568         return ret;
 569 #elif defined(__linux__)
 570         int ret;
 571         locale_t old_locale, temp_locale;
 572
 573         /* Switch to C locale for proper float/double conversion. */
 574         temp_locale = newlocale(LC_NUMERIC, "C", NULL);
 575         old_locale = uselocale(temp_locale);
 576
 577         ret = vsprintf(buf, format, args);
 578
 579         /* Switch back to original locale. */
 580         uselocale(old_locale);
 581         freelocale(temp_locale);
 582
 583         return ret;
 584 #elif defined(__unix__) || defined(__unix)
 585         /*
 586          * This is a fallback for all other BSDs, *nix and FreeBSD <= 9.0, by
 587          * using the current locale for snprintf(). This may not work correctly
 588          * for floats!
 589          */
 590         int ret;
 591
 592         ret = vsprintf(buf, format, args);
 593
 594         return ret;
 595 #else
 596         /* No implementation for unknown systems! */
 597         return -1;
 598 #endif
 599 }
 600
 601 /**
 602  * Composes a string with a format string (like printf) in the buffer pointed
 603  * by buf (taking buf_size as the maximum buffer capacity to fill).
 604  * If the resulting string would be longer than n - 1 characters, the remaining
 605  * characters are discarded and not stored, but counted for the value returned
 606  * by the function.
 607  * A terminating NUL character is automatically appended after the content
 608  * written.
 609  * After the format parameter, the function expects at least as many additional
 610  * arguments as needed for format.
 611  *
 612  * This version ignores the current locale and uses the locale "C" for Linux,
 613  * FreeBSD, OSX and Android.
 614  *
 615  * @param buf Pointer to a buffer where the resulting C string is stored.
 616  * @param buf_size Maximum number of bytes to be used in the buffer. The
 617  *        generated string has a length of at most buf_size - 1, leaving space
 618  *        for the additional terminating NUL character.
 619  * @param format C string that contains a format string (see printf).
 620  * @param ... A sequence of additional arguments, each containing a value to be
 621  *        used to replace a format specifier in the format string.
 622  *
 623  * @return On success, the number of characters that would have been written if
 624  *         buf_size had been sufficiently large, not counting the terminating
 625  *         NUL character. On failure, a negative number is returned.
 626  *         Notice that only when this returned value is non-negative and less
 627  *         than buf_size, the string has been completely written.
 628  *
 629  * @since 0.6.0
 630  */
 631 SR_API int sr_snprintf_ascii(char *buf, size_t buf_size,
 632         const char *format, ...)
 633 {
 634         int ret;
 635         va_list args;
 636
 637         va_start(args, format);
 638         ret = sr_vsnprintf_ascii(buf, buf_size, format, args);
 639         va_end(args);
 640
 641         return ret;
 642 }
 643
 644 /**
 645  * Composes a string with a format string (like printf) in the buffer pointed
 646  * by buf (taking buf_size as the maximum buffer capacity to fill).
 647  * If the resulting string would be longer than n - 1 characters, the remaining
 648  * characters are discarded and not stored, but counted for the value returned
 649  * by the function.
 650  * A terminating NUL character is automatically appended after the content
 651  * written.
 652  * Internally, the function retrieves arguments from the list identified by
 653  * args as if va_arg was used on it, and thus the state of args is likely to
 654  * be altered by the call.
 655  * In any case, arg should have been initialized by va_start at some point
 656  * before the call, and it is expected to be released by va_end at some point
 657  * after the call.
 658  *
 659  * This version ignores the current locale and uses the locale "C" for Linux,
 660  * FreeBSD, OSX and Android.
 661  *
 662  * @param buf Pointer to a buffer where the resulting C string is stored.
 663  * @param buf_size Maximum number of bytes to be used in the buffer. The
 664  *        generated string has a length of at most buf_size - 1, leaving space
 665  *        for the additional terminating NUL character.
 666  * @param format C string that contains a format string (see printf).
 667  * @param args A value identifying a variable arguments list initialized with
 668  *        va_start.
 669  *
 670  * @return On success, the number of characters that would have been written if
 671  *         buf_size had been sufficiently large, not counting the terminating
 672  *         NUL character. On failure, a negative number is returned.
 673  *         Notice that only when this returned value is non-negative and less
 674  *         than buf_size, the string has been completely written.
 675  *
 676  * @since 0.6.0
 677  */
 678 SR_API int sr_vsnprintf_ascii(char *buf, size_t buf_size,
 679         const char *format, va_list args)
 680 {
 681 #if defined(_WIN32)
 682         int ret;
 683
 684 #if 0
 685         /*
 686          * TODO: This part compiles with mingw-w64 but doesn't run with Win7.
 687          *       Doesn't start because of "Procedure entry point _create_locale
 688          *       not found in msvcrt.dll".
 689          *       mingw-w64 should link to msvcr100.dll not msvcrt.dll!.
 690          * See: https://msdn.microsoft.com/en-us/en-en/library/1kt27hek.aspx
 691          */
 692         _locale_t locale;
 693
 694         locale = _create_locale(LC_NUMERIC, "C");
 695         ret = _vsnprintf_l(buf, buf_size, format, locale, args);
 696         _free_locale(locale);
 697 #endif
 698
 699         /* vsprintf uses the current locale, may cause issues for floats. */
 700         ret = vsnprintf(buf, buf_size, format, args);
 701
 702         return ret;
 703 #elif defined(__APPLE__)
 704         /*
 705          * See:
 706          * https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man3/printf_l.3.html
 707          * https://developer.apple.com/legacy/library/documentation/Darwin/Reference/ManPages/man3/xlocale.3.html
 708          */
 709         int ret;
 710         locale_t locale;
 711
 712         locale = newlocale(LC_NUMERIC_MASK, "C", NULL);
 713         ret = vsnprintf_l(buf, buf_size, locale, format, args);
 714         freelocale(locale);
 715
 716         return ret;
 717 #elif defined(__FreeBSD__) && __FreeBSD_version >= 901000
 718         /*
 719          * See:
 720          * https://www.freebsd.org/cgi/man.cgi?query=printf_l&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE
 721          * https://www.freebsd.org/cgi/man.cgi?query=xlocale&apropos=0&sektion=3&manpath=FreeBSD+9.1-RELEASE
 722          */
 723         int ret;
 724         locale_t locale;
 725
 726         locale = newlocale(LC_NUMERIC_MASK, "C", NULL);
 727         ret = vsnprintf_l(buf, buf_size, locale, format, args);
 728         freelocale(locale);
 729
 730         return ret;
 731 #elif defined(__ANDROID__)
 732         /*
 733          * The Bionic libc only has two locales ("C" aka "POSIX" and "C.UTF-8"
 734          * aka "en_US.UTF-8"). The decimal point is hard coded as ".".
 735          * See: https://android.googlesource.com/platform/bionic/+/master/libc/bionic/locale.cpp
 736          */
 737         int ret;
 738
 739         ret = vsnprintf(buf, buf_size, format, args);
 740
 741         return ret;
 742 #elif defined(__linux__)
 743         int ret;
 744         locale_t old_locale, temp_locale;
 745
 746         /* Switch to C locale for proper float/double conversion. */
 747         temp_locale = newlocale(LC_NUMERIC, "C", NULL);
 748         old_locale = uselocale(temp_locale);
 749
 750         ret = vsnprintf(buf, buf_size, format, args);
 751
 752         /* Switch back to original locale. */
 753         uselocale(old_locale);
 754         freelocale(temp_locale);
 755
 756         return ret;
 757 #elif defined(__unix__) || defined(__unix)
 758         /*
 759          * This is a fallback for all other BSDs, *nix and FreeBSD <= 9.0, by
 760          * using the current locale for snprintf(). This may not work correctly
 761          * for floats!
 762          */
 763         int ret;
 764
 765         ret = vsnprintf(buf, buf_size, format, args);
 766
 767         return ret;
 768 #else
 769         /* No implementation for unknown systems! */
 770         return -1;
 771 #endif
 772 }
 773
 774 /**
 775  * Convert a sequence of bytes to its textual representation ("hex dump").
 776  *
 777  * Callers should free the allocated GString. See sr_hexdump_free().
 778  *
 779  * @param[in] data Pointer to the byte sequence to print.
 780  * @param[in] len Number of bytes to print.
 781  *
 782  * @return NULL upon error, newly allocated GString pointer otherwise.
 783  *
 784  * @private
 785  */
 786 SR_PRIV GString *sr_hexdump_new(const uint8_t *data, const size_t len)
 787 {
 788         GString *s;
 789         size_t i;
 790
 791         s = g_string_sized_new(3 * len);
 792         for (i = 0; i < len; i++) {
 793                 if (i)
 794                         g_string_append_c(s, ' ');
 795                 g_string_append_printf(s, "%02x", data[i]);
 796         }
 797
 798         return s;
 799 }
 800
 801 /**
 802  * Free a hex dump text that was created by sr_hexdump_new().
 803  *
 804  * @param[in] s Pointer to the GString to release.
 805  *
 806  * @private
 807  */
 808 SR_PRIV void sr_hexdump_free(GString *s)
 809 {
 810         if (s)
 811                 g_string_free(s, TRUE);
 812 }
 813
 814 /**
 815  * Convert a string representation of a numeric value to a sr_rational.
 816  *
 817  * The conversion is strict and will fail if the complete string does not
 818  * represent a valid number. The function sets errno according to the details
 819  * of the failure. This version ignores the locale.
 820  *
 821  * @param str The string representation to convert.
 822  * @param ret Pointer to sr_rational where the result of the conversion will be stored.
 823  *
 824  * @retval SR_OK Conversion successful.
 825  * @retval SR_ERR Failure.
 826  *
 827  * @since 0.5.0
 828  */
 829 SR_API int sr_parse_rational(const char *str, struct sr_rational *ret)
 830 {
 831         const char *readptr;
 832         char *endptr;
 833         gboolean is_negative, empty_integral, empty_fractional, exp_negative;
 834         int64_t integral;
 835         int64_t fractional;
 836         int64_t denominator;
 837         uint32_t fractional_len;
 838         int32_t exponent;
 839
 840         /*
 841          * Implementor's note: This routine tries hard to avoid calling
 842          * glib's or the platform's conversion routines with input that
 843          * cannot get converted *at all* (see bug #1093). It also takes
 844          * care to return with non-zero errno values for any failed
 845          * conversion attempt. It's assumed that correctness and robustness
 846          * are more important than performance, which is why code paths
 847          * are not optimized at all. Maintainability took priority.
 848          */
 849
 850         readptr = str;
 851
 852         /* Skip leading whitespace. */
 853         while (isspace(*readptr))
 854                 readptr++;
 855
 856         /* Determine the sign, default to non-negative. */
 857         is_negative = FALSE;
 858         if (*readptr == '-') {
 859                 is_negative = TRUE;
 860                 readptr++;
 861         } else if (*readptr == '+') {
 862                 is_negative = FALSE;
 863                 readptr++;
 864         }
 865
 866         /* Get the (optional) integral part. */
 867         empty_integral = TRUE;
 868         integral = 0;
 869         endptr = (char *)readptr;
 870         errno = 0;
 871         if (isdigit(*readptr)) {
 872                 empty_integral = FALSE;
 873                 integral = g_ascii_strtoll(readptr, &endptr, 10);
 874                 if (errno)
 875                         return SR_ERR;
 876                 if (endptr == str) {
 877                         errno = -EINVAL;
 878                         return SR_ERR;
 879                 }
 880                 readptr = endptr;
 881         }
 882
 883         /* Get the optional fractional part. */
 884         empty_fractional = TRUE;
 885         fractional = 0;
 886         fractional_len = 0;
 887         if (*readptr == '.') {
 888                 readptr++;
 889                 endptr++;
 890                 errno = 0;
 891                 if (isdigit(*readptr)) {
 892                         empty_fractional = FALSE;
 893                         fractional = g_ascii_strtoll(readptr, &endptr, 10);
 894                         if (errno)
 895                                 return SR_ERR;
 896                         if (endptr == readptr) {
 897                                 errno = -EINVAL;
 898                                 return SR_ERR;
 899                         }
 900                         fractional_len = endptr - readptr;
 901                         readptr = endptr;
 902                 }
 903         }
 904
 905         /* At least one of integral or fractional is required. */
 906         if (empty_integral && empty_fractional) {
 907                 errno = -EINVAL;
 908                 return SR_ERR;
 909         }
 910
 911         /* Get the (optional) exponent. */
 912         exponent = 0;
 913         if ((*readptr == 'E') || (*readptr == 'e')) {
 914                 readptr++;
 915                 endptr++;
 916                 exp_negative = FALSE;
 917                 if (*readptr == '+') {
 918                         exp_negative = FALSE;
 919                         readptr++;
 920                         endptr++;
 921                 } else if (*readptr == '-') {
 922                         exp_negative = TRUE;
 923                         readptr++;
 924                         endptr++;
 925                 }
 926                 if (!isdigit(*readptr)) {
 927                         errno = -EINVAL;
 928                         return SR_ERR;
 929                 }
 930                 errno = 0;
 931                 exponent = g_ascii_strtoll(readptr, &endptr, 10);
 932                 if (errno)
 933                         return SR_ERR;
 934                 if (endptr == readptr) {
 935                         errno = -EINVAL;
 936                         return SR_ERR;
 937                 }
 938                 readptr = endptr;
 939                 if (exp_negative)
 940                         exponent = -exponent;
 941         }
 942
 943         /* Input must be exhausted. Unconverted remaining input is fatal. */
 944         if (*endptr != '\0') {
 945                 errno = -EINVAL;
 946                 return SR_ERR;
 947         }
 948
 949         /*
 950          * Apply the sign to the integral (and fractional) part(s).
 951          * Adjust exponent (decimal position) such that the above integral
 952          * and fractional parts both fit into the (new) integral part.
 953          */
 954         if (is_negative)
 955                 integral = -integral;
 956         while (fractional_len-- > 0) {
 957                 integral *= 10;
 958                 exponent--;
 959         }
 960         if (!is_negative)
 961                 integral += fractional;
 962         else
 963                 integral -= fractional;
 964         while (exponent > 0) {
 965                 integral *= 10;
 966                 exponent--;
 967         }
 968
 969         /*
 970          * When significant digits remain after the decimal, scale up the
 971          * denominator such that we end up with two integer p/q numbers.
 972          */
 973         denominator = 1;
 974         while (exponent < 0) {
 975                 denominator *= 10;
 976                 exponent++;
 977         }
 978
 979         ret->p = integral;
 980         ret->q = denominator;
 981
 982         return SR_OK;
 983 }
 984
 985 /**
 986  * Convert a numeric value value to its "natural" string representation
 987  * in SI units.
 988  *
 989  * E.g. a value of 3000000, with units set to "W", would be converted
 990  * to "3 MW", 20000 to "20 kW", 31500 would become "31.5 kW".
 991  *
 992  * @param x The value to convert.
 993  * @param unit The unit to append to the string, or NULL if the string
 994  *             has no units.
 995  *
 996  * @return A newly allocated string representation of the samplerate value,
 997  *         or NULL upon errors. The caller is responsible to g_free() the
 998  *         memory.
 999  *
1000  * @since 0.2.0
1001  */
1002 SR_API char *sr_si_string_u64(uint64_t x, const char *unit)
1003 {
1004         uint8_t i;
1005         uint64_t quot, divisor[] = {
1006                 SR_HZ(1), SR_KHZ(1), SR_MHZ(1), SR_GHZ(1),
1007                 SR_GHZ(1000), SR_GHZ(1000 * 1000), SR_GHZ(1000 * 1000 * 1000),
1008         };
1009         const char *p, prefix[] = "\0kMGTPE";
1010         char fmt[16], fract[20] = "", *f;
1011
1012         if (!unit)
1013                 unit = "";
1014
1015         for (i = 0; (quot = x / divisor[i]) >= 1000; i++);
1016
1017         if (i) {
1018                 sprintf(fmt, ".%%0%d"PRIu64, i * 3);
1019                 f = fract + sprintf(fract, fmt, x % divisor[i]) - 1;
1020
1021                 while (f >= fract && strchr("0.", *f))
1022                         *f-- = 0;
1023         }
1024
1025         p = prefix + i;
1026
1027         return g_strdup_printf("%" PRIu64 "%s %.1s%s", quot, fract, p, unit);
1028 }
1029
1030 /**
1031  * Convert a numeric samplerate value to its "natural" string representation.
1032  *
1033  * E.g. a value of 3000000 would be converted to "3 MHz", 20000 to "20 kHz",
1034  * 31500 would become "31.5 kHz".
1035  *
1036  * @param samplerate The samplerate in Hz.
1037  *
1038  * @return A newly allocated string representation of the samplerate value,
1039  *         or NULL upon errors. The caller is responsible to g_free() the
1040  *         memory.
1041  *
1042  * @since 0.1.0
1043  */
1044 SR_API char *sr_samplerate_string(uint64_t samplerate)
1045 {
1046         return sr_si_string_u64(samplerate, "Hz");
1047 }
1048
1049 /**
1050  * Convert a numeric period value to the "natural" string representation
1051  * of its period value.
1052  *
1053  * The period is specified as a rational number's numerator and denominator.
1054  *
1055  * E.g. a pair of (1, 5) would be converted to "200 ms", (10, 100) to "100 ms".
1056  *
1057  * @param v_p The period numerator.
1058  * @param v_q The period denominator.
1059  *
1060  * @return A newly allocated string representation of the period value,
1061  *         or NULL upon errors. The caller is responsible to g_free() the
1062  *         memory.
1063  *
1064  * @since 0.5.0
1065  */
1066 SR_API char *sr_period_string(uint64_t v_p, uint64_t v_q)
1067 {
1068         double freq, v;
1069         int prec;
1070
1071         freq = 1 / ((double)v_p / v_q);
1072
1073         if (freq > SR_GHZ(1)) {
1074                 v = (double)v_p / v_q * 1000000000000.0;
1075                 prec = ((v - (uint64_t)v) < FLT_MIN) ? 0 : 3;
1076                 return g_strdup_printf("%.*f ps", prec, v);
1077         } else if (freq > SR_MHZ(1)) {
1078                 v = (double)v_p / v_q * 1000000000.0;
1079                 prec = ((v - (uint64_t)v) < FLT_MIN) ? 0 : 3;
1080                 return g_strdup_printf("%.*f ns", prec, v);
1081         } else if (freq > SR_KHZ(1)) {
1082                 v = (double)v_p / v_q * 1000000.0;
1083                 prec = ((v - (uint64_t)v) < FLT_MIN) ? 0 : 3;
1084                 return g_strdup_printf("%.*f us", prec, v);
1085         } else if (freq > 1) {
1086                 v = (double)v_p / v_q * 1000.0;
1087                 prec = ((v - (uint64_t)v) < FLT_MIN) ? 0 : 3;
1088                 return g_strdup_printf("%.*f ms", prec, v);
1089         } else {
1090                 v = (double)v_p / v_q;
1091                 prec = ((v - (uint64_t)v) < FLT_MIN) ? 0 : 3;
1092                 return g_strdup_printf("%.*f s", prec, v);
1093         }
1094 }
1095
1096 /**
1097  * Convert a numeric voltage value to the "natural" string representation
1098  * of its voltage value. The voltage is specified as a rational number's
1099  * numerator and denominator.
1100  *
1101  * E.g. a value of 300000 would be converted to "300mV", 2 to "2V".
1102  *
1103  * @param v_p The voltage numerator.
1104  * @param v_q The voltage denominator.
1105  *
1106  * @return A newly allocated string representation of the voltage value,
1107  *         or NULL upon errors. The caller is responsible to g_free() the
1108  *         memory.
1109  *
1110  * @since 0.2.0
1111  */
1112 SR_API char *sr_voltage_string(uint64_t v_p, uint64_t v_q)
1113 {
1114         if (v_q == 1000)
1115                 return g_strdup_printf("%" PRIu64 " mV", v_p);
1116         else if (v_q == 1)
1117                 return g_strdup_printf("%" PRIu64 " V", v_p);
1118         else
1119                 return g_strdup_printf("%g V", (float)v_p / (float)v_q);
1120 }
1121
1122 /**
1123  * Convert a "natural" string representation of a size value to uint64_t.
1124  *
1125  * E.g. a value of "3k" or "3 K" would be converted to 3000, a value
1126  * of "15M" would be converted to 15000000.
1127  *
1128  * Value representations other than decimal (such as hex or octal) are not
1129  * supported. Only 'k' (kilo), 'm' (mega), 'g' (giga) suffixes are supported.
1130  * Spaces (but not other whitespace) between value and suffix are allowed.
1131  *
1132  * @param sizestring A string containing a (decimal) size value.
1133  * @param size Pointer to uint64_t which will contain the string's size value.
1134  *
1135  * @return SR_OK upon success, SR_ERR upon errors.
1136  *
1137  * @since 0.1.0
1138  */
1139 SR_API int sr_parse_sizestring(const char *sizestring, uint64_t *size)
1140 {
1141         uint64_t multiplier;
1142         int done;
1143         double frac_part;
1144         char *s;
1145
1146         *size = strtoull(sizestring, &s, 10);
1147         multiplier = 0;
1148         frac_part = 0;
1149         done = FALSE;
1150         while (s && *s && multiplier == 0 && !done) {
1151                 switch (*s) {
1152                 case ' ':
1153                         break;
1154                 case '.':
1155                         frac_part = g_ascii_strtod(s, &s);
1156                         break;
1157                 case 'k':
1158                 case 'K':
1159                         multiplier = SR_KHZ(1);
1160                         break;
1161                 case 'm':
1162                 case 'M':
1163                         multiplier = SR_MHZ(1);
1164                         break;
1165                 case 'g':
1166                 case 'G':
1167                         multiplier = SR_GHZ(1);
1168                         break;
1169                 case 't':
1170                 case 'T':
1171                         multiplier = SR_GHZ(1000);
1172                         break;
1173                 case 'p':
1174                 case 'P':
1175                         multiplier = SR_GHZ(1000 * 1000);
1176                         break;
1177                 case 'e':
1178                 case 'E':
1179                         multiplier = SR_GHZ(1000 * 1000 * 1000);
1180                         break;
1181                 default:
1182                         done = TRUE;
1183                         s--;
1184                 }
1185                 s++;
1186         }
1187         if (multiplier > 0) {
1188                 *size *= multiplier;
1189                 *size += frac_part * multiplier;
1190         } else {
1191                 *size += frac_part;
1192         }
1193
1194         if (s && *s && g_ascii_strcasecmp(s, "Hz"))
1195                 return SR_ERR;
1196
1197         return SR_OK;
1198 }
1199
1200 /**
1201  * Convert a "natural" string representation of a time value to an
1202  * uint64_t value in milliseconds.
1203  *
1204  * E.g. a value of "3s" or "3 s" would be converted to 3000, a value
1205  * of "15ms" would be converted to 15.
1206  *
1207  * Value representations other than decimal (such as hex or octal) are not
1208  * supported. Only lower-case "s" and "ms" time suffixes are supported.
1209  * Spaces (but not other whitespace) between value and suffix are allowed.
1210  *
1211  * @param timestring A string containing a (decimal) time value.
1212  * @return The string's time value as uint64_t, in milliseconds.
1213  *
1214  * @todo Add support for "m" (minutes) and others.
1215  * @todo Add support for picoseconds?
1216  * @todo Allow both lower-case and upper-case? If no, document it.
1217  *
1218  * @since 0.1.0
1219  */
1220 SR_API uint64_t sr_parse_timestring(const char *timestring)
1221 {
1222         uint64_t time_msec;
1223         char *s;
1224
1225         /* TODO: Error handling, logging. */
1226
1227         time_msec = strtoull(timestring, &s, 10);
1228         if (time_msec == 0 && s == timestring)
1229                 return 0;
1230
1231         if (s && *s) {
1232                 while (*s == ' ')
1233                         s++;
1234                 if (!strcmp(s, "s"))
1235                         time_msec *= 1000;
1236                 else if (!strcmp(s, "ms"))
1237                         ; /* redundant */
1238                 else
1239                         return 0;
1240         }
1241
1242         return time_msec;
1243 }
1244
1245 /** @since 0.1.0 */
1246 SR_API gboolean sr_parse_boolstring(const char *boolstr)
1247 {
1248         /*
1249          * Complete absence of an input spec is assumed to mean TRUE,
1250          * as in command line option strings like this:
1251          *   ...:samplerate=100k:header:numchannels=4:...
1252          */
1253         if (!boolstr || !*boolstr)
1254                 return TRUE;
1255
1256         if (!g_ascii_strncasecmp(boolstr, "true", 4) ||
1257             !g_ascii_strncasecmp(boolstr, "yes", 3) ||
1258             !g_ascii_strncasecmp(boolstr, "on", 2) ||
1259             !g_ascii_strncasecmp(boolstr, "1", 1))
1260                 return TRUE;
1261
1262         return FALSE;
1263 }
1264
1265 /** @since 0.2.0 */
1266 SR_API int sr_parse_period(const char *periodstr, uint64_t *p, uint64_t *q)
1267 {
1268         char *s;
1269
1270         *p = strtoull(periodstr, &s, 10);
1271         if (*p == 0 && s == periodstr)
1272                 /* No digits found. */
1273                 return SR_ERR_ARG;
1274
1275         if (s && *s) {
1276                 while (*s == ' ')
1277                         s++;
1278                 if (!strcmp(s, "fs"))
1279                         *q = UINT64_C(1000000000000000);
1280                 else if (!strcmp(s, "ps"))
1281                         *q = UINT64_C(1000000000000);
1282                 else if (!strcmp(s, "ns"))
1283                         *q = UINT64_C(1000000000);
1284                 else if (!strcmp(s, "us"))
1285                         *q = 1000000;
1286                 else if (!strcmp(s, "ms"))
1287                         *q = 1000;
1288                 else if (!strcmp(s, "s"))
1289                         *q = 1;
1290                 else
1291                         /* Must have a time suffix. */
1292                         return SR_ERR_ARG;
1293         }
1294
1295         return SR_OK;
1296 }
1297
1298 /** @since 0.2.0 */
1299 SR_API int sr_parse_voltage(const char *voltstr, uint64_t *p, uint64_t *q)
1300 {
1301         char *s;
1302
1303         *p = strtoull(voltstr, &s, 10);
1304         if (*p == 0 && s == voltstr)
1305                 /* No digits found. */
1306                 return SR_ERR_ARG;
1307
1308         if (s && *s) {
1309                 while (*s == ' ')
1310                         s++;
1311                 if (!g_ascii_strcasecmp(s, "mv"))
1312                         *q = 1000L;
1313                 else if (!g_ascii_strcasecmp(s, "v"))
1314                         *q = 1;
1315                 else
1316                         /* Must have a base suffix. */
1317                         return SR_ERR_ARG;
1318         }
1319
1320         return SR_OK;
1321 }
1322
1323 /** @} */