Added samples for property delegates as part of KT-20357.

libraries/stdlib/samples/test/samples/properties/delegates.kt

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2010-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package samples.properties
+
+import kotlin.properties.Delegates
+import samples.*
+import kotlin.test.*
+
+class Delegates {
+    @Sample
+    fun vetoableDelegate() {
+        var max: Int by Delegates.vetoable(0) { property, oldValue, newValue ->
+            newValue > oldValue
+        }
+
+        assertPrints(max, "0")
+
+        max = 10
+        assertPrints(max, "10")
+
+        max = 5
+        assertPrints(max, "10")
+    }
+
+    @Sample
+    fun throwVetoableDelegate() {
+        var max: Int by Delegates.vetoable(0) { property, oldValue, newValue ->
+            if (newValue > oldValue) true else throw IllegalArgumentException("New value must be larger than old value.")
+        }
+
+        assertPrints(max, "0")
+
+        max = 10
+        assertPrints(max, "10")
+
+        assertFailsWith<IllegalArgumentException> { max = 5 }
+    }
+
+    @Sample
+    fun notNullDelegate() {
+        var max: Int by Delegates.notNull()
+
+        assertFailsWith<IllegalStateException> { println(max) }
+
+        max = 10
+        assertPrints(max, "10")
+    }
+
+    @Sample
+    fun observableDelegate() {
+        var observed = false
+        var max: Int by Delegates.observable(0) { property, oldValue, newValue ->
+            observed = true
+        }
+
+        assertPrints(max, "0")
+        assertFalse(observed)
+
+        max = 10
+        assertPrints(max, "10")
+        assertTrue(observed)
+    }
+}

libraries/stdlib/src/kotlin/properties/Delegates.kt

@@ -10,6 +10,8 @@ public object Delegates {
      * Returns a property delegate for a read/write property with a non-`null` value that is initialized not during
      * object construction time but at a later time. Trying to read the property before the initial value has been
      * assigned results in an exception.
+     *
+     * @sample samples.properties.Delegates.notNullDelegate
      */
     public fun <T: Any> notNull(): ReadWriteProperty<Any?, T> = NotNullVar()
 
@@ -18,6 +20,8 @@ public object Delegates {
      * @param initialValue the initial value of the property.
      * @param onChange the callback which is called after the change of the property is made. The value of the property
      *  has already been changed when this callback is invoked.
+     *
+     *  @sample samples.properties.Delegates.observableDelegate
      */
     public inline fun <T> observable(initialValue: T, crossinline onChange: (property: KProperty<*>, oldValue: T, newValue: T) -> Unit):
         ReadWriteProperty<Any?, T> = object : ObservableProperty<T>(initialValue) {
@@ -32,6 +36,9 @@ public object Delegates {
      *  The value of the property hasn't been changed yet, when this callback is invoked.
      *  If the callback returns `true` the value of the property is being set to the new value,
      *  and if the callback returns `false` the new value is discarded and the property remains its old value.
+     *
+     *  @sample samples.properties.Delegates.vetoableDelegate
+     *  @sample samples.properties.Delegates.throwVetoableDelegate
      */
     public inline fun <T> vetoable(initialValue: T, crossinline onChange: (property: KProperty<*>, oldValue: T, newValue: T) -> Boolean):
         ReadWriteProperty<Any?, T> = object : ObservableProperty<T>(initialValue) {