json 包

介绍

主要用于对 json 数据的处理，实现 String, JsonValue, DataModel 之间的相互转换。

JsonValue 是对 Json 数据格式的封装，包括 object, array, string, number, true, false 和 null。

DataModel 详细信息可参考 serialization 包文档。

json 语法规则可参考：介绍 JSON。

json 数据转换标准可参考：ECMA-404 The JSON Data Interchange Standard。

主要接口

enum JsonKind

public enum JsonKind {
    | JsNull
    | JsBool
    | JsInt
    | JsFloat
    | JsString
    | JsArray
    | JsObject
}

JsonKind 枚举类型表示 JsonValue 的所有类型。

JsNull

JsNull

JsBool

JsBool

JsInt

JsInt

JsFloat

JsFloat

JsString

JsString

JsArray

JsArray

JsObject

JsObject

class JsonValue

sealed abstract class JsonValue <: ToString

此类为 json 数据层, 主要用于 JsonValue 和 String 数据之间的互相转换。

func fromStr

public static func fromStr(s: String): JsonValue

功能：将字符串数据解析为 JsonValue，对于整数，支持前导 '0b', '0o', '0x'（不区分大小写），分别表示二进制，八进制和十六进制。字符串解析失败时将打印错误字符及其行数和列数，其中列数从错误字符所在行的非空格字符起开始计算。

参数：

  • s：传入字符串，s 暂不支持 ? 和特殊字符

返回值：转换后 JsonValue

异常：

  • 异常 JsonException：如果内存分配失败，或解析字符串出错，抛出异常

func toString

public func toString(): String

功能：将 JsonValue 转换为字符串。

返回值：转换后字符串

异常：

  • 异常 JsonException：如果 json 值不能转换为字符串, 抛出异常

func toJsonString

public func toJsonString(): String

功能：将 JsonValue 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

异常：

  • 异常 JsonException：如果 json 值不能转换为字符串, 抛出异常

func kind

public func kind(): JsonKind

功能：返回当前 JsonValue 所属的 JsonKind 类型。

返回值：当前 JsonValue 所属的 JsonKind 类型

func asNull

public func asNull(): JsonNull

功能：将 JsonValue 转换为 JsonNull 格式。

返回值：转换后 JsonNull

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asBool

public func asBool(): JsonBool

功能：将 JsonValue 转换为 JsonBool 格式。

返回值：转换后 JsonBool

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asInt

public func asInt(): JsonInt

功能：将 JsonValue 转换为 JsonInt 格式。

返回值：转换后 JsonInt

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asFloat

public func asFloat(): JsonFloat

功能：将 JsonValue 转换为 JsonFloat 格式。

返回值：转换后 JsonFloat

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asString

public func asString(): JsonString

功能：将 JsonValue 转换为 JsonString 格式。

返回值：转换后 JsonString

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asArray

public func asArray(): JsonArray

功能：将 JsonValue 转换为 JsonArray 格式。

返回值：转换后 JsonArray

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func asObject

public func asObject(): JsonObject

功能：将 JsonValue 转换为 JsonObject 格式。

返回值：转换后 JsonObject

异常：

  • 异常 JsonException：如果转换失败，抛出异常

class JsonNull

public class JsonNull <: JsonValue

此类为 JsonValue 实现子类, 主要用于封装 null 的 JSON 数据。

func toString

public func toString(): String

功能：将 JsonNull 转换为字符串。

返回值：转换后字符串

func toJsonString

public func toJsonString(): String

功能：将 JsonNull 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

func kind

public func kind(): JsonKind

功能：返回当前 JsonNull 所属的 JsonKind 类型（JsNull）。

返回值：当前 JsonNull 所属的 JsonKind 类型（JsNull）

class JsonBool

public class JsonBool <: JsonValue {
    public init(bv: Bool)
}

此类为 JsonValue 实现子类, 主要用于封装 true 或者 false 的 JSON 数据。

init

public init(bv: Bool)

功能：将指定的 Bool 类型实例封装成 JsonBool 实例。

func getValue

public func getValue(): Bool

功能：获取 JsonBool 中 value 的实际值。

返回值：value 的实际值

func toString

public func toString(): String

功能：将 JsonBool 转换为字符串。

返回值：转换后字符串

func toJsonString

public func toJsonString(): String

功能：将 JsonBool 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

func kind

public func kind(): JsonKind

功能：返回当前 JsonBool 所属的 JsonKind 类型（JsBool）。

返回值：当前 JsonBool 所属的 JsonKind 类型（JsBool）

class JsonInt

public class JsonInt <: JsonValue {
    public init(iv: Int64)
}

此类为 JsonValue 实现子类, 主要用于封装整数类型的 JSON 数据。

init

public init(iv: Int64)

功能：将指定的 Int64 类型实例封装成 JsonInt 实例。

func getValue

public func getValue(): Int64

功能：获取 JsonInt 中 value 的实际值。

返回值：value 的实际值

func toString

public func toString(): String

功能：将 JsonInt 转换为字符串。

返回值：转换后字符串

func toJsonString

public func toJsonString(): String

功能：将 JsonInt 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

func kind

public func kind(): JsonKind

