interfaces

Definition

Contains interfaces definitions.

Classes
class	xtd::collections::generic::icollection< type_t >
	Defines methods to manipulate generic collections. More...
class	xtd::collections::generic::icomparer< type_t >
	Exposes a method that compares two objects. More...
class	xtd::collections::generic::ienumerable< type_t >
	Exposes the enumerator, which supports a simple iteration over a collection of a specified type. More...
class	xtd::collections::generic::ienumerator< type_t >
	Supports a simple iteration over a generic collection. More...
class	xtd::collections::generic::iequality_comparer< type_t >
	Defines methods to support the comparison of objects for equality. More...
class	xtd::collections::generic::ilist< type_t >
	Represents a collection of objects that can be individually accessed by index. More...
class	xtd::iasync_result
	Represents the status of an asynchronous operation. More...
class	xtd::iclonable
	Supports cloning, which creates a new instance of a class with the same value as an existing instance. More...
class	xtd::icomparable< type_t >
	Defines a generalized comparison method that a value type or class implements to create a type-specific comparison method. More...
class	xtd::iequatable< type_t >
	Defines a generalized method that a value type or class implements to create a type-specific method for determining equality of instances. More...
class	xtd::iformatable
	Provides functionality to format the value of an object into a string representation. More...
class	xtd::iobservable< type_t >
	Provides a mechanism for receiving push-based notifications. More...
class	xtd::iobserver< type_t >
	Provides a mechanism for receiving push-based notifications. More...
class	xtd::iprogress< type_t >
	Defines a provider for progress updates. More...
class	xtd::istringable
	Provides a way to represent the current object as a string. More...
class	xtd::isynchronize_invoke
	Provides a way to synchronously or asynchronously execute a delegate. More...
class	xtd::forms::ibutton_control
	Allows a control to act like a button on a form. More...
class	xtd::forms::icontrol_trace
	Allow a control to be called by control_trace_listener for writing debug or trace message. More...
class	xtd::forms::imessage_filter
	Defines a message filter interface. More...
class	xtd::forms::iwin32_window
	Provides an interface to expose Win32 HWND handles. More...
class	xtd::forms::style_sheets::ibox_model
	The box model allows you to specify the margin, borders, padding, background color, width and height of a box. More...
class	xtd::forms::style_sheets::iimage_model
	The image model allows you to specify the alignment of an image. More...
class	xtd::forms::style_sheets::itext_model
	The text model allows you to specify the alignment, color, decoration, transformation, and font of a text. More...

Typedefs
using	xtd::collections::icollection = generic::icollection< xtd::any_object >
	Defines size, enumerators, and synchronization methods for all nongeneric collections.
using	xtd::collections::ienumerable = generic::ienumerable< xtd::any_object >
	Exposes an enumerator, which supports a simple iteration over a non-generic collection.
using	xtd::collections::ienumerator = generic::ienumerator< xtd::any_object >
	Supports a simple iteration over a non-generic collection.
using	xtd::collections::iequality_comparer = generic::iequality_comparer< xtd::any_object >
	Defines methods to support the comparison of objects for equality.
using	xtd::collections::ilist = generic::ilist< xtd::any_object >
	Represents a non-generic collection of objects that can be individually accessed by index.

Typedef Documentation

icollection

using xtd::collections::icollection = typedef generic::icollection<xtd::any_object>

#include <xtd.core/include/xtd/collections/icollection.h>

Defines size, enumerators, and synchronization methods for all nongeneric collections.

using icollection = xtd::collections::generic::icollection<xtd::any_object>

Header

#include <xtd/collections/icollection>

Namespace

xtd::collections

Library

xtd.core

Remarks

The xtd::collections::icollection interface is the base interface for classes in the xtd::collections namespace. Its generic equivalent is the xtd::collections::genric::icollection <type_t> interface.

The xtd::collections::icollection interface extends xtd::collections::ienumerable; xtd::collections::idictionary and xtd::collections::ilist are more specialized interfaces that extend xtd::collections::icollection. An xtd::collections::idictionary implementation is a collection of key/value pairs, like the xtd::collections::hashtable class. An xtd::collections::ilist implementation is a collection of values and its members can be accessed by index, like the xtd::collections::array_list class.

