UPSCLI_STR_ADD_UNIQU(3) NUT Manual UPSCLI_STR_ADD_UNIQU(3)

upscli_str_add_unique_token - Add a unique token into a string buffer, with optional callbacks as needed by implementation

        #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)

05/29/2025 Network UPS Tools 2.8.3