LayerAS_Layer
ObjectASText

An ASText object holds encoded text.

In Acrobat, encoded text can be specified in one of two ways:

Each of the formats described in the following table can be mapped to one of the two cases outlined above:

ASText objects also can be used to accomplish encoding conversions; your plug-in can request a string in any of the formats specified above.

In all cases the ASText code attempts to preserve all characters. For example, if your plug-in attempts to concatenate strings in separate host encoding, the implementation may convert both to Unicode and perform the concatenation in Unicode space.

When creating a new ASText object, or putting new data in an existing object, Acrobat will always copy the supplied data into the ASText object. The original data is yours to do with as you wish (and release if necessary).

The size of ASText data always is specified in bytes (for example, the len argument to ASTextFromSizedUnicode() specifies the number of bytes in the string rather than the number of Unicode characters).

Host encoding and Unicode strings are always terminated with a NULL character (which consists of one NULL byte for host-encoded strings and two NULL bytes for Unicode strings). You cannot create a string with an embedded NULL character even using methods that take an explicit length parameter.

The GetXXX methods return pointers to data held by the ASText object. Your plug-in cannot free or manipulate this data directly. The GetXXXCopy methods return data that your plug-in can manipulate at will and is responsible for freeing.



Define Summary
 Define
 ASTextEqual
Typedef Summary
 Typedef
 ASConstText
An opaque object holding constant encoded text.
 ASCountryCode
 ASLanguageCode
 ASText
An opaque object holding encoded text.
 ASUniChar
 ASUnicodeChar
An ASUnicodeChar is large enough to hold any Unicode character (at least 21 bits wide).
 ASUTF16Val
Holds a single 16-bit value from a UTF-16 encoded Unicode string. It is typically used to point to the beginning of an UTF-16 string. For example: ASUTF16Val *utf16String = ...
 ASUTF32Val
 ASUTF8Val
An ASUTF8Val holds a single 8-bit value from a UTF-8 encoded Unicode string.
Enumeration Summary
 Enumeration
  ASTextFilterType
Constants that specify filter types used to modify text objects.
  ASUnicodeFormat
Describes the various Unicode formats you can place into and read out of an ASText object.
Callback Summary
 Callback
 ASTextEvalProc
Method Summary
 Method
 
Compares two ASConstText objects, ignoring language and country information. The comparison is case-sensitive.
 
Concatenates the from text to the end of the to text, altering to but not from. It does not change the language or country of to unless it has no language or country, in which case it acquires the language and country of from.
 
void ASTextCatMany(ASText to, ... )
Concatenates a series of ASText objects to the end of the to object. Be sure to provide NULL as the last argument to the call.
 
ASInt32 ASTextCmp(ASConstText str1, ASConstText str2)
Compares two ASText objects. This routine can be used to sort text objects using the default collating rules of the underlying operating system before presenting them to the user. The comparison is case-sensitive. The results are suitable for displaying a sorted list of strings to the user in his chosen language and according to the rules of the platform on which the application is running. The results can vary based on the platform and user locale. If you want to compare strings in a way that is consistent across locales and platforms (but not suitable for displaying sorted strings to a user) see ASTextCaseSensitiveCmp().
 
Copies the text in from to to, along with the country and language.
 
Frees all memory associated with the text object.
 
Creates a new ASText object that contains the same text/country/language as the one passed in.
 
void ASTextEval(ASText theText, ASCab params)
Replaces percent-quoted expressions in the text object with the result of their evaluation, using key/value pairs in the ASCab. For example, for a text value containing the string "%keyone%%keytwo%", the value is replaced with the concatenation of the values of the keys keyone and keytwo in the ASCab passed in.
 
Runs the specified filter on a text object, modifying the text as specified.
 
ASText ASTextFromEncoded(const char* str, ASHostEncoding encoding)
Creates a new text object from a NULL-terminated multi-byte string in the specified host encoding.
 
Creates a new string from an ASInt32 by converting the number to its decimal representation without punctuation or leading zeros.
 
ASText ASTextFromPDText(const char* str)
Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate NULL termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.
 
ASText ASTextFromScriptText(const char* str, ASScript script)
Creates a new string from a NULL-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().
 
ASText ASTextFromSizedEncoded(const char* str, ASTArraySize len, ASHostEncoding encoding)
Creates a new text object from a multi-byte string of the specified length in the specified host encoding.
 
ASText ASTextFromSizedPDText(const char* str, ASTArraySize length)
Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. The length parameter specifies the size, in bytes, of the string. The string must not contain embedded NULL characters.
 
ASText ASTextFromSizedScriptText(const char* str, ASTArraySize len, ASScript script)
Creates a new text object from the specified multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().
 
Creates a new text object from the specified Unicode string. This string is not expected to have 0xFE 0xFF prepended, or country/language identifiers.
 
ASText ASTextFromUnicode(const ASUTF16Val* ucs, ASUnicodeFormat format)
Creates a new string from a NULL-terminated Unicode string. This string is not expected to have 0xFE 0xFF prepended, or country/language identifiers.
 
