apacheGH-36874: [MATLAB] Move type constructor functions from the `ar…

…row.type` package to `arrow` package (apache#36875)

### Rationale for this change

When working on PR apache#36855, we realized it would be better to place all recommended public/user-facing APIs in the top-level `arrow` package. That's why we added the function `arrow.field` in the top-level `arrow` package instead of under `arrow.type`, even though the `Field` class is within `arrow.type` package.

### What changes are included in this PR?

1. Moved the type constructor functions (`arrow.type.int8()`, `arrow.type.timestamp()`, etc) from the `arrow.type` package to the `arrow package`. 

**Example: Old Way to Create a `Timestamp` Object:**

```matlab
>> type = arrow.type.timestmap(TimeUnit="nanosecond");
```

**Example: New Way to Create a `Timestamp` Object:**

```matlab
>> type = arrow.timestmap(TimeUnit="nanosecond");
```

### Are these changes tested?

Changes are covered by existing tests.

### Are there any user-facing changes?

Yes. 

NOTE: This is a breaking change, but the MATLAB interface is not yet stable.
* Closes: apache#36874

Authored-by: Sarah Gilmore <[email protected]>
Signed-off-by: Kevin Gurney <[email protected]>

matlab/test/arrow/array/tBooleanArray.m

@@ -22,7 +22,7 @@
         MatlabArrayFcn = @logical
         MatlabConversionFcn = @logical
         NullSubstitutionValue = false
-        ArrowType = arrow.type.boolean
+        ArrowType = arrow.boolean
     end
 
     methods(TestClassSetup)

matlab/test/arrow/array/tFloat32Array.m

@@ -24,7 +24,7 @@
         MaxValue = realmax("single")
         MinValue = realmin("single")
         NullSubstitutionValue = single(NaN)
-        ArrowType = arrow.type.float32
+        ArrowType = arrow.float32
     end
 
     methods(Test)

matlab/test/arrow/array/tFloat64Array.m

@@ -24,7 +24,7 @@
         MaxValue = realmax("double")
         MinValue = realmin("double")
         NullSubstitutionValue = NaN
-        ArrowType = arrow.type.float64
+        ArrowType = arrow.float64
     end
 
     methods(Test)

matlab/test/arrow/array/tInt16Array.m

@@ -24,7 +24,7 @@
         MaxValue = intmax("int16")
         MinValue = intmin("int16")
         NullSubstitutionValue = int16(0)
-        ArrowType = arrow.type.int16
+        ArrowType = arrow.int16
     end
 
 end

matlab/test/arrow/array/tInt32Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("int32")
         MinValue = intmin("int32")
         NullSubstitutionValue = int32(0)
-        ArrowType = arrow.type.int32
+        ArrowType = arrow.int32
     end
 end

matlab/test/arrow/array/tInt64Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("int64")
         MinValue = intmin("int64")
         NullSubstitutionValue = int64(0)
-        ArrowType = arrow.type.int64
+        ArrowType = arrow.int64
     end
 end

matlab/test/arrow/array/tInt8Array.m

@@ -24,7 +24,7 @@
         MaxValue = intmax("int8")
         MinValue = intmin("int8")
         NullSubstitutionValue = int8(0)
-        ArrowType = arrow.type.int8
+        ArrowType = arrow.int8
     end
 
 end

matlab/test/arrow/array/tStringArray.m

@@ -22,7 +22,7 @@
         MatlabArrayFcn = @string
         MatlabConversionFcn = @string
         NullSubstitutionValue = string(missing)
-        ArrowType = arrow.type.string
+        ArrowType = arrow.string
     end
 
     methods(TestClassSetup)

matlab/test/arrow/array/tUInt16Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("uint16")
         MinValue = intmin("uint16")
         NullSubstitutionValue = uint16(0)
-        ArrowType = arrow.type.uint16
+        ArrowType = arrow.uint16
     end
 end

matlab/test/arrow/array/tUInt32Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("uint32")
         MinValue = intmin("uint32")
         NullSubstitutionValue = uint32(0)
-        ArrowType = arrow.type.uint32
+        ArrowType = arrow.uint32
     end
 end

matlab/test/arrow/array/tUInt64Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("uint64")
         MinValue = intmin("uint64")
         NullSubstitutionValue = uint64(0)
-        ArrowType = arrow.type.uint64
+        ArrowType = arrow.uint64
     end
 end

matlab/test/arrow/array/tUInt8Array.m

@@ -24,6 +24,6 @@
         MaxValue = intmax("uint8")
         MinValue = intmin("uint8")
         NullSubstitutionValue = uint8(0)
-        ArrowType = arrow.type.uint8
+        ArrowType = arrow.uint8
     end
 end

matlab/test/arrow/type/tBooleanType.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.BooleanType
 
     properties
-        ArrowType = arrow.type.boolean
+        ArrowType = arrow.boolean
         TypeID = arrow.type.ID.Boolean
         BitWidth = int32(1)
         ClassName = "arrow.type.BooleanType"

matlab/test/arrow/type/tField.m

@@ -19,7 +19,7 @@
     methods(Test)
         function TestBasic(testCase)
             name = "A";
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(name, type);
 
             testCase.verifyEqual(field.Name, name);
@@ -29,19 +29,19 @@ function TestBasic(testCase)
         function TestSupportedTypes(testCase)
             name = "name";
             supportedTypes = { ...
-                                 arrow.type.uint8, ...
-                                 arrow.type.uint16, ...
-                                 arrow.type.uint32, ...
-                                 arrow.type.uint64, ...
-                                 arrow.type.int8, ...
-                                 arrow.type.int16, ...
-                                 arrow.type.int32, ...
-                                 arrow.type.int64, ...
-                                 arrow.type.boolean, ...
-                                 arrow.type.float32, ...
-                                 arrow.type.float64, ...
-                                 arrow.type.string, ...
-                                 arrow.type.timestamp, ...
+                                 arrow.uint8, ...
+                                 arrow.uint16, ...
+                                 arrow.uint32, ...
+                                 arrow.uint64, ...
+                                 arrow.int8, ...
+                                 arrow.int16, ...
+                                 arrow.int32, ...
+                                 arrow.int64, ...
+                                 arrow.boolean, ...
+                                 arrow.float32, ...
+                                 arrow.float64, ...
+                                 arrow.string, ...
+                                 arrow.timestamp, ...
                              };
             for ii = 1:numel(supportedTypes)
                 supportedType = supportedTypes{ii};
@@ -56,7 +56,7 @@ function TestNameUnicode(testCase)
             tree =  "🌲";
             mango = "🥭";
 
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(smiley, type);
 
             testCase.verifyEqual(field.Name, smiley);
@@ -75,13 +75,13 @@ function TestNameUnicode(testCase)
 
         function TestErrorIfNameStringMissing(testCase)
             name = string(missing);
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             testCase.verifyError(@() arrow.field(name, type), "MATLAB:validators:mustBeNonmissing");
         end
 
         function TestNameEmptyString(testCase)
             name = "";
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(name, type);
 
             testCase.verifyEqual(field.Name, name);
@@ -90,7 +90,7 @@ function TestNameEmptyString(testCase)
 
         function TestNameCharVector(testCase)
             name = 'ABC';
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(name, type);
 
             testCase.verifyEqual(field.Name, string(name));
@@ -99,7 +99,7 @@ function TestNameCharVector(testCase)
 
         function TestNameNumber(testCase)
             name = 123;
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(name, type);
 
             testCase.verifyEqual(field.Name, string(123));
@@ -114,17 +114,17 @@ function TestArrowTypeUnsupportedInput(testCase)
 
         function TestNameUnsupportedInput(testCase)
             name = table();
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             testCase.verifyError(@() arrow.field(name, type), "MATLAB:validation:UnableToConvert");
         end
 
         function TestImmutableProperties(testCase)
             name = "A";
-            type = arrow.type.uint64;
+            type = arrow.uint64;
             field = arrow.field(name, type);
 
             testCase.verifyError(@() setfield(field, "Name", "NewValue"), "MATLAB:class:noSetMethod")
-            testCase.verifyError(@() setfield(field, "Type", arrow.type.boolean), "MATLAB:class:noSetMethod")
+            testCase.verifyError(@() setfield(field, "Type", arrow.boolean), "MATLAB:class:noSetMethod")
         end
 
     end

matlab/test/arrow/type/tFloat32Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Float32Type
 
     properties
-        ArrowType = arrow.type.float32
+        ArrowType = arrow.float32
         TypeID = arrow.type.ID.Float32
         BitWidth = int32(32)
         ClassName = "arrow.type.Float32Type"

matlab/test/arrow/type/tFloat64Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Float64Type
 
     properties
-        ArrowType = arrow.type.float64
+        ArrowType = arrow.float64
         TypeID = arrow.type.ID.Float64
         BitWidth = int32(64)
         ClassName = "arrow.type.Float64Type"

matlab/test/arrow/type/tInt16Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Int16Type
 
     properties
-        ArrowType = arrow.type.int16
+        ArrowType = arrow.int16
         TypeID = arrow.type.ID.Int16
         BitWidth = int32(16)
         ClassName = "arrow.type.Int16Type"

matlab/test/arrow/type/tInt32Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Int32Type
 
     properties
-        ArrowType = arrow.type.int32
+        ArrowType = arrow.int32
         TypeID = arrow.type.ID.Int32
         BitWidth = int32(32)
         ClassName = "arrow.type.Int32Type"

matlab/test/arrow/type/tInt64Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Int64Type
 
     properties
-        ArrowType = arrow.type.int64
+        ArrowType = arrow.int64
         TypeID = arrow.type.ID.Int64
         BitWidth = int32(64)
         ClassName = "arrow.type.Int64Type"

matlab/test/arrow/type/tInt8Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.Int8Type
 
     properties
-        ArrowType = arrow.type.int8
+        ArrowType = arrow.int8
         TypeID = arrow.type.ID.Int8
         BitWidth = int32(8)
         ClassName = "arrow.type.Int8Type"

matlab/test/arrow/type/tStringType.m

@@ -19,14 +19,14 @@
     methods (Test)
 
         function Basic(tc)
-            type = arrow.type.string;
+            type = arrow.string;
             className = string(class(type));
             tc.verifyEqual(className, "arrow.type.StringType");
             tc.verifyEqual(type.ID, arrow.type.ID.String);
         end
 
         function NumFields(tc)
-            type = arrow.type.string;
+            type = arrow.string;
             tc.verifyEqual(type.NumFields, int32(0));
         end
 

matlab/test/arrow/type/tTimestampType.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.TimestampType
 
     properties
-        ArrowType = arrow.type.timestamp
+        ArrowType = arrow.timestamp
         TypeID = arrow.type.ID.Timestamp
         BitWidth = int32(64)
         ClassName = "arrow.type.TimestampType"
@@ -32,15 +32,15 @@ function TestClass(testCase)
 
         function DefaultTimeUnit(testCase)
         % Verify the default TimeUnit is Microsecond
-            type = arrow.type.timestamp;
+            type = arrow.timestamp;
             actualUnit = type.TimeUnit;
             expectedUnit = arrow.type.TimeUnit.Microsecond; 
             testCase.verifyEqual(actualUnit, expectedUnit);
         end
 
         function DefaultTimeZone(testCase)
         % Verify the default TimeZone is ""
-            type = arrow.type.timestamp;
+            type = arrow.timestamp;
             actualTimezone = type.TimeZone;
             expectedTimezone = "";
             testCase.verifyEqual(actualTimezone, expectedTimezone);
@@ -53,7 +53,7 @@ function SupplyTimeUnitEnum(testCase)
                             TimeUnit.Microsecond, TimeUnit.Nanosecond];
 
             for unit = expectedUnit
