BRSet.h

//
//  BRSet.h
//
//  Created by Aaron Voisine on 9/11/15.
//  Copyright (c) 2015 breadwallet LLC
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.

#ifndef BRSet_h
#define BRSet_h

#include <stddef.h>
#include <inttypes.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct BRSetStruct BRSet;

// retruns a newly allocated empty set that must be freed by calling BRSetFree()
// size_t hash(const void *) is a function that returns a hash value for a given set item
// int eq(const void *, const void *) is a function that returns true if two set items are equal
// any two items that are equal must also have identical hash values
// capacity is the initial number of items the set can hold, which will be auto-increased as needed
BRSet *BRSetNew(size_t (*hash)(const void *), int (*eq)(const void *, const void *), size_t capacity);

// adds given item to set or replaces an equivalent existing item and returns item replaced if any
void *BRSetAdd(BRSet *set, void *item);

// removes item equivalent to given item from set and returns item removed if any
void *BRSetRemove(BRSet *set, const void *item);

// removes all items from set
void BRSetClear(BRSet *set);

// returns the number of items in set
size_t BRSetCount(const BRSet *set);

// true if an item equivalant to the given item is contained in set
int BRSetContains(const BRSet *set, const void *item);

// true if any items in otherSet are contained in set
int BRSetIntersects(const BRSet *set, const BRSet *otherSet);

// returns member item from set equivalent to given item, or NULL if there is none
void *BRSetGet(const BRSet *set, const void *item);

// returns an initial random item from set for use when iterating, or NULL if set is empty
void *BRSetFirst(const BRSet *set);

// returns the next item after given item when iterating, or NULL if no more items are available
void *BRSetNext(const BRSet *set, const void *item);

// writes up to count items from set to allItems and returns number of items written
size_t BRSetAll(const BRSet *set, void *allItems[], size_t count);

// calls map() with each item in set
void BRSetMap(const BRSet *set, void *info, void (*map)(void *info, void *item));

// adds or replaces items from otherSet into set
void BRSetUnion(BRSet *set, const BRSet *otherSet);

// removes items contained in otherSet from set
void BRSetMinus(BRSet *set, const BRSet *otherSet);

// removes items not contained in otherSet from set
void BRSetIntersect(BRSet *set, const BRSet *otherSet);

// frees memory allocated for set
void BRSetFree(BRSet *set);

#ifdef __cplusplus
}
#endif

#endif // BRSet_h