Creates a new string from an ASUns32 by converting it to a decimal representation without punctuation or leading zeros.
 
ASHostEncoding ASTextGetBestEncoding(ASConstText str, ASHostEncoding preferredEncoding)
Returns the best host encoding for representing the text. The best host encoding is the one that is least likely to lose characters during the conversion from Unicode to host. If the string can be represented accurately in multiple encodings (for example, it is low-ASCII text that can be correctly represented in any host encoding), ASTextGetBestEncoding() returns the preferred encoding based on the preferredEncoding parameter.
 
ASScript ASTextGetBestScript(ASConstText str, ASScript preferredScript)
Returns the best host script for representing the text. The functionality is similar to ASTextGetBestEncoding(), with resulting host encoding converted to a script code using ASScriptFromHostEncoding().
 
ASCountryCode ASTextGetCountry(ASConstText text)
Retrieves the country associated with an ASText object.
 
const char* ASTextGetEncoded(ASConstText str, ASHostEncoding encoding)
Returns a NULL-terminated string in the given encoding. The memory to which this string points is owned by the ASText object and may not be valid after additional operations are performed on the object.
 
Returns a copy of a string in a specified encoding.
 
ASLanguageCode ASTextGetLanguage(ASConstText text)
Retrieves the language code associated with an ASText object.
 
Returns the text in a form suitable for storage in a PDF file. If the text can be represented using PDFDocEncoding, it is; otherwise it is represented in big-endian UTF-16 format with 0xFE 0xFF prepended to the front and any country/language codes embedded in an escape sequence right after 0xFE 0xFF.
 
const char* ASTextGetScriptText(ASConstText str, ASScript script)
Converts the Unicode string in the ASText object to the appropriate script, and returns a pointer to the converted text. The memory to which it points is owned by the ASText object and must not be altered or destroyed by the client. The memory may also become invalid after subsequent operations are applied to the ASText object.
 
Converts the Unicode string in the ASText object to the appropriate script and returns a pointer to the converted text. The memory to which it points is owned by the client, which is responsible for freeing it using ASfree().
 
const ASUTF16Val* ASTextGetUnicode(ASConstText str)
Returns a pointer to a string in kUTF16HostEndian format (see ASUnicodeFormat). The memory to which this string points is owned by the ASText object, and may not be valid after additional operations are performed on the object.
 
Returns a pointer to a NULL-terminated string in the specified Unicode format. The memory to which this string points is owned by the client, which can modify it at will and is responsible for destroying it using ASfree.
 
Used to determine whether the ASText object contains no text. For example, it determines if retrieving Unicode text would yield a 0-length string.
 
Removes the contents of an ASText (turns it into an empty string).
 
Removes the contents of an ASText object (converts it into an empty string). It clears the released storage (for security strings).
 
ASText ASTextNew()
Creates a new text object containing no text.
 
Replaces all end-of-line characters within the ASText object with the correct end-of-line character for the current platform. For example, on Windows, \r and \n are replaced with \r\n.
 
void ASTextReplace(ASText src, ASConstText toReplace, ASConstText replacement)
Replaces all occurrences of toReplace in src with the text specified in replacement. This uses an ASText string to indicate the toReplace string; ASTextReplaceASCII() uses a low ASCII Roman string to indicate the text to replace.
 
void ASTextReplaceASCII(ASText src, const char* toReplace, ASConstText replacement)
Replaces all occurrences of toReplace in src with the text specified in replacement. ASTextReplace() uses an ASText string to indicate the toReplace string; this uses a low-ASCII Roman string to indicate the text to replace.
 
void ASTextReplaceBadChars(ASText str, const char* pszBadCharList, char replaceChar)
Replaces all occurrences of characters contained in the list pszBadCharList in the text with the specified replacement character.
 
Sets the language codes associated with a piece of text. ASText objects can have country and language codes associated with them. These can be explicitly set or parsed from the Unicode form of PDText strings.
 
void ASTextSetEncoded(ASText str, const char* text, ASHostEncoding encoding)
Replaces the contents of an existing ASText object with a NULL-terminated multi-byte string in the specified host encoding.
 
Sets the language codes associated with a piece of text.
 
void ASTextSetPDText(ASText str, const char* text)
Alters an existing string from some PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate NULL termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.
 
void ASTextSetScriptText(ASText str, const char* text, ASScript script)
Alters an existing string from a NULL-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().
 
void ASTextSetSizedEncoded(ASText str, const char* text, ASTArraySize len, ASHostEncoding encoding)
Alters an existing string from a multi-byte string in the specified host encoding and of the specified length. This text does not need to be NULL-terminated, and no NULL (zero) bytes should appear in the characters passed in.
 
void ASTextSetSizedPDText(ASText str, const char* text, ASTArraySize length)
Replaces the contents of an existing ASText object with PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the length parameter indicates the number of bytes in the string. The string should not be NULL-terminated and must not contain any NULL characters. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.
 
