libsigrok  0.5.2
sigrok hardware access and backend library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Functions
String utilities

Helper functions for handling or converting libsigrok-related strings. More...

Functions

int sr_sprintf_ascii (char *buf, const char *format,...)
 Compose a string with a format string in the buffer pointed to by buf. More...
 
int sr_vsprintf_ascii (char *buf, const char *format, va_list args)
 Compose a string with a format string in the buffer pointed to by buf. More...
 
int sr_snprintf_ascii (char *buf, size_t buf_size, const char *format,...)
 Composes a string with a format string (like printf) in the buffer pointed by buf (taking buf_size as the maximum buffer capacity to fill). More...
 
int sr_vsnprintf_ascii (char *buf, size_t buf_size, const char *format, va_list args)
 Composes a string with a format string (like printf) in the buffer pointed by buf (taking buf_size as the maximum buffer capacity to fill). More...
 
SR_PRIV GString * sr_hexdump_new (const uint8_t *data, const size_t len)
 Convert a sequence of bytes to its textual representation ("hex dump"). More...
 
SR_PRIV void sr_hexdump_free (GString *s)
 Free a hex dump text that was created by sr_hexdump_new(). More...
 
int sr_parse_rational (const char *str, struct sr_rational *ret)
 Convert a string representation of a numeric value to a sr_rational. More...
 
char * sr_si_string_u64 (uint64_t x, const char *unit)
 Convert a numeric value value to its "natural" string representation in SI units. More...
 
char * sr_samplerate_string (uint64_t samplerate)
 Convert a numeric samplerate value to its "natural" string representation. More...
 
char * sr_period_string (uint64_t v_p, uint64_t v_q)
 Convert a numeric period value to the "natural" string representation of its period value. More...
 
char * sr_voltage_string (uint64_t v_p, uint64_t v_q)
 Convert a numeric voltage value to the "natural" string representation of its voltage value. More...
 
int sr_parse_sizestring (const char *sizestring, uint64_t *size)
 Convert a "natural" string representation of a size value to uint64_t. More...
 
uint64_t sr_parse_timestring (const char *timestring)
 Convert a "natural" string representation of a time value to an uint64_t value in milliseconds. More...
 
gboolean sr_parse_boolstring (const char *boolstr)
 
int sr_parse_period (const char *periodstr, uint64_t *p, uint64_t *q)
 
int sr_parse_voltage (const char *voltstr, uint64_t *p, uint64_t *q)
 

Detailed Description

Helper functions for handling or converting libsigrok-related strings.

Function Documentation

SR_PRIV void sr_hexdump_free ( GString *  s)

Free a hex dump text that was created by sr_hexdump_new().

Parameters
[in]sPointer to the GString to release.

Definition at line 623 of file strutil.c.

SR_PRIV GString* sr_hexdump_new ( const uint8_t *  data,
const size_t  len 
)

Convert a sequence of bytes to its textual representation ("hex dump").

Callers should free the allocated GString. See sr_hexdump_free().

Parameters
[in]dataPointer to the byte sequence to print.
[in]lenNumber of bytes to print.
Returns
#NULL upon error, newly allocated GString pointer otherwise.

Definition at line 603 of file strutil.c.

gboolean sr_parse_boolstring ( const char *  boolstr)
Since
0.1.0

Definition at line 990 of file strutil.c.

int sr_parse_period ( const char *  periodstr,
uint64_t *  p,
uint64_t *  q 
)
Since
0.2.0

Definition at line 1010 of file strutil.c.

References SR_ERR_ARG, and SR_OK.

int sr_parse_rational ( const char *  str,
struct sr_rational ret 
)

Convert a string representation of a numeric value to a sr_rational.

The conversion is strict and will fail if the complete string does not represent a valid number. The function sets errno according to the details of the failure. This version ignores the locale.

Parameters
strThe string representation to convert.
retPointer to sr_rational where the result of the conversion will be stored.
Return values
SR_OKConversion successful.
SR_ERRFailure.
Since
0.5.0

Definition at line 644 of file strutil.c.

References sr_rational::p, sr_rational::q, SR_ERR, and SR_OK.

