| Layer | COS_Layer |
| Object | CosString |
A string is a sequences of characters, enclosed in parentheses. See Section 3.2.3 in the PDF Reference for details.
| Method | ||
|---|---|---|
|
Returns a newly allocated buffer containing a copy of the Cos object's name as a NULL-terminated string. Upon return, nBytes contains the number of bytes in the string.
CosCopyNameStringValue()
never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling
ASfree()
.
|
||
|
Returns a newly allocated buffer containing a copy of the Cos object's string value. Upon return, nBytes contains the number of bytes in the original Cos string.
CosCopyStringValue()
never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling
ASfree()
.
|
||
|
Creates and returns a new Cos string object.
|
||
|
ASBool CosStringGetHexFlag(CosObj cosObj)
Gets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
|
||
|
Sets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
|
||
|
Gets the value of a string Cos object, and the string's length.
|
||
|
Copies at most bufferSize bytes from the obj parameter's string value into buffer, and stores the actual length of the Cos string in *nBytes. If bufferSize is greater than the length of the Cos string, the remaining bytes in buffer have undefined values upon return.
|
||
| CosCopyNameStringValue | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
Returns a newly allocated buffer containing a copy of the Cos object's name as a NULL-terminated string. Upon return, nBytes contains the number of bytes in the string.
CosCopyNameStringValue()
never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling
ASfree()
.
Unlike Cos strings, the strings corresponding to Cos names are NULL-terminated.
This routine will avoid creating an ASAtom corresponding to the object's name and is generally more efficient than copying the value returned by ASAtomGetString(CosNameValue(obj)). (ASAtom objects consume global memory that is not deallocated.)
An out-of-memory exception is raised if insufficient memory is available.
Parameters
obj — | ||
nBytes — | OUT The length of the name of the Cos object, and therefore the length of the returned string. |
A copy of the Cos object's name, as a |
See Also
Since
| File: CosProcs.h |
| Line: 2152 |
| CosCopyStringValue | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
Returns a newly allocated buffer containing a copy of the Cos object's string value. Upon return, nBytes contains the number of bytes in the original Cos string.
CosCopyStringValue()
never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling
ASfree()
.
CosCopyStringValue()
allocates extra memory past the end of the string and writes zeros into these extra bytes to ensure that the string is NULL-terminated whether viewed as a UTF-16 (Unicode) string or as a C string (these bytes are not included in the number returned in nBytes). If the Cos string has 0 length, nBytes will be 0, and a pointer to newly allocated memory containing some zero bytes is returned (that is,
CosCopyStringValue()
still returns a NULL-terminated string but with zero length).
An out-of-memory exception is raised if insufficient memory is available. It can also raise any exception that CosStringValue() can raise.
Parameters
obj — | IN The Cos object whose string value is copied and returned. |
|
nBytes — | OUT (Filled by the method) The length of the original Cos string in bytes. It can be |
A copy of the Cos object's string value. |
See Also
Since
Note
NULL-terminated C string. Cos string objects are binary and can contain arbitrary byte sequences, including NULL characters. Standard C string handling functions may not work as expected. | File: CosProcs.h |
| Line: 1426 |
| CosNewString | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
CosObj CosNewString(CosDoc dP, ASBool indirect, const char* str, ASTArraySize nBytes)
Creates and returns a new Cos string object.
Parameters
dP — | The document in which the string is used. |
|
indirect — | If |
|
str — | The value that the new string will have. It is not a C string, since Cos strings can contain |
|
nBytes — |
The newly created string Cos object. |
See Also
Since
| File: CosProcs.h |
| Line: 237 |
| CosStringGetHexFlag | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
Gets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
Parameters
cosObj — | IN/OUT The |
The current value of the flag. |
See Also
Exceptions
Since
| File: CosProcs.h |
| Line: 1271 |
| CosStringSetHexFlag | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
Sets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
Parameters
cosObj — | The |
|
setHex — | The value to set for the flag. |
The value of |
See Also
Exceptions
Since
| File: CosProcs.h |
| Line: 1258 |
| CosStringValue | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
Gets the value of a string Cos object, and the string's length.
An exception is raised if the type of obj is not a CosString.
Parameters
obj — | ||
nBytes — | OUT (Filled by the method) The length of the string, in bytes. It must be a non- |
The value of |
See Also
Since
Note
CosStringValue()
is called again. It is recommended that you use
CosStringValueSafe()
or
CosCopyStringValue()
instead; these methods place the string into a user-allocated buffer.
str1 = CosStringValue(...);
str2 = CosStringValue(...);
In this case, the contents of str1 may be invalid by the time the second CosStringValue() call returns. NULL bytes. Standard C string-handling functions may not work as expected. | File: CosProcs.h |
| Line: 571 |
| CosStringValueSafe | () |
| Product availability: PDFL |
| Platform availability: Macintosh, Windows, UNIX |
char* CosStringValueSafe(CosObj obj, char* buffer, ASTArraySize bufferSize, ASTCount* nBytes)
Copies at most bufferSize bytes from the obj parameter's string value into buffer, and stores the actual length of the Cos string in *nBytes. If bufferSize is greater than the length of the Cos string, the remaining bytes in buffer have undefined values upon return.
A bad-parameter exception is raised if bufferSize is less than 0 or nBytes is NULL. It can also raise any exception that
CosStringValue()
can raise.
Parameters
obj — | The Cos object whose string value is copied. |
|
buffer — | The buffer into which the Cos string value is copied, or |
|
bufferSize — | The length of |
|
nBytes — | (Filled by the method) The length of the original Cos string in bytes (which may be more than |
A copy of the Cos string value or an exception. It will never return |
See Also
Since
Note
NULL-terminated C string. Cos string objects are binary data and can contain any arbitrary byte sequence, including embedded NULL characters. Standard C string handling functions may not work as expected. | File: CosProcs.h |
| Line: 1455 |