NSArray类的分析

/* NSArray.h
Copyright (c) 1994-2015, Apple Inc. All rights reserved.
*/

#import <Foundation/NSObject.h>
#import <Foundation/NSEnumerator.h>
#import <Foundation/NSRange.h>
#import <Foundation/NSObjCRuntime.h>

@class NSData, NSIndexSet, NSString, NSURL;

/**************** Immutable Array ****************/

NS_ASSUME_NONNULL_BEGIN

@interface NSArray<__covariant ObjectType> : NSObject <NSCopying, NSMutableCopying, NSSecureCoding, NSFastEnumeration>

@property (readonly) NSUInteger count;

- (ObjectType)objectAtIndex:(NSUInteger)index;//获取数组中索引为index的元素

- (instancetype)init NS_DESIGNATED_INITIALIZER;
- (instancetype)initWithObjects:(const ObjectType [])objects count:(NSUInteger)cnt NS_DESIGNATED_INITIALIZER;
- (nullable instancetype)initWithCoder:(NSCoder *)aDecoder NS_DESIGNATED_INITIALIZER;

@end

@interface NSArray<ObjectType> (NSExtendedArray)

- (NSArray<ObjectType> *)arrayByAddingObject:(ObjectType)anObject;//添加对象到数组最后一个元素

- (NSArray<ObjectType> *)arrayByAddingObjectsFromArray:(NSArray<ObjectType> *)otherArray;//将otherArray数组的元素添加到数组的末尾

- (NSString *)componentsJoinedByString:(NSString *)separator;//将数组元素用separator分隔符连接成一个字符串

- (BOOL)containsObject:(ObjectType)anObject;//判断数组中是否包含某个对象

@property (readonly, copy) NSString *description;
- (NSString *)descriptionWithLocale:(nullable id)locale;//遍历数组中的所有内容 将内容拼接成一个新的字符串返回
- (NSString *)descriptionWithLocale:(nullable id)locale indent:(NSUInteger)level;//获取第一个包含于另一个数组中的元素

- (nullable ObjectType)firstObjectCommonWithArray:(NSArray<ObjectType> *)otherArray;

- (void)getObjects:(ObjectType __unsafe_unretained [])objects range:(NSRange)range;//将数组中一定范围的元素读取到一个C数组中 objects参数需要为分配好空间的C指针

- (NSUInteger)indexOfObject:(ObjectType)anObject;//得到对象anObject在数组中的索引

- (NSUInteger)indexOfObject:(ObjectType)anObject inRange:(NSRange)range;//获取某个范围内的元素的下标值

- (NSUInteger)indexOfObjectIdenticalTo:(ObjectType)anObject;//获取与给定元素相同的元素在数组中的最小下标值

- (NSUInteger)indexOfObjectIdenticalTo:(ObjectType)anObject inRange:(NSRange)range;//在一定范围内 获取与给定元素相同的元素在数组中的最小下标值

- (BOOL)isEqualToArray:(NSArray<ObjectType> *)otherArray;//判断两个数组是否相同

@property (nullable, nonatomic, readonly) ObjectType firstObject NS_AVAILABLE(10_6, 4_0);//获取数组中第一个元素

@property (nullable, nonatomic, readonly) ObjectType lastObject;//获取数组中最后一个元素

- (NSEnumerator<ObjectType> *)objectEnumerator;//得到数组的枚举对象

- (NSEnumerator<ObjectType> *)reverseObjectEnumerator;//得到数组的反序枚举对象

@property (readonly, copy) NSData *sortedArrayHint;
- (NSArray<ObjectType> *)sortedArrayUsingFunction:(NSInteger (*)(ObjectType, ObjectType, void * __nullable))comparator context:(nullable void *)context;
- (NSArray<ObjectType> *)sortedArrayUsingFunction:(NSInteger (*)(ObjectType, ObjectType, void * __nullable))comparator context:(nullable void *)context hint:(nullable NSData *)hint;

- (NSArray<ObjectType> *)sortedArrayUsingSelector:(SEL)comparator;//使用comparator比较方法对数组进行排序

- (NSArray<ObjectType> *)subarrayWithRange:(NSRange)range;//获取数组一定范围的子数组

