JsonElement Hierarchy

/**
 * Base class representing single JSON element
 * Can be JsonPrimitive, JsonArray, or JsonObject
 */
sealed class JsonElement

/**
 * Base class representing JSON primitive value
 * JSON primitives include numbers, strings, booleans and special null value
 */
sealed class JsonPrimitive : JsonElement() {
    /**
     * Indicates whether the primitive was explicitly constructed from String
     * and whether it should be serialized as one
     */
    abstract val isString: Boolean
    
    /**
     * Content of given element without quotes
     * For JsonNull, returns "null" string
     */
    abstract val content: String
}

/**
 * Represents JSON null value
 */
object JsonNull : JsonPrimitive() {
    override val isString: Boolean // Always false
    override val content: String   // Always "null"
}

/**
 * Represents JSON object, consisting of name-value pairs
 * Also implements Map interface for traditional access methods
 */
class JsonObject(
    private val content: Map<String, JsonElement>
) : JsonElement(), Map<String, JsonElement> by content

// Create JsonObject
val jsonObj = JsonObject(mapOf(
    "name" to JsonPrimitive("Alice"),
    "age" to JsonPrimitive(25),
    "active" to JsonPrimitive(true)
))

// Access using Map interface
val name = jsonObj["name"]?.jsonPrimitive?.content  // "Alice"
val age = jsonObj["age"]?.jsonPrimitive?.int        // 25
val active = jsonObj["active"]?.jsonPrimitive?.boolean  // true

// Iterate over entries
for ((key, value) in jsonObj) {
    println("$key: $value")
}

/**
 * Represents JSON array, consisting of indexed values
 * Also implements List interface for traditional access methods
 */
class JsonArray(private val content: List<JsonElement>) : JsonElement(), List<JsonElement> by content

// Create JsonArray
val jsonArr = JsonArray(listOf(
    JsonPrimitive("Alice"),
    JsonPrimitive("Bob"),
    JsonPrimitive("Charlie")
))

// Access using List interface
val first = jsonArr[0].jsonPrimitive.content  // "Alice"
val size = jsonArr.size                       // 3

// Iterate over elements
for (element in jsonArr) {
    println(element.jsonPrimitive.content)
}

// Convert to regular list
val names = jsonArr.map { it.jsonPrimitive.content }

/** Creates JsonPrimitive from boolean value, null creates JsonNull */
fun JsonPrimitive(value: Boolean?): JsonPrimitive

/** Creates JsonPrimitive from numeric value, null creates JsonNull */
fun JsonPrimitive(value: Number?): JsonPrimitive

/** Creates JsonPrimitive from string value, null creates JsonNull */
fun JsonPrimitive(value: String?): JsonPrimitive

/** Creates numeric JsonPrimitive from UByte */
fun JsonPrimitive(value: UByte): JsonPrimitive

/** Creates numeric JsonPrimitive from UShort */
fun JsonPrimitive(value: UShort): JsonPrimitive

/** Creates numeric JsonPrimitive from UInt */
fun JsonPrimitive(value: UInt): JsonPrimitive

/** Creates numeric JsonPrimitive from ULong */
fun JsonPrimitive(value: ULong): JsonPrimitive

/** Creates JsonNull from null literal */
fun JsonPrimitive(value: Nothing?): JsonNull

/**
 * Creates JsonPrimitive from string without surrounding it in quotes
 * Used for raw JSON values like precise numbers or complex objects
 * @param value String content to use as unquoted literal
 * @throws JsonEncodingException if value equals "null"
 */
fun JsonUnquotedLiteral(value: String?): JsonPrimitive

// Primitive creation
val stringPrim = JsonPrimitive("Hello")      // Quoted string
val numberPrim = JsonPrimitive(42)           // Number  
val boolPrim = JsonPrimitive(true)           // Boolean
val nullPrim = JsonPrimitive(null)           // JsonNull

// Unsigned integers
val ubytePrim = JsonPrimitive(255u)          // UByte as number
val ulongPrim = JsonPrimitive(123456789UL)   // ULong as number

// Unquoted literals for special cases
val precisePrim = JsonUnquotedLiteral("123.456789012345")  // Precise number
val rawJsonPrim = JsonUnquotedLiteral("""{"nested": true}""")  // Raw JSON

/** Convenience method to get current element as JsonPrimitive */
val JsonElement.jsonPrimitive: JsonPrimitive

/** Convenience method to get current element as JsonObject */
val JsonElement.jsonObject: JsonObject

/** Convenience method to get current element as JsonArray */
val JsonElement.jsonArray: JsonArray

/** Convenience method to get current element as JsonNull */
val JsonElement.jsonNull: JsonNull

/** Returns content as int, throws NumberFormatException if invalid */
val JsonPrimitive.int: Int

/** Returns content as int or null if invalid */
val JsonPrimitive.intOrNull: Int?

/** Returns content as long, throws NumberFormatException if invalid */
val JsonPrimitive.long: Long

/** Returns content as long or null if invalid */
val JsonPrimitive.longOrNull: Long?

/** Returns content as double, throws NumberFormatException if invalid */
val JsonPrimitive.double: Double

/** Returns content as double or null if invalid */  
val JsonPrimitive.doubleOrNull: Double?

/** Returns content as float, throws NumberFormatException if invalid */
val JsonPrimitive.float: Float

/** Returns content as float or null if invalid */
val JsonPrimitive.floatOrNull: Float?

/** Returns content as boolean, throws IllegalStateException if invalid */
val JsonPrimitive.boolean: Boolean

/** Returns content as boolean or null if invalid */
val JsonPrimitive.booleanOrNull: Boolean?

/** Content without quotes or null if JsonNull */
val JsonPrimitive.contentOrNull: String?

// Type-safe extraction
val jsonStr = """{"count": 42, "active": true, "name": "test", "value": null}"""
val element = Json.parseToJsonElement(jsonStr)
val obj = element.jsonObject

// Extract typed values
val count = obj["count"]?.jsonPrimitive?.int          // 42
val active = obj["active"]?.jsonPrimitive?.boolean    // true  
val name = obj["name"]?.jsonPrimitive?.content        // "test"
val value = obj["value"]?.jsonPrimitive?.contentOrNull // null

// Safe extraction with null handling
val maybeCount = obj["count"]?.jsonPrimitive?.intOrNull      // 42
val maybeBoolean = obj["active"]?.jsonPrimitive?.booleanOrNull // true
val invalidInt = obj["name"]?.jsonPrimitive?.intOrNull       // null (can't parse "test" as int)

// Working with arrays
val arrayJson = """[1, 2.5, "text", true, null]"""
val array = Json.parseToJsonElement(arrayJson).jsonArray

val intVal = array[0].jsonPrimitive.int           // 1
val doubleVal = array[1].jsonPrimitive.double     // 2.5
val strVal = array[2].jsonPrimitive.content       // "text"
val boolVal = array[3].jsonPrimitive.boolean      // true
val nullVal = array[4].jsonPrimitive.contentOrNull // null