GH-35557 [MATLAB] Add unsigned integer array MATLAB classes (i.e. `UI…

…nt8Array`, `UInt16Array`, `UInt32Array`, `UInt64Array`) (#35562) ### Rationale for this change Followup to #35495 in which we added the MATLAB class `Float32Array`. This pull request adds support for round tripping signed integer between `arrow.array.<Type>Array` classes and associated MATLAB types (e.g. `uint8`, `uint16`, `uint32`, `uint64`). | Arrow Array Type | MATLAB Type | | ----------------- | -------------- | | `UInt8Array` | `uint8`| | `UInt16Array` | `uint16`| | `UInt32Array` | `uint32`| | `UInt64Array` | `uint64`| Example of round-tripping `uint8` data: ```matlab >> uint8MATLABArray = uint8([1 2 3]') uint8MATLABArray = 3×1 uint8 column vector 1 2 3 >> uint8ArrowArray = arrow.array.UInt8Array(uint8MATLABArray) uint8ArrowArray = [ 1, 2, 3 ] >> uint8MATLABArrayRoundTripped = toMATLAB(uint8ArrowArray) uint8MATLABArrayRoundTripped = 3×1 uint8 column vector 1 2 3 >> all(uint8MATLABArray == uint8MATLABArrayRoundTripped) ans = logical 1 ``` ### What changes are included in this PR? Added four new unsigned integer type `arrow.array.<Array>` concrete subclasses. 1. `arrow.array.UInt8Array` 2. `arrow.array.UInt16Array` 3. `arrow.array.UInt32Array` 4. `arrow.array.UInt64Array` ### Are these changes tested? Yes, we added the following four test classes: 1. `tUInt8Array.m` 2. `tUInt16Array.m` 3. `tUInt32Array.m` 4. `tUInt64Array.m` ### Are there any user-facing changes? Yes. This change introduces 4 new publicly documented classes: 1. `arrow.array.UInt8Array` 2. `arrow.array.UInt16Array` 3. `arrow.array.UInt32Array` 4. `arrow.array.UInt64Array` ### Future Directions 1. Add support for null values (i.e. validity bitmap) for the unsigned integer array types. ### NOTES 1. Thank you to @ kevingurney for his help with this PR! * Closes: #35557 Lead-authored-by: Sarah Gilmore <sgilmore@mathworks.com> Co-authored-by: Kevin Gurney <kgurney@mathworks.com> Signed-off-by: Sutou Kouhei <kou@clear-code.com>
apache · May 19, 2023 · 4129fe1 · 4129fe1
1 parent 00e6996
commit 4129fe1
Show file tree

Hide file tree

Showing 9 changed files with 274 additions and 0 deletions.
diff --git a/matlab/src/cpp/arrow/matlab/proxy/factory.cc b/matlab/src/cpp/arrow/matlab/proxy/factory.cc
@@ -25,6 +25,12 @@ namespace arrow::matlab::proxy {
 
 std::shared_ptr<Proxy> Factory::make_proxy(const ClassName& class_name, const FunctionArguments& constructor_arguments) {
 
+    // Register MATLAB Proxy classes for unsigned integer arrays
+    REGISTER_PROXY(arrow.array.proxy.UInt8Array, arrow::matlab::array::proxy::NumericArray<uint8_t>);
+    REGISTER_PROXY(arrow.array.proxy.UInt16Array, arrow::matlab::array::proxy::NumericArray<uint16_t>);
+    REGISTER_PROXY(arrow.array.proxy.UInt32Array, arrow::matlab::array::proxy::NumericArray<uint32_t>);
+    REGISTER_PROXY(arrow.array.proxy.UInt64Array, arrow::matlab::array::proxy::NumericArray<uint64_t>);
+
     // Register MATLAB Proxy classes with corresponding C++ Proxy classes.
     REGISTER_PROXY(arrow.array.proxy.Float32Array, arrow::matlab::array::proxy::NumericArray<float>);
     REGISTER_PROXY(arrow.array.proxy.Float64Array, arrow::matlab::array::proxy::NumericArray<double>);

diff --git a/matlab/src/matlab/+arrow/+array/UInt16Array.m b/matlab/src/matlab/+arrow/+array/UInt16Array.m
@@ -0,0 +1,40 @@
+classdef UInt16Array < arrow.array.Array
+    % arrow.array.UInt16Array
+
+    % 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.
+
+    properties (Hidden, SetAccess=private)
+        MatlabArray = uint16([])
+    end
+
+    methods
+        function obj = UInt16Array(data, opts)
+            arguments
+                data
+                opts.DeepCopy = false
+            end
+            validateattributes(data, "uint16", ["2d", "nonsparse", "real"]);
+            if ~isempty(data), validateattributes(data, "uint16", "vector"); end
+            obj@arrow.array.Array("Name", "arrow.array.proxy.UInt16Array", "ConstructorArguments", {data, opts.DeepCopy});
+            % Store a reference to the array if not doing a deep copy
+            if (~opts.DeepCopy), obj.MatlabArray = data; end
+        end
+
+        function data = uint16(obj)
+            data = obj.Proxy.toMATLAB();
+        end
+    end
+end
diff --git a/matlab/src/matlab/+arrow/+array/UInt32Array.m b/matlab/src/matlab/+arrow/+array/UInt32Array.m
@@ -0,0 +1,40 @@
+classdef UInt32Array < arrow.array.Array
+    % arrow.array.UInt32Array
+
+    % 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.
+
+    properties (Hidden, SetAccess=private)
+        MatlabArray = uint32([])
+    end
+
+    methods
+        function obj = UInt32Array(data, opts)
+            arguments
+                data
+                opts.DeepCopy = false
+            end
+            validateattributes(data, "uint32", ["2d", "nonsparse", "real"]);
+            if ~isempty(data), validateattributes(data, "uint32", "vector"); end
+            obj@arrow.array.Array("Name", "arrow.array.proxy.UInt32Array", "ConstructorArguments", {data, opts.DeepCopy});
+            % Store a reference to the array if not doing a deep copy
+            if (~opts.DeepCopy), obj.MatlabArray = data; end
+        end
+
+        function data = uint32(obj)
+            data = obj.Proxy.toMATLAB();
+        end
+    end
+end
diff --git a/matlab/src/matlab/+arrow/+array/UInt64Array.m b/matlab/src/matlab/+arrow/+array/UInt64Array.m
@@ -0,0 +1,40 @@
+classdef UInt64Array < arrow.array.Array
+    % arrow.array.UInt64Array
+
+    % 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.
+
+    properties (Hidden, SetAccess=private)
+        MatlabArray = uint64([])
+    end
+
+    methods
+        function obj = UInt64Array(data, opts)
+            arguments
+                data
+                opts.DeepCopy = false
+            end
+            validateattributes(data, "uint64", ["2d", "nonsparse", "real"]);
+            if ~isempty(data), validateattributes(data, "uint64", "vector"); end
+            obj@arrow.array.Array("Name", "arrow.array.proxy.UInt64Array", "ConstructorArguments", {data, opts.DeepCopy});
+            % Store a reference to the array if not doing a deep copy
+            if (~opts.DeepCopy), obj.MatlabArray = data; end
+        end
+
+        function data = uint64(obj)
+            data = obj.Proxy.toMATLAB();
+        end
+    end
+end
diff --git a/matlab/src/matlab/+arrow/+array/UInt8Array.m b/matlab/src/matlab/+arrow/+array/UInt8Array.m
@@ -0,0 +1,40 @@
+classdef UInt8Array < arrow.array.Array
+    % arrow.array.UInt8Array
+
+    % 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.
+
+    properties (Hidden, SetAccess=private)
+        MatlabArray = uint8([])
+    end
+
+    methods
+        function obj = UInt8Array(data, opts)
+            arguments
+                data
+                opts.DeepCopy = false
+            end
+            validateattributes(data, "uint8", ["2d", "nonsparse", "real"]);
+            if ~isempty(data), validateattributes(data, "uint8", "vector"); end
+            obj@arrow.array.Array("Name", "arrow.array.proxy.UInt8Array", "ConstructorArguments", {data, opts.DeepCopy});
+            % Store a reference to the array if not doing a deep copy
+            if (~opts.DeepCopy), obj.MatlabArray = data; end
+        end
+
+        function data = uint8(obj)
+            data = obj.Proxy.toMATLAB();
+        end
+    end
+end
diff --git a/matlab/test/arrow/array/tUInt16Array.m b/matlab/test/arrow/array/tUInt16Array.m
@@ -0,0 +1,27 @@
+classdef tUInt16Array < hNumericArray
+    % Tests for arrow.array.UInt16Array
+
+    % 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.
+
+    properties
+        ArrowArrayClassName = "arrow.array.UInt16Array"
+        ArrowArrayConstructor = @arrow.array.UInt16Array
+        MatlabConversionFcn = @uint16 % uint16 method on class
+        MatlabArrayFcn = @uint16 % uint16 function
+        MaxValue = intmax("uint16")
+        MinValue = intmin("uint16")
+    end
+end
diff --git a/matlab/test/arrow/array/tUInt32Array.m b/matlab/test/arrow/array/tUInt32Array.m
@@ -0,0 +1,27 @@
+classdef tUInt32Array < hNumericArray
+    % Tests for arrow.array.UInt32Array
+
+    % 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.
+
+    properties
+        ArrowArrayClassName = "arrow.array.UInt32Array"
+        ArrowArrayConstructor = @arrow.array.UInt32Array
+        MatlabConversionFcn = @uint32 % uint32 method on class
+        MatlabArrayFcn = @uint32 % uint32 function
+        MaxValue = intmax("uint32")
+        MinValue = intmin("uint32")
+    end
+end
diff --git a/matlab/test/arrow/array/tUInt64Array.m b/matlab/test/arrow/array/tUInt64Array.m
@@ -0,0 +1,27 @@
+classdef tUInt64Array < hNumericArray
+    % Tests for arrow.array.UInt64Array
+
+    % 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.
+
+    properties
+        ArrowArrayClassName = "arrow.array.UInt64Array"
+        ArrowArrayConstructor = @arrow.array.UInt64Array
+        MatlabConversionFcn = @uint64 % uint64 method on class
+        MatlabArrayFcn = @uint64 % uint64 function
+        MaxValue = intmax("uint64")
+        MinValue = intmin("uint64")
+    end
+end
diff --git a/matlab/test/arrow/array/tUInt8Array.m b/matlab/test/arrow/array/tUInt8Array.m
@@ -0,0 +1,27 @@
+classdef tUInt8Array < hNumericArray
+    % Tests for arrow.array.UInt8Array
+
+    % 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.
+
+    properties
+        ArrowArrayClassName = "arrow.array.UInt8Array"
+        ArrowArrayConstructor = @arrow.array.UInt8Array
+        MatlabConversionFcn = @uint8 % uint8 method on class
+        MatlabArrayFcn = @uint8 % uint8 function
+        MaxValue = intmax("uint8")
+        MinValue = intmin("uint8")
+    end
+end