Add support for enumerations. (#284)

* Add `EnumerationHandle`.

* Add an `Enumeration` class.

* Add the other enumeration-related APIs.

* Suppress Sonar warning S3427.

* FIx bugs.

* Add some more APIs.

* Always return a flat array on enumerations with fixed-size members.

* Add some tests.

* Fix tests.

* Remove two unused fields.

* Improve documentation of `ValuesPerMember`.

* Use the unified type validation API.

.editorconfig

@@ -43,3 +43,8 @@ dotnet_diagnostic.S112.severity = None
 # Native methods should be wrapped
 # For some reason this warning shows even on auto-generated files.
 dotnet_diagnostic.S4200.severity = None
+
+# S3427: Method overloads with default parameter values should not overlap
+# If we oblige to this rule and remove the overload without the default parameter,
+# the package validator will complain.
+dotnet_diagnostic.S3427.severity = none

sources/TileDB.CSharp/Array.cs

@@ -648,6 +648,54 @@ public static EncryptionType EncryptionType(Context ctx, string uri)
             return (EncryptionType)tiledb_encryption_type;
         }
 
+        /// <summary>
+        /// Gets an <see cref="Enumeration"/> from the <see cref="Array"/> by name.
+        /// </summary>
+        /// <param name="name">The enumeration's name.</param>
+        /// <seealso cref="LoadAllEnumerations"/>
+        public Enumeration GetEnumeration(string name)
+        {
+            var handle = new EnumerationHandle();
+            var successful = false;
+            tiledb_enumeration_t* enumeration_p = null;
+            try
+            {
+                using (var ctxHandle = _ctx.Handle.Acquire())
+                using (var arrayHandle = _handle.Acquire())
+                using (var ms_name = new MarshaledString(name))
+                {
+                    _ctx.handle_error(Methods.tiledb_array_get_enumeration(ctxHandle, arrayHandle, ms_name, &enumeration_p));
+                }
+                successful = true;
+            }
+            finally
+            {
+                if (successful)
+                {
+                    handle.InitHandle(enumeration_p);
+                }
+                else
+                {
+                    handle.SetHandleAsInvalid();
+                }
+            }
+
+            return new Enumeration(_ctx, handle);
+        }
+
+        /// <summary>
+        /// Loads all enumerations of the <see cref="Array"/>.
+        /// </summary>
+        /// <seealso cref="GetEnumeration"/>
+        public void LoadAllEnumerations()
+        {
+            using (var ctxHandle = _ctx.Handle.Acquire())
+            using (var arrayHandle = _handle.Acquire())
+            {
+                _ctx.handle_error(Methods.tiledb_array_load_all_enumerations(ctxHandle, arrayHandle));
+            }
+        }
+
         /// <summary>
         /// Puts a multi-value metadata to the <see cref="Array"/>.
         /// </summary>

sources/TileDB.CSharp/ArraySchema.cs

@@ -69,6 +69,18 @@ public void AddAttributes(params Attribute[] attrs)
             }
         }
 
+        /// <summary>
+        /// Adds an <see cref="Enumeration"/> in the <see cref="ArraySchema"/>.
+        /// </summary>
+        /// <param name="enumeration">The enumeration to add.</param>
+        public void AddEnumeration(Enumeration enumeration)
+        {
+            using var ctxHandle = _ctx.Handle.Acquire();
+            using var handle = _handle.Acquire();
+            using var enumHandle = enumeration.Handle.Acquire();
+            _ctx.handle_error(Methods.tiledb_array_schema_add_enumeration(ctxHandle, handle, enumHandle));
+        }
+
         /// <summary>
         /// Sets whether cells with duplicate coordinates are allowed in the <see cref="ArraySchema"/>.
         /// </summary>

sources/TileDB.CSharp/ArraySchemaEvolution.cs

@@ -63,6 +63,32 @@ public void DropAttribute(string attrName)
             _ctx.handle_error(Methods.tiledb_array_schema_evolution_drop_attribute(ctxHandle, handle, msAttrName));
         }
 