void ASTextSetSizedScriptText(ASText str, const char* text, ASTArraySize len, ASScript script)
Replaces the contents of an existing ASText object with the specified multi-byte string of the specified script. This is a wrapper around ASTextFromSizedEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().
 
void ASTextSetSizedUnicode(ASText str, const ASUTF16Val* ucsValue, ASUnicodeFormat format, ASTArraySize len)
Replaces the contents of an existing ASText object with the specified Unicode string. This string is not expected to have 0xFE 0xFF prepended or embedded country/language identifiers.
 
void ASTextSetUnicode(ASText str, const ASUTF16Val* ucsValue, ASUnicodeFormat format)
Alters an existing string from a NULL-terminated Unicode string. This string is not expected to have 0xFE 0xFF prepended or embedded country/language identifiers.
Defines Detail
ASTextEqual 
Product availability: All
Platform availability: All

Syntax

#define ASTextEqual (ASTextCmp((a), (b)) == 0)

File: ASExtraCalls.h
Line: 110

Typedefs Detail
ASConstText 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_ASTextRec* ASConstText;

An opaque object holding constant encoded text.

See Also


File: ASExpT.h
Line: 1457
ASCountryCode 
Product availability: All
Platform availability: All

Syntax

typedef ASUns16 ASCountryCode;

File: ASExtraExpT.h
Line: 41
ASLanguageCode 
Product availability: All
Platform availability: All

Syntax

typedef ASUns16 ASLanguageCode;

File: ASExtraExpT.h
Line: 43
ASText 
Product availability: All
Platform availability: All

Syntax

typedef struct _t_ASTextRec* ASText;

An opaque object holding encoded text.

An ASText object represents a Unicode string. ASText objects can also be used to convert between Unicode and various platform-specific text encodings, as well as conversions between various Unicode formats such as UTF-16 or UTF-8. Since it is common for a Unicode string to be repeatedly converted to or from the same platform-specific text encoding, ASText objects are optimized for this operation. For example, they can cache both the Unicode and platform-specific text strings.

There are several ways of creating an ASText object depending on the type and format of the original text data. The following terminology is used throughout this API to describe the various text formats:

Text Format

Description

Encoded

A multi-byte string terminated with a single 0 character and coupled with a specific host encoding indicator. On Mac OS, the text encoding is specified using a script code. On Windows, the text encoding is specified using a CHARSET code. On UNIX the only valid host encoding indicator is 0, which specifies text in the platform's default Roman encoding. On all platforms, Asian text is typically specified using multi-byte strings.

ScriptText

A multi-byte string terminated with a single 0 character and coupled with an ASScript code. This is merely another way of specifying the Encoded case; the ASScript code is converted to a host encoding using ASScriptToHostEncoding().

Unicode

Text specified using UTF-16 or UTF-8. In the UTF-16 case, the bytes can be in either big-endian format or the endian-ness that matches the platform, and are always terminated with a single ASUns16 0 value. In the UTF-8 case, the text is always terminated with a trailing 0 byte. Unicode usage in this case is straight Unicode without the 0xFE 0xFF prefix or language and country codes that can be encoded inside a PDF document.

PDText

A string of text pulled out of a PDF document. This will either be a big-endian Unicode string pre-appended with the bytes 0xFE 0xFF, or a string in PDFDocEncoding. In this case, the Unicode string may have embedded language and country identifiers. ASText objects strip language and country information out of the PDText string and track them separately. See below for more details.

ASText objects can also be used to accomplish encoding and format conversions; you can request a string in any of the formats specified above. In all cases the ASText code attempts to preserve all characters. For example, if you attempt to concatenate two strings in separate host encodings, the implementation may convert both to Unicode and perform the concatenation in Unicode space.

When creating a new ASText object or putting new data into an existing object, the implementation will always copy the supplied data into the ASText object. The original data is yours to do with as you wish (and release if necessary).

The size of ASText data is always specified in bytes. For example, the len argument to ASTextFromSizedUnicode() specifies the number of bytes in the string, not the number of Unicode characters.

Host encoding and Unicode strings are always terminated with a NULL character (which consists of one NULL byte for host encoded strings and two NULL bytes for Unicode strings). You cannot create a string with an embedded NULL character, even using the calls which take an explicit length parameter.

The Getxxx calls return pointers to data held by the ASText object. You cannot free or manipulate this data directly. The GetxxxCopy calls return data you can manipulate and that you are responsible for freeing.

An ASText object can have language and country codes associated with it. A language code is a 2-character ISO 639 language code. A country code is a 2- character ISO 3166 country code. In both cases the 2-character codes are packed into an ASUns16 value: the first character is packed in bits 8-15, and the second character is packed in bits 0-7. These language and country codes can be encoded into a UTF-16 variant of PDText encoding using an escape sequence; see Section 3.8 in the PDF Reference. The ASText calls will automatically parse the language and country codes embedded inside a UTF-16 PDText object, and will also author appropriate escape sequences to embed the language and country codes (if present) when generating a UTF-16 PDText object.

