From 16dbb994c9273a4305d23329d107d8f1e4123a9f Mon Sep 17 00:00:00 2001 From: Lauro Moura Date: Mon, 30 Sep 2019 23:10:40 -0300 Subject: [PATCH] csharp: Document Eina.List Summary: Also added Since 1.23 info Depends on D10253o ref T8293 Test Plan: Check docs Reviewers: segfaultxavi, brunobelo, felipealmeida Reviewed By: felipealmeida Subscribers: cedric, #reviewers, #committers Tags: #efl Maniphest Tasks: T8293 Differential Revision: https://phab.enlightenment.org/D10254 --- src/bindings/mono/eina_mono/eina_list.cs | 67 ++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/src/bindings/mono/eina_mono/eina_list.cs b/src/bindings/mono/eina_mono/eina_list.cs index c65801c..7521ed6 100644 --- a/src/bindings/mono/eina_mono/eina_list.cs +++ b/src/bindings/mono/eina_mono/eina_list.cs @@ -3,6 +3,7 @@ using System; using System.Runtime.InteropServices; using System.Collections.Generic; +using System.ComponentModel; using static Eina.TraitFunctions; using static Eina.ListNativeFunctions; @@ -11,6 +12,7 @@ using Eina.Callbacks; namespace Eina { +[EditorBrowsable(EditorBrowsableState.Never)] public static class ListNativeFunctions { [DllImport(efl.Libs.Eina)] public static extern IntPtr @@ -104,16 +106,22 @@ public static class ListNativeFunctions eina_list_last_data_get_custom_export_mono(IntPtr list); } +/// Native wrapper around a linked list of items. (Since EFL 1.23) public class List : IEnumerable, IDisposable { + + [EditorBrowsable(EditorBrowsableState.Never)] public IntPtr Handle {get;set;} = IntPtr.Zero; + /// Whether this managed list owns the native one. public bool Own {get;set;} + /// Whether the native list wrapped owns the content it points to. public bool OwnContent {get;set;} /// Delegate for comparing two elements of this list. /// -1, 0 or 1 for respectively smaller, equal or larger. public delegate int Compare(T a, T b); + /// The number of elements on this list. public int Length { get { return Count(); } @@ -153,11 +161,14 @@ public class List : IEnumerable, IDisposable } + /// Creates a new empty list. public List() { InitNew(); } + /// Creates a new list wrapping the given handle. + [EditorBrowsable(EditorBrowsableState.Never)] public List(IntPtr handle, bool own) { Handle = handle; @@ -165,6 +176,8 @@ public class List : IEnumerable, IDisposable OwnContent = own; } + /// Creates a new list wrapping the given handle. + [EditorBrowsable(EditorBrowsableState.Never)] public List(IntPtr handle, bool own, bool ownContent) { Handle = handle; @@ -172,11 +185,15 @@ public class List : IEnumerable, IDisposable OwnContent = ownContent; } + /// Finalizes this list. ~List() { Dispose(false); } + /// Disposes of this list. + /// Whether this was called from the finalizer (false) or from the + /// method. protected virtual void Dispose(bool disposing) { IntPtr h = Handle; @@ -207,17 +224,21 @@ public class List : IEnumerable, IDisposable } } + /// Disposes of this list. public void Dispose() { Dispose(true); GC.SuppressFinalize(this); } + /// Disposes of this list. public void Free() { Dispose(); } + /// Relinquishes of the native list. + /// The previously wrapped native list handle. public IntPtr Release() { IntPtr h = Handle; @@ -225,57 +246,77 @@ public class List : IEnumerable, IDisposable return h; } + /// Sets whether this wrapper should own the native list or not. public void SetOwnership(bool ownAll) { Own = ownAll; OwnContent = ownAll; } + /// Sets whether this wrapper should own the native list and its content or not. public void SetOwnership(bool own, bool ownContent) { Own = own; OwnContent = ownContent; } + /// Returns the number of elements in this list. public int Count() { return (int)eina_list_count_custom_export_mono(Handle); } + /// Appends val to the list. + /// The item to be appended. public void Append(T val) { IntPtr ele = ManagedToNativeAlloc(val); Handle = eina_list_append(Handle, ele); } + /// Prepends val to the list. + /// The item to be prepended. public void Prepend(T val) { IntPtr ele = ManagedToNativeAlloc(val); Handle = eina_list_prepend(Handle, ele); } + /// Inserts val in the list in a sorted manner. It presumes the list is already sorted. + /// The item to be inserted. public void SortedInsert(T val) { IntPtr ele = ManagedToNativeAlloc(val); Handle = eina_list_sorted_insert(Handle, EinaCompareCb(), ele); } + /// Inserts val in the list in a sorted manner with the given compareCb for element comparison. + /// It presumes the list is already sorted. + /// The function to compare two elements of the list. + /// The item to be inserted. public void SortedInsert(Compare compareCb, T val) { IntPtr ele = ManagedToNativeAlloc(val); Handle = eina_list_sorted_insert(Handle, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb)), ele); } + /// Sorts limit elements in this list inplace. + /// The max number of elements to be sorted. public void Sort(int limit = 0) { Handle = eina_list_sort(Handle, (uint)limit, EinaCompareCb()); } + /// Sorts all elements in this list inplace. + /// The function to compare two elements of the list. public void Sort(Compare compareCb) { Handle = eina_list_sort(Handle, 0, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb))); } + /// Sorts limit elements in this list inplace. + /// The max number of elements to be sorted. + /// The function to compare two elements of the list. public void Sort(int limit, Compare compareCb) { Handle = eina_list_sort(Handle, (uint)limit, Marshal.GetFunctionPointerForDelegate(GetNativeCompareCb(compareCb))); @@ -288,6 +329,9 @@ public class List : IEnumerable, IDisposable }; } + /// Returns the nth element of this list. Due to marshalling details, the returned element + /// may be a different C# object from the one you used to append. + /// The 0-based index to be retrieved. public T Nth(int n) { // TODO: check bounds ??? @@ -295,6 +339,9 @@ public class List : IEnumerable, IDisposable return NativeToManaged(ele); } + /// Sets the data at the idx position. + /// The 0-based index to be set. + /// The value to be inserted. public void DataSet(int idx, T val) { IntPtr pos = eina_list_nth_list(Handle, (uint)idx); @@ -312,6 +359,8 @@ public class List : IEnumerable, IDisposable InternalDataSet(pos, ele); } + /// Accessor for the data at the idx position. + /// The 0-based index to be get/set. public T this[int idx] { get @@ -324,23 +373,30 @@ public class List : IEnumerable, IDisposable } } + /// Returns the data at the last list element. + /// The value contained in the last list position. public T LastDataGet() { IntPtr ele = eina_list_last_data_get_custom_export_mono(Handle); return NativeToManaged(ele); } + /// Reverses this list in place. + /// A reference to this object. public List Reverse() { Handle = eina_list_reverse(Handle); return this; } + /// Randomly shuffles this list in place. public void Shuffle() { Handle = eina_list_shuffle(Handle, IntPtr.Zero); } + /// Gets a C# array of the elements in this list. + /// A managed array of the elements. public T[] ToArray() { var managed = new T[Count()]; @@ -353,6 +409,8 @@ public class List : IEnumerable, IDisposable return managed; } + /// Appends the given array of elements to this list. + /// The values to be appended. public void AppendArray(T[] values) { foreach (T v in values) @@ -362,16 +420,22 @@ public class List : IEnumerable, IDisposable } + /// Gets an iterator that iterates this list in normal order. + /// The iterator. public Eina.Iterator GetIterator() { return new Eina.Iterator(eina_list_iterator_new(Handle), true); } + /// Gets an iterator that iterates this list in reverse order. + /// The iterator. public Eina.Iterator GetReversedIterator() { return new Eina.Iterator(eina_list_iterator_reversed_new(Handle), true); } + /// Gets an enumerator into this list. + /// The enumerator. public IEnumerator GetEnumerator() { for (IntPtr curr = Handle; curr != IntPtr.Zero; curr = InternalNext(curr)) @@ -380,12 +444,15 @@ public class List : IEnumerable, IDisposable } } + /// Gets an enumerator into this list. + /// The enumerator. System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() { return this.GetEnumerator(); } /// Gets an Accessor for this List. + /// The accessor. public Eina.Accessor GetAccessor() { return new Eina.Accessor(eina_list_accessor_new(Handle), Ownership.Managed); -- 2.7.4