upscli_str_add_unique_token - Man Page

        #include <upsclient​.h>

        int     upscli_str_add_unique_token(char *tgt, size_t tgtsize, const char *token,
                                int (*callback_always)(char *, size_t, const char *),
                                int (*callback_unique)(char *, size_t, const char *) );

The upscli_str_add_unique_token() function takes the pointer tgt to a caller-provided char * buffer of size tgtsize, and the pointer token to a contiguous token that should be added to the end of tgt buffer, if it is not there yet​.

The token contents are stripped of surrounding space characters, and the method recurses to independently process each space-separated token inside (if there are any spaces left)​.

The resulting tgt buffer would eventually collect a string comprised of unique token values in order of first mention, separated by single space characters (ASCII 0x20)​.

Optionally calls callback_always (if not NULL) after checking the input for spaces (and maybe recursing) and before checking if the token is already there, and/or callback_unique (if not NULL) after checking for uniqueness and just before going to add a newly seen token​.

• If such callback returns 0, abort the addition of token and return -3​.

It is up to the caller to dynamically or statically allocate the tgt buffer and free() it if needed​. As far as this method is concerned, the buffer may be recycled (in data processing loops) by setting the initial character to '\0', making it an empty string again​.

The upscli_str_add_unique_token() function returns a numeric code:

• 0 if the token value was already there in tgt buffer;
• 1 if token was added successfully;
• -1 if we needed to add the token, but it did not fit under the tgtsize limit;
• -2 if either token or tgt string was NULL, or if token was empty;
• -3 if the token was rejected by the optional callback method returning 0​.

upscli_str_contains_token(3)