Note: Use CosObjEnum() to list all key-value pairs in a dictionary.
CosObj CosDictGet(CosObj dict, ASAtom key); dict | The dictionary or stream from which a value is obtained.
|
key | The key whose value is obtained, repesented as an ASAtom. See the description of "Dictionary Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.7, page 18. You can find this document on the web store of the International Standards Organization (ISO).
Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (for example, Note that strings can be used directly as keys, by calling
Key Names: Even though key names in a PDF file are written with a leading slash (e.g.,
Cos name objects can also be used as keys, by calling |
CosDictGet(). CosObj CosDictGetKey(CosObj dict, CosObj key); dict | The dictionary or stream from which a value is obtained.
|
key | The key whose value is obtained, represented as a Cos name object.
|
key is not present, it returns a NULL Cos object. CosDictGet(). CosObj CosDictGetKeyString(CosObj dict, const char *key); dict | The dictionary or stream from which a value is obtained.
|
key | The key whose value is obtained, represented as a string.
|
NULL Cos object. CosDictSetWeakReference(). ASBool CosDictIsWeakReference(CosObj dict, const char *key); dict | A dictionary.
|
key | The name of a key.
|
isWeak parameter in the most recent call to CosDictSetWeakReference() with these parameters, or false if there has been no such call.
Tests whether a specific key is found in the specified dictionary. Calling this method is equivalent to checking if the value returned from CosDictGet() is a NULL Cos object.
If it is called with a stream object instead of a dictionary object, this method tests whether the specified key is found in the stream's attributes dictionary.
ASBool CosDictKnown(CosObj dict, ASAtom key); dict | The dictionary or stream in which to look for
key. |
key | The key to find. See the description of "Dictionary Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.7, page 18. You can find this document on the web store of the International Standards Organization (ISO).
Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (see Note that strings can be used directly as keys, by calling
Cos name objects can also be used as keys, by calling |
CosDictGetKey() is a NULL Cos object. For more details, see CosDictKnown(). ASBool CosDictKnownKey(CosObj dict, CosObj key); dict | The dictionary or stream in which to look for
key. |
key | The key to find, represented as a Cos name object.
|
CosDictGetKeyString() is a NULL Cos object. For more details, see CosDictKnown(). ASBool CosDictKnownKeyString(CosObj dict, const char *key); dict | The dictionary or stream in which to look for key.
|
key | The key to find, represented as a string.
|
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. Sets the PDDocNeedsSave flag (see PDDocSetFlags) of the dict object's CosDoc if dict is indirect or is a direct object with an indirect composite object at the root of its container chain.
This method can also be used with a stream object. In that case, the key-value pair is added to the stream's attributes dictionary.
It is not safe to call CosDictPut() during a call to CosObjEnum() on that same dictionary (for example, from within the callback procedure).
An exception is raised if val is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict and val belong to different documents.
Note: A dictionary entry whose value is NULL is equivalent to an absent entry; using CosDictPut() to put a NULL value in a dictionary has the same effect as calling CosDictRemove() to remove it from the dictionary.
void CosDictPut(CosObj dict, ASAtom key, CosObj val); dict | The dictionary or stream in which a value is set.
|
key | The key whose value is set, represented as an You can find this document on the web store of the International Standards Organization (ISO).
Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (see Note that strings can be used directly as keys, by calling
Cos name objects can also be used as keys, by calling |
val | The value to set.
|
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see CosDictPut().
It is not safe to call CosDictPutKey() during a call to CosObjEnum() on that same dictionary (for example, from within the callback procedure)
An exception is raised if val is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict and val belong to different documents.
void CosDictPutKey(CosObj dict, CosObj key, CosObj val); dict | The dictionary or stream in which a value is set.
|
key | The key whose value is set, represented as a Cos name object.
|
val | The value to set.
|
Sets the value of a dictionary key, adding the key to the dictionary if it is not already present. For more details, see CosDictPut().
It is not safe to call CosDictPutKey() during a call to CosObjEnum() on that same dictionary (for example, from within the callback procedure).
An exception is raised if val is a direct non-scalar object that is already contained in another dictionary, array, or stream, or if dict and val belong to different documents.
void CosDictPutKeyString(CosObj dict, const char *key, CosObj val); dict | The dictionary or stream in which a value is set.
|
key | The key whose value is set, represented as a string.
|
val | The value to set.
|
Removes a key-value pair from a dictionary. Sets the PDDocNeedsSave flag (see PDDocSetFlags) of the dict object's CosDoc if the dictionary is indirect or has an indirect composite object at the root of its container chain.
If it is called with a stream object instead of a dictionary object, this method removes the value of the specified key from the stream's attributes dictionary.
It is not safe to call CosDictRemove() during a call to CosObjEnum() on that same dictionary (for example, from within the callback procedure).
If the key is not present in the dictionary, CosDictRemove() has no effect.
void CosDictRemove(CosObj dict, ASAtom key); dict | The dictionary from which the key-value pair is removed.
|
key | The key to remove, represented as an ASAtom. See the description of "Dictionary Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.7, page 18. You can find this document on the web store of the International Standards Organization (ISO).
Here you will find the names of keys in dictionary objects that are part of standard PDF, such as annotations or page objects (see Note that strings can be used directly as keys, by calling CosDictRemoveString() (for example,
Cos name objects can also be used as keys, by calling |
CosDictRemove(). void CosDictRemoveKey(CosObj dict, CosObj key); dict | The dictionary from which the key-value pair is removed.
|
key | The key to remove, represented as a Cos name object.
|
CosDictRemove(). void CosDictRemoveKeyString(CosObj dict, const char *key); dict | The dictionary from which the key-value pair is removed.
|
key | The key to remove, represented as a string.
|
Weak and strong references.
When a Cos document is saved in full-save mode, objects that are not accessible from the root of the document are destroyed. This process uses a mark-and-sweep garbage collector: the root is marked, and then every object to which it refers is marked, and so on. At the end of this marking phase, objects that are not marked are destroyed.
A so-called weak reference changes this policy: during the marking phase, a reference that has been declared to be weak will not be marked. For example, when a dictionary is marked, all its keys and values are normally also marked. But if a certain key has been set as a weak reference, then the corresponding value will not be marked. Consequently, if there are no other references to that value, it will be destroyed.
A so-called strong reference also changes this policy, but in the opposite direction. An object for which there is a strong reference will be marked (and therefore will not be garbage-collected), even if there is no path to the object from the root of the document, and even if a weak reference exists for it.
CosDictSetWeakReference() establishes or removes a weak reference from a dictionary.
void CosDictSetWeakReference(CosObj dict, const char *key, ASBool isWeak); dict | The dictionary containing the weak reference.
|
key | The name of a key in the dictionary.
|
isWeak | If It is not an error if there is no such value at the time of garbage collection or at the time of the call to this function.
If |
Creates a new dictionary.
For information on dictionary objects in standard PDF files, such as annotations or page objects, see the description of "Dictionary Objects" in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.7, page 18. You can find this document on the web store of the International Standards Organization (ISO).
CosObj CosNewDict(CosDoc dP, ASBool indirect, ASTArraySize nEntries); dP | The document in which the dictionary is used.
|
indirect | If
true, it creates the dictionary as an indirect Cos object, and sets the dP object's PDDocNeedsSave flag (see PDDocFlags). If false, it creates the dictionary as a direct object. |
nEntries | The number of entries in the dictionary. This value is only a hint; Cos dictionaries grow dynamically as needed.
|