A Simulate implementation of `encodeURIComponent()` in Cocoa Objective-C that provides similar percent-encoding behaviour.

README.md

If you're tired of CFURLCreateStringByAddingPercentEscapes(), try this.

I didn't write a Swift version, but it should be easy for you to adapt.

---

It is both funny and ironic that until today, in 2025, the standard library of Apple’s Cocoa ecosystem still lacks out-of-the-box but versatile APIs that can handle these most basic (and important) things "correctly", and vary with different common scenarios.

NSStringEncodeURIComponent.m

/// Simulate implementation of `encodeURIComponent()` in Cocoa Objective-C that provides similar
/// percent-encoding behaviour.
///
/// Escapes all characters except: `A–Z a–z 0–9 - _ . ! ~ * ' ( )`
+ (NSString *)encodeURIComponent:(NSString *)string {
    NSMutableCharacterSet *uriComponentAllowedCharacterSet;
    
    // Based on `URLQueryAllowedCharacterSet`, while it contains extra characters that need to be
    // escaped as for `encodeURIComponent()`.
    uriComponentAllowedCharacterSet = [NSCharacterSet.URLQueryAllowedCharacterSet mutableCopy];
    
    // Trim the character set by removing the extra characters.
    [uriComponentAllowedCharacterSet removeCharactersInString:@" \"#$%&+,/:;<=>?@[\\]^`{|}"];
    // Note: Or just remove @"$&+,/:;=?@" for short, if relying on the implementation knowledge of
    // characters that already excluded from the built-in allowed set.
    
    return [string stringByAddingPercentEncodingWithAllowedCharacters:uriComponentAllowedCharacterSet];
}

For test reference:

>> encodeURIComponent("\t\r\n0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~😊")

<- "%09%0D%0A0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ%20!%22%23%24%25%26'()*%2B%2C-.%2F%3A%3B%3C%3D%3E%3F%40%5B%5C%5D%5E_%60%7B%7C%7D~%F0%9F%98%8A"

>> NSString *testString = @"\t\r\n0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~😊";
  [... encodeURIComponent:testString];

<- (NSString *) @"%09%0D%0A0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ%20!%22%23%24%25%26'()*%2B%2C-.%2F%3A%3B%3C%3D%3E%3F%40%5B%5C%5D%5E_%60%7B%7C%7D~%F0%9F%98%8A"

Discussion:

Q: Why not use .alphanumericCharacterSet + "-_.!~*'()" (by addCharactersInString)

A: Although it works, the way it works is somehow weird.

On Stack Overflow, many people have pointed out that .alphanumericCharacterSet is actually a HUGE map that includes international character (Unicode) and not just ASCII.

Take a look at [NSCharacterSet.alphanumericCharacterSet bitmapRepresentation]. It covers many Unicode characters.

This leads me to believe that .alphanumericCharacterSet as "AllowedCharacters" is not the intended use.