Samond Classes Library 1.2.6-STABLE build 219
Programming Guide

Table of Contents

This document contains a description and summary guide to the use of various library units.
Because the that the library currently continues to improve, there may be some lag in this section of the real state of the software code. Therefore, in addition to studying this manual, we recommend to consult the description of the classes and library files.

Guide sections:

Introduction

Samond Classes Library is a suite of Objective-C protocols, classes and categories, incorporated with each other to perform the following tasks:

In the following sections we will look at various issues of the use of certain units of the library. The learning process of my development, we will follow various examples.

Just I want to draw your attention to the fact that several of my components in some duplicates the functionality of the individual elements of the standard classes, but personally I do not pay attention to it, because it allows for the implementation of projects to choose the most convenient and appropriate module.

Classes common elements

In this section, we examine the library components, by which all its modules, regardless of their type, have the same functionality. Order to ensure this both in our own classes, and classes in the standard Objective-C in the library are mandatory for the implementation of the protocols:

Implementation of these protocols is provided in the following structures:

Category NSObject(SCObject)

Category NSObject(SCObject) implements all of the above described protocols, thus providing support for the library functionality by all classes that are subclasses of the standard class NSObject. Because of this when you create a subclass of NSObject or categories of its existing child classes eliminates the need for the new implementation of the protocols - enough to override only the minimum necessary methods.

Class SCObject

All the library units (except for extending the functionality of the standard classes of categories and exception classes) are children of a common ancestor class SCObject. Beginning with version 1.2.1, this class is used to group own library classes, but in previous versions the class provided implementation of the main protocols, which is now implemented in the category NSObject(SCObject).

The class provides access to the following library features:

Class name determination

Common units for identifying instances of classes libraries use a method that is declared in key protocols as follows:

@property (nonatomic, readonly, copy) NSString *className;

The method returns the instance class name. Declaration of this method is necessary due to the fact that its support for the standard classes provided not on all platforms, while we tried to make our library to use the same regardless of the device on which the application using it will be performed.

When creating your own children of the NSObject or SCObject class you always must override this method. Also, the definition of this method is necessary for categories, which extends the standard classes and classes from the third-party libraries.

Serialized files support and protocol SCCoding

Standard Objective-C libraries make available features to read and write serialized files (special format of parameters list plist). To support these features protocol SCCoding (successor of standard protocol NSCoding) declares the following methods:

- (instancetype)initWithContentsOfSerializedFile:(NSString *)path;
- (BOOL)writeContentsToSerializedFile:(NSString *)path;

From standard protocol NSCoding protocol SCCoding inherits methods for interacting with the standard encoders (NSCoder):

- (instancetype)initWithCoder:(NSCoder *)coder;
- (void)encodeWithCoder:(NSCoder *)coder;

These methods must be overridden in child classes if they have their own fields. If a child class does not contain such fields, but only declares new or overrides existing methods, need to override these methods do not have.

More information about serialized files can be obtained from the guide section Serialized files support.

Dictionaries support and protocol SCDictionaring

Standard classes NSDictionary and NSMutableDictionary provide functionality for storing information in the properties list. This method of storage is used by the library as a way to store the instance data.

Protocol SCDictionaring requires implementation the following methods:

- (instancetype)initWithDataDictionary:(NSDictionary *)dictionary;
- (instancetype)initWithDataDictionaryFromFile:(NSString *)path;
- (void)writeToDataDictionary:(NSMutableDictionary *)dictionary;
- (void)writeToDataDictionaryFile:(NSString *)path atomically:(BOOL)atomically;
- (void)writeToDataDictionaryFile:(NSString *)path;
- (NSDictionary *)dataDictionary;

If the child class contains its own data fields, you need to override the methods initWithDataDictionary: and writeToDataDictionary:.

Work with dictionaries describes in the guide section Dictionaries support.

Streams support and protocol SCStreaming

The streams - implemented on the basis of class SCStream technologies for data streaming using different technologies - are currently supported file streams, standard input and output streams, and null output stream.

Protocol SCStreaming required implementatopm of the following methods:

- (instancetype)initWithStream:(SCStream *)stream;
- (instancetype)initWithFileStream:(NSString *)path;
- (void)writeToStream:(SCStream *)stream;
- (void)writeToFileStream:(NSString *)path;
- (void)appendToFileStream:(NSString *)path;

Methods initWithStream: and writeToStream: must be oveerided in the child class if this child class has the own data fields.

Details of streams you can obtain the the guide section Streams.

Collections support and protocol SCCollectioning

Collections are the data sets of various class instances. Collections are implemented as a separate class hierarchy based of the SCCollection class. Also some collections are implemented as a categories for extending the standard classes. To support collections each class must be implemented the following protocol SCCollectioning methods:

- (id)copyObject;
- (SCComparisonResult)compareWithObject:(id<SCCollectioning>)object;

Method compareWithObject: returns one of the following values:

SCComparisonEqual - an objects are equal
SCComparisonLess - a first instance is less then a second object
SCComparisonGreater - a second object is greater then a second object
SCComparisonNotAllowed - an objects cannot be compared

Details of collections unit can be obtained in the guide section Collections.

Interaction with Data Objects

Data objects are instances of classes NSData and NSMutableData, that provides the access to different data in the form of raw bytes. For interaction with data objects and files and URLs class SCObject implements the following methods from the protocol SCDating:

- (instancetype)initWithData:(NSData *)data;
- (instancetype)initWithDataWrapper:(SCData *)data;
- (instancetype)initWithContentsOfFile:(NSString *)path;
- (instancetype)initWithContentsOfURL:(NSURL *)url;
- (instancetype)initWithContentsOfURLString:(NSString *)urlString;
- (void)writeToData:(NSMutableData *)data;
- (BOOL)writeToFile:(NSString *)path;
- (BOOL)writeToURL:(NSURL *)url;
- (BOOL)writeToURLString:(NSString *)urlString;
- (NSData *)data;

See details about data objects in the appropriate section of this manual.

Library functionality and standard classes

As noted above, when using with the children of class SCObject to interact with various library units necessary the overring only the specified methods.

However, the implementation of categories expanding the standard classes are subject to all of the methods of the relevant protocols.

Serialized files support

Serialized files are a special version of the properties list file that allow you to store various data in XML files. Reading and writing this file are made by standard class NSCoder instances.

The basic functionality of serialized files is implemented in the standard protocol NSCoding. SCL extends this functionality especially in order to bring it to a common format with other units.

This section of the manual describes the techniques and methods of working with sequential files. Requirements for class instances are described in the section Serialized files support and protocol SCCoding. Note that the main requirement - compliance with the protocol SCCoding.

Section contents:

Instances storing

Writing to serialized file by using the method writeContentsToSerializedFile:, as a parameter that gives the path to the file. If the write operation is successful, the method returns the value YES, otherwise it returns NO. If a serialized file already exists, its contents destroyed.

NSString *sourceString = @"Sample source string";
if ( [sourceString writeContentsToSerializedFile:@"/tmp/serial.plist"]) {
NSLog( @"Writing complited");
} else {
NSLog( @"Writing error");
}
2016-06-17 02:24:14.644 libtest[14033:493323] Writing complited

The resulting file is an example of a method using:

sample_03_01.png

Instances loading

Initialize a class instance by using the data from the serialized file is performed by the method initWithContentsOfSerializedFile:, which is passes as a parameter the path to the serialized file.

NSString *string = [[NSString alloc] initWithContentsOfSerializedFile:@"/tmp/serial.plist"];
NSLog( @"%@", string);
2016-06-17 02:57:16.339 libtest[14308:521945] Sample source string

In many classes and categories are declared the additional class methods that return from serialized files downloaded and initialized instances of classes:

+ (SCArray *)arrayWithCoder:(NSCoder *)coder;
+ (SCArray *)arrayWithContentsOfSerializedFile:(NSString *)path;

Dictionaries support

Dictionaries on the basis of the standard classes NSDictionary and NSMutableDictionary and provide universal access to data stores, working on the principle of "key-value", according to which access to stored data is carried out by means of the keys, as who might be instances of any objects Objective-C.

Dictionaries are directly related to the properties list. With this available programmers are not only simple tools for the organization of universal storage, but also the possibility to control and edit these storage - built-in Xcode property list editor provides easy access to data.

With the dictionaries can interact instances of classes that match SCDictionaring protocol. Description of the implementation of this protocol is given in section Dictionaries support and protocol SCDictionaring.

Section contents:

Writing to data dictionary

The basic method for recording data in the dictionary is the method writeToDataDictionary:, receiving as a parameter the dictionary (NSMutableDictionary class instance), which is performed for instance writing. This method is subject to the overlap in child classes to keep in dictionaries other than the ancestor class data, if necessary.

Here is an example saving in the dictionary the class instance:

SCDictionary *sourceDictionary = [SCDictionary dictionaryWithName:@"Configuration"];
[sourceDictionary setObject:@"MacOS" forKey:@"System"];
[sourceDictionary setObject:@NO forKey:@"Verbose"];
[sourceDictionary setObject:@2319 forKey:@"Build"];
[sourceDictionary setObject:[NSDate date] forKey:@"Startup"];
NSMutableDictionary *dictionary = [NSMutableDictionary dictionary];
[sourceDictionary writeToDataDictionary:dictionary];
NSLog( @"%@", dictionary);
2017-09-10 10:43:29.416454+0300 libtest[13324:1085938] {
"Read Only" = 0;
"Item 3" = {
Key = {
OBJC_ClassName = NSString;
String = System
};
Object = {
OBJC_ClassName = NSString;
String = MacOS
}
};
"Item 0" = {
Key = {
OBJC_ClassName = NSString;
String = Build
};
Object = {
OBJC_ClassName = NSNumber;
Number = 2319
}
};
"Item 1" = {
Key = {
OBJC_ClassName = NSString;
String = Verbose
};
Object = {
OBJC_ClassName = NSNumber;
Number = 0
}
};
"Item 2" = {
Key = {
OBJC_ClassName = NSString;
String = Startup
};
Object = {
OBJC_ClassName = NSDate;
Date = "2017-09-10 07:43:29 +0000"
}
};
OBJC_ClassName = SCDictionary;
Name = Configuration
}

Property dataDictionary returns the dictionary with stored class instance:

NSString *sourceString = @"Sample UTF-8 string";
NSLog( @"%@", sourceString.dataDictionary);
2016-06-17 04:25:17.156 libtest[14713:582644] {
"OBJC_ClassName" = NSString;
String = "Sample UTF-8 string";
}

Writing the class instance into the properties list is carried out by the following methods:

- (void)writeToDataDictionaryFile:(NSString *)path atomically:(BOOL)atomically;
- (void)writeToDataDictionaryFile:(NSString *)path;

Both methods accept as an argument the path to the file. If this file exists, its contents destroyed. The difference between the methods is that the first of these parameter atomically: allows you to specify whether a file is produced directly (NO) or through an intermediate file (YES). The second method always writes through an intermediate file.

SCDictionary *sourceDictionary = [SCDictionary dictionaryWithName:@"Configuration"];
[sourceDictionary setObject:@"MacOS" forKey:@"System"];
[sourceDictionary setObject:@NO forKey:@"Verbose"];
[sourceDictionary setObject:@2319 forKey:@"Build"];
[sourceDictionary setObject:[NSDate date] forKey:@"Startup"];
[sourceDictionary writeToDataDictionaryFile:@"/tmp/data.plist"];

After executing this code creates a file with the following content:

sample_03_02.png

Since version 1.2.5 into a class NSMutableDictionary was added the following method:

- (void)addObject:(id<SCDictionaring>)object forKey:(NSString *)key;

This method stores the specified object with a given key in a data dictionary format. Use of this method instead a standard method setObject:forKey: guarantees that the object and its key will be saved regardless of their type - a standard dictionaries support into a dictionary file a limited number of types of objects and can use in a dictionary file only NSString keys.

Reading from data dictionary

To download class instances from the dictionaries and property lists you can using the following methods:

- (instancetype)initWithDataDictionary:(NSDictionary *)dictionary;
- (instancetype)initWithDataDictionaryFromFile:(NSString *)path;

Method initWithDataDictionary: initializes a class instance by using the data from the specified dictionary. By overlapping this method is carried out in the child classes to add support for loading from the dictionaries of their own data.

The method initWithDataDictionaryFromFile: carried out a class instance initialization by using the data from the property list with the specified path.

In many classes and c ategories are declared the additional class methods that returns downloaded from dictionaries and property lists and initializes class instances.

+ (SCQueue *)queueWithDataDictionary:(NSDictionary *)dictionary;
+ (SCQueue *)queueWithDataDictionaryFromFile:(NSString *)path;

Since version 1.2.5 in addition to a standard method objectForKey: into a class NSDictionary the method os added:

- (id)getObjectForKey:(NSString *)key;

This method creates and returns an object for a given key, which was saved earlier in a data dictionary format. Method provides support in dictionary files of all object types and keys, and not just what are by default supported by the classes NSDictionary and NSMutableDictionary.

Streams

Streams are a group of classes that implement the concept of byte-oriented input and output media. According to this concept, the streams realize input and output data withot any processing (exception for class instances and strings - their processing is a part of streams unit).

Section contents:

Stream classes hierarchy

streams.png

The common ancestor of stream classes is class SCStream that defines all stream mechanisms, except input and output operation - in the class SCStream methods for this operations are abstract.

Child classes mandatory override input and output methods, and, if necessaity, adding the techniques that are specified to the certain stream type. For example, the child class SCFileStream declares open and closing methods.

Description of streams we start with methods of class SCStreams, but because of its abstractness in the example we will use real streams instances, primarily SCFileStream class instances. After the description common to all methods and techniques, we turn to the description of specified stream classes.

Stream error processing

When working with different streams can occur errors associated directly with the streams (or specific classes of stream) and appearing outside of our code, for example when trying to write to a file available only for reading.

Error handling mode is defines through the property errorHandling and can be one of the following values:

By default the strem throws the SCStreamException exception.

Exception SCSystemException generation

Mode is activated through the direct on indirect assignment of property errorHandling the value SCStreamErrorHandlingSystem.

When using this option strem unit throws a SCSystemException exception, which contains information about an error that has been returned by the system call or the function of standard libraries. Class SCSystemException instance property error contains the identifier of a detected system error. For more information see Programming Guide section Class SCSystemException.

Give an example of using this method of handling errors:

SCFileStream *stream = [[[SCFileStream alloc] init] autorelease];
stream.errorHandling = SCStreamErrorHandlingSystem;
[stream openReadOnlyWithPath:@"/tmp/error.txt"];
[stream close];
2016-07-05 23:01:53.322 libtest[5608:1486493] SCL-20002: No such file or directory (2, /tmp/error.txt)

Exception SCStreamException generation

Mode is activated through the direct or indirect assignment of property errorHandling the value SCStreamErrorHandlingStream.

This error handling mode throws an exception SCStreamException which contains information to help determine the cause of the error. Unlike class SCSystemException instance class SCStreamException contains information about stream specified error.

With this exception can be handled the following errors:

Here is an example of stream error handling through thr throwing the exception SCStreamException:

SCFileStream *stream = [SCFileStream readOnlyFileStreamWithPath:@"/tmp/start.txt"];
[stream close];
2016-07-05 22:52:34.159 libtest[5534:1475780] SCL-20029: Stream "/tmp/start.txt" open error (2)

Stream status changing

Mode is activated through the direct or indirect assignment of property errorHandling the value SCStreamErrorHandlingStatus.

When using this error handling mode the stream unit processes the detected error by using the following algorithm:

Here is an example of error handling using this method:

SCFileStream *stream = [[[SCFileStream alloc] init] autorelease];
stream.errorHandling = SCStreamErrorHandlingStatus;
[stream openReadOnlyWithPath:@"/tmp/error.txt"];
NSLog( @"Stream status: %d", stream.status);
[stream close];
2016-07-05 23:19:45.803 libtest[5678:1502988] Stream status: -20029

Stream status

Stream status is determined by the following property:

@property (nonatomic, readonly, assign) SCStreamStatus status;

Directly through the SCStreamStatus type defines the following stream statuses:

Child classes can define their own types of derived stream states. For example, class SCFileStream defines the type SCFileStreamStatus, which extends the basic stream states. Details of this extension are described in the Programming Guide section Files and class SCFileStream.

Stream Properties

Class SCStream contains the declaration of the following properties:

@property (nonatomic, readwrite, assign) SCStreamErrorHandling errorHandling;
@property (nonatomic, readonly, assign) SCStreamStatus status;
@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) BOOL opened;
@property (nonatomic, assign, readonly, getter=eof) BOOL eof;
@property (nonatomic, assign, getter=delegate, setter=setDelegate:) id<SCStreamDelegate> delegate;
@property (nonatomic, readonly, assign) BOOL readable;
@property (nonatomic, assign, readonly, getter=writable) BOOL writable;
@property (nonatomic, assign, readonly, getter=readOnly) BOOL readOnly;
@property (nonatomic, assign, readonly, getter=writeOnly) BOOL writeOnly;
@property (nonatomic, assign, readonly, getter=readWrite) BOOL readWrite;
@property (nonatomic, assign, readonly, getter=streamException) SCStreamException *streamException;
@property (nonatomic, assign, readonly, getter=systemException) SCSystemException *systemException;

Child classes can be declare the own properties.

Data reading from stream

The main method of reading data from the stream SCStream declared in the class as follows:

- (SCSize)readBytes:(SCSize)count toBuffer:(void *)buffer;

This method reads from the stream specified number of bytes into the specified by the pointer buffer. Method returns the actually readed bytes number. In the base class SCStream this method is abstract and must be overridden in all child classes for supporting real reading operations.

In addition to the basic reading method class SCStream declares the specialized methods, providing reading into the buffer the specified data types. In fact, these methods call the method readBytes:toBuffer: with the hidden indication of the number of bytes, which corresponding to the specified type. This methods also return the actually readed number of bytes.

- (SCSize)readToByte:(SCByte *)buffer;
- (SCSize)readToUByte:(SCUByte *)buffer;
- (SCSize)readToShort:(SCShort *)buffer;
- (SCSize)readToUShort:(SCUShort *)buffer;
- (SCSize)readToInteger:(SCInteger *)buffer;
- (SCSize)readToUInteger:(SCUInteger *)buffer;
- (SCSize)readToLong:(SCULong *)buffer;
- (SCSize)readToULong:(SCULong *)buffer;
- (SCSize)readToChar:(char *)buffer;
- (SCSize)readToUnichar:(unichar *)buffer;
- (SCSize)readToCharString:(char *)buffer max:(SCSize)max;
- (SCSize)readToBool:(BOOL *)buffer;
- (SCSize)readToFloat:(SCFloat *)buffer;
- (SCSize)readToDouble:(SCDouble *)buffer;
- (SCSize)readToNSInteger:(NSInteger *)buffer;
- (SCSize)readToNSUInteger:(NSUInteger *)buffer;

Also class SCStream declares the methods, which return from the stream the data for the corresponding types.

- (SCByte)readByte;
- (SCUByte)readUByte;
- (SCShort)readShort;
- (SCUShort)readUShort;
- (SCInteger)readInteger;
- (SCUInteger)readUInteger;
- (SCLong)readLong;
- (SCULong)readULong;
- (char)readChar;
- (unichar)readUnichar;
- (const char *)readCharString;
- (BOOL)readBool;
- (SCFloat)readFloat;
- (SCDouble)readDouble;
- (NSInteger)readNSInteger;
- (NSUInteger)readNSUInteger;

Note that the data reading from the stream is possible only if the stream supports a data read operations. Otherwise, the stream unit detects an error.

Data writing to stream

Class SCStream declares the following primary data writing method:

- (SCSize)writeBytes:(SCSize)count fromBuffer:(const void *)buffer;

This method writes into the stream the specified number of bytes from the specified buffer. Method also returns the actually writed number of bytes. In the class SCStream this method is abstract and must be overridden in any child class.

To simplify the work with the standard data types class SCStream declares the following writing methods:

- (void)writeByte:(SCByte)variable;
- (void)writeUByte:(SCUByte)variable;
- (void)writeShort:(SCShort)variable;
- (void)writeUShort:(SCUShort)variable;
- (void)writeInteger:(SCInteger)variable;
- (void)writeUInteger:(SCUInteger)variable;
- (void)writeLong:(SCLong)variable;
- (void)writeULong:(SCULong)variable;
- (void)writeChar:(char)variable;
- (void)writeUnichar:(unichar)variable;
- (void)writeCharString:(const char *)variable;
- (void)writeBool:(BOOL)variable;
- (void)writeFloat:(SCFloat)variable;
- (void)writeDouble:(SCDouble)variable;
- (void)writeNSInteger:(NSInteger)variable;
- (void)writeNSUInteger:(NSUInteger)variable;

I want note that the writing operations are possible only if this stream supports this operations. If any of writing methods was called for read only stream, the error was occur.

Streams and classes

Although the basis of streams is character-oriented data transferring, the main stream purpose is class instances transmitting. With streams can interact only instances, which implements the protocol SCStreaming:

Protocol SCStreaming methods

For supporting interaction with streams protocol SCStreaming declares the following methods:

- (void)writeToStream:(SCStream *)stream;
- (instancetype)initWithStream:(SCStream *)stream;

In addition to the method of initializing an instance the class can be declared a class method to create an instance by using the loaded from stream data. Here is an example of such class method from the category NSString(SCString):

+ (NSString *)stringWithStream:(SCStream *)stream;

Class SCFileStream uses a number of protocol SCStreaming methods, which are described in Programming Guide section Files and class SCFileStream.

Class SCStream methods

For reading and writing class instances SCStream declares the following methods:

- (id)readObject;
- (void)writeObject:(id<SCStreaming>)object;

The method writeObject: writes into the stream the specified class instance. Just before writing class instance the stream unit identifies the class of the instance and writes into the stream the service information required for the later class instance loading. After writing the service information the stream unit calls the stored class method writeToStream:.

Method readObject reads from the stream the service information, detectes the required class name, creates the required class instance and calls the instance method initWithStream: for loading the instance specified data from the stream.

Give an example of the using the methods writeObject: and readObject:

SCFileStream *outputStream = [SCFileStream writeOnlyFileStreamWithPath:@"/tmp/information.dat"];
[outputStream writeObject:@"Sample String"];
[outputStream writeObject:@"This is a test"];
[outputStream writeObject:[NSNull null]];
[outputStream writeObject:[NSNumber numberWithInteger:19091975]];
[outputStream close];
SCFileStream *inputStream = [SCFileStream readOnlyFileStreamWithPath:@"/tmp/information.dat"];
SCInteger counter = 0;
while ( YES) {
id object = [inputStream readObject];
if ( !object) break;
NSLog( @"Object %d: %@", counter, object);
counter++;
}
[inputStream close];
2016-07-06 15:37:15.691 libtest[8743:2490662] Object 0: Sample String
2016-07-06 15:37:15.692 libtest[8743:2490662] Object 1: This is a test
2016-07-06 15:37:15.693 libtest[8743:2490662] Object 2: <null>
2016-07-06 15:37:15.694 libtest[8743:2490662] Object 3: 19091975

Streams and text files

Unlike ordinary files, text files do not consist of a sequence of characters. Text files contain the character strings of different length, each of which ends with a special and of line character. To work with such data class SCStream declares the some methods.

For writing text strings into the stream class SCStream declares the following methods:

- (void)writeString:(NSString *)string encoding:(NSStringEncoding)encoding;
- (void)writeString:(NSString *)string;

Example of writing text strings into the stream:

SCStream *stdoutStream = [SCStandardOutputStream stdoutStream];
[stdoutStream writeString:@"This is a test"];
[stdoutStream writeString:@"This is a test again"];
This is a test
This is a test again

For reading text strings from the stream class SCStream declares the following methods:

- (NSString *)readStringWithEncoding:(NSStringEncoding)encoding max:(SCInteger)max;
- (NSString *)readStringWithEncoding:(NSStringEncoding)encoding;
- (NSString *)readStringWithMax:(SCInteger)max;
- (NSString *)readString;

Here is an example of strings reading from the stream:

SCFileStream *file = [SCFileStream readOnlyFileStreamWithPath:@"/etc/afpovertcp.cfg"];
NSString *string;
while ( ( string = [file readString])) NSLog( @"%@", string);
[file close];
2016-07-06 17:46:00.777 libtest[9504:2628316] #
2016-07-06 17:46:00.777 libtest[9504:2628316] # /etc/afpovertcp.cfg is used to set the system-wide AFP defaults
2016-07-06 17:46:00.777 libtest[9504:2628316] # for the LibcAT AppleTalk library.
2016-07-06 17:46:00.778 libtest[9504:2628316] #
2016-07-06 17:46:00.778 libtest[9504:2628316] # Copyright 1998 Apple Computer, Inc.
2016-07-06 17:46:00.778 libtest[9504:2628316] #
2016-07-06 17:46:00.778 libtest[9504:2628316] # If this file exists, TCP/IP will be used as the default transport
2016-07-06 17:46:00.778 libtest[9504:2628316] # protocol for AFP. Otherwise ATP will be used.
2016-07-06 17:46:00.778 libtest[9504:2628316] #
2016-07-06 17:46:00.779 libtest[9504:2628316] # Supported commands are:
2016-07-06 17:46:00.779 libtest[9504:2628316] #
2016-07-06 17:46:00.779 libtest[9504:2628316] # quantum [quantum size]
2016-07-06 17:46:00.779 libtest[9504:2628316] # 16384 is a reasonable value; 4624 is the default.
2016-07-06 17:46:00.814 libtest[9504:2628316] #
2016-07-06 17:46:00.814 libtest[9504:2628316] # port [TCP listen port]
2016-07-06 17:46:00.814 libtest[9504:2628316] # The default is 548.
2016-07-06 17:46:00.815 libtest[9504:2628316] #
2016-07-06 17:46:00.815 libtest[9504:2628316] # It is legal for this file to exist and for it to have no contents.
2016-07-06 17:46:00.815 libtest[9504:2628316] #
2016-07-06 17:46:00.815 libtest[9504:2628316] quantum 16384

Delegation protocol SCStreamDelegate

If for the stream is specified the delegate object (instance of the class, which implemented the protocol SCStreamDelegate), then the appropriate methods of delegate object will be called when the events occur.

Delegation protocol defines methods to respond to the following events:

Child classes may be added to the delegate object handlers of their own events. That's what makes SCFileStream class.

A full list of the methods shown in the description of the relevant protocol and class SCStreamDelegate.

Stream statistics

In the during the work a stream is accumulate basic statistical data. Access to this data is carried out through class SCStream instance properties (read only):

@property (nonatomic, assign, readonly, getter=totalRead) SCULong totalRead;
@property (nonatomic, assign, readonly, getter=totalWrite) SCULong totalWrite;
@property (nonatomic, assign, readonly, getter=lastRead) SCULong lastRead;
@property (nonatomic, assign, readonly, getter=lastWrite) SCULong lastWrite;

For resetting the stream statistics class SCStream declares the method resetStats.

Files and class SCFileStream

As already states, SCStream is an abstract class and con not be used directly. Therefore, the different child classes have benn created, the central of which is the class SCFileStream, that is, a class that implements one of the most popular stream type - disk files. This guide section examine the various aspects of class SCFileStream:

Protocol SCStreaming methods

Protocol SCStreaming for interacting with file streams declares the following methods:

- (void)writeToFileStream:(NSString *)path;
- (void)appendToFileStream:(NSString *)path;
- (instancetype)initWithFileStream:(NSString *)path;

In addition to the initialization methods may be declared the class methods for creating class instances by using the data readed from the file stream with the specified path. For example, category NSString(SCString) declares the following class methods:

+ (NSString *)stringWithFileStream:(NSString *)path;

Below is an example of the using the protocol SCStreaming methods:

NSString *source = @"This is a test again";
[source writeToFileStream:@"/tmp/string.dat"];
NSString *string = [NSString stringWithFileStream:@"/tmp/string.dat"];
NSLog( @"%@", string);
2016-07-06 16:34:03.204 libtest[9064:2557807] This is a test again

File stream error processing

File stream error are handled as exactly as SCStream errors. The only difference is that in the class SCStreamException declares the following additional exceptions:

File stream status

Class SCFileStream extends the stream status data type SCStreamStatus by declaring the file stream status data type SCFileStreamStatus, which defines the following status constants:

File stream opening modes

