Merge pull request #467 from gnustep/NSOrderedSet_documentation

Add documentation for NSOrderedSet
This commit is contained in:
Gregory Casamento 2024-11-18 11:36:17 -05:00 committed by GitHub
commit e5f378887d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -46,6 +46,11 @@ extern "C" {
@class NSString;
@class NSPredicate;
/**
* This class provides an ordered set, a set where the order of the elements matters and
* is preserved. Once created the set cannot be modified. NSMutableOrderedSet can be
* modified.
*/
GS_EXPORT_CLASS
@interface GS_GENERIC_CLASS(NSOrderedSet, __covariant ElementT) : NSObject <NSCoding,
NSCopying,
@ -53,154 +58,530 @@ GS_EXPORT_CLASS
NSFastEnumeration>
// class methods
/**
* Create and return an empty ordered set.
*/
+ (instancetype) orderedSet;
/**
* Create and return an empty ordered set with the provided NSArray instance.
*/
+ (instancetype) orderedSetWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)objects;
/**
* Create and return an empty ordered set with the provided NSArray instance.
* Use the range to determine which elements to use. If flag is YES copy the
* elements.
*/
+ (instancetype) orderedSetWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)objects
range: (NSRange)range
copyItems: (BOOL)flag;
/**
* Create and return an ordered set with anObject as the sole member.
*/
+ (instancetype) orderedSetWithObject: (GS_GENERIC_TYPE(ElementT))anObject;
/**
* Create and return an ordered set with list of arguments starting with
* firstObject and terminated with nil.
*/
+ (instancetype) orderedSetWithObjects: (GS_GENERIC_TYPE(ElementT))firstObject, ...;
/**
* Create and return an ordered set using the C array of objects with count.
*/
+ (instancetype) orderedSetWithObjects: (const GS_GENERIC_TYPE(ElementT)[])objects
count: (NSUInteger) count;
/**
* Create and return an ordered set with the provided ordered set aSet.
*/
+ (instancetype) orderedSetWithOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet;
/**
* Create and return an ordered set with set aSet.
*/
+ (instancetype) orderedSetWithSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet;
/**
* Create and return an ordered set with the elements in aSet. If flag is YES,
* copy the elements.
*/
+ (instancetype) orderedSetWithSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet
copyItems: (BOOL)flag;
// instance methods
/**
* Initialize and return an empty ordered set with the provided NSArray instance.
*/
- (instancetype) initWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)array;
/**
* Initialize and return an empty ordered set with the provided NSArray instance.
* If flag is YES copy the elements.
*/
- (instancetype) initWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)array copyItems: (BOOL)flag;
/**
* Initialize and return an empty ordered set with the provided NSArray instance.
* Use the range to determine which elements to use. If flag is YES copy the
* elements.
*/
- (instancetype) initWithArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)array
range: (NSRange)range
copyItems: (BOOL)flag;
/**
* Initialize and return an ordered set with anObject as the sole member.
*/
- (instancetype) initWithObject: (id)object;
/**
* Initialize and return an ordered set with list of arguments starting with
* firstObject and terminated with nil.
*/
- (instancetype) initWithObjects: (GS_GENERIC_TYPE(ElementT))firstObject, ...;
- (instancetype) initWithObjects: (const GS_GENERIC_TYPE(ElementT)[])objects
count: (NSUInteger)count;
/**
* Initialize and return an ordered set using the C array of objects with count.
*/
- (instancetype) initWithOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet;
/**
* Initialize and return an ordered set with the elements in aSet. If flag is YES,
* copy the elements.
*/
- (instancetype) initWithOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet
copyItems: (BOOL)flag;
/**
* Initialize and return an empty ordered set with the provided NSArray instance.
* Use the range to determine which elements to use. If flag is YES copy the
* elements.
*/
- (instancetype) initWithOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet
range: (NSRange)range
copyItems: (BOOL)flag;
/**
* Initialize and return an ordered set with set aSet.
*/
- (instancetype) initWithSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet;
/**
* Initialize and return an ordered set with set aSet. If flag is YES, then copy the elements.
*/
- (instancetype) initWithSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet copyItems:(BOOL)flag;
/**
* Initialize an empty ordered set.
*/
- (instancetype) init;
/**
* Return the number of elements in the receiver.
*/
- (NSUInteger) count;
/**
* Returns YES if the receiver contains anObject.
*/
- (BOOL)containsObject: (GS_GENERIC_TYPE(ElementT))anObject;
/**
* Enumerate over the objects whose indexes are contained in indexSet, with the opts provided
* using aBlock.
*/
- (void) enumerateObjectsAtIndexes: (NSIndexSet *)indexSet
options: (NSEnumerationOptions)opts
usingBlock: (GSEnumeratorBlock)aBlock;
/**
* Enumerate over all objects in the receiver using aBlock.
*/
- (void) enumerateObjectsUsingBlock: (GSEnumeratorBlock)aBlock;
/**
* Enumerate over all objects in the receiver with aBlock utilizing the options specified by opts.
*/
- (void) enumerateObjectsWithOptions: (NSEnumerationOptions)opts
usingBlock: (GSEnumeratorBlock)aBlock;
/**
* First object in the receiver.
*/
- (GS_GENERIC_TYPE(ElementT)) firstObject;
/**
* Last object in the receiver.
*/
- (GS_GENERIC_TYPE(ElementT)) lastObject;
/**
* Returns the object at index in the receiver.
*/
- (GS_GENERIC_TYPE(ElementT)) objectAtIndex: (NSUInteger)index;
/**
* Returns the object at index in the receiver.
*/
- (GS_GENERIC_TYPE(ElementT)) objectAtIndexedSubscript: (NSUInteger)index;
/**
* Returns objects at the indexes specified in the receiver.
*/
- (GS_GENERIC_CLASS(NSArray, ElementT)*) objectsAtIndexes: (NSIndexSet *)indexes;
- (NSUInteger) indexOfObject: (GS_GENERIC_TYPE(ElementT))objects;
/**
* Returns the index of anObject in the receiver.
*/
- (NSUInteger) indexOfObject: (GS_GENERIC_TYPE(ElementT))anObject;
/**
* Returns the index of object key, contained within range, using options, and the provided comparator.
*/
- (NSUInteger) indexOfObject: (id)key
inSortedRange: (NSRange)range
options: (NSBinarySearchingOptions)options
usingComparator: (NSComparator)comparator;
/**
* Returns the index of objects at indexSet that pass the test in predicate with enumeration options opts.
*/
- (NSUInteger) indexOfObjectAtIndexes: (NSIndexSet *)indexSet
options: (NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
/**
* Returns the index of the first object passing test predicate.
*/
- (NSUInteger) indexOfObjectPassingTest: (GSPredicateBlock)predicate;
/**
* Returns the index of the first object passing test predicate using enumeration options opts.
*/
- (NSUInteger) indexOfObjectWithOptions: (NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
/**
* Returns an NSIndexSet containing indexes of object at indexes in indexSet matching predicate
* with enumeration options opts.
*/
- (NSIndexSet *) indexesOfObjectsAtIndexes: (NSIndexSet *)indexSet
options: (NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
- (NSIndexSet *)indexesOfObjectsPassingTest: (GSPredicateBlock)predicate;
/**
* Returns an NSIndexSet containing indexes that match predicate.
*/
- (NSIndexSet *) indexesOfObjectsPassingTest: (GSPredicateBlock)predicate;
/**
* Returns an NSIndexSet containing indexes that match predicate using opts.
*/
- (NSIndexSet *) indexesOfObjectsWithOptions: (NSEnumerationOptions)opts
passingTest: (GSPredicateBlock)predicate;
/**
* Returns an NSEnumerator to iterate over each object in the receiver.
*/
- (GS_GENERIC_CLASS(NSEnumerator, ElementT)*) objectEnumerator;
/**
* Returns an NSEnumerator to iterate over each object in the receiver in reverse order.
*/
- (GS_GENERIC_CLASS(NSEnumerator, ElementT)*) reverseObjectEnumerator;
/**
* Returns an NSOrderedSet that contains the same objects as the receiver, but in reverse order.
*/
- (NSOrderedSet *)reversedOrderedSet;
/**
* Returns a C array of objects in aBuffer at indexes specified by aRange.
*/
- (void) getObjects: (__unsafe_unretained GS_GENERIC_TYPE(ElementT)[])aBuffer
range: (NSRange)aRange;
// Key value coding support
/**
* Set value for key.
*/
- (void) setValue: (id)value forKey: (NSString*)key;
/**
* Returns the value for a given key.
*/
- (id) valueForKey: (NSString*)key;
// Comparing Sets
/**
* Returns YES if the receiver is equal to aSet.
*/
- (BOOL) isEqualToOrderedSet: (NSOrderedSet *)aSet;
// Set operations
/**
* Returns YES if the receiver intersects with ordered set aSet.
*/
- (BOOL) intersectsOrderedSet: (NSOrderedSet *)aSet;
/**
* Returns YES if the receiver intersects with set aSet.
*/
- (BOOL) intersectsSet: (NSSet *)aSet;
/**
* Returns YES if the receiver is a subset of ordered set aSet.
*/
- (BOOL) isSubsetOfOrderedSet: (NSOrderedSet *)aSet;
/**
* Returns YES if the receiver is a subset of set aSet.
*/
- (BOOL) isSubsetOfSet:(NSSet *)aSet;
// Creating a Sorted Array
/**
* Returns an NSArray instance containing the elements from the receiver sorted using sortDescriptors.
*/
- (GS_GENERIC_CLASS(NSArray, ElementT) *) sortedArrayUsingDescriptors: (NSArray *)sortDescriptors;
/**
* Returns an NSArray instance containing the elements from the receiver sorted using comparator.
*/
- (GS_GENERIC_CLASS(NSArray, ElementT) *) sortedArrayUsingComparator:
(NSComparator)comparator;
/**
* Returns an NSArray instance containing the elements from the receiver using options, sorted
* using comparator.
*/
- (GS_GENERIC_CLASS(NSArray, ElementT) *)
sortedArrayWithOptions: (NSSortOptions)options
usingComparator: (NSComparator)comparator;
// Filtering Ordered Sets
- (NSOrderedSet *)filteredOrderedSetUsingPredicate: (NSPredicate *)predicate;
/**
* Returns an NSOrderedSet instance containing elements filtered using predicate.
*/
- (NSOrderedSet *) filteredOrderedSetUsingPredicate: (NSPredicate *)predicate;
// Describing a set
/**
* Description of this NSOrderedSet.
*/
- (NSString *) description;
/**
* Localized description of this NSOrderedSet.
*/
- (NSString *) descriptionWithLocale: (NSLocale *)locale;
/**
* Localized description, indented if flag is YES.
*/
- (NSString *) descriptionWithLocale: (NSLocale *)locale indent: (BOOL)flag;
// Convert to other types
// Convert to other types
/**
* Returns an NSArray instance with the objects contained in the receiver.
*/
- (GS_GENERIC_CLASS(NSArray, ElementT) *) array;
/**
* Returns an NSSet instance with the objects contained in the receiver.
*/
- (GS_GENERIC_CLASS(NSSet, ElementT) *) set;
@end
// Mutable Ordered Set
/**
* This class provides a mutable ordered set.
*/
GS_EXPORT_CLASS
@interface GS_GENERIC_CLASS(NSMutableOrderedSet, ElementT) : GS_GENERIC_CLASS(NSOrderedSet, ElementT)
// Creating a Mutable Ordered Set
+ (instancetype)orderedSetWithCapacity: (NSUInteger)capacity;
- (instancetype)initWithCapacity: (NSUInteger)capacity;
/**
* Returns an ordered set with capacity.
*/
+ (instancetype) orderedSetWithCapacity: (NSUInteger)capacity;
/**
* Initializes an ordered set with capacity.
*/
- (instancetype) initWithCapacity: (NSUInteger)capacity;
/**
* Initializes an empty ordered set.
*/
- (instancetype) init;
- (void)addObject: (GS_GENERIC_TYPE(ElementT))anObject;
- (void)addObjects: (const GS_GENERIC_TYPE(ElementT)[])objects count: (NSUInteger)count;
- (void)addObjectsFromArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray;
- (void)insertObject: (GS_GENERIC_TYPE(ElementT))object atIndex: (NSUInteger)index;
- (void)setObject: (GS_GENERIC_TYPE(ElementT))object atIndexedSubscript: (NSUInteger)index;
- (void)insertObjects: (GS_GENERIC_CLASS(NSArray, ElementT)*)array atIndexes: (NSIndexSet *)indexes;
- (void)removeObject: (GS_GENERIC_TYPE(ElementT))object;
- (void)removeObjectAtIndex: (NSUInteger)index;
- (void)removeObjectsAtIndexes: (NSIndexSet *)indexes;
- (void)removeObjectsInArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray;
- (void)removeObjectsInRange: (NSRange)range;
- (void)removeAllObjects;
- (void)replaceObjectAtIndex: (NSUInteger)index
withObject: (GS_GENERIC_TYPE(ElementT))object;
/**
* Adds an object to the receiver.
*/
- (void) addObject: (GS_GENERIC_TYPE(ElementT))anObject;
/**
* Adds items in the C array whose length is indicated by count to the receiver.
*/
- (void) addObjects: (const GS_GENERIC_TYPE(ElementT)[])objects count: (NSUInteger)count;
/**
* Adds objects from otherArray to the receiver.
*/
- (void) addObjectsFromArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray;
/**
* Inserts object into the receiver at index.
*/
- (void) insertObject: (GS_GENERIC_TYPE(ElementT))object atIndex: (NSUInteger)index;
/**
* Sets the object at index/
*/
- (void) setObject: (GS_GENERIC_TYPE(ElementT))object atIndexedSubscript: (NSUInteger)index;
/**
* Inserts objects at indexes from array. The number of elements in indexes must be the same as the number of
* elements in array.
*/
- (void) insertObjects: (GS_GENERIC_CLASS(NSArray, ElementT)*)array atIndexes: (NSIndexSet *)indexes;
/**
* Remove object from receiver.
*/
- (void) removeObject: (GS_GENERIC_TYPE(ElementT))object;
/**
* Remove object at index.
*/
- (void) removeObjectAtIndex: (NSUInteger)index;
/**
* Remove objects at indexes.
*/
- (void) removeObjectsAtIndexes: (NSIndexSet *)indexes;
/**
* Remove objects matching items in otherArray.
*/
- (void) removeObjectsInArray: (GS_GENERIC_CLASS(NSArray, ElementT)*)otherArray;
/**
* Remove objects at indexes matching range.
*/
- (void) removeObjectsInRange: (NSRange)range;
/**
* Remove all objects from the set.
*/
- (void) removeAllObjects;
/**
* Replace the object at index with object.
*/
- (void) replaceObjectAtIndex: (NSUInteger)index
withObject: (GS_GENERIC_TYPE(ElementT))object;
/**
* Replace objects at indexes with objects. The number of objects must correspond to the number of indexes.
*/
- (void) replaceObjectsAtIndexes: (NSIndexSet *)indexes
withObjects: (GS_GENERIC_CLASS(NSArray, ElementT)*)objects;
/**
* Replace objects in the given range with items from the C array objects.
*/
- (void) replaceObjectsInRange: (NSRange)range
withObjects: (const GS_GENERIC_TYPE(ElementT)[])objects
count: (NSUInteger)count;
- (void)setObject: (GS_GENERIC_TYPE(ElementT))object atIndex: (NSUInteger)index;
- (void)moveObjectsAtIndexes: (NSIndexSet *)indexes toIndex: (NSUInteger)index;
/**
* Set object at index.
*/
- (void) setObject: (GS_GENERIC_TYPE(ElementT))object atIndex: (NSUInteger)index;
/**
* Move objects at indexes to index.
*/
- (void) moveObjectsAtIndexes: (NSIndexSet *)indexes toIndex: (NSUInteger)index;
/**
* Exchange object at index with object at otherIndex.
*/
- (void) exchangeObjectAtIndex: (NSUInteger)index withObjectAtIndex: (NSUInteger)otherIndex;
- (void)filterUsingPredicate: (NSPredicate *)predicate;
/**
* Filter objects using predicate.
*/
- (void) filterUsingPredicate: (NSPredicate *)predicate;
/**
* Sort using descriptors.
*/
- (void) sortUsingDescriptors: (NSArray *)descriptors;
/**
* Sort using comparator
*/
- (void) sortUsingComparator: (NSComparator)comparator;
/**
* Sort with options and comparator.
*/
- (void) sortWithOptions: (NSSortOptions)options
usingComparator: (NSComparator)comparator;
/**
* Sort the given range using options and comparator.
*/
- (void) sortRange: (NSRange)range
options: (NSSortOptions)options
usingComparator: (NSComparator)comparator;
/**
* This method leaves only objects that interesect with ordered set aSet in the receiver.
*/
- (void) intersectOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet;
/**
* This method leaves only objects that intersect with set aSet in the receiver.
*/
- (void) intersectSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet;
/**
* Receiver contains itself minus those elements in ordered set aSet.
*/
- (void) minusOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet;
/**
* Receiver contains itself minus those elements in aSet.
*/
- (void) minusSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet;
/**
* Receiver contains the union of itself and ordered set aSet.
*/
- (void) unionOrderedSet: (GS_GENERIC_CLASS(NSOrderedSet, ElementT)*)aSet;
/**
* Receiver contains the union of itself and aSet.
*/
- (void) unionSet: (GS_GENERIC_CLASS(NSSet, ElementT)*)aSet;
/**
* Implementation of NSCopying protocol.
*/
- (instancetype) initWithCoder: (NSCoder *)coder;
@end