Add new function: AutoFilter

- Update unit test

Author: xuri

Excelize.Tests/UnitTest.cs

@@ -877,6 +877,37 @@ public void TestAddSparkline()
         Assert.Empty(f.Close());
     }
 
+    [Fact]
+    public void TestAutoFilter()
+    {
+        File f = Excelize.NewFile();
+        Assert.Null(
+            Record.Exception(() =>
+            {
+                f.AutoFilter("Sheet1", "A2:D4", new AutoFilterOptions[] { });
+                f.AutoFilter(
+                    "Sheet1",
+                    "F2:H4",
+                    new AutoFilterOptions[]
+                    {
+                        new AutoFilterOptions { Column = "F", Expression = "x != blanks" },
+                    }
+                );
+            })
+        );
+        RuntimeError err = Assert.Throws<RuntimeError>(() =>
+            f.AutoFilter("SheetN", "L1:N4", new AutoFilterOptions[] { })
+        );
+        Assert.Equal("sheet SheetN does not exist", err.Message);
+        Assert.Null(
+            Record.Exception(() =>
+            {
+                f.SaveAs("TestAutoFilter.xlsx");
+            })
+        );
+        Assert.Empty(f.Close());
+    }
+
     [StructLayout(LayoutKind.Sequential)]
     public unsafe struct C1
     {

Excelize/Excelize.cs

@@ -166,6 +166,15 @@ ref TypesC.Table opts
         [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)]
         internal static extern IntPtr AddVBAProject(long fileIdx, byte[] b, int bLen);
 
+        [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)]
+        internal static extern IntPtr AutoFilter(
+            long fileIdx,
+            [MarshalAs(UnmanagedType.LPUTF8Str)] string sheet,
+            [MarshalAs(UnmanagedType.LPUTF8Str)] string range,
+            [In, MarshalAs(UnmanagedType.LPArray)] TypesC.AutoFilterOptions[] options,
+            int length
+        );
+
         [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl)]
         internal static extern TypesC.CellNameToCoordinatesResult CellNameToCoordinates(
             [MarshalAs(UnmanagedType.LPUTF8Str)] string cell
@@ -2185,6 +2194,131 @@ public void AddVBAProject(byte[] buffer)
                 throw new RuntimeError(err);
         }
 
