Documento de molib

Idiomas disponible : English français

NAMESPACE

mowc

NAME

wctomblen - compute the number of bytes required to encode a wc_t char
wcstombslen - compute the number of bytes required to encode a wc_t string

VERSION

Version: 1.2.0

SYNOPSIS

static int wctomblen(wc_t wc);
static int wcstombslen(const wc_t *wcs, size_t size = static_cast<size_t>(-1));

PARAMETERS

wc - an INTERNAL UCS-4 character
wcs - an INTERNAL UCS-4 string of characters

DESCRIPTION

The wctomblen() function will compute the number of bytes required to convert one wide character (wc) into a multy-byte character.

The size will be the same as when wctomb() is called.

wctomblen() will return 0 for any invalid character. Note that '\0' is taken as a valid character.

wcstombslen() computes the number of bytes required to convert a string of UCS-4 characters in a string of multi-byte characters. The computation stops whenever a nul terminator is found. (This means no nul will be included in the length computation.)

When a size parameter is specified, the computation will stop after that many characters were read even if the nul terminator wasn't found.

NOTES

when the wc char is L'\0', a size of 1 is returned

RETURN VALUE

the number of bytes necessary for the multi-byte character(s)

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

wctomb - transforms a wide character to a multi-byte character

VERSION

Version: 1.2.0

SYNOPSIS

static int wctomb(char *mb, wc_t wc);
int wcstombs(char *mb, const wc_t *s, unsigned long sz, size_t size = static_cast<size_t>(-1));

PARAMETERS

mb - the multi-byte output string pointer
wc - the character to define
s - the wide character input string pointer
sz - the size of the output string buffer
size - the maximum number of character to copy from the s string

DESCRIPTION

The wctomb() transforms one wide character (wc) to a multi-byte character (mb). The mb pointer needs to be at least 7 characters long. Please, use the MAX_MB_SIZE define to declare your buffer.

Any valid wide character will be encoded. Invalid values are all the negative values (bit 31 set) and a few characters such as 0xFFFD.

The wcstombs() will transform a whole string composed of wide characters (wc_t) into a multi-byte string of chars. The maximum size (sz) will be used to ensure the destination isn't overrun and for this reason, you should use an output buffer much larger than MAX_MB_SIZE (say, 256 bytes).

NOTES

the mb string can be "\0\0" in case the wc is L'\0', yet, in this case, a size of 1 is returned.

RETURN VALUE

the number of characters saved in the mb string

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

mbtowc - transforms a multi-byte character in a wide character

VERSION

Version: 1.2.0

SYNOPSIS

static int mbtowc(long& wc, const char *&mb, long& len);

PARAMETERS

wc - a reference where the resulting character is written
mb - the multi-byte input string pointer
len - the number of bytes in the input string

DESCRIPTION

The mbtowc() transforms a multi-byte character (mb) into a wide character (wc). The mb pointer needs to be up to 7 characters long for the widest multi-byte characters.

Any valid multi-byte character will be decoded.

Though this isn't proper, all the bytes which form a wide character will be skipped even if they are not part of the wide character being read.

RETURN VALUE

the number of bytes read from the mb string
0 when the input string is empty
-1 when an invalid byte is found (0x80 to 0xBF and 0xFE/0xFF
or too many/not enough characters found)

The mb and len parameters will have been modified accordingly
including when errors are encountered.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strlen - count the number of characters in a string

VERSION

Version: 1.2.0

SYNOPSIS

static int strlen(const char *s, encoding_t encoding = MO_ENCODING_ISO8859_1);
static int strlen(const mc_t *s);
static int strlen(const wc_t *s);
static int strlen(const wchar_t *s);

PARAMETERS

s - a chain of characters defined in bytes
encoding - one of MO_ENCODING_ISO8859_1 or MO_ENCODING_UTF8
wc - a reference where the resulting character is written
mb - the multi-byte input string pointer
len - the number of bytes in the input string

DESCRIPTION

The different strlen() functions compute the length in characters of a string. Multibytes characters are return as a count of 1 (when represented in a wc_t, it will be 1 character).

Note that the first version (the one taking a char * as parameter) is the only one which takes an encoding as an additional parameter. This function accepts the ISO8859 or any other 1 byte per character format (use the ISO8859 encoding for all of these) and the UTF8 encoding. When UTF8 is specified, all the multibytes are counted as one character.