int sr_parse_sizestring ( const char *  sizestring,
uint64_t *  size 
)

Convert a "natural" string representation of a size value to uint64_t.

E.g. a value of "3k" or "3 K" would be converted to 3000, a value of "15M" would be converted to 15000000.

Value representations other than decimal (such as hex or octal) are not supported. Only 'k' (kilo), 'm' (mega), 'g' (giga) suffixes are supported. Spaces (but not other whitespace) between value and suffix are allowed.

Parameters
sizestringA string containing a (decimal) size value.
sizePointer to uint64_t which will contain the string's size value.
Returns
SR_OK upon success, SR_ERR upon errors.
Since
0.1.0

Definition at line 883 of file strutil.c.

References SR_ERR, SR_GHZ, SR_KHZ, SR_MHZ, and SR_OK.

Referenced by sr_session_load().

+ Here is the caller graph for this function:

uint64_t sr_parse_timestring ( const char *  timestring)

Convert a "natural" string representation of a time value to an uint64_t value in milliseconds.

E.g. a value of "3s" or "3 s" would be converted to 3000, a value of "15ms" would be converted to 15.

Value representations other than decimal (such as hex or octal) are not supported. Only lower-case "s" and "ms" time suffixes are supported. Spaces (but not other whitespace) between value and suffix are allowed.

Parameters
timestringA string containing a (decimal) time value.
Returns
The string's time value as uint64_t, in milliseconds.
Since
0.1.0

Definition at line 964 of file strutil.c.

int sr_parse_voltage ( const char *  voltstr,
uint64_t *  p,
uint64_t *  q 
)
Since
0.2.0

Definition at line 1043 of file strutil.c.

References SR_ERR_ARG, and SR_OK.

char* sr_period_string ( uint64_t  v_p,
uint64_t  v_q 
)

Convert a numeric period value to the "natural" string representation of its period value.

The period is specified as a rational number's numerator and denominator.

E.g. a pair of (1, 5) would be converted to "200 ms", (10, 100) to "100 ms".

Parameters
v_pThe period numerator.
v_qThe period denominator.
Returns
A newly allocated string representation of the period value, or NULL upon errors. The caller is responsible to g_free() the memory.
Since
0.5.0

Definition at line 810 of file strutil.c.

References SR_GHZ, SR_KHZ, and SR_MHZ.

char* sr_samplerate_string ( uint64_t  samplerate)

Convert a numeric samplerate value to its "natural" string representation.

E.g. a value of 3000000 would be converted to "3 MHz", 20000 to "20 kHz", 31500 would become "31.5 kHz".

Parameters
samplerateThe samplerate in Hz.
Returns
A newly allocated string representation of the samplerate value, or NULL upon errors. The caller is responsible to g_free() the memory.
Since
0.1.0

Definition at line 788 of file strutil.c.

References sr_si_string_u64().

+ Here is the call graph for this function:

char* sr_si_string_u64 ( uint64_t  x,
const char *  unit 
)

Convert a numeric value value to its "natural" string representation in SI units.

E.g. a value of 3000000, with units set to "W", would be converted to "3 MW", 20000 to "20 kW", 31500 would become "31.5 kW".

Parameters
xThe value to convert.
unitThe unit to append to the string, or NULL if the string has no units.
Returns
A newly allocated string representation of the samplerate value, or NULL upon errors. The caller is responsible to g_free() the memory.
Since
0.2.0

Definition at line 746 of file strutil.c.

References SR_GHZ, SR_HZ, SR_KHZ, and SR_MHZ.

Referenced by sr_samplerate_string().

+ Here is the caller graph for this function:

int sr_snprintf_ascii ( char *  buf,
size_t  buf_size,
const char *  format,
  ... 
)

Composes a string with a format string (like printf) in the buffer pointed by buf (taking buf_size as the maximum buffer capacity to fill).

If the resulting string would be longer than n - 1 characters, the remaining characters are discarded and not stored, but counted for the value returned by the function. A terminating NUL character is automatically appended after the content written. After the format parameter, the function expects at least as many additional arguments as needed for format.

This version ignores the current locale and uses the locale "C" for Linux, FreeBSD, OSX and Android.