See Also


File: ASExpT.h
Line: 1451
ASUniChar 
Product availability: All
Platform availability: All

Syntax

typedef ASUTF16Val ASUniChar;

File: ASExtraExpT.h
Line: 39
ASUnicodeChar 
Product availability: All
Platform availability: All

Syntax

typedef ASUns32 ASUnicodeChar;

An ASUnicodeChar is large enough to hold any Unicode character (at least 21 bits wide).


File: ASExpT.h
Line: 3878
ASUTF16Val 
Product availability: All
Platform availability: All

Syntax

typedef ASUns16 ASUTF16Val;

Holds a single 16-bit value from a UTF-16 encoded Unicode string. It is typically used to point to the beginning of an UTF-16 string. For example: ASUTF16Val *utf16String = ...

This data type is not large enough to hold any arbitrary Unicode character. Use ASUnicodeChar to pass individual Unicode characters.

See Also


File: ASExpT.h
Line: 3891
ASUTF32Val 
Product availability: All
Platform availability: All

Syntax

typedef ASUns32 ASUTF32Val;

File: ASExpT.h
Line: 3879
ASUTF8Val 
Product availability: All
Platform availability: All

Syntax

typedef ASUns8 ASUTF8Val;

An ASUTF8Val holds a single 8-bit value from a UTF-8 encoded Unicode string.


File: ASExpT.h
Line: 3896

Enumeration Detail
ASTextFilterType
Product availability: All
Platform availability: All

Syntax

See Also


File: ASExtraExpT.h
Line: 48

Elements
kASTextFilterIdentity  

Does nothing.

 
kASTextFilterLineEndings  

Normalizes line endings (equivalent to ASTextNormalizeEndOfLine()).

 
kASTextFilterUpperCase  

Makes all text upper case. DEPRECATED: Case is not a reliably localizable concept. Do not use this.

 
kASTextFilterLowerCase  

Makes all text lower case. DEPRECATED: Case is not a reliably localizable concept. Do not use this.

 
kASTextFilterXXXDebug  

Changes any ASText to "XXX" (for debugging).

 
kASTextFilterUpperCaseDebug  

Makes all text except scanf format strings upper case.

 
kASTextFilterLowerCaseDebug  

Makes all text except scanf format strings lower case.

 
kASTextFilterRemoveAmpersands  

Removes stand-alone ampersands, and turns && into &

 
kASTextFilterNormalizeFullWidthASCIIVariants  

Changes any full width ASCII variants to their lower-ASCII version.

 
kASTextRemoveLineEndings  

Removes line endings and replaces them with spaces.

 
kASTextFilterRsvd1  

Reserved. Do not use.

 
kASTextFilterUnknown  

An invalid filter type.

ASUnicodeFormat 
Product availability: All
Platform availability: All

Syntax

enum ASUnicodeFormat {
 kUTF16BigEndian,
 
 kUTF16HostEndian,
 
 kUTF8,
 
 kUTF32BigEndian,
 
 kUTF32HostEndian
}

See Also


File: ASExpT.h
Line: 3849

Elements
kUTF16BigEndian  

Always returns the bytes in big-endian order.

 
kUTF16HostEndian  

Returns the bytes in the host's native endian order, whatever is natural for an ASUns16.

 
kUTF8  

Endian neutral.

 
kUTF32BigEndian  

Always returns the bytes in big-endian order.

 
kUTF32HostEndian  

Returns the bytes in the host's native endian order, whatever is natural for an ASUns32.


Callbacks Detail
ASTextEvalProc 
Product availability: All
Platform availability: All

Syntax

ASText (*ASTextEvalProc)(ASCab params)

File: ASExtraExpT.h
Line: 404

Method Detail
ASTextCaseSensitiveCmp()
Product availability: All
Platform availability: All

Syntax

ASInt32 ASTextCaseSensitiveCmp(ASConstText str1, ASConstText str2)

Compares two ASConstText objects, ignoring language and country information. The comparison is case-sensitive.

Various exceptions may be raised.

Parameters

str1 — 

First text object.

 
str2 — 

Second text object.

Returns

Returns a negative number if str1 < str2, a positive number if str1 > str2, and 0 if they are equal.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h
Line: 2345
ASTextCat() 
Product availability: All
Platform availability: All

Syntax

void ASTextCat(ASText to, ASConstText from)

Concatenates the from text to the end of the to text, altering to but not from. It does not change the language or country of to unless it has no language or country, in which case it acquires the language and country of from.

Parameters

to — 

IN/OUT The encoded text to which from is appended.

 
from — 

IN/OUT The encoded text to be appended to to.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 561
ASTextCatMany() 
Product availability: All
Platform availability: All

Syntax

void ASTextCatMany(ASText to, ... )

Concatenates a series of ASText objects to the end of the to object. Be sure to provide NULL as the last argument to the call.

Various exceptions may be raised.

Parameters

