 |
libsigrok
unreleased development snapshot
sigrok hardware access and backend library
|
|
libsigrok
unreleased development snapshot
sigrok hardware access and backend library
|
Helper functions for handling or converting libsigrok-related strings. More...
Functions | |
| SR_PRIV int | sr_atod_ascii_digits (const char *str, double *ret, int *digits) |
| Convert text to a floating point value, and get its precision. More... | |
| 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... | |
| 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) |
| char ** | sr_parse_probe_names (const char *spec, const char **dflt_names, size_t dflt_count, size_t max_count, size_t *ret_count) |
| Parse a probe names specification, allocate a string vector. More... | |
| void | sr_free_probe_names (char **names) |
| Release previously allocated probe names (string vector). More... | |
| char * | sr_text_trim_spaces (char *s) |
| Trim leading and trailing whitespace off text. More... | |
| char * | sr_text_next_line (char *s, size_t l, char **next, size_t *taken) |
| Check for another complete text line, trim, return consumed char count. More... | |
| char * | sr_text_next_word (char *s, char **next) |
| Isolates another space separated word in a text line. More... | |
| int | sr_next_power_of_two (size_t value, size_t *bits, size_t *power) |
| Get the number of necessary bits to hold a given value. More... | |
Helper functions for handling or converting libsigrok-related strings.
Convert text to a floating point value, and get its precision.
| [in] | str | The input text to convert. |
| [out] | ret | The conversion result, a double precision float number. |
| [out] | digits | The number of significant decimals. |
| void sr_free_probe_names | ( | char ** | names | ) |
| int sr_next_power_of_two | ( | size_t | value, |
| size_t * | bits, | ||
| size_t * | power | ||
| ) |
Get the number of necessary bits to hold a given value.
Also gets the next power-of-two value at or above the caller provided value.
| [in] | value | The value that must get stored. |
| [out] | bits | The required number of bits. |
| [out] | power | The corresponding power-of-two. |
TODO Move this routine to a more appropriate location, it is not strictly string related.
Definition at line 1837 of file strutil.c.
References SR_OK.
| gboolean sr_parse_boolstring | ( | const char * | boolstr | ) |
| int sr_parse_period | ( | const char * | periodstr, |
| uint64_t * | p, | ||
| uint64_t * | q | ||
| ) |
| char** sr_parse_probe_names | ( | const char * | spec, |
| const char ** | dflt_names, | ||
| size_t | dflt_count, | ||
| size_t | max_count, | ||
| size_t * | ret_count | ||
| ) |
Parse a probe names specification, allocate a string vector.
| [in] | spec | The input spec, list of probes or aliases. |
| [in] | dflt_names | The default probe names, a string array. |
| [in] | dflt_count | The default probe names count. Either must match the unterminated array size, or can be 0 when the default names are NULL terminated. |
| [in] | max_count | Optional resulting vector size limit. |
| [out] | ret_count | Optional result vector size (return value). |
The input spec is a comma separated list of probe names. Items can be aliases which expand to a corresponding set of signal names. The resulting names list optionally gets padded from the caller's builtin probe names, an empty input spec yields the original names as provided by the caller. Padding is omitted when the spec starts with '-', which may result in a device with fewer channels being created, enough to cover the user's spec, but none extra to maybe enable and use later on. An optional maximum length spec will trim the result set to that size. The resulting vector length optionally is returned to the caller, so that it need not re-get the length.
Calling applications must release the allocated vector by means of sr_free_probe_names().
| 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.
| str | The string representation to convert. |
| ret | Pointer to sr_rational where the result of the conversion will be stored. |
| SR_OK | Conversion successful. |
| SR_ERR | Failure. |
Definition at line 836 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.
| sizestring | A string containing a (decimal) size value. |
| size | Pointer to uint64_t which will contain the string's size value. |
Definition at line 1146 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.
| timestring | A string containing a (decimal) time value. |
| int sr_parse_voltage | ( | const char * | voltstr, |
| uint64_t * | p, | ||
| uint64_t * | q | ||
| ) |
| 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".
| v_p | The period numerator. |
| v_q | The period denominator. |
| 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".
| samplerate | The samplerate in Hz. |
Definition at line 1051 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".
| x | The value to convert. |
| unit | The unit to append to the string, or NULL if the string has no units. |
Definition at line 1009 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.
| buf | Pointer to a buffer where the resulting C string is stored. |
| buf_size | Maximum 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. |
| format | C 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. |
Definition at line 631 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.
| buf | Pointer to a buffer where the resulting C string is stored. |
| format | C 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. |
Definition at line 467 of file strutil.c.
References sr_vsprintf_ascii().
Here is the call graph for this function:| char* sr_text_next_line | ( | char * | s, |
| size_t | l, | ||
| char ** | next, | ||
| size_t * | taken | ||
| ) |
Check for another complete text line, trim, return consumed char count.
| [in] | s | The input text, current read position. |
| [in] | l | The input text, remaining available characters. |
| [out] | next | Position after the current text line. |
| [out] | taken | Count of consumed chars in current text line. |
Checks for the availability of another text line of input data. Manipulates the caller's input text in place.
The end-of-line condition is the LF character ('
'). Which covers LF-only as well as CR/LF input data. CR-only and LF/CR are considered unpopular and are not supported. LF/CR may appear to work at the caller's when leading whitespace gets trimmed (line boundaries will be incorrect, but content may get processed as expected). Support for all of the above combinations breaks the detection of empty lines (or becomes unmaintainably complex).
The input buffer must be end-of-line terminated, lack of EOL results in failure to detect the text line. This is motivated by accumulating input in chunks, and the desire to not process incomplete lines before their reception has completed. Callers should enforce EOL if their source of input provides an EOF condition and is unreliable in terms of text line termination.
When another text line is available, it gets NUL terminated and space gets trimmed of both ends. The start position of the trimmed text line is returned. Optionally the number of consumed characters is returned to the caller. Optionally 'next' points to after the returned text line, or #NULL when no other text is available in the input buffer.
The 'taken' value is not preset by this routine, only gets updated. This is convenient for callers which expect to find multiple text lines in a received chunk, before finally discarding processed data from the input buffer (which can involve expensive memory move operations, and may be desirable to defer as much as possible).
Definition at line 1741 of file strutil.c.
References sr_text_trim_spaces().
Here is the call graph for this function:| char* sr_text_next_word | ( | char * | s, |
| char ** | next | ||
| ) |
Isolates another space separated word in a text line.
| [in] | s | The input text, current read position. |
| [out] | next | The position after the current word. |
Advances over leading whitespace. Isolates (NUL terminates) the next whitespace separated word. Optionally returns the position after the current word. Manipulates the caller's input text in place.
| char* sr_text_trim_spaces | ( | char * | s | ) |
Trim leading and trailing whitespace off text.
| [in] | s | The input text. |
Manipulates the caller's input text in place.
Definition at line 1681 of file strutil.c.
Referenced by sr_text_next_line().
Here is the caller 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".
| v_p | The voltage numerator. |
| v_q | The voltage denominator. |
| 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.
| buf | Pointer to a buffer where the resulting C string is stored. |
| buf_size | Maximum 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. |
| format | C string that contains a format string (see printf). |
| args | A value identifying a variable arguments list initialized with va_start. |
Definition at line 678 of file strutil.c.
References SR_PRIV.
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.
| buf | Pointer to a buffer where the resulting C string is stored. |
| format | C string that contains a format string (see printf). |
| args | A value identifying a variable arguments list initialized with va_start. |
Definition at line 506 of file strutil.c.
Referenced by sr_sprintf_ascii().
Here is the caller graph for this function:
1.8.11
