From b37baacb77f6b5bfd7dc67030648288ecf5d1724 Mon Sep 17 00:00:00 2001 From: CaS Date: Tue, 31 Dec 2002 11:48:36 +0000 Subject: [PATCH] More documentation tweaks git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@15426 72102866-910b-0410-8b05-ffd578937521 --- Headers/gnustep/base/Unicode.h | 39 ++++++++++++++----------- Source/Additions/Unicode.m | 53 +++++++++++++++++++++++++++++----- 2 files changed, 67 insertions(+), 25 deletions(-) diff --git a/Headers/gnustep/base/Unicode.h b/Headers/gnustep/base/Unicode.h index cdf03de1e..e2348dede 100644 --- a/Headers/gnustep/base/Unicode.h +++ b/Headers/gnustep/base/Unicode.h @@ -1,4 +1,4 @@ -/* Interface for support functions for Unicode implementation. +/** Interface for support functions for Unicode implementation. Interface for GetDefEncoding function to determine default c string encoding for GNUstep based on GNUSTEP_STRING_ENCODING environment variable. @@ -24,6 +24,9 @@ You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA. + + AutogsdocSource: Additions/Unicode.m + */ #ifndef __Unicode_h_OBJECTS_INCLUDE @@ -41,22 +44,7 @@ GS_EXPORT NSStringEncoding GetDefEncoding(void); GS_EXPORT NSStringEncoding GSEncodingFromLocale(const char *clocale); GS_EXPORT NSStringEncoding GSEncodingForRegistry(NSString *registry, NSString *encoding); -GS_EXPORT NSString* GetEncodingName(NSStringEncoding encoding); - -GS_EXPORT unichar chartouni(unsigned char c); -GS_EXPORT unsigned char unitochar(unichar u); -GS_EXPORT unichar encode_chartouni(unsigned char c, NSStringEncoding enc); -GS_EXPORT unsigned char encode_unitochar(unichar u, NSStringEncoding enc); -GS_EXPORT unsigned encode_unitochar_strict(unichar u, NSStringEncoding enc); - -/** - * The next two functions are deprecated and will be removed in a future - * release. Use GSFromUnicode() and GSToUnicode() instead. - */ -GS_EXPORT int encode_ustrtocstr(char *dst, int dl, const unichar *src, int sl, - NSStringEncoding enc, BOOL strict); -GS_EXPORT int encode_cstrtoustr(unichar *dst, int dl, const char *str, int sl, - NSStringEncoding enc); +GS_EXPORT NSString* GSEncodingName(NSStringEncoding encoding); GS_EXPORT unichar uni_tolower(unichar ch); GS_EXPORT unichar uni_toupper(unichar ch); @@ -64,6 +52,7 @@ GS_EXPORT unsigned char uni_cop(unichar u); GS_EXPORT BOOL uni_isnonsp(unichar u); GS_EXPORT unichar *uni_is_decomp(unichar u); + /* * Options when converting strings. */ @@ -80,6 +69,22 @@ GS_EXPORT BOOL GSToUnicode(unichar **dst, unsigned int *size, const unsigned char *src, unsigned int slen, NSStringEncoding enc, NSZone *zone, unsigned int options); +/* + * The next functions are deprecated and will be removed in a future + * release. Use GSFromUnicode() and GSToUnicode() instead. + */ +GS_EXPORT NSString* GetEncodingName(NSStringEncoding encoding); +GS_EXPORT unichar chartouni(unsigned char c); +GS_EXPORT unsigned char unitochar(unichar u); +GS_EXPORT unichar encode_chartouni(unsigned char c, NSStringEncoding enc); +GS_EXPORT unsigned char encode_unitochar(unichar u, NSStringEncoding enc); +GS_EXPORT unsigned encode_unitochar_strict(unichar u, NSStringEncoding enc); +GS_EXPORT int encode_ustrtocstr(char *dst, int dl, const unichar *src, int sl, + NSStringEncoding enc, BOOL strict); +GS_EXPORT int encode_cstrtoustr(unichar *dst, int dl, const char *src, int sl, + NSStringEncoding enc); + + #endif #endif /* __Unicode_h_OBJECTS_INCLUDE */ diff --git a/Source/Additions/Unicode.m b/Source/Additions/Unicode.m index 22b99b521..f6ef44a3d 100644 --- a/Source/Additions/Unicode.m +++ b/Source/Additions/Unicode.m @@ -294,7 +294,11 @@ static BOOL GSEncodingSupported(NSStringEncoding enc) return NO; } -NSStringEncoding *GetAvailableEncodings() +/** + * Returns a nul terminated array of the available string encodings. + */ +NSStringEncoding * +GetAvailableEncodings() { if (_availableEncodings == 0) { @@ -579,6 +583,9 @@ GSIsByteEncoding(NSStringEncoding encoding) return encodingTable[encoding]->eightBit; } +/** + * Returns the standard name for the specified encoding. + */ NSString* GSEncodingName(NSStringEncoding encoding) { @@ -589,6 +596,9 @@ GSEncodingName(NSStringEncoding encoding) return [NSString stringWithCString: encodingTable[encoding]->ename]; } +/** + * deprecated Use GSEncodingName() + */ NSString* GetEncodingName(NSStringEncoding encoding) { @@ -605,6 +615,10 @@ iconv_stringforencoding(NSStringEncoding encoding) return encodingTable[encoding]->iconv; } +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ unichar encode_chartouni(unsigned char c, NSStringEncoding enc) { @@ -621,6 +635,10 @@ encode_chartouni(unsigned char c, NSStringEncoding enc) return u; } +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ unsigned char encode_unitochar(unichar u, NSStringEncoding enc) { @@ -637,6 +655,10 @@ encode_unitochar(unichar u, NSStringEncoding enc) return c; } +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ unsigned encode_unitochar_strict(unichar u, NSStringEncoding enc) { @@ -653,6 +675,10 @@ encode_unitochar_strict(unichar u, NSStringEncoding enc) return c; } +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ unichar chartouni(unsigned char c) { @@ -663,6 +689,10 @@ chartouni(unsigned char c) return encode_chartouni(c, defEnc); } +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ unsigned char unitochar(unichar u) { @@ -673,8 +703,8 @@ unitochar(unichar u) return encode_unitochar(u, defEnc); } -/* - * These two functions use direct access into a two-level table to map cases. +/** + * Uses direct access into a two-level table to map cases.
* The two-level table method is less space efficient (but still not bad) than * a single table and a linear search, but it reduces the number of * conditional statements to just one. @@ -687,6 +717,12 @@ uni_tolower(unichar ch) return result ? result : ch; } +/** + * Uses direct access into a two-level table to map cases.
+ * The two-level table method is less space efficient (but still not bad) than + * a single table and a linear search, but it reduces the number of + * conditional statements to just one. + */ unichar uni_toupper(unichar ch) { @@ -797,7 +833,10 @@ uni_is_decomp(unichar u) } } - +/** + * deprecated + * See GSToUnicode() and GSFromUnicode() + */ int encode_ustrtocstr(char *dst, int dl, const unichar *src, int sl, NSStringEncoding enc, BOOL strict) { @@ -815,7 +854,8 @@ int encode_ustrtocstr(char *dst, int dl, const unichar *src, int sl, } /** - * Convert to unicode .. return the number of unicode characters produced. + * deprecated + * See GSToUnicode() and GSFromUnicode() */ int encode_cstrtoustr(unichar *dst, int dl, const char *src, int sl, NSStringEncoding enc) @@ -923,7 +963,6 @@ else \ * release. * If GSUniBOM is set, the function will write the first unicode * character as a byte order marker. - * * If GSUniShortOk is set, the function will return a buffer containing * any decoded characters even if the whole conversion fails. * @@ -1393,7 +1432,6 @@ static inline int chop(unichar c, _ucc_ *table, int hi) * If GSUniStrict is set, the function will fail if a character is * encountered which can't be displayed in the source. Otherwise, some * approximation or marker will be placed in the destination. - * * If GSUniTerminate is set, the function is expected to null terminate * the output string, and will assume that it is safe to place the nul * just beyond the ned of the stated buffer size. @@ -1407,7 +1445,6 @@ static inline int chop(unichar c, _ucc_ *table, int hi) * If GSUniShortOk is set, the function will return a buffer containing * any decoded characters even if the whole conversion fails. * - * *

On return, the function result is a flag indicating success (YES) * or failure (NO), and on success, the value stored in size is the number * of characters in the converted string. The converted string itsself is