ObjFW  Check-in [012cee4f80]

Overview
Comment:More documentation improvements.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 012cee4f806875f16389ee12b5d7379a314e7ac15d5d1e9330e6d11c72e907d7
User & Date: js on 2009-12-03 10:29:45
Other Links: manifest | tags
Context
2009-12-03
11:51
Add -[componentsJoinedByString:] to OFArray. check-in: fb651428aa user: js tags: trunk
10:29
More documentation improvements. check-in: 012cee4f80 user: js tags: trunk
10:14
Add documentation for OFXMLParser. check-in: a0b676019d user: js tags: trunk
Changes

Modified src/OFArray.h from [6a0650261e] to [41841f3a03].

52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 * \return An initialized OFArray
 */
- initWithObject: (OFObject*)obj;

/**
 * Initializes an OFArray with the specified objects.
 *
 * \param obj The first object
 * \return An initialized OFArray
 */
- initWithObjects: (OFObject*)first, ...;

/**
 * Initializes an OFArray with the specified object and a va_list.
 *







|







52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 * \return An initialized OFArray
 */
- initWithObject: (OFObject*)obj;

/**
 * Initializes an OFArray with the specified objects.
 *
 * \param first The first object
 * \return An initialized OFArray
 */
- initWithObjects: (OFObject*)first, ...;

/**
 * Initializes an OFArray with the specified object and a va_list.
 *

Modified src/OFDataArray.h from [8c7292e6d0] to [fc048ad743].

59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

/**
 * Compares the OFDataArray to another object.
 *
 * \param ary A data array to compare with
 * \return An of_comparsion_result_t
 */
- (of_comparison_result_t)compare: (OFDataArray*)obj;

/**
 * Returns a specific item of the OFDataArray.
 *
 * \param index The number of the item to return
 * \return The specified item of the OFDataArray
 */







|







59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

/**
 * Compares the OFDataArray to another object.
 *
 * \param ary A data array to compare with
 * \return An of_comparsion_result_t
 */
- (of_comparison_result_t)compare: (OFDataArray*)ary;

/**
 * Returns a specific item of the OFDataArray.
 *
 * \param index The number of the item to return
 * \return The specified item of the OFDataArray
 */

Modified src/OFDictionary.h from [5518d5ed5f] to [8b63f44b4d].

122
123
124
125
126
127
128

129
130
131
132
133
134
135
- initWithKeysAndObjects: (OFObject <OFCopying>*)first, ...;

/**
 * Initializes an already allocated OFDictionary with the specified key and
 * va_list.
 *
 * \param first The first key

 * \return A new initialized OFDictionary
 */
- initWithKey: (OFObject <OFCopying>*)first
      argList: (va_list)args;

/**
 * \param key The key whose object should be returned







>







122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
- initWithKeysAndObjects: (OFObject <OFCopying>*)first, ...;

/**
 * Initializes an already allocated OFDictionary with the specified key and
 * va_list.
 *
 * \param first The first key
 * \param args A va_list of the other arguments
 * \return A new initialized OFDictionary
 */
- initWithKey: (OFObject <OFCopying>*)first
      argList: (va_list)args;

/**
 * \param key The key whose object should be returned

Modified src/OFExceptions.h from [4830360b39] to [d069b97d96].

38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
- (OFString*)string;
@end

/**
 * The OFException class is the base class for all exceptions in ObjFW.
 *
 * IMPORTANT: Exceptions do NOT use OFAutoreleasePools and can't be autoreleased
 * either! You have to make sure to dealloc the exception in your @catch block!
 */
@interface OFException: OFObject
{
	Class	 class_;
	OFString *string;
}








|







38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
- (OFString*)string;
@end

/**
 * The OFException class is the base class for all exceptions in ObjFW.
 *
 * IMPORTANT: Exceptions do NOT use OFAutoreleasePools and can't be autoreleased
 * either! You have to make sure to dealloc the exception in your \@catch block!
 */
@interface OFException: OFObject
{
	Class	 class_;
	OFString *string;
}

557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
	OFString *src;
	OFString *dest;
	int err;
}

/**
 * \param class_ The class of the object which caused the exception
 * \param source The source for the link
 * \param destination The destination for the link
 * \return A new link failed exception
 */
+ newWithClass: (Class)class_
	source: (OFString*)src
   destination: (OFString*)dest;

/**
 * Initializes an already allocated link failed exception.
 *
 * \param class_ The class of the object which caused the exception
 * \param source The source for the link
 * \param destination The destination for the link
 * \return An initialized link failed exception
 */
- initWithClass: (Class)class_
	 source: (OFString*)src
    destination: (OFString*)dest;

/**







|
|










|
|







557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
	OFString *src;
	OFString *dest;
	int err;
}

/**
 * \param class_ The class of the object which caused the exception
 * \param src The source for the link
 * \param dest The destination for the link
 * \return A new link failed exception
 */
+ newWithClass: (Class)class_
	source: (OFString*)src
   destination: (OFString*)dest;

/**
 * Initializes an already allocated link failed exception.
 *
 * \param class_ The class of the object which caused the exception
 * \param src The source for the link
 * \param dest The destination for the link
 * \return An initialized link failed exception
 */
- initWithClass: (Class)class_
	 source: (OFString*)src
    destination: (OFString*)dest;

/**
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
	OFString *src;
	OFString *dest;
	int err;
}

/**
 * \param class_ The class of the object which caused the exception
 * \param source The source for the symlink
 * \param destination The destination for the symlink
 * \return A new symlink failed exception
 */
+ newWithClass: (Class)class_
	source: (OFString*)src
   destination: (OFString*)dest;

/**
 * Initializes an already allocated symlink failed exception.
 *
 * \param class_ The class of the object which caused the exception
 * \param source The source for the symlink
 * \param destination The destination for the symlink
 * \return An initialized symlink failed exception
 */
- initWithClass: (Class)class_
	 source: (OFString*)src
    destination: (OFString*)dest;

/**







|
|










|
|







605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
	OFString *src;
	OFString *dest;
	int err;
}

/**
 * \param class_ The class of the object which caused the exception
 * \param src The source for the symlink
 * \param dest The destination for the symlink
 * \return A new symlink failed exception
 */
+ newWithClass: (Class)class_
	source: (OFString*)src
   destination: (OFString*)dest;

/**
 * Initializes an already allocated symlink failed exception.
 *
 * \param class_ The class of the object which caused the exception
 * \param src The source for the symlink
 * \param dest The destination for the symlink
 * \return An initialized symlink failed exception
 */
- initWithClass: (Class)class_
	 source: (OFString*)src
    destination: (OFString*)dest;

/**

Modified src/OFFile.h from [b5cc441e5f] to [9d72f8d05d].

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
- (size_t)readNItems: (size_t)nitems
	      ofSize: (size_t)size
	  intoBuffer: (char*)buf;

/**
 * Writes from a buffer into the file.
 *
 * \param buf The buffer from which the data is written to the file
 * \param size The size of the data that should be written
 * \param nitem The number of items to write
 * \return The number of bytes written
 */
- (size_t)writeNItems: (size_t)nitems
	       ofSize: (size_t)size
	   fromBuffer: (const char*)buf;
@end








|

|







140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
- (size_t)readNItems: (size_t)nitems
	      ofSize: (size_t)size
	  intoBuffer: (char*)buf;

/**
 * Writes from a buffer into the file.
 *
 * \param nitems The number of items to write
 * \param size The size of the data that should be written
 * \param buf The buffer from which the data is written to the file
 * \return The number of bytes written
 */
- (size_t)writeNItems: (size_t)nitems
	       ofSize: (size_t)size
	   fromBuffer: (const char*)buf;
@end

Modified src/OFIterator.h from [5f1cbb4f52] to [c4383df0ad].

45
46
47
48
49
50
51



52
53
54
55
56
57
58

/**
 * Resets the iterator, so the next call to nextObject returns the first again.
 */
- reset;
@end




@interface OFDictionary (OFIterator)
/**
 * Creates an OFIterator for the dictionary.
 *
 * It will copy the data of the OFDictionary so that OFIterator will always
 * operate on the data that was present when it was created. If you changed the
 * OFDictionary and want to operate on the new data, you need to create a new







>
>
>







45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

/**
 * Resets the iterator, so the next call to nextObject returns the first again.
 */
- reset;
@end

/**
 * The OFIterator category adds functions to get an interator to OFDictionary.
 */
@interface OFDictionary (OFIterator)
/**
 * Creates an OFIterator for the dictionary.
 *
 * It will copy the data of the OFDictionary so that OFIterator will always
 * operate on the data that was present when it was created. If you changed the
 * OFDictionary and want to operate on the new data, you need to create a new

Modified src/OFMutableArray.h from [5a4d04ab53] to [76c7e15d21].

62
63
64
65
66
67
68
69
70
71

/**
 * Removes the specified amount of objects at the specified index.
 *
 * \param nobjects The number of objects to remove
 * \param index The index at which the objects are removed
 */
- removeNObjects: (size_t)nitems
	 atIndex: (size_t)index;
@end







|


62
63
64
65
66
67
68
69
70
71

/**
 * Removes the specified amount of objects at the specified index.
 *
 * \param nobjects The number of objects to remove
 * \param index The index at which the objects are removed
 */
- removeNObjects: (size_t)nobjects
	 atIndex: (size_t)index;
@end

Modified src/OFNumber.h from [2ef00800e8] to [fb94e23de6].

192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
/**
 * \param uintmax An uintmax_t which the OFNumber should contain
 * \return A new autoreleased OFNumber
 */
+ numberWithUIntMax: (uintmax_t)uintmax;

/**
 * \param ptrdifff A ptrdiff_t which the OFNumber should contain
 * \return A new autoreleased OFNumber
 */
+ numberWithPtrDiff: (ptrdiff_t)ptrdiff;

/**
 * \param intptr An intptr_t which the OFNumber should contain
 * \return A new autoreleased OFNumber







|







192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
/**
 * \param uintmax An uintmax_t which the OFNumber should contain
 * \return A new autoreleased OFNumber
 */
+ numberWithUIntMax: (uintmax_t)uintmax;

/**
 * \param ptrdiff A ptrdiff_t which the OFNumber should contain
 * \return A new autoreleased OFNumber
 */
+ numberWithPtrDiff: (ptrdiff_t)ptrdiff;

/**
 * \param intptr An intptr_t which the OFNumber should contain
 * \return A new autoreleased OFNumber

Modified src/OFObject.h from [d628e82c53] to [a51d330892].

101
102
103
104
105
106
107

108
109
110
111
112
113
114
115
116
 *	   or nil if it isn't implemented
 */
+ (IMP)instanceMethodForSelector: (SEL)selector;

/**
 * Replaces a method implementation with another implementation.
 *

 * \param selector The selector of the method to replace
 * \param imp The new implementation for the method
 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newimp
	       forMethod: (SEL)selector;

/**
 * Replaces a method with a method from another class.







>

<







101
102
103
104
105
106
107
108
109

110
111
112
113
114
115
116
 *	   or nil if it isn't implemented
 */
+ (IMP)instanceMethodForSelector: (SEL)selector;

/**
 * Replaces a method implementation with another implementation.
 *
 * \param newimp The new implementation for the method
 * \param selector The selector of the method to replace

 * \return The old implementation
 */
+ (IMP)setImplementation: (IMP)newimp
	       forMethod: (SEL)selector;

/**
 * Replaces a method with a method from another class.

Modified src/OFTCPSocket.h from [553ceb6fb7] to [852a45db8a].

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
	    onNode: (OFString*)node;

/**
 * Bind socket on the specified node and service.
 *
 * \param service The service to bind
 * \param node The node to bind to
 * \param protocol The protocol to use (AF_INET or AF_INET6)
 */
- bindService: (OFString*)service
       onNode: (OFString*)node
   withFamily: (int)family;

/**
 * Listen on the socket.







|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
	    onNode: (OFString*)node;

/**
 * Bind socket on the specified node and service.
 *
 * \param service The service to bind
 * \param node The node to bind to
 * \param family The family to use (AF_INET or AF_INET6)
 */
- bindService: (OFString*)service
       onNode: (OFString*)node
   withFamily: (int)family;

/**
 * Listen on the socket.

Modified src/OFXMLParser.h from [71a1057f3c] to [3fccc379ee].

19
20
21
22
23
24
25

26
27
28
29
30
31
32
33
34
35
36
37
38
39

40
41
42
43
44
45
46
47
48
49
50
51

52
53
54
55
56
57
58
59

60
61
62
63
64
65
66
67
68
69
70

71
72
73
74
75
76
77
/**
 * A protocol that needs to be implemented by delegates for OFXMLParser.
 */
@protocol OFXMLParserDelegate
/**
 * This callback is called when the XML parser found the start of a new tag.
 *

 * \param name The name of the tag which just started
 * \param prefix The prefix of the tag which just started or nil
 * \param ns The namespace of the tag which just started or nil
 * \param attrs The attributes included in the tag which just started or nil
 */
-     (void)xmlParser: (OFXMLParser*)parser
  didStartTagWithName: (OFString*)name
	       prefix: (OFString*)prefix
	    namespace: (OFString*)ns
	   attributes: (OFArray*)attrs;

/**
 * This callback is called when the XML parser found the end of a tag.
 *

 * \param name The name of the tag which just ended
 * \param prefix The prefix of the tag which just ended or nil
 * \param ns The namespace of the tag which just ended or nil
 */
-   (void)xmlParser: (OFXMLParser*)parser
  didEndTagWithName: (OFString*)name
	     prefix: (OFString*)prefix
	  namespace: (OFString*)ns;

/**
 * This callback is called when the XML parser found a string.
 *

 * \param string The string the XML parser found
 */
- (void)xmlParser: (OFXMLParser*)parser
      foundString: (OFString*)string;

/**
 * This callback is called when the XML parser found a comment.
 *

 * \param comment The comment the XML parser found
 */
- (void)xmlParser: (OFXMLParser*)parser
     foundComment: (OFString*)comment;

/**
 * This callback is called when the XML parser found an entity it doesn't know.
 * The callback is supposed to return a substitution for the entity or nil if
 * it is not known to the callback as well, in which case an exception will be
 * risen.
 *

 * \param entity The name of the entity the XML parser didn't know
 * \return A substitution for the entity or nil
 */
-    (OFString*)xmlParser: (OFXMLParser*)parser
  foundUnknownEntityNamed: (OFString*)entity;
@end








>














>












>








>











>







19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
/**
 * A protocol that needs to be implemented by delegates for OFXMLParser.
 */
@protocol OFXMLParserDelegate
/**
 * This callback is called when the XML parser found the start of a new tag.
 *
 * \param parser The parser which found a new tag
 * \param name The name of the tag which just started
 * \param prefix The prefix of the tag which just started or nil
 * \param ns The namespace of the tag which just started or nil
 * \param attrs The attributes included in the tag which just started or nil
 */
-     (void)xmlParser: (OFXMLParser*)parser
  didStartTagWithName: (OFString*)name
	       prefix: (OFString*)prefix
	    namespace: (OFString*)ns
	   attributes: (OFArray*)attrs;

/**
 * This callback is called when the XML parser found the end of a tag.
 *
 * \param parser The parser which found the end of a tag
 * \param name The name of the tag which just ended
 * \param prefix The prefix of the tag which just ended or nil
 * \param ns The namespace of the tag which just ended or nil
 */
-   (void)xmlParser: (OFXMLParser*)parser
  didEndTagWithName: (OFString*)name
	     prefix: (OFString*)prefix
	  namespace: (OFString*)ns;

/**
 * This callback is called when the XML parser found a string.
 *
 * \param parser The parser which found a string
 * \param string The string the XML parser found
 */
- (void)xmlParser: (OFXMLParser*)parser
      foundString: (OFString*)string;

/**
 * This callback is called when the XML parser found a comment.
 *
 * \param parser The parser which found a comment
 * \param comment The comment the XML parser found
 */
- (void)xmlParser: (OFXMLParser*)parser
     foundComment: (OFString*)comment;

/**
 * This callback is called when the XML parser found an entity it doesn't know.
 * The callback is supposed to return a substitution for the entity or nil if
 * it is not known to the callback as well, in which case an exception will be
 * risen.
 *
 * \param parser The parser which found an unknown entity
 * \param entity The name of the entity the XML parser didn't know
 * \return A substitution for the entity or nil
 */
-    (OFString*)xmlParser: (OFXMLParser*)parser
  foundUnknownEntityNamed: (OFString*)entity;
@end

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 * unescape XML. The callback is supposed to return a substitution for the
 * entity or nil if it is not known to the callback as well, in which case an
 * exception will be risen.
 *
 * \param entity The name of the entity that is unknown
 * \return A substitution for the entity or nil
 */
- (OFString*)foundUnknownEntityNamed: (OFString*)entitiy;
@end

/**
 * An event-based XML parser which calls the delegate's callbacks as soon as
 * it finds something, thus suitable for streams as well.
 */
@interface OFXMLParser: OFObject <OFXMLUnescapingDelegate>







|







90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 * unescape XML. The callback is supposed to return a substitution for the
 * entity or nil if it is not known to the callback as well, in which case an
 * exception will be risen.
 *
 * \param entity The name of the entity that is unknown
 * \return A substitution for the entity or nil
 */
- (OFString*)foundUnknownEntityNamed: (OFString*)entity;
@end

/**
 * An event-based XML parser which calls the delegate's callbacks as soon as
 * it finds something, thus suitable for streams as well.
 */
@interface OFXMLParser: OFObject <OFXMLUnescapingDelegate>