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 ();

Since

Version 1.1.5

Available

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);

Since

Version 1.1.5

Available

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, "Hello World");
    showmessage(str);

    string::release (str);

    return 0;
}

Since

v4.1 R16516

Available

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

Preconditions

#include "internal/text.h"

String		str	= string::alloc ();

textmodel::gettext (str, 0, kEnd);
showmessage (string::get (str));

string::release (str);

Since

Version 1.1.5

Available

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;
}

Since

v4.1 R22123, 28. März 2018

Available

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);

Since

Version 1.1.5

Available

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;
}

Since

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

Available

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;
}

Since

v4.1 R16516

Available

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;
}

Since

v4.1 R16516

Available

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

static int find(
  String searchIn,
  char* 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. Simple way to define such an array for a regular expression with 4 sub-entries. int matches [6];
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;
}

Since

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

Available

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

See Also

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;
}

Since

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

Available

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));
}

Since

v4.1, R23900, 1. Oct. 2018

Available

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. See here to learn more about functions returning r/o char* values.
str	String	-	String object the content of which is to be changedobjekt
search	char* or String	-	Search string
repl	char* or String	-	Replace string

String		str	= string::alloc ();

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

string::release (str);

Since

search and repl as Strings since v4.1.8 R29550

Available

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;
}

Since

v4.1 R16516

Available

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.

Preconditions

#include "internal/text.h"

int main ()
{
    return 0;
}

Since

v4.1 R16516

Available

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

Since

v4.1 R16516

Available

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

Since

v4.1 R16516

Available

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

Since

v4.1 R16516

Available

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

Since

v4.1 R16516

Available

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.

Deprecated

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.

Deprecated

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	int		Number of tokens separated by delimiter in the input string.
input	String or char*	-	String to be searched in
delimiter	String or 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

Since

v4.1.8 R29200, 4 Oct. 2021

Available

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

Since

v4.1.8 R29200, 4 Oct. 2021

Available

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;
}

Since

v4.1 R16516

Available

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;
}

Since

v4.1 R16516

Available

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;
}

Since

v4.1 R16516

Available

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;
}

Since

v4.1 R16516

Available

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:

• 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.

Name	Type	Default	Description
Return	String		String with the input text shortened as described above. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to 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;
}

Since

v4.1 R16536

Available

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. See here to 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;
}

Since

v4.1 R16536

Available

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		Base64 coded input string. The return value is read only, do NOT CHANGE. The result will be overridden on following calls to the function. See here to 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;
}

Since

v4.1 R16536

Available

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

See Also

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. See here to 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;
}

Since

v4.1 R16536

Available

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

See Also

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. See here to learn more about functions returning r/o char* values.
input	String	-	Any String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o char* values.
input	String	-	Any String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o char* values.
input	String	-	Any String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o values.
input	char*	-	CP1252 encoded String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o values.
input	char*	-	System charset encoded String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o values.
input	char*	-	Mac Roman encoded String

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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. See here to learn more about functions returning r/o values.
input	int*	-	Unicode encoded string

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

v4.1 R18355

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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:

• "/assetdetails.html" is removed
• "content/dam" is replaced by "api/assets"
• "%20" are replaced by blank

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

Since

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

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

See Also

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

Since

v4.1.5 R24777, 18. Feb 2019

Available

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

Deprecated

Security leak

Since

v4.1.5 R24777, 18. Feb 2019

Available

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

Since

v4.1.6 R25346, 25. June 2019

Available

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

Deprecated

Security leak

Since

v4.1.6 R25346, 25. June 2019

Available

priint:comet InDesign^® Plug-Ins, comet_pdf

Preconditions

#include "internal/text.h"

Since

Version 1.1.5

Alphabetic index HTML hierarchy of classes or Java