RETURN VALUE

the number of characters in the string

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strtol - return the integer represented by the specified string
strtoll - return the integer represented by the specified string
strtod - return the double represented by the specified string

VERSION

Version: 1.2.0

SYNOPSIS

int strtol(const wc_t *wc, wc_t **end = 0, int base = 0);
long long strtoll(const wc_t *wc, wc_t **end = 0, int base = 0);
double strtod(const wc_t *wc, wc_t **end = 0);
bool strtoipv4(const wc_t *wc, unsigned long& address, unsigned short& port, unsigned long& mask);

PARAMETERS

wc - a string to parse
end - a pointer where the input string is left
base - the base used to parse the input
address - the read address
port - the port or zero
mask - the mask or -1

DESCRIPTION

The strtol() function will transform the input string in a signed decimal value. The strtoll() is similar but it also supports 64 bits integers.

If the value starts with 0x or 0X, then the base parameter is ignored and 16 is used.

The strtod() function transforms the input string in a double value.

The end parameter can be used to get a copy of the source pointer where the parsing stopped.

The strtoipv4() function reads the string and converts it to an address, an optional port and an optional mask. The expected syntax is as follow:

a.b.c.d[:p][/w.x.y.z] a.b.c.d[:p][/m]

where a, b, c, m, p, w, x, y and z and decimal numbers from 0 to 255, except for m which can be between 0 and 32 and for p which can be between 0 and 65535. When just m is specified, then the mask is built as (-1 << m) re-ordered properly for your computer endian (i.e. up-side-down for little endian computers).

The address can be preceeded and followed by spaces.

RETURN VALUE

all but strtoipv4:
the parsed value
-1 or -1.0 an error occured (check errno as well!)

stripv4:
true when a valid address, port and mask was read

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strtol - returns the integer value read in the input string
strtoll - returns the integer value read in the input string

VERSION

Version: 1.2.0

SYNOPSIS

long strtol(const char *mb, char **end, int base = 10, int length = INT_MAX);
long long strtoll(const char *mb, char **end, int base = 10, int length = INT_MAX);

PARAMETERS

mb - the source string to parse for a value
end - where a non digit character is found or NULL
base - the base of the value being read
length - the maximum number of characters to read from mb

DESCRIPTION

This function will convert a string to an integer using the specified base and reading a maximum number of characters as indicated by the length.

The end parameter will receive the pointer of mb where the first non digit character is found.

Note that the base is defaulted to 10. This function doesn't currently check and try to figure out which base should be used. It is up to you to find out. Note that any base from 2 to 36 can be used.

The leading spaces are skipped before any value is being parsed. These spaces could in the total length which will be parsed.

SEE ALSO

strtol & tointeger (wide character versions)

BUGS

These versions of strtol() and strtoll() don't support the octal and hexadecimal syntax (i.e. 077 or 0x3F).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strcmp - compare two strings, case sensitive
strcasecmp - compare two strings, case insensitive

VERSION

Version: 1.2.0

SYNOPSIS

static int strcmp(const wc_t *a, const char *b, long length = LONG_MAX);
static int strcmp(const wc_t *a, const wc_t *b, long length = LONG_MAX);
static int strcasecmp(const wc_t *a, const char *b, long length = LONG_MAX);
static int strcasecmp(const wc_t *a, const wc_t *b, long length = LONG_MAX);

PARAMETERS

a - a string
b - a string

DESCRIPTION

The strcmp() function compares two strings together. Two letters with a different case will not be recognized as being the same letter.

The strcasecmp() function compares two strings together. Two letters which are the same except for their case are viewed as being the same. Note that is yet not similar to the collate version (i.e. the accentuated letters different among each others).

The comparison is by value, none of the characters are collated.

It is acceptable to call the function with a or b or both pointers being 0. A null pointer is considered equivalent to an empty string.

RETURN VALUE

0 when the strings are equal
-1 when the a string is before the b string (value wise)
1 when the a string is after the b string (value wise)

BUGS

At this time the char * version doesn't include an encoding. It should primarily be used with the ISO8859-1 character set.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strcpy - copy a string in another

VERSION

Version: 1.2.0

SYNOPSIS