+        /// <summary>
+        /// Adds an <see cref="Enumeration"/> to the <see cref="ArraySchemaEvolution"/>.
+        /// </summary>
+        /// <param name="enumeration">A fully constructed <see cref="Enumeration"/> that will be added to the schema.</param>
+        /// <seealso cref="DropEnumeration"/>
+        public void AddEnumeration(Enumeration enumeration)
+        {
+            using var ctxHandle = _ctx.Handle.Acquire();
+            using var handle = _handle.Acquire();
+            using var enumHandle = enumeration.Handle.Acquire();
+            _ctx.handle_error(Methods.tiledb_array_schema_evolution_add_enumeration(ctxHandle, handle, enumHandle));
+        }
+
+        /// <summary>
+        /// Drops an enumeration with the given name from the <see cref="ArraySchemaEvolution"/>.
+        /// </summary>
+        /// <param name="enumerationName">The name of the attribute that will be dropped from the schema.</param>
+        /// <seealso cref="AddEnumeration"/>
+        public void DropEnumeration(string enumerationName)
+        {
+            using var ctxHandle = _ctx.Handle.Acquire();
+            using var handle = _handle.Acquire();
+            using var msEnumerationName = new MarshaledString(enumerationName);
+            _ctx.handle_error(Methods.tiledb_array_schema_evolution_drop_enumeration(ctxHandle, handle, msEnumerationName));
+        }
+
         /// <summary>
         /// Drops an <see cref="Attribute"/> from the <see cref="ArraySchemaEvolution"/>.
         /// </summary>

sources/TileDB.CSharp/Attribute.cs

@@ -3,6 +3,7 @@
 using System.Runtime.InteropServices;
 using System.Text;
 using TileDB.Interop;
+using TileDB.CSharp.Marshalling;
 using TileDB.CSharp.Marshalling.SafeHandles;
 using AttributeHandle = TileDB.CSharp.Marshalling.SafeHandles.AttributeHandle;
 using FilterListHandle = TileDB.CSharp.Marshalling.SafeHandles.FilterListHandle;
@@ -89,6 +90,17 @@ public void SetCellValNum(uint cellValNum)
             using var handle = _handle.Acquire();
             _ctx.handle_error(Methods.tiledb_attribute_set_cell_val_num(ctxHandle, handle, cellValNum));
         }
+
+        /// <summary>
+        /// Sets the name of the <see cref="Attribute"/>'s enumeration.
+        /// </summary>
+        public void SetEnumerationName(string enumerationName)
+        {
+            using var ctxHandle = _ctx.Handle.Acquire();
+            using var handle = _handle.Acquire();
+            using var ms_enumerationName = new MarshaledString(enumerationName);
+            _ctx.handle_error(Methods.tiledb_attribute_set_enumeration_name(ctxHandle, handle, ms_enumerationName));
+        }
 
         /// <summary>
         /// Get name of the attribute.
@@ -187,6 +199,23 @@ public ulong CellSize()
             return cell_size;
         }
 
+        /// <summary>
+        /// Gets the name of the <see cref="Attribute"/>'s enumeration.
+        /// </summary>
+        /// <returns>
+        /// A string with the name of the attribute's enumeration, or an
+        /// empty string if the attribute does not have an enumeration.
+        /// </returns>
+        public string EnumerationName()
+        {
+            using var ctxHandle = _ctx.Handle.Acquire();
+            using var handle = _handle.Acquire();
+            using var nameHolder = new StringHandleHolder();
+            _ctx.handle_error(Methods.tiledb_attribute_get_enumeration_name(ctxHandle, handle, &nameHolder._handle));
+
+            return nameHolder.ToString();
+        }
+
         /// <summary>
         /// Sets the fill value of a nullable multi-valued <see cref="Attribute"/>.
         /// Used when the fill value is multi-valued.