md5 improvements and documentation tidyups

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@15688 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,13 @@
+2003-01-24  Richard Frith-Macdonald <rfm@gnu.org>
+
+
+	* Source/Additions/GSCategories.m: Changed name of md5 digest method
+	and added -hexadecimalRepresentation.
+	* Source/Additions/GSMime.m: Update for md5 change.
+	* Documentation/GNUmakefile: Fixed error in installation location.
+	* Documentation/Makefile.postamble: Fixed to install BaseAdditions
+	documentation.
+
 2003-01-23  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Documentation/Base.gsdoc: Refer to additions.

Documentation/GNUmakefile

@@ -79,7 +79,7 @@ ANNOUNCE_DOC_INSTALL_DIR = Developer/Base/ReleaseNotes/$(VERSION)
 # file using the make file ../Source/DocMakefile.  If headers are added to the
 # library, you need to modify that file to get the autogsdoc tool to use them.
 #
-REF_DOC_INSTALL_DIR = $(GNUSTEP_INSTALLATION_DIR)/Documentation/Developer/Base/Reference
+REF_DOC_INSTALL_DIR = $(GNUSTEP_INSTALLATION_DIR)/Documentation/Developer
 
 -include Makefile.preamble
 

Documentation/Makefile.postamble

@@ -53,13 +53,18 @@ endif
 #
 after-install::
 ifeq ($(HAVE_LIBXML),1)
-	rm -rf $(REF_DOC_INSTALL_DIR)
-	$(MKDIRS) $(REF_DOC_INSTALL_DIR)
+	rm -rf $(REF_DOC_INSTALL_DIR)/Base/Reference
+	rm -rf $(REF_DOC_INSTALL_DIR)/BaseAdditions/Reference
+	$(MKDIRS) $(REF_DOC_INSTALL_DIR)/Base/Reference
+	$(MKDIRS) $(REF_DOC_INSTALL_DIR)/BaseAdditions/Reference
 	(cd Base; $(TAR) cf - .) | \
-	  (cd $(REF_DOC_INSTALL_DIR); $(TAR) xf -)
+	  (cd $(REF_DOC_INSTALL_DIR)/Base/Reference; $(TAR) xf -)
+	(cd BaseAdditions; $(TAR) cf - .) | \
+	  (cd $(REF_DOC_INSTALL_DIR)/BaseAdditions/Reference; $(TAR) xf -)
 ifneq ($(CHOWN_TO),)
 	$(CHOWN) -R $(CHOWN_TO) \
-	  $(REF_DOC_INSTALL_DIR)
+	  $(REF_DOC_INSTALL_DIR/Base)
+	  $(REF_DOC_INSTALL_DIR/BaseAdditions)
 endif
 endif
 

Headers/gnustep/base/GSCategories.h

@@ -38,7 +38,8 @@
 
 @interface NSData (GSCategories)
 
-- (NSData*) MD5Digest;
+- (NSString*) hexadecimalRepresentation;
+- (NSData*) md5Digest;
 
 @end
 

Source/Additions/GSCategories.m

@@ -93,7 +93,49 @@
  * Extension methods for the NSData class
  */
 @implementation NSData (GSCategories)
-  
+
+/**
+ * Returns an NSString object containing an ASCII hexadecimal representation
+ * of the receiver.  This means that the returned object will contain
+ * exactly twice as many characters as there are bytes as the receiver,
+ * as each byte in the receiver is represented by two hexadecimal digits.<br />
+ * 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.<br />
+ * If you need the hexadecimal representation as raw byte data, use code
+ * like -
+ * <example>
+ *   hexData = [[sourceData hexadecimalRepresentation]
+ *     dataUsingEncoding: NSASCIIStringEncoding];
+ * </example>
+ */
+- (NSString*) hexadecimalRepresentation
+{
+  static const char	*hexChars = "0123456789ABCDEF";
+  unsigned		slen = [self length];
+  unsigned		dlen = slen * 2;
+  const unsigned char	*src = (const unsigned char *)[self bytes];
+  char			*dst = (char*)NSZoneMalloc(NSDefaultMallocZone(), dlen);
+  unsigned		spos = 0;
+  unsigned		dpos = 0;
+  NSData		*data;
+  NSString		*string;
+
+  while (spos < slen)
+    {
+      unsigned char	c = src[spos++];
+
+      dst[dpos++] = hexChars[(c >> 4) & 0x0f];
+      dst[dpos++] = hexChars[c & 0x0f];
+    }
+  data = [NSData allocWithZone: NSDefaultMallocZone()];
+  data = [data initWithBytesNoCopy: dst length: dlen freeWhenDone: YES];
+  string = [[NSString alloc] initWithData: data
+				 encoding: NSASCIIStringEncoding];
+  RELEASE(data);
+  return AUTORELEASE(string);
+}
+
 struct MD5Context
 {
   unsigned long buf[4];
@@ -354,9 +396,19 @@ static void MD5Transform (unsigned long buf[4], unsigned long const in[16])
 
 /**
  * Creates an MD5 digest of the information stored in the receiver and
- * returns it as an autoreleased 16 byte NSData object.
+ * returns it as an autoreleased 16 byte NSData object.<br />
+ * 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 -
+ * <example>
+ *   myDigest = [[myString dataUsingEncoding: NSUTF8StringEncoding] md5Digest];
+ * </example>
+ * If you need to use the digest in a human readable form, you will
+ * probably want it to be seen as 32 hexadecimal digits, and can do that
+ * using the -hexadecimalRepresentation method.
  */
-- (NSData*) MD5Digest
+- (NSData*) md5Digest
 {
   struct MD5Context	ctx;
   unsigned char		digest[16];

Source/Additions/GSMime.m

@@ -3742,7 +3742,7 @@ static NSCharacterSet	*tokenSet = nil;
 
   source = [[[NSProcessInfo processInfo] globallyUniqueString]
     dataUsingEncoding: NSUTF8StringEncoding];
-  digest = [source MD5Digest];
+  digest = [source md5Digest];
   memcpy(output, [digest bytes], 16);
   output[16] = (sequence >> 24) & 0xff;
   output[17] = (sequence >> 16) & 0xff;

Source/NSString.m

@@ -1505,21 +1505,48 @@ handle_printf_atsign (FILE *stream,
   return array;
 }
 
+/**
+ * Returns a substring of the receiver from character at the specified
+ * index to the end of the string.<br />
+ * So, supplying an index of 3 would return a substring consisting of
+ * the entire string apart from the first three character (those would
+ * be at index 0, 1, and 2).<br />
+ * If the supplied index is greater than or equal to the length of the
+ * receiver an exception is raised.
+ */ 
 - (NSString*) substringFromIndex: (unsigned int)index
 {
   return [self substringWithRange: ((NSRange){index, [self length]-index})];
 }
 
+/**
+ * Returns a substring of the receiver from the start of the
+ * string to (but not including) the specified index position.<br />
+ * So, supplying an index of 3 would return a substring consisting of
+ * the first three characters of the receiver.<br />
+ * If the supplied index is greater than the length of the receiver
+ * an exception is raised.
+ */ 
 - (NSString*) substringToIndex: (unsigned int)index
 {
   return [self substringWithRange: ((NSRange){0,index})];;
 }
 
+/**
+ * An obsolete name for -substringWithRange: ... deprecated.
+ */
 - (NSString*) substringFromRange: (NSRange)aRange
 {
   return [self substringWithRange: aRange];
 }
 
+/**
+ * Returns a substring of the receiver containing the characters
+ * in aRange.<br />
+ * If aRange specifies any character position not
+ * present in the receiver, an exception is raised.<br />
+ * If aRange has a length of zero, an empty string is returned.
+ */
 - (NSString*) substringWithRange: (NSRange)aRange
 {
   unichar	*buf;