类

class Form

public class Form {
    public init()
    public init(queryComponent: String)
}

功能：Form 以 key-value 键值对形式存储 http 请求的表单信息，通常为请求 URL 中的 query 部分。

同一个 key 可以对应多个 value，value 以数组形式存储。& 符号分隔多个键值对；= 分隔的左侧作为 key 值，右侧作为 value 值（没有 = 或者 value 为空，均是允许的）。使用示例见 Form 的构造使用。

init()

public init()

功能：构造一个默认的 Form 实例。

示例：

import stdx.encoding.url.*

main() {
    // 使用无参构造函数创建Form实例 
    let form = Form()
}

init(String)

public init(queryComponent: String)

功能：根据 URL 编码的查询字符串，即 URL 实例的 query 部分构造 Form 实例。

解析 URL 编码的查询字符串，得到若干键值对，并将其添加到新构造的 Form 实例中。

参数：

queryComponent: String - URL 的 query 组件部分的字符串，但是不包括组件前面的 ? 符号。

异常：

IllegalArgumentException - 当URL 字符串中包含不符合 utf8 编码规则的字节时，抛出异常。
UrlSyntaxException - 当 URL 字符串中包含非法转义字符时，抛出异常。

示例：

import stdx.encoding.url.*

main() {
    // 使用带参构造函数创建Form实例 
    let form = Form("name=Zhangsan&age=30&city=Nanjing")
}

func add(String, String)

public func add(key: String, value: String): Unit

功能：新增 key-value 映射，如果 key 已存在，则将 value 添加到原来 value 数组的最后面。

参数：

key: String - 指定键，可以是新增的。
value: String - 将该值添加到指定键对应的值数组中。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例 
    let form = Form()

    // 添加键值对 
    form.add("username", "admin")
    form.add("password", "123456")

    println("toEncodeString: ${form.toEncodeString()}")
}

运行结果：

toEncodeString: username=admin&password=123456

func clone()

public func clone(): Form

功能：克隆 Form。

返回值：

Form - 克隆得到的新 Form 实例。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let originalForm = Form("item1=value1&item2=value2")

    // 克隆Form实例 
    let clonedForm = originalForm.clone()

    println("克隆的是否是 Form: ${clonedForm is Form}")
    println("toEncodeString: ${clonedForm.toEncodeString()}")
}

运行结果：

克隆的是否是 Form: true
toEncodeString: item1=value1&item2=value2

func get(String)

public func get(key: String): Option<String>

功能：根据 key 获取第一个对应的 value 值。

情况举例：

当 query 组件部分是 a=b 时，form.get("a")获得 Some(b)。
当 query 组件部分是 a= 时，form.get("a")获得 Some()。
当 query 组件部分是 a 时，form.get("a")获得 Some()。
当 query 组件部分是 a 时，form.get("c")获得 None。

参数：

key: String - 指定键。

返回值：

Option<String> - 根据指定键获取的第一个值，用 Option<String> 类型表示。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let form = Form()
    form.add("username", "admin")
    form.add("email", "[email protected]")

    // 获取指定键的值 
    let usernameResult = form.get("username")
    let emailResult = form.get("email")
    let nonexistentResult = form.get("nonexistent")

    println("username: ${usernameResult}")
    println("email: ${emailResult}")
    println("nonexistent: ${nonexistentResult}")
}

运行结果：

username: Some(admin)
email: Some([email protected])
nonexistent: None

func getAll(String)

public func getAll(key: String): ArrayList<String>

功能：根据指定的键（key）获取该键（key）对应的所有 value 值。

参数：

key: String - 用户指定的键（key），用于获取对应的 value 值。

返回值：

ArrayList<String> - 根据指定键（key）获取的全部 value 值对应的数组。当指定键（key）不存在时，返回空数组。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let form = Form()
    form.add("tag", "red")
    form.add("tag", "blue")
    form.add("tag", "green")
    form.add("name", "myForm")

    // 获取指定键的所有值 
    let tagValues = form.getAll("tag")
    let nameValues = form.getAll("name")
    let nonexistentValues = form.getAll("nonexistent")

    println("tagValues: ${tagValues}")
    println("nameValues: ${nameValues}")
    println("nonexistentValues: ${nonexistentValues}")
}

运行结果：

tagValues: [red, blue, green]
nameValues: [myForm]
nonexistentValues: []

func isEmpty()

public func isEmpty(): Bool

功能：判断 Form 是否为空。

返回值：

Bool - 如果为空，则返回 true；否则，返回 false。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个空Form实例 
    let emptyForm = Form()

    // 检查Form是否为空 
    let isEmpty = emptyForm.isEmpty()

    // 添加一些数据后再检查 
    emptyForm.add("key", "value")
    let isNotEmpty = emptyForm.isEmpty()

    println("是否为空: ${isEmpty}")
    println("添加数据后是否为空: ${isNotEmpty}")
}

运行结果：

是否为空: true
添加数据后是否为空: false

func remove(String)

public func remove(key: String): Unit

功能：删除 key 及其对应 value。

参数：

key: String - 需要删除的键。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let form = Form()
    form.add("username", "admin")
    form.add("password", "secret")

    // 移除指定的键值对 
    form.remove("password")
    // 移除不存在的键值对，无异常
    form.remove("nonexistent")

    println("toEncodeString: ${form.toEncodeString()}")
}

运行结果：

toEncodeString: username=admin

func set(String, String)

public func set(key: String, value: String): Unit

功能：重置指定 key 对应的 value。

参数：

key: String - 指定键。
value: String - 将指定键的值设置为 value。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let form = Form()
    form.add("key1", "value1")

    // 重置指定键的值 
    form.set("key1", "newvalue1")
    // 重置不存在的键的值，会创建新的键值对
    form.set("key2", "value2")

    println("toEncodeString: ${form.toEncodeString()}")
}

运行结果：

toEncodeString: key1=newvalue1&key2=value2

func toEncodeString()

public func toEncodeString(): String

功能：对表单中的键值对进行编码，编码采用百分号编码。

未保留字符不会被编码，空格将编码为 '+'。

说明：

RFC 3986 协议中对未保留字符定义如下： unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

返回值：

String - 编码后的字符串。

示例：

import stdx.encoding.url.*

main() {
    // 创建一个Form实例并添加一些键值对 
    let form = Form()
    // 存在空格
    form.add("name", "Zhang san")
    // 存在保留字符‘-’，不会进行编码
    form.add("生日", "2026-1-8")
    // 存在特殊字符，会进行编码
    form.add("email", "[email protected]")

    // 将表单转换为编码字符串 
    let encodedString = form.toEncodeString()

    println("toEncodeString: ${encodedString}")
}

运行结果：

toEncodeString: name=Zhang+san&%E7%94%9F%E6%97%A5=2026-1-8&email=zhangsan%40example.com

合并规则：将引用路径 refPath 追加到基础路径 basePath 的最后一段。如果 refPath 是绝对路径，结果就是 refPath 原本的值。如果 refPath 不是绝对路径，则将自身拼接至 basePath 最后一个 / 后，所有结果最终都会进行标准化（路径中的.字符，..字符，以及多个连续的 / 字符都会被优化）。具体行为可以参照下面示例。更详细行为参考 RFC 3986 协议。

如需合并 URL 请使用 resolveURL。

例如：

/a/b/c 合并 /d 输出 /d。
/a/b/c 合并 d 输出 /a/b/d。
/a/b/ 合并 d/e/../f 输出 /a/b/d/f。
/a/b/c/ 合并 ./../../g 输出 /a/g。

参数：

basePath: String - 基础路径。
refPath: String - 引用路径。

返回值：

String - 合并且标准化后的路径。

示例：

import stdx.encoding.url.*

main() {
    // 合并路径
    let basePath = "/a/b/c"
    let refPath = "d"
    let mergedPath = URL.mergePaths(basePath, refPath)

    println("URL mergePaths: ${mergedPath}")
}

运行结果：

URL mergePaths: /a/b/d

static func parse(String)

public static func parse(rawUrl: String): URL

功能：将原始 URL 字符串解析成 URL 对象。

这个函数会将 URL 按照组件分解，然后分别进行解码并存储在相应的组件属性中，而 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性部分存储的是原始值，不做编解码处理。

使用示例请参见URL 解析函数 parse 的使用。

注意：

该函数可以解析 URL 中的用户名和密码（如果存在），这是符合 RFC 3986 协议的解析功能的，但是 RFC 3986 也明确指出，任何场景下，明文保存用户信息存在被泄露风险，所以建议不要在 URL 中明文保存用户信息。

参数：

rawUrl: String - URL 字符串。

返回值：

URL - 解析字符串得到的 URL 实例。

异常：

UrlSyntaxException - 当 URL 字符串中包含非法字符时，抛出异常。
IllegalArgumentException - 当被编码的字符不符合 UTF-8 的字节序列规则时，抛出异常。

示例：

import stdx.encoding.url.*

main() {
    // 解析URL字符串
    let url = URL.parse("https://example.com:8080/path?query=value#fragment")

    println("URL parsed: ${url}")
}

运行结果：

URL parsed: https://example.com:8080/path?query=value#fragment

func isAbsoluteURL()

public func isAbsoluteURL(): Bool

功能：判断 URL 是否为绝对 URL（scheme 存在时，URL 是绝对 URL）。

返回值：

Bool - scheme 存在时返回 true，不存在时返回 false。

示例：

import stdx.encoding.url.*

main() {
    // 解析URL字符串
    let url = URL.parse("https://example.com:8080/path?query=value#fragment")
    let isAbsolute = url.isAbsoluteURL()
    println("isAbsolute isAbsoluteURL: ${isAbsolute}")

    let url1 = URL.parse("/path?query=value#fragment")
    let notAbsolute = url1.isAbsoluteURL()
    println("notAbsolute isAbsoluteURL: ${notAbsolute}")
}

运行结果：

isAbsolute isAbsoluteURL: true
notAbsolute isAbsoluteURL: false

func replace(Option<String>, Option<String>, Option<String>, Option<String>, Option<String>, Option<String>, Option<String>)

public func replace(scheme!: Option<String> = None, userInfo!: Option<String> = None,
 hostName!: Option<String> = None, port!: Option<String> = None, path!: Option<String> = None, 
 query!: Option<String> = None, fragment!: Option<String> = None): URL

功能：替换 URL 对象的各组件，并且返回一个新的 URL 对象。

替换时需要满足以下要求：

方案 scheme 为空时，主机名必须为空。
主机名为空时，用户信息或端口号必须为空。
方案 scheme 不为空时，主机名和路径不能同时为空。
方案 scheme 不为空时，路径必须是绝对路径。
任意组件均为合法字符。

参数：

scheme!: Option<String> - 协议组件。
userInfo!: Option<String> - 用户信息。
hostName!: Option<String> - 主机名。
port!: Option<String> - 端口号。
path!: Option<String> - 资源路径。
query!: Option<String> - 查询组件。
fragment!: Option<String> - 锚点组件。

返回值：

URL - 新的 URL 对象。

异常：

UrlSyntaxException - 不满足替换要求时，抛出异常。

示例：

import stdx.encoding.url.*

main() {
    // 解析URL字符串
    let url = URL.parse("https://example.com:8080/path?query=value#fragment")

    // 替换URL组件
    let newUrl = url.replace(path: Some("/newpath"))

    println("URL replace: ${newUrl}")
}

运行结果：

URL replace: https://example.com:8080/newpath?query=value#fragment

func resolveURL(URL)

public func resolveURL(ref: URL): URL

功能：以当前 URL 实例为基础 URL，以传入的 URL 为参考 URL，根据 RFC 3986 协议生成一个新的 URL 实例。

例如：http://a/b/c/d;p?q 为基础 URL，以下 = 左边为参考 URL，右边为生成的新 URL：

"g" = "http://a/b/c/g"
"/g" = "http://a/g"
"g?y" = "http://a/b/c/g?y"
"g?y#s" = "http://a/b/c/g?y#s"
"../" = "http://a/b/"

更多详细的 URL 生成规则，请参见 RFC 3968 协议。

参数：

ref: URL - 参考 URL 对象。

返回值：

URL - 新的 URL 实例。

示例：

import stdx.encoding.url.*

main() {
    // 解析基础URL
    let baseUrl = URL.parse("http://a/b/c/d;p?q")
    // 解析参考URL
    let refUrl = URL.parse("g")

    // 解析URL
    let resolvedUrl = baseUrl.resolveURL(refUrl)

    println("URL resolveURL: ${resolvedUrl}")
}

运行结果：

