- * A simple retain/release mechanism is not very interesting ...
- * so it's spiced up with autorelease pools. You can use the
+ * A simple retain/release mechanism has problems with passing objects
+ * from one scope to another,
+ * so it's augmented with autorelease pools. You can use the
* AUTORELEASE() macro to call the [NSObject-autorelease]
* method, which adds an object to the current autorelease pool by
* calling [NSAutoreleasePool+addObject:]. Top-level class defining methods for use when archiving (encoding)
+ * objects to a byte array or file, and when restoring (decoding) objects.
+ * Generally only subclasses of this class are used directly - [NSArchiver],
+ * [NSUnarchiver], [NSKeyedArchiver], [NSKeyedUnarchiver], or [NSPortCoder].
+ * Class for generating text representations of [NSDate]s and
+ * [NSCalendarDate]s, and for converting strings into instances of these
+ * objects. Note that [NSDate] and [NSCalendarDate] do contain some
+ * string conversion methods, but using this class provides more control
+ * over conversion. See the [NSFormatter] documentation for description of the basic methods
+ * for formatting and parsing that are available. The basic format of a format string uses "%" codes to represent
+ * components of the date. Thus, for example,
@@ -127,7 +128,7 @@ typedef struct autorelease_array_list
*
- * NB. The returned object may not actualy be the same as the
+ * NB. The returned object may not actually be the same as the
* receiver ... sometimes an init method releases the original
* receiver and returns an alternative.
* BITMAP_SIZE
+ * long, which is currently 2^16 / 8.
+ */
- (id) initWithBitmap: (NSData*)bitmap;
@end
+/**
+ * Mutable version of [NSBitmapCharSet].
+ */
@interface NSMutableBitmapCharSet : NSMutableCharacterSet
{
char _data[BITMAP_SIZE];
}
+/**
+ * Init directly with bitmap data. bitmap should be BITMAP_SIZE
+ * long, which is currently 2^16 / 8.
+ */
- (id) initWithBitmap: (NSData*)bitmap;
@end
diff --git a/Headers/Foundation/NSBundle.h b/Headers/Foundation/NSBundle.h
index ab0134301..eabefd3d7 100644
--- a/Headers/Foundation/NSBundle.h
+++ b/Headers/Foundation/NSBundle.h
@@ -140,7 +140,7 @@ GS_EXPORT NSString* NSLoadedClasses;
inDirectory: (NSString*)bundlePath;
/**
- This method has been depreciated. Version numbers were never implemented
+ This method has been deprecated. Version numbers were never implemented
so this method behaves exactly like +pathForResource:ofType:inDirectory:.
*/
+ (NSString*) pathForResource: (NSString*)name
@@ -173,6 +173,10 @@ GS_EXPORT NSString* NSLoadedClasses;
*/
- (Class) principalClass;
+/**
+ * Not implemented. Create an instance and call the corresponding instance
+ * method instead.
+ */
+ (NSArray*) pathsForResourcesOfType: (NSString*)extension
inDirectory: (NSString*)bundlePath;
@@ -241,14 +245,29 @@ GS_EXPORT NSString* NSLoadedClasses;
- (void) setBundleVersion: (unsigned)version;
#ifndef STRICT_OPENSTEP
+/**
+ * Returns subarray of given array containing those localizations that are
+ * used to locate resources given environment and user preferences.
+ */
+ (NSArray *) preferredLocalizationsFromArray: (NSArray *)localizationsArray;
+/**
+ * Returns subarray of given array containing those localizations that are
+ * used to locate resources given environment given user preferences (which
+ * are used instead of looking up the preferences of the current user).
+ */
+ (NSArray *) preferredLocalizationsFromArray: (NSArray *)localizationsArray
forPreferences: (NSArray *)preferencesArray;
- (BOOL) isLoaded;
+/**
+ * Not implemented.
+ */
- (NSArray*) pathsForResourcesOfType: (NSString*)extension
inDirectory: (NSString*)bundlePath
forLocalization: (NSString*)localizationName;
+/**
+ * Not implemented.
+ */
- (NSString*) pathForResource: (NSString*)name
ofType: (NSString*)ext
inDirectory: (NSString*)bundlePath
@@ -285,6 +304,10 @@ GS_EXPORT NSString* NSLoadedClasses;
@end
#ifndef NO_GNUSTEP
+/**
+ * Augments [NSBundle], including methods for handling libraries in the GNUstep
+ * fashion, for rapid localization, and other purposes.
+ */
@interface NSBundle (GNUstep)
/** This method is an experimental GNUstep extension, and
@@ -301,15 +324,15 @@ GS_EXPORT NSString* NSLoadedClasses;
+ (NSString*) _gnustep_target_os;
+ (NSString*) _library_combo;
-/** Find a resource in the "Library" directory */
+/** Find a resource in the "Library" directory. */
+ (NSString*) pathForLibraryResource: (NSString*)name
ofType: (NSString*)ext
inDirectory: (NSString*)bundlePath;
-/** Depreciated. Use +bundleForLibrary: instead. */
+/** Deprecated. Use +bundleForLibrary: instead. */
+ (NSBundle*) gnustepBundle;
-/** Depreciated. Use +pathForLibraryResource:ofType:inDirectory:
+/** Deprecated. Use +pathForLibraryResource:ofType:inDirectory:
or +bundleForLibrary: instead. */
+ (NSString*) pathForGNUstepResource: (NSString*)name
ofType: (NSString*)ext
diff --git a/Headers/Foundation/NSCalendarDate.h b/Headers/Foundation/NSCalendarDate.h
index ccc80abe4..18f43c017 100644
--- a/Headers/Foundation/NSCalendarDate.h
+++ b/Headers/Foundation/NSCalendarDate.h
@@ -106,7 +106,20 @@
#ifndef NO_GNUSTEP
+/**
+ * Adds -weekOfYear method.
+ */
@interface NSCalendarDate (GSCategories)
+/**
+ * The ISO standard week of the year is based on the first week of the
+ * year being that week (starting on monday) for which the thursday
+ * is on or after the first of january.
+ * This has the effect that, if january first is a friday, saturday or
+ * sunday, the days of that week (up to and including the sunday) are
+ * considered to be in week 53 of the preceeding year. Similarly if the
+ * last day of the year is a monday tuesday or wednesday, these days are
+ * part of week 1 of the next year.
+ */
- (int) weekOfYear;
@end
diff --git a/Headers/Foundation/NSCoder.h b/Headers/Foundation/NSCoder.h
index 6b67abd42..4e7dcaa9f 100644
--- a/Headers/Foundation/NSCoder.h
+++ b/Headers/Foundation/NSCoder.h
@@ -30,51 +30,191 @@
@class NSMutableData, NSData, NSString;
+/**
+ * NSPortCoder is used within the distributed objects
+ * framework. For archiving to/from disk, the Keyed... classes are
+ * preferred for new implementations, since they provide greater
+ * forward/backward compatibility in the face of class changes.@encode(...)' compile-time operator.
+ * Usually this is used for primitives though it can be used for objects as
+ * well.
+ */
- (void) encodeArrayOfObjCType: (const char*)type
count: (unsigned)count
at: (const void*)array;
+
+/**
+ * Can be ignored.
+ */
- (void) encodeBycopyObject: (id)anObject;
+/**
+ * Can be ignored.
+ */
- (void) encodeByrefObject: (id)anObject;
+
+/**
+ * Stores bytes directly into archive.
+ */
- (void) encodeBytes: (void*)d length: (unsigned)l;
+
+/**
+ * Encode object if it is/will be encoded unconditionally by this coder,
+ * otherwise store a nil.
+ */
- (void) encodeConditionalObject: (id)anObject;
+
+/**
+ * Encode an instance of [NSData].
+ */
- (void) encodeDataObject: (NSData*)data;
+
+/**
+ * Encodes a generic object. This will usually result in an [NSCoding
+ * -encodeWithCoder:] message being sent to anObject so it can encode itself.
+ */
- (void) encodeObject: (id)anObject;
+
+/**
+ * Encodes a property list by calling [NSSerializer -serializePropertyList:],
+ * then encoding the resulting [NSData] object.
+ */
- (void) encodePropertyList: (id)plist;
+
+/**
+ * Encodes a point structure.
+ */
- (void) encodePoint: (NSPoint)point;
+
+/**
+ * Encodes a rectangle structure.
+ */
- (void) encodeRect: (NSRect)rect;
+
+/**
+ * Store object and objects it refers to in archive (i.e., complete object
+ * graph).
+ */
- (void) encodeRootObject: (id)rootObject;
+
+/**
+ * Encodes a size structure.
+ */
- (void) encodeSize: (NSSize)size;
+
+/**
+ * Encodes structure or object of given type, which may be obtained
+ * through the '@encode(...)' compile-time operator. Usually
+ * this is used for primitives though it can be used for objects as well.
+ */
- (void) encodeValueOfObjCType: (const char*)type
at: (const void*)address;
+
+/**
+ * Multiple version of [-encodeValueOfObjCType:at:].
+ */
- (void) encodeValuesOfObjCTypes: (const char*)types,...;
// Decoding Data
+/**
+ * Decodes array of count structures or objects of given type, which may be
+ * obtained through the '@encode(...)' compile-time operator.
+ * Usually this is used for primitives though it can be used for objects as
+ * well. Objects will be retained and you must release them.
+ */
- (void) decodeArrayOfObjCType: (const char*)type
count: (unsigned)count
at: (void*)address;
+
+/**
+ * Retrieve bytes directly from archive.
+ */
- (void*) decodeBytesWithReturnedLength: (unsigned*)l;
+
+/**
+ * Decode an instance of [NSData].
+ */
- (NSData*) decodeDataObject;
+
+/**
+ * Decodes a generic object. Usually the class will be read from the
+ * archive, an object will be created through an alloc call,
+ * then that class will be sent an [NSCoding -initWithCoder:] message.
+ */
- (id) decodeObject;
+
+/**
+ * Decodes a property list from the archive previously stored through a call
+ * to [-encodePropertyList:].
+ */
- (id) decodePropertyList;
+
+/**
+ * Decodes a point structure.
+ */
- (NSPoint) decodePoint;
+
+/**
+ * Decodes a rectangle structure.
+ */
- (NSRect) decodeRect;
+
+/**
+ * Decodes a size structure.
+ */
- (NSSize) decodeSize;
+
+/**
+ * Decodes structure or object of given type, which may be obtained
+ * through the '@encode(...)' compile-time operator. Usually
+ * this is used for primitives though it can be used for objects as well,
+ * in which case you are responsible for releasing them.
+ */
- (void) decodeValueOfObjCType: (const char*)type
at: (void*)address;
+
+/**
+ * Multiple version of [-decodeValueOfObjCType:at:].
+ */
- (void) decodeValuesOfObjCTypes: (const char*)types,...;
// Managing Zones
+/**
+ * Returns zone being used to allocate memory for decoded objects.
+ */
- (NSZone*) objectZone;
+
+/**
+ * Sets zone to use for allocating memory for decoded objects.
+ */
- (void) setObjectZone: (NSZone*)zone;
// Getting a Version
+/**
+ * Returns *Step version, which is not the release version, but a large number,
+ * by specification <1000 for pre-OpenStep. This implementation returns
+ * a number based on the GNUstep major, minor, and subminor versions.
+ */
- (unsigned int) systemVersion;
+
+/**
+ * Returns current version of class (when encoding) or version of decoded
+ * class (decoded). Version comes from [NSObject -getVersion].
+ *
+ */
- (unsigned int) versionForClassName: (NSString*)className;
#ifndef STRICT_OPENSTEP
@@ -162,7 +302,7 @@
- (void) encodeBool: (BOOL) aBool forKey: (NSString*)aKey;
/**
+ * The high order four bits of each byte is encoded before the low
+ * order four bits. Capital letters 'A' to 'F' are used to represent
+ * values from 10 to 15.
+ * If you need the hexadecimal representation as raw byte data, use code
+ * like -
+ *
+ * If the string does not contain one or more pairs of hexadecimal digits
+ * then an exception is raised.
+ */
- (id) initWithHexadecimalRepresentation: (NSString*)string;
+
+/**
+ * Creates an MD5 digest of the information stored in the receiver and
+ * returns it as an autoreleased 16 byte NSData object.
+ * If you need to produce a digest of string information, you need to
+ * decide what character encoding is to be used and convert your string
+ * to a data object of that encoding type first using the
+ * [NSString-dataUsingEncoding:] method -
+ *
+ * Returns the encoded file name in namePtr if it is not null.
+ * Returns the encoded file mode in modePtr if it is not null.
+ */
- (BOOL) uudecodeInto: (NSMutableData*)decoded
name: (NSString**)namePtr
mode: (int*)modePtr;
+
+/**
+ * Encode the source data to uuencoded.
+ * Uses the supplied name as the filename in the encoded data,
+ * and says that the file mode is as specified.
+ * If no name is supplied, uses untitled as the name.
+ */
- (BOOL) uuencodeInto: (NSMutableData*)encoded
name: (NSString*)name
mode: (int)mode;
diff --git a/Headers/Foundation/NSDateFormatter.h b/Headers/Foundation/NSDateFormatter.h
index bbbc9b6b1..783ae24bf 100644
--- a/Headers/Foundation/NSDateFormatter.h
+++ b/Headers/Foundation/NSDateFormatter.h
@@ -29,6 +29,67 @@
#include @"%b %d, %Y"
+ * specifies strings similar to "June 18, 1991". The full list of codes is
+ * as follows:@"%b %d, %Y"
+ * specifies strings similar to "June 18, 1991".
+ */
- (NSString *) dateFormat;
@end
diff --git a/Headers/Foundation/NSDebug.h b/Headers/Foundation/NSDebug.h
index 3035020f5..6a61f6edc 100644
--- a/Headers/Foundation/NSDebug.h
+++ b/Headers/Foundation/NSDebug.h
@@ -220,8 +220,9 @@ GS_EXPORT BOOL NSDeallocateZombies;
NSProcess initialises a set of strings that are the names of active
debug levels using the '--GNU-Debug=...' command line argument.
- Each command-line argument of that form is removed from NSProcessInfos
- list of arguments and the variable part (...) is added to the set.
+ Each command-line argument of that form is removed from
+ NSProcessInfo's list of arguments and the variable part
+ (...) is added to the set.
This means that as far as the program proper is concerned, it is
running with the same arguments as if debugging had not been enabled.
NSUserDefaults also adds debug levels from the array given by the GNU-Debug key ... but these values will not take effect until the +standardUserDefaults method is called ... so they are useless for - debugging NSUserDefaults itsself or for debugging any code executed + debugging NSUserDefaults itself or for debugging any code executed before the defaults system is used.
To embed debug logging in your code you use the NSDebugLLog() or @@ -395,7 +396,7 @@ GS_EXPORT BOOL NSDeallocateZombies; something that it not necessarily fatal or illegal, but looks like it might be a programming error. eg. attempting to remove 'nil' from an NSArray, which the Spec/documentation does not prohibit, but which a - well written progam should not be attempting (since an NSArray object + well written program should not be attempting (since an NSArray object cannot contain a 'nil').
NB. The 'warn=yes' option is understood by the GNUstep make package @@ -405,7 +406,7 @@ GS_EXPORT BOOL NSDeallocateZombies;
To embed debug logging in your code you use the NSWarnLog() macro.
As a convenience, there are two more logging macros you can use - - NSWarnLog(), and NSWarnMLog(). + NSWarnFLog(), and NSWarnMLog(). These are specifically for use in either functions or methods and prepend information about the file, line and either function or class/method in which the message was generated. diff --git a/Headers/Foundation/NSDecimal.h b/Headers/Foundation/NSDecimal.h index c9fee4cbe..6a2d9d13c 100644 --- a/Headers/Foundation/NSDecimal.h +++ b/Headers/Foundation/NSDecimal.h @@ -50,7 +50,7 @@ typedef enum { NSCalculationDivideByZero } NSCalculationError; -/* +/** * Give a precision of at least 38 decimal digits * requires 128 bits. */ @@ -59,6 +59,21 @@ typedef enum { #define NSDecimalMaxDigit 38 #define NSDecimalNoScale 128 +/** + *
Structure providing equivalent functionality, in conjunction with a set + * of functions, to the [NSDecimalNumber] class.
+Instances can be initialized using the NSDecimalFromString(NSString *) +* function.
+ */ typedef struct { signed char exponent; /* Signed exponent - -128 to 127 */ BOOL isNegative; /* Is this negative? */ diff --git a/Headers/Foundation/NSDecimalNumber.h b/Headers/Foundation/NSDecimalNumber.h index f950e5ffb..d16b98677 100644 --- a/Headers/Foundation/NSDecimalNumber.h +++ b/Headers/Foundation/NSDecimalNumber.h @@ -33,15 +33,87 @@ @class NSDecimalNumber; +/** + * This protocol encapsulates information about how an [NSDecimalNumber] + * should round and process exceptions. Usually you can just create objects + * of the [NSDecimalNumberHandler] class, which implements this protocol, but + * if you don't want to use that class you can create your own implementing + * it. + */ @protocol NSDecimalNumberBehaviors + +/** + *Specifies behavior when, in the course of applying method to leftOperand + * and rightOperand, an [NSDecimalNumber] instance encounters given error.
+ *error has four possible constant values:
+ *NSCalculationLossOfPrecisionNSCalculationOverflowNSCalculationUnderflowNSCalculationDivideByZeroBehavior on error can be one of the following:
+ *NSCalculationLossOfPrecision, method will return an
+ * imprecise value, constrained to 38 significant digits. If error is
+ * NSCalculationUnderflow or
+ * NSCalculationOverflow, method will return
+ * NSDecimalNumber's notANumber. You shouldn't
+ * return nil if error is NSDivideByZero.
+ * NSDecimalNumber.
+ * The calling method will use this as its own return value.decimalNumberBy... methods
+ * round their return values. This should be set to one of the following
+ * constants:
+ * NSRoundDownNSRoundUpNSRoundPlainNSRoundBankersdecimalNumberBy... methods, in terms of the number of
+ * digits allowed after the decimal point. This can be negative, implying
+ * that the precision should be, e.g., 100's, 1000's, etc.. For unlimited
+ * precision, set to NSDecimalNoScale.
+ */
- (short) scale;
@end
+/**
+ * A utility class adopting [NSDecimalNumberBehaviors] protocol. Can be used
+ * to control [NSDecimalNumber] rounding and exception-handling behavior, by
+ * passing an instance as an argument to any [NSDecimalNumber] method ending
+ * with ...Behavior:.
+ */
@interface NSDecimalNumberHandler : NSObject NSRoundPlain). Exceptions raised on overflow,
+ * underflow, and divide by zero.
+ */
+ (id)defaultDecimalNumberHandler;
+
+/**
+ * Constructor setting all behavior. (For more precise control over error
+ * handling, create your own class implementing the [NSDecimalNumberBehaviors]
+ * protocol.)
+ */
+ (id)decimalNumberHandlerWithRoundingMode:(NSRoundingMode)roundingMode
scale:(short)scale
raiseOnExactness:(BOOL)raiseOnExactness
@@ -60,6 +144,11 @@
raiseOnUnderflow:(BOOL)raiseOnUnderflow
raiseOnDivideByZero:(BOOL)raiseOnDivideByZero;
+/**
+ * Initializor setting all behavior. (For more precise control over error
+ * handling, create your own class implementing the [NSDecimalNumberBehaviors]
+ * protocol.)
+ */
- (id)initWithRoundingMode:(NSRoundingMode)roundingMode
scale:(short)scale
raiseOnExactness:(BOOL)raiseOnExactness
@@ -68,67 +157,249 @@
raiseOnDivideByZero:(BOOL)raiseOnDivideByZero;
@end
+/**
+ * Class that implements a number of methods for performing decimal + * arithmetic to arbitrary precision. The behavior in terms of rounding + * choices and exception handling may be customized using the + * [NSDecimalNumberHandler] class, and defaults to + * [NSDecimalNumberHandler+defaultDecimalNumberHandler].
+ * + *Equivalent functionality to the NSDecimalNumber class may
+ * be accessed through functions, mostly named NSDecimalXXX,
+ * e.g., NSDecimalMin(). Both the class and the functions use a structure
+ * called NSDecimal.
Note that instances of NSDecimalNumber are immutable.
decimalNumberBy... methods will return a result
+ * constrained by the current scale. Number format
+ * is parsed according to current default locale.
+ */
+ (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString;
+
+/**
+ * New instance from string. Arbitrary precision is preserved, though calling
+ * one of the decimalNumberBy... methods will return a result
+ * constrained by the current scale. Number format
+ * is parsed according to given locale.
+ */
+ (NSDecimalNumber *)decimalNumberWithString:(NSString *)numericString
locale:(NSDictionary *)locale;
+/**
+ * Initialize with given value. Note an NSDecimal may be created using the
+ * function NSDecimalFromString().
+ */
- (id)initWithDecimal:(NSDecimal)decimal;
+
+/**
+ * Initialize by component. Note that the precision of this initializer is
+ * limited.
+ */
- (id)initWithMantissa:(unsigned long long)mantissa
exponent:(short)exponent
isNegative:(BOOL)flag;
+
+/**
+ * Initialize from string. Arbitrary precision is preserved, though calling
+ * one of the decimalNumberBy... methods will return a result
+ * constrained by the current scale. Number format
+ * is parsed according to current default locale.
+ */
- (id)initWithString:(NSString *)numberValue;
+
+/**
+ * Initialize from string. Arbitrary precision is preserved, though calling
+ * one of the decimalNumberBy... methods will return a result
+ * constrained by the current scale. Number format
+ * is parsed according to given locale.
+ */
- (id)initWithString:(NSString *)numberValue
locale:(NSDictionary *)locale;
+/**
+ * Returns the Objective-C type (@encode(...) compatible) of the
+ * data contained NSDecimalNumber, which is by convention "d"
+ * (for double), even though this is not strictly accurate.
+ */
- (const char *)objCType;
+/**
+ * Return underlying value as an NSDecimal structure.
+ */
- (NSDecimal)decimalValue;
+
+/**
+ * Returns string version of number formatted accordng to locale.
+ */
- (NSString *)descriptionWithLocale:(NSDictionary *)locale;
+
+/**
+ * Returns underlying value as a double, which may be an
+ * approximation if precision greater than the default of 38.
+ */
- (double)doubleValue;
+
+/**
+ * Compares with other number, returning less, greater, or equal.
+ */
- (NSComparisonResult)compare:(NSNumber *)decimalNumber;
+/**
+ * Adds self to decimalNumber and returns new result, using +defaultBehavior
+ * for rounding/precision/error handling.
+ */
- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber;
+
+/**
+ * Adds self to decimalNumber and returns new result, using given behavior
+ * for rounding/precision/error handling.
+ */
- (NSDecimalNumber *)decimalNumberByAdding:(NSDecimalNumber *)decimalNumber
withBehavior:(idNSLocalizedDescriptionKey should locate a human readable
+ * description in the dictionary.NSUnderlyingErrorKey key should locate an
+ * NSError instance if an error is available describing any
+ * underlying problem.alloc-init.
+ * If there is a problem with conversion, a constant-string description of
+ * what went wrong is returned through error, and NO is returned, otherwise
+ * YES.
+ */
- (BOOL) getObjectValue: (id*)anObject
forString: (NSString*)string
errorDescription: (NSString**)error;
+
+/**
+ * Checks whether partialString could, if it were completed, be
+ * parsed into a valid object. newString and error are output parameters;
+ * you should allocate memory for one pointer each for the variables passed
+ * into these methods. This method is set up to be called after every
+ * keystroke during user editing. If it returns NO, it optionally returns
+ * newString to replace what the user was editing; if it doesn't, the editor
+ * should delete the last character the user typed.
+ */
- (BOOL) isPartialStringValid: (NSString*)partialString
newEditingString: (NSString**)newString
errorDescription: (NSString**)error;
+
+/**
+ * Checks whether a change to a string leaves it a valid string that, if it
+ * were completed, could be parsed into a valid object. origString contains
+ * the string before the proposed change, and origSelRange contains the range
+ * that is updated in the proposed change. partialStringPtr contains the new
+ * string to validate and proposedSelRangePtr holds the selection range that
+ * will be used if the string is accepted or replaced. Basically, this method
+ * returns YES if partialStringPtr is valid, otherwise NO and may replace
+ * partialStringPtr and proposedSelectedRange with improved values, and may
+ * report the reason in error.
+ */
- (BOOL) isPartialStringValid: (NSString**)partialStringPtr
proposedSelectedRange: (NSRange*)proposedSelRangePtr
originalString: (NSString*)origString
originalSelectedRange: (NSRange)originalSelRangePtr
errorDescription: (NSString**)error;
+
+
+/**
+ * Primary method for converting an object to a string through formatting.
+ * Object will be converted to string according to the formatter's
+ * implementation and init parameters. There is no default handling if the
+ * class of anObject is not what the formatter expects, and usually nil
+ * will be returned in this case.
+ */
- (NSString*) stringForObjectValue: (id)anObject;
@end
diff --git a/Headers/Foundation/NSGeometry.h b/Headers/Foundation/NSGeometry.h
index 8ccef470c..9785af1e3 100644
--- a/Headers/Foundation/NSGeometry.h
+++ b/Headers/Foundation/NSGeometry.h
@@ -46,7 +46,12 @@
#define GS_DEFINED_MIN
#endif
-/* Point definition. */
+/**
+Represents a 2-d cartesian position.
*/ typedef struct _NSPoint NSPoint; struct _NSPoint { @@ -55,11 +60,17 @@ struct _NSPoint }; #ifndef STRICT_OPENSTEP +/** Array of NSPoint structs. */ typedef NSPoint *NSPointArray; typedef NSPoint *NSPointPointer; #endif -/* Rectangle sizes. */ +/** +Floating point rectangle size.
*/ typedef struct _NSSize NSSize; struct _NSSize { @@ -72,7 +83,13 @@ typedef NSSize *NSSizeArray; typedef NSSize *NSSizePointer; #endif -/* Rectangle. */ +/** +Rectangle.
*/ typedef struct _NSRect NSRect; struct _NSRect { @@ -81,6 +98,7 @@ struct _NSRect }; #ifndef STRICT_OPENSTEP +/** Array of NSPoint structs. */ typedef NSRect *NSRectArray; typedef NSRect *NSRectPointer; #endif @@ -95,8 +113,11 @@ enum _NSRectEdge NSMaxYEdge }; +/** Point at 0,0 */ static const NSPoint NSZeroPoint __attribute__((unused)); /* Zero point. */ +/** Zero-size rectangle at 0,0 */ static const NSRect NSZeroRect __attribute__((unused)); /* Zero rectangle. */ +/** Zero size */ static const NSSize NSZeroSize __attribute__((unused)); /* Zero size. */ /**** Function Prototypes ****************************************************/ diff --git a/Headers/Foundation/NSHashTable.h b/Headers/Foundation/NSHashTable.h index 2a612c0c8..a67f4bcca 100644 --- a/Headers/Foundation/NSHashTable.h +++ b/Headers/Foundation/NSHashTable.h @@ -47,25 +47,32 @@ typedef void* NSHashTable; */ typedef struct { void *map; void *node; size_t bucket; } NSHashEnumerator; -/** Callback functions.unsigned int (*hash)(NSHashTable *, const void *) ...
+ * Hashing function. NOTE: Elements with equal values must have equal hash
+ * function values. The default if NULL uses the pointer addresses
+ * directly. BOOL (*isEqual)(NSHashTable *, const void *, const void *)
+ * ... Comparison function. The default if NULL uses '=='.
+ * void (*retain)(NSHashTable *, const void *) ...
+ * Retaining function called when adding elements to the table.
+ * The default if NULL is a no-op (no reference counting). void (*release)(NSHashTable *, void *) ... Releasing
+ * function called when a data element is removed from the table.
+ * The default if NULL is a no-op (no reference counting).NSString *(*describe)(NSHashTable *, const void *) ...
+ * Description function. The default if NULL prints boilerplate. ...forKey: [NSCoder] methods, which provide for more robust
+ * forwards and backwards compatibility.
*/
@interface NSKeyedArchiver : NSCoder
{
@@ -100,16 +105,53 @@
*/
- (id) delegate;
+/**
+ * Encodes aBool and associates the encoded value with aKey.
+ */
- (void) encodeBool: (BOOL)aBool forKey: (NSString*)aKey;
+
+/**
+ * Encodes the data of the specified length and pointed to by aPointer,
+ * and associates the encoded value with aKey.
+ */
- (void) encodeBytes: (const uint8_t*)aPointer
length: (unsigned)length
forKey: (NSString*)aKey;
+
+/**
+ * Encodes anObject and associates the encoded value with aKey, but only
+ * if anObject has already been encoded using -encodeObject:forKey:
+ */
- (void) encodeConditionalObject: (id)anObject forKey: (NSString*)aKey;
+
+/**
+ * Encodes aDouble and associates the encoded value with aKey.
+ */
- (void) encodeDouble: (double)aDouble forKey: (NSString*)aKey;
+
+/**
+ * Encodes aFloat and associates the encoded value with aKey.
+ */
- (void) encodeFloat: (float)aFloat forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
- (void) encodeInt: (int)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
- (void) encodeInt32: (int32_t)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anInteger and associates the encoded value with aKey.
+ */
- (void) encodeInt64: (int64_t)anInteger forKey: (NSString*)aKey;
+
+/**
+ * Encodes anObject and associates the encoded value with aKey.
+ */
- (void) encodeObject: (id)anObject forKey: (NSString*)aKey;
/**
@@ -159,7 +201,12 @@
/**
- * Keyed unarchiving class.
+ * Implements keyed unarchiving of object graphs. The keyed archiver
+ * should be used instead of [NSArchiver] for new implementations. Classes
+ * implementing [NSCoding] should check the [NSCoder-allowsKeyedCoding]
+ * method and if the response is YES, encode/decode their fields using the
+ * ...forKey: [NSCoder] methods, which provide for more robust
+ * forwards and backwards compatibility.
*/
@interface NSKeyedUnarchiver : NSCoder
{
@@ -182,29 +229,132 @@
NSZone *_zone; /* Zone for allocating objs. */
}
+/**
+ * Returns class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping. Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
+ (Class) classForClassName: (NSString*)aString;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping. Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
+ (void) setClass: (Class)aClass forClassName: (NSString*)aString;
+
+/**
+ * Decodes from byte array in data and returns resulting root object.
+ */
+ (id) unarchiveObjectWithData: (NSData*)data;
+
+/**
+ * Decodes from file contents at aPath and returns resulting root object.
+ */
+ (id) unarchiveObjectWithFile: (NSString*)aPath;
+/**
+ * Returns class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping. The class as a whole also maintains a
+ * translation map, which is searched on decoding if no match found here.
+ */
- (Class) classForClassName: (NSString*)aString;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping. Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
- (BOOL) containsValueForKey: (NSString*)aKey;
+
+/**
+ * Sets class substituted for class name specified by aString when
+ * encountered in the archive being decoded from, or nil if there is no
+ * specific translation mapping. Each instance also maintains a translation
+ * map, which is searched first for a match during decoding.
+ */
+- (void) setClass: (Class)aClass forClassName: (NSString*)aString;
+
+/**
+ * Returns a boolean value associated with aKey. This value must previously
+ * have been encoded using -encodeBool:forKey:
+ */
- (BOOL) decodeBoolForKey: (NSString*)aKey;
+
+/**
+ * Returns a pointer to a byte array associated with aKey.NSPoint object.
*/
- (void) encodePoint: (NSPoint)aPoint forKey: (NSString*)aKey;
/**
- * Encodes an NSRect object.
+ * Encodes an NSRect object.
*/
- (void) encodeRect: (NSRect)aRect forKey: (NSString*)aKey;
/**
- * Encodes an NSSize object.
+ * Encodes an NSSize object.
*/
- (void) encodeSize: (NSSize)aSize forKey: (NSString*)aKey;
/**
- * Decodes an NSPoint object.
+ * Decodes an NSPoint object.
*/
- (NSPoint) decodePointForKey: (NSString*)aKey;
/**
- * Decodes an NSRect object.
+ * Decodes an NSRect object.
*/
- (NSRect) decodeRectForKey: (NSString*)aKey;
/**
- * Decodes an NSSize object.
+ * Decodes an NSSize object.
*/
- (NSSize) decodeSizeForKey: (NSString*)aKey;
@end
diff --git a/Headers/Foundation/NSLock.h b/Headers/Foundation/NSLock.h
index 8968716ff..780891a7b 100644
--- a/Headers/Foundation/NSLock.h
+++ b/Headers/Foundation/NSLock.h
@@ -33,19 +33,25 @@
#include newLockAt: method.
+ */
@interface NSLock (GSCategories)
+/**
+ * Initializes the id pointed to by location
+ * with a new instance of the receiver's class
+ * in a thread safe manner, unless
+ * it has been previously initialized.
+ * Returns the contents pointed to by location.
+ * The location is considered unintialized if it contains nil.
+ * newLockAt: method.
+ */
@interface NSRecursiveLock (GSCategories)
+/**
+ * Initializes the id pointed to by location
+ * with a new instance of the receiver's class
+ * in a thread safe manner, unless
+ * it has been previously initialized.
+ * Returns the contents pointed to by location.
+ * The location is considered unintialized if it contains nil.
+ * Info about layout of arguments. * Extended from the original OpenStep version to let us know if the - * arg is passed in registers or on the stack. + * arg is passed in registers or on the stack.
* - * NB. This no longer exists in Rhapsody/MacOS. + *NB. This no longer exists in Rhapsody/MacOS.
+Class encapsulating type information for method arguments and return + * value. It is used as a component of [NSInvocation] to implement message + * forwarding, such as within the distributed objects framework. Instances + * can be obtained from the [NSObject] method + * [NSObject-methodSignatureForSelector:].
+ * + *Basically, types are represented as Objective-C @encode(...)
+ * compatible strings, together with size information. The arguments are
+ * numbered starting from 0, including the implicit arguments
+ * self (type id, at position 0) and
+ * _cmd (type SEL, at position 1).
@encode(...) type codes.
+ */
+ (NSMethodSignature*) signatureWithObjCTypes: (const char*)t;
#ifndef STRICT_MACOS_X
+/**
+ * Returns full information on given argument. Indices start at 0. Provide
+ * -1 to get info on return value.
+ */
- (NSArgumentInfo) argumentInfoAtIndex: (unsigned)index;
#endif
+
+/**
+ * Number of bytes that the full set of arguments occupies on the stack, which
+ * is platformt(hardware)-dependent.
+ */
- (unsigned) frameLength;
+
+/**
+ * Returns Objective-C @encode(...) compatible string. Arguments
+ * are numbered starting from 0, including the implicit arguments
+ * self (type id, at position 0) and
+ * _cmd (type SEL, at position 1).
+ */
- (const char*) getArgumentTypeAtIndex: (unsigned)index;
+
+/**
+ * Pertains to distributed objects; method is asynchronous when invoked and
+ * return should not be waited for.
+ */
- (BOOL) isOneway;
+
+/**
+ * Number of bytes that the return value occupies on the stack, which is
+ * platformt(hardware)-dependent.
+ */
- (unsigned) methodReturnLength;
+
+/**
+ * Returns Objective-C @encode(...) compatible string. Arguments
+ * are numbered starting from 0, including the implicit arguments
+ * self (type id, at position 0) and
+ * _cmd (type SEL, at position 1).
+ */
- (const char*) methodReturnType;
+
+/**
+ * Returns number of arguments to method, including the implicit
+ * self and _cmd.
+ */
- (unsigned) numberOfArguments;
@end
#ifndef NO_GNUSTEP
+/**
+ * Declares a convenience method for getting the entire array of raw type and
+ * size information.
+ */
@interface NSMethodSignature(GNUstep)
+/**
+ * Convenience method for getting the entire array of raw type and size
+ * information.
+ */
- (NSArgumentInfo*) methodInfo;
+
+/**
+ * Returns a string containing all Objective-C
+ * @encode(...) compatible type information.
+ */
- (const char*) methodType;
@end
#endif
diff --git a/Headers/Foundation/NSNotification.h b/Headers/Foundation/NSNotification.h
index 390588a43..6bfee5d00 100644
--- a/Headers/Foundation/NSNotification.h
+++ b/Headers/Foundation/NSNotification.h
@@ -85,19 +85,25 @@
#ifndef NO_GNUSTEP
+/**
+ * Defines some extensions for maximising posting performance - these options
+ * are NOT adjustable for the default notification center.
+ *
+ */
@interface NSNotificationCenter (GNUstep)
-/*
- * Extensions for maximising posting performance - these options are
- * NOT adjustable for the default notification center.
- *
- * You can disable locking in a multi-threaded program if you KNOW that only
- * one thread will ever use the notification center.
- *
+
+/**
* You can turn on 'immutability' if you KNOW that the posting of a
* notification will never result in an attempt to modify the center.
* In this case, the center can optimise delivery of notifications.
*/
- (BOOL) setImmutableInPost: (BOOL)flag;
+
+/**
+ *
+ * You can disable locking in a multi-threaded program if you KNOW that only
+ * one thread will ever use the notification center.
+ */
- (BOOL) setLockingDisabled: (BOOL)flag;
@end
#endif
diff --git a/Headers/Foundation/NSNumberFormatter.h b/Headers/Foundation/NSNumberFormatter.h
index ba62cb4cf..7127ff2fa 100644
--- a/Headers/Foundation/NSNumberFormatter.h
+++ b/Headers/Foundation/NSNumberFormatter.h
@@ -33,6 +33,42 @@
@class NSString, NSAttributedString, NSDictionary;
+/**
+ * This class is currently not implemented in GNUstep! All set + * methods will work, but stringForObject: will ignore the format completely. + * The documentation below describes what the behavior SHOULD + * be...
+ * + *A specialization of the [NSFormatter] class for generating string + * representations of numbers ([NSNumber] and [NSDecimalNumber] instances) and + * for parsing numeric values in strings.
+ * + *See the [NSFormatter] documentation for description of the basic methods + * for formatting and parsing that are available.
+ * + *There are no convenience initializers or constructors for this class. + * Instead, to obtain an instance, call alloc init and then -setFormat: .
+ * + *The basic format of a format string uses "#" signs to represent digits,
+ * and other characters to represent themselves, in a context-dependent way.
+ * Thus, for example, @"#,###.00" means to print the number
+ * ending in .00 if it has no decimal part, otherwise print two decimal
+ * places, and to print one comma if it is greater than 1000. Thus, 1000
+ * prints as "1,000.00", and 1444555.979 prints as "1444,555.98" (see
+ * -setRoundingBehavior:).
After setting the format, you may change the thousands separator and + * decimal point using set methods, or by calling -setLocalizesFormat: .
+ * + *You may set separate formats to be used for positive numbers, negative + * numbers, and zero independently.
+ * + *In addition, this class supports attributed strings (see + * [NSAttributedString]), so that you can specify font and color attributes, + * among others, to display aspects of a number. You can assign specific sets + * of attributes for positive and negative numbers, and for specific cases + * including 0, NaN, and nil...
+ */ @interface NSNumberFormatter: NSFormatter { BOOL _hasThousandSeparators; @@ -53,45 +89,207 @@ } // Format +/** + * Returns the format string this instance was initialized with. + */ - (NSString*) format; + +/** + * Sets format string. See class description for more information. + */ - (void) setFormat: (NSString*)aFormat; + +/** + * Returns whether this format should defer to the locale in determining + * thousands separator and decimal point. The default is to NOT localize. + */ - (BOOL) localizesFormat; + +/** + * Set whether this format should defer to the locale in determining thousands + * separator and decimal point. The default is to NOT localize. + */ - (void) setLocalizesFormat: (BOOL)flag; + +/** + * Returns format used for negative numbers. + */ - (NSString*) negativeFormat; + +/** + * Sets format used for negative numbers. See class description for more + * information. + */ - (void) setNegativeFormat: (NSString*)aFormat; + +/** + * Returns format used for positive numbers. + */ - (NSString*) positiveFormat; + +/** + * Sets format used for positive numbers. See class description for more + * information. + */ - (void) setPositiveFormat: (NSString*)aFormat; + // Attributed Strings +/** + * Returns the exact attributed string used for nil values. By default this + * is an empty string. + */ - (NSAttributedString*) attributedStringForNil; + +/** + * Sets the exact attributed string used for nil values. By default this + * is an empty string. + */ - (void) setAttributedStringForNil: (NSAttributedString*)newAttributedString; + +/** + * Returns the exact attributed string used for NaN values. By default this + * is the string "NaN" with no attributes. + */ - (NSAttributedString*) attributedStringForNotANumber; + +/** + * Sets the exact attributed string used for NaN values. By default this + * is the string "NaN" with no attributes. + */ - (void) setAttributedStringForNotANumber: (NSAttributedString*)newAttributedString; + +/** + * Returns the exact attributed string used for zero values. By default this + * is based on the format for zero values, if set, or the format for positive + * values otherwise. + */ - (NSAttributedString*) attributedStringForZero; + +/** + * Sets the exact attributed string used for zero values. By default this + * is based on the format for zero values, if set, or the format for positive + * values otherwise. + */ - (void) setAttributedStringForZero: (NSAttributedString*)newAttributedString; + +/** + * Returns the attributes to apply to negative values (whole string), when + * -attributedStringForObjectValue:withDefaultAttributes: is called. Default + * is none. + */ - (NSDictionary*) textAttributesForNegativeValues; + +/** + * Sets the attributes to apply to negative values (whole string), when + * -attributedStringForObjectValue:withDefaultAttributes: is called. Default + * is none. + */ - (void) setTextAttributesForNegativeValues: (NSDictionary*)newAttributes; + +/** + * Returns the attributes to apply to positive values (whole string), when + * -attributedStringForObjectValue:withDefaultAttributes: is called. Default + * is none. + */ - (NSDictionary*) textAttributesForPositiveValues; + +/** + * Sets the attributes to apply to positive values (whole string), when + * -attributedStringForObjectValue:withDefaultAttributes: is called. Default + * is none. + */ - (void) setTextAttributesForPositiveValues: (NSDictionary*)newAttributes; -// Rounding + +// Rounding.. this should be communicated as idNSOrderedSame, NSOrderedAscending
+ * NSOrderedDescending, for left hand side equals, less than, or
+ * greater than right hand side.
+ */
typedef enum _NSComparisonResult
{
NSOrderedAscending = -1, NSOrderedSame, NSOrderedDescending
@@ -291,11 +316,38 @@ GS_EXPORT NSRecursiveLock *gnustep_global_lock;
- (id) write: (TypedStream*)aStream;
@end
+/**
+ * Provides a number of GNUstep-specific methods that are used to aid
+ * implementation of the Base library.
+ */
@interface NSObject (GSCategories)
+
+/**
+ * Message sent when an implementation wants to explicitly exclude a method
+ * (but cannot due to compiler constraint), and wants to make sure it is not
+ * called by mistake. Default implementation raises an exception at runtime.
+ */
- notImplemented:(SEL)aSel;
+
+/**
+ * Message sent when an implementation wants to explicitly require a subclass
+ * to implement a method (but cannot at compile time since there is no
+ * abstract keyword in Objective-C). Default implementation
+ * raises an exception at runtime to alert developer that he/she forgot to
+ * override a method.
+ */
- (id) subclassResponsibility: (SEL)aSel;
+
+/**
+ * Message sent when an implementation wants to explicitly exclude a method
+ * (but cannot due to compiler constraint) and forbid that subclasses
+ * implement it. Default implementation raises an exception at runtime. If a
+ * subclass does implement this method, however, the superclass's
+ * implementation will not be called, so this is not a perfect mechanism.
+ */
- (id) shouldNotImplement: (SEL)aSel;
-/*
+
+/**
WARNING: The -compare: method for NSObject is deprecated
due to subclasses declaring the same selector with
conflicting signatures.
@@ -310,23 +362,53 @@ GS_EXPORT NSRecursiveLock *gnustep_global_lock;
#endif
-/*
+/**
* Protocol for garbage collection finalization - same as libFoundation
* for compatibility.
*/
@protocol GCFinalization
+/**
+ * Called before receiver is deallocated by garbage collector. If you want
+ * to do anything special before [NSObject -dealloc] is called, do it here.
+ */
- (void) gcFinalize;
@end
#include NSPort is an abstract class defining interfaces underlying
+ * communications in the distributed objects framework. Each side of a
+ * connection will have an NSPort object, responsible for sending
+ * and receiving [NSPortMessage]s, which are then passed to delegates when
+ * received. The NSPort must be added to the [NSRunLoop] as an
+ * input source.
This class also implements the functionality of the
+ * NSMachPort class on OS X.
An [NSPort] implementation for network object communications based on + * BSD sockets. Can be used for interthread/interprocess + * communications between same or different hosts (though on same host + * [NSMessagePort] will be more efficient).
+ * + *Note that this class is incompatible with the latest OS X version.
+ */ @interface NSSocketPort : NSPortNSSocketPort given a host and
+ * number, or return nil if one has not been created.
+ */
+ (NSSocketPort*) existingPortWithNumber: (gsu16)number
onHost: (NSHost*)aHost;
+
+/**
+ * This is the preferred initialisation method for NSSocketPort.
+ * NSMessagePort.
+ *
+ * socketName is the name of the socket in the port directory
+ */
+ (NSMessagePort*) _portWithName: (const unsigned char *)socketName
listener: (BOOL)shouldListen;
+/**
+ * Setup method: add new send or receive connection handle.
+ */
- (void) addHandle: (GSMessageHandle*)handle forSend: (BOOL)send;
+
+/**
+ * This is called when a socket connection is broken. We remove the
+ * connection handle from this port and, if this was the last handle to a
+ * remote port, we invalidate the port.
+ */
- (void) removeHandle: (GSMessageHandle*)handle;
+
+/**
+ * Delegates processing of a message.
+ */
- (void) handlePortMessage: (NSPortMessage*)m;
@end
diff --git a/Headers/Foundation/NSPortCoder.h b/Headers/Foundation/NSPortCoder.h
index 64ff9255c..5a4c8885c 100644
--- a/Headers/Foundation/NSPortCoder.h
+++ b/Headers/Foundation/NSPortCoder.h
@@ -31,6 +31,17 @@
@class NSConnection;
@class NSPort;
+/**
+ * This class is an [NSCoder] implementation specialized for sending objects
+ * over network connections for immediate use (as opposed to the archivers
+ * which persist objects for reconstitution after an indefinite term). It is
+ * used to help implement the distributed objects framework by the
+ * [NSConnection] class. Even for highly specialized applications, you
+ * probably do not need to use this class directly.
+ */
+//FIXME: the above is what Apple's docs say, but looking at the code the
+// NSConnection is actually created by this class rather than the other way
+// around, so maybe the docs should be changed..
@interface NSPortCoder : NSCoder
{
@private
@@ -77,18 +88,57 @@
NSZone *_zone; /* Zone for allocating objs. */
}
+/**
+ * Create a new instance for communications over send and recv, and send an
+ * initial message through send as specified by comp.
+ */
+ (NSPortCoder*) portCoderWithReceivePort: (NSPort*)recv
sendPort: (NSPort*)send
components: (NSArray*)comp;
+
+/**
+ * Initialize a new instance for communications over send and recv, and send an
+ * initial message through send as specified by comp.
+ */
- (id) initWithReceivePort: (NSPort*)recv
sendPort: (NSPort*)send
components: (NSArray*)comp;
+/**
+ * Returns the NSConnection using this instance.
+ */
- (NSConnection*) connection;
+
+/**
+ * Return port object previously encoded by this instance. Mainly for use
+ * by the ports themselves.
+ */
- (NSPort*) decodePortObject;
+
+/**
+ * Processes and acts upon the initial message the receiver was initialized
+ * with..
+ */
- (void) dispatch;
+
+/**
+ * Encodes aPort so it can be sent to the receiving side of the connection.
+ * Mainly for use by the ports themselves.
+ */
- (void) encodePortObject: (NSPort*)aPort;
+
+/**
+ * Returns YES if receiver is in the process of encoding objects by copying
+ * them (rather than substituting a proxy). This method is mainly needed
+ * internally and by subclasses.
+ */
- (BOOL) isBycopy;
+
+/**
+ * Returns YES if receiver will substitute a proxy when encoding objects
+ * rather than by copying them. This method is mainly needed
+ * internally and by subclasses.
+ */
- (BOOL) isByref;
@end
diff --git a/Headers/Foundation/NSPortMessage.h b/Headers/Foundation/NSPortMessage.h
index 66860a6ad..5ad334405 100644
--- a/Headers/Foundation/NSPortMessage.h
+++ b/Headers/Foundation/NSPortMessage.h
@@ -27,6 +27,15 @@
#include The data transported for distributed objects communications is sent over + * the network encapsulated by NSPortMessage objects, which consist of two + * [NSPort]s (sender and receiver, not sent over the network) and a body + * consisting of one or more [NSData] or [NSPort] objects. (Data in the + * [NSData] must be in network byte order.)
+ * + *See the [NSConnection] and [NSPortCoder] classes.
+ */ @interface NSPortMessage : NSObject { unsigned _msgid; @@ -34,15 +43,59 @@ NSPort *_send; NSMutableArray *_components; } +/** + * OpenStep compatibility. + */ - (id) initWithMachMessage: (void*)buffer; + +/**The NSPropertyListSerialization class provides facilities for * serialising and deserializing property list data in a number of - * formats. - *
+ * formats. A property list is roughly an [NSArray] or [NSDictionary] object, + * with these or [NSNumber], [NSData], [NSString], or [NSDate] objects + * as members. (See below.) *You do not work with instances of this class, instead you use a - * small number of claass methods to serialized and deserialize + * small number of class methods to serialize and deserialize * property lists. - *
+ *array
+ * and whose content is the array content.
+ * data and whose content is a stream of base64 encoded bytes.
+ * date and whose content is a date in the above format.
+ * dictionary and whose content consists of pairs of
+ * strings and other property list objects.
+ * <*BY> for YES or
+ * <*BN> for NO.<true /> or
+ * <false />
+ * <*INNN> where NNN is an
+ * integer.<integer>NNN<integer>
+ * <*RNNN> where NNN is a real
+ * number.<real>NNN<real>
+ * string element, and the only character
+ * escapes required are those used by XML such as the
+ * '<' markup representing a '<' character.
+ * * The NSRange type is used to specify ranges of locations, * typically items in an array, characters in a string, and bytes diff --git a/Headers/Foundation/NSRunLoop.h b/Headers/Foundation/NSRunLoop.h index af2cb88ba..50745e44d 100644 --- a/Headers/Foundation/NSRunLoop.h +++ b/Headers/Foundation/NSRunLoop.h @@ -130,7 +130,7 @@ typedef enum { * These are general purpose methods for letting objects ask * the runloop to watch for events for them. Only one object * at a time may be watching for a particular event in a mode, but - * that object may add itsself as a watcher many times as long as + * that object may add itself as a watcher many times as long as * each addition is matched by a removal (the run loop keeps count). * Alternatively, the 'removeAll' parameter may be set to 'YES' for * [-removeEvent:type:forMode:all:] in order to remove the watcher @@ -165,9 +165,13 @@ typedef enum { all: (BOOL)removeAll; @end -/* xxx This interface will probably change. */ +/** + * Defines implementation-helper method -getFds:count:. + * This interface will probably change. Do not rely on it. + */ +// xxx This interface will probably change. @interface NSObject (OptionalPortRunLoop) -/* If a InPort object responds to this, it is sent just before we are +/** If a InPort object responds to this, it is sent just before we are about to wait listening for input. This interface will probably change. */ - (void) getFds: (int*)fds count: (int*)count; diff --git a/Headers/Foundation/NSSerialization.h b/Headers/Foundation/NSSerialization.h index 9415d38b1..fdad8a3ec 100644 --- a/Headers/Foundation/NSSerialization.h +++ b/Headers/Foundation/NSSerialization.h @@ -30,24 +30,61 @@ @class NSData, NSMutableData; +/** + * Objects that are not standard property list constituents can adopt this + * protocol to allow themselves to be serialized by an [NSSerializer] and + * deserialized by an [NSDeserializer]. Note, this mechanism has been + * deprecated and you should instead use [NSArchiver] and related facilities + * to serialize objects that are not ordinary property lists. + */ @protocol NSObjCTypeSerializationCallBack + +/** + * Decodes an object of given type from data at position cursor. + */ - (void) deserializeObjectAt: (id*)object ofObjCType: (const char *)type fromData: (NSData*)data atCursor: (unsigned*)cursor; + +/** + * Encode the given object of given type into data, using a string not a + * binary representation. + */ - (void) serializeObjectAt: (id*)object ofObjCType: (const char *)type intoData: (NSMutableData*)data; @end +/** + *
This class is deprecated in favor of + * [NSPropertyListSerialization].
+ * + *It provides a means of producing a byte-array (actually string) + * representation of a property list (NSArray or NSDictionary plus limited + * contents).
+ */ @interface NSSerializer: NSObject + +/** + *Serialize given property list (NSArray or NSDictionary plus limited + * contents) into byte array.
Deprecated in favor of + * [NSPropertyListSerialization+dataFromPropertyList:format:errorDescription:].
+ */ + (NSData*) serializePropertyList: (id)propertyList; + +/** + *Serialize given property list (NSArray or NSDictionary plus limited + * contents) into given mutable byte array.
Deprecated in favor of + * [NSPropertyListSerialization+dataFromPropertyList:format:errorDescription:].
+ + */ + (void) serializePropertyList: (id)propertyList intoData: (NSMutableData*)d; @end #ifndef NO_GNUSTEP -/* +/** * GNUstep extends serialization by having the option to make the * resulting data more compact by ensuring that repeated strings * are only stored once. If the property-list has a lot of repeated @@ -60,19 +97,56 @@ * override the default behavior. */ @interface NSSerializer (GNUstep) + +/** + * Specify whether to produce compacted format, with repeated strings only + * written once. + */ + (void) shouldBeCompact: (BOOL)flag; + +/** + * As [NSSerializer+serializePropertyList:intoData:] but specify whether to + * produce compacted format. + */ + (void) serializePropertyList: (id)propertyList intoData: (NSMutableData*)d compact: (BOOL)flag; @end #endif +/** + * This class is deprecated in favor of + * [NSPropertyListSerialization]. It provides a means of recovering a + * property list (NSArray or NSDictionary plus limited contents) from a + * byte-array (actually string) representation. + */ @interface NSDeserializer: NSObject + +/** + * Recover a property list (NSArray or NSDictionary plus limited + * contents) from a byte array. Deprecated in favor of + * [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:]. + */ + (id) deserializePropertyListFromData: (NSData*)data atCursor: (unsigned int*)cursor mutableContainers: (BOOL)flag; + +/** + * Recover a property list (NSArray or NSDictionary plus limited + * contents) from a byte array. Deprecated in favor of + * [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:]. + */ + (id) deserializePropertyListFromData: (NSData*)data mutableContainers: (BOOL)flag; + +/** + * Recover a property list (NSArray or NSDictionary plus limited contents) + * from a byte array. If the data at cursor has a length greater than + * length, a proxy is substituted for the actual property list as long as the + * constituent objects of that property list are not accessed. + * Deprecated in favor of + * [NSPropertyListSerialization+propertyListFromData:mutabilityOption:format:errorDescription:]. + */ + (id) deserializePropertyListLazilyFromData: (NSData*)data atCursor: (unsigned*)cursor length: (unsigned)length @@ -81,21 +155,24 @@ @end #ifndef NO_GNUSTEP -/* - * GNUstep extends deserialization by having the option to make the +/** + *GNUstep extends deserialization by having the option to make the * resulting data more compact by ensuring that repeated strings * are only stored once. If the property-list has a lot of repeated * strings in it, this will be more space efficient but it will be * slower (though other parts of your code may speed up through more * efficient equality testing of uniqued strings). - * The default is NOT to deserialize uniqued strings. + * The default is NOT to deserialize uniqued strings.
* - * The [+uniquing:] method turns uniquing on/off. - * Uniquing is done using a global NSCountedSet - see NSCountedSet for - * details. + *The [+uniquing:] method turns uniquing on/off. + * Uniquing is done using a global [NSCountedSet] - see its documentation + * for details.
*/ -@class NSMutableSet; @interface NSDeserializer (GNUstep) +/** + * Turns uniquing (collapsing of multiple instances of a single string in the + * output to one full copy plus references) on/off. + */ + (void) uniquing: (BOOL)flag; @end diff --git a/Headers/Foundation/NSSet.h b/Headers/Foundation/NSSet.h index 51041c202..82862dc9e 100644 --- a/Headers/Foundation/NSSet.h +++ b/Headers/Foundation/NSSet.h @@ -98,39 +98,77 @@ #ifndef NO_GNUSTEP -/* +/** * Utility methods for using a counted set to handle uniquing of objects. */ @interface NSCountedSet (GNU_Uniquing) +/** + *+ * This method removes from the set all objects whose count is + * less than or equal to the specified value. + *
+ *+ * This is useful where a counted set is used for uniquing objects. + * The set can be periodically purged of objects that have only + * been added once - and are therefore simply wasting space. + *
+ */ - (void) purge: (int)level; + +/** + *+ * If the supplied object (or one equal to it as determined by + * the [-isEqual:] method) is already present in the set, the + * count for that object is incremented, the supplied object + * is released, and the object in the set is retained and returned. + * Otherwise, the supplied object is added to the set and returned. + *
+ *
+ * This method is useful for uniquing objects - the init method of
+ * a class need simply end with -
+ *
+ * return [myUniquingSet unique: self];
+ *
+ *
Since GNUstep will generally use the GNUstep extension to the - * compiler, you should never refer to the constnat string class by + * compiler, you should never refer to the constant string class by * name, but should use the [NSString+constantStringClass] method to * get the actual class being used for constant strings.
* What follows is a dummy declaration of the class to keep the compiler @@ -377,25 +377,101 @@ extern struct objc_class _NSConstantStringClassReference; - (NSString*) immutableProxy; @end +/** + * Provides some additional (non-standard) utility methods. + */ @interface NSString (GSCategories) +/** + * Alternate way to invokestringWithFormat if you have or wish
+ * to build an explicit va_list structure.
+ */
+ (id) stringWithFormat: (NSString*)format
arguments: (va_list)argList;
+
+/**
+ * Returns a string formed by removing the prefix string from the
+ * receiver. Raises an exception if the prefix is not present.
+ */
- (NSString*) stringByDeletingPrefix: (NSString*)prefix;
+
+/**
+ * Returns a string formed by removing the suffix string from the
+ * receiver. Raises an exception if the suffix is not present.
+ */
- (NSString*) stringByDeletingSuffix: (NSString*)suffix;
+
+/**
+ * Returns a string formed by removing leading white space from the
+ * receiver.
+ */
- (NSString*) stringByTrimmingLeadSpaces;
+
+/**
+ * Returns a string formed by removing trailing white space from the
+ * receiver.
+ */
- (NSString*) stringByTrimmingTailSpaces;
+
+/**
+ * Returns a string formed by removing both leading and trailing
+ * white space from the receiver.
+ */
- (NSString*) stringByTrimmingSpaces;
+
+/**
+ * Returns a string in which any (and all) occurrences of
+ * replace in the receiver have been replaced with by.
+ * Returns the receiver if replace
+ * does not occur within the receiver. NB. an empty string is
+ * not considered to exist within the receiver.
+ */
- (NSString*) stringByReplacingString: (NSString*)replace
withString: (NSString*)by;
@end
+
+/**
+ * GNUstep specific (non-standard) additions to the NSMutableString class.
+ */
@interface NSMutableString (GSCategories)
+
+/**
+ * Removes the specified suffix from the string. Raises an exception
+ * if the suffix is not present.
+ */
- (void) deleteSuffix: (NSString*)suffix;
+
+/**
+ * Removes the specified prefix from the string. Raises an exception
+ * if the prefix is not present.
+ */
- (void) deletePrefix: (NSString*)prefix;
+
+/**
+ * Replaces all occurrances of the string replace with the string by
+ * in the receiver.NSValue class can wrap a single primitive value as an
+ * object so it can be used in the containers and other places where an object
+ * reference is needed. Once initialized, an NSValue is
+ * immutable, and there is no NSMutableValue class. You
+ * initialize it by giving it a pointer to the primitive value, and you should
+ * be careful this does not get freed until after the NSValue is
+ * no longer used.
+ */
@interface NSValue : NSObject @encode(...). For example:
+NSPoint
+ * structure.
+ */
+ (NSValue*) valueWithPoint: (NSPoint)point;
+
+/**
+ * Convenience method to create instance holding a pointer. Same as
+ * using @encode(void *) in +value:withObjCType: .
+ */
+ (NSValue*) valueWithPointer: (const void*)pointer;
+
+/**
+ * Convenience method to create instance holding an NSRange
+ * structure.
+ */
+ (NSValue*) valueWithRange: (NSRange)range;
+
+/**
+ * Convenience method to create instance holding an NSRect
+ * structure.
+ */
+ (NSValue*) valueWithRect: (NSRect)rect;
+
+/**
+ * Convenience method to create instance holding an NSSize
+ * structure.
+ */
+ (NSValue*) valueWithSize: (NSSize)size;
#ifndef STRICT_OPENSTEP
+/**
+ * Synonym for value:withObjCType: .
+ */
+ (NSValue*) valueWithBytes: (const void*)value objCType: (const char*)type;
-/* Designated initializer for all concrete subclasses */
+
+/** NSValue. For equality,
+ * both contents and declared type of the two values must match.
+ */
- (BOOL) isEqualToValue: (NSValue*)other;
#endif
// Accessing Data
+/**
+ * Copies bytes from the pointer receiver was initialized with into buffer
+ * pointed to by value. Number of bytes copied is determined by the type. If
+ * type was a void * pointer or object id, the memory address itself is
+ * copied.
+ */
- (void) getValue: (void*)value;
+
+/**
+ * Returns the string @encode(...) compatible type the receiver
+ * was initialized with.
+ */
- (const char*) objCType;
+
+/**
+ * If receiver was initialized with an object ID, return it, else raises
+ * NSInternalInconsistencyException.
+ */
- (id) nonretainedObjectValue;
+
+/**
+ * If receiver was initialized with a void * pointer, return it, else raises
+ * NSInternalInconsistencyException.
+ */
- (void*) pointerValue;
+
+/**
+ * If receiver was initialized with an NSRange value, return it,
+ * else raises NSInternalInconsistencyException.
+ */
- (NSRange) rangeValue;
+
+/**
+ * If receiver was initialized with an NSRect value, return it,
+ * else raises NSInternalInconsistencyException.
+ */
- (NSRect) rectValue;
+
+/**
+ * If receiver was initialized with an NSSize value, return it,
+ * else raises NSInternalInconsistencyException.
+ */
- (NSSize) sizeValue;
+
+/**
+ * If receiver was initialized with an NSPoint value, return it,
+ * else raises NSInternalInconsistencyException.
+ */
- (NSPoint) pointValue;
@end
+/**
+ * Subclass of [NSValue] offering convenience methods for initializing from
+ * and accessing as any C primitive numeric type. On access, the value will
+ * be type-converted if necessary, using standard C conversion rules.
+ */
@interface NSNumber : NSValue '!= NO'.
+ */
- (BOOL) boolValue;
+/** Returns value as a signed char, converting if necessary. */
- (signed char) charValue;
+/** Returns value as a double, converting if necessary. */
- (double) doubleValue;
+/** Returns value as a float, converting if necessary. */
- (float) floatValue;
+/** Returns value as a (signed) int, converting if necessary. */
- (signed int) intValue;
-- (signed long long) longLongValue;
+/** Returns value as a (signed) long, converting if necessary. */
- (signed long) longValue;
+/** Returns value as a (signed) long long, converting if necessary. */
+- (signed long long) longLongValue;
+/** Returns value as a (signed) short, converting if necessary. */
- (signed short) shortValue;
-- (NSString*) stringValue;
+/** Returns value as an unsigned char, converting if necessary. */
- (unsigned char) unsignedCharValue;
+/** Returns value as an unsigned int, converting if necessary. */
- (unsigned int) unsignedIntValue;
-- (unsigned long long) unsignedLongLongValue;
+/** Returns value as an unsigned long, converting if necessary. */
- (unsigned long) unsignedLongValue;
+/** Returns value as an unsigned long long, converting if necessary. */
+- (unsigned long long) unsignedLongLongValue;
+/** Returns value as an unsigned short, converting if necessary. */
- (unsigned short) unsignedShortValue;
+/** Returns -description . */
+- (NSString*) stringValue;
+
+/**
+ * Returns the string representation of this number using a non-localised
+ * conversion (decimal point is '.' irrespective of the locale).
+ */
- (NSString*) description;
+
+/**
+ * + * Produces a string representation of the number. For a boolean + * this will be either 'true' or 'false'. For other numbers the + * format is produced using the initWithFormat:locale:... method + * of NSString, and the format depends on the type of number as + * follows - + *
+ *NSOrderedAscending,
+ * NSOrderedDescending, or NSOrderedSame depending
+ * on whether it is less than, greater than, or equal to otherNumber.
+ */
- (NSComparisonResult) compare: (NSNumber*)otherNumber;
+
+/**
+ * Returns whether receiver and otherNumber represent the same numerical value.
+ */
- (BOOL) isEqualToNumber: (NSNumber*)otherNumber;
@end
#ifndef NO_GNUSTEP
+/**
+ * GNUstep specific (non-standard) additions to the NSNumber class.
+ */
@interface NSNumber(GSCategories)
+
+/**
+ * Parses string as a double, int, or unsigned
+ * int depending on what characters are present. Uses
+ * atof and atoi which don't report errors, so be
+ * careful if the string might contain an invalid value.
+ */
+ (NSValue*) valueFromString: (NSString *)string;
@end
-/* Note: This method is not in the OpenStep spec, but they makes
- subclassing easier. */
+/** Note: Defines a method that is not in the OpenStep spec, but makes
+ subclassing easier. */
@interface NSValue (Subclassing)
-/* Used by value: withObjCType: to determine the concrete subclass to alloc */
+/** Used by value: withObjCType: to determine the concrete subclass to alloc. */
+ (Class) valueClassWithObjCType: (const char*)type;
@end