Skip to content

Commit

Permalink
Merge pull request #18 from Mobject-Dev-Team/v0.7.0-pending
Browse files Browse the repository at this point in the history 
v0.7.0-alpha
  • Loading branch information
@benhar-dev
benhar-dev authored Apr 28, 2023
2 parents 44bc4ab + 36f87dd commit 808adcd
Show file tree
Hide file tree
Showing 65 changed files with 3,534 additions and 632 deletions.
24 changes: 18 additions & 6 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,30 +24,42 @@ The mobject-collections library provides a set of efficient and flexible data st

<img src="./images/linkedlist-example.svg">

The LinkedList class is a data structure that allows for efficient insertion, deletion, and traversal of items in a collection. Linked lists are particularly useful when you need to insert or delete items frequently. Additionally, linked lists can be easily be converted to static arrays.
The [LinkedList](linkedlist.md) class is a data structure that allows for efficient insertion, deletion, and traversal of items in a collection. Linked lists are particularly useful when you need to insert or delete items frequently. Additionally, linked lists can be easily be converted to static arrays.

Using the LinkedList class can help you to efficiently manage collections of objects in your industrial control system, particularly when frequent insertions and deletions are required.

The image above depicts a double linked list, which it the term given to a linked list who tracks both the head and tail. The benefit of a double linked list is that both forward and backwards traversing is possible.

### List

<img src="./images/list-example.svg">

The [List](list.md) class is a versatile and dynamic data structure that functions as a zero-indexed, resizable array. As a general-purpose collection, it is suitable for various applications and can easily adapt to changing data sizes. The List class is part of the mobject-collections library and, like other collection classes in the library, supports enumeration through the implementation of the GetEnumerator method.

Using the List class provides an effective way to manage collections of objects in diverse scenarios, offering the advantage of dynamic resizing and easy access to elements by index. This makes it particularly useful for situations where the size of the collection is not known in advance, or when the collection is expected to grow or shrink over time.

In comparison to the LinkedList class, the List class is better suited for situations that require fast, random access to elements within the collection. However, keep in mind that insertion or deletion of items, especially at the beginning or middle of the list, may be less efficient than with a LinkedList due to the need for element shifting.

Overall, the List class is a valuable and flexible data structure that can be employed to manage collections of objects effectively, providing dynamic resizing and quick element access for a wide range of applications.

### Queue

<img src="./images/queue-example.svg">

The Queue class is a data structure that follows the First-In-First-Out (FIFO) principle. Items are added to the back of the queue and removed from the front of the queue, in the order they were added. Queues are particularly useful for managing tasks that need to be processed in the order they were received, such as a set of instructions or a sequence of events.
The [Queue](queue.md) class is a data structure that follows the First-In-First-Out (FIFO) principle. Items are added to the back of the queue and removed from the front of the queue, in the order they were added. Queues are particularly useful for managing tasks that need to be processed in the order they were received, such as a set of instructions or a sequence of events.

Using the Queue class can help you to manage your system's tasks in an organized and efficient manner, ensuring that they are processed in the correct order and without any unnecessary delays.

### Stack

<img src="./images/stack-example.svg">

The Stack class is a data structure that follows the Last-In-First-Out (LIFO) principle. Items are added and to the front of the stack and removed from the front of the stack also, in the order they were added. Stacks are particularly useful for managing tasks that need to be processed in the most recent order they were received, such as a set of instructions or a sequence of events.
The [Stack](stack.md) class is a data structure that follows the Last-In-First-Out (LIFO) principle. Items are added and to the front of the stack and removed from the front of the stack also, in the order they were added. Stacks are particularly useful for managing tasks that need to be processed in the most recent order they were received, such as a set of instructions or a sequence of events.

Using the Stack class can help you to manage your system's tasks in an organized and efficient manner, ensuring that they are processed in the correct order and without any unnecessary delays.

### Dynamic Array and Dictionary
### Dictionary

The mobject-collections library will soon be expanding to include additional classes: Dynamic Array and Dictionary. Dynamic arrays are similar to regular arrays, but with the added benefit of being able to dynamically resize themselves as needed. Dictionaries are a data structure that allow for efficient key-value lookups.
The mobject-collections library will soon be expanding to include Dictionary. Dictionaries are a data structure that allow for efficient key-value lookups.

With the addition of these classes, the mobject-collections library will provide a comprehensive set of data structures that can be used to manage collections of objects in a wide range of scenarios.
With the addition of this class, the mobject-collections library will provide a comprehensive set of data structures that can be used to manage collections of objects in a wide range of scenarios.
9 changes: 5 additions & 4 deletions docs/_sidebar.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,19 @@
- Classes

- [LinkedList](linkedlist.md)
- [List](list.md)
- [Queue](queue.md)
- [Stack](stack.md)

- Interfaces

