Instance Property

queryItems

The query URL component as an array of name/value pairs.

Declaration

@property(copy) NSArray<NSURLQueryItem *> *queryItems;

Discussion

When you get this property’s value, the NSURLComponents class parses the query string and returns an array of NSURLQueryItem objects, each of which represents a single key-value pair, in the order in which they appear in the original query string. Because a name may appear more than once in a single query string, the name properties of query items are not guaranteed to be unique. If the query property is an empty string, the queryItems property is an empty array. If the query property is nil, the queryItems property is also nil.

When you set this property’s value, the NSURLComponents class joins each name/value pair with a = delimiter and joins the array with a & delimiter, then sets the query property to the resulting string. Setting the queryItems property to an empty array sets the query property to an empty string, and setting the the queryItems property to nil sets the query property to nil.

To ensure you can compose and decompose URL queries even with empty components, the NSURLComponents class has the following behavior for cases where no name or value is present:

  • If a name-value pair has nothing before its equals sign, the name property of the corresponding query item is a zero-length string.

  • If a name-value pair has nothing after its equals sign, the value property of the corresponding query item is a zero-length string.

  • If a name-value pair has no equals sign, the value property of the corresponding query item is nil.

  • If a name-value pair is empty (that is, the query string starts with &, ends with &, or contains &&), the corresponding query item has a zero-length name and nil value.

For example, in the URL http://www.example.com/index.php?key1=value1&key2=value2, this property’s value is an array of two NSURLQueryItem objects: one whose name property is key1 and whose value property is value1, and one whose name property is key2 and whose value property is value2.

See Also

Accessing Components in Native Format

fragment

The fragment URL component (the part after a # symbol), or nil if not present.

host

The host URL subcomponent, or nil if not present.

password

The password URL subcomponent, or nil if not present.

path

The path URL component, or nil if not present.

port

The port number URL component, or nil if not present.

query

The query URL component as a string, or nil if not present.

scheme

The scheme URL component, or nil if not present.

user

The username URL subcomponent, or nil if not present.