- (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;//将数组写入文件

- (BOOL)writeToURL:(NSURL *)url atomically:(BOOL)atomically;//将数组写入指定url路径

- (void)makeObjectsPerformSelector:(SEL)aSelector NS_SWIFT_UNAVAILABLE("Use enumerateObjectsUsingBlock: or a for loop instead");//是数组中的所有元素调用某个方法选择器

- (void)makeObjectsPerformSelector:(SEL)aSelector withObject:(nullable id)argument NS_SWIFT_UNAVAILABLE("Use enumerateObjectsUsingBlock: or a for loop instead");//是数组中的所有元素调用某个方法选择器

- (NSArray<ObjectType> *)objectsAtIndexes:(NSIndexSet *)indexes;//获取一个下标集合所对应的元素

- (ObjectType)objectAtIndexedSubscript:(NSUInteger)idx NS_AVAILABLE(10_8, 6_0);//数组的下标方法 子类重写

- (void)enumerateObjectsUsingBlock:(void (^)(ObjectType obj, NSUInteger idx, BOOL *stop))block NS_AVAILABLE(10_6, 4_0);//对数组中的元素进行枚举遍历

- (void)enumerateObjectsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(ObjectType obj, NSUInteger idx, BOOL *stop))block NS_AVAILABLE(10_6, 4_0);
- (void)enumerateObjectsAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts usingBlock:(void (^)(ObjectType obj, NSUInteger idx, BOOL *stop))block NS_AVAILABLE(10_6, 4_0);

- (NSUInteger)indexOfObjectPassingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);//通过遍历的方式查找符合条件的元素下标

- (NSUInteger)indexOfObjectWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);
- (NSUInteger)indexOfObjectAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts passingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);

- (NSIndexSet *)indexesOfObjectsPassingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);//通过遍历的方式查找所有符合条件的元素下标

- (NSIndexSet *)indexesOfObjectsWithOptions:(NSEnumerationOptions)opts passingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);

- (NSIndexSet *)indexesOfObjectsAtIndexes:(NSIndexSet *)s options:(NSEnumerationOptions)opts passingTest:(BOOL (^)(ObjectType obj, NSUInteger idx, BOOL *stop))predicate NS_AVAILABLE(10_6, 4_0);

- (NSArray<ObjectType> *)sortedArrayUsingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);//通过block进行数组排序

- (NSArray<ObjectType> *)sortedArrayWithOptions:(NSSortOptions)opts usingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);

typedef NS_OPTIONS(NSUInteger, NSBinarySearchingOptions) {
NSBinarySearchingFirstEqual = (1UL << 8),
NSBinarySearchingLastEqual = (1UL << 9),
NSBinarySearchingInsertionIndex = (1UL << 10),
};

- (NSUInteger)indexOfObject:(ObjectType)obj inSortedRange:(NSRange)r options:(NSBinarySearchingOptions)opts usingComparator:(NSComparator)cmp NS_AVAILABLE(10_6, 4_0); // binary search

@end

@interface NSArray<ObjectType> (NSArrayCreation)

+ (instancetype)array;//创建对象

+ (instancetype)arrayWithObject:(ObjectType)anObject;//通过一个元素创建数组对象

+ (instancetype)arrayWithObjects:(const ObjectType [])objects count:(NSUInteger)cnt;//通过C数组创建数组对象

+ (instancetype)arrayWithObjects:(ObjectType)firstObj, ... NS_REQUIRES_NIL_TERMINATION;//通过一组元素创建数组对象

+ (instancetype)arrayWithArray:(NSArray<ObjectType> *)array;//通过另一个数组创建数组对象

- (instancetype)initWithObjects:(ObjectType)firstObj, ... NS_REQUIRES_NIL_TERMINATION;//初始化方法

- (instancetype)initWithArray:(NSArray<ObjectType> *)array;//初始化方法

- (instancetype)initWithArray:(NSArray<ObjectType> *)array copyItems:(BOOL)flag;//初始化方法

+ (nullable NSArray<ObjectType> *)arrayWithContentsOfFile:(NSString *)path;//通过文件创建数组

+ (nullable NSArray<ObjectType> *)arrayWithContentsOfURL:(NSURL *)url;//通过url创建数组

- (nullable NSArray<ObjectType> *)initWithContentsOfFile:(NSString *)path;//通过文件l创建数组

- (nullable NSArray<ObjectType> *)initWithContentsOfURL:(NSURL *)url;//通过url创建数组

@end

@interface NSArray<ObjectType> (NSDeprecated)

/* This method is unsafe because it could potentially cause buffer overruns. You should use -getObjects:range: instead.
*/