Some collections that limit access to their elements, such as the xtd::collections::queue class and the xtd::collections::stack class, directly implement the xtd::collections::icollection interface.

If neither the xtd::collections::idictionary interface nor the xtd::collections::ilist interface meet the requirements of the required collection, derive the new collection class from the xtd::collections::icollection interface instead for more flexibility.

For the generic version of this interface, see xtd::collections::generic::icollection <type_t>.

ienumerable

using xtd::collections::ienumerable = typedef generic::ienumerable<xtd::any_object>

#include <xtd.core/include/xtd/collections/ienumerable.h>

Exposes an enumerator, which supports a simple iteration over a non-generic collection.

using ienumerable = xtd::collections::generic::ienumerable<xtd::any_object>

Header

#include <xtd/collections/ienumerable>

Namespace

xtd::collections

Library

xtd.core

Examples

The following code example demonstrates the best practice for iterating a custom collection by implementing the xtd::collection::ienumerable and xtd::collection::ienumerator interfaces. In this example, members of these interfaces are not explicitly called, but they are implemented to support the use of for each to iterate through the collection. This example is a complete Console app.

#include <xtd/collections/array_list>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::collections;
 
class program {
public:
  // Simple business object.
  struct person : public object, public iequatable<person>, public icomparable<person> {
  public:
    person(const string& first_name, const string last_name) : first_name {first_name}, last_name {last_name} {}
    
    string first_name;
    string last_name;
 
    int32 compare_to(const person& o) const noexcept override {
      if (first_name == o.first_name && last_name == o.last_name) return 0;
      if (first_name > o.first_name || (first_name == o.first_name && last_name > o.last_name)) return 1;
      return -1;
    }
    bool equals(const object& o) const noexcept override {return is<person>(o) && equals(as<person>(o));}
    bool equals(const person& o) const noexcept override {return compare_to(o) == 0;}
    string to_string() const noexcept override {return string::format("{} {}", first_name, last_name);}
  };
  
  // Collection of person objects. This class implements xtd::collections::ienumerable so that it can be used with for each syntax.
  class people : public ienumerable {
  private:
    array_list people_;
    
  public:
    people(const array<person>& p_array) {
      people_ = array_list(p_array.size());
      
      for (auto i = 0_z; i < p_array.size(); ++i)
        people_[i] = p_array[i];
    }
    
    // Implementation for the xtd::collections::ienumerable::get_enumerator method.
    enumerator get_enumerator() const override {
      return enumerator {new_ptr<people_enumerator>(people_)};
    }
  };
  
  // When you implement xtd::collections::ienumerable, you must also implement xtd::collections::ienumerator.
  class people_enumerator : public ienumerator {
  private:
    const array_list& people_;
 
    // Enumerators are positioned before the first element until the first xtd::collections::ienumerator::move_next() call.
    size position = array_list::npos;
    
  public:
    people_enumerator(const array_list& list) : people_(list) {}
    
    bool move_next() override {return ++position < people_.count();}
    
    void reset() override {position = array_list::npos;}
    
    const any_object& current() const override {
      if (position >= people_.size()) throw invalid_operation_exception {};
      return people_[position];
    }
  };
 
  static auto main() -> void {
    auto people_array = xtd::array<person> {
      person {"John", "Smith"},
      person {"Jim", "Johnson"},
      person {"Sue", "Rabon"},
    };
    
    auto people_list = people {people_array};
    for (auto person : people_list)
      console::write_line(person);
  }
};
 
startup_(program::main);
 
 
// This code produces the following output :
//
// John Smith
// Jim Johnson
// Sue Rabon

Remarks

xtd::collections::ienumerable is the base interface for all non-generic collections that can be enumerated. For the generic version of this interface see xtd::collections::generic::ieumerable <type_t>. xtd::collections::ienumerable contains a single method, xtd::collections::ienumerable::get_enumerator, which returns an xtd::collections::ienumerator. xtd::collections::ienumerator provides the ability to iterate through the collection by exposing a xtd::collections::ienumerator::current property and xtd::collections::ienumerator::move_next and xtd::collections::ienumeraror::reset methods.