File stream can be opened in various modes. Open mode defines by the class SCFileStream instance property (read only):

@property (nonatomic, readonly, assign) SCFileStreamOpenMode openMode;

Type SCFileStreamOpenMode defines the following file stream open modes:

File stream open mode defines during opening, initializing and creating the stream and does not changes during read, write and offset operations. You cannot change the open mode thithout closing and reopening the file stream.

File stream opening and closing

Class SCFileStream declares the following methods for opening file stream:

- (void)openWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode handling:(SCStreamErrorHandling)handling;
- (void)openWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode;
- (void)openWithPath:(NSString *)path;
- (void)openReadOnlyWithPath:(NSString *)path;
- (void)openWriteOnlyWithPath:(NSString *)path;
- (void)openAppendWithPath:(NSString *)path;

If no errors detected during the opening operation, than the file stream status is set to SCFileStreamOK, and an instance property opened is set to value YES. If you call the any of stream open methods for already opening stream, than call of this method is ignored.

For closing the file stream the class SCFileStream declares the following method:

- (void)close;

Method closes the previously opened file stream and sets the instance property opened to the value NO. If you call the method close for closed file stream, the method call is ignored.

File stream creating

Class SCFileStream declares the following method for creating the class instances:

+ (instancetype)fileStreamWithPath:(NSString *)path
mode:(SCFileStreamOpenMode)mode
delegate:(id<SCStreamDelegate>)delegate
handling:(SCStreamErrorHandling)handling;
+ (instancetype)fileStreamWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode delegate:(id<SCStreamDelegate>) delegate;
+ (instancetype)fileStreamWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode;
+ (instancetype)fileStreamWithPath:(NSString *)path;
+ (instancetype)readOnlyFileStreamWithPath:(NSString *)path;
+ (instancetype)writeOnlyFileStreamWithPath:(NSString *)path;
+ (instancetype)appendFileStreamWithPath:(NSString *)path;
+ (instancetype)fileStream;

All class methods, except fileStream, open the created file stream. If this operation is successfully, then instance property opened is set to value YES, and instance property status is set to value SCFileStreamOK.

Introducing an example of using the file stream creating methods:

SCFileStream *ttys = [SCFileStream readOnlyFileStreamWithPath:@"/etc/ttys"];
NSLog( @"/etc/ttys status: %d", ttys.status);
if ( ttys.opened) NSLog( @"/etc/ttys is opened");
[ttys close];
2016-07-07 03:20:14.014 libtest[11678:3116658] /etc/ttys status: 0
2016-07-07 03:20:14.014 libtest[11678:3116658] /etc/ttys is opened

File stream initializing

Class SCFileStream declares the following methods for initializing the class instances:

- (instancetype)initWithPath:(NSString *)path
mode:(SCFileStreamOpenMode)mode
delegate:(id<SCStreamDelegate>)delegate
handling:(SCStreamErrorHandling)handling;
- (instancetype)initWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode delegate:(id<SCStreamDelegate>)delegate;
- (instancetype)initWithPath:(NSString *)path mode:(SCFileStreamOpenMode)mode;
- (instancetype)initWithPath:(NSString *)path;
- (instancetype)initReadOnlyWithPath:(NSString *)path;
- (instancetype)initWriteOnlyWithPath:(NSString *)path;
- (instancetype)initAppendWithPath:(NSString *)path;
- (instancetype)init;

All initialization methods, except init, open the file stream after initialization. If the open operation is successfully, the instance property SCStream.opened "opened" is set to value YES, and the property status is set to value SCFileStreamOK.

File stream offset

File streams support the offset operations, that is a change the position of next read or write operation. Class SCFileStream declares the following offset methods:

@property (nonatomic, readonly, assign) BOOL eof;
- (void)setOffset:(NSInteger)offset whence:(SCFileStreamOffsetWhence)whence;
- (void)setOffset:(NSInteger)offset;
- (NSInteger)offset;
- (void)rewind;

When using for positioning the method setOffset:whence: as the second argument passes one of the floowing constant from the type SCFileStreamOffsetWhence :

Delegation protocol SCStreamDelegate methods

Class SCFileStream adds into the delegation protocol SCStreamDelegate methods, which called when file stream is open or close. See details in the Programming Guide section Delegation protocol SCStreamDelegate.

Standard streams

Library includes the following classes to provide access to the standard input and output streams:

All three of the above classes are children of the SCStream class. In the following sections, each of classes is described in more detail.

Standard input stream SCStandardInputStream

Class SCStandardInputStream gives programmers access to the standard input stdin. This stream provides a read-only operations.

To provide access to this stream in the class declared the following methods:

+ (instancetype)stdinStreamWithDelegate:(id<SCStreamDelegate>)delegate;
+ (instancetype)stdinStream;

Please note the both of this methods always return a pointer to the same stream - because the standard input stream stdin exists in a single copy in the operating system. Furthemore the existence of multiple instances of classes may potentially lead to conflicts, especially when the objects were created several different threads.

Provide the example of using the standard input stream:

SCStandardInputStream *input = [SCStandardInputStream stdinStream];
while ( !input.eof) {
NSString *string = [input readString];
if ( string) NSLog( @"%@", string);
}
Sample input string
2016-07-08 00:54:46.809 libtest[17772:4042392] Sample input string
Request for proposal
2016-07-08 00:54:54.691 libtest[17772:4042392] Request for proposal
Last entered string
2016-07-08 00:55:01.249 libtest[17772:4042392] Last entered string

Standard output stream SCStandardOutputStream

Class SCStandardOutputStream provides programmers access to the standard output stream stdout. This stream allows only a write operations.

For access to this output stream in the class SCStandardOutputStream declares the following methods:

+ (instancetype)stdoutStreamWithDelegate:(id<SCStreamDelegate>)delegate;
+ (instancetype)stdoutStream;

Please note the both of this methods always return a pointer to the same stream - because the standard output stream stdout exists in a single copy in the operating system. Furthemore the existence of multiple instances of classes may potentially lead to conflicts, especially when the objects were created several different threads.

Example of using the standard output stream:

SCStandardOutputStream *output = [SCStandardOutputStream stdoutStream];
[output writeString:@"Sample output string"];
[output writeString:@"This is a test string"];
[output writeString:@"Last output string"];
Sample output string
This is a test string
Last output string

Standard error stream SCStandardErrorStream

Class SCStandardErrorStream provides programmers access to the standard error stream stderr. This stream provides a write-only operations.

To provide access to this stream in the class SCStandardErrorStream declares the following classes:

+ (instancetype)stderrStreamWithDelegate:(id<SCStreamDelegate>)delegate;
+ (instancetype)stderrStream;

Please note that the both of described methods always return a pointer to the same stream - because the standard error stream stderr exists in a single copy in the operating system. Furthemore the existence of multiple instances of classes may potentially lead to conflicts, especially when the objects were created several different threads.

Example of using the standard error stream:

SCStandardErrorStream *error = [SCStandardErrorStream stderrStream];
[error writeString:@"System error: 2319"];
[error writeString:@"Application error: 2315"];
[error writeString:@"Fatal falture"];
System error: 2319
Application error: 2315
Fatal falture

Null output stream SCNullStream

Class SCNullStream is a child of the class SCStream and provides access to the system device /dev/null. This stream supports only write operations. The main purpose of the null stream - the ability to write into the stream an unlimited number of data (all writed into the null stream data are discarded).

Access to the null stream provides with using the following class SCNullStream methods:

+ (instancetype)nullStreamWithDelegate:(id<SCStreamDelegate>)delegate;
+ (instancetype)nullStream;

Please note that the both of this methods always return a pointer to the same stream - because the /dev/null stream exists in a single copy in the operating system. Furthemore the existence of multiple instances of classes may potentially lead to conflicts, especially when the objects were created several different threads.

Collections

Collections are instances of classes, which are containers for instances of other classes. A typical example of the collection is object instances array. The library includes two types of collections:

Library collections interact with processed objects through the protocol SCCollectioning methods.

Section contents:

Collection classes hierarchy

collections.png

Class SCCollection is an abstract class, because it does not contains real data storage mechanisms, implemented in the child classes in accordance with their function. However class SCCollection declares the collection common methods, which override in the child classes.

Collection class types

To organize the distribution of functionality by collection classes and categories and simplify implementation of collection functions we create the set of protocols, compliance with which determines the compatibility of library collections. In this set include the following protocols:

In the following paragraphs, these protocols will be reviewed in more details.

SCCollection protocol

Protocol defines the list of properties and methods, which implementation in the class or category required for support functionality of read-only collections. All collection classes are compliance to this protocol. Also with SCCollection protocol are compliance the following categories of standard classes:

Protocol declares the following properties, which required for all collection classes:

@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) SCIndex count;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL readOnly;
@property (nonatomic, readonly, retain) id<SCCollectionDelegate> delegate;

Collection classes and categories must be implemented the following initialization methods:

- (instancetype)initWithCollection:(id<SCCollection>)collection;

SCCollection protocol requires the implementation of the following objects search methods:

- (BOOL)containsObject:(id<SCCollectioning>)object;
- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Protocol requires the implementation of the following converting properties for all collection instances:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, retain) NSArray *foundationArray;
@property (nonatomic, readonly, retain) NSSet *foundationSet;
@property (nonatomic, readonly, retain) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, retain) NSDictionary *foundationDictionary;

Attention! When using instances of the class NSOrderedSet you must use the property libraryArray instead a property array because of existence in a class the method with this name.

For collection type detection all collection classes and categories must emplemented the following protocol SCCollection properties:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Also protocol declares the following optional properties for support the collection enumerating:

@property (nonatomic, readonly, assign) NSEnumerator *objectEnumerator;
@property (nonatomic, readonly, assign) NSEnumerator *reverseObjectEnumerator;

Support of operator for..in in collection classes is provided with implementation of the following protocol method:

- (NSUInteger)countByEnumeratingWithState:(NSFastEnumerationState *)state objects:(id *)objects count:(NSUInteger)count;

For comparing collections the protocol declares following methods:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Description above properties and methods given in the relevant sections of the Programming Guide.

SCMutableCollection protocol

Protocol SCMutableCollection extends the protocol SCCollection by declaring the methods, which must be implemented in the collection classes and categories for support the collection changing. All librray collections implement this methods of protocol SCMutableCollection. Also with the SCMutableCollection protocol are compliance the following standard classes categories:

Protocol requires the implementation of the following coping methods:

- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

For protocol compliance must be implemented the following object adding methods:

- (void)addObject:(id<SCCollectioning>)object;
- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;

Also protocol requires the implementation of the following object removing methods:

- (void)removeAllObjects;
- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObject:(id<SCCollectioning>)object;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

See the details of this methods in the corresponding sections of the Programming Guide.

SCIndexedCollection protocol

Protocol SCIndexedCollection declares methods, which must be implemented in the indexed collections. Indexed collections support the direct access to each collection object by using the specified index. With this protocol are compliance the following library classes:

Also to the protocol SCIndexedCollection are compliance the following categories of the standard classes:

Protocol requires the implementation of the following properties and methods for indexed access to collection objects:

@property (nonatomic, readonly, assign) id firstObject;
@property (nonatomic, readonly, assign) id lastObject;
- (id)objectAtIndex:(SCIndex)index;
- (id)objectAtIndexedSubscript:(SCIndex)index;

Also protocol declares the following required properties and methods for object search:

- (SCIndex)indexOfObject:(id<SCCollectioning>)object;
@property (nonatomic, readonly, assign) SCIndex indexOfLastObject;

Details of indexed collection methods provides in the Programming Guide corresponding sections.

SCMutableIndexedCollection protocol

Protocol SCMutableIndexedCollection declares methods, which can change the objects in the indexed collections. With this protocol are compliance the following library classes:

Also to the protocol are compliance the following standard classes categories:

Protocol SCMutableIndexedCollection declares the following required methods:

- (void)insertObject:(id<SCCollectioning>)object atIndex:(SCIndex)index;
- (void)removeObjectAtIndex:(SCIndex)index;
- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes;
- (void)replaceObjectAtIndex:(SCIndex)index withObject:(id<SCCollectioning>)object;
- (void)setObject:(id<SCCollectioning>)object atIndexedSubscript:(SCIndex)index;

For detailed information about this methods see the corresponding sections of the Programming Guide.

SCKeyedCollection protocol

Protocol SCKeyedCollection declares methods, which must be implemented in the keyed collections. Keyed collections support the direct access to each collection object by using the specified key. With this protocol are compliance the following library classes:

Also to the protocol SCKeyedCollection are compliance the following categories of the standard classes:

Protocol requires the implementation of the following properties and methods for keyed access to collection objects:

- (id)objectForKey:(NSString *)key;
- (id)objectForKeyedSubscript:(NSString *)key;
- (id)valueForKey:(NSString *)key;

Details of keyed collection methods provides in the Programming Guide corresponding sections.

SCMutableKeyedCollection protocol

Protocol SCMutableKeyedCollection declares methods, which can change the objects in the keyed collections. With this protocol are compliance the following library classes:

Also to the protocol are compliance the following standard classes categories:

Protocol SCMutableKeyedCollection declares the following required methods:

- (void)setObject:(id<SCCollectioning>)object forKey:(NSString *)key;
- (void)setObject:(id<SCCollectioning>)object forKeyedSubscript:(NSString *)key;
- (void)setValue:(id<SCCollectioning>)value forKey:(NSString *)key;
- (void)removeObjectForKey:(NSString *)key;

For detailed information about this methods see the corresponding sections of the Programming Guide.

Collection support types

For collections support file SCCollectionProtocols.h declares the following data types:

SCIndex - An item index data type
SCCollectionType - The enum type of collection types

Collection properties

Class SCCollection instances declares the following properties:

@property (nonatomic, readwrite, retain) NSString *name;
@property (nonatomic, readonly, assign) SCIndex count;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readwrite, assign) BOOL readOnly;
@property (nonatomic, readwrite, retain) id<SCCollectionDelegate> delegate;
@property (nonatomic, readonly, copy) NSString *typeName;

Coping collections

Coping methods remove the current collection content and replace it by the objects from the specified methods parameters. Class SCCollection declares the following coping methods:

- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

Comparing collections

Class SCCollection declares the following methods for comparing collection with other collection instances:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;
- (BOOL)isEqual:(id)object;

Enumerating collection objects

Class SCCollection declares the object enumerating properties and methods:

@property (nonatomic, readonly, assign) NSEnumerator *objectEnumerator;
@property (nonatomic, readonly, assign) NSEnumerator *reverseObjectEnumerator;
- (void)enumerateWithDelegate:(id<SCCollectionDelegate>)delegate;
- (void)enumerate;
- (void)reverseEnumerateWithDelegate:(id<SCCollectionDelegate>)delegate;
- (void)reverseEnumerate;

Also class SCCollection and its child classes since version 1.2.5 support an operator оператор for..in, which supports in Objective C sinve version 2.0:

SCArray *array = [SCArray arrayWithObjects:@100, @"200", @"300", @400, nil];
for ( id object in array) NSLog( @"%@", object);
2017-09-10 19:42:23.832149+0300 libtest[3335:100619] 100
2017-09-10 19:42:23.832178+0300 libtest[3335:100619] 200
2017-09-10 19:42:23.832203+0300 libtest[3335:100619] 300
2017-09-10 19:42:23.832249+0300 libtest[3335:100619] 400

Converting collections

Class SCCollection declares the following properties for converting collection instance from one collection type into the other collection type with objects retaining if converting type is allowed:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, assign) NSArray *foundationArray;
@property (nonatomic, readonly, assign) NSSet *foundationSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, assign) NSDictionary *foundationDictionary;

Adding objects

Class SCCollection declares the following methods for adding objects into the collection instance:

- (void)addObject:(id<SCCollectioning>)object;
- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;

If any of object adding methods calls for the read only collection, then the error SCL-20043 is generated.

Removing objects

Class SCCollection declares the following methods for removing objects from the collection instance:

- (void)removeAllObjects;
- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObject:(id<SCCollectioning>)object;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

If any of object removing methods calls for the read-only collection, then then the error SCL-20043 is generated.

Search collection items

Serach methods detects the presense in the collection the required objects. Class SCCollection declares the following search methods:

- (BOOL)containsObject:(id<SCCollectioning>)object;
- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Collection type detection

Class SCCollection declares the following properties for collection type determination:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Also class SCCollection declares the following class methods for collection type determination of the specified class instances:

+ (BOOL)isCollection:(id)object;
+ (BOOL)isLibraryCollection:(id)object;
+ (BOOL)isFoundationCollection:(id)object;
+ (BOOL)isArray:(id)object;
+ (BOOL)isLibraryArray:(id)object;
+ (BOOL)isFoundationArray:(id)object;
+ (BOOL)isSet:(id)object;
+ (BOOL)isLibrarySet:(id)object;
+ (BOOL)isFoundationSet:(id)object;
+ (BOOL)isOrderedSet:(id)object;
+ (BOOL)isLibraryOrderedSet:(id)object;
+ (BOOL)isFoundationOrderedSet:(id)object;
+ (BOOL)isDictionary:(id)object;
+ (BOOL)isLibraryDictionary:(id)object;
+ (BOOL)isFoundationDictionary:(id)object;
+ (BOOL)isStack:(id)object;
+ (BOOL)isQueue:(id)object;
+ (BOOL)isList:(id)object;
+ (BOOL)isSortable:(id)object;

Additionally, class SCCollection declares the class methods for determination collection type of the class by using the specified class name:

+ (BOOL)isCollectionClass:(NSString *)name;
+ (BOOL)isLibraryCollectionClass:(NSString *)name;
+ (BOOL)isFoundationCollectionClass:(NSString *)name;
+ (BOOL)isArrayClass:(NSString *)name;
+ (BOOL)isLibraryArrayClass:(NSString *)name;
+ (BOOL)isFoundationArrayClass:(NSString *)name;
+ (BOOL)isSetClass:(NSString *)name;
+ (BOOL)isLibrarySetClass:(NSString *)name;
+ (BOOL)isFoundationSetClass:(NSString *)name;
+ (BOOL)isOrderedSetClass:(NSString *)name;
+ (BOOL)isLibraryOrderedSetClass:(NSString *)name;
+ (BOOL)isFoundationOrderedSetClass:(NSString *)name;
+ (BOOL)isDictionaryClass:(NSString *)name;
+ (BOOL)isLibraryDictionaryClass:(NSString *)name;
+ (BOOL)isFoundationDictionaryClass:(NSString *)name;
+ (BOOL)isStackClass:(NSString *)name;
+ (BOOL)isQueueClass:(NSString *)name;
+ (BOOL)isListClass:(NSString *)name;
+ (BOOL)isSortableClass:(NSString *)name;

Arrays

Arrays is a collection of objects, each identified by the index. Therefore, an array is a collection with the random access to the objects. Also, array is a kind of sorted collection.

Class SCArray implements the arrays in the library. Class instances supports both read and update contained objects.

Creating arrays

Class SCArray implements the following methods for creating arrays using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)arrayWithCoder:(NSCoder *)coder;
+ (instancetype)arrayWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)arrayWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)arrayWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)arrayWithStream:(SCStream *)stream;
+ (instancetype)arrayWithFileStream:(NSString *)path;
+ (instancetype)arrayWithData:(NSData *)data;
+ (instancetype)arrayWithContentsOfFile:(NSString *)path;
+ (instancetype)arrayWithContentsOfURL:(NSURL *)url;
+ (instancetype)arrayWithContentsOfURLString:(NSString *)urlString;

Class SCArrays declares the following methods for creating arrays:

+ (instancetype)arrayWithName:(NSString *)name;
+ (instancetype)arrayWithObject:(id<SCCollectioning>)object;
+ (instancetype)arrayWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)arrayWithCollection:(id<SCCollection>)collection;
+ (instancetype)arrayWithArray:(SCArray *)array;
+ (instancetype)array;

Initializing arrays

Class SCArray implements the following class instances initialization methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)init;

Coping arrays

Class SCArray declares the following array coping methods:

- (void)setArray:(SCArray *)array;

Comparing arrays

Class SCArray extends the parent class SCCollection by implements the following additional methods for comparing class instances:

- (BOOL)isEqualToArray:(SCArray *)array;
SCArray *array = [SCArray array];
[array addObject:@"Line 00"];
[array addObject:@"Line 01"];
[array addObject:@"Line 02"];
SCArray *source = [SCArray arrayWithName:@"SourceArray"];
[source addObject:@"Line 00"];
[source addObject:@"Line 01"];
[source addObject:@"Line 02"];
SCArray *sample = [SCArray array];
[sample addObject:@"Line 00"];
[sample addObject:@"Line 10"];
[sample addObject:@"Line 20"];
NSLog( @"[array isEqualToArray:source] = %d", [array isEqualToArray:source]);
NSLog( @"[array isEqualToArray:sample] = %d", [array isEqualToArray:sample]);
2016-07-25 01:36:51.081 libtest[11081:1745880] [array isEqualToArray:source] = 1
2016-07-25 01:36:51.081 libtest[11081:1745880] [array isEqualToArray:sample] = 0

Deriving new arrays

You can use the following methods of the class SCArray for deriving new array by using the existing content of the receiving arrays:

- (SCArray *)arrayByAddingObject:(id<SCCollectioning>)object;
- (SCArray *)arrayByAddingObjects:(id<SCCollectioning>)object, ...;
- (SCArray *)arrayByAddingCollection:(id<SCCollection>)collection;
- (SCArray *)arrayByAddingObjectsFromArray:(SCArray *)array;
- (SCArray *)arrayByAddingArray:(SCArray *)array;
- (SCArray *)subarrayWithRange:(NSRange)range;

Sorting arrays

Arrays, like any indexed collection, can provide various modes of objects sorting. Class SCArray implements the number of methods that allow performs sorting operations. For performs the sorting operations class SCArray uses the sorters, which are instances of classes, that comforms to the protocol SCSorter. You can direct set the sorter class instance or use the default array sorter. See details in the Programming Guide section Sorters.

During the sorting operation sorter comparing array object by using the protocol SCCollectioning method compareWithObject:.

Class SCArray declares the following properties methods of sorting its contents:

- (void)sortAscendingWithSorter:(id<SCSorter>)sorter;
- (void)sortDescendingWithSorter:(id<SCSorter>)sorter;
- (void)sortWithSorter:(id<SCSorter>)sorter;
- (void)sortAscending;
- (void)sortDescending;
- (void)sort;
- (SCArray *)ascendingSortedArrayWithSorter:(id<SCSorter>)sorter;
- (SCArray *)descendingSortedArrayWithSorter:(id<SCSorter>)sorter;
- (SCArray *)sortedArrayWithSorter:(id<SCSorter>)sorter;
@property (nonatomic, readonly, assign) SCArray *ascendingSortedArray;
@property (nonatomic, readonly, assign) SCArray *descendingSortedArray;
@property (nonatomic, readonly, assign) SCArray *sortedArray;
SCArray *array = [SCArray array];
[array addObject:@"String 04"];
[array addObject:@"String 01"];
[array addObject:@"String 00"];
[array addObject:@"String 02"];
[array addObject:@"String 03"];
NSLog( @"================ SOURCE ARRAY =================");
NSLog( @"%@", array);
[array sortAscending];
NSLog( @"=========== ASCENDING SORTED ARRAY ============");
NSLog( @"%@", array);
[array sortDescending];
NSLog( @"=========== DESCENDING SORTED ARRAY ===========");
NSLog( @"%@", array);
2016-07-22 10:25:14.707 libtest[7423:1366810] ================ SOURCE ARRAY =================
2016-07-22 10:25:14.707 libtest[7423:1366810] Array count=5: (
"String 04",
"String 01",
"String 00",
"String 02",
"String 03"
)
2016-07-22 10:25:14.708 libtest[7423:1366810] =========== ASCENDING SORTED ARRAY ============
2016-07-22 10:25:14.708 libtest[7423:1366810] Array count=5: (
"String 00",
"String 01",
"String 02",
"String 03",
"String 04"
)
2016-07-22 10:25:14.708 libtest[7423:1366810] =========== DESCENDING SORTED ARRAY ===========
2016-07-22 10:25:14.708 libtest[7423:1366810] Array count=5: (
"String 04",
"String 03",
"String 02",
"String 01",
"String 00"
)

Also the class SCArray declares the class methods for creating arrays using the sorted contents of the existing collection of any supported type:

+ (instancetype)arrayWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithAscendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)arrayWithDescendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)arrayWithSortedCollection:(id<SCCollection>)collection;

Additionally class SCArray implements the methods for initializing the arrays using the sorted contents of the existing collections of any supported type:

- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection;

In addition to copying methods class SCArray provides the following methods of copying sorted contents of the existing collections of any supported type:

- (void)setAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setAscendingSortedCollection:(id<SCCollection>)collection;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection;
- (void)setSortedCollection:(id<SCCollection>)collection;

Adding objects to array

Class SCArray extends the parent class SCCollection with the following methods for adding methods into the array:

- (void)insertObject:(id<SCCollectioning>)object atIndex:(SCIndex)index;
- (void)insertAtIndex:(SCIndex)index objects:(id<SCCollectioning>)object, ...;
- (void)insertCollection:(id<SCCollection>)collection atIndex:(SCIndex)index;
- (void)insertAtIndexes:(NSIndexSet *)indexes objects:(id<SCCollectioning>)object, ...;
- (void)insertCollection:(id<SCCollection>)collection atIndexes:(NSIndexSet *)indexes;
- (void)setObject:(id<SCCollectioning>)object atIndex:(SCIndex)index;
- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;

Removing objects from array

In addition to the parent class SCCollection objects removing methods class SCArray implements the own removing methods:

- (void)removeFirstObject;
- (void)removeLastObject;
- (void)removeObjectAtIndex:(SCIndex)index;
- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes;
- (void)removeObjectsInRange:(NSRange)range;

Replacing array objects

Class SCArrays declares the following methods for object replacing:

- (void)replaceObjectAtIndex:(SCIndex)index withObject:(id<SCCollectioning>)object;
- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withObjects:(id<SCCollectioning>)object, ...;
- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withCollection:(id<SCCollection>)collection;
- (void)replaceObjectsInRange:(NSRange)range withObjects:(id<SCCollectioning>)object, ...;
- (void)replaceObjectsInRange:(NSRange)range withCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object atIndexedSubscript:(SCIndex)index;

Coping and moving array objects

Class SCArray implements some methods for coping and moving objects in the array.

Method exchangeObjectAtIndex:withObjectAtIndex: exchanges the objects in the array at given indices:

- (void)exchangeObjectAtIndex:(SCIndex)index withObjectAtIndex:(SCIndex)destination;
SCArray *array = [SCArray array];
[array addObject:@"Object 00"];
[array addObject:@"Object 01"];
[array addObject:@"Object 02"];
[array addObject:@"Object 03"];
NSLog( @"%@", array);
[array exchangeObjectAtIndex:0 withObjectAtIndex:3];
NSLog( @"%@", array);
2016-07-22 15:38:02.392 libtest[9467:1548785] Array count=4: (
"Object 00",
"Object 01",
"Object 02",
"Object 03"
)
2016-07-22 15:38:02.392 libtest[9467:1548785] Array count=4: (
"Object 03",
"Object 01",
"Object 02",
"Object 00"
)

Class SCArray implements the following methods for duplicating objects within the array:

- (void)duplicateObjectAtIndex:(SCIndex)index;
- (void)duplicateObjectsInRange:(NSRange)range;
- (void)duplicateAllObjects;
- (void)duplicate;

This methods required from the objects the compliance to the protocol SCCollection and implementation of the method copyObject.

Class SCArray declares the following methods for copying objects within array (required support of the method copyObject for array objects):

- (void)copyObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)copyObjectsInRange:(NSRange)range toIndex:(SCIndex)destination;

Class SCArray implements the following methods for moving objects within array:

- (void)moveObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)moveObjectsInRange:(NSRange)range toIndex:(SCIndex)destination;

Additional class SCArray declares the methods for reversing array contents:

- (void)reverse;
- (SCArray *)reversedArray;
SCArray *array = [SCArray array];
[array addObject:@"Object 00"];
[array addObject:@"Object 01"];
[array addObject:@"Object 02"];
[array addObject:@"Object 03"];
NSLog( @"%@", array);
[array reverse];
NSLog( @"%@", array);
2016-07-22 17:22:13.296 libtest[10119:1622519] Array count=4: (
"Object 00",
"Object 01",
"Object 02",
"Object 03"
)
2016-07-22 17:22:13.296 libtest[10119:1622519] Array count=4: (
"Object 03",
"Object 02",
"Object 01",
"Object 00"
)