- (void)getObjects:(ObjectType __unsafe_unretained [])objects;//获取数组所有元素 需要传入分配了内存的C指针

@end

/**************** Mutable Array ****************/

@interface NSMutableArray<ObjectType> : NSArray<ObjectType>

- (void)addObject:(ObjectType)anObject;//添加元素

- (void)insertObject:(ObjectType)anObject atIndex:(NSUInteger)index;//插入元素anObject到索引为index的位置上

- (void)removeLastObject;//删除数组中最后一个元素

- (void)removeObjectAtIndex:(NSUInteger)index;//移除数组中索引为index的元素

- (void)replaceObjectAtIndex:(NSUInteger)index withObject:(ObjectType)anObject;//将索引为index的元素替换为anObject对象

- (instancetype)init NS_DESIGNATED_INITIALIZER;//初始化

- (instancetype)initWithCapacity:(NSUInteger)numItems NS_DESIGNATED_INITIALIZER;
- (nullable instancetype)initWithCoder:(NSCoder *)aDecoder NS_DESIGNATED_INITIALIZER;

@end

@interface NSMutableArray<ObjectType> (NSExtendedMutableArray)
   

- (void)addObjectsFromArray:(NSArray<ObjectType> *)otherArray;//通过数组来追加元素

- (void)exchangeObjectAtIndex:(NSUInteger)idx1 withObjectAtIndex:(NSUInteger)idx2;//将索引为idx1的元素和索引为idx2的元素相互交换

- (void)removeAllObjects;//删除数组中所有元素

- (void)removeObject:(ObjectType)anObject inRange:(NSRange)range;//在一定范围内删除元素

- (void)removeObject:(ObjectType)anObject;//移除数组中和anObject一样的元素

- (void)removeObjectIdenticalTo:(ObjectType)anObject inRange:(NSRange)range;//删除指定范围内下标最小的某个元素

- (void)removeObjectIdenticalTo:(ObjectType)anObject;//删除某个元素 下标最小的

- (void)removeObjectsFromIndices:(NSUInteger *)indices numIndices:(NSUInteger)cnt NS_DEPRECATED(10_0, 10_6, 2_0, 4_0);//删除一定范围内的所有元素

- (void)removeObjectsInArray:(NSArray<ObjectType> *)otherArray;//通过数组删除元素

- (void)removeObjectsInRange:(NSRange)range;//通过范围删除元素

- (void)replaceObjectsInRange:(NSRange)range withObjectsFromArray:(NSArray<ObjectType> *)otherArray range:(NSRange)otherRange;//替换一组元素

- (void)replaceObjectsInRange:(NSRange)range withObjectsFromArray:(NSArray<ObjectType> *)otherArray;//替换一组元素

- (void)setArray:(NSArray<ObjectType> *)otherArray;//将数组内容替换为otherArray数组

- (void)sortUsingFunction:(NSInteger (*)(ObjectType,  ObjectType, void * __nullable))compare context:(nullable void *)context;//进行数组排序

- (void)sortUsingSelector:(SEL)comparator;//使用comparator比较方法进行排序

- (void)insertObjects:(NSArray<ObjectType> *)objects atIndexes:(NSIndexSet *)indexes;//插入一组元素

- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes;//删除一组元素

- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withObjects:(NSArray<ObjectType> *)objects;//替换一组元素

- (void)setObject:(ObjectType)obj atIndexedSubscript:(NSUInteger)idx NS_AVAILABLE(10_8, 6_0);//设置某个下标对应的元素 子类覆写

- (void)sortUsingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);//进行数组排序

- (void)sortWithOptions:(NSSortOptions)opts usingComparator:(NSComparator)cmptr NS_AVAILABLE(10_6, 4_0);//进行数组排序

@end

@interface NSMutableArray<ObjectType> (NSMutableArrayCreation)

+ (instancetype)arrayWithCapacity:(NSUInteger)numItems;//创建数组 numItems为元素个数

+ (nullable NSMutableArray<ObjectType> *)arrayWithContentsOfFile:(NSString *)path;//通过文件创建数组

+ (nullable NSMutableArray<ObjectType> *)arrayWithContentsOfURL:(NSURL *)url;//通过url创建数组

- (nullable NSMutableArray<ObjectType> *)initWithContentsOfFile:(NSString *)path;

- (nullable NSMutableArray<ObjectType> *)initWithContentsOfURL:(NSURL *)url;

@end

NS_ASSUME_NONNULL_END