This F4SE plugin introduces collection of multiple data structures to remove Papyrus limitations.
It is for modders, not for regular players. But it can be a dependency for other mods.



There are 3 main categories of data structures introduced by this plugin:

1. One dimentional arrays without 128 elements limitation. With sorting.
2. Sets
3. Dictionaries


Arrays:
5 types of 1-dimensinal arrays are available
int
float
string
Form
Struct


Sets:
4 types of sets are available:
int
float
string
Form


Dictionaries:

2 categories of dictionaries are available:
  key - value
  key - array of values. with sorting

2 categories of dictionaries could be added in future:
  key - set of values (postponed)
  key - dictionary of key/values (postponed)


Available types of keys:
  int
  string
  Form
Available types of values:
  int
  float
  string
  Form
  Struct


Iterators:
Iterators can be used to iterate collection elements. Currently iterators are available for elements of set and for keys of dictionary.


Actor's string attributes - moved to its own mod


F4SE API to access collections data.
An example of usage could be found in automated tests project on GitHub. Please note that not all functionality is covered by automated tests yet. Will be covered over time.
In order to get access to API one need to include/copy CollectionAccessor.h  header file to the plugin project
and files that this file depends on:
TypeDefs.h
transferable_vector.hpp
CollectionTypeId.h

Naming convention

Due to large number of collection structures naming is necessary.

Following convention is used for arrays and sets:
<element type><collection type>
For exampe:
StructArray - array of structs
IntSet - set of ints

For dictionaries convention is:
<key type>Dict<value type> where <value type> can be a collection (arrays only at this moment)
For example:
FormDictString - dictionary with Form keys and string values
StringDictStructArray - dictionary with string keys and arrays of structs as values

This F4SE plugin is shipped with set of Papyrus scripts to access plugin functionality.

Each entity (array/set/dictionary/string attribute) is identified by Keyword. Same keyword can be used for different types of entities, but it is not recommended to avoid dummy mistakes. For example, you can use same keyword to create array of ints and array of Forms. They will be isolated from each other.
For collection data structures (array/set/dictionary) you need to create one before using. Use Create function in appropriate Payrus script. Delete function can be called to destroy created data structure.

For non-array collections the only way to obtain all elements - iterators. Due to unordered nature of sets and dictionaries access by index doesn't seem reasonable. One have to create iterator descriptor using CreateIterator/CreateKeyIterator method and use returned descriptor in subsequent calls of Next/NextKey calls. When last element is iterated iterator automatically destroyed, one don't need to call DeleteIterator/DeleteKeyIterator method in this case. But iterator should be deleted explicitly if collection will not be fully iterated. It is possible that some iterating collection is modified by other script. In this case  all iterators for this modified collection becomes invalid. 

It is recommended to use Keywords defined in same ESP/ESL/ESM as the script that works with data structures associated with this Keyword. This will allow to correctly remove garbage from save files when your mod is uninstalled.

String values has length limitations. If string is used as key (as a value in set or as the key in dictionary) then limit is 4KBytes (bytes, not symbols). If string is used as value then it is practically unlimited, i.e. limit is 2GB.




At this moment code of tests is available in download section
Some code samples could be found in LiP Framework




Source codes of Papyrus scripts are available in download section
F4SE plugin source codes are available at GitHub
F4DS is based on modified F4SE. 

Documentation

Will be prepared over time.

Features to add

• sum for numeric arrays/sets
• Support ScriptObject as keys and values
• F4SE interface to allow other F4SE plugins to use DS data
  

Any thoughts and suggestions are welcome