GNUstepWiki - User contributions [en]

Creating document based applications

2011-02-03T21:17:58Z

Newacct:

Note: First version; subject to further revisions and changes.
--[[User:Quineska|ChrisArmstrong]] 07:09, 7 Jul 2005 (CEST)

== Introduction ==

[[OpenStep]] supports document-based applications, simplifying the process of creating applications whose behaviour is familiar to many users. [[GNUstep]] also provides this functionality to the developer. This guide aims to provide an overview of what is required in the creation and design of such an application.

It is assumed you are familiar with GNUstep, and have some understanding as how to create [[Gorm]]'s interface files (often referred to as nibs), as well as some understanding of how they work.

Importantly, such applications have certain components that are required, and should be considered as part of their design. When programming, classes that will be used as part of the [[AppKit]] are:

==== NSDocument ====

This class is central to the OpenStep document based model. These application's declare a new instance of a subclass of NSDocument for each “document” that is opened. You will subclass NSDocument to implement this.

Each instance of your NSDocument subclass may have one or more windows associated with it. These are used as an interface for loading and saving a representation of your document type. Each window will have an “NSWindowController” instance associated with it, where NSDocument maintains a list of these.

==== NSDocumentController ====

This class acts a controller. It maintains a list of documents (instances of your NSDocument subclass) and is responsible for loading and instantiating new documents. It is usually not necessary to implement a subclass of this, but often it may be useful to implement special functionality (especially related to opening and creating documents at an application level).

==== NSWindowController ====

As mentioned above, NSWindowController instances are individually associated with one NSWindow instance, in such a way that a document maintains a list of window controllers that are responsible for rendering the views associated with a document.

You will most likely not have to subclass NSWindowController. Instead, you associate a nib file (the Gorm output) with the subclass of NSDocument, and NSDocumentController will load this nib file for each document that is created or loaded.

For example, a text based application that is used for the editing of plain text files, may subclass NSDocument with a TextDocument class. Each instance of this class would have an NSWindowController instance associated with it, which in turn manages a window instance that is instantiated from a nib file. The NSDocumentController instance, as managed and instantiated by GNUstep, would be responsible for loading and saving documents in your application. It even prompts the user to save their documents when they try to quit the application.

== File Components ==

In building your application you will need to create a number of special files. From scratch, the following should be a rough guide to getting it working. These include the Makefile, your application's property list and the interface files.

=== The Makefile ===

For this type of application, no special makefile is needed: it just has to be a normal application. Project Builder should be able to spit out the required makefile and Gorm files that are needed for a generic application. I believe it is also capable of providing support for document-based applications. Otherwise use the following as a template:

'''GNUmakefile'''

include $(GNUSTEP_MAKEFILES)/common.make 
APP_NAME = DocumentApp 
DocumentApp_OBJC_FILES = 
MyDocument.m 
main.m 
DocumentApp_RESOURCES = \ 
Resources/Info-gnustep.plist \ 
Resources/DocumentApp.gorm \ 
Resources/MyDocument.gorm 
-include GNUmakefile.preamble 
include $(GNUSTEP_MAKEFILES)/application.make 
-include GNUmakefile.postamble 

For more information as to customising this file, as well as setting up compiler options for third party libraries and includes, see the GNUstep makefile manual.

===The application dictionary===

For those that have edited this file in their project before, it is a dictionary with various values entered. For our purposes, we need an array within the main dictionary, called "NSTypes". This is a array of unnamed dictionaries, with one dictionary for each type.

I have provided an example for this file below. ProjectBuilder creates one as well. Please note that "TextEdit" does exist as an example application from NEXT I think, and again on MacOS X but I have constructed a much simpler version, used only for plain text files.

