apacheGH-37229: [MATLAB] Add arrow.type.Date32Type class and `arrow…

….date32` construction function (apache#37348)

### Rationale for this change

In support of adding `arrow.array.Date32Array`, this pull request adds a new `arrow.type.Date32Type` class and associated `arrow.date32` construction function to the MATLAB interface.

### What changes are included in this PR?

1. New `arrow.type.Date32Type` class.
2. New `arrow.date32` construction function that returns an `arrow.type.Date32Type` instance.
3. New `arrow.type.ID.Date32` type enumeration value.
4. Added an abstract `arrow.type.DateType` class which `arrow.type.Date32Type` inherits from. `arrow.type.Date64Type` will also inherit from this class to share the `DateUnit` property. This mirrors the implementation of the `Time32Type` and `Time64Type` classes inheriting from an abstract `arrow.type.TimeType` class to share the `TimeUnit` property.

**Example**

```matlab
>> type = arrow.date32()

type = 

  Date32Type with properties:

          ID: Date32
    DateUnit: Day
```

### Are these changes tested?

Yes.

1. Added a new `tDate32Type` test class.
2. Updated the `tID` test class to include `arrow.type.ID.Date32`. 

### Are there any user-facing changes?

Yes.

1. There is a new public `arrow.type.Date32Type` class.
2. There is a new public `arrow.date32` construction function.
3. There is a new `arrow.type.ID.Date32` type enumeration value.

### Future Directions

1. apache#37230
2. Add `arrow.array.Date32Array` class.
3. Add `arrow.array.Date64Array` class.
* Closes: apache#37229

Lead-authored-by: Kevin Gurney <kgurney@mathworks.com>
Co-authored-by: Sarah Gilmore <sgilmore@mathworks.com>
Signed-off-by: Kevin Gurney <kgurney@mathworks.com>

matlab/src/cpp/arrow/matlab/proxy/factory.cc

@@ -26,6 +26,7 @@
 #include "arrow/matlab/type/proxy/primitive_ctype.h"
 #include "arrow/matlab/type/proxy/string_type.h"
 #include "arrow/matlab/type/proxy/timestamp_type.h"
+#include "arrow/matlab/type/proxy/date32_type.h"
 #include "arrow/matlab/type/proxy/time32_type.h"
 #include "arrow/matlab/type/proxy/time64_type.h"
 #include "arrow/matlab/type/proxy/field.h"
@@ -67,8 +68,9 @@ libmexclass::proxy::MakeResult Factory::make_proxy(const ClassName& class_name,
     REGISTER_PROXY(arrow.type.proxy.BooleanType    , arrow::matlab::type::proxy::PrimitiveCType<bool>);
     REGISTER_PROXY(arrow.type.proxy.StringType     , arrow::matlab::type::proxy::StringType);
     REGISTER_PROXY(arrow.type.proxy.TimestampType  , arrow::matlab::type::proxy::TimestampType);
-    REGISTER_PROXY(arrow.type.proxy.Time64Type     , arrow::matlab::type::proxy::Time64Type);
     REGISTER_PROXY(arrow.type.proxy.Time32Type     , arrow::matlab::type::proxy::Time32Type);
+    REGISTER_PROXY(arrow.type.proxy.Time64Type     , arrow::matlab::type::proxy::Time64Type);
+    REGISTER_PROXY(arrow.type.proxy.Date32Type     , arrow::matlab::type::proxy::Date32Type);
     REGISTER_PROXY(arrow.io.feather.proxy.Writer   , arrow::matlab::io::feather::proxy::Writer);
     REGISTER_PROXY(arrow.io.feather.proxy.Reader   , arrow::matlab::io::feather::proxy::Reader);
 

matlab/src/cpp/arrow/matlab/type/proxy/date32_type.cc

@@ -0,0 +1,31 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+#include "arrow/matlab/type/proxy/date32_type.h"
+
+namespace arrow::matlab::type::proxy {
+
+    Date32Type::Date32Type(std::shared_ptr<arrow::Date32Type> date32_type) : DateType(std::move(date32_type)) {}
+
+    libmexclass::proxy::MakeResult Date32Type::make(const libmexclass::proxy::FunctionArguments& constructor_arguments) {
+        using Date32TypeProxy = arrow::matlab::type::proxy::Date32Type;
+
+        const auto type = arrow::date32();
+        const auto date32_type = std::static_pointer_cast<arrow::Date32Type>(type);
+        return std::make_shared<Date32TypeProxy>(std::move(date32_type));
+    }
+}

matlab/src/cpp/arrow/matlab/type/proxy/date32_type.h

@@ -0,0 +1,36 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+#pragma once
+
+#include "arrow/matlab/type/proxy/date_type.h"
+
+namespace arrow::matlab::type::proxy {
+
+    class Date32Type : public arrow::matlab::type::proxy::DateType {
+
+        public:
+            Date32Type(std::shared_ptr<arrow::Date32Type> date32_type);
+
+            ~Date32Type() {}
+
+            static libmexclass::proxy::MakeResult make(const libmexclass::proxy::FunctionArguments& constructor_arguments);
+
+    };
+
+}
+

matlab/src/cpp/arrow/matlab/type/proxy/date_type.cc

@@ -0,0 +1,37 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+#include "arrow/matlab/type/proxy/date_type.h"
+
+namespace arrow::matlab::type::proxy {
+
+    DateType::DateType(std::shared_ptr<arrow::DateType> date_type) : FixedWidthType(std::move(date_type)) {
+        REGISTER_METHOD(DateType, getDateUnit);
+    }
+
+    void DateType::getDateUnit(libmexclass::proxy::method::Context& context) {
+        namespace mda = ::matlab::data;
+        mda::ArrayFactory factory;
+
+        auto date_type = std::static_pointer_cast<arrow::DateType>(data_type);
+        const auto date_unit = date_type->unit();
+        // Cast to uint8_t since there are only two supported DateUnit enumeration values:
+        // Day and Millisecond
+        auto date_unit_mda = factory.createScalar(static_cast<uint8_t>(date_unit));
+        context.outputs[0] = date_unit_mda;
+    }
+}

matlab/src/cpp/arrow/matlab/type/proxy/date_type.h

@@ -0,0 +1,35 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you 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.
+
+#pragma once
+
+#include "arrow/matlab/type/proxy/fixed_width_type.h"
+
+namespace arrow::matlab::type::proxy {
+
+class DateType : public arrow::matlab::type::proxy::FixedWidthType {
+
+    public:
+        DateType(std::shared_ptr<arrow::DateType> date_type);
+
+        ~DateType() {}
+
+    protected:
+        void getDateUnit(libmexclass::proxy::method::Context& context);
+};
+
+}

matlab/src/matlab/+arrow/+type/Date32Type.m

@@ -0,0 +1,33 @@
+%DATE32TYPE Type class for date32 data.
+
+% Licensed to the Apache Software Foundation (ASF) under one or more
+% contributor license agreements.  See the NOTICE file distributed with
+% this work for additional information regarding copyright ownership.
+% The ASF licenses this file to you 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.
+
+classdef Date32Type < arrow.type.DateType
+
+    methods
+
+        function obj = Date32Type(proxy)
+            arguments
+                proxy(1, 1) libmexclass.proxy.Proxy {validate(proxy, "arrow.type.proxy.Date32Type")}
+            end
+            import arrow.internal.proxy.validate
+
+            obj@arrow.type.DateType(proxy);
+        end
+
+    end
+
+end

matlab/src/matlab/+arrow/+type/DateType.m

@@ -0,0 +1,45 @@
+%DATETYPE Type class for date data.
+
+% Licensed to the Apache Software Foundation (ASF) under one or more
+% contributor license agreements.  See the NOTICE file distributed with
+% this work for additional information regarding copyright ownership.
+% The ASF licenses this file to you 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.
+
+classdef DateType < arrow.type.TemporalType
+
+    properties(Dependent, SetAccess=private, GetAccess=public)
+        DateUnit
+    end
+
+    methods
+        function obj = DateType(proxy)
+            arguments
+                proxy(1, 1) libmexclass.proxy.Proxy
+            end
+            obj@arrow.type.TemporalType(proxy);
+        end
+
+        function dateUnit = get.DateUnit(obj)
+            dateUnitvalue = obj.Proxy.getDateUnit();
+            dateUnit = arrow.type.DateUnit(dateUnitvalue);
+        end
+    end
+
+    methods (Access=protected)
+        function group = getPropertyGroups(~)
+            targets = ["ID" "DateUnit"];
+            group = matlab.mixin.util.PropertyGroup(targets);
+        end
+    end
+
+end

matlab/src/matlab/+arrow/+type/ID.m

@@ -32,7 +32,7 @@
         String  (13)
         % Binary (14)
         % FixedSizeBinary (15)
-        % Date32 (16)
+        Date32 (16)
         % Date64 (17)
         Timestamp (18)
         Time32    (19)

matlab/src/matlab/+arrow/date32.m

@@ -0,0 +1,20 @@
+% Licensed to the Apache Software Foundation (ASF) under one or more
+% contributor license agreements.  See the NOTICE file distributed with
+% this work for additional information regarding copyright ownership.
+% The ASF licenses this file to you 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.
+
+function type = date32()
+%DATE32 Creates an arrow.type.Date32Type object
+    proxy = arrow.internal.proxy.create("arrow.type.proxy.Date32Type");
+    type = arrow.type.Date32Type(proxy);
+end

matlab/test/arrow/type/tDate32Type.m

@@ -0,0 +1,81 @@
+% Licensed to the Apache Software Foundation (ASF) under one or more
+% contributor license agreements.  See the NOTICE file distributed with
+% this work for additional information regarding copyright ownership.
+% The ASF licenses this file to you 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.
+
+classdef tDate32Type < hFixedWidthType
+% Test class for arrow.type.Date32Type and arrow.date32
+
+    properties
+        ConstructionFcn = @arrow.date32
+        ArrowType = arrow.date32
+        TypeID = arrow.type.ID.Date32
+        BitWidth = int32(32)
+        ClassName = "arrow.type.Date32Type"
+    end
+
+    methods(Test)
+        function TestClass(testCase)
+            % Verify ArrowType is an object of the expected class type.
+            name = string(class(testCase.ArrowType));
+            testCase.verifyEqual(name, testCase.ClassName);
+        end
+
+        function DefaultDateUnit(testCase)
+            % Verify the default DateUnit is Day.
+            type = testCase.ArrowType;
+            actualUnit = type.DateUnit;
+            expectedUnit = arrow.type.DateUnit.Day;
+            testCase.verifyEqual(actualUnit, expectedUnit);
+        end
+
+        function Display(testCase)
+            % Verify the display of Date32Type objects.
+            %
+            % Example:
+            %
+            %  Date32Type with properties:
+            %
+            %          ID: Date32
+            %    DateUnit: Day
+            %
+            type = testCase.ConstructionFcn(); %#ok<NASGU>
+            classnameLink = "<a href=""matlab:helpPopup arrow.type.Date32Type"" style=""font-weight:bold"">Date32Type</a>";
+            header = "  " + classnameLink + " with properties:" + newline;
+            body = strjust(pad(["ID:"; "DateUnit:"]));
+            body = body + " " + ["Date32"; "Day"];
+            body = "    " + body;
+            footer = string(newline);
+            expectedDisplay = char(strjoin([header body' footer], newline));
+            actualDisplay = evalc('disp(type)');
+            testCase.verifyEqual(actualDisplay, expectedDisplay);
+        end
+
+        function DateUnitNoSetter(testCase)
+            % Verify that an error is thrown when trying to set the value
+            % of the DateUnit property.
+            type = arrow.date32();
+            testCase.verifyError(@() setfield(type, "DateUnit", "Millisecond"), "MATLAB:class:SetProhibited");
+        end
+
+        function InvalidProxy(testCase)
+            % Verify that an error is thrown when a Proxy of an unexpected
+            % type is passed to the arrow.type.Date32Type constructor.
+            array = arrow.array([1, 2, 3]);
+            proxy = array.Proxy;
+            testCase.verifyError(@() arrow.type.Date32Type(proxy), "arrow:proxy:ProxyNameMismatch");
+        end
+
+    end
+
+end

matlab/test/arrow/type/tID.m

@@ -42,6 +42,7 @@ function CastToUInt64(testCase)
                 ID.Float32,   11, ...
                 ID.Float64,   12, ...
                 ID.String,    13, ...
+                ID.Date32,    16, ...
                 ID.Timestamp, 18, ...
                 ID.Time32,    19, ...
                 ID.Time64,    20  ...

matlab/tools/cmake/BuildMatlabArrowInterface.cmake

@@ -55,6 +55,8 @@ set(MATLAB_ARROW_LIBMEXCLASS_CLIENT_PROXY_SOURCES "${CMAKE_SOURCE_DIR}/src/cpp/a
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/type.cc"
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/fixed_width_type.cc"
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/string_type.cc"
+                                                  "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/date_type.cc"
+                                                  "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/date32_type.cc"
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/timestamp_type.cc"
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/time_type.cc"
                                                   "${CMAKE_SOURCE_DIR}/src/cpp/arrow/matlab/type/proxy/time32_type.cc"