Parameters
bufPointer to a buffer where the resulting C string is stored.
buf_sizeMaximum number of bytes to be used in the buffer. The generated string has a length of at most buf_size - 1, leaving space for the additional terminating NUL character.
formatC string that contains a format string (see printf).
...A sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.
Returns
On success, the number of characters that would have been written if buf_size had been sufficiently large, not counting the terminating NUL character. On failure, a negative number is returned. Notice that only when this returned value is non-negative and less than buf_size, the string has been completely written.
Since
0.5.1

Definition at line 450 of file strutil.c.

References sr_vsnprintf_ascii().

+ Here is the call graph for this function:

int sr_sprintf_ascii ( char *  buf,
const char *  format,
  ... 
)

Compose a string with a format string in the buffer pointed to by buf.

It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result.

A terminating NUL character is automatically appended after the content written.

After the format parameter, the function expects at least as many additional arguments as needed for format.

This version ignores the current locale and uses the locale "C" for Linux, FreeBSD, OSX and Android.

Parameters
bufPointer to a buffer where the resulting C string is stored.
formatC string that contains a format string (see printf).
...A sequence of additional arguments, each containing a value to be used to replace a format specifier in the format string.
Returns
On success, the number of characters that would have been written, not counting the terminating NUL character.
Since
0.5.1

Definition at line 286 of file strutil.c.

References sr_vsprintf_ascii().

+ Here is the call graph for this function:

char* sr_voltage_string ( uint64_t  v_p,
uint64_t  v_q 
)

Convert a numeric voltage value to the "natural" string representation of its voltage value.

The voltage is specified as a rational number's numerator and denominator.

E.g. a value of 300000 would be converted to "300mV", 2 to "2V".

Parameters
v_pThe voltage numerator.
v_qThe voltage denominator.
Returns
A newly allocated string representation of the voltage value, or NULL upon errors. The caller is responsible to g_free() the memory.
Since
0.2.0

Definition at line 856 of file strutil.c.

int sr_vsnprintf_ascii ( char *  buf,
size_t  buf_size,
const char *  format,
va_list  args 
)

Composes a string with a format string (like printf) in the buffer pointed by buf (taking buf_size as the maximum buffer capacity to fill).

If the resulting string would be longer than n - 1 characters, the remaining characters are discarded and not stored, but counted for the value returned by the function. A terminating NUL character is automatically appended after the content written. Internally, the function retrieves arguments from the list identified by args as if va_arg was used on it, and thus the state of args is likely to be altered by the call. In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

This version ignores the current locale and uses the locale "C" for Linux, FreeBSD, OSX and Android.

Parameters
bufPointer to a buffer where the resulting C string is stored.
buf_sizeMaximum number of bytes to be used in the buffer. The generated string has a length of at most buf_size - 1, leaving space for the additional terminating NUL character.
formatC string that contains a format string (see printf).
argsA value identifying a variable arguments list initialized with va_start.
Returns
On success, the number of characters that would have been written if buf_size had been sufficiently large, not counting the terminating NUL character. On failure, a negative number is returned. Notice that only when this returned value is non-negative and less than buf_size, the string has been completely written.
Since
0.5.1

Definition at line 497 of file strutil.c.

Referenced by sr_snprintf_ascii().

+ Here is the caller graph for this function:

int sr_vsprintf_ascii ( char *  buf,
const char *  format,
va_list  args 
)

Compose a string with a format string in the buffer pointed to by buf.

It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result.

Internally, the function retrieves arguments from the list identified by args as if va_arg was used on it, and thus the state of args is likely to be altered by the call.

In any case, args should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

This version ignores the current locale and uses the locale "C" for Linux, FreeBSD, OSX and Android.

Parameters
bufPointer to a buffer where the resulting C string is stored.
formatC string that contains a format string (see printf).
argsA value identifying a variable arguments list initialized with va_start.
Returns
On success, the number of characters that would have been written, not counting the terminating NUL character.
Since
0.5.1

Definition at line 325 of file strutil.c.

Referenced by sr_sprintf_ascii().

+ Here is the caller graph for this function: