# addingPercentEncoding(withAllowedCharacters:) Returns a new string made from the receiver by replacing all characters not in the specified set with percent-encoded characters. ``` func addingPercentEncoding(withAllowedCharacters allowedCharacters: CharacterSet) -> String? ``` ## Parameters `allowedCharacters` The characters not replaced in the string. Typically, you specify one of the predefined character sets for a particular URL component, such as [`urlPathAllowed`](/documentation/Foundation/NSCharacterSet/urlPathAllowed) or [`urlQueryAllowed`](/documentation/Foundation/NSCharacterSet/urlQueryAllowed). ## Return Value Returns the encoded string, or `nil` if the transformation is not possible. ## Discussion Entire URL strings cannot be percent-encoded, because each URL component specifies a different set of allowed characters. For example, the query component of a URL allows the “`@`” character, but that character must be percent-encoded in the password component. UTF-8 encoding is used to determine the correct percent-encoded characters. Any characters in `allowedCharacters` outside of the 7-bit ASCII range are ignored. > Important: > You must not call this method on strings that are already percent-encoded. Calling this method on strings that are already percent-encoded will cause percent characters in a percent-encoded sequence to be percent-encoded twice. ## See Also [`replacingPercentEscapes(using:)`](/documentation/Foundation/NSString/replacingPercentEscapes(using:)) Returns a new string made by replacing in the receiver all percent escapes with the matching characters as determined by a given encoding. [`addingPercentEscapes(using:)`](/documentation/Foundation/NSString/addingPercentEscapes(using:)) Returns a representation of the receiver using a given encoding to determine the percent escapes necessary to convert the receiver into a legal URL string. --- Copyright © 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)