Array objects access

Class SCArray declares the following properties and methods for the access to the array objects:

@property (nonatomic, readonly, assign) id firstObject;
@property (nonatomic, readonly, assign) id lastObject;
- (id)objectAtIndex:(SCIndex)index;
- (SCArray *)objectsAtIndexes:(NSIndexSet *)indexes;
- (SCArray *)objectsInRange:(NSRange)range;
- (id)objectAtIndexedSubscript:(SCIndex)index;

Search array objects

For finding objects in the arrays class SCArray implements the following methods and properties:

- (SCIndex)indexOfObject:(id<SCCollectioning>)object;
- (SCIndex)indexOfObject:(id<SCCollectioning>)object inRange:(NSRange)range;
@property (nonatomic, readonly, assign) SCIndex indexOfLastObject;

Sets

Set (unordered set) is a type of collection, which can store certain objects, without any particular order, and no repeated values. Sets does not support direct access to objects.

For supporting sets the library implements the class SCSet:

Creating sets

For creating class instances using the data from the serialized files, data dictionaries, streams and data objects class SCSet implements the following class methods:

+ (instancetype)setWithCoder:(NSCoder *)coder;
+ (instancetype)setWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)setWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)setWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)setWithStream:(SCStream *)stream;
+ (instancetype)setWithFileStream:(NSString *)path;
+ (instancetype)setWithData:(NSData *)data;
+ (instancetype)setWithContentsOfFile:(NSString *)path;
+ (instancetype)setWithContentsOfURL:(NSURL *)url;
+ (instancetype)setWithContentsOfURLString:(NSString *)urlString;

Class SCSet declares the following the class methods for creating the class instances:

+ (instancetype)setWithName:(NSString *)name;
+ (instancetype)setWithObject:(id<SCCollectioning>)object;
+ (instancetype)setWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)setWithCollection:(id<SCCollection>)collection;
+ (instancetype)setWithSet:(SCSet *)set;
+ (instancetype)setWithArray:(SCArray *)array;
+ (instancetype)set;

Initializing sets

Class SCSet implements the following initializing methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithSet:(SCSet *)set;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)init;

Coping sets

Class SCSet declares the following coping methods:

- (void)setSet:(SCSet *)set;
- (void)setArray:(SCArray *)array;

Comparing sets

Class SCSet implements the following comparing methods:

- (BOOL)isSubsetOfSet:(id<SCCollection>)set;
- (BOOL)intersectsSet:(id<SCCollection>)set;
- (BOOL)isEqualToSet:(SCSet *)set;
- (BOOL)isEqualToArray:(SCArray *)array;

Deriving New Sets

Class SCSet implements the following methods for deriving a new sets using the existing sets:

- (SCSet *)setByAddingObject:(id<SCCollectioning>)object;
- (SCSet *)setByAddingObjects:(id<SCCollectioning>)object, ... NS_REQUIRES_NIL_TERMINATION;
- (SCSet *)setByAddingObjectsFromArray:(SCArray *)array;
- (SCSet *)setByAddingArray:(SCArray *)array;
- (SCSet *)setByAddingObjectsFromSet:(SCSet *)set;
- (SCSet *)setByAddingSet:(SCSet *)set;
- (SCSet *)setByAddingCollection:(id<SCCollection>)collection;

Adding Objects

Except the methods inherited from the class SCCollection the class SCSet implements own methods of adding objects:

- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;
- (void)addObjectsFromSet:(SCSet *)set;
- (void)addSet:(SCSet *)set;

Set objects access

For accessing the set objects class SCSet implements the following properties and methods:

@property (nonatomic, readonly, assign) SCArray *allObjects;
@property (nonatomic, readonly, assign) id anyObject;
- (id)member:(id<SCCollectioning>)object;

Combining and recombining sets

Combining and recombining operations are supported by the following methods of the class SCSet:

- (void)unionSet:(id<SCCollection>)set;
- (void)minusSet:(id<SCCollection>)set;
- (void)intersectSet:(id<SCCollection>)set;

Ordered sets

Ordered sets on the basis of class SCOrderedSet represent a set of objects that differ from unordered sets SCSet both support a specific sequence elements (thus the name), and index access to the objects of the set.

Ordered sets are similar as the array (the order of items, indexed access), and with unordered sets - each object is present in the ordered set only once.

Creating ordered sets

For creating ordered sets from the serialized files, data dictionaries, streams and data objects class SCOrderedSet declares the following class methods:

+ (instancetype)orderedSetWithCoder:(NSCoder *)coder;
+ (instancetype)orderedSetWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)orderedSetWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)orderedSetWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)orderedSetWithStream:(SCStream *)stream;
+ (instancetype)orderedSetWithFileStream:(NSString *)path;
+ (instancetype)orderedSetWithData:(NSData *)data;
+ (instancetype)orderedSetWithContentsOfFile:(NSString *)path;
+ (instancetype)orderedSetWithContentsOfURL:(NSURL *)url;
+ (instancetype)orderedSetWithContentsOfURLString:(NSString *)urlString;

Class SCOrderedSet implements the following class methods for creating ordered sets:

+ (instancetype)orderedSetWithName:(NSString *)name;
+ (instancetype)orderedSetWithObject:(id<SCCollectioning>)object;
+ (instancetype)orderedSetWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)orderedSetWithCollection:(id<SCCollection>)collection;
+ (instancetype)orderedSetWithArray:(SCArray *)array;
+ (instancetype)orderedSetWithSet:(SCSet *)set;
+ (instancetype)orderedSetWithOrderedSet:(SCOrderedSet *)orderedSet;
+ (instancetype)orderedSet;

Initializing ordered sets

Class SCOrderedSet declares the following initializing methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)initWithSet:(SCSet *)set;
- (instancetype)initWithOrderedSet:(SCOrderedSet *)orderedSet;
- (instancetype)init;

Coping ordered sets

Class SCOrderedSet declares the following methods for ordered set coping:

- (void)setSet:(SCSet *)set;
- (void)setOrderedSet:(SCOrderedSet *)orderedSet;
- (void)setArray:(SCArray *)array;

Comparing ordered sets

For the comparing operations class SCOrderedSet implements the following methods:

- (BOOL)isSubsetOfOrderedSet:(id<SCCollection>)orderedSet;
- (BOOL)isSubsetOfSet:(id<SCCollection>)set;
- (BOOL)intersectsOrderedSet:(id<SCCollection>)orderedSet;
- (BOOL)intersectsSet:(id<SCCollection>)set;
- (BOOL)isEqualToOrderedSet:(SCOrderedSet *)orderedSet;
- (BOOL)isEqualToSet:(SCSet *)set;
- (BOOL)isEqualToArray:(SCArray *)array;

Deriving New Ordered Sets

Class SCOrderedSet implements the following methods for deriving new ordered set by using existing ordered sets:

- (SCOrderedSet *)orderedSetByAddingObject:(id<SCCollectioning>)object;
- (SCOrderedSet *)orderedSetByAddingObjects:(id<SCCollectioning>)object, ...;
- (SCOrderedSet *)orderedSetByAddingCollection:(id<SCCollection>)collection;
- (SCOrderedSet *)orderedSetByAddingObjectsFromArray:(SCArray *)array;
- (SCOrderedSet *)orderedSetByAddingArray:(SCArray *)array;
- (SCOrderedSet *)orderedSetByAddingObjectsFromSet:(SCSet *)set;
- (SCOrderedSet *)orderedSetByAddingSet:(SCSet *)set;
- (SCOrderedSet *)orderedSetByAddingObjectsFromOrderedSet:(SCOrderedSet *)orderedSet;
- (SCOrderedSet *)orderedSetByAddingOrderedSet:(SCOrderedSet *)orderedSet;

Sorting ordered sets

Becase ordered sets support the indexed access to the objects, we also support and the sorting operations. As an arrays, ordered sets use the sorters - instances of the classes, which compliance to the SCSorter protocol. Class SCOrderedSet supports both methods with the specified sorters and with default library sorters. Details about the sorters you can obtain from the Programming Guide section Sorters.

During the sorting operation sorter comparing array object by using the protocol SCCollectioning method compareWithObject:.

Class SCOrderedSet implements the following methods and properties of sorting its contents:

- (void)sortAscendingWithSorter:(id<SCSorter>)sorter;
- (void)sortDescendingWithSorter:(id<SCSorter>)sorter;
- (void)sortWithSorter:(id<SCSorter>)sorter;
- (void)sortAscending;
- (void)sortDescending;
- (void)sort;
- (SCOrderedSet *)ascendingSortedOrderedSetWithSorter:(id<SCSorter>)sorter;
- (SCOrderedSet *)descendingSortedOrderedSetWithSorter:(id<SCSorter>)sorter;
- (SCOrderedSet *)sortedOrderedSetWithSorter:(id<SCSorter>)sorter;
@property (nonatomic, readonly, assign) SCOrderedSet *ascendingSortedOrderedSet;
@property (nonatomic, readonly, assign) SCOrderedSet *descendingSortedOrderedSet;
@property (nonatomic, readonly, assign) SCOrderedSet *sortedOrderedSet;
SCOrderedSet *orderedSet = [SCOrderedSet orderedSet];
[orderedSet addObject:@"04"];
[orderedSet addObject:@"01"];
[orderedSet addObject:@"00"];
[orderedSet addObject:@"02"];
[orderedSet addObject:@"03"];
NSLog( @"================ SOURCE ORDERED SET =================");
NSLog( @"%@", orderedSet);
[orderedSet sortAscending];
NSLog( @"=========== ASCENDING SORTED ORDERED SET ============");
NSLog( @"%@", orderedSet);
[orderedSet sortDescending];
NSLog( @"=========== DESCENDING SORTED ORDERED SET ===========");
NSLog( @"%@", orderedSet);
2016-07-26 16:53:02.377 libtest[5100:665305] ================ SOURCE ORDERED SET =================
2016-07-26 16:53:02.377 libtest[5100:665305] Ordered set count=5: {(
"04",
"01",
"00",
"02",
"03"
)}
2016-07-26 16:53:02.378 libtest[5100:665305] =========== ASCENDING SORTED ORDERED SET ============
2016-07-26 16:53:02.378 libtest[5100:665305] Ordered set count=5: {(
"00",
"01",
"02",
"03",
"04"
)}
2016-07-26 16:53:02.378 libtest[5100:665305] =========== DESCENDING SORTED ORDERED SET ===========
2016-07-26 16:53:02.378 libtest[5100:665305] Ordered set count=5: {(
"04",
"03",
"02",
"01",
"00"
)}

Also the class SCOrderedSet declares the class methods for creating ordered sets using the sorted contents of the existing collection of any supported type:

+ (instancetype)orderedSetWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithAscendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)orderedSetWithDescendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)orderedSetWithSortedCollection:(id<SCCollection>)collection;

Additionally class SCOrderedSet implements the methods for initializing the ordered sets using the sorted contents of the existing collections of any supported type:

- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection;

In addition to copying methods class SCOrderedSet provides the following methods of copying sorted contents of the existing collections of any supported type:

- (void)setAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setAscendingSortedCollection:(id<SCCollection>)collection;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection;
- (void)setSortedCollection:(id<SCCollection>)collection;

Adding objects to ordered set

Class SCOrderSet extends the class SCCollection by implementing the advanced methods for adding objects into the ordered set. Please note that each object can be added to an ordered set only once - second attempt to add an object to be ignored.

- (void)insertObject:(id<SCCollectioning>)object atIndex:(SCIndex)index;
- (void)insertAtIndex:(SCIndex)index objects:(id<SCCollectioning>)object, ...;
- (void)insertCollection:(id<SCCollection>)collection atIndex:(SCIndex)index;
- (void)insertAtIndexes:(NSIndexSet *)indexes objects:(id<SCCollectioning>)object, ...;
- (void)insertCollection:(id<SCCollection>)collection atIndexes:(NSIndexSet *)indexes;
- (void)setObject:(id<SCCollectioning>)object atIndex:(SCIndex)index;
- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;
- (void)addObjectsFromSet:(SCSet *)set;
- (void)addSet:(SCSet *)set;
- (void)addObjectsFromOrderedSet:(SCOrderedSet *)orderedSet;
- (void)addSet:(SCOrderedSet *)orderedSet;

Removing objects from ordered set

Class SCOrderSet expands the parent class SCCollection by adding the following methods for removing objects from the ordered set:

- (void)removeFirstObject;
- (void)removeLastObject;
- (void)removeObjectAtIndex:(SCIndex)index;
- (void)removeObjectsAtIndexes:(NSIndexSet *)indexes;
- (void)removeObjectsInRange:(NSRange)range;

Replacing ordered set objects

Class SCOrderedSet declares the following methods for replacing objects in the ordered set:

- (void)replaceObjectAtIndex:(SCIndex)index withObject:(id<SCCollectioning>)object;
- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withObjects:(id<SCCollectioning>)object, ...;
- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withCollection:(id<SCCollection>)collection;
- (void)replaceObjectsInRange:(NSRange)range withObjects:(id<SCCollectioning>)object, ...;
- (void)replaceObjectsInRange:(NSRange)range withCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object atIndexedSubscript:(SCIndex)index;

Moving ordered set objects

Class SCOrderedSet implemens the following methods for moving objects within ordered set:

- (void)exchangeObjectAtIndex:(SCIndex)index withObjectAtIndex:(SCIndex)destination;
- (void)moveObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)reverse;

Ordered set objects access

For accessing to the ordered set objects the class SCOrderedSet implements the following access properties and methods:

@property (nonatomic, readonly, assign) SCOrderedSet *reversedOrderedSet;
@property (nonatomic, readonly, assign) SCArray *allObjects;
@property (nonatomic, readonly, assign) id firstObject;
@property (nonatomic, readonly, assign) id lastObject;
- (id)objectAtIndex:(SCIndex)index;
- (SCArray *)objectsAtIndexes:(NSIndexSet *)indexes;
- (id)objectAtIndexedSubscript:(SCIndex)index;

Search ordered set objects

For search objects in the ordered set class SCOrderedSet declares the following methods:

- (SCIndex)indexOfObject:(id<SCCollectioning>)object;
@property (nonatomic, readonly, assign) SCIndex indexOfLastObject;

Combining and recombining ordered sets

Class SCOrderedSet declares the following methods for combining and recombining ordered sets:

- (void)unionOrderedSet:(id<SCCollection>)orderedSet;
- (void)unionSet:(id<SCCollection>)set;
- (void)minusOrderedSet:(id<SCCollection>)set;
- (void)minusSet:(id<SCCollection>)set;
- (void)intersectOrderedSet:(id<SCCollection>)orderedSet;
- (void)intersectSet:(id<SCCollection>)set;

Dictionaries

Class SCDictionary defines the interface to the data storage of the records of type "key - value", accessed by the keys, which is a text strings. Values of dictionary is a instances of classes, which comply to the SCCollectioning protocol.

Creating dictionaries

For creating dictionaries using serialized files, data dictionaries, streams and data objects class SCDictionary declares the following class methods:

+ (instancetype)dictionaryWithCoder:(NSCoder *)coder;
+ (instancetype)dictionaryWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)dictionaryWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)dictionaryWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)dictionaryWithStream:(SCStream *)stream;
+ (instancetype)dictionaryWithFileStream:(NSString *)path;
+ (instancetype)dictionaryWithData:(NSData *)data;
+ (instancetype)dictionaryWithContentsOfFile:(NSString *)path;
+ (instancetype)dictionaryWithContentsOfURL:(NSURL *)url;
+ (instancetype)dictionaryWithContentsOfURLString:(NSString *)urlString;

Class SCDictionary implements the following class methods for class instances creating:

+ (instancetype)dictionaryWithName:(NSString *)name;
+ (instancetype)dictionaryWithObject:(id<SCCollectioning>)object forKey:(NSString *)key;
+ (instancetype)dictionaryWithObject:(id<SCCollectioning>)object;
+ (instancetype)dictionaryWithObjects:(id<SCCollection>)objects forKeys:(id<SCCollection>)keys;
+ (instancetype)dictionaryWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)dictionaryWithObjectsAndKeys:(id<SCCollectioning>)object, ...;
+ (instancetype)dictionaryWithCollection:(id<SCCollection>)collection;
+ (instancetype)dictionaryWithDictionary:(SCDictionary *)dictionary;
+ (instancetype)dictionary;

Initializing dictionaries

Class SCDictionary declares the following initialization methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object forKey:(NSString *)key;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollection>)objects forKeys:(id<SCCollection>)keys;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithObjectsAndKeys:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(<SCCollection>id)collection;
- (instancetype)initWithDictionary:(SCDictionary *)dictionary;
- (instancetype)init;

Coping dictionaries

Class SCDictionary declares the following methods for dictionaries coping:

- (void)setDictionary:(SCDictionary *)dictionary;

Comparing dictionaries

Class SCDictionary implements the following comparing methods:

- (BOOL)isEqualToDictionary:(SCDictionary *)dictionary;

Deriving New Dictionaries

Class SCDictionary implements the following methods for deriving new dictionaries by using entries from existing dictionaries:

- (SCDictionary *)dictionaryByAddingObject:(id<SCCollectioning>)object forKey:(NSString *)key;
- (SCDictionary *)dictionaryByAddingObject:(id<SCCollectioning>)object;
- (SCDictionary *)dictionaryByAddingObjects:(id<SCCollection>)objects forKeys:(id<SCCollection>)keys;
- (SCDictionary *)dictionaryByAddingObjects:(id<SCCollectioning>)object, ...;
- (SCDictionary *)dictionaryByAddingObjectsAndKeys:(id<SCCollectioning>)object, ...;
- (SCDictionary *)dictionaryByAddingCollection:(id<SCCollection>)collection;
- (SCDictionary *)dictionaryByAddingObjectsFromArray:(SCArray *)array;
- (SCDictionary *)dictionaryByAddingArray:(SCArray *)array;
- (SCDictionary *)dictionaryByAddingEntriesFromDictionary:(SCDictionary *)dictionary;
- (SCDictionary *)dictionaryByAddingDictionary:(SCDictionary *)dictionary;

Adding and changing dictionary objects

For adding and changing objects and values class SCDictionary implements the following methods:

- (void)setObject:(id<SCCollectioning>)object forKey:(NSString *)key;
- (void)setObject:(id<SCCollectioning>)object forKeyedSubscript:(NSString *)key;
- (void)setObjects:(id<SCCollection>)objects forKeys:(id<SCCollection>)keys;
- (void)setObjectsAndKeys:(id<SCCollectioning>)object, ...;
- (void)setValue:(id<SCCollectioning>)value forKey:(NSString *)key;
- (void)setValues:(id<SCCollection>)values forKeys:(id<SCCollection>)keys;
- (void)setValuesAndKeys:(id<SCCollectioning>)object, ...;
- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;
- (void)addEntriesFromDictionary:(SCDictionary *)dictionary;
- (void)addDictionary:(SCDictionary *)dictionary;
- (void)addObjects:(id<SCCollection>)objects andKeys:(id<SCCollection>)keys;
- (void)addObjectsAndKeys:(id<SCCollectioning>)object, ...;

Removing objects from dictionary

Class SCDictionary implements the following methods for removing objects and values:

- (void)removeObjectForKey:(NSString *)key;
- (void)removeObjectsForKeys:(id)keys;

Dictionary keys and values access

The following class SCDictionary properties and methods provide group access to keys and values within the dictionary:

@property (nonatomic, readonly, assign) SCArray *allKeys;
@property (nonatomic, readonly, assign) SCArray *allValues;
- (SCArray *)allKeysForObject:(id<SCCollectioning>)object;

For accessing to objects and values assoicated with a keys the class declares the following methods:

- (id)objectForKey:(NSString *)key;
- (id)objectForKeyedSubscript:(NSString *)key;
- (id)valueForKey:(NSString *)key;

Search dictionary objects and keys

Class SCDictionary implements the following object searching methods:

- (BOOL)containsObjectForKey:(NSString *)key;
- (BOOL)containsStringForKey:(NSString *)key;
- (BOOL)containsNumberForKey:(NSString *)key;
- (BOOL)containsAnyObjectForKeys:(id<SCCollection>)keys;
- (BOOL)containsAllObjectsForKeys:(id<SCCollection>)keys;

For finding keys within the dictionary, class SCDictionary declares following methods:

- (BOOL)containsKey:(NSString *)key;
- (BOOL)containsKeys:(NSString *)key, ...;
- (BOOL)containsKeysFromCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyKey:(NSString *)key, ...;
- (BOOL)containsAnyKeyFromCollection:(id<SCCollection>)collection;

Enumerating dictionary objects

Property keyEnumerator returns an enumerator object that lets you access each key in the dictionary:

@property (nonatomic, readonly, assign) NSEnumerator *keyEnumerator;
SCDictionary *dictionary = [SCDictionary dictionary];
[dictionary setObject:@"MacOS" forKey:@"System"];
[dictionary setObject:@"10.11.6" forKey:@"Version"];
[dictionary setBool:NO forKey:@"Debug"];
NSEnumerator *keys = [dictionary keyEnumerator];
NSString *key;
while ( ( key = keys.nextObject)) {
id object = [dictionary objectForKey:key];
NSLog( @"%@: %@", key, object);
}
2016-08-04 14:45:46.853 libtest[20808:3795367] Version: 10.11.6
2016-08-04 14:45:46.853 libtest[20808:3795367] System: MacOS
2016-08-04 14:45:46.853 libtest[20808:3795367] Debug: 0

Stacks

Stack is a collection of objects with two principal operations: push, which adds an object to the stack, and pop, which removes the most recently added object that was not yet removed. The order in which objects come off a stack gives rise to its alternative name, LIFO (for last in, first out). Additionally, a get (peek) operation may give access to the top object without modifying the stack.

Creating stacks

Class SCStack declares the following class methods for creating stack by using the data from the serialized files, data dictionaries, streams, and data objects:

+ (instancetype)stackWithCoder:(NSCoder *)coder;
+ (instancetype)stackWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)stackWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)stackWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)stackWithStream:(SCStream *)stream;
+ (instancetype)stackWithFileStream:(NSString *)path;
+ (instancetype)stackWithData:(NSData *)data;
+ (instancetype)stackWithContentsOfFile:(NSString *)path;
+ (instancetype)stackWithContentsOfURL:(NSURL *)url;
+ (instancetype)stackWithContentsOfURLString:(NSString *)urlString;

For creating class instancess class SCStack implements the following class methods:

+ (instancetype)stackWithName:(NSString *)name;
+ (instancetype)stackWithObject:(id<SCCollectioning>)object;
+ (instancetype)stackWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)stackWithCollection:(id<SCCollection>)collection;
+ (instancetype)stackWithArray:(SCArray *)array;
+ (instancetype)stackWithStack:(SCStack *)stack;
+ (instancetype)stack;

Initializing stacks

Class SCStack implements the following initialization methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)initWithStack:(SCStack *)stack;
- (instancetype)init;

Coping stacks

Class SCStack declares the following methods for stacks coping:

- (void)setStack:(SCStack *)stack;

Comparing stacks

Class SCStack implements the following comparing methods:

- (BOOL)isEqualToStack:(SCStack *)stack;

Deriving new stacks

Class SCStack declares the following methods for deriving new stacks:

- (SCStack *)stackByPushingObject:(id<SCCollectioning>)object;
- (SCStack *)stackByPushingObjects:(id<SCCollectioning>)object, ...;
- (SCStack *)stackByPushingCollection:(id<SCCollection>)collection;
- (SCStack *)stackByPushingObjectsFromArray:(SCArray *)array;
- (SCStack *)stackByPushingArray:(SCArray *)array;
- (SCStack *)stackByPushingObjectsFromStack:(SCStack *)stack;
- (SCStack *)stackByPushingStack:(SCStack *)stack;

Adding objects to stack

Class SCStack declares the following methods for adding object into the stack:

- (void)pushObject:(id<SCCollectioning>)object;
- (void)pushObjects:(id<SCCollectioning>)object, ...;
- (void)pushCollection:(id<SCCollection>)collection;
- (void)pushObjectsFromArray:(SCArray *)array;
- (void)pushArray:(SCArray *)array;
- (void)pushObjectsFromStack:(SCStack *)stack;
- (void)pushStack:(SCStack *)stack;

Poping objects from stack

Class SCStack implements the following methods for poping objects from the stack:

- (void)pop;
- (id)popObject;

Removing objects from stack

Additionally to the method pop class SCStackimplements the method removeTopObject, which is a synomym of method pop. This method is designed for logical compatibility with the other collection classes and categories.

- (void)removeTopObject;

Coping stack objects

Method duplicateTopObject duplicates the object from the top of the receiving stack:

- (void)duplicateTopObject;
SCStack *stack = [SCStack stackWithObjects:@"Object 00", @"Object 01", nil];
NSLog( @"%@", stack);
[stack duplicateTopObject];
NSLog( @"%@", stack);
2016-08-08 16:13:06.619 libtest[47645:4720857] Stack count=2: (
"Object 01",
"Object 00"
)
2016-08-08 16:13:06.619 libtest[47645:4720857] Stack count=3: (
"Object 01",
"Object 01",
"Object 00"
)

Stack objects access

Stacks allow direct access only to the last added object (top object). Class SCStack implements the following properties for direct access to stack top object:

@property (nonatomic, readonly, assign) id topObject;

Queues

Queue is a collection in which the objects in collection are kept in order and the principal (or only) operations on the collection are the addition of objects to the rear terminal position, known as enqueue, and removal of objects from the front terminal position, known as desqueue.

This makes the queue a First-In-First-Out (FIFO) collection. In a queue, the first object added to the queue will be the first one to be removed. This is equivalnet to the requirement that once a new object is added, all objects that were added before have to be removed before the new object can be removed.

Often a peek, front or get operation is also enetered, returning the value of the front object without dequeuing it. A queue is an example of a abstractly a sequantial collection.

Library supports queue by the class SCQueue, which is a child of the class SCCollection. For adding objects to the queue class instances using the methods from the parent class SCCollection. This inherited methods are described in the Programming Guide section Adding objects.//###

Creating queues

For creating queues by using the data from the serialzied files, data dictionaries, streams and data objects class SCQueue declares the following class methods:

+ (instancetype)queueWithCoder:(NSCoder *)coder;
+ (instancetype)queueWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)queueWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)queueWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)queueWithStream:(SCStream *)stream;
+ (instancetype)queueWithFileStream:(NSString *)path;
+ (instancetype)queueWithData:(NSData *)data;
+ (instancetype)queueWithContentsOfFile:(NSString *)path;
+ (instancetype)queueWithContentsOfURL:(NSURL *)url;
+ (instancetype)queueWithContentsOfURLString:(NSString *)urlString;

Class SCQueue implements the following methods for creating class instances:

+ (instancetype)queueWithName:(NSString *)name;
+ (instancetype)queueWithObject:(id<SCCollectioning>)object;
+ (instancetype)queueWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)queueWithCollection:(id<SCCollection>)collection;
+ (instancetype)queueWithArray:(SCArray *)array;
+ (instancetype)queueWithQueue:(SCQueue *)queue;
+ (instancetype)queue;

Initializing queues

Class SCQueue declares the following initialization methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)initWithQueue:(SCQueue *)queue;
- (instancetype)init;

Coping queues

Class SCQueue declares the following methods for queues coping:

- (void)setQueue:(SCQueue *)queue;

Comparing queues

Class SCQueue implements the following comparing methods:

- (BOOL)isEqualToQueue:(SCQueue *)queue;

Deriving New Queues

Class SCQueue implements the following methods for deriving new queues by using existing queues:

- (SCQueue *)queueByAddingObject:(id<SCCollectioning>)object;
- (SCQueue *)queueByAddingObjects:(id<SCCollectioning>)object, ...;
- (SCQueue *)queueByAddingCollection:(id<SCCollection>)collection;
- (SCQueue *)queueByAddingObjectsFromArray:(SCArray *)array;
- (SCQueue *)queueByAddingArray:(SCArray *)array;
- (SCQueue *)queueByAddingObjectsFromQueue:(SCQueue *)queue;
- (SCQueue *)queueByAddingQueue:(SCQueue *)queue;

Adding objects