to — 

IN/OUT The ASText object to which the subsequent ASText arguments are concatenated.

 

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 574
ASTextCmp() 
Product availability: All
Platform availability: All

Syntax

ASInt32 ASTextCmp(ASConstText str1, ASConstText str2)

Compares two ASText objects. This routine can be used to sort text objects using the default collating rules of the underlying operating system before presenting them to the user. The comparison is case-sensitive. The results are suitable for displaying a sorted list of strings to the user in his chosen language and according to the rules of the platform on which the application is running. The results can vary based on the platform and user locale. If you want to compare strings in a way that is consistent across locales and platforms (but not suitable for displaying sorted strings to a user) see ASTextCaseSensitiveCmp().

Various exceptions may be raised.

Parameters

str1 — 

The first text object.

 
str2 — 

The second text object.

Returns

A negative number if str1 < str2, a positive number if str1 > str2, and 0 if they are equal.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 616
ASTextCopy() 
Product availability: All
Platform availability: All

Syntax

void ASTextCopy(ASText to, ASConstText from)

Copies the text in from to to, along with the country and language.

Parameters

to — 

IN/OUT The destination text object.

 
from — 

IN/OUT The source text object.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 583
ASTextDestroy() 
Product availability: All
Platform availability: All

Syntax

void ASTextDestroy(ASText str)

Frees all memory associated with the text object.

Parameters

str — 

IN/OUT A text object.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 216
ASTextDup() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextDup(ASConstText str)

Creates a new ASText object that contains the same text/country/language as the one passed in.

Parameters

str — 

A text object.

Returns

An ASText object.

Exceptions

genErrBadParm is raised if str is NULL.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 593
ASTextEval() 
Product availability: All
Platform availability: All

Syntax

void ASTextEval(ASText theText, ASCab params)

Replaces percent-quoted expressions in the text object with the result of their evaluation, using key/value pairs in the ASCab. For example, for a text value containing the string "%keyone%%keytwo%", the value is replaced with the concatenation of the values of the keys keyone and keytwo in the ASCab passed in.

Parameters

theText — 

A text object containing percent-quoted expressions to replace.

 
params — 

The ASCab containing the key/value pairs to use for text replacement.

Exceptions

genErrBadParm if theText is NULL.

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h
Line: 2158
ASTextFilter() 
Product availability: All
Platform availability: All

Syntax

void ASTextFilter(ASText text, ASTextFilterType filter)

Runs the specified filter on a text object, modifying the text as specified.

Parameters

text — 

A text object modified by the method.

 
filter — 

The filter to run on the text object.

Exceptions

genErrBadParm if text is NULL or if an invalid filter is specified.

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h
Line: 2382
ASTextFromEncoded() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromEncoded(const char* str, ASHostEncoding encoding)

Creates a new text object from a NULL-terminated multi-byte string in the specified host encoding.

Parameters

str — 

The input string.

 
encoding — 

The host encoding.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 136
ASTextFromInt32() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromInt32(ASInt32 num)

Creates a new string from an ASInt32 by converting the number to its decimal representation without punctuation or leading zeros.

Parameters

num — 

A number of type ASInt32.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 1594
ASTextFromPDText() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromPDText(const char* str)

Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate NULL termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.

Parameters

str — 

A string.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 192
ASTextFromScriptText() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromScriptText(const char* str, ASScript script)

Creates a new string from a NULL-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().

Parameters

str — 

A string.

 
script — 

The specified script.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 162
ASTextFromSizedEncoded() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromSizedEncoded(const char* str, ASTArraySize len, ASHostEncoding encoding)

Creates a new text object from a multi-byte string of the specified length in the specified host encoding.

Parameters

str — 

A string.

 
len — 

The length in bytes.

 
encoding — 

The specified host encoding.

Returns

An ASText object.

See Also

Exceptions

genErrBadParm is raised if len < 0.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 149
ASTextFromSizedPDText() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromSizedPDText(const char* str, ASTArraySize length)

Creates a new string from some PDF text taken out of a PDF file. This is either a UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string. The length parameter specifies the size, in bytes, of the string. The string must not contain embedded NULL characters.

Parameters

str — 

A string.

 
length — 

The length in bytes.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 209
ASTextFromSizedScriptText() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromSizedScriptText(const char* str, ASTArraySize len, ASScript script)

Creates a new text object from the specified multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().

Parameters

str — 

A string.

 
len — 

The length in bytes.

 
script — 

The specified script.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 176
ASTextFromSizedUnicode() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromSizedUnicode(const ASUTF16Val* ucs, ASUnicodeFormat format, ASTArraySize len)

Creates a new text object from the specified Unicode string. This string is not expected to have 0xFE 0xFF prepended, or country/language identifiers.

The string cannot contain an embedded NULL character.

Parameters

ucs — 

The Unicode string

 
format — 

The Unicode format of ucs.

 
len — 

The length of ucs in bytes.

Returns

An ASText object.

See Also

Exceptions

