<!--
{
  "availability" : [
    "iOS: 2.0.0 - 9.0.0",
    "iPadOS: 2.0.0 - 9.0.0",
    "macCatalyst: 13.1.0 - 13.1.0",
    "macOS: 10.0.0 - 10.11.0",
    "tvOS: 9.0.0 - 9.0.0",
    "visionOS: 1.0.0 - 1.0.0",
    "watchOS: 2.0.0 - 2.0.0"
  ],
  "documentType" : "symbol",
  "framework" : "CoreFoundation",
  "identifier" : "/documentation/CoreFoundation/CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)",
  "metadataVersion" : "0.1.0",
  "role" : "Function",
  "symbol" : {
    "kind" : "Function",
    "modules" : [
      "Core Foundation"
    ],
    "preciseIdentifier" : "c:@F@CFURLCreateStringByAddingPercentEscapes"
  },
  "title" : "CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)"
}
-->

# CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)

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

```
func CFURLCreateStringByAddingPercentEscapes(_ allocator: CFAllocator!, _ originalString: CFString!, _ charactersToLeaveUnescaped: CFString!, _ legalURLCharactersToBeEscaped: CFString!, _ encoding: CFStringEncoding) -> CFString!
```

## Parameters

`allocator`

The allocator to use to allocate memory for the new `CFString` object. Pass `NULL` or [`kCFAllocatorDefault`](/documentation/CoreFoundation/kCFAllocatorDefault) to use the current default allocator.

`originalString`

The `CFString` object to copy.

`charactersToLeaveUnescaped`

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

`legalURLCharactersToBeEscaped`

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

`encoding`

The encoding to use for the translation. If you are uncertain of the correct encoding, you should use UTF-8 ([`CFStringBuiltInEncodings.UTF8`](/documentation/CoreFoundation/CFStringBuiltInEncodings/UTF8)), 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](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/Concepts/Ownership.html#//apple_ref/doc/uid/20001148-103029).

## Discussion

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 [`CFStringBuiltInEncodings.UTF8`](/documentation/CoreFoundation/CFStringBuiltInEncodings/UTF8) 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(_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateStringByReplacingPercentEscapesUsingEncoding(_:_:_:_:)) then add the escape characters using [`CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)`](/documentation/CoreFoundation/CFURLCreateStringByAddingPercentEscapes(_:_:_:_:_:)), as shown in the following code fragment.

```objc
CFStringRef originalURLString = CFSTR("http://online.store.com/storefront/?request=get-document&doi=10.1175%2F1520-0426(2005)014%3C1157:DODADSS%3E2.0.CO%3B2");
CFStringRef preprocessedString =
    CFURLCreateStringByReplacingPercentEscapesUsingEncoding(kCFAllocatorDefault, originalURLString, CFSTR(""), kCFStringEncodingUTF8);
CFStringRef urlString =
    CFURLCreateStringByAddingPercentEscapes(kCFAllocatorDefault, preprocessedString, NULL, NULL, kCFStringEncodingUTF8);
url = CFURLCreateWithString(kCFAllocatorDefault, urlString, NULL);
```

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)