-                type = timestamp(TimeUnit=unit);
+                type = arrow.timestamp(TimeUnit=unit);
                 testCase.verifyEqual(type.TimeUnit, unit);
             end
         end
@@ -67,42 +67,42 @@ function SupplyTimeUnitString(testCase)
                             TimeUnit.Microsecond, TimeUnit.Nanosecond];
 
             for ii = 1:numel(unitString)
-                type = timestamp(TimeUnit=unitString(ii));
+                type = arrow.timestamp(TimeUnit=unitString(ii));
                 testCase.verifyEqual(type.TimeUnit, expectedUnit(ii));
             end
         end
 
         function SupplyTimeZone(testCase)
         % Supply the TimeZone. 
-            type = arrow.type.timestamp(TimeZone="America/New_York");
+            type = arrow.timestamp(TimeZone="America/New_York");
             testCase.verifyEqual(type.TimeZone, "America/New_York");
         end
 
         function ErrorIfMissingStringTimeZone(testCase)
-            fcn = @() arrow.type.timestamp(TimeZone=string(missing));
+            fcn = @() arrow.timestamp(TimeZone=string(missing));
             testCase.verifyError(fcn, "MATLAB:validators:mustBeNonmissing");
         end
 
         function ErrorIfTimeZoneIsNonScalar(testCase)
-            fcn = @() arrow.type.timestamp(TimeZone=["a", "b"]);
+            fcn = @() arrow.timestamp(TimeZone=["a", "b"]);
             testCase.verifyError(fcn, "MATLAB:validation:IncompatibleSize");
 
-              fcn = @() arrow.type.timestamp(TimeZone=strings(0, 0));
+              fcn = @() arrow.timestamp(TimeZone=strings(0, 0));
             testCase.verifyError(fcn, "MATLAB:validation:IncompatibleSize");
         end
 
         function ErrorIfAmbiguousTimeUnit(testCase)
-            fcn = @() arrow.type.timestamp(TimeUnit="mi");
+            fcn = @() arrow.timestamp(TimeUnit="mi");
             testCase.verifyError(fcn, "MATLAB:validation:UnableToConvert");
         end
 
         function ErrorIfTimeUnitIsNonScalar(testCase)
             units = [arrow.type.TimeUnit.Second; arrow.type.TimeUnit.Millisecond];
-            fcn = @() arrow.type.timestamp(TimeZone=units);
+            fcn = @() arrow.timestamp(TimeZone=units);
             testCase.verifyError(fcn, "MATLAB:validation:IncompatibleSize");
 
             units = ["second" "millisecond"];
-            fcn = @() arrow.type.timestamp(TimeZone=units);
+            fcn = @() arrow.timestamp(TimeZone=units);
             testCase.verifyError(fcn, "MATLAB:validation:IncompatibleSize");
         end
     end

matlab/test/arrow/type/tUInt16Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.UInt16Type
 
     properties
-        ArrowType = arrow.type.uint16
+        ArrowType = arrow.uint16
         TypeID = arrow.type.ID.UInt16
         BitWidth = int32(16)
         ClassName = "arrow.type.UInt16Type"

matlab/test/arrow/type/tUInt32Type.m

@@ -17,7 +17,7 @@
 % Test class for arrow.type.UInt32Type
 
     properties
-        ArrowType = arrow.type.uint32
+        ArrowType = arrow.uint32
         TypeID = arrow.type.ID.UInt32
         BitWidth = int32(32)
         ClassName = "arrow.type.UInt32Type"