genErrBadParm is raised if len < 0.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 125
ASTextFromUnicode() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromUnicode(const ASUTF16Val* ucs, ASUnicodeFormat format)

Creates a new string from a NULL-terminated Unicode string. This string is not expected to have 0xFE 0xFF prepended, or country/language identifiers.

Parameters

ucs — 

A Unicode string.

 
format — 

The Unicode format used by ucs.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 108
ASTextFromUns32() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextFromUns32(ASUns32 num)

Creates a new string from an ASUns32 by converting it to a decimal representation without punctuation or leading zeros.

Parameters

num — 

IN/OUT A value of type ASUns32.

Returns

An ASText object.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 1605
ASTextGetBestEncoding() 
Product availability: All
Platform availability: All

Syntax

ASHostEncoding ASTextGetBestEncoding(ASConstText str, ASHostEncoding preferredEncoding)

Returns the best host encoding for representing the text. The best host encoding is the one that is least likely to lose characters during the conversion from Unicode to host. If the string can be represented accurately in multiple encodings (for example, it is low-ASCII text that can be correctly represented in any host encoding), ASTextGetBestEncoding() returns the preferred encoding based on the preferredEncoding parameter.

Various exceptions may be raised.

Parameters

str — 

An ASText string.

 
preferredEncoding — 

The preferred encoding. There is no default.

Returns

The text encoding.


Example
How to use examples
// If you prefer to use the application's language encoding: ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, AVAppGetLanguageEncoding()); // If you prefer to use the operating system encoding: ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, (ASHostEncoding)PDGetHostEncoding()); // If you want to favor Roman encodings: ASHostEncoding hostRoman = ASScriptToHostEncoding(kASRomanScript); ASHostEncoding bestEncoding = ASTextGetBestEncoding(text, hostRoman);

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 494
ASTextGetBestScript() 
Product availability: All
Platform availability: All

Syntax

ASScript ASTextGetBestScript(ASConstText str, ASScript preferredScript)

Returns the best host script for representing the text. The functionality is similar to ASTextGetBestEncoding(), with resulting host encoding converted to a script code using ASScriptFromHostEncoding().

Parameters

str — 

IN/OUT An ASText string.

 
preferredScript — 

IN/OUT The preferred host script. There is no default.

Returns

The best host script.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 508
ASTextGetCountry() 
Product availability: All
Platform availability: All

Syntax

ASCountryCode ASTextGetCountry(ASConstText text)

Retrieves the country associated with an ASText object.

Parameters

text — 

IN/OUT An ASText object.

Returns

The country code.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 518
ASTextGetEncoded() 
Product availability: All
Platform availability: All

Syntax

const char* ASTextGetEncoded(ASConstText str, ASHostEncoding encoding)

Returns a NULL-terminated string in the given encoding. The memory to which this string points is owned by the ASText object and may not be valid after additional operations are performed on the object.

Various exceptions may be raised.

Parameters

str — 

IN/OUT An ASText object.

 
encoding — 

IN/OUT The specified host encoding.

Returns

A pointer to a NULL-terminated string corresponding to the text in str.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 390
ASTextGetEncodedCopy() 
Product availability: All
Platform availability: All

Syntax

char* ASTextGetEncodedCopy(ASConstText str, ASHostEncoding encoding)

Returns a copy of a string in a specified encoding.

Parameters

str — 

An ASText object.

 
encoding — 

The specified encoding.

Returns

A copy of the text in str. The client owns the resulting information and is responsible for freeing it using ASfree().

See Also

Exceptions

genErrNoMemory is raised if memory could not be allocated for the copy.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 404
ASTextGetLanguage() 
Product availability: All
Platform availability: All

Syntax

ASLanguageCode ASTextGetLanguage(ASConstText text)

Retrieves the language code associated with an ASText object.

Parameters

text — 

An ASText object.

Returns

The language code.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 540
ASTextGetPDTextCopy() 
Product availability: All
Platform availability: All

Syntax

char* ASTextGetPDTextCopy(ASConstText str, ASTArraySize* len)

Returns the text in a form suitable for storage in a PDF file. If the text can be represented using PDFDocEncoding, it is; otherwise it is represented in big-endian UTF-16 format with 0xFE 0xFF prepended to the front and any country/language codes embedded in an escape sequence right after 0xFE 0xFF.

You can determine if the string is Unicode by inspecting the first two bytes. The Unicode case is used if the string has a language and country code set. The resulting string is NULL-terminated as appropriate. That is, one NULL byte is used for PDFDocEncoding, two are used for UTF-16.

Various exceptions may be raised.

Parameters

str — 

A string.

 
len — 

The length in bytes of the resulting string, not counting the NULL bytes at the end.

Returns

A string copy. The client owns the resulting information and is responsible for freeing it with ASfree().

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 463
ASTextGetScriptText() 
Product availability: All
Platform availability: All

Syntax

const char* ASTextGetScriptText(ASConstText str, ASScript script)