URL resolveURL: http://a/b/c/g

func toString()

public func toString(): String

功能：获取当前 URL 实例的字符串值。

会把 hostName 编码，其余部分取 rawXXX (此处泛指前缀是 raw 的 URL 属性)属性值，按照 URL 组件构成顺序进行拼接而获得该函数返回值。

返回值：

String - 当前 URL 实例的字符串值。

示例：

import stdx.encoding.url.*

main() {
    // 解析URL字符串
    let url = URL.parse("https://example.com:8080/path?query=value#fragment")

    // 获取URL字符串表示
    let urlString = url.toString()

    println("URL toString: ${urlString}")
}

运行结果：

URL toString: https://example.com:8080/path?query=value#fragment

class UserInfo

public class UserInfo <: ToString {
    public init()
    public init(userName: String)
    public init(userName: String, passWord: String)
    public init(userName: String, passWord: Option<String>)
}

功能：UserInfo 表示 URL 中用户名和密码信息。

注意：

RFC 3986 明确指出，任何场景下，明文保存用户信息存在被泄露风险，所以建议不要在 URL 中明文保存用户信息。

父类型：

ToString

init()

public init()

功能：创建 UserInfo 实例。

示例：

import stdx.encoding.url.*

main() {
    // 使用无参构造函数创建UserInfo实例 
    let userInfo = UserInfo()
}

init(String)

public init(userName: String)

功能：根据用户名创建 UserInfo 实例。

参数：

userName: String - 用户名。

示例：

import stdx.encoding.url.*

main() {
    // 使用用户名参数创建UserInfo实例 
    let userInfo = UserInfo("Zhangsan")

    println("UserInfo: ${userInfo}")
}

运行结果：

UserInfo: Zhangsan

init(String, Option<String>)

public init(userName: String, passWord: Option<String>)

功能：根据用户名和密码创建 UserInfo 实例。参数：

userName: String - 用户名。
passWord: Option<String> - 密码，用 Option<String> 类型表示。

示例：

import stdx.encoding.url.*

main() {
    // 使用用户名和密码创建UserInfo实例 
    let userInfo = UserInfo("admin", Some("password123"))

    println("UserInfo带用户名和密码: ${userInfo}")
}

运行结果：

UserInfo带用户名和密码: admin:password123

init(String, String)

public init(userName: String, passWord: String)

功能：根据用户名和密码创建 UserInfo 实例。参数：

userName: String - 用户名。
passWord: String - 密码。

示例：

import stdx.encoding.url.*

main() {
    // 使用用户名和密码创建UserInfo实例 
    let userInfo = UserInfo("admin", "password123")

    println("UserInfo带用户名和密码: ${userInfo}")
}

运行结果：

UserInfo带用户名和密码: admin:password123

func password()

public func password(): Option<String>

功能：获取密码信息。

注意：

RFC 3986 明确指出，任何场景下，明文保存用户信息存在被泄露风险，所以建议不要在 URL 中明文保存用户信息。

返回值：

Option<String> - 将密码以 Option<String> 形式返回。

示例：

import stdx.encoding.url.*

main() {
    // 创建UserInfo实例 
    let userInfo = UserInfo("admin", "password123")

    // 获取密码信息 
    let passwordOption = userInfo.password()

    println("UserInfo password: ${passwordOption}")
}

运行结果：

UserInfo password: Some(password123)

func toString()

public func toString(): String

功能：将当前 UserInfo 实例转换为字符串。

返回值：

String - 当前 UserInfo 实例的字符串表示。

示例：

import stdx.encoding.url.*

main() {
    // 创建UserInfo实例 
    let userInfo = UserInfo("admin", "password123")

    // 获取字符串表示 
    let userInfoString = userInfo.toString()

    println("UserInfo toString方法示例: ${userInfoString}")
}

运行结果：

UserInfo toString方法示例: admin:password123

func username()

public func username(): String

功能：获取用户名信息。

返回值：

String - 字符串类型的用户名。

示例：

import stdx.encoding.url.*

main() {
    // 创建UserInfo实例 
    let userInfo = UserInfo("admin", "password123")

    // 获取用户名信息 
    let username = userInfo.username()

    println("UserInfo username: ${username}")
}

运行结果：

UserInfo username: admin

Keyboard shortcuts