- [I_Collection](i-collection.md)
- [I_Queue](i-queue.md)
- [I_Stack](i-stack.md)
- [I_CollectionChangedEvent](i-collectionchangedevent.md)
- [I_CollectionDisposedEvent](i-collectiondisposedevent.md)
- [I_LinkedList](i-linkedlist.md)
- [I_LinkedListNode](i-linkedlistnode.md)
- [I_LinkedListChangedEvent](i-linkedlistchangedevent.md)
- [I_LinkedListDisposedEvent](i-linkedlistdisposedevent.md)
- [I_Queue](i-queue.md)
- [I_Stack](i-stack.md)

- Guides

Expand Down
12 changes: 12 additions & 0 deletions docs/changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,17 @@
# Changelog

# 0.7.0

- Added List and ListForwardEnumerator Classes.
- Changed I_Collection to extend from I_EventEmitter.

!> This update contains the following breaking changes.

- I_Collection.Count is now DINT.
- Individual OnChanged and OnDisposed event classes have been removed and replaced by generic collection events.
- Added mobject-enumerable 0.1.0.
- Changed all Destination to DestinationAddress on arguments of PVOID.

# 0.6.0

- Library built using 4024.44.
Expand Down
28 changes: 14 additions & 14 deletions docs/i-collection.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## Definition

| | |
| ----------- | ------------------------------------------------------------ |
| Namespace | mobject-collections |
| Library | mobject-collections |
| Inheritance | [I_Enumerable](http://enumerable.mobject.org/#/i-enumerable) |
| Implements | |
| | |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namespace | mobject-collections |
| Library | mobject-collections |
| Inheritance | [I_Enumerable](http://enumerable.mobject.org/#/i-enumerable), [I_Disposable](http://disposable.mobject.org/#/i-disposable), [I_EventEmitter](http://events.mobject.org/#/i-event-emitter) |
| Implements | |

## Remarks

Expand Down Expand Up @@ -47,9 +47,9 @@ Checks to see if an item is contained in the collection.

#### Parameters

| Parameters | Datatype | Description |
| ---------- | -------- | ------------------------------------ |
| Item | ANY | The item to store in the collection. |
| Parameters | Datatype | Description |
| ---------- | -------- | -------------------------------------- |
| Item | ANY | The item used to check the collection. |

#### Return

Expand Down Expand Up @@ -79,10 +79,10 @@ Copies the contents of the collection to an array defined by address and size. T

#### Parameters

| Parameters | Datatype | Description |
| --------------- | -------- | ---------------------------------------------------------- |
| Destination | PVOID | The address of the array which will act as the destination |
| DestinationSize | UDINT | The size of the array which will act as the destination |
| Parameters | Datatype | Description |
| ------------------ | -------- | ---------------------------------------------------------- |
| DestinationAddress | PVOID | The address of the array which will act as the destination |
| DestinationSize | UDINT | The size of the array which will act as the destination |

#### Return

Expand Down Expand Up @@ -114,4 +114,4 @@ Returns the total number of items held in the collection

| Datatype | Description |
| -------- | ----------------------------- |
| ULINT | Total items in the collection |
| DINT | Total items in the collection |
26 changes: 13 additions & 13 deletions docs/i-linkedlistchangedevent.md → docs/i-collectionchangedevent.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# I_LinkedListChangedEvent Interface
# I_CollectionChangedEvent Interface

## Definition

Expand All @@ -11,7 +11,7 @@

## Remarks

The I_LinkedListChangedEvent is an event emitted by the [LinkedList](linkedlist.md) class.
The I_CollectionChangedEvent is an event emitted by any collection implementing the [I_Collection](i-collection.md) interface.

## Example

Expand All @@ -31,17 +31,17 @@ VAR_INPUT
Event : I_Event;
END_VAR
VAR
linkedListChangedEvent : I_LinkedListChangedEvent;
originator : I_LinkedList;
collectionChangedEvent : I_CollectionChangedEvent;
originator : I_Collection;
END_VAR
```

```body
IF __QUERYINTERFACE(Event, linkedListChangedEvent) THEN
// the received event was I_LinkedListChangedEvent. You can now use the interface
// to extract which linked list raised it
IF __QUERYINTERFACE(Event, collectionChangedEvent) THEN
// the received event was I_CollectionChangedEvent. You can now use the interface
// to extract which collection raised it
// ...
originator := linkedListChangedEvent.TargetLinkedList;
originator := collectionChangedEvent.Target;
END_IF
// other event checks can follow here..
Expand All @@ -50,12 +50,12 @@ END_IF

## Properties

### TargetLinkedList
### Target

Returns the linked list who raised the event.
Returns the collection who raised the event.

#### Return

| Datatype | Description |
| ------------------------------- | ------------------------------------ |
| [I_LinkedList](i-linkedlist.md) | The linked list who raised the event |
| Datatype | Description |
| ------------------------------- | ----------------------------------- |
| [I_Collection](i-collection.md) | The collection who raised the event |
24 changes: 12 additions & 12 deletions docs/i-linkedlistdisposedevent.md → docs/i-collectiondisposedevent.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# I_LinkedListDisposedEvent Interface
# I_CollectionDisposedEvent Interface

## Definition

Expand All @@ -11,7 +11,7 @@

## Remarks

The I_LinkedListDisposedEvent is an event emitted by the [LinkedList](linkedlist.md) class.
The I_CollectionDisposedEvent is an event emitted by the [I_Collection](i-collection.md) interface.

## Example

Expand All @@ -31,17 +31,17 @@ VAR_INPUT
Event : I_Event;
END_VAR
VAR
linkedListDisposedEvent : I_LinkedListDisposedEvent;
collectionDisposedEvent : I_CollectionDisposedEvent;
originator : I_LinkedList;
END_VAR
```

```body
IF __QUERYINTERFACE(Event, linkedListDisposedEvent) THEN
// the received event was I_LinkedListDisposedEvent. You can now use the interface
// to extract which linked list raised it
IF __QUERYINTERFACE(Event, collectionDisposedEvent) THEN
// the received event was I_CollectionDisposedEvent. You can now use the interface
// to extract which collection raised it
// ...
originator := linkedListDisposedEvent.TargetLinkedList;
originator := collectionDisposedEvent.Target;
END_IF
// other event checks can follow here..
Expand All @@ -50,12 +50,12 @@ END_IF

## Properties

### TargetLinkedList
### Target

Returns the linked list who raised the event.
Returns the collection who raised the event.

#### Return

| Datatype | Description |
| ------------------------------- | ------------------------------------ |
| [I_LinkedList](i-linkedlist.md) | The linked list who raised the event |
| Datatype | Description |
| ------------------------------- | ----------------------------------- |
| [I_Collection](i-collection.md) | The collection who raised the event |
12 changes: 6 additions & 6 deletions docs/i-linkedlist.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## Definition

| | |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Namespace | mobject-collections |
| Library | mobject-collections |
| Inheritance | [I_Collection](i-collection.md) , [I_EventEmitter](http://events.mobject.org/#/i-event-emitter) |
| Implements | |
| | |
| ----------- | ------------------------------- |
| Namespace | mobject-collections |
| Library | mobject-collections |
| Inheritance | [I_Collection](i-collection.md) |
| Implements | |

## Remarks

Expand Down
1 change: 1 addition & 0 deletions docs/images/list-example.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 15 additions & 15 deletions docs/linkedlist.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -217,19 +217,19 @@ linkedList.Clear();

### Contains(Item)

Checks to see if an item is contained in the collection.
Checks to see if an item is contained in the list.

#### Parameters

| Parameters | Datatype | Description |
| ---------- | -------- | ------------------------------------ |
| Item | ANY | The item to store in the collection. |
| Parameters | Datatype | Description |
| ---------- | -------- | ------------------------------ |
| Item | ANY | The item to to check the list. |

#### Return

| Datatype | Description |
| -------- | ------------------------------------------------------- |
| BOOL | Returns true if the item is contained in the collection |
| Datatype | Description |
| -------- | ------------------------------------------------- |
| BOOL | Returns true if the item is contained in the list |

#### Usage

Expand Down Expand Up @@ -283,10 +283,10 @@ Copies the contents of the linkedlist to an array defined by address and size. T

#### Parameters

| Parameters | Datatype | Description |
| --------------- | -------- | ---------------------------------------------------------- |
| Destination | PVOID | The address of the array which will act as the destination |
| DestinationSize | UDINT | The size of the array which will act as the destination |
| Parameters | Datatype | Description |
| ------------------ | -------- | ---------------------------------------------------------- |
| DestinationAddress | PVOID | The address of the array which will act as the destination |
| DestinationSize | UDINT | The size of the array which will act as the destination |

#### Return

Expand Down Expand Up @@ -620,7 +620,7 @@ Returns the total number of items held in the linked list

| Datatype | Description |
| -------- | ------------------------------ |
| ULINT | Total items in the linked list |
| DINT | Total items in the linked list |

#### Usage

Expand All @@ -629,7 +629,7 @@ linkedList : LinkedList;
value1 : INT := 123;
value2 : INT := 456;
value3 : INT := 789;
count : ULINT;
count : DINT;
```

```body
Expand Down Expand Up @@ -703,7 +703,7 @@ Triggered when there is any change to the content of the linked list.

| Datatype | Description |
| ------------------------------------------------------- | ------------------------------------------------------------- |
| [I_LinkedListChangedEvent](i-linkedlistchangedevent.md) | The event handler will be passed the I_LinkedListChangedEvent |
| [I_CollectionChangedEvent](i-collectionchangedevent.md) | The event handler will be passed the I_CollectionChangedEvent |

### OnDisposed

Expand All @@ -713,4 +713,4 @@ Triggered when the linked list is disposed.

| Datatype | Description |
| --------------------------------------------------------- | -------------------------------------------------------------- |
| [I_LinkedListDisposedEvent](i-linkedlistdisposedevent.md) | The event handler will be passed the I_LinkedListDisposedEvent |
| [I_CollectionDisposedEvent](i-collectiondisposedevent.md) | The event handler will be passed the I_CollectionDisposedEvent |
Loading

0 comments on commit 808adcd

Please sign in to comment.