Class SCQueue implements the following methods for adding objects:

- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;
- (void)addObjectsFromQueue:(SCQueue *)queue;
- (void)addQueue:(SCQueue *)queue;

Getting queue objects

Method getObject removes first object from the queue and returns this object. If the queue is empty, method returns the nil pointer.

- (id)getObject;
SCQueue *queue = [SCQueue queueWithObjects:@"Object 00", @"Object 01", @"Object 02", nil];
NSLog( @"%@", queue);
NSLog( @"=====");
id object;
while ( ( object = [queue getObject])) NSLog( @"=> %@", object);
NSLog( @"=====");
NSLog( @"%@", queue);
2016-08-08 17:01:45.115 libtest[48091:4744307] Queue count=3: (
"Object 00",
"Object 01",
"Object 02"
)
2016-08-08 17:01:45.115 libtest[48091:4744307] =====
2016-08-08 17:01:45.115 libtest[48091:4744307] => Object 00
2016-08-08 17:01:45.115 libtest[48091:4744307] => Object 01
2016-08-08 17:01:45.116 libtest[48091:4744307] => Object 02
2016-08-08 17:01:45.116 libtest[48091:4744307] =====
2016-08-08 17:01:45.116 libtest[48091:4744307] Queue count=0:
)

Removing objects from queue

Class SCQueue implements the following methods for removing objects from the queue:

- (void)removeFirstObject;
- (void)removeLastObject;

Coping queue objects

Class SCQueue implements the following methods for coping queue objects:

- (void)duplicateFirstObject;
- (void)duplicateLastObject;

Queue objects access

For accessing to the queue objects class SCQueue implements the following properties:

@property (nonatomic, readonly, assign) id firstObject;

Unidirectional lists

Unidirectional list is a collection, which contains object nodes which have a data field as a "next" field, which points to the next object node in line of object nodes. Operations that can be performed on unidirectional lists include insertion, deletion and travesal.

New objects can be added into the end of unidirectional list. For access to the object you must process the all previous objects from the begin of the list. Unidirectional list supports only one direction of objects processing - from previous to the next object.

Unidirectional list allows direct access only to the first object and to the current object.

Creating lists

Class SCUnidirectionalList inherits from the class SCList the following methods for creating unidirectional lists by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)listWithCoder:(NSCoder *)coder;
+ (instancetype)listWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)listWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)listWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)listWithStream:(SCStream *)stream;
+ (instancetype)listWithFileStream:(NSString *)path;
+ (instancetype)listWithData:(NSData *)data;
+ (instancetype)listWithContentsOfFile:(NSString *)path;
+ (instancetype)listWithContentsOfURL:(NSURL *)url;
+ (instancetype)listWithContentsOfURLString:(NSString *)urlString;

Class SCUnidirectionalList inherits from the class SCList the following methods for creating class instances:

+ (instancetype)listWithName:(NSString *)name;
+ (instancetype)listWithObject:(id<SCCollectioning>)object;
+ (instancetype)listWithObjects:(id<SCCollectioning>)object, ...;
+ (instancetype)listWithCollection:(id<SCCollection>)collection;
+ (instancetype)listWithArray:(SCArray *)array;
+ (instancetype)listWithList:(SCList *)list;
+ (instancetype)list;

Initializing lists

Class SCUnidirectionalList inherits from the class SCList the following initializing methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithObject:(id<SCCollectioning>)object;
- (instancetype)initWithObjects:(id<SCCollectioning>)object, ...;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)initWithList:(SCList *)list;
- (instancetype)init;

List objects access

Class SCUnidirectionalList inherits from the class SCList the following properties for access to the list objects:

@property (nonatomic, readonly, assign) id currentObject;
@property (nonatomic, readonly, assign) id firstObject;

Coping lists

Class SCUnidirectionalList inherits from the SCList the following methods for lists coping:

- (void)setList:(SCList *)list;

Comparing lists

Class SCUnidirectionalList inherits from the class SCList the following comparing methods:

- (BOOL)isEqualToList:(SCList *)list;

Deriving new lists

Class SCUnidirectionalList inherits from the class SCList the following methods for deriving new lists by using existing lists:

- (instancetype)listByAddingObject:(id<SCCollectioning>)object;
- (instancetype)listByAddingObjects:(id<SCCollectioning>)object, ...;
- (instancetype)listByAddingCollection:(id<SCCollection>)collection;
- (instancetype)listByAddingObjectsFromArray:(SCArray *)array;
- (instancetype)listByAddingArray:(SCArray *)array;
- (instancetype)listByAddingObjectsFromList:(SCList *)list;
- (instancetype)listByAddingList:(SCList *)list;

Controlling lists

Class SCUnidirectionalList inherits from the class SCList the following control methods:

- (id)nextObject;

Method nextObject shifts the current object pointer to the next object in the receiving list and return a pointer to the next object. If the cuurent object is a last list object, then method does not change the current object.

SCUnidirectionalList *list = [SCUnidirectionalList listWithObjects:@"00", @"01", @"02", nil];
NSLog( @"%@", [list currentObject]);
NSLog( @"%@", [list nextObject]);
NSLog( @"%@", [list currentObject]);
2016-08-17 17:30:22.533 libtest[1619:86864] 00
2016-08-17 17:30:22.533 libtest[1619:86864] 01
2016-08-17 17:30:22.533 libtest[1619:86864] 01

Adding objects to list

Class SCUnidirectionalList inherits from the class SCList the following methods for inserting objects before the current object:

- (void)insertCurrentObject:(id<SCCollectioning>)object;
- (void)insertCurrentObjects:(id<SCCollectioning>)object, ...;
- (void)insertCurrentCollection:(id<SCCollection>)collection;

Class SCUnidirectionalList inherits from the class SCList the following methods for inserting objects into the begin of the list:

- (void)insertFirstObject:(id<SCCollectioning>)object;
- (void)insertFirstObjects:(id<SCCollectioning>)object, ...;
- (void)insertFirstCollection:(id<SCCollection>)collection;

Also class SCUnidirectionalList inherits from the class SCList the following methods for adding objects:

- (void)addObjectsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;
- (void)addObjectsFromList:(SList *)list;
- (void)addList:(SList *)list;

Removing objects from list

For removing objects class SCUnidirectionalList inherits the following methods:

- (void)removeCurrentObject;
- (void)removeFirstObject;

Replacing list objects

Class SCUnidirectionalList ibherits from the class SCList the following methods for replacing objects:

- (void)replaceCurrentObjectWithObject:(id<SCCollectioning>)object;
- (void)replaceFirstObjectWithObject:(id<SCCollectioning>)object;

Coping list objects

Class SCUnidirectionalList inherits from the class SCList the following objects removing methods:

- (void)duplicateCurrentObject;
- (void)duplicateFirstObject;

Bidirectional lists

In the bidirectional list each object node contains, besides the next-node link, a second link field pointing to the previous object node in the sequence. The two links may be called forwards and backwards, or next and prev,

Class SCBidirectionalList provides changing the current object pointer in two directions - from current object to the next object and from current to the previous object. Additionally, class SCBidirectionalList declares the methods for accessing to the list last object.

List objects access

Class SCBidirectionalList implements the following properties for list objects accessing:

@property (nonatomic, readonly, assign) id lastObject;

Property lastObject returns the last object from the receiving list. If the list is empty, then method returns the nil pointer.

Controlling list

Class SCBidirectionalList implements the following methods for list controlling:

- (id)previousObject;

Method previousObject shifts the current object pointer to the previous object in the receiving list and return a pointer to the previous object. If the current object is a first object, then the method does not changes the current object and returns a nil pointer.

SCBidirectionalList *list = [SCBidirectionalList listWithObjects:@"00", @"01", @"02", nil];
do { } while ( [list nextObject]);
do {
NSLog( @"%@", [list currentObject]);
} while ( [list previousObject]);
2016-08-17 21:07:59.306 libtest[3279:182111] 02
2016-08-17 21:07:59.306 libtest[3279:182111] 01
2016-08-17 21:07:59.306 libtest[3279:182111] 00

Adding objects to list

Class SCBidirectionalList implements the following methods for adding objects into the bidirectional list:

- (void)insertLastObject:(id<SCCollectioning>)object;
- (void)insertLastObjects:(id<SCCollectioning>)object, ...;
- (void)insertLastCollection:(id<SCCollection>)collection;

Removing objects from list

Class SCBidirectionalList implements the following methods for removing objects:

- (void)removeLastObject;

Method removeLastObject emoves the last objects of the receiving list:

SCBidirectionalList *list = [SCBidirectionalList listWithObjects:@"00", @"01", @"02", nil];
NSLog( @"%@", list);
[list removeLastObject];
NSLog( @"%@", list);
2016-08-17 21:15:38.556 libtest[3382:184602] List count=3: (
"00",
"01",
"02"
)
Current object: "00"
2016-08-17 21:15:38.557 libtest[3382:184602] List count=2: (
"00",
"01"
)
Current object: "00"

Replacing list objects

For replacing objects class SCBidirectionalList implements the following methods:

- (void)replaceLastObjectWithObject:(id<SCCollectioning>)object;

Method replaceLastObjectWithObject: replaces the last object of receiving collection with the specified object:

SCBidirectionalList *list = [SCBidirectionalList listWithObjects:@"00", @"01", @"02", nil];
NSLog( @"%@", list);
[list replaceLastObjectWithObject:@"=="];
NSLog( @"%@", list);
2016-08-17 21:20:48.686 libtest[3422:186097] List count=3: (
"00",
"01",
"02"
)
Current object: "00"
2016-08-17 21:20:48.686 libtest[3422:186097] List count=3: (
"00",
"01",
"=="
)
Current object: "00"

Coping list objects

Class SCBidirectionalList implements the following methods for coping objects within the list:

- (void)duplicateLastObject;

Method duplicateLastObject duplicates the last object of the receiving list:

SCBidirectionalList *list = [SCBidirectionalList listWithObjects:@"00", @"01", @"02", nil];
NSLog( @"%@", list);
[list duplicateLastObject];
NSLog( @"%@", list);
2016-08-17 21:22:27.623 libtest[3448:186559] List count=3: (
"00",
"01",
"02"
)
Current object: "00"
2016-08-17 21:22:27.623 libtest[3448:186559] List count=4: (
"00",
"01",
"02",
"02"
)
Current object: "00"

Sorters

Collections, which support the direct access to the objects (arrays and ordered sets), also support the objects sorting. But the collections does not have the algorithms for sorting own objects. This approach related to the fact that it is now known many such algorithms, and can be developed in the future, new, and there is no sense to spend time and resources for the implementation of the library all of them. But at the same time we need to be able to add new sorting algorithms.

That is why the implementation of sorting algorithms made in separate classes called sorters. Instances of this classes perform all data sorting.

Protocol and class SCSorter

Any sorter class must comply with the SCSorter protocol, which declares the following mandatory methods:

- (void)ascendingSortCollection:(id<SCMutableIndexedCollection>)collection;
- (void)descendingSortCollection:(id<SCMutableIndexedCollection>)collection;
- (void)ascendingSortText:(SCStrings *)text;
- (void)descendingSortText:(SCStrings *)text;

The last two methods does not work with collections. They work with strings lists, texts and text files, which described in the Programming Guide section String lists, texts and text files. This methods have been developed beacause sorting of text data is different from the sorting of regular data.

Class SCSorter implements all methods of protocol SCSorter, but these methods are abstract and must be reimplemented in all child classes. The main purpose of the class SCSorter is grouping of library supported real sorting algorithms. Now in the library implement the following sorting algorithms as a children of class SCSorter:

These classes describe in the next sections of Programming Guide.

Sorter SCBubbleSorter

Class SCBubbleSorter implements one of the simplest and well-known sorting algorithms. This algorithm is known as "bubble" or "bubble sorting". Although the algorithm is simple, it is too slow. Class SCBubbleSorter implements only one class method for creating the class instances:

+ (instancetype)sorter;

Sorter SCFastSorter

Class SCFastSorter implements the well-known sorting algorithm, which is known as a "fast sorting". This sorter is a default library sorter. Class SCFastSorter implements only one class method for creating the class instances:

+ (instancetype)sorter;

Collections and standard classes

SCL implements a partial compatibility between collections and Objective-C standard classes. This compatibility can be devided into the following groups:

All library classes have some common opposed to the standard classes:

Collection error processing

When using the collections a variety of errors may occur. In this section, we describe the process of error handling by the collections unit.

If the collection detects the occurrence of an error, it is first of all checks the delegate object (described in the Programming Guide section Delegation protocol SCCollectionDelegate). If delegate object is not assigned, the collection is performed the exception SCCollectionException throwing.

If the delegate object is assigned, then collection calls his method collection:didDetectException:. If the method returns value YES, then collection ignores the error that occurred. Otherwise, it throws a class SCCollectionException instance.

For details on specific collection errors see Collection errors. Now we describe only the primary collection errors:

Delegation protocol SCCollectionDelegate

In order to responding to various events in the collections programmer can assign a delegate object by using property delegate.

As a delegate object you can using instance of the class, which compiances to the protocol SCCollectionDelegate. Also may be used the instance of any child of class SCCollectionDelegate (this class is implements all methods of SCCollectionDelegate protocol).

Now we examine the different methods of protocol and describe events, at approach of which they are called:

Collection error processing

Protocols SCCollectionDelegate declares the following methods for collection error handling:

- (BOOL)collection:(SCCollection *)collection didDetectException:(SCCollectionException *)exception;

Object adding events

Protocol SCCollectionDelegate declares the following methods for processing adding objects events:

- (void)collection:(SCCollection *)collection willAddObject:(id)object;
- (void)collection:(SCCollection *)collection willInsertObject:(id)object atIndex:(SCIndex)index;
- (void)collection:(SCCollection *)collection willSetObject:(id)object forKey:(NSString *)key;
- (void)collection:(SCCollection *)collection willSetValue:(id)value forKey:(NSString *)key;
- (void)collection:(SCCollection *)collection didFinishAddingObject:(id)object;
- (void)collection:(SCCollection *)collection didFinishInsertingObject:(id)object atIndex:(SCIndex)index;
- (void)collection:(SCCollection *)collection didFinishSettingObject:(id)object forKey:(NSString *)key;
- (void)collection:(SCCollection *)collection didFinishSettingValue:(id)value forKey:(NSString *)key;

Object removing events

For processing the object removing events protocol SCCollectionDelegate declares the following methods:

- (void)willRemoveAllObjectsFromCollection:(SCCollection *)collection;
- (void)collection:(SCCollection *)collection willRemoveObjectsOfClassName:(NSString *)name;
- (void)collection:(SCCollection *)collection willRemoveObject:(id)object;
- (void)collection:(SCCollection *)collection willRemoveObjectAtIndex:(SCIndex)index;
- (void)collection:(SCCollection *)collection willRemoveObjectForKey:(NSString *)key;
- (void)didFinishRemovingAllObjectsFromCollection:(SCCollection *)collection;
- (void)collection:(SCCollection *)collection didFinishRemovingObjectsOfClassName:(NSString *)name;
- (void)collection:(SCCollection *)collection didFinishRemovingObject:(id)object;
- (void)collection:(SCCollection *)collection didFinishRemovingObjectAtIndex:(SCIndex)index;
- (void)collection:(SCCollection *)collection didFinishRemovingObjectForKey:(NSString *)key;

Object processing events

Protocol SCCollectionDelegate declares the following methods for collection objects processing:

- (void)processObject:(id)object collection:(SCCollection *)collection;

Data sorting events

When the collection sorts its contents, the following methods of protocol SCCollectionDelegate are called for the delegate object:

- (void)collection:(SCCollection *)collection willSortAscending:(BOOL)ascending sorter:(id<SCSorter>)sorter;
- (void)collection:(SCCollection *)collection didFinishSortingAscending:(BOOL)ascending sorter:(id<SCSorter>)sorter;

Object replacing events

Protocol SCCollectionDelegate declares the following methods for object replacing events processing:

- (void)collection:(SCCollection *)collection willReplaceObjectAtIndex:(SCIndex)index withObject:(id)object;
- (void)collection:(SCCollection *)collection willReplaceObjectsInRange:(NSRange)range withCollection:(id)source;
- (void)collection:(SCCollection *)collection willReplaceObject:(id)replaced withObject:(id)object;
- (void)collection:(SCCollection *)collection didFinishReplacingObjectAtIndex:(SCIndex)index withObject:(id)object;
- (void)collection:(SCCollection *)collection didFinishReplacingObjectsInRange:(NSRange)range withCollection:(id)source;
- (void)collection:(SCCollection *)collection didFinishReplacingObject:(id)replaced withObject:(id)object;

Coping and moving object events

Coping and moving object events are processed by calling the following methods of protocol SCCollectionDelegate:

- (void)collection:(SCCollection *)collection willExchangeObjectAtIndex:(SCIndex)index
withObjectAtIndex:(SCIndex)destination;
- (void)collection:(SCCollection *)collection didFinishExchangingObjectAtIndex:(SCIndex)index
withObjectAtIndex:(SCIndex)destination;

String lists, texts and text files

Samond Classes Library includes the group of classes for processing text information:

The following diagram displays the text classes hierarchy.

text.png

Separate chapters are also described the additional text components:

String lists

String list is an aggregate of text strings, which are combined into the single instance of class SCStrings. Additionally to storing strings, string list supports basic methods for string processing - adding, removing, changing, moving within the list and so on.

Class SCStrings is a based (parent) class for all other text processing classes. Each child class extends the class SCStrings functionality. This Programming Guide chapter describes the class SCStrings. Other text processing classes are described in the next sections of Programming Guide.

Creating lists

For creating string lists by using the data from the serialized files, data dictionaries, streams and data objects class SCStrings declares the following class methods:

+ (instancetype)stringsWithCoder:(NSCoder *)coder;
+ (instancetype)stringsWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)stringsWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)stringsWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)stringsWithStream:(SCStream *)stream;
+ (instancetype)stringsWithFileStream:(NSString *)path;
+ (instancetype)stringsWithData:(NSData *)data;
+ (instancetype)stringsWithContentsOfFile:(NSString *)path;
+ (instancetype)stringsWithContentsOfURL:(NSURL *)url;
+ (instancetype)stringsWithContentsOfURLString:(NSString *)urlString;

Class SCStrings implements the following class method for class instances creating:

+ (instancetype)stringsWithName:(NSString *)name;
+ (instancetype)stringsWithString:(NSString *)string;
+ (instancetype)stringsWithCollection:(id<SCCollection>)collection;
+ (instancetype)stringsWithArray:(SCArray *)array;
+ (instancetype)stringsWithStrings:(SCStrings *)strings;
+ (instancetype)strings;

Initializing lists

Class SCStrings implements the following initialization methods:

- (instancetype)initWithName:(NSString *)name;
- (instancetype)initWithString:(NSString *)string;
- (instancetype)initWithCollection:(id<SCCollection>)collection;
- (instancetype)initWithArray:(SCArray *)array;
- (instancetype)initWithStrings:(SCStrings *)strings;
- (instancetype)init;

Class instance properties

Class SCStrings declares the following instance properties:

@property (nonatomic, readwrite, retain) NSString *name;
@property (nonatomic, readonly, assign) SCIndex count;
@property (nonatomic, readwrite, assign) BOOL readOnly;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL modified;
@property (nonatomic, readwrite, assign) BOOL caseInsensitive;
@property (nonatomic, readwrite, retain) id<SCTextDelegate> delegate;

Copying lists

Class SCStrings implements the following methods for copying strings lists:

- (void)setStrings:(SCStrings *)strings;
- (void)setCollection:(id<SCCollection>)collection;
- (void)setString:(NSString *)string;

Comparing lists

Class SCStrings implements the following comparing methods:

- (BOOL)isEqualToStrings:(SCStrings *)strings;
- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Deriving new strings lists

Class SCStrings declares the following methods for deriving new strings lists by using an existing strings lists:

- (instancetype)stringsByAddingString:(NSString *)string;
- (instancetype)stringsByAddingCollection:(id<SCCollection>)collection;
- (instancetype)stringsByAddingStrings:(SCStrings *)strings;
- (instancetype)stringsByAddingStringsFromArray:(SCArray *)array;
- (instancetype)stringsByAddingArray:(SCArray *)array;

Enumerating strings

Class SCStrings implements the following enumerating strings methods:

@property (nonatomic, readonly, assign) NSEnumerator *stringEnumerator;
@property (nonatomic, readonly, assign) NSEnumerator *reverseStringEnumerator;
- (void)enumerateWithDelegate:(id<SCTextDelegate>)delegate;
- (void)enumerate;
- (void)reverseEnumerateWithDelegate:(id<SCTextDelegate>)delegate;
- (void)reverseEnumerate;

Also for support of operator for..in class SCStrings implements the following method:

- (NSUInteger)countByEnumeratingWithState:(NSFastEnumerationState *)state objects:(id *)buffer count:(NSUInteger)count;
SCStrings *list = [SCStrings strings];
[list addString:@"First string"];
[list addString:@"Second string"];
[list addString:@"Last string"];
for ( NSString *string in list) NSLog( @"%@", string);
2017-09-10 21:48:48.625693+0300 libtest[5836:158623] First string
2017-09-10 21:48:48.625713+0300 libtest[5836:158623] Second string
2017-09-10 21:48:48.625725+0300 libtest[5836:158623] Last string

Converting lists

Class SCStrings implements the following converting properties:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, retain) NSArray *foundationArray;

Sorting lists

Class SCStrings implements the following sorting properties and methods:

- (void)sortAscendingWithSorter:(id<SCSorter>)sorter;
- (void)sortDescendingWithSorter:(id<SCSorter>)sorter;
- (void)sortWithSorter:(id<SCSorter>)sorter;
- (void)sortAscending;
- (void)sortDescending;
- (void)sort;
- (SCStrings *)ascendingSortedStringsWithSorter:(id<SCSorter>)sorter;
- (SCStrings *)descendingSortedStringsWithSorter:(id<SCSorter>)sorter;
- (SCStrings *)sortedStringsWithSorter:(id<SCSorter>)sorter;
@property (nonatomic, readonly, assign) SCStrings *ascendingSortedStrings;
@property (nonatomic, readonly, assign) SCStrings *descendingSortedStrings;
@property (nonatomic, readonly, assign) SCStrings *sortedStrings;
Attention
If any of these methods are calling for the read only strings list, then error SCL-20063 is occurs.
Attention
Strings sort depends on the value of the property caseInsensitive.

During the sorting operation strings list calls the methods text:willSortAscending:sorter: and text:didFinishSortingAscending:sorter: of the delegate object.

Adding strings to list

If the described methods calls for the read only strings list, then the error SCL-20063 is occurs.

Class SCStrings implements the following methods for adding strings:

- (void)addString:(NSString *)string;
- (void)addCollection:(id<SCCollection>)collection;
- (void)addStrings:(SCStrings *)strings;
- (void)addLine;
- (void)addStringsFromArray:(SCArray *)array;
- (void)addArray:(SCArray *)array;

During execution of this methods strings list calls the events text:willAddString: and text:didFinishAddingString: of the delegate object.

Additionally to adding methods class SCStrings implements the methods for inserting strings at the specified indexes:

- (void)insertString:(NSString *)string atIndex:(SCIndex)index;
- (void)insertStrings:(SCStrings *)strings atIndex:(SCIndex)index;
- (void)insertCollection:(id<SCCollection>)collection atIndex:(SCIndex)index;
- (void)insertStrings:(SCStrings *)strings atIndexes:(NSIndexSet *)indexes;
- (void)insertCollection:(id<SCCollection>)collection atIndexes:(NSIndexSet *)indexes;
- (void)insertLineAtIndex:(SCIndex)index;

During the methods execution the strings list calls the event handlers text:willInsertString:atIndex: and text:didFinishInsertingString:atIndex: of list delegation object.

Removing strings from list

Class SCStrings implements the following methods for removing strings from the list:

- (void)removeAllStrings;
- (void)removeFirstString;
- (void)removeLastString;
- (void)removeStringAtIndex:(SCIndex)index;
- (void)removeStringsAtIndexes:(NSIndexSet *)indexes;
- (void)removeString:(NSString *)string;
- (void)removeStrings:(SCStrings *)strings;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeStringsWithSubstring:(NSString *)substring;
- (void)removeStringsNotAtIndexes:(NSIndexSet *)indexes;
- (void)removeStringsNotEqualTo:(NSString *)string;
- (void)removeStringsNotInStrings:(SCStrings *)strings;
- (void)removeStringsNotInCollection:(id<SCCollection>)collection;
- (void)removeStringsWithoutSubstring:(NSString *)substring;
- (void)removeDuplicatedStrings;

If any method calls for the read only list, then error SCL-20063 is occurs.

This methods call the event handlers text:willRemoveStringAtIndex: and text:didFinishRemovingStringAtIndex: of the list delegate object.

These methods call the event handlers text:willRemoveString: and text:didFinishRemovingString: of the delegate object.

These methods call the event handlers text:willRemoveStringAtIndex: and text:didFinishRemovingStringAtIndex: of the delegate object.

Replacing strings

Class SCStrings implements the following methods for replacing strings within list:

- (void)replaceStringAtIndex:(SCIndex)index withString:(NSString *)string;
- (void)replaceStringsAtIndexes:(NSIndexSet *)indexes withStrings:(SCStrings *)strings;
- (void)replaceStringsAtIndexes:(NSIndexSet *)indexes withCollection:(id<SCCollection>)collection;
- (void)replaceString:(NSString *)string withString:(NSString *)newString;

If any of these methods calls for a read only strings list, then the error SCL-20063 is occurs.

These methods call the event handlers text:willReplaceStringAtIndex:withString: and text:didFinishReplacingStringAtIndex:withString: delegate object.

Also a class SCStrings provides the support of the operator [] for replacing strings by using its indexes:

SCStrings *strings = [SCStrings strings];
[strings addString:@"First string"];
[strings addString:@"Second string"];
[strings addString:@"Last string"];
NSLog( @"%@", strings);
strings[1] = @"New string";
NSLog( @"%@", strings);
2017-09-11 12:47:49.626863+0300 libtest[15505:479454] Strings list count=3, case sensitive, modified: (
First string
Second string
Last string
)
2017-09-11 12:47:49.626967+0300 libtest[15505:479454] Strings list count=3, case sensitive, modified: (
First string
New string
Last string
)

Coping and moving strings

Class SCStrings is not just a container for storing a variety of strings, but also offers enough powerful tools for line by line content processing. These tools contain the following methods:

- (void)exchangeStringAtIndex:(SCIndex)index withStringAtIndex:(SCIndex)destination;
- (void)duplicateStringAtIndex:(SCIndex)index;
- (void)duplicateAllStrings;
- (void)duplicate;
- (void)copyStringAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)moveStringAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)forwardMoveStringAtIndex:(SCIndex)index steps:(SCIndex)steps;
- (void)forwardMoveStringAtIndex:(SCIndex)index;
- (void)backwardMoveStringAtIndex:(SCIndex)index steps:(SCIndex)steps;
- (void)backwardMoveStringAtIndex:(SCIndex)index;
- (void)moveToFirstPositionStringAtIndex:(SCIndex)index;
- (void)moveToLastPositionStringAtIndex:(SCIndex)index;

If you attempt calling any of these methods for the read only strings list, then the error SCL-20063 is occurs. In addition to this error may cause other errors, typical for the whole group of methods and specific method. When considering the methods we will indicate the exceptions that may occur during operations.

Into the moving and copying properties and methods also include the reverse properties and methods:

@property (nonatomic, readonly, assign) SCStrings *reversedStrings;
- (void)reverse;

Strings access

Class SCStrings implements the following properties and methods for accessing to the strings:

@property (nonatomic, readonly, assign) NSString *firstString;
@property (nonatomic, readonly, assign) NSString *lastString;
- (NSString *)firstString;
- (NSString *)lastString;
- (NSString *)stringAtIndex:(SCIndex)index;
- (SCStrings *)stringsAtIndexes:(NSIndexSet *)indexes;

Also the class SCStrings provides a support of the operator [] for accessing a direct access to strings by using indexes:

SCStrings *strings = [SCStrings strings];
[strings addString:@"First string"];
[strings addString:@"Second string"];
[strings addString:@"Last string"];
NSLog( @"%@", strings[1]);
2017-09-11 12:58:11.386036+0300 libtest[15714:487455] Second string

Search strings

