This documentation describes the Prokee module interface.
This module is depricated!
Static Methods:
to_str
to_str (version 2)
[WIN_ONLY]
char *strconv::to_str(char **out,unsigned int *out_ln,const wchar_t *in)
to_wcs
to_wcs (version 1)
wchar_t *strconv::to_wcs(wchar_t **out,unsigned int *out_ln,const wchar_t *in)
to_wcs (version 2)
[WIN_ONLY]
wchar_t *strconv::to_wcs(wchar_t **out,unsigned int *out_ln,const char *in)
Motivation
Dieses Modul dient unter Windows zur Umwandlung von UTF-8 Strings in Windows WideCharacter-Strings und umgekehrt.
-
Die Windows Version dieses Moduls ruft dabei die Funktionen WideCharToMultiByte() und MultiByteToWideChar() der Windows API auf.
-
In der Linux Variante des Moduls werden die Strings lediglich kopiert.
Funktionen zur Konvertierung sind unter Linux für dieses Modul nicht implementiert.
Das Modul wird in einigen anderen Modulen innerhalb von Templates eingesetzt.
Dazu folgendes Muster:
template<class T> my_universal_print_function(const T text)
{
char *utf8_text=strconv::to_str(NULL,NULL,text);
printf_utf8(utf8_text);
free(utf8_text);
}
Dieser Ansatz ist jedoch nicht optimal (unnötiges Kopieren des Strings, falls dieser bereits als utf8-String vorliegt).
Static Methods
to_str (version 1)
Kopiert den null-terminierten String
in nach
out.
Signature:
char *strconv::to_str(char **out,unsigned int *out_ln,const char *in)
Parameters:
| char ** | out | [OUT] | Speicherbereich in den die Ausgabe geschrieben wird. Falls NULL angegeben wird, oder falls *out = 0 ist, wird der Speicherbereich neu alloziert. Die anfängliche Länge des Speicherbereichs kann in diesem Fall durch *out_ln festgelegt werden. Falls *out_ln = 0 oder out_ln = NULL ist, so wird die anfängliche Länge auf 256 Bytes festgelegt. Ist der Speicherbereich für die Ausgabe zu klein, so wird die Länge so lange verdoppelt (und der Speicher neu alloziert) bis der Speicherbereich lang genug ist. Die Länge des resultierenden Speicherbereichs kann daher deutlich länger sein, als die Länge des Strings. Bei wiederholtem Aufruf, sollte ein bereits allozierter Speicherbereich wiederverwendet werden, um die Anzahl der benötigten Speicher-Allozierungen gering zu halten. Wird der Speicherbereich neu alloziert (oder re-alloziert) und ist out nicht NULL, so wird die neue Adresse des Speicherbereichs nach *out zurück geschrieben.
|
| unsigned int * | out_ln | [IN/OUT] | Länge des Speicherbereichs out in den die Ausgabe geschrieben wird. Bei Angabe von NULL oder falls *out_ln = 0 ist, so wird falls out = NULL oder *out = 0 ist, ein neuer Speicherbereich alloziert bzw. falls *out != 0 ist, der bestehende Speicherbereich re-alloziert. Ist der Speicherbereich zu klein für die Ausgabe, so wird ebenso ein längerer Speicherbereich alloziert. Sofern out_ln nicht NULL ist, wird die neue Länge des Speicherbereichs nach *out_ln geschrieben. |
| const char * | in | [IN] | Ein null-terminierter String in UTF-8 Codierung. |
Return value:Die Funktion gibt
*out bzw. einen Pointer auf den neu allozierten String zurück.
to_str (version 2) [WIN_ONLY]
Schreibt den null-terminerten Windows Wide-Character String
in als UTF-8 String nach
out.
Signature:
char *strconv::to_str(char **out,unsigned int *out_ln,const wchar_t *in)
Parameters:
| char ** | out | [OUT] | Speicherbereich in den die Ausgabe geschrieben wird. Falls NULL angegeben wird, oder falls *out = 0 ist, wird der Speicherbereich neu alloziert. Die Länge des Speicherbereichs kann in diesem Fall durch *out_ln festgelegt werden. Falls *out_ln = 0 oder out_ln = NULL ist, so wird ein Speicherbereich in erforderlicher Länge reserviert. Ist der Speicherbereich für die Ausgabe zu klein, so wird die Länge so lange verdoppelt (und der Speicher neu alloziert) bis der Speicherbereich lang genug ist. Die Länge des resultierenden Speicherbereichs kann daher deutlich länger sein, als die Länge des Strings. Bei wiederholtem Aufruf, sollte ein bereits allozierter Speicherbereich wiederverwendet werden, um die Anzahl der benötigten Speicher-Allozierungen gering zu halten. Wird der Speicherbereich neu alloziert (oder re-alloziert) und ist out nicht NULL, so wird die neue Adresse des Speicherbereichs nach *out zurück geschrieben.
|
| unsigned int * | out_ln | [IN/OUT] | Länge des Speicherbereichs out in den die Ausgabe geschrieben wird. Bei Angabe von NULL oder falls *out_ln = 0 ist, so wird falls out = NULL oder *out = 0 ist, ein neuer Speicherbereich alloziert bzw. falls *out != 0 ist, der bestehende Speicherbereich re-alloziert. Ist der Speicherbereich zu klein für die Ausgabe, so wird ebenso ein längerer Speicherbereich alloziert. Sofern out_ln nicht NULL ist, wird die neue Länge des Speicherbereichs nach *out_ln geschrieben. |
| const wchar_t * | in | [IN] | Ein null-terminierter String in Windows Wide-Character Codierung. |
Return value:Die Funktion gibt
*out bzw. einen Pointer auf den neu allozierten String zurück. Falls die Konvertierung scheitert, gibt die Funktion 0 zurück.
Remarks: Diese Funktion steht nur unter Windows Betriebssystemen zur Verfügung. Es kann sein, dass die Funktion unter anderen Betriebssystemen ebenfalls deklariert ist, die konkrete Implementierung fehlt aber in jedem Fall. Verwenden Sie diese Funktion daher mit Vorsicht. Aufrufe sollten immer innerhalb eines entsprechenden Präprozessor-Blocks stehen: Z.B.:
#ifdef _WIN32 ... #endif.
to_wcs (version 1)
Kopiert den null-terminierten String
in nach
out.
Signature:
wchar_t *strconv::to_wcs(wchar_t **out,unsigned int *out_ln,const wchar_t *in)
Parameters:
| wchar_t ** | out | [OUT] | Speicherbereich in den die Ausgabe geschrieben wird. Falls NULL angegeben wird, oder falls *out = 0 ist, wird der Speicherbereich neu alloziert. Die anfängliche Länge des Speicherbereichs kann in diesem Fall durch *out_ln festgelegt werden. Falls *out_ln = 0 oder out_ln = NULL ist, so wird die anfängliche Länge auf 256 Bytes festgelegt. Ist der Speicherbereich für die Ausgabe zu klein, so wird die Länge so lange verdoppelt (und der Speicher neu alloziert) bis der Speicherbereich lang genug ist. Die Länge des resultierenden Speicherbereichs kann daher deutlich länger sein, als die Länge des Strings. Bei wiederholtem Aufruf, sollte ein bereits allozierter Speicherbereich wiederverwendet werden, um die Anzahl der benötigten Speicher-Allozierungen gering zu halten. Wird der Speicherbereich neu alloziert (oder re-alloziert) und ist out nicht NULL, so wird die neue Adresse des Speicherbereichs nach *out zurück geschrieben.
|
| unsigned int * | out_ln | [IN/OUT] | Länge des Speicherbereichs out in den die Ausgabe geschrieben wird. Bei Angabe von NULL oder falls *out_ln = 0 ist, so wird falls out = NULL oder *out = 0 ist, ein neuer Speicherbereich alloziert bzw. falls *out != 0 ist, der bestehende Speicherbereich re-alloziert. Ist der Speicherbereich zu klein für die Ausgabe, so wird ebenso ein längerer Speicherbereich alloziert. Sofern out_ln nicht NULL ist, wird die neue Länge des Speicherbereichs nach *out_ln geschrieben. |
| const wchar_t * | in | [IN] | Ein null-terminierter String in Windows Wide-Character Codierung. |
Return value:Die Funktion gibt
*out bzw. einen Pointer auf den neu allozierten String zurück.
to_wcs (version 2) [WIN_ONLY]
Schreibt den null-terminerten UTF-8 codierten String
in als Windows Wide-Character String nach
out.
Signature:
wchar_t *strconv::to_wcs(wchar_t **out,unsigned int *out_ln,const char *in)
Parameters:
| wchar_t ** | out | [OUT] | Speicherbereich in den die Ausgabe geschrieben wird. Falls NULL angegeben wird, oder falls *out = 0 ist, wird der Speicherbereich neu alloziert. Die Länge des Speicherbereichs kann in diesem Fall durch *out_ln festgelegt werden. Falls *out_ln = 0 oder out_ln = NULL ist, so wird ein Speicherbereich in erforderlicher Länge reserviert. Ist der Speicherbereich für die Ausgabe zu klein, so wird die Länge so lange verdoppelt (und der Speicher neu alloziert) bis der Speicherbereich lang genug ist. Die Länge des resultierenden Speicherbereichs kann daher deutlich länger sein, als die Länge des Strings. Bei wiederholtem Aufruf, sollte ein bereits allozierter Speicherbereich wiederverwendet werden, um die Anzahl der benötigten Speicher-Allozierungen gering zu halten. Wird der Speicherbereich neu alloziert (oder re-alloziert) und ist out nicht NULL, so wird die neue Adresse des Speicherbereichs nach *out zurück geschrieben.
|
| unsigned int * | out_ln | [IN/OUT] | Länge des Speicherbereichs out in den die Ausgabe geschrieben wird. Bei Angabe von NULL oder falls *out_ln = 0 ist, so wird falls out = NULL oder *out = 0 ist, ein neuer Speicherbereich alloziert bzw. falls *out != 0 ist, der bestehende Speicherbereich re-alloziert. Ist der Speicherbereich zu klein für die Ausgabe, so wird ebenso ein längerer Speicherbereich alloziert. Sofern out_ln nicht NULL ist, wird die neue Länge des Speicherbereichs nach *out_ln geschrieben. |
| const char * | in | [IN] | Ein null-terminierter String in UTF-8 Codierung. |
Return value:Die Funktion gibt
*out bzw. einen Pointer auf den neu allozierten String zurück. Falls die Konvertierung scheitert, gibt die Funktion 0 zurück.
Remarks: Diese Funktion steht nur unter Windows Betriebssystemen zur Verfügung. Es kann sein, dass die Funktion unter anderen Betriebssystemen ebenfalls deklariert ist, die konkrete Implementierung fehlt aber in jedem Fall. Verwenden Sie diese Funktion daher mit Vorsicht. Aufrufe sollten immer innerhalb eines entsprechenden Präprozessor-Blocks stehen: Z.B.:
#ifdef _WIN32 ... #endif.
This documenta- tion describes the current state of development.
A
aprint