+        /// <summary>
+        /// Adds an auto filter to a worksheet using the specified sheet name,
+        /// range reference, and filter options.
+        ///
+        /// An auto filter in Excel provides a way to filter a 2D range of data
+        /// based on simple criteria. For example, to apply an auto filter to
+        /// the range <c>A1:D4</c> on the worksheet "Sheet1":
+        ///
+        /// <code><![CDATA[
+        /// f.AutoFilter("Sheet1", "A1:D4", Array.Empty<AutoFilterOptions>());
+        /// ]]></code>
+        ///
+        /// To filter data within an auto filter:
+        ///
+        /// <code>
+        /// f.AutoFilter("Sheet1", "A1:D4", new AutoFilterOptions[]
+        /// {
+        ///     new AutoFilterOptions { Column = "B", Expression = "x != blanks" }
+        /// });
+        /// </code>
+        ///
+        /// <para>
+        /// <b>Column</b> specifies which column in the auto filter range will
+        /// apply a filter.
+        /// </para>
+        ///
+        /// <para>
+        /// Note: Specifying filter conditions alone is not sufficient. Rows
+        /// that do not match the filter criteria must also be hidden manually
+        /// using <c>SetRowVisible</c>. The library cannot automatically hide
+        /// rows because this is outside the Excel file format's capabilities.
+        /// </para>
+        ///
+        /// <para>
+        /// <b>Expression</b> defines the filter criteria. The following
+        /// operators are supported:
+        /// </para>
+        ///
+        /// <list type="bullet">
+        ///   <item><description><c>==</c></description></item>
+        ///   <item><description><c>!=</c></description></item>
+        ///   <item><description><c>&gt;</c></description></item>
+        ///   <item><description><c>&lt;</c></description></item>
+        ///   <item><description><c>&gt;=</c></description></item>
+        ///   <item><description><c>&lt;=</c></description></item>
+        ///   <item><description><c>and</c></description></item>
+        ///   <item><description><c>or</c></description></item>
+        /// </list>
+        ///
+        /// <para>
+        /// Expressions may contain a single condition or two conditions
+        /// combined using <c>and</c> or <c>or</c>. Examples:
+        /// </para>
+        ///
+        /// <code>
+        /// x &lt; 2000
+        /// x &gt; 2000
+        /// x == 2000
+        /// x &gt; 2000 and x &lt; 5000
+        /// x == 2000 or x == 5000
+        /// </code>
+        ///
+        /// <para>
+        /// Filtering blank or non-blank values:
+        /// </para>
+        ///
+        /// <code>
+        /// x == Blanks
+        /// x == NonBlanks
+        /// </code>
+        ///
+        /// <para>
+        /// Simple string matching is also supported:
+        /// </para>
+        ///
+        /// <code>
+        /// x == b*      // begins with b
+        /// x != b*      // doesn't begin with b
+        /// x == *b      // ends with b
+        /// x != *b      // doesn't end with b
+        /// x == *b*     // contains b
+        /// x != *b*     // doesn't contain b
+        /// </code>
+        ///
+        /// <para>
+        /// Wildcards:
+        /// </para>
+        /// <list type="bullet">
+        ///   <item><description><c>*</c> matches any sequence of characters or digits.</description></item>
+        ///   <item><description><c>?</c> matches any single character or digit.</description></item>
+        ///   <item><description><c>~</c> escapes Excel's wildcard characters.</description></item>
+        /// </list>
+        ///
+        /// <para>
+        /// In expressions, the placeholder variable (commonly shown as <c>x</c>)
+        /// may be any simple string. The actual placeholder name is ignored, so
+        /// the following are equivalent:
+        /// </para>
+        ///
+        /// <code>
+        /// x     &lt; 2000
+        /// col   &lt; 2000
+        /// Price &lt; 2000
+        /// </code>
+        /// </summary>
+        /// <param name="sheet">The worksheet name</param>
+        /// <param name="range">The top-left and right-bottom cell range reference</param>
+        /// <param name="opts"> The auto filter options</param>
+        /// <exception cref="RuntimeError">Return None if no error occurred,
+        /// otherwise raise a RuntimeError with the message.</exception>
+        public void AutoFilter(string sheet, string range, AutoFilterOptions[] opts)
+        {
+            TypesC.AutoFilterOptions[] arr = new TypesC.AutoFilterOptions[opts.Length];
+            for (int i = 0; i < opts.Length; i++)
+            {
+                arr[i] = (TypesC.AutoFilterOptions)
+                    Lib.CsToC(opts[i], new TypesC.AutoFilterOptions());
+            }
+            string err = Marshal.PtrToStringUTF8(
+                Lib.AutoFilter(FileIdx, sheet, range, arr, arr.Length)
+            );
+            if (!string.IsNullOrEmpty(err))
+                throw new RuntimeError(err);
+        }
+
         /// <summary>
         /// Closes and cleanup the open temporary file for the spreadsheet.
         /// </summary>

Excelize/TypesC.cs

@@ -118,6 +118,13 @@ public struct Protection
         public bool Locked;
     }
 
+    [StructLayout(LayoutKind.Sequential)]
+    public unsafe struct AutoFilterOptions
+    {
+        public sbyte* Column;
+        public sbyte* Expression;
+    }
+
     [StructLayout(LayoutKind.Sequential)]
     public unsafe struct HeaderFooterOptions
     {

Excelize/TypesCs.cs

@@ -291,6 +291,15 @@ public struct Protection
         public bool Hidden;
     }
 
+    /// <summary>
+    /// AutoFilterOptions directly maps the auto filter settings.
+    /// </summary>
+    public struct AutoFilterOptions
+    {
+        public string Column;
+        public string Expression;
+    }
+
     /// <summary>
     /// HeaderFooterOptions directly maps the settings of header and footer.
     /// </summary>