It is a best practice to implement xtd::collections::ienumerable and xtd::collections::ienumerator on your collection classes to enable the for each syntax, however implementing xtd::collections::ienumerable is not required. If your collection does not implement xtd::collections::ienumerable, you must still follow the iterator pattern to support this syntax by providing a xtd::collections::ienumerable::get_enumerator method that returns an interface, class or struct. You must provide a class that contains a xtd::collections::ienumerator::current property, and xtd::collections::ienumerator::move_next and Reset methods as described by xtd::collections::ienumerator, but the class does not have to implement xtd::collections::ienumerator.

ienumerator

using xtd::collections::ienumerator = typedef generic::ienumerator<xtd::any_object>

#include <xtd.core/include/xtd/collections/ienumerator.h>

Supports a simple iteration over a non-generic collection.

using ienumerator = xtd::collections::generic::ienumerator<xtd::any_object>

Header

#include <xtd/collections/ienumerator>

Namespace

xtd::collections

Library

xtd.core

The following code example demonstrates the best practice for iterating a custom collection by implementing the xtd::collection::ienumerable and xtd::collection::ienumerator interfaces. In this example, members of these interfaces are not explicitly called, but they are implemented to support the use of for each to iterate through the collection. This example is a complete Console app.

#include <xtd/collections/array_list>
#include <xtd/console>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::collections;
 
class program {
public:
  // Simple business object.
  struct person : public object, public iequatable<person>, public icomparable<person> {
  public:
    person(const string& first_name, const string last_name) : first_name {first_name}, last_name {last_name} {}
    
    string first_name;
    string last_name;
 
    int32 compare_to(const person& o) const noexcept override {
      if (first_name == o.first_name && last_name == o.last_name) return 0;
      if (first_name > o.first_name || (first_name == o.first_name && last_name > o.last_name)) return 1;
      return -1;
    }
    bool equals(const object& o) const noexcept override {return is<person>(o) && equals(as<person>(o));}
    bool equals(const person& o) const noexcept override {return compare_to(o) == 0;}
    string to_string() const noexcept override {return string::format("{} {}", first_name, last_name);}
  };
  
  // Collection of person objects. This class implements xtd::collections::ienumerable so that it can be used with for each syntax.
  class people : public ienumerable {
  private:
    array_list people_;
    
  public:
    people(const array<person>& p_array) {
      people_ = array_list(p_array.size());
      
      for (auto i = 0_z; i < p_array.size(); ++i)
        people_[i] = p_array[i];
    }
    
    // Implementation for the xtd::collections::ienumerable::get_enumerator method.
    enumerator get_enumerator() const override {
      return enumerator {new_ptr<people_enumerator>(people_)};
    }
  };
  
  // When you implement xtd::collections::ienumerable, you must also implement xtd::collections::ienumerator.
  class people_enumerator : public ienumerator {
  private:
    const array_list& people_;
 
    // Enumerators are positioned before the first element until the first xtd::collections::ienumerator::move_next() call.
    size position = array_list::npos;
    
  public:
    people_enumerator(const array_list& list) : people_(list) {}
    
    bool move_next() override {return ++position < people_.count();}
    
    void reset() override {position = array_list::npos;}
    
    const any_object& current() const override {
      if (position >= people_.size()) throw invalid_operation_exception {};
      return people_[position];
    }
  };
 
  static auto main() -> void {
    auto people_array = xtd::array<person> {
      person {"John", "Smith"},
      person {"Jim", "Johnson"},
      person {"Sue", "Rabon"},
    };
    
    auto people_list = people {people_array};
    for (auto person : people_list)
      console::write_line(person);
  }
};
 
startup_(program::main);
 
 
// This code produces the following output :
//
// John Smith
// Jim Johnson
// Sue Rabon

Remarks

xtd::collections::ienumerator is the base interface for all non-generic enumerators. Its generic equivalent is the xtd::collections::generic::iznumerator <type_t> interface.

The for each statement of the C++ language hides the complexity of the enumerators. Therefore, using for each is recommended instead of directly manipulating the enumerator.