Class SCStrings implements the many methods for searching and selecting strings within the strings list by using the various criteria. This methods can be devided into the following groups, which are desribed in this section:

During search operations class SCStrings allows for value of the property caseInsensitive. If this value is equal to NO, then class instance ignores the characters case.

Class SCStrings declares the following methods of checking for strings:

- (BOOL)containsString:(NSString *)string;
- (BOOL)containsStrings:(SCStrings *)strings;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyString:(SCStrings *)strings;
- (BOOL)containsAnyStringFromCollection:(id<SCCollection>)collection;
- (BOOL)containsSubstring:(NSString *)substring;
- (BOOL)containsSubstrings:(SCStrings *)substrings;
- (BOOL)containsSubstringsFromCollection:(id<SCCollection>)collection;
- (BOOL)containsAnySubstring:(SCStrings *)substrings;
- (BOOL)containsAnySubstringFromCollection:(id<SCCollection>)collection;
- (BOOL)containsDuplicatedStrings;

For indexes detection class SCStrings implements the following properties and methods:

@property (nonatomic, readonly, assign) SCIndex indexOfLastString;
- (SCIndex)indexOfString:(NSString *)string;
- (SCIndex)indexOfLastString;
- (SCIndex)indexOfSubstring:(NSString *)substring;

Strings selection is a process of creating new strings list based on selection criteria from the source list. Class SCStrings declares a wide range of selection methods:

- (SCStrings *)stringsWithSubstring:(NSString *)substring;
- (SCStrings *)stringsWithSubstrings:(SCStrings *)substrings;
- (SCStrings *)stringsWithSubstringsFromCollection:(id<SCCollection>)collection;
- (SCStrings *)stringsWithAnySubstring:(SCStrings *)substrings;
- (SCStrings *)stringsWithAnySubstringFromCollection:(id<SCCollection>)collection;
- (SCStrings *)stringsWithoutSubstring:(NSString *)substring;
- (SCStrings *)stringsWithoutSubstrings:(SCStrings *)substrings;
- (SCStrings *)stringsWithoutSubstringsFromCollection:(id<SCCollection>)collection;

Class SCStrings implements the following methods for strings counting:

- (SCULong)countOfString:(NSString *)string;
- (SCULong)countOfSubstring:(NSString *)substring;
- (SCULong)countOfStringsWithSubstring:(NSString *)substring;

Unique strings lists

Class SCUniqueStrings inherits from the class SCStrings all strings list functionality, extending it with the features for control the uniqueness added information - the unique strings list do not allow duplicate strings stored in them. Trying to add an already presented string into the list, depending on the property strongMode value leads either to ignore the added string or causes the trowing the exception SCL-20069, indicating what of the existing strings of the new duplicates.

Accordingly, inherited from the class SCStrings methods to copy and duplicate strings are overloaded and ignore the duplicated strings or throw the exception SCL-20069.

We note in particular that, as an ancesor class, SCUniqueStrings depends on the value of the property caseInsensitive. The important point is an instance behavior when you change the property value from NO to YES. With this switching can be a situation when the previously considered differnt strings in the new mode will be recognized as the same and a string with large index well be removed or exception SCL-20069 will be throwing.

SCUniqueStrings *strings = [SCUniqueStrings uniqueStrings];
strings.caseInsensitive = NO;
[strings addString:@"String 00"];
[strings addString:@"string 00"];
strings.caseInsensitive = YES;
2016-08-25 11:30:46.520 libtest[12212:1075882] SCL-20069: Duplicate string "string 00" at index 1
2016-08-25 11:30:46.520 libtest[12212:1075882] ==================================================

Therefore, we recommend caution with change the case insensitive mode for non-empty unique strings lists.

When you copy strings from the existing collections of any supported type duplicate string will be either removed or the error is occurs.

Class instance properties

Class SCUniqueStrings extends the class SCStrings by implements the following properties:

@property (nonatomic, readwrite, assign) BOOL strongMode;

Creating lists

Class SCUniqueStrings declares the following class methods for creating class instances by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)uniqueStringsWithCoder:(NSCoder *)coder;
+ (instancetype)uniqueStringsWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)uniqueStringsWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)uniqueStringsWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)uniqueStringsWithStream:(SCStream *)stream;
+ (instancetype)uniqueStringsWithFileStream:(NSString *)path;
+ (instancetype)uniqueStringsWithData:(NSData *)data;
+ (instancetype)uniqueStringsWithContentsOfFile:(NSString *)path;
+ (instancetype)uniqueStringsWithContentsOfURL:(NSURL *)url;
+ (instancetype)uniqueStringsWithContentsOfURLString:(NSString *)urlString;

For creating lists class SCUniqueStrings implements the following class methods:

+ (instancetype)uniqueStringsWithName:(NSString *)name;
+ (instancetype)uniqueStringsWithString:(NSString *)string;
+ (instancetype)uniqueStringsWithCollection:(id<SCCollection>)collection;
+ (instancetype)uniqueStringsWithArray:(SCArray *)array;
+ (instancetype)uniqueStringsWithStrings:(SCStrings *)strings;
+ (instancetype)uniqueStringsWithUniqueStrings:(SCUniqueStrings *)uniqueStrings;
+ (instancetype)uniqueStrings;

Initializing lists

Class SCUniqueStrings declares the following initializing methods:

- (instancetype)initWithUniqueStrings:(SCUniqueStrings *)uniqueStrings;

Coping lists

Class SCUniqueStrings implements the following advanced methods for coping class instances:

Comparing lists

Class SCUniqueStrings extends the parent class SCStrings by declaring the following comparing methods:

- (BOOL)isEqualToUniqueStrings:(SCUniqueStrings *)uniqueStrings;

Converting lists

Class SCUniqueStrings implements the following advanced converting properties:

@property (nonatomic, readonly, assign) SCStrings *strings;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;

Deriving new unique strings lists

Class SCUniqueStrings implements the following methods for creating new unique strings lists by using existing unique strings lists:

- (instancetype)uniqueStringsByAddingString:(NSString *)string;
- (instancetype)uniqueStringsByAddingCollection:(id<SCCollection>)collection;
- (instancetype)uniqueStringsByAddingStringsFromArray:(SCArray *)array;
- (instancetype)uniqueStringsByAddingArray:(SCArray *)array;
- (instancetype)uniqueStringsByAddingStrings:(SCStrings *)strings;
- (instancetype)uniqueStringsByAddingUniqueStrings:(SCUniqueStrings *)uniqueStrings;

Texts

Class SCText extends the parent class SCStrings functionality by adding to a strings list methods for working with text blocks - continuous groups of strings within the list. Class SCText provides the operations such as add, insert, delete, copy, move text blocks and so on. This functionality is a standard features set of the modern text processing software.

This section describes the methods of work with texts and text blocks on the assumption that you are already familiar with basic functionality, implemented in the class SCStrings.

Creating texts

Class SCText declares the following class methods for creating class instances by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)textWithCoder:(NSCoder *)coder;
+ (instancetype)textWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)textWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)textWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)textWithStream:(SCStream *)stream;
+ (instancetype)textWithFileStream:(NSString *)path;
+ (instancetype)textWithData:(NSData *)data;
+ (instancetype)textWithContentsOfFile:(NSString *)path;
+ (instancetype)textWithContentsOfURL:(NSURL *)url;
+ (instancetype)textWithContentsOfURLString:(NSString *)urlString;

For creating texts class SCText implements the following class methods:

+ (instancetype)textWithName:(NSString *)name;
+ (instancetype)textWithString:(NSString *)string;
+ (instancetype)textWithStrings:(SCStrings *)strings;
+ (instancetype)textWithCollection:(id<SCCollection>)collection;
+ (instancetype)textWithArray:(SCArray *)array;
+ (instancetype)textWithText:(SCText *)text;
+ (instancetype)text;

Initializing texts

Class SCText extends the parent class by declaring the following initialization methods:

- (instancetype)initWithText:(SCText *)text;

Coping texts

Class SCText declares the following additional coping methods:

- (void)setText:(SCText *)text;

Comparing texts

Class SCText implements the following comparing methods:

- (BOOL)isEqualToText:(SCText *)text;

Deriving new texts

Class SCText declares the following methods for deriving new texts by using existing texts:

- (instancetype)textByAddingString:(NSString *)string;
- (instancetype)textByAddingCollection:(id<SCCollection>)collection;
- (instancetype)textByAddingStringsFromArray:(SCArray *)array;
- (instancetype)textByAddingArray:(SCArray *)array;
- (instancetype)textByAddingStrings:(SCStrings *)strings;
- (instancetype)textByAddingText:(SCText *)text;

Converting texts

Class SCText implements the following advanced converting properties:

@property (nonatomic, readonly, assign) SCStrings *strings;
@property (nonatomic, readonly, assign) SCUniqueStrings *uniqueStrings;

Adding text blocks

Class SCText declares the following methods for adding text blocks:

- (void)addText:(SCStrings *)text;
- (void)insertText:(SCStrings *)text atIndex:(SCIndex)index;

Removing text blocks

Class SCText implements the following methods for removing text blocks from the text:

- (void)removeAllText;
- (void)removeTextInRange:(NSRange)range;
- (void)removeTextWithSubstring:(NSString *)substring;
- (void)removeTextWithoutSubstring:(NSString *)substring;
- (void)removeSubstring:(NSString *)substring;
- (SCText *)cutTextInRange:(NSRange)range;
- (void)removeText:(SCStrings *)text;

Replacing text blocks

Class SCText declares the following replacing methods:

- (void)replaceTextInRange:(NSRange)range withText:(SCStrings *)text;
- (void)replaceTextInRange:(NSRange)range withCollection:(id<SCCollection>)collection;
- (void)replaceText:(SCStrings *)oldText withText:(SCStrings *)newText;

Coping and moving text blocks

Class SCText extends the parent class coping and moving methods by implements the following own methods:

- (void)exchangeTextInRange:(NSRange)source withTextInRange:(NSRange)destination;
- (void)duplicateTextInRange:(NSRange)range;
- (void)duplicateStringsInRange:(NSRange)range;
- (void)copyTextInRange:(NSRange)range toIndex:(SCIndex)destination;
- (void)moveTextInRange:(NSRange)range toIndex:(SCIndex)destination;
- (void)forwardMoveTextInRange:(NSRange)range steps:(SCIndex)steps;
- (void)forwardMoveTextInRange:(NSRange)range;
- (void)backwardMoveTextInRange:(NSRange)range steps:(SCIndex)steps;
- (void)backwardMoveTextInRange:(NSRange)range;
- (void)moveToFirstPositionTextInRange:(NSRange)range;
- (void)moveToLastPositionTextInRange:(NSRange)range;

Text access

Class SCText implements the following methods for accessing to the text:

- (SCText *)textInRange:(NSRange)range;

Finding and selecting text

Class SCText implemens the following methods for finding and selecting texts:

- (BOOL)containsText:(SCStrings *)text;
- (NSRange)rangeOfText:(SCStrings *)text;
- (NSRange)rangeOfCollection:(id<SCCollection>)collection;
- (SCIndex)indexOfText:(SCStrings *)text;
- (SCIndex)indexOfCollection:(id<SCCollection>)collection;
- (SCUInteger)countOfText:(SCStrings *)text;
- (SCUInteger)countOfCollection:(id<SCCollection>)collection;
- (SCArray *)indexesOfText:(SCStrings *)text;
- (SCArray *)indexesOfCollection:(id<SCCollection>)collection;
- (SCTextIndex *)textIndexOfSubstring:(NSString *)substring;
- (SCArray *)textIndexesOfSubstring:(NSString *)substring;

Please note that the work of these methods depends on the value of the property caseInsensitive.

Class SCText extends the strings selecting features of the parent class SCStrings by implementing the following own methods:

- (SCText *)textWithSubstring:(NSString *)substring;
- (SCText *)textWithoutSubstring:(NSString *)substring;

Please note that the work of these methods depends on the value of the property caseInsensitive.

Text files

Class SCTextFile extends the parent class SCText functionality by adding methods for working with disk files. Text files allow reading text from files, writing text to the files and text blocks reading and writing operations. As a child of classes SCText and SCStrings, instances of class SCTextFile allows all parent classes functionality.

Class instance properties

Class SCTextFile declares the following most important properties:

@property (nonatomic, readonly, retain) NSString *path;
@property (nonatomic, readonly, assign) BOOL modified;

Creating text files

Class SCTextFile declares the following class methods for creating class instances by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)textFileWithCoder:(NSCoder *)coder;
+ (instancetype)textFileWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)textFileWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)textFileWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)textFileWithStream:(SCStream *)stream;
+ (instancetype)textFileWithFileStream:(NSString *)path;
+ (instancetype)textFileWithData:(NSData *)data;
+ (instancetype)textFileWithContentsOfFile:(NSString *)path;
+ (instancetype)textFileWithContentsOfURL:(NSURL *)url;
+ (instancetype)textFileWithContentsOfURLString:(NSString *)urlString;

For creating text files class SCTextFile implements the following class methods:

+ (instancetype)textFileWithName:(NSString *)name;
+ (instancetype)textFileWithString:(NSString *)string;
+ (instancetype)textFileWithStrings:(SCStrings *)strings;
+ (instancetype)textFileWithCollection:(id<SCCollection>)collection;
+ (instancetype)textFileWithArray:(SCArray *)array;
+ (instancetype)textFileWithText:(SCText *)text;
+ (instancetype)textFileWithTextFile:(SCTextFile *)textFile;
+ (instancetype)textFileWithName:(NSString *)name stream:(SCStream *)stream;
+ (instancetype)textFileFromStream:(SCStream *)stream;
+ (instancetype)textFileWithName:(NSString *)name path:(NSString *)path;
+ (instancetype)textFileWithPath:(NSString *)path;
+ (instancetype)textFile;

Initializing text files

Class SCTextFile implements the following initialization methods (additionally to initialization methods of the parent classes SCText and SCStrings):

- (instancetype)initWithTextFile:(SCTextFile *)textFile;
- (instancetype)initWithName:(NSString *)name stream:(SCStream *)stream;
- (instancetype)initFromStream:(SCStream *)stream;
- (instancetype)initWithName:(NSString *)name path:(NSString *)path;
- (instancetype)initWithPath:(NSString *)path;

Coping text files

Class SCTextFile declares the following methods for coping class instances:

- (void)setTextFile:(SCTextFile *)textFile;

Deriving New Text Files

Class SCTextFile implements the following methods for creating new text files by using strings from the existing text files:

- (instancetype)textFileByAddingString:(NSString *)string;
- (instancetype)textFileByAddingCollection:(id<SCCollection>)collection;
- (instancetype)textFileByAddingStringsFromArray:(SCArray *)array;
- (instancetype)textFileByAddingArray:(SCArray *)array;
- (instancetype)textFileByAddingStrings:(SCStrings *)strings;
- (instancetype)textFileByAddingText:(SCText *)text;
- (instancetype)textFileByAddingTextFile:(SCTextFile *)textFile;
- (instancetype)textFileByAddingTextFileWithPath:(NSString *)path;

Converting text files

Class SCTextFile implements the following converting properties:

@property (nonatomic, readonly, assign) SCStrings *strings;
@property (nonatomic, readonly, assign) SCUniqueStrings *uniqueStrings;
@property (nonatomic, readonly, assign) SCText *text;

Reading and writing text files

Class SCTextFile declares the following methods for reading text files:

- (BOOL)readFromStream:(SCStream *)stream;
- (BOOL)readWithPath:(NSString *)path;
- (BOOL)read;
- (BOOL)reset;

All methods return the value YES if the reading operation is successfully complited, otherwise return the value NO.

Class SCTextFile implements the following writing methods:

- (BOOL)writeTextToStream:(SCStream *)stream;
- (BOOL)writeWithPath:(NSString *)path;
- (BOOL)write;
- (BOOL)appendToFileWithPath:(NSString *)path;

Reading and writing text blocks

Class SCTextFile declares the following methods for reading the text blocks:

- (BOOL)addTextFromStream:(SCStream *)stream;
- (BOOL)addTextWithPath:(NSString *)path;
- (BOOL)insertTextFromStream:(SCStream *)stream atIndex:(SCIndex)index;
- (BOOL)insertTextWithPath:(NSString *)path atIndex:(SCIndex)index;

Examples of this section use the test file /tmp/sample.txt with the following contents:

String 10
String 11

Class SCTextFile implements the following methods for text blocks replacement:

- (BOOL)replaceTextInRange:(NSRange)range withTextFromStream:(SCStream *)stream;
- (BOOL)replaceTextInRange:(NSRange)range withTextWithPath:(NSString *)path;
- (BOOL)replaceText:(SCStrings *)text withTextFromStream:(SCStream *)stream;
- (BOOL)replaceText:(SCStrings *)text withTextWithPath:(NSString *)path;

Class SCTextFile implements the following methods for text blocks writing:

- (BOOL)writeTextInRange:(NSRange)range toStream:(SCStream *)stream;
- (BOOL)writeTextInRange:(NSRange)range withPath:(NSString *)path;
- (BOOL)appendTextInRange:(NSRange)range toFileWithPath:(NSString *)path;
- (SCText *)cutTextInRange:(NSRange)range toStream:(SCStream *)stream;
- (SCText *)cutTextInRange:(NSRange)range withPath:(NSString *)path;
- (SCText *)cutAndAppendTextInRange:(NSRange)range toFileWithPath:(NSString *)path;

Additionally, class SCTextFile implements the methods for writing strings, which selected by using the various criteria:

- (BOOL)writeTextWithSubstring:(NSString *)substring toStream:(SCStream *)stream;
- (BOOL)writeTextWithSubstring:(NSString *)substring withPath:(NSString *)path;
- (BOOL)writeTextWithoutSubstring:(NSString *)substring toStream:(SCStream *)stream;
- (BOOL)writeTextWithoutSubstring:(NSString *)substring withPath:(NSString *)path;

Text error processing

Text classes implement the tools for processing errors, which can occur in the instances of class SCStrings and his children. These tools are based on the exception class SCTextException.

This section describes the error processing algorithm and errors decriptions, which are grouping by classes, which can occur these errors:

Error processing algorithm

The basic error processing algorithm is implemented in the class SCStrings. His children extends this algorith for processing the own errors (class specific errors).

When an error is detected, the class SCStrings instance comes the following:

  1. If the instance has an assigned delegate object, then it calls a method text:didDetectException:, passing it the pointers to the erroneous class instance and error related information as a exception class SCTextException instance.
  2. If the delegate object method text:didDetectException: returns the value YES, then the class instance ignores the detected error, but stops the erroneous method execution.
  3. If the method text:didDetectException: returns the value NO or the delegate object does not assigned, then the erroneous class instance creates and throws the exception class SCTextException instance which contains the error specific data.

Strings list errors

Instances of the class SCStrings and its children classes can detect the following errors:

SCTextErrorSource = -20061, // Source object does not exists
SCTextErrorReadOnly = -20063, // Strings list is read only
SCTextErrorEmptyString = -20064, // Nil pointer instead string
SCTextErrorUnsupported = -20066, // Unsupported class detected
SCTextErrorSorter = -20070, // Incorrect strings sorter
SCTextErrorIndex = -20072, // Incorrect index
SCTextErrorIndexSet = -20074, // Incorrect index set
SCTextErrorIndexesCount = -20075, // Number of indexes does not match to number of strings

Unique strings list errors

Class SCUniqueStrings expands the parent class SCStrings by adding the following own exceptions:

SCTextErrorDuplicated = -20069, // Strings uniqueness violation

Text errors

Class SCText declares the following advanced exceptions:

SCTextErrorRange = -20073, // Incorrect strings range
SCTextErrorIntersected = -20076, // Intersected ranges detected

Text file errors

Like other children of the class SCStrings, the class SCTextFile adds its own exceptions related to various errors when performing reading and writing operations. Please note that in some cases (depending on the stream operating mode) instead of throwing the exception SCTextException possible to throw exceptions of the classes SCStreamException and SCSystemException.

SCTextErrorInputStream = -20062, // Incorrect input stream
SCTextErrorClosedStream = -20065, // Stream does not open
SCTextErrorRead = -20067, // Stream reading error
SCTextErrorEmptyPath = -20068, // Nil pointer instead the file path
SCTextErrorOutputStream = -20071, // Incorrect output stream
SCTextErrorWrite = -20077, // Stream writing error

Delegation protocol SCTextDelegate

Delegation protocol SCTextDelegate declares methods, which can be devided into the following functional groups:

For more details see the protocol SCTextDelegate description.

Text indexes

Text index is a class SCTextIndex instance, which contains information about position within the text, consisting of the string index and character index in the string. Class SCTextIndex is a support class for text unit and it does not used alone.

Class SCTextIndex declares the following properties and access methods:

@property (nonatomic, readwrite, assign) SCIndex line;
@property (nonatomic, readwrite, assign) SCIndex character;
- (void)setLine:(SCULong)line;
- (void)setCharacter:(SCULong)character;

For creating the class SCTextIndex instances you may use the following class methods and functions:

+ (instancetype)textIndexWithLine:(SCULong)line character:(SCULong)character;
+ (instancetype)textIndexWithTextIndex:(SCTextIndex *)textIndex;
+ (instancetype)textIndex;
SCTextIndex *SCMakeTextIndex( SCULong line, SCULong character);

Interaction with Data Objects

Standard data classes (NSData and NSMutableData) provides storage the raw data bytes as a single object. Some standard classes have methods for creating instances using the data objects and methods for storing instances in the data objects. SCL adds the methods for interaction with data objects into the own classes and standard classes that have not these methods.

Because class NSData instances have methods for loading and storing data in files and with URL use, SCL also adds the methods for interaction with files and URLs.

This section describes these methods and contains examples on their use:

Methods for interaction with data objects

Protocol SCDating defines the following methods for interaction with data objects:

- (instancetype)initWithData:(NSData *)data;
- (instancetype)initWithDataWrapper:(SCData *)data;
- (void)writeToData:(NSMutableData *)data;
- (NSData *)data;

Methods for interaction with files

For interaction with files protocol SCDating defines the following methods:

- (instancetype)initWithContentsOfURL:(NSURL *)url;
- (BOOL)writeToFile:(NSString *)path;

Methods for interaction with URLs

Objective-C declares the special class NSURL for working with URLs. However in some cases it is more convenient using the strings URLs instead instances of the class NSURL. Therefore protocol SCDating declares both types of methods - for using NSUSRL class instances and strings.

- (instancetype)initWithContentsOfURL:(NSURL *)url;
- (instancetype)initWithContentsOfURLString:(NSString *)urlString;
- (BOOL)writeToURL:(NSURL *)url;
- (BOOL)writeToURLString:(NSString *)urlString;

NSString extensions

Standard class NSString provides programmers a large range of features. Nevertheless, there are always those or other needs and suggestions that wants to supplement the basic functionality of the standard class.

With the power of language Objective-C it can be done without the need to create child classes that would require in the code to use instances of these subclasses. Due to categories, we can extend the functionality of an existing class, and cause the new features when using instances of the class itself, not its children.

This Programming Guide section describes the extensions provided by the category NSString(SCString), including adding support for standard features of our library (streams, data dictionaries, collections, and so on).

Consider by us added capabilities, we will in accordance with their categories the following groups:

Creating strings

Category NSString(SCString) implements the following methods for creating strings using the data from the serialized files, data dictionaries and streams:

+ (instancetype)stringWithCoder:(NSCoder *)coder;
+ (instancetype)stringWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)stringWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)stringWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)stringWithStream:(SCStream *)stream;
+ (instancetype)stringWithFileStream:(NSString *)path;

Category implements the following methods for support data objects:

+ (instancetype)stringWithData:(NSData *)data;
+ (instancetype)stringWithContentsOfFile:(NSString *)path;
+ (instancetype)stringWithContentsOfURL:(NSURL *)url;
+ (instancetype)stringWithContentsOfURLString:(NSString *)urlString;

Category NSString(SCString) implements the following class methods for creating strings:

+ (instancetype)stringWithIndexSet:(NSIndexSet *)indexSet;
+ (instancetype)stringWithCharacter:(unichar)character;
+ (instancetype)stringWithCharacter:(unichar)character length:(SCIndex)length;
+ (instancetype)stringWithLength:(SCUInteger)length;
+ (instancetype)stringWithPointer:(void *)pointer;
+ (instancetype)stringWithID:(id)object;

Initializing strings

Category NSString(SCString) declares the following additional initializing methods:

- (instancetype)initWithIndexSet:(NSIndexSet *)indexSet;
- (instancetype)initWithCharacter:(unichar)character;
- (instancetype)initWithCharacter:(unichar)character length:(SCIndex)length;
- (instancetype)initWithLength:(SCUInteger)length;
- (instancetype)initWithPointer:(void *)pointer;
- (instancetype)initWithID:(id)object;

Dividing strings and replacing substrings

Category NSString(SCString) extends the standard class NSString by implementing the large range of properties and methods for dividing strings and replacing substrings within strings. For convenience of description its this section is divided into several subsections according to the use of methods:

Strings part dropping

@property (nonatomic, readonly, assign) NSString *trimmedString;
- (NSString *)ltrim;
- (NSString *)rtrim;
- (NSString *)trim;
- (NSString *)stringWithLeftCharacters:(SCIndex)characters;
- (NSString *)stringWithRightCharacters:(SCIndex)characters;
- (NSString *)skipLeftPart:(SCIndex)characters;
- (NSString *)skipRightPart:(SCIndex)characters;

Searching substrings

- (BOOL)isCorrectRange:(NSRange)range;
- (BOOL)existsSubstring:(NSString *)substring caseInsensitive:(BOOL)caseInsensitive;
- (BOOL)existsSubstring:(NSString *)substring;
- (SCIndex)countOfSubstring:(NSString *)substring caseInsensitive:(BOOL)caseInsensitive;
- (SCIndex)countOfSubstring:(NSString *)substring;
- (SCIndex)indexOfSubstring:(NSString *)substring caseInsensitive:(BOOL)caseInsensitive;
- (SCIndex)indexOfSubstring:(NSString *)substring;
- (NSArray *)indexesOfSubstring:(NSString *)substring caseInsensitive:(BOOL)caseInsensitive;
- (NSArray *)indexesOfSubstring:(NSString *)substring;

Removing substrings

- (NSString *)stringWithDeletedSubstring:(NSString *)substring caseInsensitive:(BOOL)caseInsensitive;
- (NSString *)stringWithDeletedSubstring:(NSString *)substring;
- (NSString *)stringWithDeletedSubstringToIndex:(SCIndex)index;
- (NSString *)stringWithDeletedSubstringToRange:(NSRange)range;
- (NSString *)stringWithDeletedSubstringFromIndex:(SCIndex)index;
- (NSString *)stringWithDeletedSubstringWithRange:(NSRange)range;

Replacing substrings

- (NSString *)stringWithReplacedSubstringToIndex:(SCUInteger)index withString:(NSString *)string;
- (NSString *)stringWithReplacedSubstringFromIndex:(SCUInteger)index withString:(NSString *)string;
- (NSString *)stringWithReplacedSubstringWithRange:(NSRange)range withString:(NSString *)string;
- (NSString *)stringWithReplacedSubstring:(NSString *)substring
withString:(NSString *)string
caseInsensitive:(BOOL)caseInsensitive;
- (NSString *)stringWithReplacedSubstring:(NSString *)substring withString:(NSString *)string;

Inserting substrings

- (NSString *)stringWithInsertedString:(NSString *)string;
- (NSString *)stringWithInsertedString:(NSString *)string index:(SCUInteger)index;

String words

For operations with single words within strings the category NSString(SCString) implements the following properties and methods:

@property (nonatomic, readonly, assign) NSString *normalizedString;
@property (nonatomic, readonly, assign) SCIndex wordsCount;
@property (nonatomic, readonly, assign) NSString *firstWord;
@property (nonatomic, readonly, assign) NSString *lastWord;
@property (nonatomic, readonly, assign) NSString *endOfString;
- (NSString *)word:(SCIndex)word;

Comparing strings

Category NSString(SCString) implements the following additional comparing methods:

- (BOOL)isEqualToStrings:(NSString *)string, ...;

Expanding strings

Category NSString(SCString) declares the following expanding methods:

- (NSString *)leftExpandedStringToLength:(SCIndex)length character:(unichar)character;
- (NSString *)leftExpandedStringToLength:(SCIndex)length;
- (NSString *)leftZeroExpandedStringToLength:(SCIndex)length;
- (NSString *)rightExpandedStringToLength:(SCIndex)length character:(unichar)character;
- (NSString *)rightExpandedStringToLength:(SCIndex)length;