功能：返回当前 JsonInt 所属的 JsonKind 类型（JsInt）。

返回值：当前 JsonInt 所属的 JsonKind 类型（JsInt）

class JsonFloat

public class JsonFloat <: JsonValue {
    public init(fv: Float64)
    public init(v: Int64)
}

此类为 JsonValue 实现子类, 主要用于封装浮点类型的 JSON 数据。

init

public init(fv: Float64)

功能：将指定的 Float64 类型实例封装成 JsonFloat 实例。

参数：

  • fv：Float64 类型

init

public init(v: Int64)

功能：将指定的 Int64 类型实例封装成 JsonFloat 实例。

参数：

  • v：Int64 类型

func getValue

public func getValue(): Float64

功能：获取 JsonFloat 中 value 的实际值。

返回值：value 的实际值

func toString

public func toString(): String

功能：将 JsonFloat 转换为字符串。

返回值：转换后字符串

func toJsonString

public func toJsonString(): String

功能：将 JsonFloat 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

func kind

public func kind(): JsonKind

功能：返回当前 JsonFloat 所属的 JsonKind 类型（JsFloat）。

返回值：当前 JsonFloat 所属的 JsonKind 类型（JsFloat）

class JsonString

public class JsonString <: JsonValue {
    public init(sv: String)
}

此类为 JsonValue 实现子类, 主要用于封装字符串类型的 JSON 数据。

init

public init(sv: String)

功能：将指定的 String 类型实例封装成 JsonString 实例。

func getValue

public func getValue(): String

功能：获取 JsonString 中 value 的实际值。

返回值：value 的实际值

func toString

public func toString(): String

功能：将 JsonString 转换为字符串。

返回值：转换后字符串

func toJsonString

public func toJsonString(): String

功能：将 JsonString 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

func kind

public func kind(): JsonKind

功能：返回当前 JsonString 所属的 JsonKind 类型（JsString）。

返回值：当前 JsonString 所属的 JsonKind 类型（JsString）

class JsonArray

public class JsonArray <: JsonValue {
    public init()
    public init(list: ArrayList<JsonValue>)
    public init(list: Array<JsonValue>)
}

此类为 JsonValue 实现子类, 主要用于封装数组类型的 JSON 数据。

init

public init()

功能：创建空 JsonArray。

init

public init(list: ArrayList<JsonValue>)

功能：将指定的 ArrayList 类型实例封装成 JsonArray 实例。

init

public init(list: Array<JsonValue>)

功能：将指定的 Array 类型实例封装成 JsonArray 实例。

func toJsonString

public func toJsonString(): String

功能：将 JsonArray 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

异常：

  • 异常 JsonException：如果数组中存在 JsonValue 元素无法转为字符串，抛出异常

func toJsonString

public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false): String

功能：将 JsonArray 转换为 Json-String。

参数：

  • depth：JSON 格式缩进深度
  • bracketInNewLine：如果是 false, 第一个括号将不会缩进，其他所有行都会缩进指定深度，true，所有行按照缩进深度跟随缩进，默认是 false

返回值：json 转换的字符串是项字符串数据

异常：

  • 异常 JsonException：如果存在无法转换为字符串的 JsonArray, 则抛出异常

func toString

public func toString(): String

功能：将 JsonString 转换为字符串。

返回值：转换后字符串

异常：

  • 异常 JsonException：如果数组中存在 JsonValue 元素无法转为字符串，抛出异常

func kind

public func kind(): JsonKind

功能：返回当前 JsonArray 所属的 JsonKind 类型（JsArray）。

返回值：当前 JsonArray 所属的 JsonKind 类型（JsArray）

func size

public func size(): Int64

功能：获取 JsonArray 中 JsonValue 的数量。

返回值：JsonArray 中 items 的大小

func add

public func add(jv: JsonValue): JsonArray

功能：向 JsonArray 中加入 JsonValue 数据。

参数：

  • jv：需要加入的 JsonValue

func get

public func get(index: Int64): Option<JsonValue>

功能：获取 JsonArray 中指定索引的 JsonValue，并用 Option 封装。

参数：

  • index：指定的索引

返回值：对应索引的 JsonValue 数据的封装形式

operator func []

public operator func [](index: Int64): JsonValue

功能：获取 JsonArray 中指定索引的 JsonValue。

参数：

  • index：指定的索引

返回值：对应索引的 JsonValue

异常：

  • 异常 JsonException：如果 index 不是 JsonArray 的有效索引，抛出异常

func getItems

public func getItems(): ArrayList<JsonValue>

功能：获取 JsonArray 中的 items 数据。

返回值：JsonArray 的 items 数据

class JsonObject

public class JsonObject <: JsonValue {
    public init()
    public init(map: HashMap<String, JsonValue>)
}

此类为 JsonValue 实现子类, 主要用于封装 object 类型的 JSON 数据。

init

public init()

功能：创建空 JsonObject。

init

public init(map: HashMap<String, JsonValue>)

功能：将指定的 HashMap 类型实例封装成 JsonObject 实例。

func toJsonString

public func toJsonString(): String

功能：将 JsonObject 转换为 json 格式 (带有空格换行符) 字符串。

返回值：转换后 json 格式字符串