static void strcpy(wc_t *d, const char *s, long length = LONG_MAX, encoding_t encoding = MO_ENCODING_ISO8859_1);
static void strcpy(wc_t *d, const mc_t *s, long length = LONG_MAX, encoding_t encoding = MO_ENCODING_UTF16_INTERNAL);
static void strcpy(wc_t *d, const wc_t *s, long length = LONG_MAX, encoding_t encoding = MO_ENCODING_UTF32_INTERNAL);
static void strcpy(wc_t *d, const wchar_t *s, long length = LONG_MAX);

PARAMETERS

wc - the destination string
s - the source string
length - the maximum number of character copied (not including
the null terminator which IS ALWAYS INSERTED)
encoding - specify the encoding used to copy the string

DESCRIPTION

These functions are used internally (though they are available to the end user) to copy any format string to the wc_t * type of strings.

The destination wc string is always in the UTF32 INTERNAL format (endian of the currently running processor).

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

strchr - find the first instance of a character in a string
strrchr - find the last instance of a character in a string

VERSION

Version: 1.2.0

SYNOPSIS

mowc strchr(const wc_t *s, wc_t c);
mowc strrchr(const wc_t *s, wc_t c);

PARAMETERS

s - the string to scan
c - the character searched

DESCRIPTION

These functions search for the character c and return a pointer on the last found instance of it found in the input string.

Note that if the character exists in the string, it will be included in the result.

If the character doesn't exist in the string, then NULL is returned.

strchr() will search for the first instance of the given character.

strrchr() will search for the last instance of the given character.

RETURN VALUE

A pointer on the last found character or NULL.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

backslash_char - replace backslashed characters with the
C/C++ corresponding character

VERSION

Version: 1.2.0

SYNOPSIS

wc_t backslash_char(const wc_t *& s);
wc_t backslash_char(wc_t *& s);

PARAMETERS

s - the input string where one character is read

DESCRIPTION

The backslash_char() function accepts a C string as input and transforms the letters and digits in the corresponding backslashed character. The input string must point right after the backslash character (which is thus already eaten) and it will point after all the characters used to generate the backslashed character once the function returns. When an error occurs, the pointer may not be moved.

The understood characters are as follow:

\a audible bell (0x07) \b backspace (0x08) \c. the control character (i.e. \cA to \cZ) \e or \? escape (0x1B) \f form feed (0x0C) \n new line (0x0A) \r carriage return (0x0D) \t horizontal tab (0x09) \v vertical tab (0x0B)

The \ can also be followed by an octal or hexadecimal value:

\x## hexadecimal value \X## hexadecimal value \L#... hexadecimal value (any number of digits) \#... octal value (any number of digits)

All other characters are kept as is, thus "\\" becomes "\", etc.

RETURN VALUE

the value of the backslashed character

SEE ALSO

Replace

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

toupper - returns the upper case of the specified character
tolower - returns the lower case of the specified character
digit - transform a character in a decimal digit
xdigit - transform a character in an hexadecimal digit
tointeger - transform a string in an integer
tolargeinteger - transform a string in a 64 bits integer
tofloat - transform a string in a float

isinteger - check whether a whole string represents an integer
isfloat - check whether a whole string represents a float
isalnum - test for alphanumeric characters
isalpha - test for alphabetic characters
isascii - test for ASCII characters
isblank - test for blanks
iscntrl - test for controls
isdigit - test for a decimal digit
isiso8859_1 - test for ISO 8859-1 characters
isodigit - test for an octal digit
isxdigit - test for an hexadecimal digit
isgraph - test for graphical characters
islower - test for lower case
isprint - test for printable characters
ispunct - test for punctuation
isspace - test for space
isupper - test for upper case

VERSION

Version: 1.2.0

SYNOPSIS

long tointeger(const wc_t *str, int base = 0);
long long tolargeinteger(const wc_t *str, int base = 0);
double tofloat(const wc_t *str);
wc_t toupper(wc_t wc);
wc_t tolower(wc_t wc);
int digit(wc_t wc);
int xdigit(wc_t wc);

