Add SettingsList for storing lists of settings (#738)

This is a new type that is used to store lists of settings in addition
to `SettingsMap`. The difference is that for lists you don't use keys to
look up the values, but instead you use indices, or more likely,
iteration.

Author: CryZe

crates/livesplit-auto-splitting/README.md

@@ -42,6 +42,9 @@ pub struct ProcessId(u64);
 #[repr(transparent)]
 pub struct SettingsMap(NonZeroU64);
 
+#[repr(transparent)]
+pub struct SettingsList(NonZeroU64);
+
 #[repr(transparent)]
 pub struct SettingValue(NonZeroU64);
 
@@ -295,13 +298,64 @@ extern "C" {
         key_ptr: *const u8,
         key_len: usize,
     ) -> Option<SettingValue>;
+    /// Gets the length of a settings map.
+    pub fn settings_map_len(map: SettingsMap) -> u64;
+    /// Gets the key of a setting value from the settings map based on the index
+    /// by storing it into the buffer provided. Returns `false` if the buffer is
+    /// too small. After this call, no matter whether it was successful or not,
+    /// the `buf_len_ptr` will be set to the required buffer size. If `false` is
+    /// returned and the `buf_len_ptr` got set to 0, the index is out of bounds.
+    /// The key is guaranteed to be valid UTF-8 and is not nul-terminated.
+    pub fn settings_map_get_key_by_index(
+        map: SettingsMap,
+        idx: u64,
+        buf_ptr: *mut u8,
+        buf_len_ptr: *mut usize,
+    ) -> bool;
+    /// Gets a copy of the setting value from the settings map based on the
+    /// index. Returns `None` if the index is out of bounds. Any changes to it
+    /// are only perceived if it's stored back. You own the setting value and
+    /// are responsible for freeing it.
+    pub fn settings_map_get_value_by_index(map: SettingsMap, idx: u64) -> Option<SettingValue>;
+
+    /// Creates a new settings list. You own the settings list and are
+    /// responsible for freeing it.
+    pub fn settings_list_new() -> SettingsList;
+    /// Frees a settings list.
+    pub fn settings_list_free(list: SettingsList);
+    /// Copies a settings list. No changes inside the copy affect the original
+    /// settings list. You own the new settings list and are responsible for
+    /// freeing it.
+    pub fn settings_list_copy(list: SettingsList) -> SettingsList;
+    /// Gets the length of a settings list.
+    pub fn settings_list_len(list: SettingsList) -> u64;
+    /// Gets a copy of the setting value from the settings list based on the
+    /// index. Returns `None` if the index is out of bounds. Any changes to it
+    /// are only perceived if it's stored back. You own the setting value and
+    /// are responsible for freeing it.
+    pub fn settings_list_get(list: SettingsList, idx: u64) -> Option<SettingValue>;
+    /// Pushes a copy of the setting value to the end of the settings list. You
+    /// still retain ownership of the setting value, which means you still need
+    /// to free it.
+    pub fn settings_list_push(list: SettingsList, value: SettingValue);
+    /// Inserts a copy of the setting value into the settings list at the index
+    /// given. If the index is out of bounds, the setting value is pushed to the
+    /// end of the settings list. You still retain ownership of the setting
+    /// value, which means you still need to free it.
+    pub fn settings_list_insert(list: SettingsList, idx: u64, value: SettingValue);
 
     /// Creates a new setting value from a settings map. The value is a copy of
     /// the settings map. Any changes to the original settings map afterwards
     /// are not going to be perceived by the setting value. You own the setting
     /// value and are responsible for freeing it. You also retain ownership of
     /// the settings map, which means you still need to free it.
     pub fn setting_value_new_map(value: SettingsMap) -> SettingValue;
+    /// Creates a new setting value from a settings list. The value is a copy of
+    /// the settings list. Any changes to the original settings list afterwards
+    /// are not going to be perceived by the setting value. You own the setting
+    /// value and are responsible for freeing it. You also retain ownership of
+    /// the settings list, which means you still need to free it.
+    pub fn setting_value_new_list(value: SettingsList) -> SettingValue;
     /// Creates a new boolean setting value. You own the setting value and are
     /// responsible for freeing it.
     pub fn setting_value_new_bool(value: bool) -> SettingValue;
@@ -317,13 +371,24 @@ extern "C" {
     pub fn setting_value_new_string(value_ptr: *const u8, value_len: usize) -> SettingValue;
     /// Frees a setting value.
     pub fn setting_value_free(value: SettingValue);
+    /// Copies a setting value. No changes inside the copy affect the original
+    /// setting value. You own the new setting value and are responsible for
+    /// freeing it.
+    pub fn setting_value_copy(value: SettingValue) -> SettingValue;
     /// Gets the value of a setting value as a settings map by storing it into
     /// the pointer provided. Returns `false` if the setting value is not a
     /// settings map. No value is stored into the pointer in that case. No
     /// matter what happens, you still retain ownership of the setting value,
     /// which means you still need to free it. You own the settings map and are
     /// responsible for freeing it.
     pub fn setting_value_get_map(value: SettingValue, value_ptr: *mut SettingsMap) -> bool;
+    /// Gets the value of a setting value as a settings list by storing it into
+    /// the pointer provided. Returns `false` if the setting value is not a
+    /// settings list. No value is stored into the pointer in that case. No
+    /// matter what happens, you still retain ownership of the setting value,
+    /// which means you still need to free it. You own the settings list and are
+    /// responsible for freeing it.
+    pub fn setting_value_get_list(value: SettingValue, value_ptr: *mut SettingsList) -> bool;
     /// Gets the value of a boolean setting value by storing it into the pointer
     /// provided. Returns `false` if the setting value is not a boolean. No
     /// value is stored into the pointer in that case. No matter what happens,

crates/livesplit-auto-splitting/src/lib.rs

@@ -43,6 +43,9 @@
 //! pub struct SettingsMap(NonZeroU64);
 //!
 //! #[repr(transparent)]
+//! pub struct SettingsList(NonZeroU64);
+//!
+//! #[repr(transparent)]
 //! pub struct SettingValue(NonZeroU64);
 //!
 //! #[repr(transparent)]
@@ -295,13 +298,64 @@
 //!         key_ptr: *const u8,
 //!         key_len: usize,
 //!     ) -> Option<SettingValue>;
+//!     /// Gets the length of a settings map.
+//!     pub fn settings_map_len(map: SettingsMap) -> u64;
+//!     /// Gets the key of a setting value from the settings map based on the index
+//!     /// by storing it into the buffer provided. Returns `false` if the buffer is
+//!     /// too small. After this call, no matter whether it was successful or not,
+//!     /// the `buf_len_ptr` will be set to the required buffer size. If `false` is
+//!     /// returned and the `buf_len_ptr` got set to 0, the index is out of bounds.
+//!     /// The key is guaranteed to be valid UTF-8 and is not nul-terminated.
+//!     pub fn settings_map_get_key_by_index(
+//!         map: SettingsMap,
+//!         idx: u64,
+//!         buf_ptr: *mut u8,
+//!         buf_len_ptr: *mut usize,
+//!     ) -> bool;
+//!     /// Gets a copy of the setting value from the settings map based on the
+//!     /// index. Returns `None` if the index is out of bounds. Any changes to it
+//!     /// are only perceived if it's stored back. You own the setting value and
+//!     /// are responsible for freeing it.
+//!     pub fn settings_map_get_value_by_index(map: SettingsMap, idx: u64) -> Option<SettingValue>;
+//!
+//!     /// Creates a new settings list. You own the settings list and are
+//!     /// responsible for freeing it.
+//!     pub fn settings_list_new() -> SettingsList;
+//!     /// Frees a settings list.
+//!     pub fn settings_list_free(list: SettingsList);
+//!     /// Copies a settings list. No changes inside the copy affect the original
+//!     /// settings list. You own the new settings list and are responsible for
+//!     /// freeing it.
+//!     pub fn settings_list_copy(list: SettingsList) -> SettingsList;
+//!     /// Gets the length of a settings list.
+//!     pub fn settings_list_len(list: SettingsList) -> u64;
+//!     /// Gets a copy of the setting value from the settings list based on the
+//!     /// index. Returns `None` if the index is out of bounds. Any changes to it
+//!     /// are only perceived if it's stored back. You own the setting value and
+//!     /// are responsible for freeing it.
+//!     pub fn settings_list_get(list: SettingsList, idx: u64) -> Option<SettingValue>;
+//!     /// Pushes a copy of the setting value to the end of the settings list. You
+//!     /// still retain ownership of the setting value, which means you still need
+//!     /// to free it.
+//!     pub fn settings_list_push(list: SettingsList, value: SettingValue);
+//!     /// Inserts a copy of the setting value into the settings list at the index
+//!     /// given. If the index is out of bounds, the setting value is pushed to the
+//!     /// end of the settings list. You still retain ownership of the setting
+//!     /// value, which means you still need to free it.
+//!     pub fn settings_list_insert(list: SettingsList, idx: u64, value: SettingValue);
 //!
 //!     /// Creates a new setting value from a settings map. The value is a copy of
 //!     /// the settings map. Any changes to the original settings map afterwards
 //!     /// are not going to be perceived by the setting value. You own the setting
 //!     /// value and are responsible for freeing it. You also retain ownership of
 //!     /// the settings map, which means you still need to free it.
 //!     pub fn setting_value_new_map(value: SettingsMap) -> SettingValue;
+//!     /// Creates a new setting value from a settings list. The value is a copy of
+//!     /// the settings list. Any changes to the original settings list afterwards
+//!     /// are not going to be perceived by the setting value. You own the setting
+//!     /// value and are responsible for freeing it. You also retain ownership of
+//!     /// the settings list, which means you still need to free it.
+//!     pub fn setting_value_new_list(value: SettingsList) -> SettingValue;
 //!     /// Creates a new boolean setting value. You own the setting value and are
 //!     /// responsible for freeing it.
 //!     pub fn setting_value_new_bool(value: bool) -> SettingValue;
@@ -317,13 +371,24 @@
 //!     pub fn setting_value_new_string(value_ptr: *const u8, value_len: usize) -> SettingValue;
 //!     /// Frees a setting value.
 //!     pub fn setting_value_free(value: SettingValue);
+//!     /// Copies a setting value. No changes inside the copy affect the original
+//!     /// setting value. You own the new setting value and are responsible for
+//!     /// freeing it.
+//!     pub fn setting_value_copy(value: SettingValue) -> SettingValue;
 //!     /// Gets the value of a setting value as a settings map by storing it into
 //!     /// the pointer provided. Returns `false` if the setting value is not a
 //!     /// settings map. No value is stored into the pointer in that case. No
 //!     /// matter what happens, you still retain ownership of the setting value,
 //!     /// which means you still need to free it. You own the settings map and are
 //!     /// responsible for freeing it.
 //!     pub fn setting_value_get_map(value: SettingValue, value_ptr: *mut SettingsMap) -> bool;
+//!     /// Gets the value of a setting value as a settings list by storing it into
+//!     /// the pointer provided. Returns `false` if the setting value is not a
+//!     /// settings list. No value is stored into the pointer in that case. No
+//!     /// matter what happens, you still retain ownership of the setting value,
+//!     /// which means you still need to free it. You own the settings list and are
+//!     /// responsible for freeing it.
+//!     pub fn setting_value_get_list(value: SettingValue, value_ptr: *mut SettingsList) -> bool;
 //!     /// Gets the value of a boolean setting value by storing it into the pointer
 //!     /// provided. Returns `false` if the setting value is not a boolean. No
 //!     /// value is stored into the pointer in that case. No matter what happens,
@@ -392,6 +457,6 @@ mod timer;
 
 pub use process::Process;
 pub use runtime::{Config, CreationError, InterruptHandle, Runtime, RuntimeGuard};
-pub use settings::{SettingValue, SettingsMap, UserSetting, UserSettingKind};
+pub use settings::{SettingValue, SettingsList, SettingsMap, UserSetting, UserSettingKind};
 pub use time;
 pub use timer::{Timer, TimerState};