Enumerators can be used to read the data in the collection, but they cannot be used to modify the underlying collection.

The xtd::collections::ienumerator::reset method is provided for COM interoperability and does not need to be fully implemented; instead, the implementer can throw a xtd::not_supported_exception.

Initially, the enumerator is positioned before the first element in the collection. You must call the xtd::collections::ienumerator::MMoveN_next method to advance the enumerator to the first element of the collection before reading the value of xtd::collections::ienumerator::current; otherwise, xtd::collections::ienumerator::current is undefined.

xtd::collections::ienumerator::current returns the same object until either xtd::collections::ienumerator::move_next or xtd::collections::ienumerator::reset is called. xtd::collections::ienumerator::move_next sets xtd::collections::ienumerator::current to the next element.

If xtd::collections::ienumerator::move_next passes the end of the collection, the enumerator is positioned after the last element in the collection and xtd::collections::ienumerator::move_next returns false. When the enumerator is at this position, subsequent calls to xtd::collections::ienumerator::move_next also return false. If the last call to xtd::collections::ienumerator::move_next returned false, xtd::collections::ienumerator::current is undefined.

To set xtd::collections::ienumerator::current to the first element of the collection again, you can call Reset, if it's implemented, followed by xtd::collections::ienumerator::move_next. If xtd::collections::ienumerator::reset is not implemented, you must create a new enumerator instance to return to the first element of the collection.

If changes are made to the collection, such as adding, modifying, or deleting elements, the behavior of the enumerator is undefined.

The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads can still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

iequality_comparer

using xtd::collections::iequality_comparer = typedef generic::iequality_comparer<xtd::any_object>

#include <xtd.core/include/xtd/collections/iequality_comparer.h>

Defines methods to support the comparison of objects for equality.

using iequality_comparer = xtd::collections::generic::iequality_comparer<xtd::any_object>

Header

#include <xtd/collections/iequality_comparer>

Namespace

xtd::collections

Library

xtd.core

Remarks

This interface allows the implementation of customized equality comparison for collections. That is, you can create your own definition of equality, and specify that this definition be used with a collection type that accepts the xtd::collections::iequality_comparer interface. In the xtd framework, constructors of the xtd::collections::hashtable, xtd::collections::specialized::name_value_collection, and xtd::collections::specialized::ordered_dictionary collection types accept this interface.

For the generic version of this interface, see xtd::collections::generic::iequality_comparer <type_t>.

The xtd::collections::iequality_comparer interface supports only equality comparisons. Customization of comparisons for sorting and ordering is provided by the xtd::collections::icomparer interface.

ilist

using xtd::collections::ilist = typedef generic::ilist<xtd::any_object>

#include <xtd.core/include/xtd/collections/ilist.h>

Represents a non-generic collection of objects that can be individually accessed by index.

using ilist = xtd::collections::generic::ilist<xtd::any_object>

Header

#include <xtd/collections/ilist>

Namespace

xtd::collections

Library

xtd.core

par Examples The following example demonstrates the implementation of the xtd::collections::ilist interface to create a simple, fixed-size list.

#include <xtd/collections/array_list>
#include <xtd/array>
#include <xtd/console>
#include <xtd/not_implemented_exception>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::collections;
 
class program {
public:
  static auto main() -> void {
    auto test = simple_list();
    
    // Populate the List.
    console::write_line("Populate the List");
    test.add("one");
    test.add("two");
    test.add("three");
    test.add("four");
    test.add("five");
    test.add("six");
    test.add("seven");
    test.add("eight");
    test.print_contents();
    console::write_line();
    
    // Remove elements from the list.
    console::write_line("Remove elements from the list");
    test.remove("six");
    test.remove("eight");
    test.print_contents();
    console::write_line();
    
    // Add an element to the end of the list.
    console::write_line("Add an element to the end of the list");
    test.add("nine");
    test.print_contents();
    console::write_line();
    
    // Insert an element into the middle of the list.
    console::write_line("Insert an element into the middle of the list");
    test.insert(4, "number");
    test.print_contents();
    console::write_line();
    
    // Check for specific elements in the list.
    console::write_line("Check for specific elements in the list");
    console::write_line("List contains \"three\": {}", test.contains("three"));
    console::write_line("List contains \"ten\": {}", test.contains("ten"));
  }
  