Additionally, category NSString(SCString) implements the class methods for creating expanded strings:

+ (instancetype)stringWithLeftExpandedString:(NSString *)string length:(SCIndex)length character:(unichar)character;
+ (instancetype)stringWithLeftExpandedString:(NSString *)string length:(SCIndex)length;
+ (instancetype)stringWithLeftZeroExpandedString:(NSString *)string length:(SCIndex)length;
+ (instancetype)stringWithRightExpandedString:(NSString *)string length:(SCIndex)length character:(unichar)character;
+ (instancetype)stringWithRightExpandedString:(NSString *)string length:(SCIndex)length;

Also category implements the following initialization methods:

- (instancetype)initWithLeftExpandedString:(NSString *)string length:(SCIndex)length character:(unichar)character;
- (instancetype)initWithLeftExpandedString:(NSString *)string length:(SCIndex)length;
- (instancetype)initWithLeftZeroExpandedString:(NSString *)string length:(SCIndex)length;
- (instancetype)initWithRightExpandedString:(NSString *)string length:(SCIndex)length character:(unichar)character;
- (instancetype)initWithRightExpandedString:(NSString *)string length:(SCIndex)length;

Adding delimiters

Category NSString(SCString) implements the following methods for separation strings on the groups of characters:

- (NSString *)stringWithSeparator:(NSString *)separator left:(SCIndex)left;
- (NSString *)stringWithSpacesLeft:(SCIndex)left;
- (NSString *)stringWithSeparator:(NSString *)separator right:(SCIndex)right;
- (NSString *)stringWithSpacesRight:(SCIndex)right;

Also category declares the class methods and initializing methods for creating strings with the separators:

+ (instancetype)stringWithString:(NSString *)string separator:(NSString *)separator left:(SCIndex)left;
+ (instancetype)stringWithString:(NSString *)string spacesLeft:(SCIndex)left;
+ (instancetype)stringWithString:(NSString *)string separator:(NSString *)separator right:(SCIndex)right;
+ (instancetype)stringWithString:(NSString *)string spacesRight:(SCIndex)right;
- (instancetype)initWithString:(NSString *)string separator:(NSString *)separator left:(SCIndex)left;
- (instancetype)initWithString:(NSString *)string spacesLeft:(SCIndex)left;
- (instancetype)initWithString:(NSString *)string separator:(NSString *)separator right:(SCIndex)right;
- (instancetype)initWithString:(NSString *)string spacesRight:(SCIndex)right;

Data types representation

This sectiond describes the category NSString(SCString) properties and methods, which communicate between number objects and numbers text representation:

Detecting digits

Category NSString(SCString) declares the following methods to determine whether a string is a character representation of the number objects.

@property (nonatomic, readonly, assign) BOOL isBinaryString;
@property (nonatomic, readonly, assign) BOOL isOctalString;
@property (nonatomic, readonly, assign) BOOL isDecimalString;
@property (nonatomic, readonly, assign) BOOL isHexadecimalString;
@property (nonatomic, readonly, assign) BOOL isBooleanString;
@property (nonatomic, readonly, assign) BOOL isFloatString;
@property (nonatomic, readonly, assign) BOOL isDoubleString;

Converting strings to numbers

Category NSString(SCString) implements the following properties, which convert the various number representations into the integer or boolean values:

@property (nonatomic, readonly, assign) SCULong binaryValue;
@property (nonatomic, readonly, assign) SCULong octalValue;
@property (nonatomic, readonly, assign) SCULong decimalValue;
@property (nonatomic, readonly, assign) SCULong hexadecimalValue;
@property (nonatomic, readonly, assign) BOOL booleanValue;

Converting numbers to strings

Category NSString(SCString) implements the following methods, which create the text representations of the various integer and boolean values:

+ (instancetype)stringWithBinaryInteger:(SCULong)integer capacity:(SCCapacity)capacity;
+ (instancetype)stringWithBinaryInteger:(SCULong)integer;
+ (instancetype)stringWithOctalInteger:(SCULong)integer;
+ (instancetype)stringWithDecimalInteger:(SCLong)integer separators:(BOOL)separators;
+ (instancetype)stringWithDecimalInteger:(SCLong)integer;
+ (instancetype)stringWithInteger:(SCLong)integer;
+ (instancetype)stringWithHexadecimalInteger:(SCULong)integer capacity:(SCCapacity)capacity;
+ (instancetype)stringWithHexadecimalInteger:(SCULong)integer;
+ (instancetype)stringWithBool:(BOOL)boolean;
+ (instancetype)stringWithFloat:(SCFloat)value;
+ (instancetype)stringWithDouble:(SCDouble)value;

Initializing number strings

Categoty NSString(SCString) declares the following methods for initializing the class instances as an integer and boolean values representation:

- (instancetype)initWithBinaryInteger:(SCULong)integer capacity:(SCCapacity)capacity;
- (instancetype)initWithBinaryInteger:(SCULong)integer;
- (instancetype)initWithOctalInteger:(SCULong)integer;
- (instancetype)initWithDecimalInteger:(SCLong)integer separators:(BOOL)separators;
- (instancetype)initWithDecimalInteger:(SCLong)integer;
- (instancetype)initWithInteger:(SCLong)integer;
- (instancetype)initWithHexadecimalInteger:(SCULong)integer capacity:(SCCapacity)capacity;
- (instancetype)initWithHexadecimalInteger:(SCULong)integer;
- (instancetype)initWithBool:(BOOL)boolean;
- (instancetype)initWithFloat:(SCFloat)value;
- (instancetype)initWithDouble:(SCDouble)value;

Reversing strings

Category NSString(SCString) implements the following reversing methods:

@property (nonatomic, readonly, assign) NSString *reversedString;
+ (instancetype)stringWithReversedString:(NSString *)string;
- (instancetype)initWithReversedString:(NSString *)string;

Other methods

In addition to described properties and methods category NSString(SCString) declares the following properties that can not be assigned to any particular group:

@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) NSString *stringWithUpperFirstLetter;

Standard classes extentions

In the previous section has been described the category NSString(SCString), which extends the functionality of the standard class NSString. Additionally many standard classes also got advanced properties and methods. In this section, we describe this classes and their extensions. This section contains the description of the extentions for the following classes:

Class NSObject extentions

Class NSObject provides the standard features of all standard classes. That's why we created the category NSObject(SCObject), through which we add support for the mechanisms of our library to all classes at once, primarily support for SCCoding, SCDictionaring, SCStreaming, SCCollectioning and SCDating protocols.

We want to note that compliance with these protocols does not guarantee that an instance of any child class will support the corresponding mechanism, beacuse for full support it is necessary to implement it by overriding the corresponding methods through the creation a category or a child class.

Serialized files support

For supporting serialized files category implements the following methods from the protocol SCCoding:

- (instancetype)initWithCoder:(NSCoder *)coder;
- (instancetype)initWithContentsOfSerializedFile:(NSString *)path;
- (void)encodeWithCoder:(NSCoder *)coder;
- (BOOL)writeContentsToSerializedFile:(NSString *)path;

Data dictionaries support

Category NSObject(SCObject) supports data dictionaries by implementing the following methods of the protocol SCDictionaring:

- (instancetype)initWithDataDictionary:(NSDictionary *)dictionary;
- (instancetype)initWithDataDictionaryFromFile:(NSString *)path;
- (void)writeToDataDictionary:(NSMutableDictionary *)dictionary;
- (void)writeToDataDictionaryFile:(NSString *)path atomically:(BOOL)atomically;
- (void)writeToDataDictionaryFile:(NSString *)path;
- (NSDictionary *)dataDictionary;

Streams support

Category NSObject(SCObject) implements the streams support by declaring the following methods of the protocol SCStreaming:

- (instancetype)initWithStream:(SCStream *)stream;
- (instancetype)initWithFileStream:(NSString *)path;
- (void)writeToStream:(SCStream *)stream;
- (void)writeToFileStream:(NSString *)path;
- (void)appendToFileStream:(NSString *)path;

Collections support

For supporting the collections the category NSObject(SCObject) implements the following methods from the protocol SCCollectioning:

- (id)copyObject;
- (SCComparisonResult)compareWithObject:(id<SCCollectioning>)object;

Interaction with data objects

Interaction with data objects, files and URLs обеспечивается provides with the following methods of the category NSObject(SCObject):

- (instancetype)initWithData:(NSData *)data;
- (instancetype)initWithContentsOfFile:(NSString *)path;
- (instancetype)initWithContentsOfURL:(NSURL *)url;
- (instancetype)initWithContentsOfURLString:(NSString *)urlString;
- (void)writeToData:(NSMutableData *)data;
- (BOOL)writeToFile:(NSString *)path;
- (BOOL)writeToURL:(NSURL *)url;
- (BOOL)writeToURLString:(NSString *)urlString;
- (NSData *)data;

Class NSNumber extensions

Class NSNumber provides the standard features for working with integers, logical values and float values. Of great importance of this class for all the Objective C has necessitated its extension both in support the SCL standard mechanisms and for entering the additional functionality.

Creating class instances

Category NSNumber(SCNumber) implements the following class methods for creating a numbers by using data from the serialized files, data dictionaries, streams and guideData:

+ (instancetype)numberWithCoder:(NSCoder *)coder;
+ (instancetype)numberWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)numberWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)numberWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)numberWithStream:(SCStream *)stream;
+ (instancetype)numberWithFileStream:(NSString *)path;
+ (instancetype)numberWithData:(NSData *)data;
+ (instancetype)numberWithContentsOfFile:(NSString *)path;
+ (instancetype)numberWithContentsOfURL:(NSURL *)url;
+ (instancetype)numberWithContentsOfURLString:(NSString *)urlString;

Category NSNumber(SCNumber) declares the following class methods for creating the class instances by using the existing other types data:

+ (instancetype)numberWithNumber:(NSNumber *)number;
+ (instancetype)numberWithByte:(SCByte)byte;
+ (instancetype)numberWithUnsignedByte:(SCUByte)byte;
+ (instancetype)numberWithUnichar:(unichar)chr;

Category NSNumber(SCNumber) implements the following class methods for creating the number by using the text representation of the source value:

+ (instancetype)numberWithBinaryString:(NSString *)string;
+ (instancetype)numberWithOctalString:(NSString *)string;
+ (instancetype)numberWithDecimalString:(NSString *)string;
+ (instancetype)numberWithHexadecimalString:(NSString *)string;
+ (instancetype)numberWithString:(NSString *)string;
+ (instancetype)numberWithBoolString:(NSString *)string;
+ (instancetype)numberWithFloatString:(NSString *)string;
+ (instancetype)numberWithDoubleString:(NSString *)string;

Initializing class instances

Category NSNumber(SCNumber) implements the following methods for initializing the class instances by using the existing other types data:

- (instancetype)initWithNumber:(NSNumber *)number;
- (instancetype)initWithByte:(SCByte)byte;
- (instancetype)initWithUnsignedByte:(SCUByte)byte;
- (instancetype)initWithUnichar:(unichar)chr;

Category NSNumber(SCNumber) declares the methods for initializing class instances using the text representation of the source data values:

- (instancetype)initWithBinaryString:(NSString *)string;
- (instancetype)initWithOctalString:(NSString *)string;
- (instancetype)initWithDecimalString:(NSString *)string;
- (instancetype)initWithHexadecimalString:(NSString *)string;
- (instancetype)initWithString:(NSString *)string;
- (instancetype)initWithBoolString:(NSString *)string;
- (instancetype)initWithFloatString:(NSString *)string;
- (instancetype)initWithDoubleString:(NSString *)string;

Class instance properties

Category NSNumber(SCNumber) declares the following properties:

@property (nonatomic, readonly, assign) SCByte byteValue;
@property (nonatomic, readonly, assign) SCUByte unsignedByteValue;
@property (nonatomic, readonly, assign) unichar unicharValue;

Also the category NSNumber(SCNumber) implements the properties for access to the text representations of the numbers:

@property (nonatomic, readonly, assign) NSString *binaryString;
@property (nonatomic, readonly, assign) NSString *octalString;
@property (nonatomic, readonly, assign) NSString *decimalString;
@property (nonatomic, readonly, assign) NSString *string;
@property (nonatomic, readonly, assign) NSString *hexadecimalString;
@property (nonatomic, readonly, assign) NSString *boolString;
@property (nonatomic, readonly, assign) NSString *floatString;
@property (nonatomic, readonly, assign) NSString *doubleString;

Type detection

Class NSNumber instance can contain different types of data, which is determined during the instance creating. For information about the type of the number the category NSNumber(SCNumber) uses the property type:

@property (nonatomic, readonly, assign) SCStandardType type;

Property returns the data type ID. See details in the section Standard types.

NSNumber *number = [NSNumber numberWithShort:1909];
if ( number.type == SCTypeShort) NSLog( @"number is signed short");
2016-09-14 17:33:22.302 libtest[5377:337635] number is signed short

Comparing class instances

For comparison the numbers with the other data type values category NSNumber(SCNumber) implements the following comparing methods:

- (BOOL)isEqualToByte:(SCByte)value;
- (BOOL)isEqualToUnsignedByte:(SCUByte)value;
- (BOOL)isEqualToShort:(SCShort)value;
- (BOOL)isEqualToUnsignedShort:(SCUShort)value;
- (BOOL)isEqualToInteger:(SCInteger)value;
- (BOOL)isEqualToUnsignedInteger:(SCUInteger)value;
- (BOOL)isEqualToLongLong:(SCLong)value;
- (BOOL)isEqualToUnsignedLongLong:(SCULong)value;
- (BOOL)isEqualToChar:(char)value;
- (BOOL)isEqualToUnichar:(unichar)value;
- (BOOL)isEqualToBool:(BOOL)value;
- (BOOL)isEqualToFloat:(SCFloat)value;
- (BOOL)isEqualToDouble:(SCDouble)value;

For comparison the numbers with the its text representations (both as a strings and classic C strings) category NSNumber(SCNumber) declares the following methods:

- (BOOL)isEqualToBinaryString:(NSString *)string;
- (BOOL)isEqualToOctalString:(NSString *)string;
- (BOOL)isEqualToDecimalString:(NSString *)string;
- (BOOL)isEqualToHexadecimalString:(NSString *)string;
- (BOOL)isEqualToString:(NSString *)string;
- (BOOL)isEqualToBoolString:(NSString *)string;
- (BOOL)isEqualToFloatString:(NSString *)string;
- (BOOL)isEqualToDoubleString:(NSString *)string;

Error processing

When working with serialized files, data dictionaries, streams and collections we may encounter a situation where instead of a number object is detected an instance of another class. To indicate this situation we have the exception class SCNumberException, which provide the error SCL-20011.

Class NSNull extensions

CategoryNSNull(SCNull) does not add into the class NSNull no additional features, instead the class methods for creating class instances by using a serialized files, data dictionaries, streams and data objects:

+ (instancetype)nullWithCoder:(NSCoder *)coder;
+ (instancetype)nullWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)nullWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)nullWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)nullWithStream:(SCStream *)stream;
+ (instancetype)nullWithFileStream:(NSString *)path;
+ (instancetype)nullWithData:(NSData *)data;
+ (instancetype)nullWithContentsOfFile:(NSString *)path;
+ (instancetype)nullWithContentsOfURL:(NSURL *)url;
+ (instancetype)nullWithContentsOfURLString:(NSString *)urlString;

Class NSDate extensions

Category NSDate(SCDate) implements into the class NSDate methods for creating dates by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)dateWithCoder:(NSCoder *)coder;
+ (instancetype)dateWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)dateWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)dateWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)dateWithStream:(SCStream *)stream;
+ (instancetype)dateWithFileStream:(NSString *)path;
+ (instancetype)dateWithData:(NSData *)data;
+ (instancetype)dateWithContentsOfFile:(NSString *)path;
+ (instancetype)dateWithContentsOfURL:(NSURL *)url;
+ (instancetype)dateWithContentsOfURLString:(NSString *)urlString;

Class NSArray extensions

Categoy NSArray(SCArray) adds into the standard class NSArray features for support the protocols SCCollection and SCIndexedCollection:

Creating arrays

Category NSArray(SCArray) declares the following class methods for creating arrays with data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)arrayWithCoder:(NSCoder *)coder;
+ (instancetype)arrayWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)arrayWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)arrayWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)arrayWithStream:(SCStream *)stream;
+ (instancetype)arrayWithFileStream:(NSString *)path;
+ (instancetype)arrayWithData:(NSData *)data;
+ (instancetype)arrayWithContentsOfURLString:(NSString *)urlString;

Category NSArray(SCArray) implements the following additional methods for creating arrays:

+ (instancetype)arrayWithCollection:(id<SCCollection>)collection;

Initializing arrays

Category NSArray(SCArray) declares the following additional initializing methods:

- (instancetype)initWithCollection:(id<SCCollection>)collection;

Protocol SCCollection implementation

The most popular properties of protocol SCCollection in the class NSArray are the following properties implemented in the category NSArray(SCArray):

@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL readOnly;
@property (nonatomic, readonly, retain) id<SCCollectionDelegate> delegate;

Also category NSArray(SCArray) implements the following methods for collection type detection from the protocol SCCollection:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Property collectionType of objects of classes NSArray and NSMutableArray always returns the value SCCollectionFoundationArray.

For the classes NSArray and NSMutableArray instances the value YES return the following collection type detection properties:

Other type detection properties always return the value NO.

Searching array objects

Category NSArray(SCArray) implements the following protocol SCCollection properties and methods for objects searching:

@property (nonatomic, readonly, assign) SCIndex indexOfLastObject;
- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Converting arrays

Category NSArray(SCArray) implements the following converting properties of the protocol SCCollection:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, assign) NSArray *foundationArray;
@property (nonatomic, readonly, assign) NSSet *foundationSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, assign) NSDictionary *foundationDictionary;
@property (nonatomic, readonly, assign) NSArray *reversedArray;

Sorting arrays

Category NSArray(SCArray) implements the following sorting properties and methods of the protocol SCCollection:

@property (nonatomic, readonly, assign) NSArray *ascendingSortedArray;
@property (nonatomic, readonly, assign) NSArray *descendingSortedArray;
@property (nonatomic, readonly, assign) NSArray *sortedArray;
- (NSArray *)ascendingSortedArrayWithSorter:(id<SCSorter>)sorter;
- (NSArray *)descendingSortedArrayWithSorter:(id<SCSorter>)sorter;
- (NSArray *)sortedArrayWithSorter:(id<SCSorter>)sorter;

Also category implements the methods for creating and initializing the sorted arrays using existing collections of any supported type:

+ (instancetype)arrayWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)arrayWithAscendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)arrayWithDescendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)arrayWithSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection;

Comparing arrays

Additionally to the standard comparing methods the category NSArray(SCArray) implements the following new methods:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Deriving new arrays

Category NSArray(SCArray) declares the following methods for deriving new arrays that contains objects from the receiving arrays:

- (NSArray *)arrayByAddingObjects:(id)object, ... NS_REQUIRES_NIL_TERMINATION;
- (NSArray *)arrayByAddingArray:(NSArray *)array;
- (NSArray *)arrayByAddingCollection:(id<SCCollection>)collection;

Class NSMutableArray extensions

Category NSMutableArray(SCMutableArray) extends the class NSMutableArray by implementing the methods of the protocols SCMutableCollection and SCMutableIndexedCollection. Also the class NSMutableArray inherits all extensions from the category NSArray(SCArray).

Copying arrays

Category NSMutableArray(SCMutableArray) implements the following copying methods of the protocol SCMutableCollection:

- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

Additionally, category NSMutableArray(SCMutableArray) implements the methods for copying into the array the sorted content of the existing collections of any supported type:

- (void)setAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setAscendingSortedCollection:(id<SCCollection>)collection;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection;
- (void)setSortedCollection:(id<SCCollection>)collection;

Adding objects to array

Category NSMutableArray(SCMutableArray) implements the following adding methods:

- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;

Also the category NSMutableArray(SCMutableArray) declares the method addArray: that adds into the receiving array objects from the specified array:

- (void)addArray:(NSArray *)array;
NSMutableArray *array = [NSMutableArray arrayWithArray:@[ @200, @600, @800, @400]];
[array addArray:@[ @100, @500]];
NSLog( @"%@", array);
2017-06-08 09:59:42.981230+0300 libtest[84484:5850646] (
200,
600,
800,
400,
100,
500
)

Removing objects from array

Category NSMutableArray(SCMutableArray) implements the following removing methods of the protocol SCMutableCollection:

- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

Replacing objects

Category NSMutableArray(SCMutableArray) implements the following objects replacing methods of the protocol SCMutableCollection:

- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withCollection:(id<SCCollection>)collection;
- (void)replaceObjectsInRange:(NSRange)range withObjects:(id<SCCollectioning>)object, ...;
- (void)replaceObjectsInRange:(NSRange)range withCollection:(id<SCCollection>)collection;

Sorting arrays

Category NSMutableArray(SCMutableArray) declares the following sorting methods:

- (void)sortAscendingWithSorter:(id<SCSorter>)sorter;
- (void)sortDescendingWithSorter:(id<SCSorter>)sorter;
- (void)sortWithSorter:(id<SCSorter>)sorter;
- (void)sortAscending;
- (void)sortDescending;
- (void)sort;

Advanced methods

Also category NSMutableArray(SCMutableArray) implements the following additional methods:

- (void)copyObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)moveObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;
- (void)reverse;

Class NSSet extensions

Category NSSet(SCSet) appends into the standard class NSSet support of the serialized files, data dictionaries and streams. Also the category implements the methods for compatibility with the collections and primarily with the class SCSet:

Creating sets

Category NSSet(SCSet) declares the following methods for creating sets with data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)setWithCoder:(NSCoder *)coder;
+ (instancetype)setWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)setWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)setWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)setWithStream:(SCStream *)stream;
+ (instancetype)setWithFileStream:(NSString *)path;
+ (instancetype)setWithData:(NSData *)data;
+ (instancetype)setWithContentsOfFile:(NSString *)path;
+ (instancetype)setWithContentsOfURL:(NSURL *)url;
+ (instancetype)setWithContentsOfURLString:(NSString *)urlString;

Category implements the following class methods for creating class instances:

+ (instancetype)setWithCollection:(id<SCCollection>)collection;

Initializing sets

Category declares the following additional initializing methods:

- (instancetype)initWithCollection:(id<SCCollection>)collection;

Protocol SCCollection implementation

To comply with the SCCollection protocol the category NSSet(SCSet) implements the following properties:

@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL readOnly;
@property (nonatomic, readonly, retain) id<SCCollectionDelegate> delegate;

Also category implements the collection type detection properties from the protocol SCCollection:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Property collectionType of objects of classes SCSet and NSMutableSet always returns the value SCCollectionFoundationSet.

For the classes NSSet and NSMutableSet the value YES returns methods isCollection, isFoundationCollection, isSet and isFoundationSet. Other collection type detection methods return the value NO.

Searching set objects

Category NSSet(SCSet) implements the following searching methods from the protocol SCCollection:

- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Converting sets

Category declares the following converting properties:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, assign) NSArray *foundationArray;
@property (nonatomic, readonly, assign) NSSet *foundationSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, assign) NSDictionary *foundationDictionary;

Comparing sets

Additionally to the standard comparing methods the category NSSet(SCSet) implements the following new methods:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Deriving new sets

Category NSSet(SCSet) implements the following methods for deriving new sets by using objects from existing sets:

- (NSSet *)setByAddingObjects:(id)object, ...;
- (NSSet *)setByAddingArray:(NSArray *)array;
- (NSSet *)setByAddingSet:(NSSet *)set;
- (NSSet *)setByAddingCollection:(id<SCCollection>)collection;

Class NSMutableSet extensions

Category NSMutableSet(SCMutableSet) extends the class NSMutableSet functions by implements the methods of the protocol SCMutableCollection:

Copying sets

Category implements the following copying methods from the protocol SCMutableCollection:

- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

Adding objects to set

Category NSMutableSet(SCMutableSet) implements the following methods of the procotol SCMutableCollection for adding objects into the sets:

- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;

Also the category declares the following methods for adding objects:

- (void)addArray:(NSArray *)array;
- (void)addObjectsFromSet:(NSSet *)set;
- (void)addSet:(NSSet *)set;

Removing objects from set

Category implements the following methods for removing objects from set:

- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

Class NSOrderedSet extensions

Category NSOrderedSet(SCOrderedSet) implements in the ordered sets the methods and properties from the protocols SCCollection and SCIndexedCollection:

Creating ordered sets

Category declares the following methods for creating an ordered sets with data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)orderedSetWithCoder:(NSCoder *)coder;
+ (instancetype)orderedSetWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)orderedSetWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)orderedSetWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)orderedSetWithStream:(SCStream *)stream;
+ (instancetype)orderedSetWithFileStream:(NSString *)path;
+ (instancetype)orderedSetWithData:(NSData *)data;
+ (instancetype)orderedSetWithContentsOfFile:(NSString *)path;
+ (instancetype)orderedSetWithContentsOfURL:(NSURL *)url;
+ (instancetype)orderedSetWithContentsOfURLString:(NSString *)urlString;

Also the caregory implements the following methods for creating a class instances:

+ (instancetype)orderedSetWithCollection:(id<SCCollection>)collection;

Initializing ordered sets

- (instancetype)initWithCollection:(id<SCCollection>)collection;

Protocol SCCollection implementation

Category NSOrderedSet(SCOrderedSet) implements the following properties of the SCCollection protocol:

@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL readOnly;
@property (nonatomic, readonly, retain) id<SCCollectionDelegate> delegate;

The following properties of the protocol SCCollection and category NSOrderedSet(SCOrderedSet) determines the receiving collection type:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Property collectionType of objects of classes SCOrderedSet and NSMutableOrderedSet always returns the value SCCollectionFoundationOrderedSet.

The methods isCollection, isFoundationCollection, isOrderedSet and isFoundationOrderedSet for class NSOrderedSet instances always return the value YES.

Searching ordered set objects

Category NSOrderedSet(SCOrderedSet) implements the following searching properties of the protocol SCCollection:

@property (nonatomic, readonly, assign) SCIndex indexOfLastObject;
- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Converting ordered sets

Category NSOrderedSet(SCOrderedSet) supports operations of converting the ordered sets into the collections of any supported type:

@property (nonatomic, readonly, assign) SCArray *libraryArray;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, assign) NSArray *foundationArray;
@property (nonatomic, readonly, assign) NSSet *foundationSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, assign) NSDictionary *foundationDictionary;

Sorting ordered sets

Category NSOrderedSet(SCOrderedSet) implements properties and methods thatreturn the sorted ordered sets:

@property (nonatomic, readonly, assign) NSOrderedSet *ascendingSortedOrderedSet;
@property (nonatomic, readonly, assign) NSOrderedSet *descendingSortedOrderedSet;
@property (nonatomic, readonly, assign) NSOrderedSet *sortedOrderedSet;
- (NSOrderedSet *)ascendingSortedOrderedSetWithSorter:(id<SCSorter>)sorter;
- (NSOrderedSet *)descendingSortedOrderedSetWithSorter:(id<SCSorter>)sorter;
- (NSOrderedSet *)sortedOrderedSetWithSorter:(id<SCSorter>)sorter;

Also category declares the methods for creating and initializing sorted ordered sets by using the existing collections of any supported type:

+ (instancetype)orderedSetWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
+ (instancetype)orderedSetWithAscendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)orderedSetWithDescendingSortedCollection:(id<SCCollection>)collection;
+ (instancetype)orderedSetWithSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (instancetype)initWithAscendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithDescendingSortedCollection:(id<SCCollection>)collection;
- (instancetype)initWithSortedCollection:(id<SCCollection>)collection;

Comparing ordered sets

Additionally to the standard comparing methods the category NSOrderedSet(SCOrderedSet) implements the following new methods:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Deriving new ordered sets

Category NSOrderedSet(SCOrderedSet) declares the following methods for deriving new ordered sets:

- (NSOrderedSet *)orderedSetByAddingObject:(id)object;
- (NSOrderedSet *)orderedSetByAddingObjects:(id)object, ... NS_REQUIRES_NIL_TERMINATION;
- (NSOrderedSet *)orderedSetByAddingCollection:(id<SCCollection>)collection;
- (NSOrderedSet *)orderedSetByAddingArray:(NSArray *)array;
- (NSOrderedSet *)orderedSetByAddingSet:(NSSet *)set;
- (NSOrderedSet *)orderedSetByAddingOrderedSet:(NSOrderedSet *)orderedSet;

Advanced methods

Additionally, the category NSOrderedSet(SCOrderedSet) implements the properties not related to any functional group:

@property (nonatomic, readonly, assign) NSArray* allObjects;

Class NSMutableOrderedSet extensions

Category NSMutableOrderedSet(SCMutableOrderedSet) implements into the mutable ordered sets the protocols SCMutableCollection and SCMutableIndexedCollection functionality:

Copying ordered sets

To support the copying methods of the protocol SCMutableCollection category NSMutableOrderedSet(SCMutableOrderedSet) implements these methods in the class NSMutableOrderedSet:

- (void)setSet:(NSSet *)set;
- (void)setOrderedSet:(NSOrderedSet *)orderedSet;
- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

Adding objects to ordered set

To comply with the protocol SCMutableCollection category NSMutableOrderedSet(SCMutableOrderedSet) implements the following methods for adding objects into the ordered set:

- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;
- (void)addArray:(NSArray *)array;
- (void)addObjectsFromSet:(NSSet *)set;
- (void)addSet:(NSSet *)set;
- (void)addObjectsFromOrderedSet:(NSOrderedSet *)orderedSet;
- (void)addOrderedSet:(NSOrderedSet *)orderedSet;

Removing objects from ordered set

Category implements the following removing methods of the protocol SCMutableCollection:

- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

Replacing objects

Category NSMutableOrderedSet(SCMutableOrderedSet) implements the following methods for replacing objects within the ordered set:

- (void)replaceObjectsAtIndexes:(NSIndexSet *)indexes withCollection:(id<SCCollection>)collection;

Sorting ordered sets

Sort of ordered set objects is performed by the following methods of the category:

- (void)sortAscendingWithSorter:(id<SCSorter>)sorter;
- (void)sortDescendingWithSorter:(id<SCSorter>)sorter;
- (void)sortWithSorter:(id<SCSorter>)sorter;
- (void)sortAscending;
- (void)sortDescending;
- (void)sort;

Additionally, the category implements the methods for replacing the receiving ordered set content of the sorted content of the specified existing collections of any supported type:

- (void)setAscendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setSortedCollection:(id<SCCollection>)collection sorter:(id<SCSorter>)sorter;
- (void)setAscendingSortedCollection:(id<SCCollection>)collection;
- (void)setDescendingSortedCollection:(id<SCCollection>)collection;
- (void)setSortedCollection:(id<SCCollection>)collection;

Advanced methods

Category NSMutableOrderedSet(SCMutableOrderedSet) implements the following advanced methods:

- (void)moveObjectAtIndex:(SCIndex)index toIndex:(SCIndex)destination;

Class NSDictionary extensions

Category NSDictionary(SCDictionary) extends the standard class NSDictionary by adding the support of the protocol SCCollection. These extensions not only added the new functionality but also provide class compatibility with the SCL:

Creating dictionaries

Category implements the following methods for creating a dictionaries with data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)dictionaryWithCoder:(NSCoder *)coder;
+ (instancetype)dictionaryWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)dictionaryWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)dictionaryWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)dictionaryWithStream:(SCStream *)stream;
+ (instancetype)dictionaryWithFileStream:(NSString *)path;
+ (instancetype)dictionaryWithData:(NSData *)data;
+ (instancetype)dictionaryWithContentsOfURLString:(NSString *)urlString;

Category declares the following methods for creating dictionaries:

+ (instancetype)dictionaryWithCollection:(id<SCCollection>)collection;

Initializing dictionaries

Category NSDictionary(SCDictionary) declares the following initialization methods:

- (instancetype)initWithCollection:(id<SCCollection>)collection;

Protocol SCCollection implementation

Category implements the following properties of the SCCollection protocol:

@property (nonatomic, readonly, retain) NSString *name;
@property (nonatomic, readonly, assign) BOOL empty;
@property (nonatomic, readonly, assign) BOOL readOnly;
@property (nonatomic, readonly, retain) id<SCCollectionDelegate> delegate;

Also category implements the collection type detection properties:

@property (nonatomic, readonly, assign) SCCollectionType collectionType;
@property (nonatomic, readonly, assign) BOOL isCollection;
@property (nonatomic, readonly, assign) BOOL isLibraryCollection;
@property (nonatomic, readonly, assign) BOOL isFoundationCollection;
@property (nonatomic, readonly, assign) BOOL isArray;
@property (nonatomic, readonly, assign) BOOL isLibraryArray;
@property (nonatomic, readonly, assign) BOOL isFoundationArray;
@property (nonatomic, readonly, assign) BOOL isSet;
@property (nonatomic, readonly, assign) BOOL isLibrarySet;
@property (nonatomic, readonly, assign) BOOL isFoundationSet;
@property (nonatomic, readonly, assign) BOOL isOrderedSet;
@property (nonatomic, readonly, assign) BOOL isLibraryOrderedSet;
@property (nonatomic, readonly, assign) BOOL isFoundationOrderedSet;
@property (nonatomic, readonly, assign) BOOL isDictionary;
@property (nonatomic, readonly, assign) BOOL isLibraryDictionary;
@property (nonatomic, readonly, assign) BOOL isFoundationDictionary;
@property (nonatomic, readonly, assign) BOOL isStack;
@property (nonatomic, readonly, assign) BOOL isQueue;
@property (nonatomic, readonly, assign) BOOL isList;
@property (nonatomic, readonly, assign) BOOL isSortable;

Property collectionType of objects of classes NSDictionary and NSMutableDictionary always returns the value SCCollectionFoundationDictionary.

For the instances of the classes NSDictionary and NSMutableDictionary return the YES value the methods isCollection, isFoundationCollection, isDictionary and isFoundationDictionary. Other methods return the NO value.

Searching dictionary objects and keys

Category declares the following object search methods of the protocol <SCCollection>:

- (BOOL)containsObject:(id<SCCollectioning>)object;
- (BOOL)containsObjects:(id<SCCollectioning>)object, ...;
- (BOOL)containsCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyObject:(id<SCCollectioning>)object, ...;
- (BOOL)containsAnyObjectFromCollection:(id<SCCollection>)collection;

Also the category NSDictionary(SCDictionary) implements the following methods for finding keys:

- (BOOL)containsKey:(id)key;
- (BOOL)containsKeys:(id)key, ... NS_REQUIRES_NIL_TERMINATION;
- (BOOL)containsKeysFromCollection:(id<SCCollection>)collection;
- (BOOL)containsAnyKey:(id)key, ... NS_REQUIRES_NIL_TERMINATION;
- (BOOL)containsAnyKeyFromCollection:(id<SCCollection>)collection;

Accessing Keys and Values

Method getObjectForKey: creates and returns an object for a given key that stores in a data dictionaries format, that saves the type of a key and object.

Converting dictionaries

Category implements the following converting properties:

@property (nonatomic, readonly, assign) SCArray *array;
@property (nonatomic, readonly, assign) SCSet *set;
@property (nonatomic, readonly, assign) SCOrderedSet *orderedSet;
@property (nonatomic, readonly, assign) SCDictionary *dictionary;
@property (nonatomic, readonly, assign) SCStack *stack;
@property (nonatomic, readonly, assign) SCQueue *queue;
@property (nonatomic, readonly, assign) SCUnidirectionalList *unidirectionalList;
@property (nonatomic, readonly, assign) SCBidirectionalList *bidirectionalList;
@property (nonatomic, readonly, assign) NSArray *foundationArray;
@property (nonatomic, readonly, assign) NSSet *foundationSet;
@property (nonatomic, readonly, assign) NSOrderedSet *foundationOrderedSet;
@property (nonatomic, readonly, assign) NSDictionary *foundationDictionary;

Comparing dictionaries

Additionally to the standard comparing methods the category NSDictionary(SCDictionary) implements the following new methods:

- (BOOL)isEqualToCollection:(id<SCCollection>)collection;

Deriving new dictionaries

Category NSDictionary(SCDictionary) implements the following methods for deriving new dictionaries by using existing dictionaries:

- (NSDictionary *)dictionaryByAddingObject:(id)object forKey:(id)key;
- (NSDictionary *)dictionaryByAddingObject:(id)object;
- (NSDictionary *)dictionaryByAddingObjects:(NSArray *)objects forKeys:(NSArray *)keys;
- (NSDictionary *)dictionaryByAddingObjects:(id)object, ...;
- (NSDictionary *)dictionaryByAddingObjectsAndKeys:(id)object, ...;
- (NSDictionary *)dictionaryByAddingCollection:(id<SCCollection>)collection;
- (NSDictionary *)dictionaryByAddingObjectsFromArray:(NSArray *)array;
- (NSDictionary *)dictionaryByAddingArray:(NSArray *)array;
- (NSDictionary *)dictionaryByAddingEntriesFromDictionary:(NSDictionary *)dictionary;
- (NSDictionary *)dictionaryByAddingDictionary:(NSDictionary *)dictionary;

Class NSMutableDictionary extensions

Category NSMutableDictionary(SCMutableDictionary) extends the class NSMutableDictionary by adding the functionality of the protocol SCMutableCollection:

Copying dictionaries

Category implements the following protocol SCMutableCollection methods:

- (void)setCollection:(id<SCCollection>)collection;
- (void)setObject:(id<SCCollectioning>)object;
- (void)setObjects:(id<SCCollectioning>)object, ...;

Adding objects to dictionary

Category implements the following adding methods of the SCMutableCollection protocol. These methods generate keys for added objects automatically, except some situations of the method addCollection:.

- (void)addObject:(id<SCCollectioning>)object;
- (void)addObjects:(id<SCCollectioning>)object, ...;
- (void)addCollection:(id<SCCollection>)collection;
- (void)addObjectsFromArray:(NSArray *)array;
- (void)addArray:(NSArray *)array;
- (void)addDictionary:(NSDictionary *)dictionary;
- (void)addObjects:(id<SCCollection>)objects forKeys:(id<SCCollection>)keys;
- (void)addObjectsAndKeys:(id)object, ...;
- (void)addObject:(id<SCDictionaring>)object forKey:(NSString *)key;

Removing objects from dictionary

For removing objects from the dictionaries category NSMutableDictionary(SCMutableDictionary) implements the following methods of the protocol SCMutableCollection:

- (void)removeObjectsWithClass:(Class)oclass;
- (void)removeObjectsWithClassName:(NSString *)name;
- (void)removeCollection:(id<SCCollection>)collection;
- (void)removeObject:(id<SCCollectioning>)object;
- (void)removeObjects:(id<SCCollectioning>)object, ...;

Class NSData extensions

Category NSData(SCData) implements into the class NSData methods for creating a data objects by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)dataWithCoder:(NSCoder *)coder;
+ (instancetype)dataWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)dataWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)dataWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)dataWithStream:(SCStream *)stream;
+ (instancetype)dataWithFileStream:(NSString *)path;
+ (instancetype)dataWithContentsOfURLString:(NSString *)urlString;

Class NSIndexSet extentions

Category NSIndexSet(SCIndexSet) implements in the class NSIndexSet methods for creating an index sets by using the data from the serialized files, data dictionaries, streams and data objects:

+ (instancetype)indexSetWithCoder:(NSCoder *)coder;
+ (instancetype)indexSetWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)indexSetWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)indexSetWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)indexSetWithStream:(SCStream *)stream;
+ (instancetype)indexSetWithFileStream:(NSString *)path;
+ (instancetype)indexSetWithData:(NSData *)data;
+ (instancetype)indexSetWithContentsOfFile:(NSString *)path;
+ (instancetype)indexSetWithContentsOfURL:(NSURL *)url;
+ (instancetype)indexSetWithContentsOfURLString:(NSString *)urlString;

Also category declares the following methods for creating index sets:

+ (instancetype)indexSetWithIndexSet:(NSIndexSet *)indexSet;

Classes and categories for macOS

Warning
Classes and categories described in this section are supported only in the operation system macOS and a limited support with the GNUstep.

Section desctibes the following components:

Category NSButton(SCButton)

Category NSButton(SCButton) extends the standard class NSButton by declaring the following property:

@property (nonatomic, readwrite, assign) BOOL boolState;

This property allows to set the state of the interface button by using the boolean value:

Category NSAlert(SCAlert)

The standard class NSAlert implements the interface for using the alerts with the various messages and buttons for the request the user response. The next image contains the sample of the alert, which is required the user response before the deleting action:

sample_11_01_en.png

Although its capabilities, class NSAlert to operate it requires a large number of parameters, which makes this class is not the most comfortable to use. To solve this issue, we developed our extentions as a category NSAlert(SCAlert). Thid section details considering our additions to the class:

Alert styles

Opeationg system macOS defines the following alert styles:

NSAlertStyleCritical - critical alert with the error message
NSAlertStyleWarning - alert with the warning message
NSAlertStyleInformational - alert with the informational text

Creating and initializing alerts

Category NSAlert(SCAlert) declares the following method for creating a generic alert:

+ (instancetype)alertWithStyle:(NSAlertStyle)style
message:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;

A method returns the pointer to the alert with the specified style, message text, informative text and a comma-separated list of the button titles, ending with nil pointer. For creating the sample alert from the previous section You can use the following code:

NSAlert *alert = [NSAlert criticalAlertWithMessage:@"Confirm the deleting of the selected user:"
text:@"John Smith"
buttons:@"Yes", @"No", @"Help", nil];
[alert runModal];

Also the category NSAlert(SCAlert) declares the following methods for creating an alerts:

+ (instancetype)criticalAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (instancetype)criticalAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (instancetype)criticalAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (instancetype)warningAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (instancetype)warningAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (instancetype)warningAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (instancetype)alertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (instancetype)alertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (instancetype)alertWithMessage:(NSString *)message text:(NSString *)text;

Also the category NSAlert(SCAlert) implements the following initialization methods:

- (instancetype)initWithStyle:(NSAlertStyle)style
message:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
- (instancetype)initCriticalAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
- (instancetype)initCriticalAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
- (instancetype)initCriticalAlertWithMessage:(NSString *)message text:(NSString *)text;
- (instancetype)initWarningAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
- (instancetype)initWarningAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
- (instancetype)initWarningAlertWithMessage:(NSString *)message text:(NSString *)text;
- (instancetype)initWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
- (instancetype)initWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
- (instancetype)initWithMessage:(NSString *)message text:(NSString *)text;

Running alerts

A created alerts can be show on the screen by using the method NSAlert::runModal, but the category NSAlert(SCAlert) declares the methods that perform the following actions:

These methods are declares in the category NSAlert(SCAlert) as follows:

+ (NSInteger)runAlertWithStyle:(NSAlertStyle)style
message:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (NSInteger)runCriticalAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (NSInteger)runCriticalAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (NSInteger)runCriticalAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (NSInteger)runWarningAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (NSInteger)runWarningAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (NSInteger)runWarningAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (NSInteger)runAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (NSInteger)runAlertWithMessage:(NSString *)message text:(NSString *)text button:(NSString *)button;
+ (NSInteger)runAlertWithMessage:(NSString *)message text:(NSString *)text;

Details of the codes returned by these methods see in the section Alert buttons of the Programming Guide.

Request confirmation

In the previous section we looked at methods that show the alerts on the screen. In most cases, alerts is used for the doing one of the following:

Previously examined methods can be used to solve both of these tasks. However in the second case often all we are waiting for the user to select one of two options - to do or not to do a certain action, for example, delete or do not delete some entry in the database.

For in these simple cases, do not add to the application checks the user selected the button code we created in the category NSAlert(SCAlert) series of confirmation request methods, most important of which is the method:

+ (BOOL)confirmAlertWithStyle:(NSAlertStyle)style
message:(NSString *)message
text:(NSString *)text
confirm:(NSInteger)confirm
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;

This method creates and displays the alert with the specified style, message text, informative text and a list of the button titles. Once the user clicks one of the buttons, the method compares the code of the button with the code, which is specified by the parameter confirm. If the codes match, the method returns the value of YES, otherwise it returns a value NO.

Also the vategory NSAlert(SCAlert) declares the following additional methods for running the confirmation requests:

+ (BOOL)confirmCriticalAlertWithMessage:(NSString *)message
text:(NSString *)text
confirm:(NSInteger)confirm
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (BOOL)confirmCriticalAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (BOOL)confirmWarningAlertWithMessage:(NSString *)message
text:(NSString *)text
confirm:(NSInteger)confirm
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (BOOL)confirmWarningAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (BOOL)confirmAlertWithMessage:(NSString *)message
text:(NSString *)text
confirm:(NSInteger)confirm
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;
+ (BOOL)confirmAlertWithMessage:(NSString *)message
text:(NSString *)text
buttons:(NSString *)button, ... NS_REQUIRES_NIL_TERMINATION;

Please note that if the method does not have an option confirm, this means that the first added button is used as a confirm button. Learn more about working with the buttons and their codes can be found in the next section.

Additionally a category NSAlert(SCAlert) implements the simple confirmation request methods:

+ (BOOL)confirmYesNoAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (BOOL)confirmNoYesAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (BOOL)confirmOKCancelAlertWithMessage:(NSString *)message text:(NSString *)text;
+ (BOOL)confirmCancelOKAlertWithMessage:(NSString *)message text:(NSString *)text;

Alert buttons

Class NSAlert declares the method addButtonWithTitle: which adds into the existing alert the new button to the left of the previously added. This algorithm is also using by the methods from the category NSAlert(SCAlert) - if You use the method which allows defining a several buttons, than the method displays the first button on a right of an alert, the next button is placed to the left of the previous button and so on.

Method NSAlert::runModal returns the code of the user pressed button, which is defines by using the next formula: 1000 + id, where the argument id defines the order number of the button from right to left. For the rightmost button id is set to 0. Thus, the rightmost button returns the code 1000, the next button returns the code 1001 and so on.

Apple defines for the class NSAlert the following predefined constants of the buttons return codes:

NSAlertFirstButtonReturn = 1000 // A rightmost button
NSAlertSecondButtonReturn = 1001 // The second button on the right of the alert
NSAlertThirdButtonReturn = 1002 // The third button on the right of the alert

However, you can use your own constants for the first three buttons, as well as for all the others, you will be added to your alert if necessary.

Exceptions

Samond Classes Library uses the exception classes hierarchy (with parent class SCException) for the efficient handling of possible errors. This Programming Guide section describes in detail how on common points of all exception classes, and about the features of certain library errors.

The library declares the following types of exceptions:

Exception classes hierarchy

exceptions.png

Category NSException(SCException)

Category NSException(SCException) adds into the class SCException the support of serialized files, data dictionaries, streams, data objects and collections:

+ (instancetype)exceptionWithCoder:(NSCoder *)coder;
+ (instancetype)exceptionWithContentsOfSerializedFile:(NSString *)path;
+ (instancetype)exceptionWithDataDictionary:(NSDictionary *)dictionary;
+ (instancetype)exceptionWithDataDictionaryFromFile:(NSString *)path;
+ (instancetype)exceptionWithStream:(SCStream *)stream;
+ (instancetype)exceptionWithFileStream:(NSString *)path;
+ (instancetype)exceptionWithData:(NSData *)data;
+ (instancetype)exceptionWithContentsOfFile:(NSString *)path;
+ (instancetype)exceptionWithContentsOfURL:(NSURL *)url;
+ (instancetype)exceptionWithContentsOfURLString:(NSString *)urlString;

Class SCException

Class SCException is a parent class of all other library exception classes. It not only defines a class hierarchy, it also defines for other classes some concepts and tools such as error codes and error identifiers:

Error codes and IDs

Each library error has its own code and ID.

Error code is a negative number starting from the value -20000 and below. This choice is related to the error codes that are allocated for the ORACLE database user errors. In fact the system itself is the formation of codes and identifiers of error is taken by us from ORACLE.

For getting the error code you can use the property code of the class SCException instance:

@property (nonatomic, readonly, assign) SCInteger code;
@try {
SCArray *array = [SCArray arrayWithCollection:nil];
NSLog( @"%@", array);
}
@catch (SCException *error) {
NSLog( @"%@", [error description]);
NSLog( @"========================================================================");
NSLog( @"Error code: %d", error.code);
NSLog( @"========================================================================");
}
2016-09-21 13:11:00.173 libtest[3362:472990] SCL-20041: Source collection is nil
2016-09-21 13:11:00.174 libtest[3362:472990] ========================================================================
2016-09-21 13:11:00.174 libtest[3362:472990] Error code: -20041
2016-09-21 13:11:00.174 libtest[3362:472990] ========================================================================

Error ID is a string, which normally contains three characters and text representation of the error code. For the library errors we use the symbols SCL. For getting the error ID you can use property eid of the class SCException instance:

@property (nonatomic, readonly, retain) NSString *eid;
@try {
SCArray *array = [SCArray array];
[array addObject:nil];
NSLog( @"%@", array);
}
@catch (SCException *error) {
NSLog( @"%@", [error description]);
NSLog( @"========================================================================");
NSLog( @"Error ID: %@", error.eid);
NSLog( @"========================================================================");
}
2016-09-21 14:04:41.375 libtest[3803:499118] SCL-20044: Array - empty item adding attemption
2016-09-21 14:04:41.375 libtest[3803:499118] ========================================================================
2016-09-21 14:04:41.375 libtest[3803:499118] Error ID: SCL-20044
2016-09-21 14:04:41.375 libtest[3803:499118] ========================================================================

Initializing exceptions

Class SCException declares the following methods for exceptions initializing:

- (instancetype)initWithName:(NSString *)name reason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;

Class SCAbstractMethodException

Class SCAbstractMethodException created specifically for situations where there is an attempt to call an abstract method. Since the Objective C does not implement the concept of an abstract method, it is necessary to create the implementation of this method to call the exception SCL-20001.

Class declares the following properties for accessing to the error data:

@property (nonatomic, readonly, retain) NSString *methodName;

Class method returns a class instance created by using the specified abstract method name:

+ (instancetype)exceptionWithMethod:(NSString *)method;

Class SCSystemException

Exception class SCSystemException designed to handle errors that occur when using the system calls directly or through the thrid-party libraries. All system error are identified by the error ID SCL-20002.

Class declares the following properties and methods for accessing to the processed error data:

@property (nonatomic, assign, readonly, getter=error) SCSystemError error;
@property (nonatomic, retain, readonly, getter=objectName) NSString *objectName;

Class declares the following methods for creating a class instances:

+ (instancetype)exceptionWithError:(SCSystemError)error object:(NSString *)object;
+ (instancetype)exceptionWithError:(SCSystemError)error;

Class SCNumberException

Class SCNumberException handle the number object errors, which can be occur when you use the methods from the class NSNumber expanding category NSNumber(SCNumber). Class defines the following error identifiers:

The following class method returns a number exception created by using the specified description, code and ID:

- (instancetype)initWithReason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;

Unspecified NSNumber error

Error SCL-20010 did not used by the library, but it can be used in those cases when it is necessary to identify a numeric error object, but does not enter a new error identifier.

The following methods can be used for creating and initializing the number exception:

+ (instancetype)exception;

Unsupported number object type

Error SCL-20011 is generated upon detection of an unsupported number object. Thus during the error processing can use the following properties:

@property (nonatomic, readonly, retain) NSString *unsupportedType;

For creating the unsupported number object type exception you can use the following methods:

+ (instancetype)exceptionWithUnsupportedType:(NSString *)type;

Class SCStreamException

Exception class SCStreamException provides stream error handling:

Exception properties

Class SCStreamException declares the following properties and access methods:

@property (nonatomic, readonly, retain) NSString *streamName;
@property (nonatomic, readonly, retain) NSString *unknown;
@property (nonatomic, readonly, retain) NSString *unexpected;
@property (nonatomic, readonly, retain) NSString *expected;
@property (nonatomic, readonly, retain) NSString *unsupported;
@property (nonatomic, readonly, assign) SCSize readedBytes;
@property (nonatomic, readonly, assign) SCSize writedBytes;
@property (nonatomic, readonly, assign) SCSize waitedBytes;
@property (nonatomic, readonly, assign) SCInteger openError;
@property (nonatomic, readonly, assign) SCInteger readError;
@property (nonatomic, readonly, assign) SCInteger writeError;
@property (nonatomic, readonly, assign) NSString *numberType;
@property (nonatomic, readonly, assign) SCFileStreamOpenMode openMode;
@property (nonatomic, readonly, assign) SCSystemError seekError;
@property (nonatomic, readonly, assign) NSInteger offset;
@property (nonatomic, readonly, assign) SCFileStreamOffsetWhence whence;

SCL-20020: unspecified stream error

This error can be used in cases where the handled situation not appropriate for the existing stream error codes, but the new error ID creating is inappropriate.

The exception class SCStreamException allows you to create an exception to the possibility of set the custom error codes and identifiers:

+ (instancetype)exceptionWithStream:(NSString *)stream
reason:(NSString *)reason
code:(SCInteger)code
eid:(NSString *)eid;
+ (instancetype)exceptionWithReason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;

SCL-20021: stream not open

This error occurs when attempting to make a read or write operation with unopened stream.

The following class methods create this exception:

+ (instancetype)exceptionWithNotOpenStream:(NSString *)stream;
+ (instancetype)exceptionWithNotOpen;

SCL-20022: read only stream

The exception occurs when you try to write data to the stream, which is open for read-only.

The following class methods create this exception:

+ (instancetype)exceptionWithReadOnlyStream:(NSString *)stream;
+ (instancetype)exceptionWithReadOnly;

SCL-20023: write only stream

The exception occurs when you try to read data from the stream, which is open for write-only.

The following class methods create this exception:

+ (instancetype)exceptionWithReadOnlyStream:(NSString *)stream;
+ (instancetype)exceptionWithReadOnly;

SCL-20024: unknown class

The error occurs when readed from the stream class instance is refers to an unknown class in the system. This usually happens when you try to read the stream of the older version of software than the version of the software by means of which have been writed this stream.

Obtain the name of an unknown class is possible through the property unknown:

@property (nonatomic, readonly, retain) NSString *unknown;

To create this exception instances are designed th following class methods:

+ (instancetype)exceptionWithUnknown:(NSString *)name stream:(NSString *)stream;
+ (instancetype)exceptionWithUnknown:(NSString *)name;

SCL-20025: unexpected class

If the stream instead of an instance of one class detects instance of the another class, then the generate this exception.

The name of the detected and the expected classes are determined by the following properties of the class:

@property (nonatomic, readonly, retain) NSString *unexpected;
@property (nonatomic, readonly, retain) NSString *expected;

To create this exception are designed the following class methods:

+ (instancetype)exceptionWithUnexpected:(NSString *)unexpected expected:(NSString *)expected stream:(NSString *)stream;
+ (instancetype)exceptionWithUnexpected:(NSString *)unexpected expected:(NSString *)expected;

SCL-20026: unsupported class

When you load an data of the class instance you may find that this class does not comply the SCStreaming protocol.

The name of the class can be found out by property of the SCStreamException class instance:

@property (nonatomic, readonly, retain) NSString *unsupported;

The following class methods can be used to create an exception:

+ (instancetype)exceptionWithUnsupported:(NSString *)name stream:(NSString *)stream;
+ (instancetype)exceptionWithUnsupported:(NSString *)name;

SCL-20027: incomplete read operation

An error occurs if less characters were retrieved from the stream than was requested.

Data that how many characters have been read, and as requested, can be obtained by the following properties:

@property (nonatomic, readonly, assign) SCSize readedBytes;
@property (nonatomic, readonly, assign) SCSize waitedBytes;

The following methods create the exception:

+ (instancetype)exceptionWithReaded:(SCSize)readed waited:(SCSize)waited stream:(NSString *)stream;
+ (instancetype)exceptionWithReaded:(SCSize)readed waited:(SCSize)waited;

SCL-20028: incomplete write operation

This error is usually generated by a stream unit in cases where has been fixed the fact that the stream was write less characters than required. This can occur when you try to write to a file on the file system, which is out of space or when writing in which closed due to a network failure stream.

Data actually written and to be written symbols can be read through the properties of the class:

@property (nonatomic, readonly, assign) SCSize writedBytes;
@property (nonatomic, readonly, assign) SCSize waitedBytes;

To create an instance of the exception class are designed the following methods:

