[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[pdf-devel] Proposal of API for the Encoded Text module
|
From: |
Aleksander Morgado |
|
Subject: |
[pdf-devel] Proposal of API for the Encoded Text module |
|
Date: |
Mon, 28 Jan 2008 13:30:07 +0100 |
|
User-agent: |
Thunderbird 2.0.0.9 (Macintosh/20071031) |
Hi all,
Find attached my changes to the proposed API for the Encoded Text
module. It's a diff to the gnupdf.texi file.
Some comments on the changes:
- Host encoding management will probably need a second round. We will
need to clearly determine which OS don't have support for iconv
(excluding Windows OSs, which have their specific way of handling host
encodings).
- Regarding the issue of the `best encoding' to encode a given character
string, I really think that UTF-8 could be the default best encoding for
all of those OS supporting iconv (GNU/Linux, Unix, Mac OS X...) and even
for Windows OSs (AFAIK, UTF-8 is available in all modern Windows
versions... should we give support for older versions?). UTF-8, in fact,
is one of the encoding conversions which will be built-in in the library.
- Maybe we should really decide which will be the full list of supported
OS (and version of OS, if needed), and not think it during the
development phase. This will help not only to determine the specific
OS-dependent functions for host encoding support (determine which OS
don't handle UTF-8, for example), but also to determine platforms with a
lack of some required feature (e.g. 64bit integers, discussed in another
thread). I could start a new page in the Wiki with this issue.
- All the functions involving encoding conversion (even those which
create and initialize a new text object) return the status of the
conversion, which should always be checked.
- I renamed functions involving PDF Strings
(pdf_text_new_from_pdf_string) and PDF Doc Encoding
(pdf_text_get_pdfdocenc, pdf_text_set_pdfdocenc), so that it is clear
which one is being considered (PDF Strings can be in PDF Doc Encoding or
in UTF-16BE with BOM).
- pdf_text_concat won't work with text objects with different
country/language code informations, so the returned status of this
function should always be checked.
- In addition to the `best encoding', another function is given to get
the default host encoding configured in the user's locale
(pdf_text_get_host_encoding).
- And the last one, a new function is given to `initialize' the text
module, which must be called at program startup, and is not thread-safe:
pdf_text_init. This function will be used to load the user's locale
information.
Additional comments are welcome,
--
Aleksander
Index: gnupdf.texi
===================================================================
RCS file: /cvsroot/pdf/libgnupdf/doc/gnupdf.texi,v
retrieving revision 1.22
diff -r1.22 gnupdf.texi
1090a1091
> * Initializing Text Module::
1094a1096
> * Managing Host Encodings::
1104a1107,1108
> @item PDF_TEXT_UTF8
> UTF-8 encoding.
1106c1110,1112
< Big Endian UTF16 encoding.
---
> Big Endian UTF-16 encoding.
> @item PDF_TEXT_UTF16_LE
> Little Endian UTF-16 encoding.
1108,1110c1114
< Host Endian UTF16 encoding (may be little-endian or big-endian).
< @item PDF_TEXT_UTF8
< UTF8 encoding.
---
> Host Endian UTF-16 encoding (may be little-endian or big-endian).
1112c1116,1118
< Big Endian UTF32 encoding.
---
> Big Endian UTF-32 encoding.
> @item PDF_TEXT_UTF32_LE
> Little Endian UTF-32 encoding.
1114c1120,1139
< Host Endian UTF32 encoding (may be little-endian or big-endian).
---
> Host Endian UTF-32 encoding (may be little-endian or big-endian).
> @end table
> @end deftp
>
>
> @deftp {Data Type} pdf_text_unicode_options
>
> Enumeration of extra options to get the contents of a pdf_text_t in a given
> UNICODE encoding (see function `pdf_text_get_unicode').
>
> @table @code
> @item PDF_TEXT_UNICODE_NO_OPTION (= 0)
> No specific option
> @item PDF_TEXT_UNICODE_WITH_BOM
> Prepend Byte Order Marker to the UNICODE string. This option is NOT applicable
> to UTF-8. If specified in UTF-8, it will be ignored.
> @item PDF_TEXT_UTF16BE_WITH_LANGCODE
> Insert language/country code information between the BOM (if required) and the
> data. This option is ONLY applicable to UTF16BE. If specified in any other
> encoding, it will be ignored.
1117a1143,1144
>
>
1143,1149d1169
< @deftp {Data Type} pdf_text_country_code_t
<
< A country code.
<
< @end deftp
<
< @deftp {Data Type} pdf_text_lang_code_t
1151,1159c1171
< A language code.
<
< @end deftp
<
< @deftp {Data Type} pdf_text_utf16_val_t
<
< A UTF16 value.
<
< @end deftp
---
> @deftp {Data Type} pdf_text_t
1161c1173,1175
< @deftp {Data Type} pdf_text_utf32_val_t
---
> A Unicode string, which must be considered as an opaque type. It contains the
> data
> in UTF-32BE encoding, as well as any `ISO-639-1' country code and/or
> `ISO-3166-1 alpha-2'
> language code applied.
1163c1177
< A UTF32 value.
---
> This data type must be initialized before being used, and destroyed
> afterwards.
1167c1181
< @deftp {Data Type} pdf_text_utf8_val_t
---
> @deftp {Data Type} pdf_text_host_encoding_t
1169c1183,1185
< A UTF8 value.
---
> This data type identifies an encoding used in a host (all the possible values
> are host-dependent). There is no initialization/destruction requirement for
> this data type.
1173,1175d1188
< @deftp {Data Type} pdf_text_unicode_char_t
<
< This data type is large enough to contain any Unicode character code.
1177c1190,1191
< @end deftp
---
> @node Initializing Text Module
> @subsection Initializing Text Module
1179c1193
< @deftp {Data Type} pdf_text_t
---
> @deftypefun pdf_status_t pdf_text_init (void)
1181,1183c1195,1196
< A Unicode string.
<
< @end deftp
---
> Initialize the Text Module. Must be launched only once at program startup,
> and is NOT thread-safe.
1185,1192c1198,1204
< @deftp {Data Type} pdf_text_host_encoding_t
<
< This data type identifies an encoding used in a host. The value of
< host encodings depends on the specific hosts.
<
< XXX Determine values for GNU, Unix, Windows and Macintosh hosts.
<
< @end deftp
---
> @table @strong
> @item Parameters
> None.
> @item Returns
> Status of the initialization.
> @end table
> @end deftypefun
1214a1227,1250
>
> @deftypefun void pdf_text_destroy (pdf_text_t text)
>
> Destroy a text object and its contents.
>
> @table @strong
> @item Parameters
> @table @var
> @item text
> A properly created text object.
> @end table
> @item Returns
> None
> @item Usage Example
> @example
> pdf_text_t mytext;
>
> mytext = pdf_text_new ();
> pdf_text_destroy(mytext);
>
> @end example
> @end table
> @end deftypefun
>
1238c1274
< @deftypefun pdf_text_t pdf_text_new_from_host (const char address@hidden,
pdf_size_t @var{length}, pdf_text_host_encoding_t @var{enc})
---
> @deftypefun pdf_status_t pdf_text_new_from_host (pdf_text_t address@hidden,
> const pdf_char_t address@hidden, const pdf_size_t @var{size}, const
> pdf_text_host_encoding_t @var{enc})
1245a1282,1283
> @item text
> A pointer to the output text object
1248,1249c1286,1287
< @item length
< The length of @var{str}.
---
> @item size
> The length of @var{str}, in bytes.
1254c1292
< A pointer to the newly created text object.
---
> The status of the conversion
1257a1296,1312
> pdf_text_t text;
> pdf_char_t *he_string;
> pdf_size_t he_string_size;
> pdf_text_host_encoding_t encoding;
> pdf_status_t ret_code;
>
> /* Obtain host encoding and text... */
>
> /* And create text object with those contents */
> ret_code = pdf_text_new_from_host(&text,
> he_string, he_string_size,
> encoding);
> if(ret_code != PDF_OK)
> @{
> /* Something bad happened */
> @}
>
1262c1317
< @deftypefun pdf_text_t pdf_text_new_from_pdf (const char address@hidden,
pdf_size_t @var{length})
---
> @deftypefun pdf_status_t pdf_text_new_from_pdf_string (pdf_text_t
> address@hidden, const pdf_char_t address@hidden, pdf_size_t @var{size},
> pdf_char_t address@hidden, pdf_size_t address@hidden)
1264,1265c1319,1327
< Create a new text object and initialize it with a given PDF string
< text representation.
---
> Create a new text object and initialize it with a given `PDF string'
> text representation. This `PDF string' can be either encoded in UTF-16BE, with
> BOM and optional Country/Language code information, or in PDF Doc Encoding.
>
> The Country/Language code marker is treated as end-of-text marker, so that a
> text object
> handles only a given pair of country and language codes. This function must
> be used
> inside a loop, so that the input string of data is splitted in chunks if more
> than
> one language/code is available in the text (only if PDF string is encoded in
> UTF-16BE).
1269a1332,1333
> @item text
> A pointer to the newly created text object.
1271,1280c1335,1341
< A text representation of a PDF string. It is either a UTF-16 string
< (prepended with @code{0xFEFF}) or a @code{PDFDocEncoding} string.
<
< If it is a UTF-16 string then it may have language and country
< embedded information.
<
< @var{str} should not contain embedded @code{NULL} characters.
< @item length
< The length of @var{str} in bytes.
< @end table
---
> A text representation of a PDF string.
> @item size
> The length of @var{str} in bytes
> @item remaining_str
> Returned pointer to the next chunk of data to process, if any.
> @item remaining_length
> Length of @var{remaining_str} in bytes
1282c1343,1345
< A pointer to the newly created text object.
---
> The status of the conversion
> @end table
>
1285a1349,1373
> pdf_text_t text;
> pdf_char_t *pdf_string;
> pdf_size_t pdf_string_size;
> pdf_char_t *remaining_str;
> pdf_size_t remaining_size;
> pdf_status_t ret_code;
>
> /* Obtain PDF string... */
>
> /* And create text object with those contents */
> remaining_str = pdf_string;
> remaining_length = pdf_string_size;
> do
> @{
> ret_code = pdf_text_new_from_host(&text,
> remaining_str, remaining_length,
> &remaining_str, &remaining_length);
>
> /* Do something with the chunk of string */
>
> pdf_text_destroy(text);
> @}
> while((ret_code == PDF_OK) && (remaining_length > 0));
>
>
1290c1378
< @deftypefun pdf_text_t pdf_text_new_from_unicode (const pdf_text_utf16_val_t
address@hidden, enum pdf_text_unicode_encoding_e @var{enc})
---
> @deftypefun pdf_text_t pdf_text_new_from_unicode (pdf_text_t address@hidden,
> const pdf_char_t address@hidden, const pdf_size_t @var{size}, const enum
> pdf_text_unicode_encoding_e @var{enc})
1293c1381,1387
< given unicode encoding.
---
> given unicode encoding. The Unicode string can be given with or without BOM,
> and there mustn't be any language/code information embedded in the string.
>
> Note that for UTF-16BE strings two options are possible to create the
> pdf_text_t object: treating it as a PDF string (so BOM is mandatory and
> Language/Country code are optional) or treating it as a general Unicode
> string (so BOM is optional and Language/Country code is not allowed).
1297a1392,1393
> @item text
> A pointer to the newly created text object.
1299,1302c1395,1397
< A Unicode string. It do not have the @code{0xFEFF} prefix and do not
< contain language or country information.
<
< Should not contain any @code{NULL} character.
---
> A Unicode string.
> @item size
> The length of @var{ucs} in bytes.
1307c1402
< A pointer to the newly created text object.
---
> The status of the conversion
1310a1406,1421
> pdf_text_t text;
> pdf_char_t *unicode_string;
> pdf_size_t unicode_string_size;
> pdf_status_t ret_code;
>
> /* Obtain unicode text... */
>
> /* And create text object with those contents */
> ret_code = pdf_text_new_from_unicode(&text,
> unicode_string, unicode_string_size,
> PDF_TEXT_UTF16_BE);
> if(ret_code != PDF_OK)
> @{
> /* Something bad happened */
> @}
>
1315c1426
< @deftypefun pdf_text_t pdf_text_new_from_u32 (pdf_u32_t @var{number})
---
> @deftypefun pdf_status_t pdf_text_new_from_u32 (pdf_text_t *text, const
> pdf_u32_t @var{number})
1322a1434,1435
> @item text
> A pointer to the newly created text object.
1327c1440
< A pointer to the newly created text object.
---
> The status of the conversion
1331a1445
> pdf_status_t ret_code;
1334c1448,1453
< text = pdf_text_new_from_u32 (number);
---
> ret_code = pdf_text_new_from_u32 (&text, number);
>
> if(ret_code != PDF_OK)
> @{
> /* Something bad happened */
> @}
1336d1454
< /* The content of text is now "24" */
1344c1462
< @deftypefun pdf_text_country_code_t pdf_text_get_country (pdf_text_t
@var{text})
---
> @deftypefun {const pdf_char_t *}pdf_text_get_country (pdf_text_t @var{text})
1346c1464,1466
< Return the country associated with a text variable.
---
> Return the `ISO-3166-1 alpha-2' country code associated with a text variable,
> as a
> NUL-terminated string. The returned string should not be modified, as it is
> managed by the `pdf_text_t' data type.
1359c1479
< pdf_text_country_code_t code;
---
> pdf_char_t *code;
1368c1488
< @deftypefun pdf_text_lang_code_t pdf_text_get_language (pdf_text_t @var{text})
---
> @deftypefun {const pdf_char_t *}pdf_text_get_language (pdf_text_t @var{text})
1370c1490,1492
< Return the language associated with a text variable.
---
> Return the `ISO-639-1' language code associated with a text variable, as a
> NUL-terminated string. The returned string should not be modified, as it is
> managed by the `pdf_text_t' data type.
1383c1505
< pdf_text_lang_code_t code;
---
> pdf_char_t *code;
1392c1514
< @deftypefun pdf_status_t pdf_text_set_country (pdf_text_t @var{text},
pdf_text_country_code_t @var{code})
---
> @deftypefun pdf_status_t pdf_text_set_country (pdf_text_t @var{text}, const
> pdf_char_t address@hidden)
1394c1516
< Associate a text variable with a country.
---
> Associate a text variable with a `ISO-3166-1 alpha-2' country code.
1405,1409c1527
< A status code:
< @table @code
< @item PDF_OK
< The operation succedded.
< @end table
---
> The status of the assignment.
1413c1531
< pdf_text_country_code_t code;
---
> pdf_status_t ret_code;
1417,1418c1535,1536
< code = 27;
< code = pdf_text_set_country (text, code);
---
> ret_code = pdf_text_set_country (text, "27");
>
1423c1541
< @deftypefun pdf_text_lang_code_t pdf_text_set_language (pdf_text_t
@var{text}, pdf_text_lang_code_t @var{code})
---
> @deftypefun pdf_status_t pdf_text_set_language (pdf_text_t @var{text}, const
> pdf_char_t address@hidden)
1425c1543
< Associate a text variable with a language.
---
> Associate a text variable with a `ISO-639-1' language code.
1436,1440c1554
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @end table
---
> The status of the assignment.
1444c1558
< pdf_text_lang_code_t code;
---
> pdf_status_t ret_code;
1448,1449c1562
< code = 10;
< code = pdf_text_set_language (text, 10);
---
> ret_code = pdf_text_set_language (text, "10");
1454c1567
< @deftypefun pdf_bool_t pdf_text_empty_p (pdf_text_t @var{text})
---
> @deftypefun {inline pdf_bool_t} pdf_text_empty_p (pdf_text_t @var{text})
1456c1569
< Determine if a given text variable is empty (contain no text).
---
> Determine if a given text variable is empty (contains no text).
1480c1593
< /* `text' contain no text */
---
> /* `text' contains no text */
1485a1599
>
1489,1521c1603
< @deftypefun pdf_text_host_encoding_t pdf_text_get_best_encoding (pdf_text_t
@var{text}, pdf_text_host_encoding_t @var{preferred_encoding})
<
< Return the best available host encoding to encode the contents of a
< given text variable. A specified preferred encoding is selected if
< available.
<
< The ``best'' encoding is an encoding able to encode the bigger number
< of characters of the unicode content of the given text variable.
< @table @strong
< @item Parameters
< @table @var
< @item text
< A text variable.
< @item preferred_encoding
< A text encoding supported by the host.
< @end table
< @item Returns
< The best host encoding available to encode the contents of @var{text}.
< @item Usage Example
< @example
< pdf_text_t text;
< pdf_text_host_encoding pref;
< pdf_text_host_encoding enc;
<
< /* ...create and manipulate `text'... */
<
< pref = 10;
< enc = pdf_text_get_best_encoding (text, pref);
< @end example
< @end table
< @end deftypefun
<
< @deftypefun char* pdf_text_get_host (pdf_text_t @var{text},
pdf_text_host_encoding_t @var{enc})
---
> @deftypefun pdf_status_t pdf_text_get_host (pdf_char_t address@hidden,
> pdf_size_t address@hidden, const pdf_text_t @var{text}, const
> pdf_text_host_encoding_t @var{enc})
1527a1610,1613
> @item contents
> Output array of bytes (May contain NUL bytes). Must be freed afterwards.
> @item length
> Output length of @var{contents}
1531c1617
< A host encoding.
---
> A host encoding supported by the host.
1534,1536c1620
< A pointer to a string containing the encoded representation
< of the text variable. The caller should not modify that string: it is
< managed by the text variable.
---
> The status of the conversion.
1541c1625,1627
< char *str;
---
> pdf_char_t *str;
> pdf_size_t str_length;
> pdf_status_t ret_code;
1545,1546c1631,1634
< encoding = 10;
< str = pdf_text_get_host (text, encoding);
---
> ret_code = pdf_text_get_host (&str, &str_length, text, encoding);
>
> pdf_free(str);
>
1551c1639
< @deftypefun char* pdf_text_get_pdf (pdf_text_t @var{text})
---
> @deftypefun pdf_status_t pdf_text_get_pdfdocenc (pdf_char_t address@hidden,
> const pdf_text_t @var{text})
1553c1641,1642
< Get the contents of a text variable encoded in PDFDocEncoding.
---
> Get the contents of a text variable encoded in PDF Doc Encoding,
> and NUL-terminated.
1557a1647,1648
> @item contents
> Output array of bytes (Can't contain NUL bytes). Must be freed afterwards.
1562,1564c1653
< A pointer to a string containing the encoded representation of the
< text variable. The caller should not modify that string: it is managed
< by the text variable.
---
> The status of the conversion.
1568c1657,1658
< char *str;
---
> pdf_char_t *str;
> pdf_status_t ret_code;
1572c1662,1665
< str = pdf_text_get_pdf (text);
---
> ret_code = pdf_text_get_pdfdocenc (&str, text);
>
> pdf_free(str);
>
1577d1669
< @deftypefun char* pdf_text_get_unicode (pdf_text_t @var{text})
1579,1580c1671,1674
< Get the contents of a text variable encoded in UTF16 using
< host-endian.
---
> @deftypefun pdf_status_t pdf_text_get_unicode (pdf_char_t address@hidden,
> pdf_size_t address@hidden, const pdf_text_t @var{text}, const enum
> pdf_text_unicode_encoding_e @var{enc}, const int @var{options})
>
> Get the contents of a text variable encoded in the specified
> Unicode encoding. Additional options can be set in the request.
1584a1679,1682
> @item contents
> Output array of bytes (May contain NUL bytes). Must be freed afterwards.
> @item length
> Output length of @var{contents}
1586a1685,1689
> @item enc
> A given UNICODE encoding, specifying requested endianness.
> @item options
> Additional options that can be set, in the way: OPTION_1 | OPTION_2 |
> OPTION_3.
> (see @code{pdf_text_unicode_options} data type)
1589,1591c1692
< A pointer to a string containing the encoded representation of the
< text variable. The caller should not modify that string: it is managed
< by the text variable.
---
> The status of the conversion.
1595c1696,1698
< char *str;
---
> pdf_char_t *str;
> pdf_size_t str_length;
> pdf_status_t ret_code;
1599c1702,1708
< str = pdf_text_get_unicode (text);
---
> ret_code = pdf_text_get_unicode (&str, &str_length,
> text,
> PDF_TEXT_UTF16_BE,
> PDF_TEXT_UNICODE_WITH_BOM |
> PDF_TEXT_UTF16BE_WITH_LANGCODE);
>
> pdf_free(str);
>
1604c1713
< @deftypefun pdf_status_t pdf_text_set_host (pdf_text_t @var{text}, char
address@hidden, pdf_text_host_encoding_t @var{enc})
---
> @deftypefun pdf_status_t pdf_text_set_host (pdf_text_t @var{text}, const
> pdf_char_t address@hidden, const pdf_size_t @var{size}, const
> pdf_text_host_encoding_t @var{enc})
1607c1716
< variable.
---
> variable.
1616a1726,1727
> The length of @var{str}, in bytes.
> @item enc
1620,1626c1731
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @item PDF_E_BADDATA
< The string @var{str} contain invalid data.
< @end table
---
> The status of the conversion.
1631c1736,1737
< char *str;
---
> pdf_char_t *str;
> pdf_size_t length;
1634c1740
< if (pdf_text_set_host (text, str, enc) != PDF_OK)
---
> if (pdf_text_set_host (text, str, length, enc) != PDF_OK)
1642c1748
< @deftypefun pdf_status_t pdf_text_set_pdf (pdf_text_t @var{text}, char
address@hidden)
---
> @deftypefun pdf_status_t pdf_text_set_pdfdocenc (pdf_text_t @var{text}, const
> pdf_char_t address@hidden)
1644c1750
< Set a PDFDocEncoding encoded string as the value of a text variable.
---
> Set a PDF Doc Encoding encoded string as the value of a text variable.
1652c1758
< A string encoded with PDFDocEncoding.
---
> A string encoded with PDF Doc Encoding, NUL terminated.
1655,1661c1761
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @item PDF_E_BADDATA
< The string @var{str} contain invalid data.
< @end table
---
> The status of the conversion.
1665c1765
< char *str;
---
> pdf_char_t *str;
1668c1768
< if (pdf_text_set_pdf (text, str) != PDF_OK)
---
> if (pdf_text_set_pdfdocenc (text, str) != PDF_OK)
1676c1776
< @deftypefun pdf_status_t pdf_text_set_unicode (pdf_text_t @var{text},
pdf_text_utf16_val_t address@hidden, enum pdf_text_unicode_encoding_e @var{enc})
---
> @deftypefun pdf_status_t pdf_text_set_unicode (pdf_text_t @var{text}, const
> pdf_char_t address@hidden, const pdf_size_t @var{size}, const enum
> pdf_text_unicode_encoding_e @var{enc})
1686c1786,1788
< A unicode string without prefix and country/language data embedded.
---
> A Unicode string without country/language data embedded.
> @item size
> The length of @var{str}, in bytes.
1688c1790
< The used Unicode encoding.
---
> The used Unicode encoding in @var{str}.
1691,1697c1793
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @item PDF_E_BADDATA
< The string @var{str} contain invalid data.
< @end table
---
> The status of the conversion.
1701c1797,1798
< pdf_text_utf16_val_t *str;
---
> pdf_char_t *str;
> pdf_size_t length;
1705c1802
< if (pdf_text_set_unicode (text, str, enc) != PDF_OK)
---
> if (pdf_text_set_unicode (text, str, length, enc) != PDF_OK)
1713c1810
< @deftypefun pdf_status_t pdf_text_concat (pdf_text_t @var{to}, pdf_text_t
@var{from})
---
> @deftypefun pdf_status_t pdf_text_concat (pdf_text_t @var{text}, const
> pdf_text_t @var{text1}, const pdf_text_t @var{text2})
1715,1716c1812,1817
< Concatenate the contents of two text variables and store the result in
< the second text variable.
---
> Concatenate the contents of two text variables (@var{text1} first,
> then @var{text2}) and store the result in the output text variable
> (@var{text}).
>
> Warning! If different country/language codes are found within
> the text variables an error will be returned (concatenation not
> possible)
1721,1724c1822,1824
< @item to
< The second text variable to concatenate. The contents of this variable
< are modified to hold the result of the operation.
< @item from
---
> @item text
> The output text variable.
> @item text1
1726a1827,1829
> @item text2
> The second text variable to concatenate. The contents of this variable
> are left unchanged.
1729,1733c1832
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @end table
---
> The status of the operation.
1740c1839
< if (pdf_text_concat (text1, text2) != PDF_OK)
---
> if (pdf_text_concat (text1, text1, text2) != PDF_OK)
1748c1847
< @deftypefun pdf_status_t pdf_text_replace (pdf_text_t @var{text}, pdf_text_t
@var{to}, pdf_text_t @var{from})
---
> @deftypefun pdf_status_t pdf_text_replace (pdf_text_t @var{text}, const
> pdf_text_t @var{new_pattern}, const pdf_text_t @var{old_pattern})
1757c1856
< @item to
---
> @item new_pattern
1759,1761c1858,1859
< @item from
< The text to be replaced. Any occurrence of this text is replaced with
< @var{to}.
---
> @item old_pattern
> The text to be replaced. Any occurrence of this text is replaced with
> @var{new_pattern}.
1764,1768c1862
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @end table
---
> The status of the operation
1772,1773c1866,1867
< pdf_text_t from;
< pdf_text_t to;
---
> pdf_text_t new_pattern;
> pdf_text_t old_pattern;
1775,1776c1869,1870
< /* ...initialize `text', `from' and `to'... */
< if (pdf_text_replace (text, to, from) != PDF_OK)
---
> /* ...initialize `text', `new_pattern' and `old_pattern'... */
> if (pdf_text_replace (text, new_pattern, new_pattern) != PDF_OK)
1784c1878
< @deftypefun pdf_status_t pdf_text_replace_ascii (pdf_text_t @var{text}, char
address@hidden, char address@hidden)
---
> @deftypefun pdf_status_t pdf_text_replace_ascii (pdf_text_t @var{text}, const
> pdf_char_t address@hidden, const pdf_char_t address@hidden)
1793c1887
< @item to
---
> @item new_pattern
1795,1797c1889,1890
< @item from
< The text to be replaced. Any occurrence of this text is replaced with
< @var{to}.
---
> @item old_pattern
> The text to be replaced. Any occurrence of this text is replaced with
> @var{new_pattern}.
1800,1804c1893
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @end table
---
> The status of the operation
1808,1809c1897,1898
< char *from;
< char *to;
---
> const pdf_char_t *new_pattern = "GNU/Linux";
> const pdf_char_t *old_pattern = "Linux";
1811,1812c1900,1901
< /* ...initialize `text', `from' and `to'... */
< if (pdf_text_replace_ascii (text, to, from) != PDF_OK)
---
> /* ...initialize `text'... */
> if (pdf_text_replace_ascii (text, new_pattern, old_pattern) != PDF_OK)
1820c1909
< @deftypefun pdf_status_t pdf_text_filter (pdf_text_t @var{text}, enum
pdf_text_filter_type_e @var{filter})
---
> @deftypefun pdf_status_t pdf_text_filter (pdf_text_t @var{text}, const enum
> pdf_text_filter_type_e @var{filter})
1833,1837c1922
< A status code:
< @table @code
< @item PDF_OK
< The operation succeeded.
< @end table
---
> The status of the operation
1879a1965
> If text1 < text2
1880a1967
> If text1 = text2
1881a1969
> If text1 > text2
1911a2000,2055
> @node Managing Host Encodings
> @subsection Managing Host Encodings
>
> @deftypefun pdf_text_host_encoding_t pdf_text_get_host_encoding (void)
>
> Return the host encoding configured by the user/system in the locale.
>
> @table @strong
> @item Parameters
> None
> @item Returns
> The host encoding configured in the user's locale.
> @item Usage Example
> @example
> pdf_text_host_encoding enc;
>
> enc = pdf_text_get_host_encoding();
>
> @end example
> @end table
> @end deftypefun
>
>
> @deftypefun pdf_text_host_encoding_t pdf_text_get_best_encoding (const
> pdf_text_t @var{text}, const pdf_text_host_encoding_t
> @var{preferred_encoding})
>
> Return the best available host encoding to encode the contents of a
> given text variable. A specified preferred encoding is selected if
> available.
>
> The ``best'' encoding is an encoding able to encode the bigger number
> of characters of the unicode content of the given text variable.
> @table @strong
> @item Parameters
> @table @var
> @item text
> A text variable.
> @item preferred_encoding
> A text encoding supported by the host.
> @end table
> @item Returns
> The best host encoding available to encode the contents of @var{text}.
> @item Usage Example
> @example
> pdf_text_t text;
> pdf_text_host_encoding pref;
> pdf_text_host_encoding enc;
>
> /* ...create and manipulate `text'... */
>
> enc = pdf_text_get_best_encoding (text, pref);
>
> @end example
> @end table
> @end deftypefun
>
>