/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
/*
 * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 * Use is subject to license terms.
 */

#ifndef _GROUP_H
#define _GROUP_H

/*
 * Group Abstraction
 */

#ifdef  __cplusplus
extern "C" {
#endif

#if (defined(_KERNEL) || defined(_KMEMUSER))
#include <sys/types.h>

#define GRP_RESIZE      0x1     /* Resize group capacity if needed */
#define GRP_NORESIZE    0x2     /* Do not resize group capacity; may fail */

/*
 * group structure
 */
typedef struct group {
        uint_t          grp_size;       /* # of elements */
        uint_t          grp_capacity;   /* current group capacity */
        void            **grp_set;      /* element vector */
} group_t;

typedef uint_t group_iter_t;


/*
 * Return the number of elements in the group
 */
#define GROUP_SIZE(grp)                 ((grp)->grp_size)

/*
 * Access the element at the specified group index
 */
#define GROUP_ACCESS(grp, index)        ((grp)->grp_set[index])

/*
 * Group creation / destruction
 */
void            group_create(group_t *);
void            group_destroy(group_t *);

/*
 * Expand a group's holding capacity
 */
void            group_expand(group_t *, uint_t);

/*
 * Group element iteration
 */
void            group_iter_init(group_iter_t *);
void            *group_iterate(group_t *, group_iter_t *);

/*
 * Add / remove an element (or elements) from the group
 */
int             group_add(group_t *, void *, int);
int             group_remove(group_t *, void *, int);
void            group_empty(group_t *);

/*
 * Add / remove / access an element at a specified index.
 * The group must already have sufficient capacity to hold
 * an element at the specified index.
 */
int             group_add_at(group_t *, void *, uint_t);
void            group_remove_at(group_t *, uint_t);

/*
 * Search for an element in a group.
 * Returns an index that may be used with the *_at()
 * routines above to add or remove the element.
 */
uint_t          group_find(group_t *, void *);

/*
 * Convert a group to a string with list of integers.
 *
 * The consecutive integer values are represented using x-y notation.
 * The resulting string looks like "1,2-5,8"
 *
 * The convert argument is used to map group elements to integer IDs.
 * The output buffer and its length are specfied in the arguments.
 */
extern char *group2intlist(group_t *, char *, size_t, int (convert)(void*));

#endif  /* !_KERNEL && !_KMEMUSER */

#ifdef  __cplusplus
}
#endif

#endif /* _GROUP_H */