Converts the Unicode string in the ASText object to the appropriate script, and returns a pointer to the converted text. The memory to which it points is owned by the ASText object and must not be altered or destroyed by the client. The memory may also become invalid after subsequent operations are applied to the ASText object.

Various exceptions may be raised.

Parameters

str — 

IN/OUT A string.

 
script — 

IN/OUT The writing script.

Returns

A string.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 422
ASTextGetScriptTextCopy() 
Product availability: All
Platform availability: All

Syntax

char* ASTextGetScriptTextCopy(ASConstText str, ASScript script)

Converts the Unicode string in the ASText object to the appropriate script and returns a pointer to the converted text. The memory to which it points is owned by the client, which is responsible for freeing it using ASfree().

Parameters

str — 

A string.

 
script — 

A writing script.

Returns

A string copy. The client owns the resulting information.

See Also

Exceptions

genErrNoMemory is raised if memory could not be allocated for the copy.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 439
ASTextGetUnicode() 
Product availability: All
Platform availability: All

Syntax

ASUTF16Val ASTextGetUnicode(ASConstText str)

Returns a pointer to a string in kUTF16HostEndian format (see ASUnicodeFormat). The memory to which this string points is owned by the ASText object, and may not be valid after additional operations are performed on the object.

The Unicode text returned will not have 0xFE 0xFF prepended or any language or country codes.

Parameters

str — 

A string.

Returns

See above.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 353
ASTextGetUnicodeCopy() 
Product availability: All
Platform availability: All

Syntax

ASUTF16Val ASTextGetUnicodeCopy(ASConstText str, ASUnicodeFormat format)

Returns a pointer to a NULL-terminated string in the specified Unicode format. The memory to which this string points is owned by the client, which can modify it at will and is responsible for destroying it using ASfree.

The Unicode text returned will not have 0xFE 0xFF prepended or any language or country codes.

Parameters

str — 

A string.

 
format — 

The Unicode format.

Returns

A string copy. The client owns the resulting information.

See Also

Exceptions

genErrNoMemory is raised if memory could not be allocated for the copy.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 373
ASTextIsEmpty() 
Product availability: All
Platform availability: All

Syntax

ASBool ASTextIsEmpty(ASConstText str)

Used to determine whether the ASText object contains no text. For example, it determines if retrieving Unicode text would yield a 0-length string.

Parameters

str — 

A string.

Returns

Returns true if the ASText object contains no text.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 1571
ASTextMakeEmpty() 
Product availability: All
Platform availability: All

Syntax

void ASTextMakeEmpty(ASText str)

Removes the contents of an ASText (turns it into an empty string).

Parameters

str

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 1612
ASTextMakeEmptyClear() 
Product availability: All
Platform availability: All

Syntax

void ASTextMakeEmptyClear(ASText str)

Removes the contents of an ASText object (converts it into an empty string). It clears the released storage (for security strings).

Parameters

str

Since

PI_ASEXTRA_VERSION >= 0x00090000

File: ASExtraProcs.h
Line: 2458
ASTextNew() 
Product availability: All
Platform availability: All

Syntax

ASText ASTextNew()

Creates a new text object containing no text.

Returns

An ASText object.

Exceptions

genErrNoMemory

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 96
ASTextNormalizeEndOfLine() 
Product availability: All
Platform availability: All

Syntax

void ASTextNormalizeEndOfLine(ASText text)

Replaces all end-of-line characters within the ASText object with the correct end-of-line character for the current platform. For example, on Windows, \r and \n are replaced with \r\n.

Parameters

text — 

An object of type ASText.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 1582
ASTextReplace() 
Product availability: All
Platform availability: All

Syntax

void ASTextReplace(ASText src, ASConstText toReplace, ASConstText replacement)

Replaces all occurrences of toReplace in src with the text specified in replacement. This uses an ASText string to indicate the toReplace string; ASTextReplaceASCII() uses a low ASCII Roman string to indicate the text to replace.

Various exceptions may be raised.

Parameters

src — 

Source text.

 
toReplace — 

Text in source text to replace.

 
replacement — 

Text used in replacement.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 633
ASTextReplaceASCII() 
Product availability: All
Platform availability: All

Syntax

void ASTextReplaceASCII(ASText src, const char* toReplace, ASConstText replacement)

Replaces all occurrences of toReplace in src with the text specified in replacement. ASTextReplace() uses an ASText string to indicate the toReplace string; this uses a low-ASCII Roman string to indicate the text to replace.

This call is intended for formatting strings for the user interface. For example, it can be used for replacing a known sequence such as '1' with other text. Be sure to use only low ASCII characters, which are safe on all platforms. Avoid using backslash and currency symbols.

Various exceptions may be raised.

Parameters

src — 

The ASText object containing the text.

 
toReplace — 

The text to replace.

 
replacement — 

The replacement text.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 656
ASTextReplaceBadChars() 
Product availability: All
Platform availability: All

Syntax

void ASTextReplaceBadChars(ASText str, const char* pszBadCharList, char replaceChar)

