idset_decode(3)
SYNOPSIS
#include <flux/idset.h>
typedef struct {
char text[160];
} idset_error_t;
struct idset *idset_decode (const char *s);
struct idset *idset_decode_ex (const char *s,
ssize_t len,
ssize_t size,
int flags,
idset_error_t *error);
bool idset_decode_empty (const char *s, ssize_t len);
int idset_decode_info (const char *s,
ssize_t len,
size_t *count,
unsigned int *maxid,
idset_error_t *error);
int idset_decode_add (struct idset *idset,
const char *s,
ssize_t len,
idset_error_t *error);
int idset_decode_subtract (struct idset *idset,
const char *s,
ssize_t len,
idset_error_t *error);
Link with -lflux-idset.
DESCRIPTION
Refer to idset_create(3) for a general description of idsets.
idset_decode() creates an idset from a string s. The string may
have been produced by idset_encode(). It must consist of comma-separated
non-negative integer ids, and may also contain hyphenated ranges.
If enclosed in square brackets, the brackets are ignored. Some examples
of valid input strings are:
1,2,5,4
1-4,7,9-10
42
[99-101]
idset_decode_ex() creates an idset from a string s optionally
truncated at len bytes. If len is -1, the full, NUL-terminated
string length is parsed. The idset is created using the specified flags
and size. If size is -1, the idset is made to exactly fit the
largest id specified in s. If size is 0, a default size is used.
The following functions parse an idset string without creating an idset:
idset_decode_empty() parses s optionally truncated at len
and returns true if it is the empty set, or false if it is not the empty set
or cannot be parsed.
idset_decode_info() parses s optionally truncated at len
bytes to determine the idset count and maxid. Either of the
two output parameters may be set to NULL to suppress assignment.
idset_decode_add() parses s optionally truncated at len
bytes and adds members of the resulting set to idset.
idset_decode_subtract() parses s optionally truncated at
len bytes and removes members of the resulting set from idset.
CAVEATS
idset_decode_ex() without IDSET_FLAGS_AUTOGROW fails when presented
with an empty set because an idset cannot be created with zero slots.
In situations where the set should not grow automatically and the empty
set is valid, it is recommended to represent the empty set with NULL,
and use idset_decode_empty() to distinguish it from a parse error, e.g.
struct idset *idset;
idset_error_t error;
if (idset_decode_empty (input, -1))
idset = NULL;
else if (!(idset = idset_decode_ex (input, -1, -1, 0, &error)))
// handle parse error
RETURN VALUE
idset_decode_empty() returns a boolean value.
idset_decode() and idset_decode_ex() return an idset on success
which must be freed with idset_destroy(3). On failure, they return NULL
with errno set. In addition, idset_decode_ex() sets error
on failure, if non-NULL.
idset_decode_empty() returns a boolean value.
idset_decode_add() and idset_decode_subtract() return 0 on success,
or -1 on failure with errno and error (if non-NULL) set.
ERRORS
- EINVAL
One or more arguments were invalid.
- ENOMEM
Out of memory.
RESOURCES
Flux: http://flux-framework.org
Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc