From d1f2f5f430133a4d503da2d4fec6620fc53320a5 Mon Sep 17 00:00:00 2001 From: "scc%mozilla.org" Date: Sat, 5 Aug 2000 04:25:49 +0000 Subject: [PATCH] added comments and made some changes suggested by reviewers; still not in the build git-svn-id: svn://10.0.0.236/trunk@75634 18797224-902f-48f8-a5cc-f745e15eee43 --- mozilla/string/public/nsReadableUtils.h | 62 +++++++++++++++++-- mozilla/string/src/nsReadableUtils.cpp | 17 ++++- mozilla/xpcom/ds/nsReadableUtils.cpp | 17 ++++- mozilla/xpcom/ds/nsReadableUtils.h | 62 +++++++++++++++++-- mozilla/xpcom/string/public/nsReadableUtils.h | 62 +++++++++++++++++-- mozilla/xpcom/string/src/nsReadableUtils.cpp | 17 ++++- 6 files changed, 216 insertions(+), 21 deletions(-) diff --git a/mozilla/string/public/nsReadableUtils.h b/mozilla/string/public/nsReadableUtils.h index 0201df111d5..56099a49b89 100755 --- a/mozilla/string/public/nsReadableUtils.h +++ b/mozilla/string/public/nsReadableUtils.h @@ -28,12 +28,64 @@ #include "nsAReadableString.h" -char* ToNewCString( const nsAReadableString& ); -char* ToNewCString( const nsAReadableCString& ); -PRUnichar* ToNewUnicode( const nsAReadableString& ); -PRUnichar* ToNewUnicode( const nsAReadableCString& ); + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableString& aSource ); -PRBool IsASCII( const nsAReadableString& ); + + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableCString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableCString& aSource ); + + + /** + * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F). + * + * @param aString a 16-bit wide string to scan + */ +PRBool IsASCII( const nsAReadableString& aString ); #endif // !defined(nsReadableUtils_h___) diff --git a/mozilla/string/src/nsReadableUtils.cpp b/mozilla/string/src/nsReadableUtils.cpp index aa0ab6e2426..d1c2210520e 100755 --- a/mozilla/string/src/nsReadableUtils.cpp +++ b/mozilla/string/src/nsReadableUtils.cpp @@ -28,6 +28,11 @@ + + + /** + * A character sink that performs a |reinterpret_cast| style conversion between character types. + */ template class LossyConvertEncoding { @@ -59,6 +64,15 @@ class LossyConvertEncoding output_type* mDestination; }; + + + /** + * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator). + * + * @param aSource an string you will eventually be making a copy of + * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|. + * + */ template inline ToCharT* @@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource ) PRBool IsASCII( const nsAReadableString& aString ) { - - const PRUnichar NOT_ASCII = PRUnichar(~0x007F); + static const PRUnichar NOT_ASCII = PRUnichar(~0x007F); // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character diff --git a/mozilla/xpcom/ds/nsReadableUtils.cpp b/mozilla/xpcom/ds/nsReadableUtils.cpp index aa0ab6e2426..d1c2210520e 100755 --- a/mozilla/xpcom/ds/nsReadableUtils.cpp +++ b/mozilla/xpcom/ds/nsReadableUtils.cpp @@ -28,6 +28,11 @@ + + + /** + * A character sink that performs a |reinterpret_cast| style conversion between character types. + */ template class LossyConvertEncoding { @@ -59,6 +64,15 @@ class LossyConvertEncoding output_type* mDestination; }; + + + /** + * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator). + * + * @param aSource an string you will eventually be making a copy of + * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|. + * + */ template inline ToCharT* @@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource ) PRBool IsASCII( const nsAReadableString& aString ) { - - const PRUnichar NOT_ASCII = PRUnichar(~0x007F); + static const PRUnichar NOT_ASCII = PRUnichar(~0x007F); // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character diff --git a/mozilla/xpcom/ds/nsReadableUtils.h b/mozilla/xpcom/ds/nsReadableUtils.h index 0201df111d5..56099a49b89 100755 --- a/mozilla/xpcom/ds/nsReadableUtils.h +++ b/mozilla/xpcom/ds/nsReadableUtils.h @@ -28,12 +28,64 @@ #include "nsAReadableString.h" -char* ToNewCString( const nsAReadableString& ); -char* ToNewCString( const nsAReadableCString& ); -PRUnichar* ToNewUnicode( const nsAReadableString& ); -PRUnichar* ToNewUnicode( const nsAReadableCString& ); + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableString& aSource ); -PRBool IsASCII( const nsAReadableString& ); + + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableCString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableCString& aSource ); + + + /** + * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F). + * + * @param aString a 16-bit wide string to scan + */ +PRBool IsASCII( const nsAReadableString& aString ); #endif // !defined(nsReadableUtils_h___) diff --git a/mozilla/xpcom/string/public/nsReadableUtils.h b/mozilla/xpcom/string/public/nsReadableUtils.h index 0201df111d5..56099a49b89 100755 --- a/mozilla/xpcom/string/public/nsReadableUtils.h +++ b/mozilla/xpcom/string/public/nsReadableUtils.h @@ -28,12 +28,64 @@ #include "nsAReadableString.h" -char* ToNewCString( const nsAReadableString& ); -char* ToNewCString( const nsAReadableCString& ); -PRUnichar* ToNewUnicode( const nsAReadableString& ); -PRUnichar* ToNewUnicode( const nsAReadableCString& ); + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs a lossy encoding conversion by chopping 16-bit wide characters down to 8-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableString& aSource ); -PRBool IsASCII( const nsAReadableString& ); + + /** + * Returns a new |char| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |char| buffer you must free with |nsMemory::Free|. + */ +char* ToNewCString( const nsAReadableCString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource a 16-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableString& aSource ); + + + /** + * Returns a new |PRUnichar| buffer containing a zero-terminated copy of |aSource|. + * + * Allocates and returns a new |char| buffer which you must free with |nsMemory::Free|. + * Performs an encoding conversion by 0-padding 8-bit wide characters up to 16-bits wide while copying |aSource| to your new buffer. + * This conversion is not well defined; but it reproduces legacy string behavior. + * The new buffer is zero-terminated, but that may not help you if |aSource| contains embedded nulls. + * + * @param aSource an 8-bit wide string + * @return a new |PRUnichar| buffer you must free with |nsMemory::Free|. + */ +PRUnichar* ToNewUnicode( const nsAReadableCString& aSource ); + + + /** + * Returns |PR_TRUE| if |aString| contains only ASCII characters, that is, characters in the range (0x00, 0x7F). + * + * @param aString a 16-bit wide string to scan + */ +PRBool IsASCII( const nsAReadableString& aString ); #endif // !defined(nsReadableUtils_h___) diff --git a/mozilla/xpcom/string/src/nsReadableUtils.cpp b/mozilla/xpcom/string/src/nsReadableUtils.cpp index aa0ab6e2426..d1c2210520e 100755 --- a/mozilla/xpcom/string/src/nsReadableUtils.cpp +++ b/mozilla/xpcom/string/src/nsReadableUtils.cpp @@ -28,6 +28,11 @@ + + + /** + * A character sink that performs a |reinterpret_cast| style conversion between character types. + */ template class LossyConvertEncoding { @@ -59,6 +64,15 @@ class LossyConvertEncoding output_type* mDestination; }; + + + /** + * A helper function that allocates a buffer of the desired character type big enough to hold a copy of the supplied string (plus a zero terminator). + * + * @param aSource an string you will eventually be making a copy of + * @return a new buffer (of the type specified by the second parameter) which you must free with |nsMemory::Free|. + * + */ template inline ToCharT* @@ -107,8 +121,7 @@ ToNewUnicode( const nsAReadableCString& aSource ) PRBool IsASCII( const nsAReadableString& aString ) { - - const PRUnichar NOT_ASCII = PRUnichar(~0x007F); + static const PRUnichar NOT_ASCII = PRUnichar(~0x007F); // Don't want to use |copy_string| for this task, since we can stop at the first non-ASCII character