Methods for using objects of the string class.

Methods for using objects of the string class.

String objects are expected to be encoded with UTF-8.

When creating String objects from differently encoded data, the results may be unexpected!

Please note the fundamental difference between strings of type String and char*.!

char* is a piece of memory that you have previously reserved with alloc. The contents of this piece of memory can be used up to the allocated size of this memory, but no further! An Ascii-0 within this reserved memory area signals the end of your string (but not necessarily the end of the reserved memory area).

The following table shows a char* character string allocated with the length 5. alloc has chosen the address 1000 for it and 5 bytes reserved for the content. With strcpy (my_char, "FUN"); four of the bytes of this area were filled, three with the text "FUN" and one at the end with \0 to indicate that the text ends here:
Address 1000 1001 1002 1003 1004
Content F U N \0 undefined

String is an object that is much simpler. About the length and location of its content you don't have to worry about. This is done by object itself.
Address 1000 ... char* with the content
Content Internal object informations
...
Current size of the reserved memory
char* address to content
... FUN\0
On the other hand, you usually cannot simply access the object by char*. The content is not located there. To access the char* content of a string, use the function string::get. However, a wide variety of cScript functions are able to make the necessary conversion from String to char* independently. Please note the respective description of the function parameters. If there is String or char*, you can use both data types, otherwise only the specified data type. And, please, constants of the kind "abcde" are not strings but char*!

Character positions within a string are counted always 0-based.

Since UTF-8 characters within a string can consist of up to 4 single bytes, there is a difference between the so-called letter or UTF-8 and the "real" or byte index: Because the letter ä consists of two UTF8 characters, the n in "Hände" (hands) has the index 2, but is actually at byte index 3.

Unless otherwise specified, the String functions use the UTF-8 index.

static String alloc(char* value = "", ...)

Create a new self-managing string. The object must be deleted again using string::release.

Name Type Default Description
Return String   A new object of type String
value String or char * "" Initial value of the string. This value is copied.
The string can contain %-marks , see here to learn more. An additional parameter is expected in the (correct) sequence and with the correct type for each of these markers.
since v4.1 R16516
... Depending on the %-markers - Values or variables according to the %-markers in value since v4.1 R16516

String		str	= string::alloc ();

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static void release(String str)

Delete a string object created using string::alloc

Name Type Default Description
str String - Delete an object from the memory

String		str	= string::alloc ();
 	:
 	:
string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String set(
  String target,
  String format,
  ...)

Set the value of the string

Name Type Default Description
Return String   Changed input string
target String - String object to set the value for
format String or char * - New value of the string. This value is copied.
The string can contain %-marks , see here to learn more. An additional parameter is expected in the (correct) sequence and with the correct type for each of these markers.
... Depending on the %-markers - Values or variables according to the %-markers in format

