Freeciv-3.2: /fast/freeciv/nightly/S3_2/utility/fciconv.h Source File

Freeciv-3.2

Loading...
Searching...
No Matches
fciconv.h
Go to the documentation of this file.
1/***********************************************************************
2 Freeciv - Copyright (C) 2003-2004 - The Freeciv Project
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License as published by
5 the Free Software Foundation; either version 2, or (at your option)
6 any later version.
7
8 This program is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 GNU General Public License for more details.
12***********************************************************************/
13#ifndef FC__FCICONV_H
14#define FC__FCICONV_H
15
16#ifdef __cplusplus
17extern "C" {
18#endif /* __cplusplus */
19
20#include <stdio.h>
21
22/* utility */
23#include "shared.h"
24
25/*
26 Technical details:
27
28 - There are three encodings used by freeciv: the data encoding, the
29 internal encoding, and the local encoding. Each is a character set
30 (like utf-8 or latin1). Each string in the code must be in one of these
31 three encodings; to cut down on bugs always document whenever you have
32 a string in anything other than the internal encoding and never make
33 global variables hold anything other than the internal encoding; the
34 local and data encodings should only be used locally within the code
35 and always documented as such.
36
37 - The data_encoding is used in all data files and network transactions.
38 This is always UTF-8.
39
40 - The internal_encoding is used internally within freeciv. This is always
41 UTF-8 at the server, but can be configured by the GUI client. The GTK
42 clients use UTF-8 here but other clients will use whatever their GUI
43 library or platform requires. By using the GUI encoding internally at
44 the client it allows us to pass any strings directly to the GUI without
45 needing to convert them. The drawback is that we have to convert them
46 into the data encoding before sending them over the network (a likely
47 source of bugs). Also, gettext is set up to always return strings in
48 the internal encoding.
49
50 - The local_encoding is the one supported on the command line, which is
51 generally the value listed in the $LANG environment variable. This is
52 not under freeciv control; all output to the command line must be
53 converted or it will not display correctly.
54
55 Practical details:
56
57 - Translation files are not controlled by freeciv iconv. The .po files
58 can be in any character set, as set at the top of the file.
59
60 - All translatable texts should be American English ASCII. In the past,
61 gettext documentation has always said to stick to ASCII for the gettext
62 input (pre-translated texts) and rely on translations to supply the
63 needed non-ASCII characters.
64
65 - All other texts, including rulesets, nations, and code files must be in
66 UTF-8 (ASCII is a subset of UTF-8, and is fine for use here).
67
68 - The server uses UTF-8 for everything; UTF-8 is the server's "internal
69 encoding".
70
71 - Everything sent over the network is always in UTF-8.
72
73 - Everything in the client is converted into the client's "internal
74 encoding" when it is received from the server. Depending on which
75 GUI is used, this may be just about any character set. Conversely when
76 sending strings from the client to the server they need to be converted
77 into the data encoding. This should be done internally within the
78 network code.
79
80 - Everything printed to the command line must be converted into the
81 "local encoding" which may be anything as defined by the system. Using
82 fc_fprintf is generally the easiest way to print to the command line
83 in which case all strings passed to it should be in the internal
84 encoding.
85
86 See PR#40028 in the old RT for additional explanation.
87*/
88
89#define FC_DEFAULT_DATA_ENCODING "UTF-8"
90
91void init_character_encodings(const char *internal_encoding,
92 bool use_transliteration);
93void fc_iconv_close(void);
94
95const char *get_data_encoding(void);
96const char *get_local_encoding(void);
97const char *get_internal_encoding(void);
98
99 char *data_to_internal_string_malloc(const char *text);
100 char *internal_to_data_string_malloc(const char *text);
101 char *internal_to_local_string_malloc(const char *text);
102 char *local_to_internal_string_malloc(const char *text);
103
104 char *local_to_internal_string_buffer(const char *text,
105 char *buf, size_t bufsz);
106 char *internal_to_local_string_buffer(const char *text,
107 char *buf, size_t bufsz);
108
109#define fc_printf(...) fc_fprintf(stdout, __VA_ARGS__)
110 void fc_fprintf(FILE *stream, const char *format, ...)
111 fc__attribute((__format__ (__printf__, 2, 3)));
112
113size_t get_internal_string_length(const char *text);
114
115#ifdef __cplusplus
116}
117#endif /* __cplusplus */
118
119#endif /* FC__FCICONV_H */
incite_cost
char * incite_cost
Definition comments.c:74
internal_encoding
#define internal_encoding
Definition fciconv.c:52
get_internal_string_length
void size_t get_internal_string_length(const char *text)
Definition fciconv.c:395
internal_to_local_string_buffer
char * internal_to_local_string_buffer(const char *text, char *buf, size_t bufsz)
init_character_encodings
void init_character_encodings(const char *internal_encoding, bool use_transliteration)
Definition fciconv.c:70
internal_to_local_string_malloc
char * internal_to_local_string_malloc(const char *text)
fc_iconv_close
void fc_iconv_close(void)
Definition fciconv.c:417
local_to_internal_string_buffer
char * local_to_internal_string_buffer(const char *text, char *buf, size_t bufsz)
get_data_encoding
const char * get_data_encoding(void)
Definition fciconv.c:151
internal_to_data_string_malloc
char * internal_to_data_string_malloc(const char *text)
get_internal_encoding
const char * get_internal_encoding(void)
Definition fciconv.c:182
local_to_internal_string_malloc
char * local_to_internal_string_malloc(const char *text)
fc_fprintf
void fc_fprintf(FILE *stream, const char *format,...) fc__attribute((__format__(__printf__
data_to_internal_string_malloc
char * data_to_internal_string_malloc(const char *text)
get_local_encoding
const char * get_local_encoding(void)
Definition fciconv.c:160
bufsz
static const int bufsz
Definition helpdlg.c:70
shared.h
fc__attribute
#define fc__attribute(x)
Definition support.h:99