ustdio.h
Go to the documentation of this file.
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
******************************************************************************
*
* Copyright (C) 1998-2015, International Business Machines
* Corporation and others. All Rights Reserved.
*
******************************************************************************
*
* File ustdio.h
*
* Modification History:
*
* Date Name Description
* 10/16/98 stephen Creation.
* 11/06/98 stephen Modified per code review.
* 03/12/99 stephen Modified for new C API.
* 07/19/99 stephen Minor doc update.
* 02/01/01 george Added sprintf & sscanf with all of its variants
******************************************************************************
*/
#ifndef USTDIO_H
#define USTDIO_H
#include <stdio.h>
#include <stdarg.h>
#include "unicode/utypes.h"
#include "unicode/ucnv.h"
#include "unicode/utrans.h"
#include "unicode/unum.h"
#if U_SHOW_CPLUSPLUS_API
#include "unicode/localpointer.h"
#endif // U_SHOW_CPLUSPLUS_API
#if !UCONFIG_NO_CONVERSION
/*
TODO
The following is a small list as to what is currently wrong/suggestions for
ustdio.
* Make sure that * in the scanf format specification works for all formats.
* Each UFILE takes up at least 2KB.
Look into adding setvbuf() for configurable buffers.
* This library does buffering. The OS should do this for us already. Check on
this, and remove it from this library, if this is the case. Double buffering
wastes a lot of time and space.
* Test stdin and stdout with the u_f* functions
* Testing should be done for reading and writing multi-byte encodings,
and make sure that a character that is contained across buffer boundaries
works even for incomplete characters.
* Make sure that the last character is flushed when the file/string is closed.
* snprintf should follow the C99 standard for the return value, which is
return the number of characters (excluding the trailing '\0')
which would have been written to the destination string regardless
of available space. This is like pre-flighting.
* Everything that uses %s should do what operator>> does for UnicodeString.
It should convert one byte at a time, and once a character is
converted then check to see if it's whitespace or in the scanset.
If it's whitespace or in the scanset, put all the bytes back (do nothing
for sprintf/sscanf).
* If bad string data is encountered, make sure that the function fails
without memory leaks and the unconvertable characters are valid
substitution or are escaped characters.
* u_fungetc() can't unget a character when it's at the beginning of the
internal conversion buffer. For example, read the buffer size # of
characters, and then ungetc to get the previous character that was
at the end of the last buffer.
* u_fflush() and u_fclose should return an int32_t like C99 functions.
0 is returned if the operation was successful and EOF otherwise.
* u_fsettransliterator does not support U_READ side of transliteration.
* The format specifier should limit the size of a format or honor it in
order to prevent buffer overruns. (e.g. %256.256d).
* u_fread and u_fwrite don't exist. They're needed for reading and writing
data structures without any conversion.
* u_file_read and u_file_write are used for writing strings. u_fgets and
u_fputs or u_fread and u_fwrite should be used to do this.
* The width parameter for all scanf formats, including scanset, needs
better testing. This prevents buffer overflows.
* Figure out what is suppose to happen when a codepage is changed midstream.
Maybe a flush or a rewind are good enough.
* 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, %#
* Look at newline handling of fputs/puts
* Think more about codeunit/codepoint error handling/support in %S,%s,%C,%c,%[]
* Complete the file documentation with proper doxygen formatting.
See http://oss.software.ibm.com/pipermail/icu/2003-July/005647.html
*/
#define U_EOF 0xFFFF
typedef struct UFILE UFILE;
typedef enum {
U_READ = 1,
U_WRITE = 2,
U_READWRITE =3 /* == (U_READ | U_WRITE) */
} UFileDirection;
U_CAPI UFILE* U_EXPORT2
u_fopen(const char *filename,
const char *perm,
const char *locale,
const char *codepage);
U_CAPI UFILE* U_EXPORT2
u_fopen_u(const UChar *filename,
const char *perm,
const char *locale,
const char *codepage);
U_CAPI UFILE* U_EXPORT2
u_finit(FILE *f,
const char *locale,
const char *codepage);
U_CAPI UFILE* U_EXPORT2
u_fadopt(FILE *f,
const char *locale,
const char *codepage);
U_CAPI UFILE* U_EXPORT2
u_fstropen(UChar *stringBuf,
int32_t capacity,
const char *locale);
U_CAPI void U_EXPORT2
u_fclose(UFILE *file);
#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
U_DEFINE_LOCAL_OPEN_POINTER(LocalUFILEPointer, UFILE, u_fclose);
U_NAMESPACE_END
#endif
U_CAPI UBool U_EXPORT2
u_feof(UFILE *f);
U_CAPI void U_EXPORT2
u_fflush(UFILE *file);
U_CAPI void
u_frewind(UFILE *file);
U_CAPI FILE* U_EXPORT2
u_fgetfile(UFILE *f);
#if !UCONFIG_NO_FORMATTING
U_CAPI const char* U_EXPORT2
u_fgetlocale(UFILE *file);
U_CAPI int32_t U_EXPORT2
u_fsetlocale(UFILE *file,
const char *locale);
#endif
U_CAPI const char* U_EXPORT2
u_fgetcodepage(UFILE *file);
U_CAPI int32_t U_EXPORT2
u_fsetcodepage(const char *codepage,
UFILE *file);
U_CAPI UConverter* U_EXPORT2 u_fgetConverter(UFILE *f);
#if !UCONFIG_NO_FORMATTING
U_CAPI const UNumberFormat* U_EXPORT2 u_fgetNumberFormat(UFILE *f);
/* Output functions */
U_CAPI int32_t U_EXPORT2
u_printf(const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_fprintf(UFILE *f,
const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vfprintf(UFILE *f,
const char *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_printf_u(const UChar *patternSpecification,
... );
U_CAPI UFILE * U_EXPORT2
u_get_stdout(void);
U_CAPI int32_t U_EXPORT2
u_fprintf_u(UFILE *f,
const UChar *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vfprintf_u(UFILE *f,
const UChar *patternSpecification,
va_list ap);
#endif
U_CAPI int32_t U_EXPORT2
u_fputs(const UChar *s,
UFILE *f);
U_CAPI UChar32 U_EXPORT2
u_fputc(UChar32 uc,
UFILE *f);
U_CAPI int32_t U_EXPORT2
u_file_write(const UChar *ustring,
int32_t count,
UFILE *f);
/* Input functions */
#if !UCONFIG_NO_FORMATTING
U_CAPI int32_t U_EXPORT2
u_fscanf(UFILE *f,
const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vfscanf(UFILE *f,
const char *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_fscanf_u(UFILE *f,
const UChar *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vfscanf_u(UFILE *f,
const UChar *patternSpecification,
va_list ap);
#endif
U_CAPI UChar* U_EXPORT2
u_fgets(UChar *s,
int32_t n,
UFILE *f);
U_CAPI UChar U_EXPORT2
u_fgetc(UFILE *f);
U_CAPI UChar32 U_EXPORT2
u_fgetcx(UFILE *f);
U_CAPI UChar32 U_EXPORT2
u_fungetc(UChar32 c,
UFILE *f);
U_CAPI int32_t U_EXPORT2
u_file_read(UChar *chars,
int32_t count,
UFILE *f);
#if !UCONFIG_NO_TRANSLITERATION
U_CAPI UTransliterator* U_EXPORT2
u_fsettransliterator(UFILE *file, UFileDirection direction,
UTransliterator *adopt, UErrorCode *status);
#endif
/* Output string functions */
#if !UCONFIG_NO_FORMATTING
U_CAPI int32_t U_EXPORT2
u_sprintf(UChar *buffer,
const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_snprintf(UChar *buffer,
int32_t count,
const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vsprintf(UChar *buffer,
const char *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_vsnprintf(UChar *buffer,
int32_t count,
const char *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_sprintf_u(UChar *buffer,
const UChar *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_snprintf_u(UChar *buffer,
int32_t count,
const UChar *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vsprintf_u(UChar *buffer,
const UChar *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_vsnprintf_u(UChar *buffer,
int32_t count,
const UChar *patternSpecification,
va_list ap);
/* Input string functions */
U_CAPI int32_t U_EXPORT2
u_sscanf(const UChar *buffer,
const char *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vsscanf(const UChar *buffer,
const char *patternSpecification,
va_list ap);
U_CAPI int32_t U_EXPORT2
u_sscanf_u(const UChar *buffer,
const UChar *patternSpecification,
... );
U_CAPI int32_t U_EXPORT2
u_vsscanf_u(const UChar *buffer,
const UChar *patternSpecification,
va_list ap);
#endif
#endif
#endif
LocalUFILEPointer
"Smart pointer" class, closes a UFILE via u_fclose().
localpointer.h
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
U_DEFINE_LOCAL_OPEN_POINTER
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:550
ucnv.h
C API: Character conversion.
UConverter
struct UConverter UConverter
Definition: ucnv_err.h:96
UChar32
int32_t UChar32
Define UChar32 as a type for single Unicode code points.
Definition: umachine.h:427
UBool
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:247
U_CAPI
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
UChar
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:378
unum.h
C API: Compatibility APIs for number formatting.
UNumberFormat
void * UNumberFormat
A number formatter.
Definition: unum.h:145
u_vfprintf_u
U_CAPI int32_t u_vfprintf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Write formatted data to a UFILE.
u_fopen_u
U_CAPI UFILE * u_fopen_u(const UChar *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE with a UChar* filename A UFILE is a wrapper around a FILE* that is locale and codepage a...
u_feof
U_CAPI UBool u_feof(UFILE *f)
Tests if the UFILE is at the end of the file stream.
u_fscanf_u
U_CAPI int32_t u_fscanf_u(UFILE *f, const UChar *patternSpecification,...)
Read formatted data from a UFILE.
u_vfprintf
U_CAPI int32_t u_vfprintf(UFILE *f, const char *patternSpecification, va_list ap)
Write formatted data to a UFILE.
u_fgetc
U_CAPI UChar u_fgetc(UFILE *f)
Read a UChar from a UFILE.
u_fgetcodepage
U_CAPI const char * u_fgetcodepage(UFILE *file)
Get the codepage in which data is written to and read from the UFILE.
u_file_write
U_CAPI int32_t u_file_write(const UChar *ustring, int32_t count, UFILE *f)
Write Unicode to a UFILE.
u_fflush
U_CAPI void u_fflush(UFILE *file)
Flush output of a UFILE.
u_vfscanf_u
U_CAPI int32_t u_vfscanf_u(UFILE *f, const UChar *patternSpecification, va_list ap)
Read formatted data from a UFILE.
u_fopen
U_CAPI UFILE * u_fopen(const char *filename, const char *perm, const char *locale, const char *codepage)
Open a UFILE.
u_vsnprintf_u
U_CAPI int32_t u_vsnprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_fgetNumberFormat
U_CAPI const UNumberFormat * u_fgetNumberFormat(UFILE *f)
Returns an alias to the number formatter being used for this file.
u_fprintf_u
U_CAPI int32_t u_fprintf_u(UFILE *f, const UChar *patternSpecification,...)
Write formatted data to a UFILE.
u_frewind
U_CAPI void u_frewind(UFILE *file)
Rewind the file pointer to the beginning of the file.
u_fgetfile
U_CAPI FILE * u_fgetfile(UFILE *f)
Get the FILE* associated with a UFILE.
u_fclose
U_CAPI void u_fclose(UFILE *file)
Close a UFILE.
u_fgetConverter
U_CAPI UConverter * u_fgetConverter(UFILE *f)
Returns an alias to the converter being used for this file.
u_fsetcodepage
U_CAPI int32_t u_fsetcodepage(const char *codepage, UFILE *file)
Set the codepage in which data will be written to and read from the UFILE.
u_fsettransliterator
U_CAPI UTransliterator * u_fsettransliterator(UFILE *file, UFileDirection direction, UTransliterator *adopt, UErrorCode *status)
Set a transliterator on the UFILE.
u_fsetlocale
U_CAPI int32_t u_fsetlocale(UFILE *file, const char *locale)
Set the locale whose conventions will be used to format and parse output.
u_printf_u
U_CAPI int32_t u_printf_u(const UChar *patternSpecification,...)
Write formatted data to stdout.
u_printf
U_CAPI int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
u_sprintf
U_CAPI int32_t u_sprintf(UChar *buffer, const char *patternSpecification,...)
Write formatted data to a Unicode string.
u_fscanf
U_CAPI int32_t u_fscanf(UFILE *f, const char *patternSpecification,...)
Read formatted data from a UFILE.
u_fgetlocale
U_CAPI const char * u_fgetlocale(UFILE *file)
Get the locale whose conventions are used to format and parse output.
u_sscanf
U_CAPI int32_t u_sscanf(const UChar *buffer, const char *patternSpecification,...)
Read formatted data from a Unicode string.
u_finit
U_CAPI UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_fstropen
U_CAPI UFILE * u_fstropen(UChar *stringBuf, int32_t capacity, const char *locale)
Create a UFILE that can be used for localized formatting or parsing.
u_fputs
U_CAPI int32_t u_fputs(const UChar *s, UFILE *f)
Write a Unicode to a UFILE.
u_file_read
U_CAPI int32_t u_file_read(UChar *chars, int32_t count, UFILE *f)
Read Unicode from a UFILE.
u_fadopt
U_CAPI UFILE * u_fadopt(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_vsprintf_u
U_CAPI int32_t u_vsprintf_u(UChar *buffer, const UChar *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_snprintf_u
U_CAPI int32_t u_snprintf_u(UChar *buffer, int32_t count, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
u_fungetc
U_CAPI UChar32 u_fungetc(UChar32 c, UFILE *f)
Unget a UChar from a UFILE.
UFileDirection
UFileDirection
Enum for which direction of stream a transliterator applies to.
Definition: ustdio.h:222
u_vsscanf
U_CAPI int32_t u_vsscanf(const UChar *buffer, const char *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
u_fputc
U_CAPI UChar32 u_fputc(UChar32 uc, UFILE *f)
Write a UChar to a UFILE.
u_snprintf
U_CAPI int32_t u_snprintf(UChar *buffer, int32_t count, const char *patternSpecification,...)
Write formatted data to a Unicode string.
u_fgets
U_CAPI UChar * u_fgets(UChar *s, int32_t n, UFILE *f)
Read one line of text into a UChar* string from a UFILE.
u_sscanf_u
U_CAPI int32_t u_sscanf_u(const UChar *buffer, const UChar *patternSpecification,...)
Read formatted data from a Unicode string.
u_get_stdout
U_CAPI UFILE * u_get_stdout(void)
Get a UFILE for stdout.
u_sprintf_u
U_CAPI int32_t u_sprintf_u(UChar *buffer, const UChar *patternSpecification,...)
Write formatted data to a Unicode string.
u_fprintf
U_CAPI int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
u_fgetcx
U_CAPI UChar32 u_fgetcx(UFILE *f)
Read a UChar32 from a UFILE.
u_vsnprintf
U_CAPI int32_t u_vsnprintf(UChar *buffer, int32_t count, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
UFILE
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:215
u_vsprintf
U_CAPI int32_t u_vsprintf(UChar *buffer, const char *patternSpecification, va_list ap)
Write formatted data to a Unicode string.
u_vsscanf_u
U_CAPI int32_t u_vsscanf_u(const UChar *buffer, const UChar *patternSpecification, va_list ap)
Read formatted data from a Unicode string.
u_vfscanf
U_CAPI int32_t u_vfscanf(UFILE *f, const char *patternSpecification, va_list ap)
Read formatted data from a UFILE.
utrans.h
C API: Transliterator.
UTransliterator
void * UTransliterator
An opaque transliterator for use in C.
Definition: utrans.h:73
utypes.h
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:430