LayerCOS_Layer
ObjectCosString

A string is a sequences of characters, enclosed in parentheses. See Section 3.2.3 in the PDF Reference for details.



Method Summary
 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() .
 
char* CosCopyStringValue(CosObj obj, ASTCount* nBytes)
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() .
 
CosObj CosNewString(CosDoc dP, ASBool indirect, const char* str, ASTArraySize nBytes)
Creates and returns a new Cos string object.
 
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.
 
ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex)
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.
 
char* CosStringValue(CosObj obj, ASTCount* nBytes)
Gets the value of a string Cos object, and the string's length.
 
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.




Method Detail
CosCopyNameStringValue()
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

char* CosCopyNameStringValue(CosObj obj, ASTCount* nBytes)

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 — 

IN A Cos name object.

 
nBytes — 

OUT The length of the name of the Cos object, and therefore the length of the returned string. nBytes may be NULL if you do not care how many bytes are in the name.

Returns

A copy of the Cos object's name, as a NULL-terminated string.

See Also

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 2152
CosCopyStringValue() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

char* CosCopyStringValue(CosObj obj, ASTCount* nBytes)

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 NULL if you do not care how many bytes were in the original string.

Returns

A copy of the Cos object's string value.

See Also

Since

PI_COS_VERSION >= 0x00050000

Note

In general, the returned value is not a 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

Syntax

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 true, it creates the string as an indirect object, and sets the document (dP) object's PDDocNeedsSave flag (see PDDocFlags). If false, it creates the string as a direct object.

 
str — 

The value that the new string will have. It is not a C string, since Cos strings can contain NULL characters. The data in str is copied; that is, if str was dynamically allocated, it can be freed after this call.

 
nBytes — 

The length of str.

Returns

The newly created string Cos object.

See Also

Since

PI_COS_VERSION >= 0x00020000

Examples

go to source arrow CosObj rComp = CosNewString(cosDoc, false, (char*)rCompStr, sizeLUT);
go to source arrow CosObj gComp = CosNewString(cosDoc, false, (char*)gCompStr, sizeLUT);
go to source arrow CosObj bComp = CosNewString(cosDoc, false, (char*)bCompStr, sizeLUT);

more...

File: CosProcs.h
Line: 237
CosStringGetHexFlag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

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.

Parameters

cosObj — 

IN/OUT The CosString for which the hex flag is obtained.

Returns

The current value of the flag.

See Also

Exceptions

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h
Line: 1271
CosStringSetHexFlag() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex)

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 CosString for which the hex flag is set.

 
setHex — 

The value to set for the flag.

Returns

The value of setHex.

See Also

Exceptions

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h
Line: 1258
CosStringValue() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

char* CosStringValue(CosObj obj, ASTCount* nBytes)

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 — 

IN The object whose value is obtained.

 
nBytes — 

OUT (Filled by the method) The length of the string, in bytes. It must be a non-NULL pointer.

Returns

The value of obj.

See Also

Since

PI_COS_VERSION >= 0x00020000

Note

The pointer returned from this method is not guaranteed to remain valid if CosStringValue() is called again. It is recommended that you use CosStringValueSafe() or CosCopyStringValue() instead; these methods place the string into a user-allocated buffer.
The caller must immediately copy the returned string. The memory pointed to be the return value may become invalid if any memory-allocating calls are made. In particular, consider the sequence: str1 = CosStringValue(...); str2 = CosStringValue(...); In this case, the contents of str1 may be invalid by the time the second CosStringValue() call returns.
The returned value is not a C-style string. Cos string objects can contain NULL bytes. Standard C string-handling functions may not work as expected.

Examples

go to source arrow char *c = CosStringValue(coValue, &nCount);

File: CosProcs.h
Line: 571
CosStringValueSafe() 
Product availability: PDFL
Platform availability: Macintosh, Windows, UNIX

Syntax

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

 
bufferSize — 

The length of buffer or 0.

 
nBytes — 

(Filled by the method) The length of the original Cos string in bytes (which may be more than bufferSize). It must be a non-NULL pointer.

Returns

A copy of the Cos string value or an exception. It will never return NULL.

See Also

Since

PI_COS_VERSION >= 0x00050000

Note

In general, the returned value is not a 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