Taking a look at the single dictionary entry in the NSTypes array, the following key-value pairs are needed:
* '''NSDocumentClass:''' This is (string) the subclass name you use in your code, the "objective-c name" of your document subclass. This is used by NSDocumentController's default implementation to create instances of your document type.
* '''NSName:''' The generic file type (string). This is completely arbitrary, and can be anything you like. For the purpose of conventions, it may be more appropriate not to use the "NS" or "GS" prefix (the latter of which I not sure), and instead use either your own, or no prefix at all.
* '''NSHumanReadableName:''' The human readable name of your document type (string)? TODO: explain where this is used.
* '''NSUnixExtensions:''' An array of strings, each containing a file extension connected to this document type on "unix" platforms. TODO: explain how "unix" is interpreted by GNUstep.
* '''NSDOSExtensions:''' An array of strings, each containing a file extension connected to this document type on "DOS" platforms (could be loosely interpreted as any MS platforms GNUstep runs on, i.e. Windows 2000/XP).
* '''NSRole:''' A string, either "Viewer" or "Editor", depending on how your document operates on this file type.
* '''NSIcon:''' A icon name associated with this document type. TODO: Investigate how this works.

'''Info-gnustep.plist'''
{
ApplicationDescription = "A simple text editor for GNUstep.";
ApplicationName = TextEdit;
ApplicationRelease = 0.10;
Authors = ( "Christopher Armstrong" );
Copyright = "Copyright (C) 2005 Christopher Armstrong";
CopyrightDescription = "Released under GPL.";
FullVersionID = 0.10;
NSExecutable = TextEdit;
NSMainNibFile = TextEdit.gorm;
NSPrincipalClass = NSApplication;
NSRole = Application;
NSTypes = (
{
NSDocumentClass = "TextDocument";
NSName = "GSTextDocumentType";
NSHumanReadableName = "Text Document";
NSUnixExtensions = ( "txt", "" );
NSDOSExtensions = ( "txt" );
NSRole = Editor;
}
);
}

For more information on property list files, consult [[Property Lists]].

=== Interface files ===

Two interface files are needed: one for your main application, and another that will be instantiated with each instance of your document subclass. These both should be listed as resources in your makefile, (as shown the GNUmakefile example above). It may be helpful to name the document nib file after your class.

==== Application Interface File ====

The application one should just be a menu (though it could be more if necessary). When constructing it, take the following into account:

* '''Use an "Application" template''': Use a standard Gorm template for an Application.
* '''Delete the NSWindow instance''': In the "Objects" pane, remove the NSWindow instance by going File->Delete (unless you need a main window, which is beyond the scope of this document).
* '''Set NSOwner's class to "NSDocumentController"''': This is the custom class option of NSOwner in the property inspector. This ensures that the openDocument:, newDocument: messages, as sent to NSFirst, get picked up by NSDocumentController. Do not instantiate it (I believe you can't anyway).
* '''[Optional] Subclass NSDocumentController''':If you intend to subclass NSDocumentController, subclass it in the Classes pane. To make sure that this class is instantiated and used, make sure you instantiate it in Gorm or in your main.m file, and then set NSOwner to be of your custom subclass type.
* '''Add a "Document" menu''': Drag a Document menu from the palette onto your main menu. This already has the proper outlet and action linkage for each relevant message to be directed to NSFirst. Generic messages (such as openDocument:, not associated with any document instance) are forwarded to the shared instance of NSDocumentController (see it's reference documentation). When a document is active, more specific messages (such as close: or saveDocument:) are forwarded to the relevant document instance of your NSDocument subclass.
* '''[Optional] Add other menus''': Add any appropriate menus such as "Info" and "Format" which may be relevant to your application.

==== Document Interface File(s) ====

The document interface file is a window containing the view(s) required for the implementation of one instance of your document type. For example, in the case of a TextDocument type, a window instance with a NSTextView drawn on it is used for each document window. This interface file is instantiated every time a person creates a new document (the newDocument: message is sent to NSDocumentController) or opens an existing document (openDocument:).

You will need to:
* '''Subclass NSDocument''' with your document type in Gorm. This is done in a couple of ways, see [[Gorm_Manual#Custom_classes|custom classes]]. It is up to you whether or not you let Gorm generate the class files, but make sure you add the appropriate outlets to your class in the source files (otherwise, I think your your program may segfault).
* '''Set NSOwner:''' Set your subclass as NSOwner's Custom class using the Property Inspector. ''DO NOT INSTANTIATE IT.''

Another thing that you may want to consider is custom outlets. If you place certain views or controls on your window (including the window itself), you may want to refer to them directly in your code, e.g. the NSTextView in our TextEdit example is accessed directly, so that we can save it's contents to a file. To enable this, we add outlets to our class (see [[Gorm_Manual#Custom_classes|custom classes]]). We then connect NSOwner to the appropriate controls/views, and select the outlets in the Connections Property Inspector (see [[Gorm_Manual#Editing_the_interface|editing the interface]]).

== Code ==

Various things need to be done at a code level, to ensure that your NSDocument subclass is properly instantiated. This section aims to tell you what is necessary.

=== NSDocument subclass ===

When creating your subclass, you may have chosen to have Gorm create the class files. If not, you should create two files for your subclass: a header (.h) file and an implementation file (.m). The header file should take the following layout (we're using the TextEdit example again):

#ifndef TEXTDOCUMENT_H
#define TEXTDOCUMENT_H 
#include <AppKit/AppKit.h> 
@class NSDocument; 
/* The document type string, as specified in the property list [[#The_application_dictionary|NSTypes array]] */ 
NSString * GSTextDocumentType = "GSTextDocumentType";
@interface TextDocument : NSDocument
{
@protected
/* Outlets we added in our Gorm nib file */
id * textView;
NSString* fileContents;
}
/* Basic methods used for loading and saving document data (respectively). */
- (BOOL) loadDataRepresentation:(NSData*)representation ofType:(NSString*)type;
- (NSData*) dataRepresentationOfType: (NSString*)type; 
/* Information and events handling of GUI related changes */
- (NSString*) windowNibName;
- (void) windowControllerDidLoadNib:(NSWindowController*)windowController; 
@end 

Firstly, take note that we inherit from NSDocument. As a result, we need to override some methods for a basic (but working) implementation.

==== loadDataRepresentation:ofType: and dataRepresentationOfType: ====

The methods, loadDataRepresent:ofType: and dataRepresentationOfType: are used by NSDocumentController to load and save our files. The first method is called when the user tries to open a document (NSDocumentController gets the file name and copies it's data using an open panel). The method is passed the raw data in this file, as well as a string representing its type. It is important to note that this type string is the same one used in your property list. It is used by NSDocumentController to tell you what type it thinks you should open the data with. If this is not possible, or if there is an error trying to parse the data, your method returns FALSE/NO. Otherwise, you should store a local, meaningful representation of the data, which you can insert into your document window a little later (and return TRUE/YES).

For example, in terms of the TextEdit example:
- (BOOL) loadDataRepresentation:(NSData*) representation ofType:(NSString*)type
{
/*Check type information */
if (![type isEqual:GSTextDocumentType])
return NO;
/* Clean out our old representation if it still exists */
if (self->fileContents) RELEASE(self->fileContents); 
/* Allocate room for the new data, and try to initialise a string with it. */
self->fileContents = [NSString alloc];
self->fileContents = [self->fileContents initWithBytes: [representation bytes]
length: [representation length]
encoding: NSASCIIStringEncoding]; 
/* If this can't be done, return NO */
if (!self->fileContents)
return NO; 
/* Otherwise, set our TextView to the string data. */
[self->textView setString: fileContents];
return YES;
}

If this is not sufficient, or if your program can open the data in a more efficient manner, it may be worth looking into overriding -initWithContentsOfFile:ofType: and -initWithContentsOfURL:ofType:. Again, see the GUI manual for more details.

dataRepresentationOfType: is used to save the data. Your method is expected to return an instance of NSData that contains what should be saved to a file, for the type specified. Again, the ''type'' variable should be checked to ensure that you can write data of that type. Return nil if the file cannot be saved as that type.

For example:

- (NSData*) dataRepresentationOfType:(NSString*)type
{
if (![type isEqual:GSTextDocumentType])
return nil; 
NSData stringData = [[textView string] dataUsingEncoding:NSASCIIStringEncoding];
return stringData;
}

If a more sophisticated save implementation is needed, consult the documentation for information on the writeTo* methods.

==== windowNibName ====

This method must be overridden to return the a string of the name of your nib file (without the file extension). More complex implementations will use other methods to load the interface files. TODO: information on what methods need to be overridden.

==== windowControllerDidLoadNib: ====

Use this method to add code that should be run as soon as ''windowController'' has been initialised. Your document may have many window controllers; each window controller taking possession of one window.

In the TextEdit example, this method is used to copy the ''fileContents'' variable to the text view. It otherwise initialises the document window.

Also note that you can override windowControllerWillLoadNib: to perform pre-interface loading initialisation.

==== makeWindowControllers ====

This is an optional method to override, which must be used if you have multiple window controllers per document. It is responsible for creating each window controller from it's interface file and then adding it to the document. Use the addWindowController: method.

==== Other considerations ====

* You need a way to notify NSDocument that your document has changed, so that NSDocumentController can enable the menu item to allow saving. This is done by a call to the updateChangeCount: method. For example, the TextDocument class adds itself as a delegate to the textView, for any notification of changes. It then calls updateChangeCount: in the delegate's method.

* You may also wish to add a close: method (not the close method already in NSDocument, see below) to respond to the menu item permitting your document to close. This could perform cleanup operations before a call to [self close] is made e.g.

- (void) close:(id)sender /* Note this is not the method found in NSDocument (they differ by a parameter) */
{
[self close];
}

=== NSDocumentController ===

This class can optionally be subclassed, to implement some specific functionality. For example, programs handling multiple document types may override newDocument: to create a window so that the user can select which document type to create.

You should use separate implementation files and add the .m file to GNUmakefile.

=== NSWindowController ===

This class can also be optionally subclassed, to implement functionality specific to a window controller for a document type. You may need to override makeWindowControllers: in the NSDocument subclass in order to make sure your specific window controller is instantiated.

You should use separate implementation files and add the .m file to GNUmakefile.

== Optional Additions ==

=== Custom NSDocumentController and NSWindowController implementations ===

See [[#NSWindowController|NSWindowController]] and [[#NSDocumentController|NSDocumentController]].

----

[[Category:Development]]

HOM

2010-06-07T18:38:04Z

Newacct:

HOM (short for ''High Order Messaging'') is a mechanism for encapsulating control structures and other programming patterns. It is similar to blocks in [[Smalltalk]] and higher order functions in functional languages.

[[Objective-C]] does not have blocks. They're not a part of the language, although [http://virtualschool.edu/cox/ Brad Cox]'s [http://virtualschool.edu/cox/pub/TaskMaster/index.html TaskMaster Paper] outlines them nicely (and the [http://users.pandora.be/stes/compiler.html Portable Object Compiler] implements them).

However, it is possible to implement HOM (using [[trampoline|trampolines]]), but HOM is not a language feature at this point.

== What does HOM look like? ==

Suppose you have an [[NSArray]] containing objects you want to call a message on. Normally you would have to do something like

[anArray makeObjectsPerformSelector: @selector(someOtherMessage)];

With HOM you simply write

[[anArray do] someOtherMessage];

instead.

Simply put: the ''-do'' message tells the array to call ''-someOtherMessage'' on each of its objects.

== HOM related messages ==

To further explain how HOM works, here's a list of usual methods including a simple example.

We start by assuming there's an array

NSArray *array;

array = [@"one two three four five six seven eight nine ten" componentsSeparatedByString: @" "];

Now let's see how to use HOM methods on that array and what the results will be:

* ''-select''
Returns members of the array if they respond YES to the argument message -- which necessarily returns a BOOL.

NSArray *array2 = [[array select] hasPrefix: @"t"];
NSLog(@"%@", array2);

This will give us all numbers starting with a ''t''

(two, three, ten)

* ''-reject''
The inverse of ''-select''; it returns the elements responding NO.

NSArray *array3 = [[array2 reject] hasSuffix: @"e"];
NSLog(@"%@", array3);

will return all numbers in ''array2'' that do '''not''' end with an ''e''

(two, ten)

* ''-collect''
Executes the argument message and returns an array of the responses to the argument message.

NSArray *array4 = [[array3 collect] stringByAppendingString: @" books"];
NSLog(@"%@", array4);

will add ''books'' to all objects in ''array3''

("two books", "ten books")

* ''-do''
Executes the argument message.

NSArray *array5 = [[array collect] mutableCopy];
[[array5 do] appendString: @" eggplants"];
NSLog(@"%@", array5);

will create a mutable copy of ''array'' and append ''eggplants'' to each object.

(
"one eggplants",
"two eggplants",
"three eggplants",
"four eggplants",
"five eggplants",
"six eggplants",
"seven eggplants",
"eight eggplants",
"nine eggplants",
"ten eggplants"
)

As you can see, ''-do'' is quite similar to ''-collect'' but works on the objects inside the collection (here ''array5'' -- the mutable copy of ''array'') instead of returning a new array (as ''-collect'' does).

* ''-each''
Returns each object, similar to ''-objectEnumerator''.

NSArray *string = [[@"I like to eat " collect] stringByAppendingString: [array5 each]];

This is a stupid example (because I do not like eggplants) that would give us

(
"I like to eat one eggplants",
"I like to eat two eggplants",
"I like to eat three eggplants",
"I like to eat four eggplants",
"I like to eat five eggplants",
"I like to eat six eggplants",
"I like to eat seven eggplants",
"I like to eat eight eggplants",
"I like to eat nine eggplants",
"I like to eat ten eggplants"
)

* ''-performAfterDelay:''
Performs the argument message after a specified delay.

[[someArray performAfterDelay: 5] delayedMessage];

* ''-ignoreExceptions''
Traps and ignores any exception that may occur during execution of the argument message.

[[someArray ignoreExceptions] messageThatMayRaiseAnException];

* ''-ifResponds''
Sends the argument message only if the receiver reponds to it.
Instead of writing

if( [receiver respondsToSelector: @selector(foobar)] ) [receiver foobar]

you simply use

[[receiver ifResponds] foobar].

[[Category:Objective-C]]
[[Category:Snippets]]

NSArray

2009-05-12T08:00:49Z

Newacct: /* From a List */

[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSArray.html#class$NSArray NSArray] is an immutable, integer indexed, array of objects.

== Creating Arrays ==

=== From a List ===

The most common method to create an array is to just pass it a list:

NSArray *array = [NSArray arrayWithObjects: @"John", @"Bob", [NSNull null], @"Jane", nil];

When creating arrays remember that any kind of object can be included, but only objects can be included. Note that <code>nil</code> values cannot be included in an array; you should use the [[NSNull|<code>[NSNull null]</code>]] dummy object instead.

Note that when you provide a variable-length list of objects in Objective-C, you need to "terminate" the list with <code>nil</code>. Otherwise, the function has no way of knowing how many arguments there are.

=== Copy an Array ===

A copy of an array can be done simply by doing the following:

NSArray *array1 = [NSArray arrayWithObjects: @"John", @"Bob", [NSNull null], @"Jane", nil];
NSArray *array2 = [NSArray arrayWithArray: array1];

=== From an Array ===

An array object can be made with a regular array of objects, as shown in the following example:

id array1[4] = {@"John", @"Bob", [NSNull null], @"Jane"};
NSArray *array2 = [NSArray arrayWithObjects: array1 count: 4];

Count being the number of objects from the array to be used.

== Code chunks ==

=== Create index dictionary ===

Following NSArray category method creates a dictionary which works as an index by an attribute of contained objects. It uses [[Key Value Coding]].

- (NSDictionary *)indexDictionaryForKey:(NSString *)key
{
NSMutableDictionary *dict = [[NSMutableDictionary alloc] init];
NSDictionary *retval;
NSEnumerator *enumerator;
id object;

enumerator = [self objectEnumerator];

while( (object = [enumerator nextObject]) )
{
[dict setObject:object forKey:[object valueForKey:key]];
}

retval = [[NSDictionary alloc] initWithDictionary:dict];
RELEASE(dict);

return AUTORELEASE(retval);
}

== See Also ==

*[[NSMutableArray]]
*[[NSEnumerator]]

[[Category:Foundation]]
[[Category:Snippets]]

NSEnumerator

2009-05-12T06:28:51Z

Newacct: /* Using NSEnumerator */

[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSEnumerator.html#class$NSEnumerator NSEnumerator] in gnustep-base allow for iteration over collection.

== Using NSEnumerator ==

The following example demonstrates the use of NSEnumerator with an [[NSArray]] object:

NSArray *aArray = [NSArray arrayWithObjects: @"John", @"Bob", @"Jane", nil];
NSEnumerator *enumerator = [aArray objectEnumerator];
id obj;

while(obj = [enumerator nextObject])
doSomethingWithObject( obj );

== Getting an NSEnumerator from a Collection ==

The [[NSArray]], [[NSSet]], and [[NSDictionary]] collection objects all include the -objectEnumerator method.
[[NSDictionary]] also includes -keyEnumerator, which enumerates over the dictionary keys instead of the objects.

[[Category:Foundation]]
[[Category:Snippets]]

NSString

2009-05-12T04:51:34Z

Newacct: /* Substrings */

Strings in GNUstep use the [http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSString.html#class$NSString NSString] class in gnustep-base.
NSString is a immutable class, meaning it cannot change.
For mutable strings, see [[NSMutableString]].
See the reference manual for gnustep-base for more details about NSString.

== Constructing Strings ==

=== Constant Strings ===

As you can create static instances of char* plain C, you can create strings in GNUstep that automatically flatten out to be static instances of NSString. This is done by preceding the quoted string by an "at" symbol ('@'). For example:

NSString * myString = @"This is an example of a string.";
NSLog(myString);

myString is now an NSString object, and can have methods called on it like any other string.

=== Copy Strings ===

You can also make a copy of a string as shown in the following example:

NSString *myString = @"This is an example of a string.";
NSString *newString = [NSString stringWithString: myString];

=== C Strings ===

Or if you already have a C string you can convert it to a NSString object as follows:

char *myString = "This is a C string.";
...
NSString *NSString newString1 = [NSString stringWithCString: myString encoding: [NSString defaultCStringEncoding]];
// Or:
NSString *NSString newString2 = [NSString stringWithUTF8String: myString];

Note that using [NSString stringWithCString] is deprecated!

=== Formated Strings ===

A more flexable way of creating a string, using C style format flags follows:

NSString *myString = [NSString stringWithFormat: @"This is an%@ of a string with %d integer.", @" example", 1];

== Getting a C String ==

You can convert an NSString object to a plain C string using the cStringUsingEncoding: method. For example:

NSString *newString = @"This is a test string.";
char *theString;

theString = [newString cStringWithEncoding:[NSString defaultCStringEncoding]];

or:

theString = [newString UTF8String];

Note that using [string cString] is deprecated!

== Reading and Writing Files With String ==

The following example shows how you would use files with NSString:

// Read in the file.
NSString *aString = [NSString stringWithContentsOfFile: @"infile.txt"];
// Do something with our new string.
aString = ''doSomething''(aString);
// And finally save our changes to a file.
if([aString writeToFile: @"outfile" atomically: YES])
// Success code.
else
// Error code.

== Substrings ==

If you have a delimiter for breaking the string up, the easiest method to use would be the [string componentsSeparatedByString:] method.
The following example demonstrates this:

NSString *string = @"John, Bob, Jane";
NSArray *strings = [string componentsSeparatedByString: @", "];
// give us the array {@"John", @"Bob", @"Jane"}

An array of string can also be joined together with the [array componentsJoinedByString:] method as follows:

NSArray *strings = [NSArray arrayWithObjects: @"John", @"Bob", @"Jane", nil];
NSString *string = [strings componentsJoinedByString: @", "];
// creating the string @"John, Bob, Jane"

If you need something more advanced [[NSScanner]] will be need.

----

One the other hand, if you know the indexes ahead of time one of three substring methods could be used, as demonstrated in the following example:

NSString *string = @"John, Bob, Jane";

NSLog([string substringFromIndex: 6]);
// Get the last six characters in the string (", Jane")

NSLog([string substringToIndex: 6]);
// Get the first six characters in the string ("John, ")

NSLog([string substringWithRange: NSMakeRange(3, 6)]);
// Starting at index three get a string of length six ("hn, Bo")

[[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/TypesAndConstants.html#type$NSRange NSRange]] is a structure used mainly in string and arrays, defining the beginning index and the offset.

[[Category:Foundation]]
[[Category:Snippets]]

NSMutableString

2009-05-12T04:50:54Z

Newacct:

[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSString.html#class$NSMutableString NSMutableString] inherits from [[NSString]], but includes methods for changing the string.

== Editing Strings ==

=== Adding To Strings ===

Strings can be added on to by appending the new substring to the end, or by inserting it any where in the middle.

==== Appending Strings ====

The simplest way to edit a string is by appending to the end of the string, as shown here:

NSMutableString *str = [NSMutableString stringWithString: @"short string"];
[str appendString: @" made longer"];
// str is now = @"short string made longer"

C style formating flags can also be used as follows:

NSMutableString *str = [NSMutableString stringWithString: @"short string"];
[str appendFormat: @" made longer %@.", @"with formating"];
// str is now = @"short string made longer with formating."

==== Inserting Substrings ====

The more advanced method of adding to strings in by insertion, as demonstrated here:

NSMutableString *str = [NSMutableString stringWithString: @"a string"];
[str insertString: @"new " atIndex: 2];
// str is now = @"a new string"

=== Replacing Substrings ===

A certain substring can be replaced with a new one as follows:

NSMutableString *str = [NSMutableString stringWithString: @"a old string"];
[str replaceString: @"old" withString: @"new];
// str is now = @"a new string"

This can also be done with ranges:

NSMutableString *str = [NSMutableString stringWithString: @"a old string"];
// start at index 2 and include the next 3 characters
[str replaceCharactersInRange: NSMakeRange(2, 3) withString: @"new];
// str is now = @"a new string"

[[Category:Foundation]]
[[Category:Snippets]]

NSString

2009-05-12T04:25:32Z

Newacct: /* Substrings */

Strings in GNUstep use the [http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSString.html#class$NSString NSString] class in gnustep-base.
NSString is a immutable class, meaning it cannot change.
For mutable strings, see [[NSMutableString]].
See the reference manual for gnustep-base for more details about NSString.

== Constructing Strings ==

=== Constant Strings ===

As you can create static instances of char* plain C, you can create strings in GNUstep that automatically flatten out to be static instances of NSString. This is done by preceding the quoted string by an "at" symbol ('@'). For example:

NSString * myString = @"This is an example of a string.";
NSLog(myString);

myString is now an NSString object, and can have methods called on it like any other string.

=== Copy Strings ===

You can also make a copy of a string as shown in the following example:

NSString *myString = @"This is an example of a string.";
NSString *newString = [NSString stringWithString: myString];

=== C Strings ===

Or if you already have a C string you can convert it to a NSString object as follows:

char *myString = "This is a C string.";
...
NSString *NSString newString1 = [NSString stringWithCString: myString encoding: [NSString defaultCStringEncoding]];
// Or:
NSString *NSString newString2 = [NSString stringWithUTF8String: myString];

Note that using [NSString stringWithCString] is deprecated!

=== Formated Strings ===

A more flexable way of creating a string, using C style format flags follows:

NSString *myString = [NSString stringWithFormat: @"This is an%@ of a string with %d integer.", @" example", 1];

== Getting a C String ==

You can convert an NSString object to a plain C string using the cStringUsingEncoding: method. For example:

NSString *newString = @"This is a test string.";
char *theString;

theString = [newString cStringWithEncoding:[NSString defaultCStringEncoding]];

or:

theString = [newString UTF8String];

Note that using [string cString] is deprecated!

== Reading and Writing Files With String ==

The following example shows how you would use files with NSString:

// Read in the file.
NSString *aString = [NSString stringWithContentsOfFile: @"infile.txt"];
// Do something with our new string.
aString = ''doSomething''(aString);
// And finally save our changes to a file.
if([aString writeToFile: @"outfile" atomically: YES])
// Success code.
else
// Error code.

== Substrings ==

If you have a delimiter for breaking the string up, the easiest method to use would be the [string componentsSeparatedByString:] method.
The following example demonstrates this:

NSString *string = @"John, Bob, Jane";
NSArray *strings = [string componentsSeparatedByString: @", "];
// give us the array {@"John", @"Bob", @"Jane"}

An array of string can also be joined together with the [array componentsJoinedByString:] method as follows:

NSArray *strings = [NSArray arrayWithObjects: @"John", @"Bob", @"Jane", nil];
NSString *string = [strings componentsJoinedByString: @", "];
// creating the string @"John, Bob, Jane"

If you need something more advanced [[NSScanner]] will be need.

----

One the other hand, if you know the indexes ahead of time one of three substring methods could be used, as demonstrated in the following example:

NSString *string = @"John, Bob, Jane";

NSLog([string substringFromIndex: 6]);
// Get the last six characters in the string (", Jane")

NSLog([string substringToIndex: 6]);
// Get the first six characters in the string ("John, ")

NSRange range = {3, 6};
NSLog([string substringWithRange: range]);
// Starting at index three get a string of length six ("hn, Bo")
// This can be written on one line as:
// NSLog([string substringWithRange: NSMakeRange(3, 6)]);

[[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/TypesAndConstants.html#type$NSRange NSRange]] is a structure used mainly in string and arrays, defining the beginning index and the offset.

[[Category:Foundation]]
[[Category:Snippets]]

NSArray

2009-05-12T04:21:35Z

Newacct:

[http://www.gnustep.org/resources/documentation/Developer/Base/Reference/NSArray.html#class$NSArray NSArray] is an immutable, integer indexed, array of objects.

== Creating Arrays ==

=== From a List ===

The most common method to create an array is to just pass it a list:

NSArray *array = [NSArray arrayWithObjects: @"John", @"Bob", [NSNull null], @"Jane", nil];

When creating arrays remember that any kind of object can be included, but only objects can be included. Note that <code>nil</code> values cannot be included in an array; you should use the <code>[[[NSNull]] null]</code> dummy object instead.

Note that when you provide a variable-length list of objects in Objective-C, you need to "terminate" the list with <code>nil</code>. Otherwise, the function has no way of knowing how many arguments there are.

=== Copy an Array ===

A copy of an array can be done simply by doing the following:

NSArray *array1 = [NSArray arrayWithObjects: @"John", @"Bob", [NSNull null], @"Jane", nil];
NSArray *array2 = [NSArray arrayWithArray: array1];

=== From an Array ===

An array object can be made with a regular array of objects, as shown in the following example:

id array1[4] = {@"John", @"Bob", [NSNull null], @"Jane"};
NSArray *array2 = [NSArray arrayWithObjects: array1 count: 4];

Count being the number of objects from the array to be used.

== Code chunks ==

=== Create index dictionary ===

Following NSArray category method creates a dictionary which works as an index by an attribute of contained objects. It uses [[Key Value Coding]].

- (NSDictionary *)indexDictionaryForKey:(NSString *)key
{
NSMutableDictionary *dict = [[NSMutableDictionary alloc] init];
NSDictionary *retval;
NSEnumerator *enumerator;
id object;

enumerator = [self objectEnumerator];

while( (object = [enumerator nextObject]) )
{
[dict setObject:object forKey:[object valueForKey:key]];
}

retval = [[NSDictionary alloc] initWithDictionary:dict];
RELEASE(dict);

return AUTORELEASE(retval);
}

== See Also ==

*[[NSMutableArray]]
*[[NSEnumerator]]

[[Category:Foundation]]
[[Category:Snippets]]