A structure that parses URLs into and constructs URLs from their constituent parts.
This structure parses and constructs URLs according to [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). Its behavior differs subtly from that of the ``URL`` structure, which conforms to older RFCs. However, you can easily obtain a ``URL`` value based on the contents of a ``URLComponents`` value or vice versa.
Members (52)
get · iOS 8.0+
queryItems
TypeScript
get queryItems(): (Array<URLQueryItem>) | null
Swift declaration
var queryItems: [URLQueryItem]? { get set }
The query subcomponent as an array of URLQueryItems.
Each `URLQueryItem` represents a single key-value pair,
Note that a name may appear more than once in a single query string, so the name values are not guaranteed to be unique. If the `URLComponents` has an empty query component, returns an empty array. If the `URLComponents` has no query component, returns nil.
The setter combines an array containing any number of `URLQueryItem`s, each of which represents a single key-value pair, into a query string and sets the `URLComponents` query property. Passing an empty array sets the query component of the `URLComponents` to an empty string. Passing nil removes the query component of the `URLComponents`.
- note: If a name-value pair in a query is empty (i.e. the query string starts with '&', ends with '&', or has "&&" within it), you get a `URLQueryItem` with a zero-length name and a nil value. If a query's name-value pair has nothing before the equals sign, you get a zero-length name. If a query's name-value pair has nothing after the equals sign, you get a zero-length value. If a query's name-value pair has no equals sign, the query name-value pair string is the name and you get a nil value.
set · iOS 8.0+
queryItems
TypeScript
set queryItems(value: (Array<URLQueryItem>) | null)
Swift declaration
var queryItems: [URLQueryItem]? { get set }
The query subcomponent as an array of URLQueryItems.
Each `URLQueryItem` represents a single key-value pair,
Note that a name may appear more than once in a single query string, so the name values are not guaranteed to be unique. If the `URLComponents` has an empty query component, returns an empty array. If the `URLComponents` has no query component, returns nil.
The setter combines an array containing any number of `URLQueryItem`s, each of which represents a single key-value pair, into a query string and sets the `URLComponents` query property. Passing an empty array sets the query component of the `URLComponents` to an empty string. Passing nil removes the query component of the `URLComponents`.
- note: If a name-value pair in a query is empty (i.e. the query string starts with '&', ends with '&', or has "&&" within it), you get a `URLQueryItem` with a zero-length name and a nil value. If a query's name-value pair has nothing before the equals sign, you get a zero-length name. If a query's name-value pair has nothing after the equals sign, you get a zero-length value. If a query's name-value pair has no equals sign, the query name-value pair string is the name and you get a nil value.
get · iOS 8.0+
description
TypeScript
get description(): string
Swift declaration
var description: String { get }
A textual representation of this instance.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(describing:)`
initializer. This initializer works with any type, and uses the custom
`description` property for types that conform to
`CustomStringConvertible`:
struct Point: CustomStringConvertible {
let x: Int, y: Int
var description: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(describing: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `description` property.
get · iOS 16.0+
encodedHost
TypeScript
get encodedHost(): (string) | null
Swift declaration
var encodedHost: String? { get set }
The host subcomponent, percent-encoded.
set · iOS 16.0+
encodedHost
TypeScript
set encodedHost(value: (string) | null)
Swift declaration
var encodedHost: String? { get set }
The host subcomponent, percent-encoded.
get · iOS 9.0+
rangeOfHost
TypeScript
get rangeOfHost(): (SDKHandle) | null
Swift declaration
var rangeOfHost: Range<String.Index>? { get }
The character range of the host in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfPath
TypeScript
get rangeOfPath(): (SDKHandle) | null
Swift declaration
var rangeOfPath: Range<String.Index>? { get }
The character range of the path in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfPort
TypeScript
get rangeOfPort(): (SDKHandle) | null
Swift declaration
var rangeOfPort: Range<String.Index>? { get }
The character range of the port in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfUser
TypeScript
get rangeOfUser(): (SDKHandle) | null
Swift declaration
var rangeOfUser: Range<String.Index>? { get }
The character range of the user in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 8.0+
customMirror
TypeScript
get customMirror(): SDKHandle
Swift declaration
var customMirror: Mirror { get }
The custom mirror for this instance.
If this type has value semantics, the mirror should be unaffected by
subsequent mutations of the instance.
get · iOS 9.0+
rangeOfQuery
TypeScript
get rangeOfQuery(): (SDKHandle) | null
Swift declaration
var rangeOfQuery: Range<String.Index>? { get }
The character range of the query in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfScheme
TypeScript
get rangeOfScheme(): (SDKHandle) | null
Swift declaration
var rangeOfScheme: Range<String.Index>? { get }
The character range of the scheme in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfFragment
TypeScript
get rangeOfFragment(): (SDKHandle) | null
Swift declaration
var rangeOfFragment: Range<String.Index>? { get }
The character range of the fragment in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 9.0+
rangeOfPassword
TypeScript
get rangeOfPassword(): (SDKHandle) | null
Swift declaration
var rangeOfPassword: Range<String.Index>? { get }
The character range of the password in the ``string`` property.
If the component does not exist, nil is returned.
- note: Zero length components are legal. For example, the URL string "scheme://:@/?#" has a zero length user, password, host, query and fragment; the URL strings "scheme:" and "" both have a zero length path.
get · iOS 8.0+
debugDescription
TypeScript
get debugDescription(): string
Swift declaration
var debugDescription: String { get }
A textual representation of this instance, suitable for debugging.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(reflecting:)`
initializer. This initializer works with any type, and uses the custom
`debugDescription` property for types that conform to
`CustomDebugStringConvertible`:
struct Point: CustomDebugStringConvertible {
let x: Int, y: Int
var debugDescription: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(reflecting: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `debugDescription` property.
get · iOS 8.0+ · Deprecated in iOS 100000.0
percentEncodedHost
TypeScript
get percentEncodedHost(): (string) | null
Swift declaration
var percentEncodedHost: String? { get set }
The host subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlHostAllowed`).
set · iOS 8.0+ · Deprecated in iOS 100000.0
percentEncodedHost
TypeScript
set percentEncodedHost(value: (string) | null)
Swift declaration
var percentEncodedHost: String? { get set }
The host subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlHostAllowed`).
get · iOS 8.0+
percentEncodedPath
TypeScript
get percentEncodedPath(): string
Swift declaration
var percentEncodedPath: String { get set }
The path subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlPathAllowed`).
set · iOS 8.0+
percentEncodedPath
TypeScript
set percentEncodedPath(value: string)
Swift declaration
var percentEncodedPath: String { get set }
The path subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlPathAllowed`).
get · iOS 8.0+
percentEncodedUser
TypeScript
get percentEncodedUser(): (string) | null
Swift declaration
var percentEncodedUser: String? { get set }
The user subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlUserAllowed`).
set · iOS 8.0+
percentEncodedUser
TypeScript
set percentEncodedUser(value: (string) | null)
Swift declaration
var percentEncodedUser: String? { get set }
The user subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlUserAllowed`).
get · iOS 8.0+
percentEncodedQuery
TypeScript
get percentEncodedQuery(): (string) | null
Swift declaration
var percentEncodedQuery: String? { get set }
The query subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlQueryAllowed`).
set · iOS 8.0+
percentEncodedQuery
TypeScript
set percentEncodedQuery(value: (string) | null)
Swift declaration
var percentEncodedQuery: String? { get set }
The query subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlQueryAllowed`).
get · iOS 8.0+
percentEncodedFragment
TypeScript
get percentEncodedFragment(): (string) | null
Swift declaration
var percentEncodedFragment: String? { get set }
The fragment subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlFragmentAllowed`).
set · iOS 8.0+
percentEncodedFragment
TypeScript
set percentEncodedFragment(value: (string) | null)
Swift declaration
var percentEncodedFragment: String? { get set }
The fragment subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlFragmentAllowed`).
get · iOS 8.0+
percentEncodedPassword
TypeScript
get percentEncodedPassword(): (string) | null
Swift declaration
var percentEncodedPassword: String? { get set }
The password subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlPasswordAllowed`).
set · iOS 8.0+
percentEncodedPassword
TypeScript
set percentEncodedPassword(value: (string) | null)
Swift declaration
var percentEncodedPassword: String? { get set }
The password subcomponent, percent-encoded.
The getter for this property retains any percent encoding this component may have. Setting this properties assumes the component string is already correctly percent encoded. Attempting to set an incorrectly percent encoded string will cause a `fatalError`.
Although ';' is a legal path character, it is recommended that it be percent-encoded for best compatibility with `URL` (`String.addingPercentEncoding(withAllowedCharacters:)` will percent-encode any ';' characters if you pass `CharacterSet.urlPasswordAllowed`).
get · iOS 11.0+
percentEncodedQueryItems
TypeScript
get percentEncodedQueryItems(): (Array<URLQueryItem>) | null
Swift declaration
var percentEncodedQueryItems: [URLQueryItem]? { get set }
The query subcomponent as an array of percent-encoded URLQueryItems.
The setter combines an array containing any number of `URLQueryItem`s, each of which represents a single key-value pair, into a query string and sets the `URLComponents` query property. This property assumes the query item names and values are already correctly percent-encoded, and that the query item names do not contain the query item delimiter characters '&' and '='. Attempting to set an incorrectly percent-encoded query item or a query item name with the query item delimiter characters '&' and '=' will cause a `fatalError`.
set · iOS 11.0+
percentEncodedQueryItems
TypeScript
set percentEncodedQueryItems(value: (Array<URLQueryItem>) | null)
Swift declaration
var percentEncodedQueryItems: [URLQueryItem]? { get set }
The query subcomponent as an array of percent-encoded URLQueryItems.
The setter combines an array containing any number of `URLQueryItem`s, each of which represents a single key-value pair, into a query string and sets the `URLComponents` query property. This property assumes the query item names and values are already correctly percent-encoded, and that the query item names do not contain the query item delimiter characters '&' and '='. Attempting to set an incorrectly percent-encoded query item or a query item name with the query item delimiter characters '&' and '=' will cause a `fatalError`.
Returns a URL based on the components relative to a base URL.
If the URLComponents has an authority component (user, password, host or port) and a path component, then the path must either begin with "/" or be an empty string. If the URLComponents does not have an authority component (user, password, host or port) and has a path component, the path component must not start with "//". If those requirements are not met, nil is returned.
Initializes URLComponents from a URL, optionally resolving against its base URL.
If resolvingAgainstBaseURL is `true` and url is a relative URL, the components of url.absoluteURL are used. If the url string from the URL is malformed, nil is returned.
get · iOS 8.0+
url
TypeScript
get url(): (string) | null
Swift declaration
var url: URL? { get }
A URL created from the components.
If the URLComponents has an authority component (user, password, host or port) and a path component, then the path must either begin with "/" or be an empty string. If the NSURLComponents does not have an authority component (user, password, host or port) and has a path component, the path component must not start with "//". If those requirements are not met, nil is returned.
get · iOS 8.0+
host
TypeScript
get host(): (string) | null
Swift declaration
var host: String? { get set }
The host subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
set · iOS 8.0+
host
TypeScript
set host(value: (string) | null)
Swift declaration
var host: String? { get set }
The host subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
get · iOS 8.0+
path
TypeScript
get path(): string
Swift declaration
var path: String { get set }
The path subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
set · iOS 8.0+
path
TypeScript
set path(value: string)
Swift declaration
var path: String { get set }
The path subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
get · iOS 8.0+
port
TypeScript
get port(): (number) | null
Swift declaration
var port: Int? { get set }
The port subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Attempting to set a negative port number will cause a fatal error.
set · iOS 8.0+
port
TypeScript
set port(value: (number) | null)
Swift declaration
var port: Int? { get set }
The port subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Attempting to set a negative port number will cause a fatal error.
get · iOS 8.0+
user
TypeScript
get user(): (string) | null
Swift declaration
var user: String? { get set }
The user subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Warning: IETF STD 66 (rfc3986) says the use of the format "user:password" in the userinfo subcomponent of a URI is deprecated because passing authentication information in clear text has proven to be a security risk. However, there are cases where this practice is still needed, and so the user and password components and methods are provided.
set · iOS 8.0+
user
TypeScript
set user(value: (string) | null)
Swift declaration
var user: String? { get set }
The user subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Warning: IETF STD 66 (rfc3986) says the use of the format "user:password" in the userinfo subcomponent of a URI is deprecated because passing authentication information in clear text has proven to be a security risk. However, there are cases where this practice is still needed, and so the user and password components and methods are provided.
get · iOS 8.0+
query
TypeScript
get query(): (string) | null
Swift declaration
var query: String? { get set }
The query subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
set · iOS 8.0+
query
TypeScript
set query(value: (string) | null)
Swift declaration
var query: String? { get set }
The query subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
get · iOS 8.0+
scheme
TypeScript
get scheme(): (string) | null
Swift declaration
var scheme: String? { get set }
The scheme subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Attempting to set the scheme with an invalid scheme string will cause an exception.
set · iOS 8.0+
scheme
TypeScript
set scheme(value: (string) | null)
Swift declaration
var scheme: String? { get set }
The scheme subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Attempting to set the scheme with an invalid scheme string will cause an exception.
Initializes URLComponents from a URL string, with option to encode invalid characters.
If `encodingInvalidCharacters` is false, and the URL string is invalid according to RFC 3986, `nil` is returned.
If `encodingInvalidCharacters` is true, `URLComponents` will try to encode the string to create a valid URL.
If the URL string is still invalid after encoding, `nil` is returned.
- Parameter string: The URL string.
- Parameter encodingInvalidCharacters: True if `URLComponents` should try to encode an invalid URL string, false otherwise.
- Returns: A `URLComponents` struct for a valid URL, or `nil` if the URL is invalid.
Initializes URLComponents from a URL string.
Returns nil if the URL string is malformed.
get · iOS 8.0+
string
TypeScript
get string(): (string) | null
Swift declaration
var string: String? { get }
A URL string derived from the components.
If the URLComponents has an authority component (user, password, host or port) and a path component, then the path must either begin with "/" or be an empty string. If the URLComponents does not have an authority component (user, password, host or port) and has a path component, the path component must not start with "//". If those requirements are not met, nil is returned.
get · iOS 8.0+
fragment
TypeScript
get fragment(): (string) | null
Swift declaration
var fragment: String? { get set }
The fragment subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
set · iOS 8.0+
fragment
TypeScript
set fragment(value: (string) | null)
Swift declaration
var fragment: String? { get set }
The fragment subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
get · iOS 8.0+
password
TypeScript
get password(): (string) | null
Swift declaration
var password: String? { get set }
The password subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Warning: IETF STD 66 (rfc3986) says the use of the format "user:password" in the userinfo subcomponent of a URI is deprecated because passing authentication information in clear text has proven to be a security risk. However, there are cases where this practice is still needed, and so the user and password components and methods are provided.
set · iOS 8.0+
password
TypeScript
set password(value: (string) | null)
Swift declaration
var password: String? { get set }
The password subcomponent.
The getter for this property removes any percent encoding this component may have (if the component allows percent encoding). Setting this property assumes the subcomponent or component string is not percent encoded and will add percent encoding (if the component allows percent encoding).
Warning: IETF STD 66 (rfc3986) says the use of the format "user:password" in the userinfo subcomponent of a URI is deprecated because passing authentication information in clear text has proven to be a security risk. However, there are cases where this practice is still needed, and so the user and password components and methods are provided.