+ (instancetype)exceptionWithWrited:(SCUInteger)writed waited:(SCUInteger)waited stream:(NSString *)stream;
+ (instancetype)exceptionWithWrited:(SCUInteger)writed waited:(SCUInteger)waited;

SCL-20029: stream opening error

This error occurs during the stream open operation. The main error parameter is the error code, which returns after the unsuccessful execution the system call or third-party function:

@property (nonatomic, readonly, assign) SCInteger openError;

You can create this exception by using the following methods:

+ (instancetype)exceptionWithOpenError:(SCInteger)error stream:(NSString *)stream;
+ (instancetype)exceptionWithOpenError:(SCInteger)error;

SCL-20030: data read error

The error occurs if during the read operation system or library call returns the data read error (for example, when trying to read a file from a damaged media or in the event of network failures). When an error occurs the detected error code written in the property readError:

@property (nonatomic, readonly, assign) SCInteger readError;

For creating this exception, are responsible the followin class methods:

+ (instancetype)exceptionWithReadError:(SCInteger)error stream:(NSString *)stream;
+ (instancetype)exceptionWithReadError:(SCInteger)error;

SCL-20031: data write error

This exception is designed to handle errors during data writing into the stream. Information, which are obtained from the system of librray call, is stored in the property writeError:

@property (nonatomic, readonly, assign) SCInteger writeError;

Exception class SCStreamException declares the following methods for creating class instances:

+ (instancetype)exceptionWithWriteError:(SCInteger)error stream:(NSString *)stream;
+ (instancetype)exceptionWithWriteError:(SCInteger)error;

SCL-20032: NSNumber error

The error occurs when the stream unit detects the unknown number object type. Information about detected NSNumber type stores in the property numberType:

@property (nonatomic, readonly, assign) NSString *numberType;

Creating this exception provided by the following class methods:

+ (instancetype)exceptionWithUnsupportedNumberType:(NSString *)type stream:(NSString *)stream;
+ (instancetype)exceptionWithUnsupportedNumberType:(NSString *)type;

SCL-20033: incorrect stream mode

Class SCFileStream supports a specified set of file stream open modes. When you try to open a stream with a different mode this exception is generated. Property openMode allows obtained the detected incorrect opening mode:

@property (nonatomic, readonly, assign) SCFileStreamOpenMode openMode;

For creating this exception you can use the following class methods:

+ (instancetype)exceptionWithOpenMode:(SCFileStreamOpenMode)mode path:(NSString *)path;
+ (instancetype)exceptionWithOpenMode:(SCFileStreamOpenMode)mode;

SCL-20034: empty file stream path

This error is occurs when you try to open a file by using the nil path. Typically, this situation occurs when the software transmits without verification the path, that received from the user. Also this error can be occur as a result of the errors in the software, which uses the streams.

Create this exception is possible by using the following class methods:

+ (instancetype)exceptionWithEmptyPath;

SCL-20035: end of stream

The error is generated when trying to read data from the stream after its end has been reached, that is, read all the available data in the stream. For creating this exception class SCStreamException declares the following class methods:

+ (instancetype)exceptionWithEndOfFile:(NSString *)file;
+ (instancetype)exceptionWithEndOfFile;

SCL-20036: incorrect offset

The error occurs when trying to position the pointer over the stream boundaries.

For accessing the error data class SCStreamException declares the following properties:

@property (nonatomic, readonly, assign) SCSystemError seekError;
@property (nonatomic, readonly, assign) NSInteger offset;
@property (nonatomic, readonly, assign) SCFileStreamOffsetWhence whence;

Class SCStreamException implements the following methods for creating the exceptions:

+ (instancetype)exceptionWithSeekError:(SCSystemError)error
whence:(SCFileStreamOffsetWhence)whence
offset:(NSInteger)offset
path:(NSString *)path;
+ (instancetype)exceptionWithSeekError:(SCSystemError)error
whence:(SCFileStreamOffsetWhence)whence
offset:(NSInteger)offset;
+ (instancetype)exceptionWithSeekError:(SCSystemError)error path:(NSString *)path;
+ (instancetype)exceptionWithSeekError:(SCSystemError)error;

SCL-20037: incorrect offset whence

This error is occurs when the stream detects the incorrect whence of the offset operation. Error data can be obtained from the following properties of the class SCStreamException:

@property (nonatomic, readonly, assign) SCSystemError seekError;
@property (nonatomic, readonly, assign) SCFileStreamOffsetWhence whence;

Class SCStreamException implements the following class methods for creating this exception:

+ (instancetype)exceptionWithWhence:(SCFileStreamOffsetWhence)whence path:(NSString *)path;
+ (instancetype)exceptionWithWhence:(SCFileStreamOffsetWhence)whence;

Class SCCollectionException

Exception class SCCollectionException supports handling of errors, which can occur during the operations with collections:

Exception properties

For access to the information about collection errors the class SCCollectionException declares the following read only properties:

@property (nonatomic, readonly, retain) NSString *collectionName;
@property (nonatomic, readonly, retain) NSString *typeName;
@property (nonatomic, readonly, retain) NSString *unsupported;
@property (nonatomic, readonly, retain) NSString *unknown;
@property (nonatomic, readonly, assign) SCIndex index;
@property (nonatomic, readonly, assign) NSRange range;
@property (nonatomic, readonly, retain) NSIndexSet *indexSet;
@property (nonatomic, readonly, assign) SCULong indexesCount;
@property (nonatomic, readonly, assign) SCULong objectsCount;
@property (nonatomic, readonly, retain) NSString *key;
@property (nonatomic, readonly, assign) SCULong keysCount;

SCL-20040 - unspecified collection error

Error SCL-20040 is designed to indicate the collection errors, that are not related to those already defined for specific exceptions. This ID is created for cases where there is no need to create the individual error ID.

The following class SCCollectionException methods can be used for creating the exceptions by using the specified error codes and identifiers:

+ (instancetype)exceptionWithName:(NSString *)name reason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;
+ (instancetype)exceptionWithReason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;

SCL-20041 - source collection does not exist

Exception SCL-20041 is generated if the collection detects what the specified source collection does not exists - collection method receives the nil pointer instead the pointer to the collection.

Class SCCollectionException declares the following methods for creating this exception:

+ (instancetype)exceptionWithSource;

SCL-20042 - unsupported collection type

Exception SCL-20042 is generated if the collection instead the pointer to the collection receivies the pointer to instance of any other class, for example, class receives the string instead the pointer to the array.

Name of the unsupported collection type stores in the property typeName:

@property (nonatomic, readonly, retain) NSString *typeName;

Class SCCollectionException implements the following creating methods:

+ (instancetype)exceptionWithUnsupportedType:(NSString *)type;

SCL-20043 - collection is read-only

If you attemt changing the content of read only collection, then the error SCL-20043 is occurs.

Class SCCollectionException declares the following class methods for creating this exception:

+ (instancetype)exceptionWithReadOnlyType:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithReadOnlyType:(NSString *)type;

Please note, that the parameter type of these methods (and some other) passes the type name of collection that caused the exception to the correct error message generation.

SCL-20044 - adding a null pointer

Error SCL-20044 is occurs when the collection detects the attempt to adding the nil pointer. For creating this exception instances you can use the follow class SCCollectionException methods:

+ (instancetype)exceptionWithItemType:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithItemType:(NSString *)type;

SCL-20045 - source object does not exist

Exception SCL-20045 is generated when the collection receives the nil pointer instead the source object.

Class SCCollectionException implements the following methods for creating this exception instance:

+ (instancetype)exceptionWithObject;

SCL-20046 - unsupported class

If the collection detects the instance of the class, which does not comply to the protocol SCCollectioning, then the exception SCL-20046 is generated. The name of this class can be obtained from the property unsupported:

@property (nonatomic, readonly, retain) NSString *unsupported;

Class SCCollectionException declares the following methods for creating this exception:

+ (instancetype)exceptionWithUnsupported:(NSString *)cname type:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithUnsupported:(NSString *)cname type:(NSString *)type;

SCL-20047 - unknown class

If the collection detects the class, which does not known by the system, the exception SCL-20047 is generated. Name of the unknown class can be obtained from the property unknown.

@property (nonatomic, readonly, retain) NSString *unknown;

For creating this exception instance class SCCollectionException declares the following methods:

+ (instancetype)exceptionWithUnknown:(NSString *)cname type:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithUnknown:(NSString *)cname type:(NSString *)type;

SCL-20048 - incomparable collection object

Exception SCL-20048 is generated when the collection during the sorting process detects the objects, that cannot be compared. For creating this exception instance class SCCollectionException implements the following methods:

+ (instancetype)exceptionWithNotComparableType:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithNotComparableType:(NSString *)type;

SCL-20049 - collection does not support sorting

Error SCL-20049 occurs if you attempt sorting collection, which does not support the sorting opeations. Class SCCollectionException implements the following methods for creating this exception instance:

+ (instancetype)exceptionWithNotSortableType:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithNotSortableType:(NSString *)type;

SCL-20050 - incorrect data sorter

Error SCL-20050 is occurs when the collection receives the pointer to the incorrect data sorter. Class SCCollectionException implements the following methods for creating this exception instance:

+ (instancetype)exceptionWithSorterType:(NSString *)type name:(NSString *)name;
+ (instancetype)exceptionWithSorterType:(NSString *)type;

SCL-20052 - incorrect index

If the indexed collection detects the incorrect index, then the exception SCL-20052 is generated. This exception stores the detected incorrect index in the property index:

@property (nonatomic, readonly, assign) SCIndex index;

You can create the exception instance by using the specified class methods:

+ (instancetype)exceptionWithIndex:(SCIndex)index name:(NSString *)name;
+ (instancetype)exceptionWithIndex:(SCIndex)index;

SCL-20053 - incorrect objects range

If the collection detects the incorrect objects range, then the exception SCL-20053 is generated. The incorrect range can be obtained from the property range:

@property (nonatomic, readonly, assign) NSRange range;

Exception instance can be created by using the specified class SCCollectionException methods:

+ (instancetype)exceptionWithRange:(NSRange)range name:(NSString *)name;
+ (instancetype)exceptionWithRange:(NSRange)range;

SCL-20054 - incorrect index set

If the indexed collection detects the incorrect index set (nil pointer to index set or incorrect index within the set), then the error SCL-20054 is occurs and exception is generated. The property indexSet return the detected incorrect index set.

@property (nonatomic, readonly, retain) NSIndexSet *indexSet;

Class SCCollectionException declares the following methods for creating this exception:

+ (instancetype)exceptionWithIndexSet:(NSIndexSet *)indexSet name:(NSString *)name;
+ (instancetype)exceptionWithIndexSet:(NSIndexSet *)indexSet;

SCL-20055 - number of indexes does not match number of objects

Some methods of indexed collections operate with index sets and object lists. The number of indexes in the set must match the number of objects. If the collection detects a mismatch between them, the exception SCL-20055 is thrown. Error information is stored in the following properties:

@property (nonatomic, readonly, assign) SCULong indexesCount;
@property (nonatomic, readonly, assign) SCULong objectsCount;

Class SCCollectionException implements the following methods for creating this exception instance:

+ (instancetype)exceptionWithIndexesCount:(SCULong)indexes objectsCount:(SCULong)objects;

SCL-20056 - incorrect object key

If the collection detects the incorrect object key, then the error SCL-20056 is occurs. Detected incorrect key can be obtained from the property key:

@property (nonatomic, readonly, retain) NSString *key;

Class SCCollectionException declares the following methods for creating this exception instance:

+ (instancetype)exceptionWithKey:(NSString *)key name:(NSString *)name;
+ (instancetype)exceptionWithKey:(NSString *)key;

SCL-20057 - number of keys does not match number of objects

Error SCL-20057 is equals to the error SCL-20055, but instead the number of indexes use the number of keys. Error information can be obtained by using the following properties:

@property (nonatomic, readonly, assign) SCULong keysCount;
@property (nonatomic, readonly, assign) SCULong objectsCount;

Class SCCollectionException implements the following methods for creating this exception instance:

+ (instancetype)exceptionWithKeysCount:(SCULong)keys objectsCount:(SCULong)objects;

SCL-20058 - empty value

Error SCL-20058 can be occured if you attempt add into the collection the nil pointer instead the value. Key of the erroneous value can be obtained from the property key:

@property (nonatomic, readonly, retain) NSString *key;

For creating this exception instance you can use the following methods of the class SCCollectionException:

+ (instancetype)exceptionValueForKey:(NSString *)key name:(NSString *)name;
+ (instancetype)exceptionValueForKey:(NSString *)key;

Class SCTextException

Exception class SCTextException handle the errors, which can be occur during using the text classes:

Exception properties

Class SCTextException declares the following read only properties:

@property (nonatomic, readonly, retain) NSString *textName;
@property (nonatomic, readonly, retain) NSString *string;
@property (nonatomic, readonly, assign) SCIndex index;
@property (nonatomic, readonly, retain) NSIndexSet *indexSet;
@property (nonatomic, readonly, retain) NSString *unsupported;
@property (nonatomic, readonly, assign) SCULong indexesCount;
@property (nonatomic, readonly, assign) SCULong stringsCount;
@property (nonatomic, readonly, assign) NSRange range;
@property (nonatomic, readonly, assign) NSRange intersected;
@property (nonatomic, readonly, retain) SCStream *stream;

SCL-20060 - unspecified text error

In addition to certain exceptions class SCTextException class allows you to create exception to the additional error identifiers and unspecified text error SCL-20060:

+ (instancetype)exceptionWithName:(NSString *)name reason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;
+ (instancetype)exceptionWithReason:(NSString *)reason code:(SCInteger)code eid:(NSString *)eid;
+ (instancetype)exceptionWithName:(NSString *)name;
+ (instancetype)exception;

SCL-20061 - source object does not exist

Error SCL-20061 is occurs when the text object receives the nil pointer instead the pointer to the source object. For creating this exception instance class SCTextException implements the following class methods:

+ (instancetype)sourceExceptionWithName:(NSString *)name;
+ (instancetype)sourceException;

SCL-20062 - incorrect input stream

If the problem with the input stream (nil pointer to the stream, specified stream does not support read operations) is detected during the read text from the stream, then the text object throws an exception SCL-20062. The pointer to the incorrect input stream can be ontained by using the property stream:

@property (nonatomic, readonly, retain) SCStream *stream;

Class SCTextException declares the following methods for creating this exception instance:

+ (instancetype)exceptionWithInputStream:(SCStream *)stream name:(NSString *)name;
+ (instancetype)exceptionWithInputStream:(SCStream *)stream;

SCL-20063 - text is read only

Error SCL-20063 is occurs when you attempt changing the content of the read only text object. For creating this exception instances class SCTextException implements the following methods:

+ (instancetype)readOnlyExceptionWithName:(NSString *)name;
+ (instancetype)readOnlyException;

SCL-20064 - null string adding

Error SCL-20064 occurs during the attemt to add the nil string into the text object. Class SCTextException declares the following methods for creating this exception instances:

+ (instancetype)emptyStringExceptionWithName:(NSString *)name;
+ (instancetype)emptyStringException;

SCL-20065 - closed stream

Exception SCL-20065 is thrown then the text object detects the attemption to read from or write to the closed stream. Pointer to the closed stream can be obtained from the property stream:

@property (nonatomic, readonly, retain) SCStream *stream;

Class SCTextException declares the following methods for creating this exception instances:

+ (instancetype)exceptionWithClosedStream:(SCStream *)stream name:(NSString *)name;
+ (instancetype)exceptionWithClosedStream:(SCStream *)stream;

SCL-20066 - not string instance

If the text object detects the unsupported class, then the exception SCL-20066 is thrown. Name of unsupported class can be obtained from the property unsupported:

@property (nonatomic, readonly, retain) NSString *unsupported;

For creating this exception instance class SCTextException declares the following class methods:

+ (instancetype)exceptionWithUnsupported:(NSString *)unsupported name:(NSString *)name;
+ (instancetype)exceptionWithUnsupported:(NSString *)unsupported;

SCL-20067 - reading error

If the reading error detects during the reading strings from the stream, then the text object generates the exception SCL-20067. Erroneous stream can be obtained from the property SCTextException.stream "stream":

@property (nonatomic, readonly, retain) SCStream *stream;

Class SCTextException implements the following class methods for creating this exception instance:

+ (instancetype)readErrorExceptionWithStream:(SCStream *)stream name:(NSString *)name;
+ (instancetype)readErrorExceptionWithStream:(SCStream *)stream;

SCL-20068 - empty text file path

Error SCL-20068 is occurs then the text file receives the empty path to the disk file (nil pointer or empty string). For creating this exception instance class SCTextException implements the following class methods:

+ (instancetype)emptyPathExceptionWithName:(NSString *)name;
+ (instancetype)emptyPathException;

SCL-20069 - string unique violation

Exception SCL-20069 generates by the class SCUniqueStrings if the unique strings list detects the unique violation. For processing this exception class SCTextException uses the following properties and methods:

@property (nonatomic, readonly, retain) NSString *string;
@property (nonatomic, readonly, assign) SCIndex index;

For creating this exception instance class SCTextException uses the following class methods:

+ (instancetype)duplicateExceptionWithName:(NSString *)name string:(NSString *)string index:(SCIndex)index;
+ (instancetype)duplicateExceptionWithString:(NSString *)string index:(SCIndex)index;

SCL-20070 - incorrect strings sorter

If the text object detects the incorrect strings sorter, then the exception SCL-20070 is thrown. For creating this exception instance class SCTextException implements the following methods:

+ (instancetype)sorterExceptionWithName:(NSString *)name;
+ (instancetype)sorterException;

SCL-20071 - incorrect output stream

Error SCL-20071 is occurs if the text object detects the nil pointer to the output stream or detects the output stream, which does not support write operations. Erroneous stream can be obtained from the property stream:

@property (nonatomic, readonly, retain) SCStream *stream;

Class SCTextException declares the following class methods for creating this exception instances:

+ (instancetype)exceptionWithOutputStream:(SCStream *)stream name:(NSString *)name;
+ (instancetype)exceptionWithOutputStream:(SCStream *)stream;

SCL-20072 - incorrect string index

Error SCL-20072 is occurs when the text object detects the incorrect index. Detected index can be obtained from the property index:

@property (nonatomic, readonly, assign) SCIndex index;

Class SCTextException implements the following class methods for creating this exception instance:

+ (instancetype)exceptionWithIndex:(SCIndex)index name:(NSString *)name;
+ (instancetype)exceptionWithIndex:(SCIndex)index;

SCL-20073 - incorrect string range

If the text object detects the incorrect strings range, then the exception SCL-20073 is thrown. Detected incorrect range can be obtained from the property range:

@property (nonatomic, readonly, assign) NSRange range;

Class SCTextException declares the following class methods for creating this exception instances:

+ (instancetype)exceptionWithRange:(NSRange)range name:(NSString *)name;
+ (instancetype)exceptionWithRange:(NSRange)range;

SCL-20074 - incorrect index set

Incorrect index set generates the exception SCL-20074. Detected index set can be obtained from the property indexSet:

@property (nonatomic, readonly, retain) NSIndexSet *indexSet;

Class SCTextException declares the following class methods for creating this exception instances:

+ (instancetype)exceptionWithIndexSet:(NSIndexSet *)indexSet name:(NSString *)name;
+ (instancetype)exceptionWithIndexSet:(NSIndexSet *)indexSet;

SCL-20075 - number of indexes does not match number of strings

Some text objects methods accept as an argument the index sets and object lists. If the number of indexes does not match the number of objects, then the error SCL-20075 is occurs. Class SCTextException declares the following properties and methods for accessing the error information:

@property (nonatomic, readonly, assign) SCULong indexesCount;
@property (nonatomic, readonly, assign) SCULong stringsCount;

Class SCTextException implements the following class methods for creating this exception instance:

+ (instancetype)exceptionWithIndexesCount:(SCULong)icount stringsCount:(SCULong)scount name:(NSString *)name;
+ (instancetype)exceptionWithIndexesCount:(SCULong)icount stringsCount:(SCULong)scount;

SCL-20076 - intersected string ranges

If the text object detects the intersected ranges of strings, then the exception SCL-20076 is thrown. Information about intersected ranges can be obtained from the following properties and methods of the class SCTextException:

@property (nonatomic, readonly, assign) NSRange range;
@property (nonatomic, readonly, assign) NSRange intersected;

Class SCTextException implements the following class methods for creating this exception instances:

+ (instancetype)exceptionWithRange:(NSRange)range intersected:(NSRange)intersected name:(NSString *)name;
+ (instancetype)exceptionWithRange:(NSRange)range intersected:(NSRange)intersected;

SCL-20077 - writing error

If the text object detects the error during the read strings from the stream, then the error SCL-20077 is occurs. The erroneous stream can be obtained from the property stream:

@property (nonatomic, readonly, retain) SCStream *stream;

Class SCTextException declares the following methods for creating this exception instance:

+ (instancetype)writeErrorExceptionWithStream:(SCStream *)stream name:(NSString *)name;
+ (instancetype)writeErrorExceptionWithStream:(SCStream *)stream;

Grouping classes

In this Programming Guide section we describe the grouping classes that provide the creation of an hierarchy of classes related to each other only logically. Create instances of these classes makes no sense:

Class SCDelegate

Class SCDelegate is a common ancestor of the delegation classes (event handling classes). Currently the delegate classes Класс SCDelegate объединяет в общую иерархию все классы-обработчики событий (классы делегирования):

delegates.png

Class SCService

Class SCService creates the hierarchy of the auxiliary classes, which very rarely used outside of library units:

services.png

Library information

Information relating directly to the library, available through class properties declared in a special class SCCommon. To call these methods, there is no need to create instances of this class.

@property (class, readonly, copy) NSString *version;
@property (class, readonly, copy) NSString *fullVersion;
@property (class, readonly, assign) SCUInteger sclBuild;
@property (class, readonly, copy) NSString *libraryInformation;
@property (class, readonly, copy) NSString *compilationDate;
@property (class, readonly, copy) NSString *compilationDateTime;
@property (class, readonly, copy) NSString *compilationString;
@property (class, readonly, copy) NSString *copyright;

Types and constants

This Programming Guide section describes data types, constants and macroses, which are used by many components of the library:

Standard types

For ease of programming and maintenance of software portability between different systems, the library introduces its standard data types that are defined in the file SCTypes.h:

Data type Description Size Comments
SCBool Boolean type 1 byte
SCChar Signed character type 1 byte
SCByte Signed 8-bit integer data type 1 byte
SCShort Signed 16-bit integer data type 2 bytes
SCInteger Signed 32-bit integer data type 4 bytes
SCLong Signed 64-bit integet data type 8 bytes
SCSignedLong Signed integer long data type 4 or 8 bytes
SCUChar Unsigned character type 1 byte
SCUByte Unsigned 8-bit integer data type 1 byte
SCUShort Unsigned 16-bit integer data type 2 bytes
SCUInteger Unsigned 32-bit integer data type 4 bytes
SCULong Unsigned 64-bit integer data type 8 bytes
SCUnsignedLong Unsigned long integer data type 4 or 8 bytes
SCFloat Float data type 4 bytes
SCDouble Double data type 8 bytes
SCVoid Void data type 1 byte
SCCharString Character string
SCConstString Constant character string
SCSelector Class method selector type
SCClass Class type
SCID Object type
SCString String object
SCNumber Number object
SCDecimal Decimal number object
SCDate Date and time object
SCValue Values storage object
SCNull Null object
SCURL URL object

Special types

Library in the file SCTypes.h declares the following special data type:

Data type Description Size Comments
SCSize Unsigned size data type 4 or 8 bytes

Other data types

File SCTypes.h declares the following advanced data types:

Data type Description
SCCapacity Declares a set of constants that indicate a capacity of integer values (8, 16, 32 and 64 bits)
SCIntegerBase Declares a set of contants that indicate a base of an integer values

Macroses

File SCConstants.h declares the following macroses:

#define SCLS( string) NSLocalizedString( string, nil)
#define __abstract__( name) { @throw [SCAbstractMethodException exceptionWithMethod:name]; }

Data Types Definition System

Data Types Definition System is developed for the purpose of support of different data storage and transport systems (such as a database systems) with their different data types. By the analysis of the majority of DBMS all diversity of their types was reduced to a limited set which is declared in library by means of the SCDataType type (since version 1.2.5).

Type SCDataType defines the following constants and data types:

Constant Description Data type Comments
SCTypeUnspecified Unspecified data type
SCTypeBool Boolean data type BOOL
SCTypeChar Signed character data type char
SCTypeByte Signed 8-bit integer data type SCByte
SCTypeShort Signed 16-bit integer data type SCShort
SCTypeInteger Signed 32-bit integer data type SCInteger
SCTypeLong Signed 64-bit integer data type SCLong
SCTypeSignedLong Signed long integer data type SCSignedLong
SCTypeNSInteger Signed NSInteger data type NSInteger
SCTypeUChar Unsigned character data type unsigned char
SCTypeUByte Signed 8-bit integer data type SCUByte
SCTypeUShort Signed 16-bit integer data type SCUShort
SCTypeUInteger Signed 32-bit integer data type SCUInteger
SCTypeULong Signed 64-bit integer data type SCULong
SCTypeUnsignedLong Unsigned long intgeger data type SCUnsignedLong
SCTypeNSUInteger Unsigned NSUInteger data type NSUInteger
SCTypeFloat Float data type SCFloat
SCTypeDouble Double data type SCDouble
SCTypeVoid Void data type void
SCTypeCharString Character string type char *
SCTypeConstString Constant character type const char *
SCTypeSelector Method selector type SEL
SCTypeClass Class type Class
SCTypeObject Object data type id
SCTypeString String data type NSString
SCTypeNumber Number data type NSNumber
SCTypeDecimal Decimal number data type NSDecimalNumber
SCTypeDate Date and time data type NSDate
SCTypeArray Array type NSArray
SCTypeDictionary Dictionary type NSDictionary
SCTypeSet Unordered set type NSSet
SCTypeData Binary data type NSData
SCTypePointer Data pointer type not implemented
SCTypeBitmap Bit array (bitmap) data type not implemented
SCTypeDataSet Data set type not implemented
SCTypeCursor Data cursor type not implemented
SCTypeRowID Row ID data type not implemented
SCTypeValue Value class type NSValue
SCTypeNull Class type for null (empty) values NSNull
SCTypeURL URL type NSURL
SCTypeConfig Configuration data type not implemented
SCTypeGUID GUID data type not implemented
SCTypeXML XML data type not implemented

At present not all DTDS types have implementation in Objective C or our library - gradually we will add new data types from listed above. Also so,me types from the standard do not support such mechanisms of our library, as a serialized files and streams. This support will be added also in a futured versions of our library.

Let's in addition mark that for today we did not start development of components which will use SDTS in the operation, however we enter DTDS into version 1.2.5 that in upcoming versions to start development of mechanisms of library using these system.

DTDS also contains a SCArgumentType type that defines kinds of agruments by operation with different modules (for example stored procedures of databases). Type defines the following constants and argument kinds:

Constant Description Comments
SCArgumentUnspecified Unspecified argument type
SCArgumentReturn Function or method return type
SCArgumentInputOutput Argument transfers data into and from a call unit
SCArgumentCopy Argument transfers by copy of a data
SCArgumentReference Argument transfers data by using a reference
SCArgumentOneWay One way argument
SCArgumentInput Argument transfers data into a call unit
SCArgumentOutput Argument transfers data from a call unit
SCArgumentConst Constant argument

Functions

This documentation section describes various functions which does not belong to any classes of library. For convenience of study of functions are grouped in the functionality:

Logging functions

Logging functions provide the formatted output of various information and are analogs standard functions NSLog and NSLogv. Functions were developed with two purposes:

A Samond Classes Library declares the following logging functions:

void SCLog( NSString *format, ...);
void SCLogv( NSString *format, va_list arguments);
void SCLogl();
void SCError( NSString *format, ...);
void SCErrorv( NSString *format, va_list arguments);
void SCErrorl();
void SCPrint( NSString *format, ...);
void SCPrintv( NSString *format, va_list arguments);
void SCPrintError( NSString *format, ...);
void SCPrintErrorv( NSString *format, va_list arguments);
Generated on Fri Aug 10 2018 16:06:33 for Samond Classes Library 1.2.6-STABLE build 219 by   doxygen 1.8.9.1