From f543f0dbe10dab780d36c203fef6b3203f09b523 Mon Sep 17 00:00:00 2001 From: George Rhoten Date: Thu, 27 May 2004 05:24:44 +0000 Subject: [PATCH] ICU-3499 Improve some documentation X-SVN-Rev: 15576 --- icu4c/source/io/unicode/ustdio.h | 128 ++++++++++++++----------------- 1 file changed, 57 insertions(+), 71 deletions(-) diff --git a/icu4c/source/io/unicode/ustdio.h b/icu4c/source/io/unicode/ustdio.h index 7e0b559424d..fc4a9a1c847 100644 --- a/icu4c/source/io/unicode/ustdio.h +++ b/icu4c/source/io/unicode/ustdio.h @@ -77,6 +77,7 @@ * Make sure that a UFile opened with "rw" can be used after using u_fflush with a u_frewind. * scanf(%i) should detect what type of number to use. + * Add more testing of the alternate format, %# * Complete the file documentation with proper doxygen formatting. See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html */ @@ -86,52 +87,61 @@ * \brief C API: Unicode stdio-like API * *

Unicode stdio-like C API

-printf -fmt type Comment -%E double Scientific with an uppercase exponent -%e double Scientific with a lowercase exponent -%G double Use %E or %f for best format -%g double Use %e or %f for best format -%f double Simple floating point without the exponent -%X int32_t ustdio special uppercase hex radix formatting -%x int32_t ustdio special lowercase hex radix formatting -%d int32_t Decimal format -%i int32_t Same as %d -%n int32_t count (write the number of chars written) -%o int32_t octal ustdio special octal radix formatting -%u uint32_t Decimal format -%p void * Prints the pointer value -%s char * Use default converter or specified converter from fopen -%hs char * (Unimplemented) Use invariant converter -%ls N/A (Unimplemented) Reserved for future implementation -%c char Use default converter or specified converter from fopen -%hc char (Unimplemented) Use invariant converter -%lc N/A (Unimplemented) Reserved for future implementation -%S UChar * Null terminated UTF-16 string -%hS char * (Unimplemented) Null terminated UTF-8 string -%lS UChar32 * (Unimplemented) Null terminated UTF-32 string -%C UChar 16-bit Unicode code unit -%hC char (Unimplemented) 8-bit Unicode code unit -%lC UChar32 (Unimplemented) 32-bit Unicode code unit -%% N/A Show a percent sign +General printf format:
+%[format modifier][width][.precision][type modifier][format] + +General scanf format:
+%[*][format modifier][width][type modifier][format] + + + + + + + + + + + + + + + + + + + + + +
formatdefault
type		description
%EdoubleScientific with an uppercase exponent
%edoubleScientific with a lowercase exponent
%GdoubleUse %E or %f for best format
%gdoubleUse %e or %f for best format
%fdoubleSimple floating point without the exponent
%Xint32_tustdio special uppercase hex radix formatting
%xint32_tustdio special lowercase hex radix formatting
%dint32_tDecimal format
%iint32_tSame as %d
%nint32_tcount (write the number of chars written)
%oint32_tustdio special octal radix formatting
%uuint32_tDecimal format
%pvoid *Prints the pointer value
%schar *Use default converter or specified converter from fopen
%ccharUse default converter or specified converter from fopen
%SUChar *Null terminated UTF-16 string
%CUChar16-bit Unicode code unit
%%N/AShow a percent sign
Format modifiers -%h int16_t short format for %d, %i, %o, %x -%l int32_t long format for %d, %i, %o, %x (no effect) -%ll int64_t long long format for %d, %i, %o, %x -%h uint16_t short format for %u -%l uint32_t long format for %u (no effect) -%ll uint64_t (Unimplemented) long long format for %u -%- N/A Left justify -%+ N/A Always show the plus or minus sign. Needs data for plus sign. -% N/A Instead of a "+" output a blank character for positive numbers. -%# N/A Precede octal value with 0, hex with 0x and show the - decimal point for floats. -%num N/A Width of input/output. num is an actual number from 0 to - some large number. -%.num N/A Significant digits precision. num is an actual number from - 0 to some large number. Currently can only specify precision - before or after decimal, and not total precision. + + + + + + + + + + + + + + + + + + +%d, %i, %o, %x, %e, %f, %g, %E, %F, %G +%d, %i, %o, %x, %e, %f, %g, %E, %F, %G + + +
modifierformatstypecomments
%h%d, %i, %o, %xint16_tshort format
%h%uuint16_tshort format
%hcchar(Unimplemented) Use invariant converter
%hschar *(Unimplemented) Use invariant converter
%hCchar(Unimplemented) 8-bit Unicode code unit
%hSchar *(Unimplemented) Null terminated UTF-8 string
%l%d, %i, %o, %xint32_tlong format (no effect)
%l%uuint32_tlong format (no effect)
%lcN/A(Unimplemented) Reserved for future implementation
%lsN/A(Unimplemented) Reserved for future implementation
%lCUChar32(Unimplemented) 32-bit Unicode code unit
%lSUChar32 *(Unimplemented) Null terminated UTF-32 string
%ll%d, %i, %o, %xint64_tlong long format
%ll%uuint64_t(Unimplemented) long long format
%-allN/ALeft justify
%+%d, %i, %o, %x, %e, %f, %g, %E, %F, %GN/AAlways show the plus or minus sign. Needs data for plus sign.
% N/AInstead of a "+" output a blank character for positive numbers.
%#N/APrecede octal value with 0, hex with 0x and show the + decimal point for floats.
%nallN/AWidth of input/output. num is an actual number from 0 to + some large number.
%.n%e, %f, %g, %E, %F, %GN/ASignificant digits precision. num is an actual number from + 0 to some large number.
If * is used in printf, then the precision is passed in as an argument before the number to be formatted.
printf modifier %* int32_t Next argument after this one specifies the width @@ -211,7 +221,7 @@ u_finit(FILE *f, * The string is usable once u_fclose or u_fflush has been called on the * returned UFILE. * @param stringBuf The string used for reading or writing. - * @param count The number of code units available for use in stringBuf + * @param capacity The number of code units available for use in stringBuf * @param locale The locale whose conventions will be used to format * and parse output. If this parameter is NULL, the default locale will * be used. @@ -331,7 +341,7 @@ u_fsetcodepage(const char *codepage, /** * Returns an alias to the converter being used for this file. - * @param file The UFILE to set. + * @param f The UFILE to get the value from * @return alias to the converter * @draft 3.0 */ @@ -611,8 +621,6 @@ u_fsettransliterator(UFILE *file, UFileDirection direction, * Write formatted data to a Unicode string. * * @param buffer The Unicode String to which to write. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @return The number of Unicode code units written to buffer. This @@ -634,8 +642,6 @@ u_sprintf(UChar *buffer, * * @param buffer The Unicode String to which to write. * @param count The number of code units to read. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @return The number of Unicode code units written to buffer. This @@ -654,8 +660,6 @@ u_snprintf(UChar *buffer, * not call va_start/TT> and va_end. * * @param buffer The Unicode string to which to write. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @param ap The argument list to use. @@ -680,8 +684,6 @@ u_vsprintf(UChar *buffer, * * @param buffer The Unicode string to which to write. * @param count The number of code units to read. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @param ap The argument list to use. @@ -699,8 +701,6 @@ u_vsnprintf(UChar *buffer, * Write formatted data to a Unicode string. * * @param buffer The Unicode string to which to write. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @return The number of Unicode characters written to buffer. @@ -721,8 +721,6 @@ u_sprintf_u(UChar *buffer, * * @param buffer The Unicode string to which to write. * @param count The number of code units to read. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @return The number of Unicode characters written to buffer. @@ -740,9 +738,6 @@ u_snprintf_u(UChar *buffer, * not call va_start/TT> and va_end. * * @param buffer The Unicode string to which to write. - * @param count The number of code units to read. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @param ap The argument list to use. @@ -766,8 +761,7 @@ u_vsprintf_u(UChar *buffer, * null terminated and count is returned. * * @param buffer The Unicode string to which to write. - * @param locale The locale to use for formatting the numbers, dates and other - * locale specific information. + * @param count The number of code units to read. * @param patternSpecification A pattern specifying how u_sprintf will * interpret the variable arguments received and format the data. * @param ap The argument list to use. @@ -787,8 +781,6 @@ u_vsnprintf_u(UChar *buffer, * Read formatted data from a Unicode string. * * @param buffer The Unicode string from which to read. - * @param locale The locale to use for parsing the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sscanf will * interpret the variable arguments received and parse the data. * @return The number of items successfully converted and assigned, or EOF @@ -806,8 +798,6 @@ u_sscanf(const UChar *buffer, * not call va_start/TT> and va_end. * * @param buffer The Unicode string from which to read. - * @param locale The locale to use for parsing the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sscanf will * interpret the variable arguments received and parse the data. * @param ap The argument list to use. @@ -825,8 +815,6 @@ u_vsscanf(const UChar *buffer, * Read formatted data from a Unicode string. * * @param buffer The Unicode string from which to read. - * @param locale The locale to use for parsing the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sscanf will * interpret the variable arguments received and parse the data. * @return The number of items successfully converted and assigned, or EOF @@ -844,8 +832,6 @@ u_sscanf_u(const UChar *buffer, * not call va_start/TT> and va_end. * * @param buffer The Unicode string from which to read. - * @param locale The locale to use for parsing the numbers, dates and other - * locale specific information. * @param patternSpecification A pattern specifying how u_sscanf will * interpret the variable arguments received and parse the data. * @param ap The argument list to use.