Latest 0.1
License MIT
Platforms ios 8.0, osx 10.10, watchos 2.0, tvos 9.0

A type-safe and friendly Swift API for query items


queryItems is defined as [NSURLQueryItem]?, which makes it slightly annoying to work with if you need to grab and modify items in the query string:

  • The array of NSURLQueryItems is an Optional, which makes sense since the querystring may not be present. But still a hinderance when you want to work it
  • NSURLQueryItem is immutable (good), so need to replaced into queryItems
  • The value of NSURLQueryItem can be exactly one type (String)

While querystrings by nature are typed as strings, in practice we often want to grab an integer or boolean value from a querystring parameter.


You’ll initialize the QueryItemWrangler with an optional array of NSURLQueryItem:

let url = NSURL(string: "")!
let components = NSURLComponents(URL: url, resolvingAgainstBaseURL: true)!
var wrangler = QueryItemWrangler(items: components.queryItems)

The simplest API is for reading and writing strings:

wrangler["str"] // => Optional("foo bar"))
wrangler["str"] = "baz"
wrangler["str"] // => Optional("baz"))

To work with other types, the QueryItemKey struct can be used to represent the item key/name and the type of its value:

let key = QueryItemKey<Int?>("num") // The type of the item named "num" is `Int?`
wrangler[key] // => Optional(42)
wrangler[key] = 84
wrangler[key] // => Optional(84)

wrangler[QueryItemKey<Int>("num")] // => 88
// Non-optional Int's default to 0 if the value is nil
wrangler[QueryItemKey<Int?>("num")] = nil
wrangler[QueryItemKey<Int>("num")] // => 0
wrangler[QueryItemKey<Int?>("num")] // => nil

Boolean values are either true or false (nil is false):

wrangler[QueryItemKey<Bool>("flag")] // => true
wrangler[QueryItemKey<Bool>("flag")] = false
wrangler[QueryItemKey<Bool>("flag")] // => false
wrangler[QueryItemKey<Bool>("flag2")] // => true

To update the originating NSURLComponents, simply assign to the queryItems property:

components.queryItems = wrangler.queryItems

Supported types

QueryItemKey can be used as subscripting in QueryItemWrangler for the following types:

  • String
  • String?
  • Int
  • Int?
  • Bool


QueryItemWrangler was created by Johan Sørensen



Latest podspec

    "name": "QueryItemWrangler",
    "version": "0.1",
    "summary": "A type-safe and friendly Swift API for NSURLComponents query items",
    "description": "Easily manipulate NSURLQueryItem's in a type safe and swiftly manner",
    "homepage": "",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    "authors": {
        "Johan Su00f8rensen": "[email protected]"
    "social_media_url": "",
    "platforms": {
        "ios": "8.0",
        "osx": "10.10",
        "watchos": "2.0",
        "tvos": "9.0"
    "source": {
        "git": "",
        "tag": "0.1"
    "source_files": "Source/*.swift"

Pin It on Pinterest

Share This