bool isinteger(const wc_t *str, int base = 0);
bool isfloat(const wc_t *str);
bool isalnum(wc_t wc);
bool isalpha(wc_t wc);
bool isascii(wc_t wc);
bool isblank(wc_t wc);
bool iscntrl(wc_t wc);
bool isdigit(wc_t wc);
bool isodigit(wc_t wc);
bool isxdigit(wc_t wc);
bool isgraph(wc_t wc);
bool islower(wc_t wc);
bool isprint(wc_t wc);
bool ispunct(wc_t wc);
bool isspace(wc_t wc);
bool isupper(wc_t wc);

DESCRIPTION

These are wide character versions of the ctype functions.

SEE ALSO

CaseCompare

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

NAMESPACE

mowc

NAME

fwprintf - write a formated string to a stream
vfwprintf - write a formated string to a stream

VERSION

Version: 1.2.0

SYNOPSIS

int fwprintf(moOStream *out, const wc_t *format, ...);
int vfwprintf(moOStream *out, const wc_t *format, va_list args);
int fprintf(moOStream *out, const char *format, ...);
int vfprintf(moOStream *out, const char *format, va_list args);

DESCRIPTION

The format function can be used to create a string with the result of a formatted set of arguments.

The vfwprintf() accepts a variable list of arguments as obtained by va_start(args, <last parameter>).

It doesn't use the standard wprintf() function of the C library because otherwise it would transform the different characters depending on environment defined settings. Instead, the whole function format was reprogrammed.

Please, though it doesn't use the wprintf(), you certainly want to see this function documentation for more information about the default formats supported by the function.

The following is a list of the flags supported by this implementation:

The format of a conversion is as follow:

'%' [<position>'&x24;'] [<flags>] [<width>] ['.'<precision>] [<length>] <conversion>

There is one special case: "%%" will be used to insert a percent in the output.

Position:

Defines the position of the argument in the list of parameters. This is useful to write the parameters in run-time varying order.

The positions start at 1 from the first parameter after the format.

Flags:

# introducer; when used as in %#o, prepend a "0"; when used as in %#x or %#X, include a "0x" or "0X" respectively; when used with one of the floating conversions, ensures that a decimal point always appears.

' ' (space) writes a space wherever a signed and positive value is written

+ writes a plus for positive and signed values (unsigned value conversions ignore this flag).

0 zero pad on the left up to either precision or width digits

- left justify (default to right justification).