int main()
{
    String str = string::alloc();
string::set(str, "Hallo Welt"); showmessage(str);
string::release (str);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static char* get(String str)

Get the contents of a string as char*. The length of the contents of a string object may not be changed!

Name Type Default Description
Return char*   The content of the object as 0-ended C-String.

The return value is read only! It must never (in words: NEVER be changed directly. Changes to this char * lead to an immediate crash of InDesign®.

Use strcpy to copy the content of a string into an allocated char* pointer.
str String - String object the content of which is to be ascertained

#include "internal/text.h"
String		str	= string::alloc ();
textmodel::gettext (str, 0, kEnd); showmessage (string::get (str));
string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static char* data(String str)

Content of a string object. The result can contain 0 bytes. Strings with 0-bytes be useful for transporting binary files.

Name Type Default Description
Return int   Content of a string object. The result can contain 0 bytes.
str String - Valid String

Read a binary file and write the result to another file. (Please note: The script is for demonstration only, normally you would use file::duplicate here.)

int main ()
{
    String		str		= string::alloc ();
    int 		fileRef;
    int			fileSize;
// Read file fileRef = file::open("$DESKTOP/b1.jpg", "r"); fileSize = file::read_str (fileRef, str, 4); file::close (fileRef);
// Write read data to another file fileRef = file::open("$DESKTOP/b2.jpg", "w"); file::write (fileRef, string::data (str), fileSize); file::close (fileRef);
return 0; }

v4.1 R22123, 28. März 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static int length(String str, int countBytes = 1)

Current length of the string

Name Type Default Description
Return int   Length of the string in bytes or letters
str String - String object the length of which is to be ascertained
countBytes int 1 Which length should be determined?

0 : Letters, multibyte UTF8 characters count as one letter

1 : Bytes

String		str	= string::alloc ();
int		len;
 	:
textmodel::gettext (str);
len = string::length (str);
 	:
string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String append(
  String target,
  String toAppend,
  ...)

Append to a string

Name Type Default Description
Return String   Changed input string
target String - String object to append into
toAppend String or char * "" Value to append

The string can contain %-marks , see here to learn more. An additional parameter is expected in the (correct) sequence and with the correct type for each of these markers.
since v4.1 R16516
... Depending on the %-markers - Values or variables according to the %-markers in value since v4.1 R22201

int main()
{
    String str = string::alloc("aaa");
string::append(str, "bbb %d", 123); showmessage(str); //shows "aaabbb 123"
string::release(str);
return 0; }

v4.1 R19023
%-markers since v4.1 R22201, 10. Apr 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String insert(
  String target,
  int position,
  String input)

Insertion into a string

Name Type Default Description
Return String   Changed input string
target String - String object to insert into
position int - Position to insert to
-1: At end
input String or char * - Value to insert

int main()
{
    String target = string::alloc();
    String input = string::alloc();
    int length = 0;
string::set(target, "AAACCC"); string::set(input, "BBB");
//insert at position 3 (middle) string::insert(target, 3, input); showmessage(target); //shows "AAABBBCCC"
//insert at the end length = string::length(target, 0); string::insert(target, length, "DDD"); showmessage(target); //shows "AAABBBCCCDDD"
string::release(target); string::release(input);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String erase(
  String input,
  int position,
  int length = -1)

Delete characters from a string

Name Type Default Description
Return String   Changed input string
input String - String object to delete from
position int - Position to delete from
length int - How many characters should be deleted (-1 = to end)?

int main()
{
    String target = string::alloc();
string::set(target, "Hello World");
string::erase(target, 4, 1); showmessage(target); //shows "Hell World"
string::erase(target, 4, -1); showmessage(target); //shows "Hell"
string::release(target);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int find(
  String searchIn,
  String searchFor,
  int fromPosition = 0,
  int* matchLength = 0,
  int* matches = 0,
  int compile_options = 0,
  int study_options = 0,
  int exec_options = 0)

Search strings inside a string

Name Type Default Description
Return int   -1 : not found

otherwise : Position of the searched string
searchIn String - String object to search inside
searchFor String or char * - Search for this substring. Must not be equal to "".

The search string may be a regular expression.
Use prefix "regexp:" or "pcre:" to mark a search string as a regular expression.
fromPosition int 0 Search from this position
matchLength int * 0 (For regular expressions only) Length of found sub string
matches int * 0 (For regular expressions only) int-Array containing pairs of positions and lengths for the sub-entries of the next match.

The first pair gives the position and the length of whole expression. The following pairs containing the positions and lengths of every sub-expression. Sub-expressions of an regular expressions are every "(...)" substring of the regular expression, for instance ([a-z]{3,7}). The array is closed by the pair (-1, 0).

Attention : Sub entries may have a length of 0! The regular expression ([0-9])([a-z]{0,7})([0-9])) applied to "14" will return an empty string for the second sub-expression.

Take care to allocate enough space, if you are using this array. You need at least (1+number of sub-expressions+1) * 2 integers.
compile_options int 0 Additional options while compiling regular expression, see here
study_options int 0 Additional options while studying compiled regular expression, see here
exec_options int 0 Additional options while executing regular expression, see here

int main()
{
    String myString = string::alloc();
    int position = 0;
string::set(myString, "123 444 555"); position = string::find(myString, "444", 0); showmessage("Found at %d", position); //Shows "Found at 4" string::release(myString);
return 0; }
//find regex with loop
int main()
{
    String myString = string::alloc();
    String foundString = string::alloc();
    int position = 0;
    int matchLength = 0;
string::set(myString, "ÄÄÄ 123 øøø 444"); while (1) { //find blocks of numbers position = string::find(myString, "pcre:[0-9]+", position + matchLength, &matchLength); if (position < 0) { break; } if (matchLength <= 0) { break; } string::set(foundString, string::substring(myString, position, matchLength));
showmessage("found match (with loop) at %d with length %d: %s", position, matchLength, foundString); } string::release(myString); string::release(foundString);
return 0; }

v4.1 R16516
compile_options, study_options, exec_options since v4.0.5 R20456, 10. Oct 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_realindex, get_utf8index

static String replace(
  String input,
  String searchFor,
  String replaceBy,
  int position = 0,
  int replaceAll = 1,
  int compile_options = 0,
  int study_options = 0,
  int exec_options = 0)

Replace substrings inside a string

Name Type Default Description
Return String   Changed input string
input String - String object to search inside
searchFor String or char * - Search for this substring. Must not be equal to "".

The search string may be a regular expression.
Use prefix "regexp:" or "pcre:" to mark a search string as a regular expression.
replaceBy String or char * - This replaces the found substrings
position int 0 Search from this position
replaceAll int 1 Should all occurrences (1) or only the first one (0) be replaced?
compile_options int 0 Additional options while compiling regular expression, see here
study_options int 0 Additional options while studying compiled regular expression, see here
exec_options int 0 Additional options while executing regular expression, see here

int main()
{
    String myString = string::alloc();
string::set(myString, "Hello Leo, how are you today Leo?"); string::replace(myString, "Leo", "Paul"); showmessage(myString); //shows "Hello Paul, how are you today Paul?"
return 0; }
//replace all white space in a string with underscores
int main()
{
    String myString = string::alloc();
string::set(myString, "Hello Leo, how are you today Leo?"); string::replace(myString, "pcre:[\\s]+", "_"); showmessage(myString); //shows "Hello_Leo,_how_are_you_today_Leo?"
return 0; }

v4.1 R16516
compile_options, study_options, exec_options since v4.0.5 R20456, 10. Oct 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

String replace_multis(String str, String repl = 0)

Remove multiple characters from a string. The function replaces Κ all repetitions of each character in repl in str. With the repl string "abc", all "aa", "bb", "cc" ΚΚΚΚ "aaa", "bbb", "ccc", ... are shortened to one character each.

Name Type Default Description
Return char*   str ist returned for your convinience
str char* - source string
repl char* 0 Replace all multiples of all letters of this string. Only ASCIIs are allowed here!

0 : Replace are multiple blanks ( ) by single blanks.

Here's an example of a string compare script

char * prepare_string (char * str)
{
    char		*	result = alloc (strlen (str)+10);
get_netweight_str (result, str, 1, 1); strreplace (result, "\t", " "); strreplace_multis (result, " \t");
return result; }
int main () { return strcmp (prepare_string (gDocumentValue), prepare_string (gDataPoolValue)); }

v4.1, R23900, 1. Oct. 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static char* replace_all(
  String str,
  char* search,
  char* repl)

Replace all occurrences of a substring with another substring.

Name Type Default Description
Return char*   The new content of the string as 0-ended C-String.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

str String - String object the content of which is to be changedobjekt
search char* - Search string
rep char* - Replace string

String		str	= string::alloc ();
textmodel::gettext (str, 0, kEnd); showmessage (string::replace_all (str, "aa", "a"));
string::release (str);


priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String substring(
  String input,
  int position,
  int length = -1)

Extracts a substring from a string

Name Type Default Description
Return String   Substring
The result is only valid directly after the call. If it is to be used again it must be copied into another string
input String - String object to extract from
position int - Startposition of the substring
length int -1 Length of the substring (-1 = until the end)

int main ()
{
    String str = string::alloc("Hallo Welt");
    String sub = string::alloc();
sub = string::substring(str, 0, 5); showmessage(sub); //shows "Hallo"
string::release(str); string::release(sub);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int compare(
  String first,
  String second,
  int maxLength = -1,
  int netweight = 0)

Alpha-numerical comparison of two strings.

The content of an empty placeholder isn't empty but a zero width space (<0x200B>). In the following code snippet the showmessage will never reached:

int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText);

    if (string::compare(docText, "") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}


In this case, one must check the document text against the zero width space (UTF8 = E2 80 8B, Unicode = 200B):

int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText);

    if (string::compare(docText, "\xE2\x80\x8B") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}


If you use a tagged format to retreive the document text, please use the Unicode tag of zero width space to compare. This however complicates the string comparison as the tagged formats are more verbose and contain styles, which may be different :

#include "internal/text.h" int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText, 0, -1, kExportTT);

    if (string::compare(docText, "%!TT<ParaStyle:NormalParagraphStyle><0x200B>") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}


To compare the "net weight" strings you can use the function with netWeight = 1.

Name Type Default Description
Return int   < 0 : first < second
Return int   = 0 : first == second
Return int   > 0 : first > second
first String or char* - First string to compare
second String or char* - Second string to compare
maxLength int -1 Only compare to given length. If a string is shorter, the comparison ends there.
netweight int 0 Compare the net weight strings

  • Replace empty strings by a zero width space (Unicode 0x200B).
  • Replace all UTF-8 letters by their (Unicode) tags <0xXXXX>.
  • If the strings begins with %!TT, remove the ParaStyle right behind %!TT.
  • Replace all other ParaStyles by paragraph delimiters (hard returns).
  • Remove all remaining TaggedText tags.
  • Replace every double quota by " and every singe quota by '.
  • Replace every blank (Unicode 0x2000 - 0x200F) by space.
  • Replace every hyphenation sign (Unicode 0x2010 - 0x2016) by minus.

#include "internal/text.h"
int main ()
{
    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String upper(String input)

Covert string to upper case characters.

Name Type Default Description
Return String   Changed input string
input String - String to be converted to uppercase characters

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String lower(String input)

Covert string to upper case characters.

Name Type Default Description
Return String   Changed entry string
input String - String to be converted to lowercase characters

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String reverse(String input)

Reverse a string

Name Type Default Description
Return String   Changed entry string
input String - String to be reversed

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf

static String trim(String input, char toTrim = 0)

Remove the occurrences of a specified character at the start and the end of a character string.

Name Type Default Description
Return String   Changed entry string
input String - String to be trimmed
toTrim char 0 Character to remove. Only single-byte characters with an Ascii value < 128 are allowed. Higher-order Ascii or Unicode characters can cause InDesign® to crash.

0 : Remove all invisible characters (Blanks, Tabs, Line delimiters, ...) at the start and the end of the string

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int token_count(
  String input,
  char delimiter,
  int checkIfEmpty = 0)

When using UTF-8 strings, the function is extremely toxic and should be urgently replaced by string::get_token_count:

  1. Change the function name to string::get_token_count.
  2. Change the single quotes around the delimiter to double quotes.

Please use the string::get_token_count function instead.

static String token(
  String input,
  char delimiter,
  int tokenIndex)

When using UTF-8 strings, the function is extremely toxic and should be urgently replaced by string::get_token:

  1. Change the function name to string::get_token.
  2. Change the single quotes around the delimiter to double quotes.

Please use the string::get_token function instead.

static int get_token_count(String str, String delimiter)

How many parts separated by a certain word (the so-called tokens) does a string consist of? Common uses are tab-delimited text lines or file paths. To simplify the calls, both strings may be specified as String as well as char*.

Name Type Default Description
Return String or char*   Number of tokens separated by delimiter in the input string.
input String or char* - String to be searched in
delimiter char - Separator. The separator may contain UTF-8 characters and can be several letters long.

Here is a simple example:

String	str = string::alloc ();
...
string::set (str, "Matthias"); string::get_token_count (str, "a") // returns 3 string::get_token_count (str, "i") // returns 2 string::get_token_count (str, " ") // returns 1

v4.1.8 R29200, 4 Oct. 2021

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String get_token(
  String str,
  String delimiter,
  int nth)

Get the n-th word of the strings subdivided by a specified character. Common uses are tab-delimited text lines or file paths. To simplify the calls, both strings may be specified as String as well as char*. But please note that the result is of type String in any case.

Name Type Default Description
Return String   Found token. If no further token was found, the result is empty. The result is only valid directly after the call. If it is to be used again it must be copied into another string.
input String - String to be searched in
delimiter char - Separator. The separator may contain UTF-8 characters and can be several letters long.
tokenIndex int - 0-based index of the word

Here is a simple example:

String	str = string::alloc ();
...
string::set (str, "Matthias"); string::get_token_count (str, "a", 0) // returns M string::get_token_count (str, "a", 1) // returns tthi string::get_token_count (str, "a", 2) // returns s string::get_token_count (str, "a", 3) // returns the empty string string::get_token_count (str, "x", 3) // returns Matthias

v4.1.8 R29200, 4 Oct. 2021

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int to_int(String input)

Convert a fixed number string into a number. The string may also begin with hexadecimal or octal numbers. Hexadecimal numbers must begin with "0x".

Name Type Default Description
Return int   Number value of the string
input String - Number string

//Different formats for representing the same number
int main()
{
    String myString = string::alloc();
    int stringValue = 0;
string::set(myString, "255"); stringValue = string::to_int(myString); showmessage("%d", stringValue); //shows 255
string::set(myString, "0xff"); stringValue = string::to_int(myString); showmessage("%d", stringValue); //shows 255
string::set(myString, "0xFF"); stringValue = string::to_int(myString); showmessage("%d", stringValue); //shows 255
string::set(myString, "0xFFTTT"); stringValue = string::to_int(myString); showmessage("%d", stringValue); //shows 255
string::release(myString);
return 0; }

Data type int is 64bit aware. Here's an example with integers greater than 32 bit:

int main ()
{
    int a = 6917529027641081856;
    String str = string::alloc();
    string::from_int(str, a);
//the messages below show the same value showmessage("Int value of a is %d", a); showmessage("Int value of str is %d", string::to_int(str));
string::release(str);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String from_int(int value)

Convert a fixed number into a string.

Name Type Default Description
Return String   Value as string.
The result is only valid directly after the call. If it is to be used again it must be copied into another string
value int - Value to be converted to a string

int main ()
{
    int a = 1234;
    showmessage(string::from_int(a));
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static float to_float(String input)

Convert a string of a float number into a string

Name Type Default Description
Return float   Float value of the string
input String - Float number string.
The number must be point ('.') or comma (',') separated. No delimiters are allowed between the 1000s.

//Different formats for representing the same number
int main ()
{
    String myString = string::alloc();
string::set(myString, "12.3"); showmessage("%f", string::to_float(myString)); //shows 12.3000
string::set(myString, "12,3"); showmessage("%f", string::to_float(myString)); //shows 12.3000
string::set(myString, "1.23e+1"); showmessage("%f", string::to_float(myString)); //shows 12.3000
string::set(myString, "123.e-1"); showmessage("%f", string::to_float(myString)); //shows 12.3000
string::release(myString);
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String from_float(float value, String format)

Convert a float number into a string.

Name Type Default Description
Return String   Value as string.
The result is only valid directly after the call. If it is to be used again it must be copied into another string
value int - Value to be converted to a string
format String or char * "%f" Format string, e.g. "%f".
See any public documentation of the C function sprintf.

int main ()
{
    float f = 12.34567;
    showmessage(string::from_float(f, "%.2f"));	//shows 12.35
return 0; }

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String get_netweight(
  String source,
  int convertUniTags = 0,
  int replaceTypos = 0)

Get the net weight string of a given string. Net weight strings are calculated as follows:

Name Type Default Description
Return String   Newly created string with the base64 coded input string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

source String oder char * - String to get the netweight for
convertUniTags int 0 Auto replace Unicode tags of form <0x200B>?

0 : No
else : Yes
replaceTypos int 0 Replace quotes, blanks and hyphens by unique letters?

0 : No
else : Yes

int main ()
{
    String source = string::alloc("ÄÖÜ");
    String netWeight = string::alloc();
string::set(string::get_netweight(source)); showmessage(netWeight); //Shows "<0x00C4><0x00D6><0x00DC>"
string::release(source); string::release(netWeight);
return 0; }

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf

4

static String md5(String input, int upperCase = 0)

Get the md5hash of a string.

Name Type Default Description
Return String   32 hex digits long md5hash of the string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String or char * - Any string
upperCase int 0 Use capital letters for hex numbers?

0 : no
1 : yes

Get the md5hash of a string.

int main () {
    String str = string::alloc("Hallo Welt");
    String md5;
    md5 = string::md5(str);
if (md5 != 0) { showmessage(md5); }
string::release(str);
return 0; }

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String encode_base64(String source)

Create a base64 coded string of a given string.

Name Type Default Description
Return String   New created string with the base64 coded input string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String or char* - Any string

Encoding a text and decoding the result again should yield the original text.

int main () {
    String str = string::alloc("Hallo Welt");
    String reconverted;
    String base64;
base64 = string::encode_base64(str);
if (base64 != 0) { showmessage(base64); reconverted = string::decode_base64(base64); if (reconverted != 0) { showmessage(reconverted); //Shows "Hallo Welt" } }
string::release(str); //Do NOT release base64 and reconverted!" //This strings are r/o return values of built-in functions."
return 0; }

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

string::decode_base64

static String decode_base64(String source)

Decode a base64 encoded string.

Name Type Default Description
Return String   Newly created string with the base64 coded input string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String or char* - Any base64 encoded string

Encoding a text and decoding the result again should yield the original text.

int main () {
    String str = string::alloc("Hallo Welt");
    String reconverted;
    String base64;<>
    base64 = string:br:encode_base64(str);
if (base64 != 0) { showmessage(base64); reconverted = string::decode_base64(base64); if (reconverted != 0) { showmessage(reconverted); //Shows "Hallo Welt" } }
string::release(str); //Do NOT release base64 and reconverted!" //This strings are r/o return values of built-in functions."

return 0; }

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

string::encode_base64

static char* to_cp1252(String source)

Convert a String to 'Code Page 1252'

Name Type Default Description
Return char*   Newly created char* with changed encoding

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String - Any String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_cp1252

static char* to_systemcharset(String source)

Convert a String to the system charset

Name Type Default Description
Return char*   Newly created char* with changed encoding

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String - Any String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_systemcharset

static char* to_macroman(String source)

Convert a String to Mac Roman

Name Type Default Description
Return char*   Newly created char* with changed encoding

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o char* values.

input String - Any String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_macroman

static int* to_wchar(String input, int* destination)

Convert a String to Unicode

Name Type Default Description
Return int*   Converted String, same as parameter destination
input String - Any String
destination String - Reserved memory for the result

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_wchar

static String from_cp1252(char* input)

Convert a 'Code Page 1252' char* into a String

Name Type Default Description
Return String   Newly created string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o values.

input char* - CP1252 encoded String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_cp1252

static String from_systemcharset(char* input)

Convert a system charset encoded char* into a String

Name Type Default Description
Return String   Newly created string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o values.

input char* - System charset encoded String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_systemcharset

static String from_macroman(char* input)

Convert a system charset Mac Roman char* into a String

Name Type Default Description
Return String   Newly created string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o values.

input char* - Mac Roman encoded String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_macroman

static String from_wchar(String source)

Convert a unicode int* to a String

Name Type Default Description
Return String   Newly created string.

The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. Learn more about functions returning r/o values.

input int* - Unicode encoded string

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_wchar

static String escape_tagged(String source)

Replace all non-ASCII character with TaggedText markers.

Name Type Default Description
Return String   Changed String, same as parameter input
input String - Unicode encoded string

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::unescape_tagged

static String unescape_tagged(String source)

Replace all TaggedText markers with their UTF8 characters.

Name Type Default Description
Return String   Changed String, same as parameter input
input String - Unicode encoded string

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::escape_tagged

static String prepare_aem_url(
  String url,
  char* user = 0,
  char* pwd = 0,
  int pwd_encrypted = 0)

Prepare an asset URL from an AEM® for downloading the asset.

If you drag&drop an asset from an AEM®, the drop coontains an URL without credentials. But for downloading assest from an AEM® crendetials are required. The function inserts the user name and password of the current AEM® connection into the URL. Defaults can be used, if no AEM® connection is established.

In addition to adding the credentials some corrections on the URL are done to create a valid download request:

You may use all string functions, to do further preparations.

Name Type Default Description
Return String   Changed String, same as parameter url
url String - URL of an AEM® asset
user String oder char* 0 User name. The parameter is used only, if no AEM® connetion is established.

0 or empty : "admin"
pwd String oder char* 0 Password. The parameter is used only, if no AEM® connetion is established.

0 or empty : "admin"
pwd_encrypted int 0 Is the password encrypted? The parameter is used only, if no AEM® connetion is established.

0 : No
1 : Yes, encrypted by crypt

v4.1 R23457, 19. Jul 2018
Parameter pwd_encrypted since v4.1.6 R25346, 25. Juni 2019

priint:comet InDesign® Plug-Ins, comet_pdf

file::aem_get_asset, crypt

static String crypt_url_credentials(String url)

Encrypts authentication tokens in an URL, e.g. http://user:password@pubserver.priint.com/...
The URL can be decrypted using string::decrypt_url_credentials

Name Type Default Description
Return String   Changed string, same as parameter url
url String - URL

v4.1.5 R24777, 18. Feb 2019
priint:comet InDesign® Plug-Ins, comet_pdf

static String decrypt_url_credentials(String url)

Decrypts authentication tokens in an URL, e.g. http://user:password@pubserver.priint.com/...
The URL can be encrypted again using string::crypt_url_credentials

Name Type Default Description
Return String   Changed string, same as parameter url
url String - URL

Security leak
v4.1.5 R24777, 18. Feb 2019
priint:comet InDesign® Plug-Ins, comet_pdf

static String crypt(String str)

Encrypts a string. The result is a encrypted and Base64-encoded string. The encryption can be undone with string::decrypt.

Name Type Default Description
Return String   Changed string, same as parameter str
str String - String to encrypt

v4.1.6 R25346, 25. June 2019
priint:comet InDesign® Plug-Ins, comet_pdf

static String decrypt(String url)

Decrypts a string encrypted with string::crypt.

Name Type Default Description
Return String   Changed string, same as parameter str
str String - String to decrypt

Security leak
v4.1.6 R25346, 25. June 2019
priint:comet InDesign® Plug-Ins, comet_pdf

This class has no child classes.

Preconditions
#include "internal/text.h"

Since
Version 1.1.5

Alphabetic index HTML hierarchy of classes or Java