  class simple_list : public object, public ilist {
  private:
    array<any_object> contents_ = array<any_object>(8);
    size count_;
    
  public:
    inline static constexpr size npos = ilist::npos;
 
    simple_list() {count_ = 0;}
    
    void print_contents() const noexcept {
      console::write_line("List has a capacity of {} and currently has {} elements.", contents_.size(), count_);
      console::write("List contents:");
      for (auto i = 0_z; i < count(); ++i)
        console::write(" {}", contents_[i]);
      console::write_line();
    }
 
    // xtd::collections::iist Members
    
    bool is_fixed_size() const noexcept override {return true;}
    
    bool is_read_only() const noexcept override {return false;}
 
    void add(const any_object& value) override {
      if (count_ < contents_.size()) {
        contents_[count_] = value;
        count_++;
      }
    }
    
    void clear() override {
      count_ = 0;
    }
    
    bool contains(const any_object& value) const noexcept override {
      for (auto i = 0_z; i < count(); ++i)
        if (contents_[i] == value) return true;
      return false;
    }
    
    size index_of(const any_object& value) const noexcept override {
      for (auto i = 0_z; i < count(); ++i)
        if (contents_[i] == value) return i;
      return npos;
    }
    
    void insert(size index, const any_object& value) override {
      if (count_ + 1 <= contents_.size() && index < count()) {
        ++count_;
        
        for (size i = count() - 1; i > index; --i)
          contents_[i] = contents_[i - 1];
        
        contents_[index] = value;
      }
    }
    
    bool remove(const any_object& value) override {
      auto index = index_of(value);
      remove_at(index);
      return index != npos;
    }
    
    void remove_at(size index) override {
      if (index < count()) {
        for (size i = index; i < count() - 1; ++i)
          contents_[i] = contents_[i + 1];
        --count_;
      }
    }
    
    const any_object& operator[] (size index) const override {
      return contents_[index];
    }
    any_object& operator[] (size index) override {
      return contents_[index];
    }
    
    // xtd::collections::icollection members.
    
    size count() const noexcept override {return count_;}
    
    bool is_synchronized() const noexcept override {return false;}
    
    // Return the current instance since the underlying store is not
    // publicly available.
    const object& sync_root() const noexcept override {return *this;}
    
    void copy_to(xtd::array<any_object>& array, size index) const noexcept override {
      for (auto i = 0_z; i < count(); ++i)
        array[index + i] = contents_[i];
    }
    
    // xtd::collections::ienumerable Members
    
    enumerator get_enumerator() const override {
      // Refer to the xtd::collection::ienumerator documentation for an example of
      // implementing an enumerator.
      throw not_implemented_exception {"The method or operation is not implemented."};
    }
  };
};
 
startup_(program::main);
 
 
// This code produces the following output :
//
// Populate the List
// List has a capacity of 8 and currently has 8 elements.
// List contents: one two three four five six seven eight
//
// Remove elements from the list
// List has a capacity of 8 and currently has 6 elements.
// List contents: one two three four five seven
//
// Add an element to the end of the list
// List has a capacity of 8 and currently has 7 elements.
// List contents: one two three four five seven nine
//
// Insert an element into the middle of the list
// List has a capacity of 8 and currently has 8 elements.
// List contents: one two three four number five seven nine
//
// Check for specific elements in the list
// List contains "three": true
// List contains "ten": false

Remarks

xtd::collections::ilist is a descendant of the xtd::collections::icollection interface and is the base interface of all non-generic lists. xtd::collections::ilist implementations fall into three categories: read-only, fixed-size, and variable-size. A read-only xtd::collections::ilist cannot be modified. A fixed-size xtd::collections::ilist does not allow the addition or removal of elements, but it allows the modification of existing elements. A variable-size xtd::collections::ilist allows the addition, removal, and modification of elements.

For the generic version of this interface, see xtd::collections::generic::ilist <type_t>.