From 193bcaaa7daccc676fc47f197eece0741c31753f Mon Sep 17 00:00:00 2001 From: cbullinger Date: Wed, 23 Aug 2023 10:02:28 -0400 Subject: [PATCH] test draft --- .../schemas/supported-types.txt | 351 +++++++++++------- 1 file changed, 221 insertions(+), 130 deletions(-) diff --git a/source/sdk/kotlin/realm-database/schemas/supported-types.txt b/source/sdk/kotlin/realm-database/schemas/supported-types.txt index 97ef8ecef3a..c239a1f8279 100644 --- a/source/sdk/kotlin/realm-database/schemas/supported-types.txt +++ b/source/sdk/kotlin/realm-database/schemas/supported-types.txt @@ -1,8 +1,8 @@ .. _kotlin-supported-types: -======================= -Data Types - Kotlin SDK -======================= +============================ +Supported Types - Kotlin SDK +============================ .. contents:: On this page :local: @@ -11,79 +11,197 @@ Data Types - Kotlin SDK :class: singlecol -The Kotlin SDK supports Kotlin data types, a limited subset of -`BSON `__ types, and :wikipedia:`UUID `. +The Kotlin SDK supports `Kotlin types +`__, a limited subset of +`BSON `__ types, and +:wikipedia:`UUID `. + +Realm does not support fields with modifiers ``final`` and +``volatile``, though you can use fields with those modifiers if you +:ref:`ignore ` them. If you choose to provide custom +constructors, you must +:ref:`declare a public constructor with no arguments `. .. include:: /includes/map-to-bson-type.rst .. _kotlin-data-types: -Supported Types ---------------- - -Realm supports the following field data types: - -- ``String`` -- ``Byte`` -- ``Char`` -- ``Short`` -- ``Int`` -- ``MutableRealmInt``, which behaves like a ``Long`` but also supports ``increment`` - and ``decrement`` methods that implement a conflict-free replicated data type. - For more information, see `MutableRealmInt <{+kotlin-local-prefix+}io.realm.kotlin.types/-mutable-realm-int/index.html>`__. -- ``Long`` -- ``Boolean`` -- ``Double`` -- ``Float`` -- ``Decimal128`` -- ``ObjectId`` -- ``RealmAny``, which represents a polymorphic Realm value. For more - information, see `RealmAny <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-any/index.html>`__. +Supported Data Types List +------------------------- + +The Realm Kotlin SDK supports the following Kotlin data types, MongoDB BSON types, and Realm-specific types: + +.. list-table:: + :header-rows: 1 + + * - Kotlin Data Types + Data Type + - Required + - Optional + * - ``String`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Byte`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Short`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Int`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Long`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Float`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Double`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Boolean`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Char`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + +.. list-table:: + :header-rows: 1 + + * - MongoDB BSON Types + Data Type + - Required + - Optional + * - :ref:`ObjectId ` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``Decimal128`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + +.. list-table:: + :header-rows: 1 + + * - Realm-Specific Types + Data Type + - Required + - Optional + * - :ref:`RealmUUID ` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmInstant`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmAny`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``MutableRealmInt`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmObject`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmBacklinks`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmList`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmSet`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmMap`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + * - ``RealmDictionary`` + - ``var name: String = "John"`` + - ``var name: String? = null`` + + +Kotlin Data Types +----------------- + +Realm stores all non-decimal numeric types as ``Long`` values. +Similarly, Realm stores all decimal numeric types as ``Double`` +values. + +.. note:: + + You cannot store Kotlin's built-in ``Date`` or ``Instant`` types in Realm. + Instead, the Kotlin SDK uses the `RealmInstant + <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-instant/index.html>`__ + type, which stores time information as a UNIX epoch timestamp. + + See the :ref:`RealmInstant ` section on this page for more information. + +MongoDB BSON Types +------------------ + +.. _kotlin-objectid: + +ObjectId +~~~~~~~~ + +.. important:: + + In Realm Kotlin SDK version 1.5.0 and newer, `io.realm.kotlin.types.ObjectId <{+kotlin-local-prefix+}/io.realm.kotlin.types/-object-id/index.html>`__ is deprecated. You must import ``ObjectId`` from :github:`org.mongodb.kbson.ObjectId ` instead. + +, a MongoDB-specific 12-byte unique value that you +can use as an identifier for objects. It is :ref:`indexable ` +and can be used as a :ref:`primary key `. + +.. _kotlin-additional-types: + +Realm-Specific Types +-------------------- + +- ``RealmUUID`` - ``RealmInstant`` -- ``RealmUUID`` +- ``MutableRealmInt`` +- ``RealmAny`` - Any ``RealmObject`` subclass -- ``RealmList``, where T is any of the supported data types or a - `RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. - Lists of ``RealmObject`` cannot have null elements. - All other types of ``RealmList`` can be nullable (``RealmList``). -- ``RealmSet``, where T is any of the supported data types or a - `RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. - Sets of ``RealmObject`` cannot have null elements. - All other types of ``RealmSet`` can be nullable (``RealmSet``). -- ``RealmDictionary``, where T is any type of Realm primitive nullable or - non-nullable value (``RealmDictionary``), a - `RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__, - or an `EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__. - Dictionaries of ``RealmObject`` and ``EmbeddedRealmObject`` must be declared nullable. - ``BacklinksDelegate``, a `backlinks <{+kotlin-local-prefix+}io.realm.kotlin.ext/backlinks.html>`__ delegate used to define an inverse relationship between - `RealmObjects <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. + `RealmObjects <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. +- Realm collections, which contain zero or more instances of a supported data type, and + all objects are of the same type: + + - ``RealmList`` + - ``RealmSet`` + - ``RealmMap`` + - ``RealmDictionary`` -Realm stores all non-decimal numeric types as ``Long`` values. -Similarly, Realm stores all decimal numeric types as ``Double`` -values. +.. _kotlin-uuid: -Realm does not support fields with modifiers ``final`` and -``volatile``, though you can use fields with those modifiers if you -:ref:`ignore ` them. If you choose to provide custom -constructors, you must -:ref:`declare a public constructor with no arguments `. +RealmUUID +~~~~~~~~~ + +(Universal Unique Identifier), a 16-byte :wikipedia:`unique value +` that you can use as an identifier for +objects. It is :ref:`indexable ` and can be used as a +:ref:`primary key `. -Updating Strings and Byte Arrays -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Realm creates UUIDs with the `RealmUUID <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/index.html>`__ type that: -Since Realm operates on fields as a whole, it's not possible -to directly update individual elements of strings or byte arrays. Instead, -you'll need to read the whole field, make your modification to individual -elements, and then write the entire field back again in a transaction block. +- conform to `RFC 4122 version 4 `_ +- are created with random bytes + +You can generate a random ``RealmUUID`` using `RealmUUID.random() +<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/random.html>`__ +or pass a UUID-formatted string to `RealmUUID.from() +<{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/from.html>`__. + +.. include:: /includes/note-using-uuid-instead-of-objectid.rst .. _kotlin-timestamps: -Timestamps -~~~~~~~~~~ +RealmInstant +~~~~~~~~~~~~ + +, which stores time information as a UNIX epoch timestamp. -You cannot store Kotlin's built-in ``Date`` or ``Instant`` types in Realm -Database. Instead, use the +You cannot store Kotlin's built-in ``Date`` or ``Instant`` types in Realm. Instead, use the `RealmInstant <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-instant/index.html>`__ type, which stores time information as a UNIX epoch timestamp. @@ -94,27 +212,36 @@ example: .. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.timestamp-workaround.kt :language: kotlin -.. _kotlin-reference-realm-object: +MutableRealmInt +~~~~~~~~~~~~~~~ -Reference Realm Objects ------------------------ +``MutableRealmInt`` behaves like a ``Long`` but also supports ``increment`` +, which behaves like a ``Long`` but also supports ``increment`` +and ``decrement`` methods that implement a conflict-free replicated data type. +For more information, see `MutableRealmInt <{+kotlin-local-prefix+}io.realm.kotlin.types/-mutable-realm-int/index.html>`__. -You can also reference one or more Realm objects from another. Learn more in the -:ref:`relationship properties documentation `. +RealmAny +~~~~~~~~ + +, which represents a polymorphic Realm value. For more +information, see `RealmAny <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-any/index.html>`__. .. _kotlin-collections: +.. _kotlin-realm-list: + +RealmLists +~~~~~~~~~~ -Collections ------------ +, where T is any of the supported data types or a +`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. +Lists of ``RealmObject`` cannot have null elements. -A Realm collection contains zero or more instances of a -:ref:`Realm supported data type `. -In a Realm collection, all objects in a collection are of the same type. +All other types of ``RealmList`` can be nullable (``RealmList``). .. _kotlin-realm-set: -RealmSet -~~~~~~~~ +RealmSets +~~~~~~~~~ A `RealmSet() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-set/index.html>`__ @@ -128,78 +255,42 @@ interface, so it works just like the built-in ``HashSet`` class, except managed ``RealmSet`` instances persist their contents to a realm. +, where T is any of the supported data types or a +`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__. +Sets of ``RealmObject`` cannot have null elements. + +All other types of ``RealmSet`` can be nullable (``RealmSet``). + .. _kotlin-realm-dictionary: -RealmMap/RealmDictionary -~~~~~~~~~~~~~~~~~~~~~~~~ +RealmMap/RealmDictionaries +~~~~~~~~~~~~~~~~~~~~~~~~~~ A `RealmDictionary <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-dictionary/index.html>`__ is a specialized `RealmMap <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-map/index.html>`__ where every key is a string. A ``RealmMap`` is an associative array that -contains key-value pairs with unique keys. - -.. _kotlin-additional-types: +contains key-value pairs with unique keys. -Additional Supported Data Types -------------------------------- +, where T is any type of Realm primitive nullable or +non-nullable value (``RealmDictionary``), a +`RealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-object/index.html>`__, +or an `EmbeddedRealmObject <{+kotlin-local-prefix+}io.realm.kotlin.types/-embedded-realm-object/index.html>`__. +Dictionaries of ``RealmObject`` and ``EmbeddedRealmObject`` must be declared nullable. -.. _kotlin-objectid: +EmbeddedRealmObject +~~~~~~~~~~~~~~~~~~~ -ObjectId -~~~~~~~~ -.. note:: Importing ``ObjectId`` in the Realm Kotlin SDK ``version 1.5.x`` or Higher - - With the :github:`Realm Kotlin Kotlin version 1.5.0 - ` you must import - ``ObjectId`` from :github:`org.mongodb.kbson.ObjectId `. If - you were using an older SDK version and wish to upgrade, replace your old - import statements as `io.realm.kotlin.types.ObjectId - <{+kotlin-local-prefix+}io.realm.kotlin.types/#-1137254501%2FClasslikes%2F-1651551339>`__ - has been deprecated. - -``ObjectId`` is a MongoDB-specific 12-byte unique value which you can use as an -identifier for objects. ``ObjectId`` is :ref:`indexable ` -and can be used as a :ref:`primary key `. - -To define a property as an ObjectId, set its type as ``ObjectId`` in -your :ref:`object model `. - -.. _kotlin-uuid: +AsymmetricRealmObject +~~~~~~~~~~~~~~~~~~~~~ -UUID -~~~~ -``UUID`` (Universal Unique Identifier) is a 16-byte :wikipedia:`unique value -`. You can use ``UUID`` as an identifier for -objects. ``UUID`` is :ref:`indexable ` and can be used as a -:ref:`primary key `. - -Realm creates UUIDs with the `RealmUUID <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/index.html>`__ type that: - -- conform to `RFC 4122 version 4 `_ -- are created with random bytes - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.uuid.kt - :language: kotlin - :copyable: false - -.. include:: /includes/note-using-uuid-instead-of-objectid.rst - -Create a UUID from a String -``````````````````````````` - -To generate a new ``RealmUUID`` from a UUID formatted string, pass the string to `RealmUUID.from() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/from.html>`__: - -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.create-uuid-from-string.kt - :language: kotlin - -Create a Random UUID -```````````````````` +.. _kotlin-reference-realm-object: -To generate a random ``RealmUUID``, call `RealmUUID.random() <{+kotlin-local-prefix+}io.realm.kotlin.types/-realm-u-u-i-d/-companion/random.html>`__: +Reference Realm Objects +----------------------- -.. literalinclude:: /examples/generated/kotlin/SchemaTest.snippet.create-uuid-random.kt - :language: kotlin +You can also reference one or more Realm objects from another. Learn more in the +:ref:`relationship properties documentation `.