异常：

  • 异常 JsonException：如果 JsonObject 中存在 JsonValue 元素无法转为字符串，抛出异常

func toJsonString

public func toJsonString(depth: Int64, bracketInNewLine!: Bool = false): String

功能：将 JsonObject 转换为 Json-String。

参数：

  • depth：JSON 格式缩进深度
  • bracketInNewLine：如果是 false，第一个括号将不会缩进，其他所有行都会缩进指定深度，true，所有行按照缩进深度跟随缩进，默认是 false

返回值：json 转换的字符串是项字符串数据

异常：

  • 异常 JsonException：如果存在无法转换为字符串的 JsonObject，则抛出异常

func toString

public func toString(): String

功能：将 JsonObject 转换为字符串。

返回值：转换后字符串

异常：

  • 异常 JsonException：如果 JsonObject 中存在 JsonValue 元素无法转为字符串，抛出异常

func kind

public func kind(): JsonKind

功能：返回当前 JsonObject 所属的 JsonKind 类型（JsObject）。

返回值：当前 JsonObject 所属的 JsonKind 类型（JsObject）

func size

public func size(): Int64

功能：获取 JsonObject 中 fields 存入 string-JsonValue 的数量。

返回值：JsonObject 中 fields 的大小

func containsKey

public func containsKey(key: String): Bool

功能：判断 JsonObject 中是否存在 key。

参数：

  • key：指定的 key

返回值：存在返回 true，不存在返回 false

func put

public func put(key: String, v: JsonValue)

功能：向 JsonObject 中加入 key-JsonValue 数据。

参数：

  • key：需要加入的 key
  • v：对应 key 的 JsonValue

func get

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

功能：获取 JsonObject 中 key 对应的 JsonValue, 并用 Option 封装。

参数：

  • key：指定的 key

返回值：key 对应的 JsonValue 的封装形式

operator func []

public operator func [](key: String): JsonValue

功能：获取 JsonObject 中 key 对应的 JsonValue。

参数：

  • key：指定的 key

返回值：key 对应的 JsonValue

异常：

  • 异常 JsonException：如果 key 不是 JsonObject 的有效键，抛出异常

func getFields

public func getFields(): HashMap<String, JsonValue>

功能：获取 JsonObject 中的 fields 数据。

返回值：JsonObject 的 fields 数据

interface ToJson

public interface ToJson {
    func toJson(): JsonValue
    static func fromJson(jv: JsonValue): DataModel
}

此接口用于实现 JsonValue 和 DataModel 的相互转换，DataModel 依赖 serialization 包，DataModel 为数据中间层， 可以通过序列化和反序列化的函数实现 DataModel 和对象的相互转换，支持的对象类型包括：

基本数据类型：整数类型、浮点类型、布尔类型、字符类型、字符串类型。

Collection 类型：Array、ArrayList、HashSet、HashMap、Option。

用户自定义的实现了 Serializable 接口的类型。

JsonValue 与 DataModel 的对应关系如下：

JsonValueDataModel
JsonBoolDataModelBool
JsonIntDataModelInt
JsonFloatDataModelFloat
JsonStringDataModelString
JsonArrayDataModelSeq
JsonObjectDataModelStruct
JsonNullDataModelNull

func toJson

func toJson(): JsonValue

功能：将自身转化为 JsonValue。

异常：

  • 异常 JsonException：如果转换失败，抛出异常

func fromJson

static func fromJson(jv: JsonValue): DataModel

功能：将 JsonValue 转化为对象 DataModel。

异常：

  • 异常 JsonException：如果转换失败，抛出异常

class JsonException

public class JsonException <: Exception {
    public init()
    public init(message: String)
}

Json 包的异常类

init

public init()

功能：创建 JsonException。

init

public init(message: String)

功能：创建 JsonException。

参数：

  • message：异常提示字符串

extend DataModel <: ToJson

extend DataModel <: ToJson

此扩展主要用于实现 DataModel 的 ToJson 接口

func fromJson

public static func fromJson(jv: JsonValue): DataModel

功能：将 JsonValue 数据解析为 DataModel。

参数：

  • jv：Json 数据格式的 JsonValue

返回值：解析的数据模型

func toJson

public func toJson(): JsonValue

功能：将 DataModel 转换为 JsonValue。

返回值：json 转换的 JsonValue

示例

JsonValue 的 fromStr/toJsonString 函数

下面是实现 String 和 JsonValue 相互转换的示例。

代码如下：

from encoding import json.*

main() {
    var str = ##"[true,"kjjjke\"eed",{"sdfd":"ggggg","eeeee":[341,false,{"nnnn":55.87}]},3422,22.341,false,[22,22.22,true,"ddd"],43]"##
    var jv: JsonValue = JsonValue.fromStr(str)
    var res = jv.toString()
    var prettyres = jv.toJsonString()
    println(res)
    println(prettyres)

    var strO = ##"{"name":"Tom","age":"18","version":"0.1.1"}"##
    var kO = JsonValue.fromStr(strO)
    var resO = kO.asObject().get("name").getOrThrow()
    println(resO)
    0
}

运行结果如下：

