Creates a copy of a string, replacing certain characters with the equivalent percent escape sequence based on the specified encoding.


CFStringRef CFURLCreateStringByAddingPercentEscapes(CFAllocatorRef allocator, CFStringRef originalString, CFStringRef charactersToLeaveUnescaped, CFStringRef legalURLCharactersToBeEscaped, CFStringEncoding encoding);



The allocator to use to allocate memory for the new CFString object. Pass NULL or kCFAllocatorDefault to use the current default allocator.


The CFString object to copy.


Characters whose percent escape sequences you want to leave intact. Pass NULL to specify that all illegal characters be escaped.


Legal characters to be escaped. Pass NULL to specify that no legal characters be replaced.


The encoding to use for the translation. If you are uncertain of the correct encoding, you should use UTF-8 (kCFStringEncodingUTF8), which is the encoding designated by RFC 2396 as the correct encoding for use in URLs.

Return Value

A copy of originalString replacing certain characters. If it does not need to be modified (no percent escape sequences are missing), this function may merely return originalString with its reference count incremented. Ownership follows the create rule. See The Create Rule.


The characters escaped are all characters that are not legal URL characters (based on RFC 2396), plus any characters in legalURLCharactersToBeEscaped, less any characters in charactersToLeaveUnescaped. To simply correct any non-URL characters in an otherwise correct URL string, pass NULL for the allocator, charactersToLeaveEscaped, and legalURLCharactersToBeEscaped parameters, and kCFStringEncodingUTF8 as the encoding parameter.

It may be difficult to use this function to "clean up" unescaped or partially escaped URL strings where sequences are unpredictable and you cannot specify charactersToLeaveUnescaped. Instead, you can "pre-process" a URL string using CFURLCreateStringByReplacingPercentEscapesUsingEncoding then add the escape characters using CFURLCreateStringByAddingPercentEscapes, as shown in the following code fragment.

CFStringRef originalURLString = CFSTR("");
CFStringRef preprocessedString =
    CFURLCreateStringByReplacingPercentEscapesUsingEncoding(kCFAllocatorDefault, originalURLString, CFSTR(""), kCFStringEncodingUTF8);
CFStringRef urlString =
    CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, preprocessedString, NULL, NULL, kCFStringEncodingUTF8);
url = CFURLCreateWithString(kCFAllocatorDefault, urlString, NULL);

See Also

Converting URLs to Other Representations


Creates a CFData object containing the content of a given URL.


Creates a new string by replacing any percent escape sequences with their character equivalent.


Creates a new string by replacing any percent escape sequences with their character equivalent.


Fills a buffer with the file system's native string representation of a given URL's path.


Converts a given URL to a file or directory object.


Returns the URL as a CFString object.