CFStringCreateWithCharactersNoCopy(_:_:_:_:)

Creates a string from a buffer of Unicode characters that might serve as the backing store for the object.

Declaration

func CFStringCreateWithCharactersNoCopy(_ alloc: CFAllocator!, _ chars: UnsafePointer<UniChar>!, _ numChars: CFIndex, _ contentsDeallocator: CFAllocator!) -> CFString!

Parameters

alloc:
The allocator to use to allocate memory for the new string. Pass NULL or Kcfallocatordefault to use the current default allocator.
chars:
The Unicode buffer that has been allocated and initialized with Unicode characters.
numChars:
The number of characters in the buffer pointed to by chars. Only this number of characters will be copied to internal storage.
contentsDeallocator:
The allocator to use to deallocate the external buffer when it is no longer needed. You can pass NULL or Kcfallocatordefault to request the default allocator for this purpose. If the buffer does not need to be deallocated, or if you want to assume responsibility for deallocating the buffer (and not have the string deallocate it), pass Kcfallocatornull.

Return Value

An immutable string containing chars, or NULL if there was a problem creating the object. Ownership follows the The Create Rule.

Discussion

Unless the situation warrants otherwise, the returned object does not copy the external buffer to internal storage but instead uses the buffer as its backing store. However, you should never count on the object using the external buffer since it could copy the buffer to internal storage or might even dump the buffer altogether and use alternative means for storing the characters.

The function includes a contentsDeallocator parameter with which to specify an allocator to use for deallocating the external buffer when the string is deallocated. If you want to assume responsibility for deallocating this memory, specify kCFAllocatorNull for this parameter.

If at creation time CFString decides it can’t use the buffer, and there is a contentsDeallocator, it will use this allocator to free the buffer at that time.

Special Considerations

If an error occurs during the creation of the string, then chars is not deallocated. In this case, the caller is responsible for freeing the buffer. This allows the caller to continue trying to create a string with the buffer, without having the buffer deallocated.