apacheGH-37230: [MATLAB] Add arrow.type.Date64Type class and `arrow…

….date64` construction function (apache#37578)

### Rationale for this change

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

### What changes are included in this PR?

1. New `arrow.type.Date64Type` class.
2. New `arrow.date64` construction function that returns an `arrow.type.Date64Type` instance.
3. New `arrow.type.ID.Date64` type enumeration value.

**Example**
```matlab
>> type = arrow.date64()

type = 

  Date64Type with properties:

          ID: Date64
    DateUnit: Millisecond
```

### Are these changes tested?

Yes.

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

### Are there any user-facing changes?

Yes.

1. There is a new public `arrow.type.Date64Type` class.
2. There is a new public `arrow.date64` construction function.
3. There is a new `arrow.type.ID.Date64` type enumeration value.

### Future Directions

1. apache#37572
2. apache#37577
* Closes: apache#37230

Authored-by: Kevin Gurney <kgurney@mathworks.com>
Signed-off-by: Kevin Gurney <kgurney@mathworks.com>

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

@@ -29,6 +29,7 @@
 #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/date64_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"
@@ -76,6 +77,7 @@ libmexclass::proxy::MakeResult Factory::make_proxy(const ClassName& class_name,
  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.type.proxy.Date64Type , arrow::matlab::type::proxy::Date64Type);
  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/date64_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/date64_type.h"
+
+namespace arrow::matlab::type::proxy {
+
+ Date64Type::Date64Type(std::shared_ptr<arrow::Date64Type> date64_type) : DateType(std::move(date64_type)) {}
+
+ libmexclass::proxy::MakeResult Date64Type::make(const libmexclass::proxy::FunctionArguments& constructor_arguments) {
+ using Date64TypeProxy = arrow::matlab::type::proxy::Date64Type;
+
+ const auto type = arrow::date64();
+ const auto date64_type = std::static_pointer_cast<arrow::Date64Type>(type);
+ return std::make_shared<Date64TypeProxy>(std::move(date64_type));
+ }
+}

matlab/src/cpp/arrow/matlab/type/proxy/date64_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 Date64Type : public arrow::matlab::type::proxy::DateType {
+
+ public:
+ Date64Type(std::shared_ptr<arrow::Date64Type> date64_type);
+
+ ~Date64Type() {}
+
+ static libmexclass::proxy::MakeResult make(const libmexclass::proxy::FunctionArguments& constructor_arguments);
+
+ };
+
+}
+

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

@@ -0,0 +1,33 @@
+%DATE64TYPE Type class for date64 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 Date64Type < arrow.type.DateType
+
+ methods
+
+ function obj = Date64Type(proxy)
+ arguments
+ proxy(1, 1) libmexclass.proxy.Proxy {validate(proxy, "arrow.type.proxy.Date64Type")}
+ end
+ import arrow.internal.proxy.validate
+
+ obj@arrow.type.DateType(proxy);
+ end
+
+ end
+
+end

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

@@ -33,7 +33,7 @@
  % Binary (14)
  % FixedSizeBinary (15)
  Date32 (16)
- % Date64 (17)
+ Date64 (17)
  Timestamp (18)
  Time32 (19)
  Time64 (20)

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

@@ -1,3 +1,5 @@
+%DATE32 Creates an arrow.type.Date32Type object
+
 % 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.
@@ -14,7 +16,6 @@
 % 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/src/matlab/+arrow/date64.m

@@ -0,0 +1,21 @@
+%DATE64 Creates an arrow.type.Date64Type object
+
+% 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 = date64()
+ proxy = arrow.internal.proxy.create("arrow.type.proxy.Date64Type");
+ type = arrow.type.Date64Type(proxy);
+end

matlab/test/arrow/type/tDate32Type.m

@@ -1,3 +1,5 @@
+% Test class for arrow.type.Date32Type and arrow.date32
+
 % 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.
@@ -14,7 +16,6 @@
 % permissions and limitations under the License.
 
 classdef tDate32Type < hFixedWidthType
-% Test class for arrow.type.Date32Type and arrow.date32
 
  properties
  ConstructionFcn = @arrow.date32

matlab/test/arrow/type/tDate64Type.m

@@ -0,0 +1,116 @@
+% Test class for arrow.type.Date64Type and arrow.date64
+
+% 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 tDate64Type < hFixedWidthType
+
+ properties
+ ConstructionFcn = @arrow.date64
+ ArrowType = arrow.date64
+ TypeID = arrow.type.ID.Date64
+ BitWidth = int32(64)
+ ClassName = "arrow.type.Date64Type"
+ 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 Millisecond.
+ type = testCase.ArrowType;
+ actualUnit = type.DateUnit;
+ expectedUnit = arrow.type.DateUnit.Millisecond;
+ testCase.verifyEqual(actualUnit, expectedUnit);
+ end
+
+ function Display(testCase)
+ % Verify the display of Date64Type objects.
+ %
+ % Example:
+ %
+ % Date32Type with properties:
+ %
+ % ID: Date64
+ % DateUnit: Millisecond
+ %
+ type = testCase.ConstructionFcn(); %#ok<NASGU>
+ classnameLink = "<a href=""matlab:helpPopup arrow.type.Date64Type"" style=""font-weight:bold"">Date64Type</a>";
+ header = " " + classnameLink + " with properties:" + newline;
+ body = strjust(pad(["ID:"; "DateUnit:"]));
+ body = body + " " + ["Date64"; "Millisecond"];
+ 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.date64();
+ testCase.verifyError(@() setfield(type, "DateUnit", "Day"), "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.Date64Type constructor.
+ array = arrow.array([1, 2, 3]);
+ proxy = array.Proxy;
+ testCase.verifyError(@() arrow.type.Date64Type(proxy), "arrow:proxy:ProxyNameMismatch");
+ end
+
+ function IsEqualTrue(testCase)
+ % Verifies isequal method of arrow.type.Date64Type returns true if
+ % these conditions are met:
+ %
+ % 1. All input arguments have a class type arrow.type.Date64Type
+ % 2. All inputs have the same size
+
+ % Scalar Date64Type arrays
+ date64Type1 = arrow.date64();
+ date64Type2 = arrow.date64();
+ testCase.verifyTrue(isequal(date64Type1, date64Type2));
+
+ % Non-scalar Date64Type arrays
+ typeArray1 = [date64Type1 date64Type1];
+ typeArray2 = [date64Type2 date64Type2];
+ testCase.verifyTrue(isequal(typeArray1, typeArray2));
+ end
+
+ function IsEqualFalse(testCase)
+ % Verifies the isequal method of arrow.type.Date64Type returns
+ % false when expected.
+
+ % Pass a different arrow.type.Type subclass to isequal
+ date64Type = arrow.date64();
+ int32Type = arrow.int32();
+ testCase.verifyFalse(isequal(date64Type, int32Type));
+ testCase.verifyFalse(isequal([date64Type date64Type], [int32Type int32Type]));
+
+ % Date64Type arrays have different sizes
+ typeArray1 = [date64Type date64Type];
+ typeArray2 = [date64Type date64Type]';
+ testCase.verifyFalse(isequal(typeArray1, typeArray2));
+ end
+
+ end
+
+end

matlab/test/arrow/type/tID.m

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

matlab/tools/cmake/BuildMatlabArrowInterface.cmake

@@ -59,6 +59,7 @@ set(MATLAB_ARROW_LIBMEXCLASS_CLIENT_PROXY_SOURCES "${CMAKE_SOURCE_DIR}/src/cpp/a
  "${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/date64_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"