[true,"kjjjke\"eed",{"sdfd":"ggggg","eeeee":[341,false,{"nnnn":55.870000}]},3422,22.341000,false,[22,22.220000,true,"ddd"],43]
[
  true,
  "kjjjke\"eed",
  {
    "sdfd": "ggggg",
    "eeeee": [
      341,
      false,
      {
        "nnnn": 55.870000
      }
    ]
  },
  3422,
  22.341000,
  false,
  [
    22,
    22.220000,
    true,
    "ddd"
  ],
  43
]
"Tom"

JsonValue 添加多种数据并转 String

下面是 JsonValue 添加多种数据并转换成 String 的示例。

代码如下：

from encoding import json.*
from std import collection.*

main() {
    var a: JsonValue = JsonNull()
    var b: JsonValue = JsonBool(true)
    var c: JsonValue = JsonBool(false)
    var d: JsonValue = JsonInt(7363)
    var e: JsonValue = JsonFloat(736423.546)
    var list: ArrayList<JsonValue> = ArrayList<JsonValue>()
    var list2: ArrayList<JsonValue> = ArrayList<JsonValue>()
    var map = JsonObject()
    var map1 = JsonObject()
    map1.put("a", JsonString("jjjjjj"))
    map1.put("b", b)
    map1.put("c", JsonString("hhhhh"))
    list2.append(b)
    list2.append(JsonInt(3333333))
    list2.append(map1)
    list2.append(JsonString("sdfghgfasd"))
    list.append(b)
    list.append(a)
    list.append(map)
    list.append(c)
    list.append(JsonArray(list2))
    list.append(d)
    list.append(JsonString("ddddddd"))
    list.append(e)
    var result: JsonValue = JsonArray(list)
    println(result.toString())
    println(result.toJsonString())
    0
}

运行结果如下：

[true,null,{},false,[true,3333333,{"a":"jjjjjj","b":true,"c":"hhhhh"},"sdfghgfasd"],7363,"ddddddd",736423.546000]
[
  true,
  null,
  {},
  false,
  [
    true,
    3333333,
    {
      "a": "jjjjjj",
      "b": true,
      "c": "hhhhh"
    },
    "sdfghgfasd"
  ],
  7363,
  "ddddddd",
  736423.546000
]

Json 字符串与自定义类型间的转换

下面是 Json 字符串与自定义类型间的转换的示例。

代码如下：

from serialization import serialization.*
from encoding import json.*

class Person <: Serializable<Person> {
    var name: String = ""
    var age: Int64 = 0
    var loc: Option<Location> = Option<Location>.None

    public func serialize(): DataModel {
        return DataModelStruct().add(field<String>("name", name)).add(field<Int64>("age", age)).add(field<Option<Location>>("loc", loc))
    }

    public static func deserialize(dm: DataModel): Person {
        var dms = match (dm) {
            case data: DataModelStruct => data
            case _ => throw Exception("this data is not DataModelStruct")
        }
        var result = Person()
        result.name = String.deserialize(dms.get("name"))
        result.age = Int64.deserialize(dms.get("age"))
        result.loc = Option<Location>.deserialize(dms.get("loc"))
        return result
    }
}

class Location <: Serializable<Location>{
    var country: String = ""
    var province: String = ""

    public func serialize(): DataModel {
        return DataModelStruct().add(field<String>("country", country)).add(field<String>("province", province))
    }

    public static func deserialize(dm: DataModel): Location {
        var dms = match (dm) {
            case data: DataModelStruct => data
            case _ => throw Exception("this data is not DataModelStruct")
        }
        var result = Location()
        result.country = String.deserialize(dms.get("country"))
        result.province = String.deserialize(dms.get("province"))
        return result
    }
}

main() {
    var js = ##"{
    "name": "A",
    "age": 30,
    "loc": {
        "country": "China",
        "province": "Beijing"
    }
}"##
    var jv = JsonValue.fromStr(js)
    var dm = DataModel.fromJson(jv)
    var A = Person.deserialize(dm)
    println("name == ${A.name}")
    println("age == ${A.age}")
    println("country == ${A.loc.getOrThrow().country}")
    println("province == ${A.loc.getOrThrow().province}")
    println("====================") // 上部分实现从 Json 字符串到自定义类型的转换，下部分实现从自定义类型到 Json 字符串的转换。
    dm = A.serialize()
    var jo = dm.toJson().asObject()
    println(jo.toJsonString())
    0
}

运行结果如下：

name == A
age == 30
country == China
province == Beijing
====================
{
  "name": "A",
  "age": 30,
  "loc": {
    "country": "China",
    "province": "Beijing"
  }
}

Json 中转义字符处理

Json 在解析 String 转换为 JsonValue 时，转义字符 \ 之后只能对应 json 支持的转义字符（b、f、n、r、t、u、\、"、/），其中 \u 的格式为：\uXXXX，X 为十六进制数，例：\u0041 代表字符 'A'

代码如下：

from encoding import json.*

main() {
    println(JsonString("\b | \f | \n | \r | \t | A | \\ | \" | /").toString())
    println(JsonValue.fromStr("\"\\b\"").toString())
    println(JsonValue.fromStr("\"\\f\"").toString())
    println(JsonValue.fromStr("\"\\n\"").toString())
    println(JsonValue.fromStr("\"\\r\"").toString())
    println(JsonValue.fromStr("\"\\t\"").toString())
    println(JsonValue.fromStr("\"\\u0041\"").toString())
    println(JsonValue.fromStr("\"\\\\\"").toString())
    println(JsonValue.fromStr("\"\\\"\"").toString())
    println(JsonValue.fromStr("\"\\/\"").toString())
}

运行结果如下：

"\b | \f | \n | \r | \t | A | \\ | \" | /"
"\b"
"\f"
"\n"
"\r"
"\t"
"A"
"\\"
"\""
"/"

Json 中转义字符错误处理

json 转义错误示例，\ 后面加上数字 (非 json 支持的转义字符)。

代码如下：

from encoding import json.*

main() {
    var s1 = JsonValue.fromStr("\"\\1\"").toString()
    println(s1)
}

运行结果如下：会抛出异常

An exception has occurred:
JsonException: the json data is Non-standard, please check:
Parse Error: [Line]: 1, [Pos]: 3, [Error]: Unexpected character: '1'.

json.stream 包

介绍

本包主要用于仓颉对象和 JSON 数据流之间的互相转换。

本包提供了 JsonWriter 和 JsonReader 类，JsonWriter 用于提供仓颉对象转 JSON 数据流的序列化能力；JsonReader 用于提供 JSON 数据流转仓颉对象的反序列化能力。

主要接口

enum JsonToken

public enum JsonToken <: Equatable<JsonToken> & Hashable{
    | JsonNull
    | JsonBool
    | JsonNumber
    | JsonString
    | BeginArray
    | EndArray
    | BeginObject
    | EndObject
    | Name
}
JsonNull
JsonNull

功能：表示 JSON 的 null 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue<Option>() 读取。

JsonBool
JsonBool

功能：表示 JSON 的 bool 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。

JsonNumber
JsonNumber

功能：表示 JSON 的 number 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。

JsonString
JsonString

功能：表示 JSON 的 string 类型。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readValue() 读取。

BeginArray
BeginArray

功能：表示 JSON 中 array 的开始。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.startArray() 读取。

EndArray
EndArray

功能：表示 JSON 中 array 的结束。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.endArray() 读取。

BeginObject
BeginObject

功能：表示 JSON 中 object 的开始。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.startObject() 读取。

EndObject
EndObject

功能：表示 JSON 中 object 的结束。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.endObject() 读取。

Name
Name

功能：表示 object 中的 name。如果 JsonReader.peek() 返回的是该类型，可以使用 JsonReader.readName() 读取。

operator func ==
public operator func ==(that: JsonToken): Bool

功能：判等。

参数：

  • that：被比较的 JsonToken 对象

返回值：当前实例与 that 相等返回 true，否则返回 false

operator func !=
public operator func !=(that: JsonToken): Bool

功能：判不等。

参数：

  • that：被比较的 JsonToken 对象

返回值：当前实例与 that 不相等返回 true，否则返回 false

func hashCode
public func hashCode(): Int64

功能：获取 JsonToken 对象的 hashCode 值。

返回值：hashCode 值

class JsonReader

public class JsonReader {
    public init(inputStream: InputStream)
}

此类提供 JSON 数据流转仓颉对象的反序列化能力。

init
public init(inputStream: InputStream)

功能：根据输入流创建一个 JsonReader， JsonReader 从输入流中读取数据时，将跳过非 JsonString 中的空字符（'\0', '\t', '\n', '\r'）。

参数：

  • inputStream： 输入的 JSON 数据流
func peek
public func peek(): Option<JsonToken>

功能：获取输入流的下一个 JsonToken 的类型，不保证下一个 JsonToken 的格式一定正确。

例：如果输入流中的下一个字符为 't'，获取的 JsonToken 将为 JsonToken.Bool，但调用 readValue() 不一定成功。

返回值：

  • Option<JsonToken>： 获取到的下一个 JsonToken 的类型，如果到了输入流的结尾返回 None。

异常：

  • 异常 IllegalStateException：如果输入流的下一个字符不在一下范围内：(n, t, f, ", 0~9, -, {, }, [, ])，读取下一字符时，将根据 JSON 规则跳过逗号。
func readName
public func readName(): String

功能：从输入流的当前位置读取一个 name。

返回值：

  • String： 读取出的 name 值

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func readValue
public func readValue<T>(): T where T <: JsonDeserializable<T>

功能：从输入流的当前位置读取一个 value。

返回值：

  • T： 读取出的 value 值

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func startArray
public func startArray(): Unit

功能：从输入流的当前位置跳过空白字符后消耗一个 '[' 字符。

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func endArray
public func endArray(): Unit

功能：从输入流的当前位置跳过空白字符后消耗一个 ']' 字符，endArray 必须有一个 startArray 与之对应。

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func startObject
public func startObject(): Unit

功能：从输入流的当前位置跳过空白字符后消耗一个 '{' 字符。

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func endObject
public func endObject(): Unit

功能：从输入流的当前位置跳过空白字符后消耗一个 '}' 字符，endObject 必须有一个 startObject 与之对应。

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常
func skip
public func skip(): Unit

功能：从输入流的当前位置跳过一组数据。

如果 next token 是 value，跳过这个 value, 跳过 value 时不检查该 value 格式是否正确。

如果 next token 是 Name，跳过 (name + value) 这一个组合。

如果 next token 是 BeginArray，跳过这个 array。

如果 next token 是 BeginObject，跳过这个 object。

如果 next token 是 EndArray 或者 EndObject 或者 None，不做任何操作，peek 仍返回 EndArray 或者 EndObject 或者 None。

异常：

  • 异常 IllegalStateException：如果输入流的 JSON 数据不符合格式，抛出异常

interface JsonDeserializable

public interface JsonDeserializable<T> {
    static func fromJson(r: JsonReader): T
}

此接口用于实现从 JsonReader 中读取一个仓颉对象，支持的对象类型包括：

基本数据类型：整数类型、浮点类型、布尔类型、字符串类型。

Collection 类型：Array、ArrayList、HashMap、Option。

func fromJson
static func fromJson(r: JsonReader): T

功能：从参数 r 指定的 JsonReader 实例中读取一个 T 类型对象。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：T 类型的实例

extend Int64 <: JsonDeserializable

extend Int64 <: JsonDeserializable<Int64>

此扩展为 Int64 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Int64

功能：从参数 r 指定的 JsonReader 实例中读取出 Int64 类型实例。支持前导 '0b', '0o', '0x'（不区分大小写），分别表示二进制，八进制和十六进制。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：Int64 类型的实例

extend UInt64 <: JsonDeserializable

extend UInt64 <: JsonDeserializable<UInt64>

此扩展为 UInt64 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): UInt64

功能：从参数 r 指定的 JsonReader 实例中读取出 UInt64 类型实例。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：UInt64 类型的实例

extend Float64 <: JsonDeserializable

extend Float64 <: JsonDeserializable<Float64>

此扩展为 Float64 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Float64

功能：从参数 r 指定的 JsonReader 实例中读取出 Float64 类型实例。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：Float64 类型的实例

extend Bool <: JsonDeserializable

extend Bool <: JsonDeserializable<Bool>

此扩展为 Bool 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Bool

功能：从参数 r 指定的 JsonReader 实例中读取出 Bool 类型实例。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：Bool 类型的实例

extend String <: JsonDeserializable

extend String <: JsonDeserializable<String>

此扩展为 String 类型实现 JsonDeserializable 接口。 根据下一个 JsonToken`` 的不同， String` 的反序列化结果将会不同：

  • 当下一个 JsonToken 是 JsonString 时， 反序列化过程会按照标准ECMA-404 The JSON Data Interchange Standard对读到的 String 进行转义。
  • 当下一个 JsonToken 是 JsonNumber JsonBool JsonNull 其中一个时，将会读取下一个 value 字段的原始字符串并返回。
  • 当下一个 JsonToken 是其它类型时，调用此接口会抛异常。
func fromJson
public static func fromJson(r: JsonReader): String

功能：从参数 r 指定的 JsonReader 中读取 String。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：String 类型的实例

extend Option <: JsonDeserializable

extend Option<T> <: JsonDeserializable<Option<T>> where T <: JsonDeserializable<T>

此扩展为 Option 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Option<T>

功能：从参数 r 指定的 JsonReader 中读取 String。如果 JSON 数据流的下一 token 为 null，返回 None。

参数：

  • r：读取反序列化结果的 Option 实例

返回值：Option 类型的实例

extend Array <: JsonDeserializable

extend Array<T> <: JsonDeserializable<Array<T>> where T <: JsonDeserializable<T>

此扩展为 Array 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Array<T>

功能：从参数 r 指定的 JsonReader 中读取 Array<T>。调用该函数前后不需要调用 startArray 和 endArray 函数。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：Array<T> 类型的实例

extend ArrayList <: JsonDeserializable

extend ArrayList<T> <: JsonDeserializable<ArrayList<T>> where T <: JsonDeserializable<T>

为 ArrayList 类型扩展实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): ArrayList<T>

功能：从参数 r 指定的 JsonReader 实例中读取出 ArrayList<T> 类型实例。调用该函数前后不需要调用 startArray 和 endArray 函数。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：ArrayList<T> 类型的实例

extend HashMap <: JsonDeserializable

extend HashMap<K, T> <: JsonDeserializable<HashMap<K, T>> where T <: JsonDeserializable<T>, K <: String

此扩展为 HashMap 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): HashMap<K, T>

功能：从参数 r 指定的 JsonReader 实例中读取出 HashMap<K, T> 类型实例。调用该函数前后不需要调用 startObject 和 endObject 函数。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：HashMap<K, T> 类型的实例

extend BigInt <: JsonDeserializable

extend BigInt <: JsonDeserializable<BigInt>

此扩展为 BigInt 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): BigInt

功能：从参数 r 指定的 JsonReader 实例中读取出 BigInt 类型实例。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：BigInt 类型的实例

extend Decimal <: JsonDeserializable

extend Decimal <: JsonDeserializable<Decimal>

此扩展为 Decimal 类型实现 JsonDeserializable 接口。

func fromJson
public static func fromJson(r: JsonReader): Decimal

功能：从参数 r 指定的 JsonReader 实例中读取出 Decimal 类型实例。

参数：

  • r：读取反序列化结果的 JsonReader 实例

返回值：Decimal 类型的实例

class JsonWriter

public class JsonWriter {
    public init(out: OutputStream)
}

JsonWriter 提供了将仓颉对象序列化到 OutputStream 的能力。

JsonWriter 需要和 interface JsonSerializable 搭配使用，JsonWriter 可以通过 writeValue 来将实现了 JsonSerializable 接口的类型写入到 Stream 中。

JsonWriter 中使用缓存来减少写入 Stream 时的 IO 次数，在结束使用 JsonWriter 之前需要调用 flush 函数来确保缓存中的数据全部写入 Stream。

init
public init(out: OutputStream)

功能：构造函数，构造一个将数据写入 out 的实例。

参数：

  • out：目标流
func writeNullValue
public func writeNullValue(): JsonWriter

功能：向流中写入 JSON value null。

返回值：为方便链式调用，返回值为当前 JsonWriter 的引用。

异常：

  • IllegalStateException： 当前 writer 的状态不应该写入 value 时
func jsonValue
public func jsonValue(value: String): JsonWriter

功能: 将符合JSON value规范的原始字符串写入stream，此函数不会对值 value 进行转义。如果使用者能够保证输入的值 value 符合数据转换标准ECMA-404 The JSON Data Interchange Standard， 建议使用该函数。

返回值：为方便链式调用，返回值为当前 JsonWriter 的引用。

异常：

  • IllegalStateException： 当前 writer 的状态不应该写入 value 时。
func flush
public func flush(): Unit

功能：将缓存中的数据写入 out，并且调用 out 的 flush 方法。

func writeValue
public func writeValue<T>(v: T): JsonWriter where T <: JsonSerializable

功能：将实现了 JsonSerializable 接口的类型写入到 Stream 中。该接口会调用泛型 T 的 toJson 方法向输出流中写入数据

json.stream 包已经为基础类型 Int64、UInt64、Float64、Bool、String类型扩展实现了 JsonSerializable， 并且为 Collection 类型 Array、ArrayList和 HashMap 扩展实现了 JsonSerializable。

返回值：返回当前 JsonWriter 的引用。

异常：

  • IllegalStateException： 当前 writer 的状态不应该写入 value 时。
func writeName
public func writeName(name: String): JsonWriter

功能：在 object 结构中写入 name。

返回值：当前 JsonWriter 引用

异常：

  • IllegalStateException：当前 JsonWriter 的状态不应写入参数 name 指定字符串时。
func startArray
public func startArray(): Unit

功能：开始序列化一个新的 JSON 数组，每一个 startArray 都必须有一个 endArray 对应。

异常：

  • IllegalStateException： 当前 writer 的状态不应该写入 JSON array 时。
func endArray
public func endArray(): Unit

功能：结束序列化当前的 JSON 数组。

异常：

  • IllegalStateException： 当前 writer 没有匹配的 startArray 时。
func startObject
public func startObject(): Unit

功能：开始序列化一个新的 JSON object，每一个 startObject 都必须有一个 endObject 对应。

异常：

  • IllegalStateException： 当前 writer 的状态不应该写入 JSON object 时。
func endObject
public func endObject(): Unit

功能：结束序列化当前的 JSON object。

异常：

  • IllegalStateException： 当前 writer 的状态不应该结束一个 JSON object 时。

interface JsonSerializable

public interface JsonSerializable {
   	func toJson(w: JsonWriter): Unit
}

功能：为类型提供序列化成 JSON 的接口，与 JsonWriter 搭配使用，JsonWriter 可以通过 writeValue 来将实现了 JsonSerializable 接口的类型写入到 Stream 中。

func toJson
func toJson(w: JsonWriter): Unit

功能：将实现了 JsonSerializable 接口的类型写入参数 w 指定的 JsonWriter 实例中。

参数：

  • w：写入序列化结果的 JsonWriter 实例

extend Int64 <: JsonSerializable

extend Int64 <: JsonSerializable
func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Int64 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend UInt64 <: JsonSerializable

extend UInt64 <: JsonSerializable

功能：为 UInt64 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 UInt64 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend Float64 <: JsonSerializable

extend Float64 <: JsonSerializable

功能：为 Float64 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Float64 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend Bool <: JsonSerializable

extend Bool <: JsonSerializable

功能：为 Bool 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Bool 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend String <: JsonSerializable

extend String <: JsonSerializable

为 String 类型扩展实现 JsonSerializable 接口。String 的序列化过程会按照标准ECMA-404 The JSON Data Interchange Standard进行转义。为了追求更好的序列化性能，如果能够确保 String 符合 ECMA-404 规定的转义后的标准，可以调用 JsonWriter 的 jsonValue 方法。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 String 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend Option <: JsonSerializable

extend Option<T> <: JsonSerializable where T <: JsonSerializable

功能：为 Option 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Option 的序列化结果写入参数 w 指定的 JsonWriter。如果 Option 的值是 Some(v)，将会调用 T 类型的 toJson 方法进行序列化，如果 Option 的值是 None，将会向输出流中写入 null。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend Array <: JsonSerializable

extend Array<T> <: JsonSerializable where T <: JsonSerializable

功能：为 Array 类型扩展实现了 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Array 的序列化结果写入参数 w 指定的 JsonWriter。该接口直接向输出流中写入 JSON array，调用该函数前后不需要调用 startArray 和 endArray 函数。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend ArrayList <: JsonSerializable

extend ArrayList<T> <: JsonSerializable where T <: JsonSerializable

功能：为 ArrayList 类型扩展实现了 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 ArrayList 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。该接口直接向输出流中写入 JSON array，调用该函数前后不需要调用 startArray 和 endArray 函数。

extend HashMap <: JsonSerializable

extend HashMap<K, V> <: JsonSerializable where V <: JsonSerializable, K <: String

功能：为 HashMap 类型扩展实现了 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 HashMap 的序列化结果写入参数 w 指定的 JsonWriter。该函数直接向输出流中写入 JSON object，JSON object 中 name-value 对应着 HashMap 中的 key-value。调用该函数前后不需要调用 startObject 和 endObject 函数。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend BigInt <: JsonSerializable

extend BigInt <: JsonSerializable

功能：为 BigInt 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 BigInt 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

extend Decimal <: JsonSerializable

extend Decimal <: JsonSerializable

功能：为 Decimal 类型扩展实现 JsonSerializable 接口。

func toJson
public func toJson(w: JsonWriter): Unit

功能：将 Decimal 的序列化结果写入参数 w 指定的 JsonWriter。

参数：

  • w：写入序列化结果的 JsonWriter 实例。

示例

反序列化

代码如下：

from encoding import json.stream.*
from std import io.*
from std import collection.*

class A <: JsonDeserializable<A> {
    var key1: Option<String> = None
    var key2: Bool = false
    var key3: Float64 = 0.0
    var key4: String = ""
    var key5: Array<Int64> = Array<Int64>()
    var key6: HashMap<String, String> = HashMap<String, String>()

    public static func fromJson(r: JsonReader): A {
        var res = A()
        while (let Some(v) <- r.peek()) {
            match(v) {
                case BeginObject =>
                    r.startObject()
                    while(r.peek() != EndObject) {
                        let n = r.readName()
                        match (n) {
                            case "key1" => res.key1 = r.readValue<Option<String>>()
                            case "key2" => res.key2 = r.readValue<Bool>()
                            case "key3" => res.key3 = r.readValue<Float64>()
                            case "key4" => res.key4 = r.readValue<String>()
                            case "key5" => res.key5 = r.readValue<Array<Int64>>()
                            case "key6" => res.key6 = r.readValue<HashMap<String, String>>()
                            case _ => ()
                        }
                    }
                    r.endObject()
                    break
                case _ => throw Exception()
            }
        }
        return res
    }

    func toString(): String {
        return "${key1}\n${key2}\n${key3}\n${key4}\n${key5}\n${key6}"
    }
}

main() {
    let jsonStr = ##"{"key1": null, "key2": true, "key3": 123.456, "key4": "string", "key5": [123, 456], "key6": {"key7": " ", "key8": "\\a"}}"##
    var bas = ByteArrayStream()
    unsafe { bas.write(jsonStr.rawData()) }
    var reader = JsonReader(bas)
    var obj = A.fromJson(reader)
    println(obj.toString())
}

运行结果可能如下：

None
true
123.456000
string
[123, 456]
[(key7,  ), (key8, \a)]

序列化

from encoding import json.stream.*
from std import io.ByteArrayStream

class Image <: JsonSerializable {
    var width: Int64
    var height: Int64
    var title: String
    var ids: Array<Int64>

    public init() {
        width = 0
        height = 0
        title = ""
        ids = Array<Int64>()
    }

    public func toJson(w: JsonWriter): Unit {
        w.startObject() // start encoding an object
        w.writeName("Width").writeValue(width) // write name and value pair in current object
        w.writeName("Height").writeValue(height)
        w.writeName("Title").writeValue(title)
        w.writeName("Ids").writeValue<Array<Int64>>(ids) //use class Array's func toJson
        w.endObject()// end current object
    }
}


main(){
    let image = Image()
    image.width = 800
    image.height = 600
    image.title = "View from 15th Floor"
    image.ids = [116, 943, 234, 38793]

    let stream = ByteArrayStream() // output
    let writer = JsonWriter(stream) // init a JsonWriter
    writer.writeValue(image) // serialize image to JSON
    writer.flush()
    println(String.fromUtf8(stream.readToEnd()))
}

运行结果如下：

{"Width":800,"Height":600,"Title":"View from 15th Floor","Ids":[116,943,234,38793]}

HashMap 序列化的使用方式

与 Array 不同的是，HashMap 中的每一条数据都是 name-value 组合， 所以 HashMap 的序列化时会序列化成 JSON object。

from encoding import json.stream.*
from std import io.ByteArrayStream
from std import collection.HashMap
main(){
    let map = HashMap<String, Int64>()
    map.put("Width", 800)
    map.put("Height", 600)

    let stream = ByteArrayStream()
    let writer = JsonWriter(stream)
    writer.writeValue(map)
    writer.flush()
    println(String.fromUtf8(stream.readToEnd()))
}

运行结果如下

{"Width":800,"Height":600}