` write out thousands in decimal conversions.

Width:

The width is a decimal value which can be defined as a direct value an asterisk or an asterisk followed by a position (<position>'&x24;'). When an asterisk is specified, the width is taken from the list of parameters as an 'int'.

Precision:

The precision is a decimal value which can be defined as a direct value, an asterisk or an asterisk followed by a position (<position>'&x24;'). When an asterisk is specified, the precision is taken from the list of parameters as an 'int'.

Length:

hh A character.

h A short.

<none> An integer.

l A long.

ll A long long.

L A long double. (not currently available on Macs)

q A long long (like ll).

j An intmax_t.

z or Z A size_t (the 'Z' is deprecated and should never be used).

t A ptrdiff_t.

Conversions:

D,d,i Writes out a decimal number. 'D' is deprecated. It can be used to write out a long value (i.e. use %ld instead). All the sizes, except 'L' can be used with this conversion. '#' has no effect.

U,u,O,o,X,x Writes out an unsigned number in decimal (u,U), octal (o,O) or hexadecimal (x,X) notation. The U and O are deprecated. It can be used to write out a long value (i.e. use %lu and %lo instead). All the sizes, except the 'L' can be used with this conversion. '#' has no effect on the u and U conversions. With the o and O is ensures the value always starts with a zero. With the x and X is introduces the value with 0x and 0X respectively.

e,E,f,F,g,G,a,A Writes out a floating point number. The 'e' and 'E' can be used to write number in scientific notation (always including an exponent). The 'f' can be used to always avoid an exponent (watch out for really large or small values!). The 'F' is deprecated and works like 'f'. The 'g' and 'G' will select between 'f' and 'e' or 'E' depending on the value to be written. When the value can be written in a reasonable width using 'f', then it is used. The 'a' and 'A' print out the value in hexadecimal floating point. In all cases, the capital version makes the exponent letter be written in capital. The only two length accepted are <none> and 'L'.

c,C Writes out one character. The C notation is deprecated. It can be used to output of a long character (use %lc instead). The lengths accepted are 'hh' (char), 'h' (mc_t), <none> or 'll' (wc_t) and 'l' (wchar_t).

Note: if the fprintf() and vfprintf() versions are used, then the meaning of 'll' (or <none>) and 'hh' are exchanged.

s,S Writes out a string of characters. The S notation is deprecated. It can be used to output of a string of long characters (use %ls instead). The lengths accepted are 'hh' (char), 'h' (mc_t), <none> or 'll' (wc_t) and 'l' (wchar_t).

Note: if the fprintf() and vfprintf() versions are used, then the meaning of 'll' (or <none>) and 'hh' are exchanged.

p,P Writes out a pointer. The format used is "%#x" with the adequate size. The capital 'P' can be used to have the hexadecimal letters (and the 0X) in uppercase. This conversion doesn't accept a length.

n Used to query the number of characters written at the point where this "conversion" appears. By default, the type expected for this parameter is an 'int'. You can use the length argument to change the type to any length except 'L'.

m Writes out a string as returned by strerror(<arg>); where <arg> is an integer. The string will automatically be transformed to unicode as required.

SEE ALSO

backslash_char

BUGS

A common mistake is to type something like this:

moWCString string;

string.VFormat(...);

in which case the result is lost. One needs to use the function as a static function instead:

moWCString string;

string = moWCString::VFormat(...);

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

mowc::moIConv

NAME

moIConv - initializes an iconv(3) filter
~moIConv - release resources allocated for this convertor filter

VERSION

Version: 1.2.0

SYNOPSIS

moIConv(void);
~moIConv();

DESCRIPTION

This function creates an international character convertor to use as a filter for a I/O stream or some other object supporting the moFIFO interface.

It expects a call to the SetEncodings() function to initialize the exact filtering. Without such a call, only a few encodings are internally supported as input in an automated manner:

ISO8859-1 default UTF-8 detects a valid UTF-8 sequence UTF-16 detects zeroes and 0xFEFF UTF-32 detects zeroes and 0xFEFF

The output will always be UTF-32.

Reading a string such as encoding="..." can also trigger a specific encoding/decoding process.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

mowc::moIConv

NAME

Reset - reset the state of the convertor

VERSION

Version: 1.2.0

SYNOPSIS

virtual void Reset(void);

DESCRIPTION

Resets the current state of the convertor.

This is useful if you want to reuse the same convertor again for a different stream of data. This ensures that any intermediate state will be cleared.

SEE ALSO

moFIFO::Reset

BUGS

You can't know whether the function worked or the Lock() function failed.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

mowc::moIConv

NAME

SetEncodings - defines the source and destination encodings

VERSION

Version: 1.2.0

SYNOPSIS

virtual int SetEncodings(const char *from, const char *to);

PARAMETERS

from - name of the source encoding
to - name of the destination encoding

DESCRIPTION

Defines the input and output encodings to use to parse the input.

By default, the output is defined as UTF-32 and the input is guessed from the data being read.

Using the special name "*" as the input (from) keeps the filter in a guessing mode for the input data.

Using the special name "*" as the output (to) is similar to asking for UTF-32.

RETURN VALUE

0 when the function succeeds
-1 when it fails (unrecognized encoding?)

BUGS

Changing the encoding format from ASCII to another format is safe. Changing the encoding midway from any format other than ASCII to another may have unknown side effects. Use Reset() between changes.

If the function fails, the previous in place convertions will be lost.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

mowc::moIConv

NAME

Read - the filter convertion always happens on read

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Read(void *buffer, unsigned long size, bool peek = false);

PARAMETERS

buffer - where the data will be written for the user to use
size - the number of bytes the user is interseted in
peek - whether the position pointer will be moved

DESCRIPTION

This overloaded virtual function is the one which takes care of the filtering. We expect that the user wrote data in the FIFO before the Read() is being called. This function reads that data, converts it as defined by the encoding currently in force and writes it in the user buffer.

It handles many cases or "too many bytes converted" and not enough data found in the source buffer.

In any event the call never blocks and returns the number of bytes transformed.

RETURN VALUE

the number of bytes written in the user buffer when the function
succeeds; this can be zero when nothing can be written or the end
of the input is found

and -1 when an error occurs

BUGS

Not writing enough bytes in the FIFO will results in no characters being output here. It is important to know whether the end of the stream was not reached yet and data is missing or the convertion of the last sequence was not possible.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox