@typedef CFBinaryHeapCallBacks
Structure containing the callbacks for values of a CFBinaryHeap.
@field version The version number of the structure type being passed
in as a parameter to the CFBinaryHeap creation functions.
This structure is version 0.
@field retain The callback used to add a retain for the binary heap
on values as they are put into the binary heap.
This callback returns the value to use as the value in the
binary heap, which is usually the value parameter passed to
this callback, but may be a different value if a different
value should be added to the binary heap. The binary heap’s
allocator is passed as the first argument.
@field release The callback used to remove a retain previously added
for the binary heap from values as they are removed from
the binary heap. The binary heap’s allocator is passed as the
first argument.
@field copyDescription The callback used to create a descriptive
string representation of each value in the binary heap. This
is used by the CFCopyDescription() function.
@field compare The callback used to compare values in the binary heap for
equality in some operations.
@typedef CFDictionaryValueCallBacks
Structure containing the callbacks for values of a CFDictionary.
@field version The version number of the structure type being passed
in as a parameter to the CFDictionary creation functions.
This structure is version 0.
@field retain The callback used to add a retain for the dictionary
on values as they are put into the dictionary.
This callback returns the value to use as the value in the
dictionary, which is usually the value parameter passed to
this callback, but may be a different value if a different
value should be added to the dictionary. The dictionary’s
allocator is passed as the first argument.
@field release The callback used to remove a retain previously added
for the dictionary from values as they are removed from
the dictionary. The dictionary’s allocator is passed as the
first argument.
@field copyDescription The callback used to create a descriptive
string representation of each value in the dictionary. This
is used by the CFCopyDescription() function.
@field equal The callback used to compare values in the dictionary for
equality in some operations.
@typedef CFSetCallBacks
Structure containing the callbacks of a CFSet.
@field version The version number of the structure type being passed
in as a parameter to the CFSet creation functions. This
structure is version 0.
@field retain The callback used to add a retain for the set on
values as they are put into the set. This callback returns
the value to store in the set, which is usually the value
parameter passed to this callback, but may be a different
value if a different value should be stored in the set.
The set’s allocator is passed as the first argument.
@field release The callback used to remove a retain previously added
for the set from values as they are removed from the
set. The set’s allocator is passed as the first
argument.
@field copyDescription The callback used to create a descriptive
string representation of each value in the set. This is
used by the CFCopyDescription() function.
@field equal The callback used to compare values in the set for
equality for some operations.
@field hash The callback used to compare values in the set for
uniqueness for some operations.
@typedef CFTreeContext
Structure containing user-specified data and callbacks for a CFTree.
@field version The version number of the structure type being passed
in as a parameter to the CFTree creation function.
This structure is version 0.
@field info A C pointer to a user-specified block of data.
@field retain The callback used to add a retain for the info field.
If this parameter is not a pointer to a function of the correct
prototype, the behavior is undefined. The value may be NULL.
@field release The calllback used to remove a retain previously added
for the info field. If this parameter is not a pointer to a
function of the correct prototype, the behavior is undefined.
The value may be NULL.
@field copyDescription The callback used to provide a description of
the info field.
@struct JSAPIModuleLoader
@abstract The callbacks used to load and evaluate modules.
@field moduleLoaderResolve The callback used to resolve a module specifier.
@field moduleLoaderEvaluate The callback used to evaluate a module.
@field moduleLoaderFetch The callback used to fetch a module.
@struct JSClassDefinition
@abstract This structure contains properties and callbacks that define a type of object. All fields other than the version field are optional. Any pointer may be NULL.
@field version The version number of this structure. The current version is 0.
@field attributes A logically ORed set of JSClassAttributes to give to the class.
@field className A null-terminated UTF8 string containing the class’s name.
@field parentClass A JSClass to set as the class’s parent class. Pass NULL use the default object class.
@field staticValues A JSStaticValue array containing the class’s statically declared value properties. Pass NULL to specify no statically declared value properties. The array must be terminated by a JSStaticValue whose name field is NULL.
@field staticFunctions A JSStaticFunction array containing the class’s statically declared function properties. Pass NULL to specify no statically declared function properties. The array must be terminated by a JSStaticFunction whose name field is NULL.
@field initialize The callback invoked when an object is first created. Use this callback to initialize the object.
@field finalize The callback invoked when an object is finalized (prepared for garbage collection). Use this callback to release resources allocated for the object, and perform other cleanup.
@field hasProperty The callback invoked when determining whether an object has a property. If this field is NULL, getProperty is called instead. The hasProperty callback enables optimization in cases where only a property’s existence needs to be known, not its value, and computing its value is expensive.
@field getProperty The callback invoked when getting a property’s value.
@field setProperty The callback invoked when setting a property’s value.
@field deleteProperty The callback invoked when deleting a property.
@field getPropertyNames The callback invoked when collecting the names of an object’s properties.
@field callAsFunction The callback invoked when an object is called as a function.
@field hasInstance The callback invoked when an object is used as the target of an ‘instanceof’ expression.
@field callAsConstructor The callback invoked when an object is used as a constructor in a ‘new’ expression.
@field convertToType The callback invoked when converting an object to a particular JavaScript type.
@discussion The staticValues and staticFunctions arrays are the simplest and most efficient means for vending custom properties. Statically declared properties autmatically service requests like getProperty, setProperty, and getPropertyNames. Property access callbacks are required only to implement unusual properties, like array indexes, whose names are not known at compile-time.
@struct JSStaticFunction
@abstract This structure describes a statically declared function property.
@field name A null-terminated UTF8 string containing the property’s name.
@field callAsFunction A JSObjectCallAsFunctionCallback to invoke when the property is called as a function.
@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
@struct JSStaticValue
@abstract This structure describes a statically declared value property.
@field name A null-terminated UTF8 string containing the property’s name.
@field getProperty A JSObjectGetPropertyCallback to invoke when getting the property’s value.
@field setProperty A JSObjectSetPropertyCallback to invoke when setting the property’s value. May be NULL if the ReadOnly attribute is set.
@field attributes A logically ORed set of JSPropertyAttributes to give to the property.
Attribute Specifier
Use attribute specifier to tell tokenizer to prepare the specified attribute
when it tokenizes the given string. The attribute value can be retrieved by
calling CFStringTokenizerCopyCurrentTokenAttribute with one of the attribute
option.
Attribute Specifier
Use attribute specifier to tell tokenizer to prepare the specified attribute
when it tokenizes the given string. The attribute value can be retrieved by
calling CFStringTokenizerCopyCurrentTokenAttribute with one of the attribute
option.
Compound token which may contain derived subtokens.
Its subtokens and derived subtokens can be obtained by calling
CFStringTokenizerGetCurrentSubTokens.
Compound token which may contain derived subtokens.
Its subtokens and derived subtokens can be obtained by calling
CFStringTokenizerGetCurrentSubTokens.
Compound token which may contain derived subtokens.
Its subtokens and derived subtokens can be obtained by calling
CFStringTokenizerGetCurrentSubTokens.
Compound token which may contain subtokens but with no derived subtokens.
Its subtokens can be obtained by calling CFStringTokenizerGetCurrentSubTokens.
Compound token which may contain derived subtokens.
Its subtokens and derived subtokens can be obtained by calling
CFStringTokenizerGetCurrentSubTokens.
@constant kCFCopyStringDictionaryKeyCallBacks
Predefined CFDictionaryKeyCallBacks structure containing a
set of callbacks appropriate for use when the keys of a
CFDictionary are all CFStrings, which may be mutable and
need to be copied in order to serve as constant keys for
the values in the dictionary.
@constant kCFCopyStringSetCallBacks
Predefined CFSetCallBacks structure containing a set of callbacks
appropriate for use when the values in a CFSet should be copies
of a CFString.
@constant kCFStringBinaryHeapCallBacks
Predefined CFBinaryHeapCallBacks structure containing a set
of callbacks appropriate for use when the values in a CFBinaryHeap
are all CFString types.
@constant kCFTypeArrayCallBacks
Predefined CFArrayCallBacks structure containing a set of callbacks
appropriate for use when the values in a CFArray are all CFTypes.
@constant kCFTypeDictionaryKeyCallBacks
Predefined CFDictionaryKeyCallBacks structure containing a
set of callbacks appropriate for use when the keys of a
CFDictionary are all CFTypes.
@constant kCFTypeDictionaryValueCallBacks
Predefined CFDictionaryValueCallBacks structure containing a set
of callbacks appropriate for use when the values in a CFDictionary
are all CFTypes.
@constant kCFTypeSetCallBacks
Predefined CFSetCallBacks structure containing a set of callbacks
appropriate for use when the values in a CFSet are all CFTypes.
@const kJSClassDefinitionEmpty
@abstract A JSClassDefinition structure of the current version, filled with NULL pointers and having no attributes.
@discussion Use this constant as a convenience when creating class definitions. For example, to create a class definition with only a finalize method:
@function CFArrayAppendArray
Adds the values from an array to another array.
@param theArray The array to which values from the otherArray are to
be added. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
@param otherArray The array providing the values to be added to the
array. If this parameter is not a valid CFArray, the
behavior is undefined.
@param otherRange The range within the otherArray from which to add
the values to the array. If the range location or end point
(defined by the location plus length minus 1) is outside
the index space of the otherArray (0 to N-1 inclusive, where
N is the count of the otherArray), the behavior is
undefined. The new values are retained by the array using
the retain callback provided when the array was created. If
the values are not of the sort expected by the retain
callback, the behavior is undefined. The values are assigned
to the indices one larger than the previous largest index
in the array, and beyond, and the count of the array is
increased by range.length. The values are assigned new
indices in the array from smallest to largest index in the
order in which they appear in the otherArray.
@function CFArrayAppendValue
Adds the value to the array giving it a new largest index.
@param theArray The array to which the value is to be added. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param value The value to add to the array. The value is retained by
the array using the retain callback provided when the array
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The value is
assigned to the index one larger than the previous largest
index, and the count of the array is increased by one.
@function CFArrayApplyFunction
Calls a function once for each value in the array.
@param theArray The array to be operated upon. If this parameter is not
a valid CFArray, the behavior is undefined.
@param range The range of values within the array to which to apply
the function. If the range location or end point (defined by
the location plus length minus 1) is outside the index
space of the array (0 to N-1 inclusive, where N is the count
of the array), the behavior is undefined. If the range
length is negative, the behavior is undefined. The range may
be empty (length 0).
@param applier The callback function to call once for each value in
the given range in the array. If this parameter is not a
pointer to a function of the correct prototype, the behavior
is undefined. If there are values in the range which the
applier function does not expect or cannot properly apply
to, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the second parameter to the applier function, but is
otherwise unused by this function. If the context is not
what is expected by the applier function, the behavior is
undefined.
@function CFArrayBSearchValues
Searches the array for the value using a binary search algorithm.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined. If the array is
not sorted from least to greatest according to the
comparator function, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find a match in the array. If
value, or any of the values in the array, are not understood
by the comparator callback, the behavior is undefined.
@param comparator The function with the comparator function type
signature which is used in the binary search operation to
compare values in the array with the given value. If this
parameter is not a pointer to a function of the correct
prototype, the behavior is undefined. If there are values
in the range which the comparator function does not expect
or cannot properly compare, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the third parameter to the comparator function, but is
otherwise unused by this function. If the context is not
what is expected by the comparator function, the behavior is
undefined.
@result The return value is either 1) the index of a value that
matched, if the target value matches one or more in the
range, 2) greater than or equal to the end point of the
range, if the value is greater than all the values in the
range, or 3) the index of the value greater than the target
value, if the value lies between two of (or less than all
of) the values in the range.
@function CFArrayContainsValue
Reports whether or not the value is in the array.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find matches in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result true, if the value is in the specified range of the array,
otherwise false.
@function CFArrayCreate
Creates a new immutable array with the given values.
@param allocator The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param values A C array of the pointer-sized values to be in the
array. The values in the array are ordered in the same order
in which they appear in this C array. This parameter may be
NULL if the numValues parameter is 0. This C array is not
changed or freed by this function. If this parameter is not
a valid pointer to a C array of at least numValues pointers,
the behavior is undefined.
@param numValues The number of values to copy from the values C
array into the CFArray. This number will be the count of the
array.
If this parameter is negative, or greater than the number of
values actually in the value’s C array, the behavior is
undefined.
@param callBacks A pointer to a CFArrayCallBacks structure
initialized with the callbacks for the array to use on each
value in the array. The retain callback will be used within
this function, for example, to retain all of the new values
from the values C array. A copy of the contents of the
callbacks structure is made, so that a pointer to a
structure on the stack can be passed in, or can be reused
for multiple array creations. If the version field of this
callbacks structure is not one of the defined ones for
CFArray, the behavior is undefined. The retain field may be
NULL, in which case the CFArray will do nothing to add a
retain to the contained values for the array. The release
field may be NULL, in which case the CFArray will do nothing
to remove the array’s retain (if any) on the values when the
array is destroyed. If the copyDescription field is NULL,
the array will create a simple description for the value. If
the equal field is NULL, the array will use pointer equality
to test for equality of values. This callbacks parameter
itself may be NULL, which is treated as if a valid structure
of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFArrayCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
array is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new immutable CFArray.
@function CFArrayCreateCopy
Creates a new immutable array with the values from the given array.
@param allocator The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theArray The array which is to be copied. The values from the
array are copied as pointers into the new array (that is,
the values themselves are copied, not that which the values
point to, if anything). However, the values are also
retained by the new array. The count of the new array will
be the same as the given array. The new array uses the same
callbacks as the array to be copied. If this parameter is
not a valid CFArray, the behavior is undefined.
@result A reference to the new immutable CFArray.
@function CFArrayCreateMutable
Creates a new empty mutable array.
@param allocator The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFArray. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. An array’s actual capacity is only limited by
address space and available memory constraints). If this
parameter is negative, the behavior is undefined.
@param callBacks A pointer to a CFArrayCallBacks structure
initialized with the callbacks for the array to use on each
value in the array. A copy of the contents of the
callbacks structure is made, so that a pointer to a
structure on the stack can be passed in, or can be reused
for multiple array creations. If the version field of this
callbacks structure is not one of the defined ones for
CFArray, the behavior is undefined. The retain field may be
NULL, in which case the CFArray will do nothing to add a
retain to the contained values for the array. The release
field may be NULL, in which case the CFArray will do nothing
to remove the array’s retain (if any) on the values when the
array is destroyed. If the copyDescription field is NULL,
the array will create a simple description for the value. If
the equal field is NULL, the array will use pointer equality
to test for equality of values. This callbacks parameter
itself may be NULL, which is treated as if a valid structure
of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFArrayCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
array is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new mutable CFArray.
@function CFArrayCreateMutableCopy
Creates a new mutable array with the values from the given array.
@param allocator The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFArray. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. An array’s actual capacity is only limited by
address space and available memory constraints).
This parameter must be greater than or equal
to the count of the array which is to be copied, or the
behavior is undefined. If this parameter is negative, the
behavior is undefined.
@param theArray The array which is to be copied. The values from the
array are copied as pointers into the new array (that is,
the values themselves are copied, not that which the values
point to, if anything). However, the values are also
retained by the new array. The count of the new array will
be the same as the given array. The new array uses the same
callbacks as the array to be copied. If this parameter is
not a valid CFArray, the behavior is undefined.
@result A reference to the new mutable CFArray.
@function CFArrayExchangeValuesAtIndices
Exchanges the values at two indices of the array.
@param theArray The array of which the values are to be swapped. If
this parameter is not a valid mutable CFArray, the behavior
is undefined.
@param idx1 The first index whose values should be swapped. If the
index is outside the index space of the array (0 to N-1
inclusive, where N is the count of the array before the
operation), the behavior is undefined.
@param idx2 The second index whose values should be swapped. If the
index is outside the index space of the array (0 to N-1
inclusive, where N is the count of the array before the
operation), the behavior is undefined.
@function CFArrayGetCount
Returns the number of values currently in the array.
@param theArray The array to be queried. If this parameter is not a valid
CFArray, the behavior is undefined.
@result The number of values in the array.
@function CFArrayGetCountOfValue
Counts the number of times the given value occurs in the array.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param value The value for which to find matches in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The number of times the given value occurs in the array,
within the specified range.
@function CFArrayGetFirstIndexOfValue
Searches the array for the value.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
The search progresses from the smallest index defined by
the range to the largest.
@param value The value for which to find a match in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The lowest index of the matching values in the range, or
kCFNotFound if no value in the range matched.
@function CFArrayGetLastIndexOfValue
Searches the array for the value.
@param theArray The array to be searched. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range within the array to search. If the range
location or end point (defined by the location plus length
minus 1) is outside the index space of the array (0 to
N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
The search progresses from the largest index defined by the
range to the smallest.
@param value The value for which to find a match in the array. The
equal() callback provided when the array was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the array, are not understood by the equal() callback,
the behavior is undefined.
@result The highest index of the matching values in the range, or
kCFNotFound if no value in the range matched.
@function CFArrayGetValueAtIndex
Retrieves the value at the given index.
@param theArray The array to be queried. If this parameter is not a
valid CFArray, the behavior is undefined.
@param idx The index of the value to retrieve. If the index is
outside the index space of the array (0 to N-1 inclusive,
where N is the count of the array), the behavior is
undefined.
@result The value with the given index in the array.
@function CFArrayGetValues
Fills the buffer with values from the array.
@param theArray The array to be queried. If this parameter is not a
valid CFArray, the behavior is undefined.
@param range The range of values within the array to retrieve. If
the range location or end point (defined by the location
plus length minus 1) is outside the index space of the
array (0 to N-1 inclusive, where N is the count of the
array), the behavior is undefined. If the range length is
negative, the behavior is undefined. The range may be empty
(length 0), in which case no values are put into the buffer.
@param values A C array of pointer-sized values to be filled with
values from the array. The values in the C array are ordered
in the same order in which they appear in the array. If this
parameter is not a valid pointer to a C array of at least
range.length pointers, the behavior is undefined.
@function CFArrayInsertValueAtIndex
Adds the value to the array, giving it the given index.
@param theArray The array to which the value is to be added. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param idx The index to which to add the new value. If the index is
outside the index space of the array (0 to N inclusive,
where N is the count of the array before the operation), the
behavior is undefined. If the index is the same as N, this
function has the same effect as CFArrayAppendValue().
@param value The value to add to the array. The value is retained by
the array using the retain callback provided when the array
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The value is
assigned to the given index, and all values with equal and
larger indices have their indexes increased by one.
@function CFArrayRemoveAllValues
Removes all the values from the array, making it empty.
@param theArray The array from which all of the values are to be
removed. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
@function CFArrayRemoveValueAtIndex
Removes the value with the given index from the array.
@param theArray The array from which the value is to be removed. If
this parameter is not a valid mutable CFArray, the behavior
is undefined.
@param idx The index from which to remove the value. If the index is
outside the index space of the array (0 to N-1 inclusive,
where N is the count of the array before the operation), the
behavior is undefined.
@function CFArrayReplaceValues
Replaces a range of values in the array.
@param theArray The array from which all of the values are to be
removed. If this parameter is not a valid mutable CFArray,
the behavior is undefined.
@param range The range of values within the array to replace. If the
range location or end point (defined by the location plus
length minus 1) is outside the index space of the array (0
to N inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0),
in which case the new values are merely inserted at the
range location.
@param newValues A C array of the pointer-sized values to be placed
into the array. The new values in the array are ordered in
the same order in which they appear in this C array. This
parameter may be NULL if the newCount parameter is 0. This
C array is not changed or freed by this function. If this
parameter is not a valid pointer to a C array of at least
newCount pointers, the behavior is undefined.
@param newCount The number of values to copy from the values C
array into the CFArray. If this parameter is different than
the range length, the excess newCount values will be
inserted after the range, or the excess range values will be
deleted. This parameter may be 0, in which case no new
values are replaced into the array and the values in the
range are simply removed. If this parameter is negative, or
greater than the number of values actually in the newValues
C array, the behavior is undefined.
@function CFArraySetValueAtIndex
Changes the value with the given index in the array.
@param theArray The array in which the value is to be changed. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param idx The index to which to set the new value. If the index is
outside the index space of the array (0 to N inclusive,
where N is the count of the array before the operation), the
behavior is undefined. If the index is the same as N, this
function has the same effect as CFArrayAppendValue().
@param value The value to set in the array. The value is retained by
the array using the retain callback provided when the array
was created, and the previous value with that index is
released. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The indices of
other values is not affected.
@function CFArraySortValues
Sorts the values in the array using the given comparison function.
@param theArray The array whose values are to be sorted. If this
parameter is not a valid mutable CFArray, the behavior is
undefined.
@param range The range of values within the array to sort. If the
range location or end point (defined by the location plus
length minus 1) is outside the index space of the array (0
to N-1 inclusive, where N is the count of the array), the
behavior is undefined. If the range length is negative, the
behavior is undefined. The range may be empty (length 0).
@param comparator The function with the comparator function type
signature which is used in the sort operation to compare
values in the array with the given value. If this parameter
is not a pointer to a function of the correct prototype, the
the behavior is undefined. If there are values in the array
which the comparator function does not expect or cannot
properly compare, the behavior is undefined. The values in
the range are sorted from least to greatest according to
this function.
@param context A pointer-sized user-defined value, which is passed
as the third parameter to the comparator function, but is
otherwise unused by this function. If the context is not
what is expected by the comparator function, the behavior is
undefined.
@function CFAttributedStringBeginEditing
In cases where attributed string might do a bunch of work to assure self-consistency, CFAttributedStringBeginEditing/CFAttributedStringEndEditing allow disabling that to allow deferring and coalescing any work. It’s a good idea to call these around a set of related mutation calls which don’t require the string to be in consistent state in between. These calls can be nested.
@function CFAttributedStringCreateMutable
Creates a mutable empty attributed string. maxLength, if not 0, is a hard bound on the length of the attributed string; exceeding this size limit during any editing operation is a programming error. If 0, there is no limit on the length.
@function CFAttributedStringCreateMutableCopy
Creates a mutable attributed string copy. maxLength, if not 0, is a hard bound on the length of the attributed string; exceeding this size limit during any editing operation is a programming error. If 0, there is no limit on the length.
@function CFAttributedStringCreateWithSubstring
Creates a sub-attributed string from the specified range. It’s a programming error for range to specify characters outside the bounds of aStr.
@function CFAttributedStringEndEditing
In cases where attributed string might do a bunch of work to assure self-consistency, CFAttributedStringBeginEditing/CFAttributedStringEndEditing allow disabling that to allow deferring and coalescing any work. It’s a good idea to call these around a set of related mutation calls which don’t require the string to be in consistent state in between. These calls can be nested.
@function CFAttributedStringGetAttribute
Returns the value of a single attribute at the specified location. If the specified attribute doesn’t exist at the location, returns NULL. If effectiveRange is not NULL, upon return *effectiveRange contains a range over which the exact same attribute value applies. Note that for performance reasons, the returned effectiveRange is not necessarily the maximal range - for that, use CFAttributedStringGetAttributeAndLongestEffectiveRange(). It’s a programming error for loc to specify a location outside the bounds of the attributed string.
@function CFAttributedStringGetAttributeAndLongestEffectiveRange
Returns the value of a single attribute at the specified location. If longestEffectiveRange is not NULL, upon return *longestEffectiveRange contains the maximal range within inRange over which the exact same attribute value applies. The returned range is clipped to inRange. It’s a programming error for loc or inRange to specify locations outside the bounds of the attributed string.
@function CFAttributedStringGetAttributes
Returns the attributes at the specified location. If effectiveRange is not NULL, upon return *effectiveRange contains a range over which the exact same set of attributes apply. Note that for performance reasons, the returned effectiveRange is not necessarily the maximal range - for that, use CFAttributedStringGetAttributesAndLongestEffectiveRange(). It’s a programming error for loc to specify a location outside the bounds of the attributed string.
@function CFAttributedStringGetAttributesAndLongestEffectiveRange
Returns the attributes at the specified location. If longestEffectiveRange is not NULL, upon return *longestEffectiveRange contains the maximal range within inRange over which the exact same set of attributes apply. The returned range is clipped to inRange. It’s a programming error for loc or inRange to specify locations outside the bounds of the attributed string.
@function CFAttributedStringGetLength
Returns the length of the attributed string in characters; same as CFStringGetLength(CFAttributedStringGetString(aStr))
@function CFAttributedStringGetMutableString
Gets the string for the attributed string as a mutable string, allowing editing the character contents of the string as if it were an CFMutableString. Attributes corresponding to the edited range are appropriately modified. If, as a result of the edit, new characters are introduced into the string, they inherit the attributes of the first replaced character from range. If no existing characters are replaced by the edit, the new characters inherit the attributes of the character preceding range if it has any, otherwise of the character following range. If the initial string is empty, the attributes for the new characters are also empty.
@function CFAttributedStringGetString
Returns the string for the attributed string. For performance reasons, this will often point at the backing store of the attributed string, and it might change if the attributed string is edited. However, this is an implementation detail, and definitely not something that should be counted on.
@function CFAttributedStringRemoveAttribute
Removes the value of a single attribute over the specified range, which should be valid. It’s OK for the attribute not the exist over the specified range.
@function CFAttributedStringReplaceAttributedString
Replaces the attributed substring over the specified range with the attributed string specified in replacement. range should be valid. To delete a range of the attributed string, call CFAttributedStringReplaceString() with empty string and specified range.
@function CFAttributedStringReplaceString
Modifies the string for the attributed string, much like CFStringReplace(). It’s an error for range to specify characters outside the bounds of aStr.
@function CFAttributedStringSetAttribute
Sets the value of a single attribute over the specified range, which should be valid. value should not be NULL.
@function CFAttributedStringSetAttributes
Sets the value of multiple attributes over the specified range, which should be valid. If clearOtherAttributes is false, existing attributes (which aren’t being replaced) are left alone; otherwise they are cleared. The dictionary should be setup for “usual” CF type usage — CFString keys, and arbitrary CFType values. Note that after this call, further mutations to the replacement dictionary argument by the caller will not affect the contents of the attributed string.
@function CFBinaryHeapAddValue
Adds the value to the binary heap.
@param heap The binary heap to which the value is to be added. If this parameter is not a
valid mutable CFBinaryHeap, the behavior is undefined.
@param value The value to add to the binary heap. The value is retained by
the binary heap using the retain callback provided when the binary heap
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined.
@function CFBinaryHeapApplyFunction
Calls a function once for each value in the binary heap.
@param heap The binary heap to be operated upon. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@param applier The callback function to call once for each value in
the given binary heap. If this parameter is not a
pointer to a function of the correct prototype, the behavior
is undefined. If there are values in the binary heap which the
applier function does not expect or cannot properly apply
to, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the second parameter to the applier function, but is
otherwise unused by this function. If the context is not
what is expected by the applier function, the behavior is
undefined.
@function CFBinaryHeapContainsValue
Reports whether or not the value is in the binary heap.
@param heap The binary heap to be searched. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@param value The value for which to find matches in the binary heap. The
compare() callback provided when the binary heap was created is
used to compare. If the compare() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the binary heap, are not understood by the compare() callback,
the behavior is undefined.
@result true, if the value is in the specified binary heap, otherwise false.
@function CFBinaryHeapCreate
Creates a new mutable binary heap with the given values.
@param allocator The CFAllocator which should be used to allocate
memory for the binary heap and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFBinaryHeap. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A heap’s actual capacity is only limited by
address space and available memory constraints). If this
parameter is negative, the behavior is undefined.
@param callBacks A pointer to a CFBinaryHeapCallBacks structure
initialized with the callbacks for the binary heap to use on
each value in the binary heap. A copy of the contents of the
callbacks structure is made, so that a pointer to a structure
on the stack can be passed in, or can be reused for multiple
binary heap creations. If the version field of this callbacks
structure is not one of the defined ones for CFBinaryHeap, the
behavior is undefined. The retain field may be NULL, in which
case the CFBinaryHeap will do nothing to add a retain to values
as they are put into the binary heap. The release field may be
NULL, in which case the CFBinaryHeap will do nothing to remove
the binary heap’s retain (if any) on the values when the
heap is destroyed or a key-value pair is removed. If the
copyDescription field is NULL, the binary heap will create a
simple description for a value. If the equal field is NULL, the
binary heap will use pointer equality to test for equality of
values. This callbacks parameter itself may be NULL, which is
treated as if a valid structure of version 0 with all fields
NULL had been passed in. Otherwise,
if any of the fields are not valid pointers to functions
of the correct type, or this parameter is not a valid
pointer to a CFBinaryHeapCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
binary heap is not one understood by one of the callback functions
the behavior when that callback function is used is undefined.
@param compareContext A pointer to a CFBinaryHeapCompareContext structure.
@result A reference to the new CFBinaryHeap.
@function CFBinaryHeapCreateCopy
Creates a new mutable binary heap with the values from the given binary heap.
@param allocator The CFAllocator which should be used to allocate
memory for the binary heap and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFBinaryHeap. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A heap’s actual capacity is only limited by
address space and available memory constraints).
This parameter must be greater than or equal
to the count of the heap which is to be copied, or the
behavior is undefined. If this parameter is negative, the
behavior is undefined.
@param heap The binary heap which is to be copied. The values from the
binary heap are copied as pointers into the new binary heap (that is,
the values themselves are copied, not that which the values
point to, if anything). However, the values are also
retained by the new binary heap. The count of the new binary will
be the same as the given binary heap. The new binary heap uses the same
callbacks as the binary heap to be copied. If this parameter is
not a valid CFBinaryHeap, the behavior is undefined.
@result A reference to the new mutable binary heap.
@function CFBinaryHeapGetCount
Returns the number of values currently in the binary heap.
@param heap The binary heap to be queried. If this parameter is not a valid
CFBinaryHeap, the behavior is undefined.
@result The number of values in the binary heap.
@function CFBinaryHeapGetCountOfValue
Counts the number of times the given value occurs in the binary heap.
@param heap The binary heap to be searched. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@param value The value for which to find matches in the binary heap. The
compare() callback provided when the binary heap was created is
used to compare. If the compare() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the binary heap, are not understood by the compare() callback,
the behavior is undefined.
@result The number of times the given value occurs in the binary heap.
@function CFBinaryHeapGetMinimum
Returns the minimum value is in the binary heap. If the heap contains several equal
minimum values, any one may be returned.
@param heap The binary heap to be searched. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@result A reference to the minimum value in the binary heap, or NULL if the
binary heap contains no values.
@function CFBinaryHeapGetMinimumIfPresent
Returns the minimum value is in the binary heap, if present. If the heap contains several equal
minimum values, any one may be returned.
@param heap The binary heap to be searched. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@param value A C pointer to pointer-sized storage to be filled with the minimum value in
the binary heap. If this value is not a valid C pointer to a pointer-sized block
of storage, the result is undefined. If the result of the function is false, the value
stored at this address is undefined.
@result true, if a minimum value was found in the specified binary heap, otherwise false.
@function CFBinaryHeapGetValues
Fills the buffer with values from the binary heap.
@param heap The binary heap to be queried. If this parameter is not a
valid CFBinaryHeap, the behavior is undefined.
@param values A C array of pointer-sized values to be filled with
values from the binary heap. The values in the C array are ordered
from least to greatest. If this parameter is not a valid pointer to a
C array of at least CFBinaryHeapGetCount() pointers, the behavior is undefined.
@function CFBinaryHeapRemoveAllValues
Removes all the values from the binary heap, making it empty.
@param heap The binary heap from which all of the values are to be
removed. If this parameter is not a valid mutable CFBinaryHeap,
the behavior is undefined.
@function CFBinaryHeapRemoveMinimumValue
Removes the minimum value from the binary heap.
@param heap The binary heap from which the minimum value is to be removed. If this
parameter is not a valid mutable CFBinaryHeap, the behavior is undefined.
@function CFCharacterSetAddCharactersInRange
Adds the given range to the charaacter set.
@param theSet The character set to which the range is to be added.
If this parameter is not a valid mutable CFCharacterSet,
the behavior is undefined.
@param theRange The range to add to the character set. It accepts
the range in 32-bit in the UTF-32 format. The valid
character point range is from 0x00000 to 0x10FFFF. If the
range is outside of the valid Unicode character point,
the behavior is undefined.
@function CFCharacterSetAddCharactersInString
Adds the characters in the given string to the charaacter set.
@param theSet The character set to which the characters in the
string are to be added. If this parameter is not a
valid mutable CFCharacterSet, the behavior is undefined.
@param theString The string to add to the character set.
If this parameter is not a valid CFString, the behavior
is undefined.
@function CFCharacterSetCreateBitmapRepresentation
Creates a new immutable data with the bitmap representation from the given character set.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theSet The CFCharacterSet which is to be used create the
bitmap representation from. Refer to the comments for
CFCharacterSetCreateWithBitmapRepresentation for the
detailed discussion of the bitmap representation format.
If this parameter is not a valid CFCharacterSet, the
behavior is undefined.
@result A reference to the new immutable CFData.
@function CFCharacterSetCreateCopy
Creates a new character set with the values from the given character set. This function tries to compact the backing store where applicable.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theSet The CFCharacterSet which is to be copied. If this
parameter is not a valid CFCharacterSet, the behavior is
undefined.
@result A reference to the new CFCharacterSet.
@function CFCharacterSetCreateInvertedSet
Creates a new immutable character set that is the invert of the specified character set.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theSet The CFCharacterSet which is to be inverted. If this
parameter is not a valid CFCharacterSet, the behavior is
undefined.
@result A reference to the new immutable CFCharacterSet.
@function CFCharacterSetCreateMutable
Creates a new empty mutable character set.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@result A reference to the new mutable CFCharacterSet.
@function CFCharacterSetCreateMutableCopy
Creates a new mutable character set with the values from the given character set.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theSet The CFCharacterSet which is to be copied. If this
parameter is not a valid CFCharacterSet, the behavior is
undefined.
@result A reference to the new mutable CFCharacterSet.
@function CFCharacterSetCreateWithBitmapRepresentation
Creates a new immutable character set with the bitmap representtion in the given data.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theData The CFData which should be used to specify the
bitmap representation of the Unicode character points
the character set is filled with. The bitmap
representation could contain all the Unicode character
range starting from BMP to Plane 16. The first 8192 bytes
of the data represent the BMP range. The BMP range 8192
bytes can be followed by zero to sixteen 8192 byte
bitmaps, each one with the plane index byte prepended.
For example, the bitmap representing the BMP and Plane 2
has the size of 16385 bytes (8192 bytes for BMP, 1 byte
index + 8192 bytes bitmap for Plane 2). The plane index
byte, in this case, contains the integer value two. If
this parameter is not a valid CFData or it contains a
Plane index byte outside of the valid Plane range
(1 to 16), the behavior is undefined.
@result A reference to the new immutable CFCharacterSet.
@function CFCharacterSetCreateWithCharactersInRange
Creates a new immutable character set with the values from the given range.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theRange The CFRange which should be used to specify the
Unicode range the character set is filled with. It
accepts the range in 32-bit in the UTF-32 format. The
valid character point range is from 0x00000 to 0x10FFFF.
If the range is outside of the valid Unicode character
point, the behavior is undefined.
@result A reference to the new immutable CFCharacterSet.
@function CFCharacterSetCreateWithCharactersInString
Creates a new immutable character set with the values in the given string.
@param alloc The CFAllocator which should be used to allocate
memory for the array and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theString The CFString which should be used to specify
the Unicode characters the character set is filled with.
If this parameter is not a valid CFString, the behavior
is undefined.
@result A reference to the new immutable CFCharacterSet.
@function CFCharacterSetGetPredefined
Returns a predefined CFCharacterSet instance.
@param theSetIdentifier The CFCharacterSetPredefinedSet selector
which specifies the predefined character set. If the
value is not in CFCharacterSetPredefinedSet, the behavior
is undefined.
@result A reference to the predefined immutable CFCharacterSet.
This instance is owned by CF.
@function CFCharacterSetHasMemberInPlane
Reports whether or not the character set contains at least one member character in the specified plane.
@param theSet The character set to be checked for the membership. If this
parameter is not a valid CFCharacterSet, the behavior is undefined.
@param thePlane The plane number to be checked for the membership.
The valid value range is from 0 to 16. If the value is outside of the valid
plane number range, the behavior is undefined.
@function CFCharacterSetIntersect
Forms the intersection with the given character set.
@param theSet The destination character set into which the
intersection of the two character sets is stored.
If this parameter is not a valid mutable CFCharacterSet,
the behavior is undefined.
@param theOtherSet The character set with which the intersection
is formed. If this parameter is not a valid CFCharacterSet,
the behavior is undefined.
@function CFCharacterSetInvert
Inverts the content of the given character set.
@param theSet The character set to be inverted.
If this parameter is not a valid mutable CFCharacterSet,
the behavior is undefined.
@function CFCharacterSetIsCharacterMember
Reports whether or not the Unicode character is in the character set.
@param theSet The character set to be searched. If this parameter
is not a valid CFCharacterSet, the behavior is undefined.
@param theChar The Unicode character for which to test against the
character set. Note that this function takes 16-bit Unicode
character value; hence, it does not support access to the
non-BMP planes.
@result true, if the value is in the character set, otherwise false.
@function CFCharacterSetIsLongCharacterMember
Reports whether or not the UTF-32 character is in the character set.
@param theSet The character set to be searched. If this parameter
is not a valid CFCharacterSet, the behavior is undefined.
@param theChar The UTF-32 character for which to test against the
character set.
@result true, if the value is in the character set, otherwise false.
@function CFCharacterSetIsSupersetOfSet
Reports whether or not the character set is a superset of the character set specified as the second parameter.
@param theSet The character set to be checked for the membership of theOtherSet.
If this parameter is not a valid CFCharacterSet, the behavior is undefined.
@param theOtherset The character set to be checked whether or not it is a subset of theSet.
If this parameter is not a valid CFCharacterSet, the behavior is undefined.
@function CFCharacterSetRemoveCharactersInRange
Removes the given range from the charaacter set.
@param theSet The character set from which the range is to be
removed. If this parameter is not a valid mutable
CFCharacterSet, the behavior is undefined.
@param theRange The range to remove from the character set.
It accepts the range in 32-bit in the UTF-32 format.
The valid character point range is from 0x00000 to 0x10FFFF.
If the range is outside of the valid Unicode character point,
the behavior is undefined.
@function CFCharacterSetRemoveCharactersInString
Removes the characters in the given string from the charaacter set.
@param theSet The character set from which the characters in the
string are to be remove. If this parameter is not a
valid mutable CFCharacterSet, the behavior is undefined.
@param theString The string to remove from the character set.
If this parameter is not a valid CFString, the behavior
is undefined.
@function CFCharacterSetUnion
Forms the union with the given character set.
@param theSet The destination character set into which the
union of the two character sets is stored. If this
parameter is not a valid mutable CFCharacterSet, the
behavior is undefined.
@param theOtherSet The character set with which the union is
formed. If this parameter is not a valid CFCharacterSet,
the behavior is undefined.
@function CFDictionaryAddValue
Adds the key-value pair to the dictionary if no such key already exists.
@param theDict The dictionary to which the value is to be added. If this
parameter is not a valid mutable CFDictionary, the behavior is
undefined.
@param key The key of the value to add to the dictionary. The key is
retained by the dictionary using the retain callback provided
when the dictionary was created. If the key is not of the sort
expected by the retain callback, the behavior is undefined. If
a key which matches this key is already present in the dictionary,
this function does nothing (“add if absent”).
@param value The value to add to the dictionary. The value is retained
by the dictionary using the retain callback provided when the
dictionary was created. If the value is not of the sort expected
by the retain callback, the behavior is undefined.
@function CFDictionaryApplyFunction
Calls a function once for each value in the dictionary.
@param theDict The dictionary to be queried. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param applier The callback function to call once for each value in
the dictionary. If this parameter is not a
pointer to a function of the correct prototype, the behavior
is undefined. If there are keys or values which the
applier function does not expect or cannot properly apply
to, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the third parameter to the applier function, but is
otherwise unused by this function. If the context is not
what is expected by the applier function, the behavior is
undefined.
@function CFDictionaryContainsKey
Reports whether or not the key is in the dictionary.
@param theDict The dictionary to be searched. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param key The key for which to find matches in the dictionary. The
hash() and equal() key callbacks provided when the dictionary
was created are used to compare. If the hash() key callback
was NULL, the key is treated as a pointer and converted to
an integer. If the equal() key callback was NULL, pointer
equality (in C, ==) is used. If key, or any of the keys in
the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@result true, if the key is in the dictionary, otherwise false.
@function CFDictionaryContainsValue
Reports whether or not the value is in the dictionary.
@param theDict The dictionary to be searched. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param value The value for which to find matches in the dictionary. The
equal() callback provided when the dictionary was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@result true, if the value is in the dictionary, otherwise false.
@function CFDictionaryCreate
Creates a new immutable dictionary with the given values.
@param allocator The CFAllocator which should be used to allocate
memory for the dictionary and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param keys A C array of the pointer-sized keys to be used for
the parallel C array of values to be put into the dictionary.
This parameter may be NULL if the numValues parameter is 0.
This C array is not changed or freed by this function. If
this parameter is not a valid pointer to a C array of at
least numValues pointers, the behavior is undefined.
@param values A C array of the pointer-sized values to be in the
dictionary. This parameter may be NULL if the numValues
parameter is 0. This C array is not changed or freed by
this function. If this parameter is not a valid pointer to
a C array of at least numValues pointers, the behavior is
undefined.
@param numValues The number of values to copy from the keys and
values C arrays into the CFDictionary. This number will be
the count of the dictionary. If this parameter is
negative, or greater than the number of values actually
in the keys or values C arrays, the behavior is undefined.
@param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
initialized with the callbacks for the dictionary to use on
each key in the dictionary. The retain callback will be used
within this function, for example, to retain all of the new
keys from the keys C array. A copy of the contents of the
callbacks structure is made, so that a pointer to a structure
on the stack can be passed in, or can be reused for multiple
dictionary creations. If the version field of this
callbacks structure is not one of the defined ones for
CFDictionary, the behavior is undefined. The retain field may
be NULL, in which case the CFDictionary will do nothing to add
a retain to the keys of the contained values. The release field
may be NULL, in which case the CFDictionary will do nothing
to remove the dictionary’s retain (if any) on the keys when the
dictionary is destroyed or a key-value pair is removed. If the
copyDescription field is NULL, the dictionary will create a
simple description for a key. If the equal field is NULL, the
dictionary will use pointer equality to test for equality of
keys. If the hash field is NULL, a key will be converted from
a pointer to an integer to compute the hash code. This callbacks
parameter itself may be NULL, which is treated as if a valid
structure of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
the behavior is undefined. If any of the keys put into the
dictionary is not one understood by one of the callback functions
the behavior when that callback function is used is undefined.
@param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
initialized with the callbacks for the dictionary to use on
each value in the dictionary. The retain callback will be used
within this function, for example, to retain all of the new
values from the values C array. A copy of the contents of the
callbacks structure is made, so that a pointer to a structure
on the stack can be passed in, or can be reused for multiple
dictionary creations. If the version field of this callbacks
structure is not one of the defined ones for CFDictionary, the
behavior is undefined. The retain field may be NULL, in which
case the CFDictionary will do nothing to add a retain to values
as they are put into the dictionary. The release field may be
NULL, in which case the CFDictionary will do nothing to remove
the dictionary’s retain (if any) on the values when the
dictionary is destroyed or a key-value pair is removed. If the
copyDescription field is NULL, the dictionary will create a
simple description for a value. If the equal field is NULL, the
dictionary will use pointer equality to test for equality of
values. This callbacks parameter itself may be NULL, which is
treated as if a valid structure of version 0 with all fields
NULL had been passed in. Otherwise,
if any of the fields are not valid pointers to functions
of the correct type, or this parameter is not a valid
pointer to a CFDictionaryValueCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
dictionary is not one understood by one of the callback functions
the behavior when that callback function is used is undefined.
@result A reference to the new immutable CFDictionary.
@function CFDictionaryCreateCopy
Creates a new immutable dictionary with the key-value pairs from
the given dictionary.
@param allocator The CFAllocator which should be used to allocate
memory for the dictionary and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theDict The dictionary which is to be copied. The keys and values
from the dictionary are copied as pointers into the new
dictionary (that is, the values themselves are copied, not
that which the values point to, if anything). However, the
keys and values are also retained by the new dictionary using
the retain function of the original dictionary.
The count of the new dictionary will be the same as the
given dictionary. The new dictionary uses the same callbacks
as the dictionary to be copied. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@result A reference to the new immutable CFDictionary.
@function CFDictionaryCreateMutable
Creates a new mutable dictionary.
@param allocator The CFAllocator which should be used to allocate
memory for the dictionary and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFDictionary. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A dictionary’s actual capacity is only limited by
address space and available memory constraints). If this
parameter is negative, the behavior is undefined.
@param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
initialized with the callbacks for the dictionary to use on
each key in the dictionary. A copy of the contents of the
callbacks structure is made, so that a pointer to a structure
on the stack can be passed in, or can be reused for multiple
dictionary creations. If the version field of this
callbacks structure is not one of the defined ones for
CFDictionary, the behavior is undefined. The retain field may
be NULL, in which case the CFDictionary will do nothing to add
a retain to the keys of the contained values. The release field
may be NULL, in which case the CFDictionary will do nothing
to remove the dictionary’s retain (if any) on the keys when the
dictionary is destroyed or a key-value pair is removed. If the
copyDescription field is NULL, the dictionary will create a
simple description for a key. If the equal field is NULL, the
dictionary will use pointer equality to test for equality of
keys. If the hash field is NULL, a key will be converted from
a pointer to an integer to compute the hash code. This callbacks
parameter itself may be NULL, which is treated as if a valid
structure of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
the behavior is undefined. If any of the keys put into the
dictionary is not one understood by one of the callback functions
the behavior when that callback function is used is undefined.
@param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
initialized with the callbacks for the dictionary to use on
each value in the dictionary. The retain callback will be used
within this function, for example, to retain all of the new
values from the values C array. A copy of the contents of the
callbacks structure is made, so that a pointer to a structure
on the stack can be passed in, or can be reused for multiple
dictionary creations. If the version field of this callbacks
structure is not one of the defined ones for CFDictionary, the
behavior is undefined. The retain field may be NULL, in which
case the CFDictionary will do nothing to add a retain to values
as they are put into the dictionary. The release field may be
NULL, in which case the CFDictionary will do nothing to remove
the dictionary’s retain (if any) on the values when the
dictionary is destroyed or a key-value pair is removed. If the
copyDescription field is NULL, the dictionary will create a
simple description for a value. If the equal field is NULL, the
dictionary will use pointer equality to test for equality of
values. This callbacks parameter itself may be NULL, which is
treated as if a valid structure of version 0 with all fields
NULL had been passed in. Otherwise,
if any of the fields are not valid pointers to functions
of the correct type, or this parameter is not a valid
pointer to a CFDictionaryValueCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
dictionary is not one understood by one of the callback functions
the behavior when that callback function is used is undefined.
@result A reference to the new mutable CFDictionary.
@function CFDictionaryCreateMutableCopy
Creates a new mutable dictionary with the key-value pairs from
the given dictionary.
@param allocator The CFAllocator which should be used to allocate
memory for the dictionary and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFDictionary. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A dictionary’s actual capacity is only limited by
address space and available memory constraints).
This parameter must be greater than or equal
to the count of the dictionary which is to be copied, or the
behavior is undefined. If this parameter is negative, the
behavior is undefined.
@param theDict The dictionary which is to be copied. The keys and values
from the dictionary are copied as pointers into the new
dictionary (that is, the values themselves are copied, not
that which the values point to, if anything). However, the
keys and values are also retained by the new dictionary using
the retain function of the original dictionary.
The count of the new dictionary will be the same as the
given dictionary. The new dictionary uses the same callbacks
as the dictionary to be copied. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@result A reference to the new mutable CFDictionary.
@function CFDictionaryGetCount
Returns the number of values currently in the dictionary.
@param theDict The dictionary to be queried. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@result The number of values in the dictionary.
@function CFDictionaryGetCountOfKey
Counts the number of times the given key occurs in the dictionary.
@param theDict The dictionary to be searched. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param key The key for which to find matches in the dictionary. The
hash() and equal() key callbacks provided when the dictionary
was created are used to compare. If the hash() key callback
was NULL, the key is treated as a pointer and converted to
an integer. If the equal() key callback was NULL, pointer
equality (in C, ==) is used. If key, or any of the keys in
the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@result Returns 1 if a matching key is used by the dictionary,
0 otherwise.
@function CFDictionaryGetCountOfValue
Counts the number of times the given value occurs in the dictionary.
@param theDict The dictionary to be searched. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param value The value for which to find matches in the dictionary. The
equal() callback provided when the dictionary was created is
used to compare. If the equal() value callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values in
the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@result The number of times the given value occurs in the dictionary.
@function CFDictionaryGetKeysAndValues
Fills the two buffers with the keys and values from the dictionary.
@param theDict The dictionary to be queried. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param keys A C array of pointer-sized values to be filled with keys
from the dictionary. The keys and values C arrays are parallel
to each other (that is, the items at the same indices form a
key-value pair from the dictionary). This parameter may be NULL
if the keys are not desired. If this parameter is not a valid
pointer to a C array of at least CFDictionaryGetCount() pointers,
or NULL, the behavior is undefined.
@param values A C array of pointer-sized values to be filled with values
from the dictionary. The keys and values C arrays are parallel
to each other (that is, the items at the same indices form a
key-value pair from the dictionary). This parameter may be NULL
if the values are not desired. If this parameter is not a valid
pointer to a C array of at least CFDictionaryGetCount() pointers,
or NULL, the behavior is undefined.
@function CFDictionaryGetValue
Retrieves the value associated with the given key.
@param theDict The dictionary to be queried. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param key The key for which to find a match in the dictionary. The
hash() and equal() key callbacks provided when the dictionary
was created are used to compare. If the hash() key callback
was NULL, the key is treated as a pointer and converted to
an integer. If the equal() key callback was NULL, pointer
equality (in C, ==) is used. If key, or any of the keys in
the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@result The value with the given key in the dictionary, or NULL if
no key-value pair with a matching key exists. Since NULL
can be a valid value in some dictionaries, the function
CFDictionaryGetValueIfPresent() must be used to distinguish
NULL-no-found from NULL-is-the-value.
@function CFDictionaryGetValueIfPresent
Retrieves the value associated with the given key.
@param theDict The dictionary to be queried. If this parameter is
not a valid CFDictionary, the behavior is undefined.
@param key The key for which to find a match in the dictionary. The
hash() and equal() key callbacks provided when the dictionary
was created are used to compare. If the hash() key callback
was NULL, the key is treated as a pointer and converted to
an integer. If the equal() key callback was NULL, pointer
equality (in C, ==) is used. If key, or any of the keys in
the dictionary, are not understood by the equal() callback,
the behavior is undefined.
@param value A pointer to memory which should be filled with the
pointer-sized value if a matching key is found. If no key
match is found, the contents of the storage pointed to by
this parameter are undefined. This parameter may be NULL,
in which case the value from the dictionary is not returned
(but the return value of this function still indicates
whether or not the key-value pair was present).
@result true, if a matching key was found, false otherwise.
@function CFDictionaryRemoveAllValues
Removes all the values from the dictionary, making it empty.
@param theDict The dictionary from which all of the values are to be
removed. If this parameter is not a valid mutable
CFDictionary, the behavior is undefined.
@function CFDictionaryRemoveValue
Removes the value of the key from the dictionary.
@param theDict The dictionary from which the value is to be removed. If this
parameter is not a valid mutable CFDictionary, the behavior is
undefined.
@param key The key of the value to remove from the dictionary. If a key
which matches this key is present in the dictionary, the key-value
pair is removed from the dictionary, otherwise this function does
nothing (“remove if present”).
@function CFDictionaryReplaceValue
Replaces the value of the key in the dictionary.
@param theDict The dictionary to which the value is to be replaced. If this
parameter is not a valid mutable CFDictionary, the behavior is
undefined.
@param key The key of the value to replace in the dictionary. If a key
which matches this key is present in the dictionary, the value
is changed to the given value, otherwise this function does
nothing (“replace if present”).
@param value The value to replace into the dictionary. The value
is retained by the dictionary using the retain callback provided
when the dictionary was created, and the previous value is
released. If the value is not of the sort expected by the
retain or release callbacks, the behavior is undefined.
@function CFDictionarySetValue
Sets the value of the key in the dictionary.
@param theDict The dictionary to which the value is to be set. If this
parameter is not a valid mutable CFDictionary, the behavior is
undefined.
@param key The key of the value to set into the dictionary. If a key
which matches this key is already present in the dictionary, only
the value is changed (“add if absent, replace if present”). If
no key matches the given key, the key-value pair is added to the
dictionary. If added, the key is retained by the dictionary,
using the retain callback provided
when the dictionary was created. If the key is not of the sort
expected by the key retain callback, the behavior is undefined.
@param value The value to add to or replace into the dictionary. The value
is retained by the dictionary using the retain callback provided
when the dictionary was created, and the previous value if any is
released. If the value is not of the sort expected by the
retain or release callbacks, the behavior is undefined.
@function CFErrorCopyDescription
@abstract Returns a human-presentable description for the error. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedDescriptionKey at the time of CFError creation.
@discussion This is a complete sentence or two which says what failed and why it failed. Please refer to header comments for -[NSError localizedDescription] for details on the steps used to compute this; but roughly:
@function CFErrorCopyFailureReason
@abstract Returns a human-presentable failure reason for the error. May return NULL. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedFailureReasonKey at the time of CFError creation.
@discussion This is a complete sentence which describes why the operation failed. In many cases this will be just the “because” part of the description (but as a complete sentence, which makes localization easier). By default this looks for kCFErrorLocalizedFailureReasonKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL.
Example Description: “Could not save file ‘Letter’ in folder ‘Documents’ because the volume ‘MyDisk’ doesn’t have enough space.”
Corresponding FailureReason: “The volume ‘MyDisk’ doesn’t have enough space.”
@param err The CFError whose failure reason is to be returned. If this reference is not a valid CFError, the behavior is undefined.
@result A CFString with the localized, end-user presentable failure reason of the CFError, or NULL.
@function CFErrorCopyRecoverySuggestion
@abstract Returns a human presentable recovery suggestion for the error. May return NULL. CFError creators should strive to make sure the return value is human-presentable and localized by providing a value for kCFErrorLocalizedRecoverySuggestionKey at the time of CFError creation.
@discussion This is the string that can be displayed as the “informative” (aka “secondary”) message on an alert panel. By default this looks for kCFErrorLocalizedRecoverySuggestionKey in the user info. Toll-free bridged NSError instances might provide additional behaviors for manufacturing this value. If no user-presentable string is available, returns NULL.
Example Description: “Could not save file ‘Letter’ in folder ‘Documents’ because the volume ‘MyDisk’ doesn’t have enough space.”
Corresponding RecoverySuggestion: “Remove some files from the volume and try again.”
@param err The CFError whose recovery suggestion is to be returned. If this reference is not a valid CFError, the behavior is undefined.
@result A CFString with the localized, end-user presentable recovery suggestion of the CFError, or NULL.
@function CFErrorCopyUserInfo
@abstract Returns CFError userInfo dictionary.
@discussion Returns a dictionary containing the same keys and values as in the userInfo dictionary the CFError was created with. Returns an empty dictionary if NULL was supplied to CFErrorCreate().
@param err The CFError whose error user info is to be returned. If this reference is not a valid CFError, the behavior is undefined.
@result The user info of the CFError.
@function CFErrorCreate
@abstract Creates a new CFError.
@param allocator The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the
current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
@param domain A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.
@param code A CFIndex identifying the error code. The code is interpreted within the context of the error domain.
@param userInfo A CFDictionary created with kCFCopyStringDictionaryKeyCallBacks and kCFTypeDictionaryValueCallBacks. It will be copied with CFDictionaryCreateCopy().
If no userInfo dictionary is desired, NULL may be passed in as a convenience, in which case an empty userInfo dictionary will be assigned.
@result A reference to the new CFError.
@function CFErrorCreateWithUserInfoKeysAndValues
@abstract Creates a new CFError without having to create an intermediate userInfo dictionary.
@param allocator The CFAllocator which should be used to allocate memory for the error. This parameter may be NULL in which case the
current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.
@param domain A CFString identifying the error domain. If this reference is NULL or is otherwise not a valid CFString, the behavior is undefined.
@param code A CFIndex identifying the error code. The code is interpreted within the context of the error domain.
@param userInfoKeys An array of numUserInfoValues CFStrings used as keys in creating the userInfo dictionary. NULL is valid only if numUserInfoValues is 0.
@param userInfoValues An array of numUserInfoValues CF types used as values in creating the userInfo dictionary. NULL is valid only if numUserInfoValues is 0.
@param numUserInfoValues CFIndex representing the number of keys and values in the userInfoKeys and userInfoValues arrays.
@result A reference to the new CFError. numUserInfoValues CF types are gathered from each of userInfoKeys and userInfoValues to create the userInfo dictionary.
@function CFErrorGetCode
@abstract Returns the error code the CFError was created with.
@param err The CFError whose error code is to be returned. If this reference is not a valid CFError, the behavior is undefined.
@result The error code of the CFError (not an error return for the current call).
@function CFErrorGetDomain
@abstract Returns the error domain the CFError was created with.
@param err The CFError whose error domain is to be returned. If this reference is not a valid CFError, the behavior is undefined.
@result The error domain of the CFError. Since this is a “Get” function, the caller shouldn’t CFRelease the return value.
@function CFSetAddValue
Adds the value to the set if it is not already present.
@param theSet The set to which the value is to be added. If this
parameter is not a valid mutable CFSet, the behavior is
undefined.
@param value The value to add to the set. The value is retained by
the set using the retain callback provided when the set
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The count of the
set is increased by one.
@function CFSetApplyFunction
Calls a function once for each value in the set.
@param theSet The set to be operated upon. If this parameter is not
a valid CFSet, the behavior is undefined.
@param applier The callback function to call once for each value in
the given set. If this parameter is not a
pointer to a function of the correct prototype, the behavior
is undefined. If there are values in the set which the
applier function does not expect or cannot properly apply
to, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the second parameter to the applier function, but is
otherwise unused by this function. If the context is not
what is expected by the applier function, the behavior is
undefined.
@function CFSetContainsValue
Reports whether or not the value is in the set.
@param theSet The set to be searched. If this parameter is not a
valid CFSet, the behavior is undefined.
@param value The value for which to find matches in the set. The
equal() callback provided when the set was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the set, are not understood by the equal() callback,
the behavior is undefined.
@result true, if the value is in the set, otherwise false.
@function CFSetCreate
Creates a new immutable set with the given values.
@param allocator The CFAllocator which should be used to allocate
memory for the set and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param values A C array of the pointer-sized values to be in the
set. This C array is not changed or freed by this function.
If this parameter is not a valid pointer to a C array of at
least numValues pointers, the behavior is undefined.
@param numValues The number of values to copy from the values C
array into the CFSet. This number will be the count of the
set. If this parameter is zero, negative, or greater than
the number of values actually in the values C array, the
behavior is undefined.
@param callBacks A C pointer to a CFSetCallBacks structure
initialized with the callbacks for the set to use on each
value in the set. A copy of the contents of the
callbacks structure is made, so that a pointer to a
structure on the stack can be passed in, or can be reused
for multiple set creations. If the version field of this
callbacks structure is not one of the defined ones for
CFSet, the behavior is undefined. The retain field may be
NULL, in which case the CFSet will do nothing to add a
retain to the contained values for the set. The release
field may be NULL, in which case the CFSet will do nothing
to remove the set’s retain (if any) on the values when the
set is destroyed. If the copyDescription field is NULL,
the set will create a simple description for the value. If
the equal field is NULL, the set will use pointer equality
to test for equality of values. The hash field may be NULL,
in which case the CFSet will determine uniqueness by pointer
equality. This callbacks parameter
itself may be NULL, which is treated as if a valid structure
of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFSetCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
set is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new immutable CFSet.
@function CFSetCreateCopy
Creates a new immutable set with the values from the given set.
@param allocator The CFAllocator which should be used to allocate
memory for the set and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param theSet The set which is to be copied. The values from the
set are copied as pointers into the new set (that is,
the values themselves are copied, not that which the values
point to, if anything). However, the values are also
retained by the new set. The count of the new set will
be the same as the copied set. The new set uses the same
callbacks as the set to be copied. If this parameter is
not a valid CFSet, the behavior is undefined.
@result A reference to the new immutable CFSet.
@function CFSetCreateMutable
Creates a new empty mutable set.
@param allocator The CFAllocator which should be used to allocate
memory for the set and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFSet. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A set’s actual capacity is only limited by
address space and available memory constraints). If this
parameter is negative, the behavior is undefined.
@param callBacks A C pointer to a CFSetCallBacks structure
initialized with the callbacks for the set to use on each
value in the set. A copy of the contents of the
callbacks structure is made, so that a pointer to a
structure on the stack can be passed in, or can be reused
for multiple set creations. If the version field of this
callbacks structure is not one of the defined ones for
CFSet, the behavior is undefined. The retain field may be
NULL, in which case the CFSet will do nothing to add a
retain to the contained values for the set. The release
field may be NULL, in which case the CFSet will do nothing
to remove the set’s retain (if any) on the values when the
set is destroyed. If the copyDescription field is NULL,
the set will create a simple description for the value. If
the equal field is NULL, the set will use pointer equality
to test for equality of values. The hash field may be NULL,
in which case the CFSet will determine uniqueness by pointer
equality. This callbacks parameter
itself may be NULL, which is treated as if a valid structure
of version 0 with all fields NULL had been passed in.
Otherwise, if any of the fields are not valid pointers to
functions of the correct type, or this parameter is not a
valid pointer to a CFSetCallBacks callbacks structure,
the behavior is undefined. If any of the values put into the
set is not one understood by one of the callback functions
the behavior when that callback function is used is
undefined.
@result A reference to the new mutable CFSet.
@function CFSetCreateMutableCopy
Creates a new immutable set with the values from the given set.
@param allocator The CFAllocator which should be used to allocate
memory for the set and its storage for values. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param capacity A hint about the number of values that will be held
by the CFSet. Pass 0 for no hint. The implementation may
ignore this hint, or may use it to optimize various
operations. A set’s actual capacity is only limited by
address space and available memory constraints).
This parameter must be greater than or equal
to the count of the set which is to be copied, or the
behavior is undefined. If this parameter is negative, the
behavior is undefined.
@param theSet The set which is to be copied. The values from the
set are copied as pointers into the new set (that is,
the values themselves are copied, not that which the values
point to, if anything). However, the values are also
retained by the new set. The count of the new set will
be the same as the copied set. The new set uses the same
callbacks as the set to be copied. If this parameter is
not a valid CFSet, the behavior is undefined.
@result A reference to the new mutable CFSet.
@function CFSetGetCount
Returns the number of values currently in the set.
@param theSet The set to be queried. If this parameter is not a valid
CFSet, the behavior is undefined.
@result The number of values in the set.
@function CFSetGetCountOfValue
Counts the number of times the given value occurs in the set. Since
sets by definition contain only one instance of a value, this function
is synonymous to CFSetContainsValue.
@param theSet The set to be searched. If this parameter is not a
valid CFSet, the behavior is undefined.
@param value The value for which to find matches in the set. The
equal() callback provided when the set was created is
used to compare. If the equal() callback was NULL, pointer
equality (in C, ==) is used. If value, or any of the values
in the set, are not understood by the equal() callback,
the behavior is undefined.
@result The number of times the given value occurs in the set.
@function CFSetGetValue
Retrieves a value in the set which hashes the same as the specified value.
@param theSet The set to be queried. If this parameter is not a
valid CFSet, the behavior is undefined.
@param value The value to retrieve. The equal() callback provided when
the set was created is used to compare. If the equal() callback
was NULL, pointer equality (in C, ==) is used. If a value, or
any of the values in the set, are not understood by the equal()
callback, the behavior is undefined.
@result The value in the set with the given hash.
@function CFSetGetValueIfPresent
Retrieves a value in the set which hashes the same as the specified value,
if present.
@param theSet The set to be queried. If this parameter is not a
valid CFSet, the behavior is undefined.
@param candidate This value is hashed and compared with values in the
set to determine which value to retrieve. The equal() callback provided when
the set was created is used to compare. If the equal() callback
was NULL, pointer equality (in C, ==) is used. If a value, or
any of the values in the set, are not understood by the equal()
callback, the behavior is undefined.
@param value A pointer to memory which should be filled with the
pointer-sized value if a matching value is found. If no
match is found, the contents of the storage pointed to by
this parameter are undefined. This parameter may be NULL,
in which case the value from the dictionary is not returned
(but the return value of this function still indicates
whether or not the value was present).
@result True if the value was present in the set, otherwise false.
@function CFSetGetValues
Fills the buffer with values from the set.
@param theSet The set to be queried. If this parameter is not a
valid CFSet, the behavior is undefined.
@param values A C array of pointer-sized values to be filled with
values from the set. The values in the C array are ordered
in the same order in which they appear in the set. If this
parameter is not a valid pointer to a C array of at least
CFSetGetCount() pointers, the behavior is undefined.
@function CFSetRemoveAllValues
Removes all the values from the set, making it empty.
@param theSet The set from which all of the values are to be
removed. If this parameter is not a valid mutable CFSet,
the behavior is undefined.
@function CFSetRemoveValue
Removes the specified value from the set.
@param theSet The set from which the value is to be removed.
If this parameter is not a valid mutable CFSet,
the behavior is undefined.
@param value The value to remove. The equal() callback provided when
the set was created is used to compare. If the equal() callback
was NULL, pointer equality (in C, ==) is used. If a value, or
any of the values in the set, are not understood by the equal()
callback, the behavior is undefined.
@function CFSetReplaceValue
Replaces the value in the set if it is present.
@param theSet The set to which the value is to be replaced. If this
parameter is not a valid mutable CFSet, the behavior is
undefined.
@param value The value to replace in the set. The equal() callback provided when
the set was created is used to compare. If the equal() callback
was NULL, pointer equality (in C, ==) is used. If a value, or
any of the values in the set, are not understood by the equal()
callback, the behavior is undefined. The value is retained by
the set using the retain callback provided when the set
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The count of the
set is increased by one.
@function CFSetSetValue
Replaces the value in the set if it is present, or adds the value to
the set if it is absent.
@param theSet The set to which the value is to be replaced. If this
parameter is not a valid mutable CFSet, the behavior is
undefined.
@param value The value to set in the CFSet. The equal() callback provided when
the set was created is used to compare. If the equal() callback
was NULL, pointer equality (in C, ==) is used. If a value, or
any of the values in the set, are not understood by the equal()
callback, the behavior is undefined. The value is retained by
the set using the retain callback provided when the set
was created. If the value is not of the sort expected by the
retain callback, the behavior is undefined. The count of the
set is increased by one.
@function CFStringFindCharacterFromSet
Query the range of the first character contained in the specified character set.
@param theString The CFString which is to be searched. If this
parameter is not a valid CFString, the behavior is
undefined.
@param theSet The CFCharacterSet against which the membership
of characters is checked. If this parameter is not a valid
CFCharacterSet, the behavior is undefined.
@param rangeToSearch The range of characters within the string to search. If
the range location or end point (defined by the location
plus length minus 1) are outside the index space of the
string (0 to N-1 inclusive, where N is the length of the
string), the behavior is undefined. If the range length is
negative, the behavior is undefined. The range may be empty
(length 0), in which case no search is performed.
@param searchOptions The bitwise-or’ed option flags to control
the search behavior. The supported options are
kCFCompareBackwards andkCFCompareAnchored.
If other option flags are specified, the behavior
is undefined.
@param result The pointer to a CFRange supplied by the caller in
which the search result is stored. Note that the length
of this range can be more than 1, if for instance the
result is a composed character. If a pointer to an invalid
memory is specified, the behavior is undefined.
@result true, if at least a character which is a member of the character
set is found and result is filled, otherwise, false.
@function CFStringFold
Folds the string into the form specified by the flags.
Character foldings are operations that convert any of a set of characters
sharing similar semantics into a single representative from that set.
This function can be used to preprocess strings that are to be compared,
searched, or indexed.
Note that folding does not include normalization, so it is necessary
to use CFStringNormalize in addition to CFStringFold in order to obtain
the effect of kCFCompareNonliteral.
@param theString The string which is to be folded. If this parameter is not
a valid mutable CFString, the behavior is undefined.
@param theFlags The equivalency flags which describes the character folding form.
Only those flags containing the word “insensitive” are recognized here; other flags are ignored.
Folding with kCFCompareCaseInsensitive removes case distinctions in accordance with the mapping
specified by ftp://ftp.unicode.org/Public/UNIDATA/CaseFolding.txt. Folding with
kCFCompareDiacriticInsensitive removes distinctions of accents and other diacritics. Folding
with kCFCompareWidthInsensitive removes character width distinctions by mapping characters in
the range U+FF00-U+FFEF to their ordinary equivalents.
@param theLocale The locale tailoring the character folding behavior. If NULL,
it’s considered to be the system locale returned from CFLocaleGetSystem().
If non-NULL and not a valid CFLocale object, the behavior is undefined.
@function CFStringGetHyphenationLocationBeforeIndex
Retrieve the first potential hyphenation location found before the specified location.
@param string The CFString which is to be hyphenated. If this
parameter is not a valid CFString, the behavior is
undefined.
@param location An index in the string. If a valid hyphen index is returned, it
will be before this index.
@param limitRange The range of characters within the string to search. If
the range location or end point (defined by the location
plus length minus 1) are outside the index space of the
string (0 to N-1 inclusive, where N is the length of the
string), the behavior is undefined. If the range length is
negative, the behavior is undefined. The range may be empty
(length 0), in which case no hyphen location is generated.
@param options Reserved for future use.
@param locale Specifies which language’s hyphenation conventions to use.
This must be a valid locale. Hyphenation data is not available
for all locales. You can use CFStringIsHyphenationAvailableForLocale
to test for availability of hyphenation data.
@param character The suggested hyphen character to insert. Pass NULL if you
do not need this information.
@result an index in the string where it is appropriate to insert a hyphen, if
one exists; else kCFNotFound
@function CFStringGetRangeOfComposedCharactersAtIndex
Returns the range of the composed character sequence at the specified index.
@param theString The CFString which is to be searched. If this
parameter is not a valid CFString, the behavior is
undefined.
@param theIndex The index of the character contained in the
composed character sequence. If the index is
outside the index space of the string (0 to N-1 inclusive,
where N is the length of the string), the behavior is
undefined.
@result The range of the composed character sequence.
@function CFStringNormalize
Normalizes the string into the specified form as described in
Unicode Technical Report #15.
@param theString The string which is to be normalized. If this
parameter is not a valid mutable CFString, the behavior is
undefined.
@param theForm The form into which the string is to be normalized.
If this parameter is not a valid CFStringNormalizationForm value,
the behavior is undefined.
@function CFStringTokenizerAdvanceToNextToken
@abstract Token enumerator.
@param tokenizer The reference to CFStringTokenizer returned by
CFStringTokenizerCreate.
@result Type of the token if succeeded in finding a token and setting it as
current token. kCFStringTokenizerTokenNone if failed in finding a token.
@discussion If there is no preceding call to CFStringTokenizerGoToTokenAtIndex
or CFStringTokenizerAdvanceToNextToken, it finds the first token in the range
specified to CFStringTokenizerCreate. If there is a current token after successful
call to CFStringTokenizerGoToTokenAtIndex or CFStringTokenizerAdvanceToNextToken,
it proceeds to the next token. If succeeded in finding a token, set it as current
token and return its token type. Otherwise invalidate current token and return
kCFStringTokenizerTokenNone.
The range and attribute of the token can be obtained by calling
CFStringTokenizerGetCurrentTokenRange and
CFStringTokenizerCopyCurrentTokenAttribute. If the token is a compound
(with type kCFStringTokenizerTokenHasSubTokensMask or
kCFStringTokenizerTokenHasDerivedSubTokensMask), its subtokens and
(or) derived subtokens can be obtained by calling CFStringTokenizerGetCurrentSubTokens.
@function CFStringTokenizerCopyBestStringLanguage
@abstract Guesses the language of a string and returns the BCP 47 string of the
language.
@param string The string whose language is to be guessed.
@param range The range of characters in string whose language to be
guessed. The specified range must not exceed the bounds of the string.
@result A language represented in BCP 47 string. NULL is returned either if
string is NULL, the location of range is negative, the length of range
is 0, or the language of the string cannot be guessed.
@discussion The result is not guaranteed to be accurate. Typically 200-400
characters are required to reliably guess the language of a string.
@function CFStringTokenizerCopyCurrentTokenAttribute
@abstract Copies the specified attribute of current token.
@param tokenizer The reference to CFStringTokenizer returned by
CFStringTokenizerCreate.
@param attribute Specify a token attribute you want to obtain. The value is
one of kCFStringTokenizerAttributeLatinTranscription or
kCFStringTokenizerAttributeLanguage.
@result Token attribute, or NULL if current token does not have the specified
attribute or if there is no current token.
@function CFStringTokenizerCreate
@abstract Creates a tokenizer instance.
@param alloc The CFAllocator which should be used to allocate memory for the
tokenizer and its storage for values. This parameter may be NULL in which
case the current default CFAllocator is used.
@param string The string to tokenize.
@param range The range of characters within the string to be tokenized. The
specified range must not exceed the length of the string.
@param options Use one of the Tokenization Unit options to specify how the
string should be tokenized. Optionally specify one or more attribute
specifiers to tell the tokenizer to prepare specified attributes when it
tokenizes the string.
@param locale The locale to specify language or region specific behavior. Pass
NULL if you want tokenizer to identify the locale automatically.
@result A reference to the new CFStringTokenizer.
@function CFStringTokenizerGetCurrentSubTokens
@abstract Retrieves the subtokens or derived subtokens contained in the compound token.
@param tokenizer The reference to CFStringTokenizer returned by CFStringTokenizerCreate.
@param ranges An array of CFRange to fill in with the ranges of subtokens. The filled in
ranges are relative to the string specified to CFStringTokenizerCreate. This parameter
can be NULL.
@param maxRangeLength The maximum number of ranges to return.
@param derivedSubTokens An array of CFMutableArray to which the derived subtokens are to
be added. This parameter can be NULL.
@result number of subtokens.
@discussion If token type is kCFStringTokenizerTokenNone, the ranges array and
derivedSubTokens array are untouched and the return value is 0.
If token type is kCFStringTokenizerTokenNormal, the ranges array has one item
filled in with the entire range of the token (if maxRangeLength >= 1) and a string
taken from the entire token range is added to the derivedSubTokens array and the
return value is 1.
If token type is kCFStringTokenizerTokenHasSubTokensMask or
kCFStringTokenizerTokenHasDerivedSubTokensMask, the ranges array is filled
in with as many items as there are subtokens (up to a limit of maxRangeLength).
The derivedSubTokens array will have sub tokens added even when the sub token is a
substring of the token. If token type is kCFStringTokenizerTokenHasSubTokensMask,
the ordinary non-derived subtokens are added to the derivedSubTokens array.
@function CFStringTokenizerGetCurrentTokenRange
@abstract Returns the range of current token.
@param tokenizer The reference to CFStringTokenizer returned by
CFStringTokenizerCreate.
@result Range of current token, or {kCFNotFound,0} if there is no current token.
@function CFStringTokenizerGoToTokenAtIndex
@abstract Random access to a token. Find a token that includes the character specified
by character index, and set it as the current token.
@param tokenizer The reference to CFStringTokenizer returned by
CFStringTokenizerCreate.
@param index The index of the Unicode character in the CFString.
@result Type of the token if succeeded in finding a token and setting it as
current token. kCFStringTokenizerTokenNone if failed in finding a token.
@discussion The range and attribute of the token can be obtained by calling
CFStringTokenizerGetCurrentTokenRange and CFStringTokenizerCopyCurrentTokenAttribute.
If the token is a compound (with type kCFStringTokenizerTokenHasSubTokensMask or
kCFStringTokenizerTokenHasDerivedSubTokensMask), its subtokens and
(or) derived subtokens can be obtained by calling CFStringTokenizerGetCurrentSubTokens.
@function CFStringTokenizerSetString
@abstract Set the string to tokenize.
@param tokenizer The reference to CFStringTokenizer returned by
CFStringTokenizerCreate.
@param string The string to tokenize.
@param range The range of characters within the string to be tokenized. The
specified range must not exceed the length of the string.
@function CFTreeAppendChild
Adds the newChild to the specified tree as the last in its list of children.
@param tree The tree to be operated on. If this parameter is not a valid
CFTree, the behavior is undefined.
@param newChild The child to be added.
If this parameter is not a valid CFTree, the behavior is undefined.
If this parameter is a tree which is already a child of any tree,
the behavior is undefined.
@function CFTreeApplyFunctionToChildren
Calls a function once for each child of the tree. Note that the applier
only operates one level deep, and does not operate on descendents further
removed than the immediate children of the tree.
@param tree The tree to be operated upon. If this parameter is not a
valid CFTree, the behavior is undefined.
@param applier The callback function to call once for each child of
the given tree. If this parameter is not a pointer to a
function of the correct prototype, the behavior is undefined.
If there are values in the tree which the applier function does
not expect or cannot properly apply to, the behavior is undefined.
@param context A pointer-sized user-defined value, which is passed
as the second parameter to the applier function, but is
otherwise unused by this function. If the context is not
what is expected by the applier function, the behavior is
undefined.
@function CFTreeCreate
Creates a new mutable tree.
@param allocator The CFAllocator which should be used to allocate
memory for the tree and storage for its children. This
parameter may be NULL in which case the current default
CFAllocator is used. If this reference is not a valid
CFAllocator, the behavior is undefined.
@param context A C pointer to a CFTreeContext structure to be copied
and used as the context of the new tree. The info parameter
will be retained by the tree if a retain function is provided.
If this value is not a valid C pointer to a CFTreeContext
structure-sized block of storage, the result is undefined.
If the version number of the storage is not a valid CFTreeContext
version number, the result is undefined.
@result A reference to the new CFTree.
@function CFTreeFindRoot
Returns the root tree of which the specified tree is a descendent.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@result A reference to the root of the tree.
@function CFTreeGetChildAtIndex
Returns the nth child of the specified tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@param idx The index of the child tree to be returned. If this parameter
is less than zero or greater than the number of children of the
tree, the result is undefined.
@result A reference to the specified child tree.
@function CFTreeGetChildCount
Returns the number of children of the specified tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@result The number of children.
@function CFTreeGetChildren
Fills the buffer with children from the tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@param children A C array of pointer-sized values to be filled with
children from the tree. If this parameter is not a valid pointer to a
C array of at least CFTreeGetChildCount() pointers, the behavior is undefined.
@function CFTreeGetContext
Returns the context of the specified tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@param context A C pointer to a CFTreeContext structure to be filled in with
the context of the specified tree. If this value is not a valid C
pointer to a CFTreeContext structure-sized block of storage, the
result is undefined. If the version number of the storage is not
a valid CFTreeContext version number, the result is undefined.
@function CFTreeGetFirstChild
Returns the first child of the tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@result The first child of the tree.
@function CFTreeGetNextSibling
Returns the sibling after the specified tree in the parent tree’s list.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@result The next sibling of the tree.
@function CFTreeGetParent
Returns the parent of the specified tree.
@param tree The tree to be queried. If this parameter is not a valid
CFTree, the behavior is undefined.
@result The parent of the tree.
@function CFTreeInsertSibling
Inserts newSibling into the the parent tree’s linked list of children after
tree. The newSibling will have the same parent as tree.
@param tree The tree to insert newSibling after. If this parameter is not a valid
CFTree, the behavior is undefined. If the tree does not have a
parent, the behavior is undefined.
@param newSibling The sibling to be added.
If this parameter is not a valid CFTree, the behavior is undefined.
If this parameter is a tree which is already a child of any tree,
the behavior is undefined.
@function CFTreePrependChild
Adds the newChild to the specified tree as the first in its list of children.
@param tree The tree to be operated on. If this parameter is not a valid
CFTree, the behavior is undefined.
@param newChild The child to be added.
If this parameter is not a valid CFTree, the behavior is undefined.
If this parameter is a tree which is already a child of any tree,
the behavior is undefined.
@function CFTreeRemove
Removes the tree from its parent.
@param tree The tree to be removed. If this parameter is not a valid
CFTree, the behavior is undefined.
@function CFTreeRemoveAllChildren
Removes all the children of the tree.
@param tree The tree to remove all children from. If this parameter is not a valid
CFTree, the behavior is undefined.
@function CFTreeSetContext
Replaces the context of a tree. The tree releases its retain on the
info of the previous context, and retains the info of the new context.
@param tree The tree to be operated on. If this parameter is not a valid
CFTree, the behavior is undefined.
@param context A C pointer to a CFTreeContext structure to be copied
and used as the context of the new tree. The info parameter
will be retained by the tree if a retain function is provided.
If this value is not a valid C pointer to a CFTreeContext
structure-sized block of storage, the result is undefined.
If the version number of the storage is not a valid CFTreeContext
version number, the result is undefined.
@function CFTreeSortChildren
Sorts the children of the specified tree using the specified comparator function.
@param tree The tree to be operated on. If this parameter is not a valid
CFTree, the behavior is undefined.
@param comparator The function with the comparator function type
signature which is used in the sort operation to compare
children of the tree with the given value. If this parameter
is not a pointer to a function of the correct prototype, the
the behavior is undefined. The children of the tree are sorted
from least to greatest according to this function.
@param context A pointer-sized user-defined value, which is passed
as the third parameter to the comparator function, but is
otherwise unused by this function. If the context is not
what is expected by the comparator function, the behavior is
undefined.
@function JSCheckScriptSyntax
@abstract Checks for syntax errors in a string of JavaScript.
@param ctx The execution context to use.
@param script A JSString containing the script to check for syntax errors.
@param sourceURL A JSString containing a URL for the script’s source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
@param startingLineNumber An integer value specifying the script’s starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
@result true if the script is syntactically correct, otherwise false.
@function
@abstract Creates a JavaScript class suitable for use with JSObjectMake.
@param definition A JSClassDefinition that defines the class.
@result A JSClass with the given definition. Ownership follows the Create Rule.
@function
@abstract Gets the global context of a JavaScript execution context.
@param ctx The JSContext whose global context you want to get.
@result ctx’s global context.
@function
@abstract Gets the global object of a JavaScript execution context.
@param ctx The JSContext whose global object you want to get.
@result ctx’s global object.
@function
@abstract Gets the context group to which a JavaScript execution context belongs.
@param ctx The JSContext whose group you want to get.
@result ctx’s group.
@function
@abstract Gets the shared data pointer
@param ctx The JSContext whose global object you want to get.
@result A void* that is the context’s shared data, if the context has shared data, otherwise NULL.
@function
@abstract Creates a JavaScript context group.
@discussion A JSContextGroup associates JavaScript contexts with one another.
Contexts in the same group may share and exchange JavaScript objects. Sharing and/or exchanging
JavaScript objects between contexts in different groups will produce undefined behavior.
When objects from the same context group are used in multiple threads, explicit
synchronization is required.
@function
@abstract Gets the shared data pointer
@param ctx The JSContext whose global object you want to get.
@param data A void* to set as the context’s shared data. Pass NULL to specify no shared data.
@function JSEvaluateScript
@abstract Evaluates a string of JavaScript.
@param ctx The execution context to use.
@param script A JSString containing the script to evaluate.
@param thisObject The object to use as “this,” or NULL to use the global object as “this.”
@param sourceURL A JSString containing a URL for the script’s source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
@param startingLineNumber An integer value specifying the script’s starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The JSValue that results from evaluating script, or NULL if an exception is thrown.
@function JSGarbageCollect
@abstract Performs a JavaScript garbage collection.
@param ctx The execution context to use.
@discussion JavaScript values that are on the machine stack, in a register,
protected by JSValueProtect, set as the global object of an execution context,
or reachable from any such value will not be collected.
@function JSGetMemoryUsageStatistics
@abstract Returns the current memory usage of a context.
@param ctx The execution context to use.
@result A JSObjectRef containing the memory usage statistics.
@function
@abstract Gets a copy of the name of a context.
@param ctx The JSGlobalContext whose name you want to get.
@result The name for ctx.
@discussion A JSGlobalContext’s name is exposed when inspecting the context to make it easier to identify the context you would like to inspect.
@function
@abstract Creates a global JavaScript execution context.
@discussion JSGlobalContextCreate allocates a global object and populates it with all the
built-in JavaScript objects, such as Object, Function, String, and Array.
@function
@abstract Creates a global JavaScript execution context in the context group provided.
@discussion JSGlobalContextCreateInGroup allocates a global object and populates it with
all the built-in JavaScript objects, such as Object, Function, String, and Array.
@param globalObjectClass The class to use when creating the global object. Pass
NULL to use the default object class.
@param group The context group to use. The created global context retains the group.
Pass NULL to create a unique group for the context.
@result A JSGlobalContext with a global object of class globalObjectClass and a context
group equal to group.
@function
@abstract Gets whether the context is inspectable in Web Inspector.
@param ctx The JSGlobalContext that you want to change the inspectability of.
@result Whether the context is inspectable in Web Inspector.
@function
@abstract Retains a global JavaScript execution context.
@param ctx The JSGlobalContext to retain.
@result A JSGlobalContext that is the same as ctx.
@function
@abstract Sets whether the context is inspectable in Web Inspector. Default value is NO.
@param ctx The JSGlobalContext that you want to change the inspectability of.
@param inspectable YES to allow Web Inspector to connect to the context, otherwise NO.
@function
@abstract Sets the name exposed when inspecting a context.
@param ctx The JSGlobalContext that you want to name.
@param name The name to set on the context.
@function
@abstract Sets the callback function that will be called when an uncaught exception occurs on the main thread.
@param ctx The JSGlobalContext whose uncaught exception callback you want to set.
@param callback The JSObjectRef to call when an uncaught exception occurs. Pass NULL to remove the callback.
@function
@abstract Sets the callback function that will be called when an uncaught exception occurs.
@param ctx The JSGlobalContext whose uncaught exception callback you want to set.
@param callback The JSObjectRef to call when an uncaught exception occurs. Pass NULL to remove the callback.
@function
@abstract Sets the callback function that will be called when an unhandled promise rejection occurs.
@param ctx The JSGlobalContext whose unhandled promise rejection callback you want to set.
@param function The JSObjectRef to call when an unhandled promise rejection occurs. Pass NULL to remove the callback.
@param exception The exception to pass to the callback. Pass NULL to specify no exception.
@function JSLinkAndEvaluateModule
@abstract Links and evaluates a module.
@param ctx The execution context to use.
@param moduleKey A JSString containing the module key to link and evaluate.
@result The JSValue that results from evaluating the module, or NULL if an exception is thrown.
@function JSLoadAndEvaluateModule
@abstract Evaluates a file containing JavaScript Code.
@param ctx The execution context to use.
@param filename A JSString containing the path to the module to evaluate.
@function JSLoadAndEvaluateModuleFromSource
@abstract Evaluates a string of JavaScript as a module.
@param ctx The execution context to use.
@param module A JSString containing the module code to evaluate.
@param sourceURLString A JSString containing a URL for the script’s source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
@param startingLineNumber An integer value specifying the script’s starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function JSLoadModule
@abstract Loads a module.
@param ctx The execution context to use.
@param moduleKey A JSString containing the module key to load.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function JSLoadModuleFromSource
@abstract Loads a module from a string of JavaScript.
@param ctx The execution context to use.
@param module A JSString containing the module code to load.
@param sourceURLString A JSString containing a URL for the script’s source file. This is used by debuggers and when reporting exceptions. Pass NULL if you do not care to include source file information.
@param startingLineNumber An integer value specifying the script’s starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function
@abstract Calls an object as a constructor.
@param ctx The execution context to use.
@param object The JSObject to call as a constructor.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of arguments to pass to the constructor. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The JSObject that results from calling object as a constructor, or NULL if an exception is thrown or object is not a constructor.
@function
@abstract Calls an object as a function.
@param ctx The execution context to use.
@param object The JSObject to call as a function.
@param thisObject The object to use as “this,” or NULL to use the global object as “this.”
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of arguments to pass to the function. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The JSValue that results from calling object as a function, or NULL if an exception is thrown or object is not a function.
@function
@abstract Gets the names of an object’s enumerable properties.
@param ctx The execution context to use.
@param object The object whose property names you want to get.
@result A JSPropertyNameArray containing the names object’s enumerable properties. Ownership follows the Create Rule.
@function
@abstract Deletes a property from an object.
@param ctx The execution context to use.
@param object The JSObject whose property you want to delete.
@param propertyName A JSString containing the property’s name.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).
@function
@abstract Deletes a property from an object using a JSValueRef as the property key.
@param ctx The execution context to use.
@param object The JSObject whose property you want to delete.
@param propertyKey A JSValueRef containing the property key to use when looking up the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result true if the delete operation succeeds, otherwise false (for example, if the property has the kJSPropertyAttributeDontDelete attribute set).
@discussion This function is the same as performing “delete object[propertyKey]” from JavaScript.
@function
@abstract Returns the number of bytes in a JavaScript data object.
@param ctx The execution context to use.
@param object The JS Arary Buffer object whose length in bytes to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The number of bytes stored in the data object.
@function
@abstract Returns a pointer to the data buffer that serves as the backing store for a JavaScript Typed Array object.
@param object The Array Buffer object whose internal backing store pointer to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A pointer to the raw data buffer that serves as object’s backing store or NULL if object is not an Array Buffer object.
@discussion The pointer returned by this function is temporary and is not guaranteed to remain valid across JavaScriptCore API calls.
@function
@abstract Gets an object’s private data.
@param object A JSObject whose private data you want to get.
@result A void* that is the object’s private data, if the object has private data, otherwise NULL.
@function
@abstract Gets a property from an object.
@param ctx The execution context to use.
@param object The JSObject whose property you want to get.
@param propertyName A JSString containing the property’s name.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The property’s value if object has the property, otherwise the undefined value.
@function
@abstract Gets a property from an object by numeric index.
@param ctx The execution context to use.
@param object The JSObject whose property you want to get.
@param propertyIndex An integer value that is the property’s name.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The property’s value if object has the property, otherwise the undefined value.
@discussion Calling JSObjectGetPropertyAtIndex is equivalent to calling JSObjectGetProperty with a string containing propertyIndex, but JSObjectGetPropertyAtIndex provides optimized access to numeric properties.
@function
@abstract Gets a property from an object using a JSValueRef as the property key.
@param ctx The execution context to use.
@param object The JSObject whose property you want to get.
@param propertyKey A JSValueRef containing the property key to use when looking up the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The property’s value if object has the property key, otherwise the undefined value.
@discussion This function is the same as performing “object[propertyKey]” from JavaScript.
@function
@abstract Gets an object’s prototype.
@param ctx The execution context to use.
@param object A JSObject whose prototype you want to get.
@result A JSValue that is the object’s prototype.
@function
@abstract Returns the JavaScript Array Buffer object that is used as the backing of a JavaScript Typed Array object.
@param ctx The execution context to use.
@param object The JSObjectRef whose Typed Array type data pointer to obtain.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef with a JSTypedArrayType of kJSTypedArrayTypeArrayBuffer or NULL if object is not a Typed Array.
@function
@abstract Returns the byte length of a JavaScript Typed Array object.
@param ctx The execution context to use.
@param object The Typed Array object whose byte length to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The byte length of the Typed Array object or 0 if the object is not a Typed Array object.
@function
@abstract Returns the byte offset of a JavaScript Typed Array object.
@param ctx The execution context to use.
@param object The Typed Array object whose byte offset to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The byte offset of the Typed Array object or 0 if the object is not a Typed Array object.
@function
@abstract Returns a temporary pointer to the backing store of a JavaScript Typed Array object.
@param ctx The execution context to use.
@param object The Typed Array object whose backing store pointer to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A pointer to the raw data buffer that serves as object’s backing store or NULL if object is not a Typed Array object.
@discussion The pointer returned by this function is temporary and is not guaranteed to remain valid across JavaScriptCore API calls.
@function
@abstract Returns the length of a JavaScript Typed Array object.
@param ctx The execution context to use.
@param object The Typed Array object whose length to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The length of the Typed Array object or 0 if the object is not a Typed Array object.
@function
@abstract Tests whether an object has a given property.
@param object The JSObject to test.
@param propertyName A JSString containing the property’s name.
@result true if the object has a property whose name matches propertyName, otherwise false.
@function
@abstract Tests whether an object has a given property using a JSValueRef as the property key.
@param object The JSObject to test.
@param propertyKey A JSValueRef containing the property key to use when looking up the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result true if the object has a property whose name matches propertyKey, otherwise false.
@discussion This function is the same as performing “propertyKey in object” from JavaScript.
@function
@abstract Tests whether an object can be called as a constructor.
@param ctx The execution context to use.
@param object The JSObject to test.
@result true if the object can be called as a constructor, otherwise false.
@function
@abstract Returns a boolean value indicating whether or not a JavaScript value is a detached Typed Array object.
@param ctx The execution context to use.
@param objectRef The JSObjectRef whose Typed Array type data pointer to obtain.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A boolean value indicating whether or not objectRef is a detached Typed Array object.
@function
@abstract Tests whether an object can be called as a function.
@param ctx The execution context to use.
@param object The JSObject to test.
@result true if the object can be called as a function, otherwise false.
@function
@abstract Creates a JavaScript object.
@param ctx The execution context to use.
@param jsClass The JSClass to assign to the object. Pass NULL to use the default object class.
@param data A void* to set as the object’s private data. Pass NULL to specify no private data.
@result A JSObject with the given class and private data.
@discussion The default object class does not allocate storage for private data, so you must provide a non-NULL jsClass to JSObjectMake if you want your object to be able to store private data.
@function
@abstract Creates a JavaScript Array object.
@param ctx The execution context to use.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of data to populate the Array with. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is an Array.
@discussion The behavior of this function does not exactly match the behavior of the built-in Array constructor. Specifically, if one argument
is supplied, this function returns an array with one element.
@function
@abstract Creates a JavaScript Array Buffer object from an existing pointer.
@param ctx The execution context to use.
@param bytes A pointer to the byte buffer to be used as the backing store of the Typed Array object.
@param byteLength The number of bytes pointed to by the parameter bytes.
@param bytesDeallocator The allocator to use to deallocate the external buffer when the Typed Array data object is deallocated.
@param deallocatorContext A pointer to pass back to the deallocator.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef Array Buffer whose backing store is the same as the one pointed to by bytes or NULL if there was an error.
@discussion If an exception is thrown during this function the bytesDeallocator will always be called.
@function
@abstract Convenience method for creating a JavaScript constructor.
@param ctx The execution context to use.
@param jsClass A JSClass that is the class your constructor will assign to the objects its constructs. jsClass will be used to set the constructor’s .prototype property, and to evaluate ‘instanceof’ expressions. Pass NULL to use the default object class.
@param callAsConstructor A JSObjectCallAsConstructorCallback to invoke when your constructor is used in a ‘new’ expression. Pass NULL to use the default object constructor.
@result A JSObject that is a constructor. The object’s prototype will be the default object prototype.
@discussion The default object constructor takes no arguments and constructs an object of class jsClass with no private data. If the constructor is inherited via JS subclassing and the value returned from callAsConstructor was created with jsClass, then the returned object will have it’s prototype overridden to the derived class’s prototype.
@function
@abstract Creates a JavaScript Date object, as if by invoking the built-in Date constructor.
@param ctx The execution context to use.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of arguments to pass to the Date Constructor. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is a Date.
@function
@abstract Creates a JavaScript promise object by invoking the provided executor.
@param ctx The execution context to use.
@param resolve A pointer to a JSObjectRef in which to store the resolve function for the new promise. Pass NULL if you do not care to store the resolve callback.
@param reject A pointer to a JSObjectRef in which to store the reject function for the new promise. Pass NULL if you do not care to store the reject callback.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is a promise or NULL if an exception occurred.
@function
@abstract Creates a JavaScript Error object, as if by invoking the built-in Error constructor.
@param ctx The execution context to use.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of arguments to pass to the Error Constructor. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is an Error.
@function
@abstract Creates a function with a given script as its body.
@param ctx The execution context to use.
@param name A JSString containing the function’s name. This will be used when converting the function to string. Pass NULL to create an anonymous function.
@param parameterCount An integer count of the number of parameter names in parameterNames.
@param parameterNames A JSString array containing the names of the function’s parameters. Pass NULL if parameterCount is 0.
@param body A JSString containing the script to use as the function’s body.
@param sourceURL A JSString containing a URL for the script’s source file. This is only used when reporting exceptions. Pass NULL if you do not care to include source file information in exceptions.
@param startingLineNumber An integer value specifying the script’s starting line number in the file located at sourceURL. This is only used when reporting exceptions. The value is one-based, so the first line is line 1 and invalid values are clamped to 1.
@param exception A pointer to a JSValueRef in which to store a syntax error exception, if any. Pass NULL if you do not care to store a syntax error exception.
@result A JSObject that is a function, or NULL if either body or parameterNames contains a syntax error. The object’s prototype will be the default function prototype.
@discussion Use this method when you want to execute a script repeatedly, to avoid the cost of re-parsing the script before each execution.
@function
@abstract Convenience method for creating a JavaScript function with a given callback as its implementation.
@param ctx The execution context to use.
@param name A JSString containing the function’s name. This will be used when converting the function to string. Pass NULL to create an anonymous function.
@param callAsFunction The JSObjectCallAsFunctionCallback to invoke when the function is called.
@result A JSObject that is a function. The object’s prototype will be the default function prototype.
@function
@abstract Creates a JavaScript RegExp object, as if by invoking the built-in RegExp constructor.
@param ctx The execution context to use.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of arguments to pass to the RegExp Constructor. Pass NULL if argumentCount is 0.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is a RegExp.
@function
@abstract Creates a JavaScript TypeError object, as if by invoking the built-in TypeError constructor.
@param ctx The execution context to use.
@param message A JSString containing the message for the TypeError’s ‘message’ property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObject that is an TypeError.
@function
@abstract Creates a JavaScript Typed Array object with the given number of elements.
@param ctx The execution context to use.
@param arrayType A value identifying the type of array to create. If arrayType is kJSTypedArrayTypeNone or kJSTypedArrayTypeArrayBuffer then NULL will be returned.
@param length The number of elements to be in the new Typed Array.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef that is a Typed Array with all elements set to zero or NULL if there was an error.
@function
@abstract Creates a JavaScript Typed Array object from an existing JavaScript Array Buffer object.
@param ctx The execution context to use.
@param arrayType A value identifying the type of array to create. If arrayType is kJSTypedArrayTypeNone or kJSTypedArrayTypeArrayBuffer then NULL will be returned.
@param buffer An Array Buffer object that should be used as the backing store for the created JavaScript Typed Array object.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef that is a Typed Array or NULL if there was an error. The backing store of the Typed Array will be buffer.
@function
@abstract Creates a JavaScript Typed Array object from an existing JavaScript Array Buffer object with the given offset and length.
@param ctx The execution context to use.
@param arrayType A value identifying the type of array to create. If arrayType is kJSTypedArrayTypeNone or kJSTypedArrayTypeArrayBuffer then NULL will be returned.
@param buffer An Array Buffer object that should be used as the backing store for the created JavaScript Typed Array object.
@param byteOffset The byte offset for the created Typed Array. byteOffset should aligned with the element size of arrayType.
@param length The number of elements to include in the Typed Array.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef that is a Typed Array or NULL if there was an error. The backing store of the Typed Array will be buffer.
@function
@abstract Creates a JavaScript Typed Array object from an existing pointer.
@param ctx The execution context to use.
@param arrayType A value identifying the type of array to create. If arrayType is kJSTypedArrayTypeNone or kJSTypedArrayTypeArrayBuffer then NULL will be returned.
@param bytes A pointer to the byte buffer to be used as the backing store of the Typed Array object.
@param byteLength The number of bytes pointed to by the parameter bytes.
@param bytesDeallocator The allocator to use to deallocate the external buffer when the JSTypedArrayData object is deallocated.
@param deallocatorContext A pointer to pass back to the deallocator.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSObjectRef Typed Array whose backing store is the same as the one pointed to by bytes or NULL if there was an error.
@discussion If an exception is thrown during this function the bytesDeallocator will always be called.
@function
@abstract Implement the async iterable protocol on an object.
@param ctx The execution context to use.
@param object The JSObject to implement the async iterable protocol on.
@param value A zero-argument function that returns an object, conforming to the async iterator protocol.
@param attributes A logically ORed set of JSPropertyAttributes to give to the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function
@abstract Implement the iterator protocol on an object.
@param ctx The execution context to use.
@param object The JSObject to implement the iterator protocol on.
@param value A zero-argument function that returns an object, conforming to the iterator protocol.
@param attributes A logically ORed set of JSPropertyAttributes to give to the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function
@abstract Sets a pointer to private data on an object.
@param object The JSObject whose private data you want to set.
@param data A void* to set as the object’s private data.
@result true if object can store private data, otherwise false.
@discussion The default object class does not allocate storage for private data. Only objects created with a non-NULL JSClass can store private data.
@function
@abstract Sets a property on an object.
@param ctx The execution context to use.
@param object The JSObject whose property you want to set.
@param propertyName A JSString containing the property’s name.
@param value A JSValueRef to use as the property’s value.
@param attributes A logically ORed set of JSPropertyAttributes to give to the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function
@abstract Sets a property on an object by numeric index.
@param ctx The execution context to use.
@param object The JSObject whose property you want to set.
@param propertyIndex The property’s name as a number.
@param value A JSValue to use as the property’s value.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@discussion Calling JSObjectSetPropertyAtIndex is equivalent to calling JSObjectSetProperty with a string containing propertyIndex, but JSObjectSetPropertyAtIndex provides optimized access to numeric properties.
@function
@abstract Sets a property on an object using a JSValueRef as the property key.
@param ctx The execution context to use.
@param object The JSObject whose property you want to set.
@param propertyKey A JSValueRef containing the property key to use when looking up the property.
@param value A JSValueRef to use as the property’s value.
@param attributes A logically ORed set of JSPropertyAttributes to give to the property.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@discussion This function is the same as performing “object[propertyKey] = value” from JavaScript.
@function
@abstract Sets an object’s prototype.
@param ctx The execution context to use.
@param object The JSObject whose prototype you want to set.
@param value A JSValue to set as the object’s prototype.
@function
@abstract Adds a property name to a JavaScript property name accumulator.
@param accumulator The accumulator object to which to add the property name.
@param propertyName The property name to add.
@function
@abstract Gets a count of the number of items in a JavaScript property name array.
@param array The array from which to retrieve the count.
@result An integer count of the number of names in array.
@function
@abstract Gets a property name at a given index in a JavaScript property name array.
@param array The array from which to retrieve the property name.
@param index The index of the property name to retrieve.
@result A JSStringRef containing the property name.
@function
@abstract Retains a JavaScript property name array.
@param array The JSPropertyNameArray to retain.
@result A JSPropertyNameArray that is the same as array.
@function JSSetAPIModuleLoader
@abstract Sets the moduleLoader used to load and evaluate modules.
@param ctx The execution context to use.
@param moduleLoader A JSAPIModuleLoader structure containing the callbacks to use.
@function JSSetSyntheticModuleKeys
@abstract Sets the synthetic module keys.
@param ctx The execution context to use.
@param argumentCount The number of keys.
@param keys An array of JSString containing the keys.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@function
@abstract Creates a CFString from a JavaScript string.
@param alloc The alloc parameter to pass to CFStringCreate.
@param string The JSString to copy into the new CFString.
@result A CFString containing string. Ownership follows the Create Rule.
@function
@abstract Creates a JavaScript string from a CFString.
@discussion This function is optimized to take advantage of cases when
CFStringGetCharactersPtr returns a valid pointer.
@param string The CFString to copy into the new JSString.
@result A JSString containing string. Ownership follows the Create Rule.
@function
@abstract Creates a JavaScript string from a buffer of Unicode characters.
@param chars The buffer of Unicode characters to copy into the new JSString.
@param numChars The number of characters to copy from the buffer pointed to by chars.
@result A JSString containing chars. Ownership follows the Create Rule.
@function
@abstract Creates a JavaScript string from a null-terminated UTF8 string.
@param string The null-terminated UTF8 string to copy into the new JSString.
@result A JSString containing string. Ownership follows the Create Rule.
@function
@abstract Returns a pointer to the Unicode character buffer that
serves as the backing store for a JavaScript string.
@param string The JSString whose backing store you want to access.
@result A pointer to the Unicode character buffer that serves as string’s
backing store, which will be deallocated when string is deallocated.
@function
@abstract Returns the number of Unicode characters in a JavaScript string.
@param string The JSString whose length (in Unicode characters) you want to know.
@result The number of Unicode characters stored in string.
@function
@abstract Returns the maximum number of bytes a JavaScript string will
take up if converted into a null-terminated UTF8 string.
@param string The JSString whose maximum converted size (in bytes) you
want to know.
@result The maximum number of bytes that could be required to convert string into a
null-terminated UTF8 string. The number of bytes that the conversion actually ends
up requiring could be less than this, but never more.
@function
@abstract Converts a JavaScript string into a null-terminated UTF8 string,
and copies the result into an external byte buffer.
@param string The source JSString.
@param buffer The destination byte buffer into which to copy a null-terminated
UTF8 representation of string. On return, buffer contains a UTF8 string
representation of string. If bufferSize is too small, buffer will contain only
partial results. If buffer is not at least bufferSize bytes in size,
behavior is undefined.
@param bufferSize The size of the external buffer in bytes.
@result The number of bytes written into buffer (including the null-terminator byte).
@function
@abstract Tests whether two JavaScript strings match.
@param a The first JSString to test.
@param b The second JSString to test.
@result true if the two strings match, otherwise false.
@function
@abstract Tests whether a JavaScript string matches a null-terminated UTF8 string.
@param a The JSString to test.
@param b The null-terminated UTF8 string to test.
@result true if the two strings match, otherwise false.
@function
@abstract Creates a JavaScript string containing the JSON serialized representation of a JS value.
@param ctx The execution context to use.
@param value The value to serialize.
@param indent The number of spaces to indent when nesting. If 0, the resulting JSON will not contains newlines. The size of the indent is clamped to 10 spaces.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSString with the result of serialization, or NULL if an exception is thrown.
@function
@abstract Returns a JavaScript value’s type.
@param ctx The execution context to use.
@param value The JSValue whose type you want to obtain.
@result A value of type JSType that identifies value’s type.
@function
@abstract Returns a JavaScript value’s Typed Array type.
@param ctx The execution context to use.
@param value The JSValue whose Typed Array type to return.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A value of type JSTypedArrayType that identifies value’s Typed Array type, or kJSTypedArrayTypeNone if the value is not a Typed Array object.
@function
@abstract Tests whether a JavaScript value is an array.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value is an array, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the boolean type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the boolean type, otherwise false.
@function
@abstract Tests whether a JavaScript value is a date.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value is a date, otherwise false.
@function
@abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.
@param ctx The execution context to use.
@param a The first value to test.
@param b The second value to test.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result true if the two values are equal, false if they are not equal or an exception is thrown.
@function
@abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
@param ctx The execution context to use.
@param value The JSValue to test.
@param constructor The constructor to test against.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the null type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the null type, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the number type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the number type, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the object type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the object type, otherwise false.
@function
@abstract Tests whether a JavaScript value is an object with a given class in its class chain.
@param ctx The execution context to use.
@param value The JSValue to test.
@param jsClass The JSClass to test against.
@result true if value is an object and has jsClass in its class chain, otherwise false.
@function
@abstract Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
@param ctx The execution context to use.
@param a The first value to test.
@param b The second value to test.
@result true if the two values are strict equal, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the string type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the string type, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the symbol type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the symbol type, otherwise false.
@function
@abstract Tests whether a JavaScript value’s type is the undefined type.
@param ctx The execution context to use.
@param value The JSValue to test.
@result true if value’s type is the undefined type, otherwise false.
@function
@abstract Creates a JavaScript value of the boolean type.
@param ctx The execution context to use.
@param boolean The bool to assign to the newly created JSValue.
@result A JSValue of the boolean type, representing the value of boolean.
@function
@abstract Creates a JavaScript value from a JSON formatted string.
@param ctx The execution context to use.
@param string The JSString containing the JSON string to be parsed.
@result A JSValue containing the parsed value, or NULL if the input is invalid.
@function
@abstract Creates a JavaScript value of the number type.
@param ctx The execution context to use.
@param number The double to assign to the newly created JSValue.
@result A JSValue of the number type, representing the value of number.
@function
@abstract Creates a JavaScript value of the string type.
@param ctx The execution context to use.
@param string The JSString to assign to the newly created JSValue. The
newly created JSValue retains string, and releases it upon garbage collection.
@result A JSValue of the string type, representing the value of string.
@function
@abstract Creates a JavaScript value of the symbol type.
@param ctx The execution context to use.
@param description A description of the newly created symbol value.
@result A unique JSValue of the symbol type, whose description matches the one provided.
@function
@abstract Protects a JavaScript value from garbage collection.
@param ctx The execution context to use.
@param value The JSValue to protect.
@discussion Use this method when you want to store a JSValue in a global or on the heap, where the garbage collector will not be able to discover your reference to it.
@function
@abstract Converts a JavaScript value to boolean and returns the resulting boolean.
@param ctx The execution context to use.
@param value The JSValue to convert.
@result The boolean result of conversion.
@function
@abstract Converts a JavaScript value to number and returns the resulting number.
@param ctx The execution context to use.
@param value The JSValue to convert.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The numeric result of conversion, or NaN if an exception is thrown.
@function
@abstract Converts a JavaScript value to object and returns the resulting object.
@param ctx The execution context to use.
@param value The JSValue to convert.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result The JSObject result of conversion, or NULL if an exception is thrown.
@function
@abstract Converts a JavaScript value to string and copies the result into a JavaScript string.
@param ctx The execution context to use.
@param value The JSValue to convert.
@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
@result A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.
@function
@abstract Unprotects a JavaScript value from garbage collection.
@param ctx The execution context to use.
@param value The JSValue to unprotect.
@discussion A value may be protected multiple times and must be unprotected an
equal number of times before becoming eligible for garbage collection.
@typedef CFArrayApplierFunction
Type of the callback function used by the apply functions of
CFArrays.
@param value The current value from the array.
@param context The user-defined context parameter given to the apply
function.
@typedef CFArrayCallBacks
Structure containing the callbacks of a CFArray.
@field version The version number of the structure type being passed
in as a parameter to the CFArray creation functions. This
structure is version 0.
@field retain The callback used to add a retain for the array on
values as they are put into the array. This callback returns
the value to store in the array, which is usually the value
parameter passed to this callback, but may be a different
value if a different value should be stored in the array.
The array’s allocator is passed as the first argument.
@field release The callback used to remove a retain previously added
for the array from values as they are removed from the
array. The array’s allocator is passed as the first
argument.
@field copyDescription The callback used to create a descriptive
string representation of each value in the array. This is
used by the CFCopyDescription() function.
@field equal The callback used to compare values in the array for
equality for some operations.
@typedef CFBinaryHeapApplierFunction
Type of the callback function used by the apply functions of
CFBinaryHeap.
@param val The current value from the binary heap.
@param context The user-defined context parameter given to the apply
function.
@typedef CFDictionaryApplierFunction
Type of the callback function used by the apply functions of
CFDictionarys.
@param key The current key for the value.
@param value The current value from the dictionary.
@param context The user-defined context parameter given to the apply
function.
@typedef CFDictionaryKeyCallBacks
Structure containing the callbacks for keys of a CFDictionary.
@field version The version number of the structure type being passed
in as a parameter to the CFDictionary creation functions.
This structure is version 0.
@field retain The callback used to add a retain for the dictionary
on keys as they are used to put values into the dictionary.
This callback returns the value to use as the key in the
dictionary, which is usually the value parameter passed to
this callback, but may be a different value if a different
value should be used as the key. The dictionary’s allocator
is passed as the first argument.
@field release The callback used to remove a retain previously added
for the dictionary from keys as their values are removed from
the dictionary. The dictionary’s allocator is passed as the
first argument.
@field copyDescription The callback used to create a descriptive
string representation of each key in the dictionary. This
is used by the CFCopyDescription() function.
@field equal The callback used to compare keys in the dictionary for
equality.
@field hash The callback used to compute a hash code for keys as they
are used to access, add, or remove values in the dictionary.
@typedef CFSetApplierFunction
Type of the callback function used by the apply functions of
CFSets.
@param value The current value from the set.
@param context The user-defined context parameter given to the apply
function.
@typedef CFSetCopyDescriptionCallBack
Type of the callback function used by CFSets for describing values.
@param value The value to describe.
@result A description of the specified value.
@typedef CFSetEqualCallBack
Type of the callback function used by CFSets for comparing values.
@param value1 The first value to compare.
@param value2 The second value to compare.
@result True if the values are equal, otherwise false.
@typedef CFSetHashCallBack
Type of the callback function used by CFSets for hashing values.
@param value The value to hash.
@result The hash of the value.
@typedef CFSetReleaseCallBack
Type of the callback function used by CFSets for releasing a retain on values.
@param allocator The allocator of the CFSet.
@param value The value to release.
@typedef CFSetRetainCallBack
Type of the callback function used by CFSets for retaining values.
@param allocator The allocator of the CFSet.
@param value The value to retain.
@result The value to store in the set, which is usually the value
parameter passed to this callback, but may be a different
value if a different value should be stored in the set.
@typedef CFStringNormalizationForm
This is the type of Unicode normalization forms as described in
Unicode Technical Report #15. To normalize for use with file
system calls, use CFStringGetFileSystemRepresentation().
@typedef CFTreeApplierFunction
Type of the callback function used by the apply functions of
CFTree.
@param value The current value from the CFTree
@param context The user-defined context parameter give to the apply
function.
@typedef CFTreeCopyDescriptionCallBack
Type of the callback function used to provide a description of the
user-specified info parameter.
@param info A user-supplied info parameter provided in a CFTreeContext.
@result A description of the info parameter.
@typedef CFTreeReleaseCallBack
Type of the callback function used to remove a retain previously
added to the user-specified info parameter.
@param info A user-supplied info parameter provided in a CFTreeContext.
@typedef CFTreeRetainCallBack
Type of the callback function used to add a retain to the user-specified
info parameter. This callback may returns the value to use whenever the
info parameter is retained, which is usually the value parameter passed
to this callback, but may be a different value if a different value
should be used.
@param info A user-supplied info parameter provided in a CFTreeContext.
@result The retained info parameter.
@typedef JSChar
@abstract A UTF-16 code unit. One, or a sequence of two, can encode any Unicode
character. As with all scalar types, endianness depends on the underlying
architecture.
@typedef JSContextGroupRef A group that associates JavaScript contexts with one another. Contexts in the same group may share and exchange JavaScript objects.
@typedef JSModuleLoaderCreateImportMetaProperties
@abstract The callback invoked when creating import meta properties.
@param ctx The execution context to use.
@param key A JSValue containing the module specifier.
@param scriptFetcher A JSValue containing the script fetcher.
@result A JSObjectRef containing the import meta properties.
@typedef JSModuleLoaderEvaluate
@abstract The callback invoked when evaluating a module.
@param ctx The execution context to use.
@param key A JSValue containing the module specifier to evaluate.
@param scriptFetcher A JSValue containing the script fetcher.
@param sentValue A JSValue containing the value to send to the module.
@param resumeMode A JSValue containing the resume mode.
@result A JSValue containing the result of evaluating the module.
@typedef JSModuleLoaderFetch
@abstract The callback invoked when fetching a module.
@param ctx The execution context to use.
@param key A JSValue containing the module specifier to fetch.
@param attributesValue A JSValue containing the attributes.
@param scriptFetcher A JSValue containing the script fetcher.
@result A JSStringRef containing the fetched module.
@typedef JSModuleLoaderResolve
@abstract The callback invoked when resolving a module specifier.
@param ctx The execution context to use.
@param keyValue A JSValue containing the module specifier to resolve.
@param referrerValue A JSValue containing the referrer URL.
@param scriptFetcher A JSValue containing the script fetcher.
@result A JSString containing the resolved module specifier.
@typedef JSObjectCallAsConstructorCallback
@abstract The callback invoked when an object is used as a constructor in a ‘new’ expression.
@param ctx The execution context to use.
@param constructor A JSObject that is the constructor being called.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of the arguments passed to the function.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result A JSObject that is the constructor’s return value.
@discussion If you named your function CallAsConstructor, you would declare it like this:
@typedef JSObjectCallAsFunctionCallback
@abstract The callback invoked when an object is called as a function.
@param ctx The execution context to use.
@param function A JSObject that is the function being called.
@param thisObject A JSObject that is the ‘this’ variable in the function’s scope.
@param argumentCount An integer count of the number of arguments in arguments.
@param arguments A JSValue array of the arguments passed to the function.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result A JSValue that is the function’s return value.
@discussion If you named your function CallAsFunction, you would declare it like this:
@typedef JSObjectConvertToTypeCallback
@abstract The callback invoked when converting an object to a particular JavaScript type.
@param ctx The execution context to use.
@param object The JSObject to convert.
@param type A JSType specifying the JavaScript type to convert to.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result The objects’s converted value, or NULL if the object was not converted.
@discussion If you named your function ConvertToType, you would declare it like this:
@typedef JSObjectDeletePropertyCallback
@abstract The callback invoked when deleting a property.
@param ctx The execution context to use.
@param object The JSObject in which to delete the property.
@param propertyName A JSString containing the name of the property to delete.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result true if propertyName was successfully deleted, otherwise false.
@discussion If you named your function DeleteProperty, you would declare it like this:
@typedef JSObjectFinalizeCallback
@abstract The callback invoked when an object is finalized (prepared for garbage collection). An object may be finalized on any thread.
@param object The JSObject being finalized.
@discussion If you named your function Finalize, you would declare it like this:
@typedef JSObjectGetPropertyCallback
@abstract The callback invoked when getting a property’s value.
@param ctx The execution context to use.
@param object The JSObject to search for the property.
@param propertyName A JSString containing the name of the property to get.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result The property’s value if object has the property, otherwise NULL.
@discussion If you named your function GetProperty, you would declare it like this:
@typedef JSObjectGetPropertyNamesCallback
@abstract The callback invoked when collecting the names of an object’s properties.
@param ctx The execution context to use.
@param object The JSObject whose property names are being collected.
@param propertyNames A JavaScript property name accumulator in which to accumulate the names of object’s properties.
@discussion If you named your function GetPropertyNames, you would declare it like this:
@typedef JSObjectHasInstanceCallback
@abstract hasInstance The callback invoked when an object is used as the target of an ‘instanceof’ expression.
@param ctx The execution context to use.
@param constructor The JSObject that is the target of the ‘instanceof’ expression.
@param possibleInstance The JSValue being tested to determine if it is an instance of constructor.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result true if possibleInstance is an instance of constructor, otherwise false.
@discussion If you named your function HasInstance, you would declare it like this:
@typedef JSObjectHasPropertyCallback
@abstract The callback invoked when determining whether an object has a property.
@param ctx The execution context to use.
@param object The JSObject to search for the property.
@param propertyName A JSString containing the name of the property look up.
@result true if object has the property, otherwise false.
@discussion If you named your function HasProperty, you would declare it like this:
@typedef JSObjectInitializeCallback
@abstract The callback invoked when an object is first created.
@param ctx The execution context to use.
@param object The JSObject being created.
@discussion If you named your function Initialize, you would declare it like this:
@typedef JSObjectSetPropertyCallback
@abstract The callback invoked when setting a property’s value.
@param ctx The execution context to use.
@param object The JSObject on which to set the property’s value.
@param propertyName A JSString containing the name of the property to set.
@param value A JSValue to use as the property’s value.
@param exception A pointer to a JSValueRef in which to return an exception, if any.
@result true if the property was set, otherwise false.
@discussion If you named your function SetProperty, you would declare it like this:
@enum JSType
@abstract A constant identifying the type of a JSValue.
@constant kJSTypeUndefined The unique undefined value.
@constant kJSTypeNull The unique null value.
@constant kJSTypeBoolean A primitive boolean value, one of true or false.
@constant kJSTypeNumber A primitive number value.
@constant kJSTypeString A primitive string value.
@constant kJSTypeObject An object value (meaning that this JSValueRef is a JSObjectRef).
@constant kJSTypeSymbol A primitive symbol value.
@typedef JSTypedArrayBytesDeallocator A function used to deallocate bytes passed to a Typed Array constructor. The function should take two arguments. The first is a pointer to the bytes that were originally passed to the Typed Array constructor. The second is a pointer to additional information desired at the time the bytes are to be freed.
@typedef JSUncaughtExceptionAtEventLoop
@abstract The callback invoked when an exception is not caught in the event loop.
@param ctx The execution context to use.
@param exception A JSValue containing the uncaught exception.
@typedef JSUncaughtExceptionHandler
@abstract The callback invoked when an exception is not caught.
@param ctx The execution context to use.
@param exception A JSValue containing the uncaught exception.
@enum JSPropertyAttribute
@constant kJSPropertyAttributeNone Specifies that a property has no special attributes.
@constant kJSPropertyAttributeReadOnly Specifies that a property is read-only.
@constant kJSPropertyAttributeDontEnum Specifies that a property should not be enumerated by JSPropertyEnumerators and JavaScript for…in loops.
@constant kJSPropertyAttributeDontDelete Specifies that the delete operation should fail on a property.
@enum JSClassAttribute
@constant kJSClassAttributeNone Specifies that a class has no special attributes.
@constant kJSClassAttributeNoAutomaticPrototype Specifies that a class should not automatically generate a shared prototype for its instance objects. Use kJSClassAttributeNoAutomaticPrototype in combination with JSObjectSetPrototype to manage prototypes manually.