Implement scope-local C pointer. (#1471)

INTEROP.md

@@ -337,6 +337,22 @@ manually:
 
 In all cases the C string is supposed to be encoded as UTF-8.
 
+### Scope-local pointers ###
+
+It is possible to create scope-stable pointer of C representation of `CValues<T>`
+instance using `CValues<T>.ptr` extension property available under memScoped { ... }.
+It allows to use APIs which requires C pointers with lifetime bound to certain `MemScope`. For example:
+```
+memScoped {
+    items = arrayOfNulls<CPointer<ITEM>?>(6)
+    arrayOf("one", "two").forEachIndexed { index, value -> items[index] = value.cstr.ptr }
+    menu = new_menu("Menu".cstr.ptr, items.toCValues().ptr)
+    ...
+}
+```
+In this example all values passed to the C API `new_menu()` have lifetime of innermost `memScope`
+it belongs to. Once control flow will leave `memScoped` scope C pointers become invalid.
+
 ### Passing and receiving structs by value ###
 
 When C function takes or returns a struct `T` by value, the corresponding