Replaces all occurrences of characters contained in the list pszBadCharList in the text with the specified replacement character.

Various exceptions may be raised.

Parameters

str — 

The text in which to replace characters.

 
pszBadCharList — 

A list of characters to replace, in sorted order with no duplicates.

 
replaceChar — 

The character with which to replace any character appearing in the list.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00060000

File: ASExtraProcs.h
Line: 1631
ASTextSetCountry() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetCountry(ASText text, ASCountryCode country)

Sets the language codes associated with a piece of text. ASText objects can have country and language codes associated with them. These can be explicitly set or parsed from the Unicode form of PDText strings.

Parameters

text — 

IN/OUT An ASText object.

 
country — 

IN/OUT Country code.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 531
ASTextSetEncoded() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetEncoded(ASText str, const char* text, ASHostEncoding encoding)

Replaces the contents of an existing ASText object with a NULL-terminated multi-byte string in the specified host encoding.

Parameters

str — 

IN/OUT An ASText object to hold the string.

 
text — 

IN/OUT A pointer to the text string.

 
encoding — 

IN/OUT The type of encoding.

See Also

Exceptions

genErrBadParm is raised if text is NULL.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 259
ASTextSetLanguage() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetLanguage(ASText text, ASLanguageCode language)

Sets the language codes associated with a piece of text.

Parameters

text — 

IN/OUT An ASText object.

 
language — 

IN/OUT The language code.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 550
ASTextSetPDText() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetPDText(ASText str, const char* text)

Alters an existing string from some PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the string is expected to have the appropriate NULL termination. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.

Parameters

str — 

A string.

 
text — 

A text string.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 318
ASTextSetScriptText() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetScriptText(ASText str, const char* text, ASScript script)

Alters an existing string from a NULL-terminated multi-byte string of the specified script. This is a wrapper around ASTextFromEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().

Parameters

str — 

IN/OUT A string.

 
text — 

IN/OUT A pointer to the text string.

 
script — 

IN/OUT The writing script.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 287
ASTextSetSizedEncoded() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetSizedEncoded(ASText str, const char* text, ASTArraySize len, ASHostEncoding encoding)

Alters an existing string from a multi-byte string in the specified host encoding and of the specified length. This text does not need to be NULL-terminated, and no NULL (zero) bytes should appear in the characters passed in.

Parameters

str — 

IN/OUT A string.

 
text — 

IN/OUT A pointer to the text string.

 
len — 

IN/OUT The length of the text string.

 
encoding — 

IN/OUT The host encoding type.

See Also

Exceptions

genErrBadParm is raised if text is NULL.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 274
ASTextSetSizedPDText() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetSizedPDText(ASText str, const char* text, ASTArraySize length)

Replaces the contents of an existing ASText object with PDF text taken out of a PDF file. This is either a big-endian UTF-16 string with the 0xFEFF prepended to the front or a PDFDocEncoding string. In either case the length parameter indicates the number of bytes in the string. The string should not be NULL-terminated and must not contain any NULL characters. If the PDText is in UTF-16, it may have embedded language and country information; this will cause the ASText object to have its language and country codes set to the values found in the string.

Parameters

str — 

A string.

 
text — 

A pointer to a text string.

 
length — 

The length of the text string.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 337
ASTextSetSizedScriptText() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetSizedScriptText(ASText str, const char* text, ASTArraySize len, ASScript script)

Replaces the contents of an existing ASText object with the specified multi-byte string of the specified script. This is a wrapper around ASTextFromSizedEncoded(); the script is converted to a host encoding using ASScriptToHostEncoding().

Parameters

str — 

IN/OUT A string.

 
text — 

IN/OUT A pointer to the text string.

 
len — 

IN/OUT The length of the text string.

 
script — 

IN/OUT The writing script.

Exceptions

genErrBadParm is raised if text is NULL.

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 302
ASTextSetSizedUnicode() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetSizedUnicode(ASText str, const ASUTF16Val* ucsValue, ASUnicodeFormat format, ASTArraySize len)

Replaces the contents of an existing ASText object with the specified Unicode string. This string is not expected to have 0xFE 0xFF prepended or embedded country/language identifiers.

The string cannot contain a NULL character.

Parameters

str — 

(Filled by the method) A string.

 
ucsValue — 

A Unicode string.

 
format — 

The Unicode format.

 
len — 

The length of the string in bytes.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 246
ASTextSetUnicode() 
Product availability: All
Platform availability: All

Syntax

void ASTextSetUnicode(ASText str, const ASUTF16Val* ucsValue, ASUnicodeFormat format)

Alters an existing string from a NULL-terminated Unicode string. This string is not expected to have 0xFE 0xFF prepended or embedded country/language identifiers.

Parameters

str — 

(Filled by the method) A string.

 
ucsValue — 

A Unicode string.

 
format — 

The Unicode format.

See Also

Since

PI_ASEXTRA_VERSION >= 0x00050000

File: ASExtraProcs.h
Line: 229