Adds a few LAZYLIST macros and documentation (#25590)

* wow none of this was documented!

* sentences two spaces to death

* corrects lazylen comment

code/__HELPERS/lists.dm

@@ -643,33 +643,54 @@
 //Picks from the list, with some safeties, and returns the "default" arg if it fails
 #define DEFAULTPICK(L, default) ((istype(L, /list) && L:len) ? pick(L) : default)
 
+///Initialize the lazylist
 #define LAZYINITLIST(L) if(!L) { L = list() }
-
+///If the provided list is empty, set it to null
 #define UNSETEMPTY(L) if(L && !length(L)) L = null
+///If the provided key -> list is empty, remove it from the list
+#define ASSOC_UNSETEMPTY(L, K) if(!length(L[K])) L -= K;
+///Like LAZYCOPY - copies an input list if the list has entries, If it doesn't the assigned list is nulled
+#define LAZYLISTDUPLICATE(L) (L ? L.Copy() : null )
+///Remove an item from the list, set the list to null if empty
 #define LAZYREMOVE(L, I) if(L) { L -= I; if(!length(L)) { L = null; } }
+///Add an item to the list, if the list is null it will initialize it
 #define LAZYADD(L, I) if(!L) { L = list(); } L += I;
-/// Add an item to the list if not already present, if the list is null it will initialize it
+///Add an item to the list if not already present, if the list is null it will initialize it
 #define LAZYOR(L, I) if(!L) { L = list(); } L |= I;
-/// Adds I to L, initializing L if necessary, if I is not already in L
+///Adds I to L, initializing L if necessary, if I is not already in L
 #define LAZYDISTINCTADD(L, I) if(!L) { L = list(); } L |= I;
+///returns L[I] if L exists and I is a valid index of L, runtimes if L is not a list
 #define LAZYACCESS(L, I) (L ? (isnum(I) ? (I > 0 && I <= length(L) ? L[I] : null) : L[I]) : null)
+///Returns the length of L
 #define LAZYLEN(L) length(L) // Despite how pointless this looks, it's still needed in order to convey that the list is specificially a 'Lazy' list.
+///Sets a list to null
+#define LAZYNULL(L) L = null
+///Removes all elements from the list
 #define LAZYCLEARLIST(L) if(L) L.Cut()
-
-// LAZYING PT 2: THE LAZENING
+//Clears a list and then re-initializes it
 #define LAZYREINITLIST(L) LAZYCLEARLIST(L); LAZYINITLIST(L);
-
-// Lazying Episode 3
-#define LAZYSET(L, K, V) LAZYINITLIST(L); L[K] = V;
-
-#define LAZYADDASSOC(L, K, V) if(!L) { L = list(); } L[K] += list(V);
+///Use LAZYLISTDUPLICATE instead if you want it to null with no entries
+#define LAZYCOPY(L) (L ? L.Copy() : list() )
+///Sets the item K to the value V, if the list is null it will initialize it
+#define LAZYSET(L, K, V) if(!L) { L = list(); } L[K] = V;
+///Sets the length of a lazylist
+#define LAZYSETLEN(L, V) if(!L) { L = list(); } L.len = V;
+///Adds to the item K the value V, if the list is null it will initialize it
+#define LAZYADDASSOC(L, K, V) if(!L) { L = list(); } L[K] += V;
+///This is used to add onto lazy assoc list when the value you're adding is a /list/. This one has extra safety over lazyaddassoc because the value could be null (and thus cant be used to += objects)
+#define LAZYADDASSOCLIST(L, K, V) if(!L) { L = list(); } L[K] += list(V);
+///Removes the value V from the item K, if the item K is empty will remove it from the list, if the list is empty will set the list to null
 #define LAZYREMOVEASSOC(L, K, V) if(L) { if(L[K]) { L[K] -= V; if(!length(L[K])) L -= K; } if(!length(L)) L = null; }
-
-/// Returns whether a numerical index is within a given list's bounds. Faster than isnull(LAZYACCESS(L, I)).
-#define ISINDEXSAFE(L, I) (I >= 1 && I <= length(L))
+///Accesses an associative list, returns null if nothing is found
+#define LAZYACCESSASSOC(L, I, K) L ? L[I] ? L[I][K] ? L[I][K] : null : null : null
+///Qdel every item in the list before setting the list to null
+#define QDEL_LAZYLIST(L) for(var/I in L) qdel(I); L = null;
 ///If the lazy list is currently initialized find item I in list L
 #define LAZYIN(L, I) (L && (I in L))
-/// Performs an insertion on the given lazy list with the given key and value. If the value already exists, a new one will not be made.
+///Returns whether a numerical index is within a given list's bounds. Faster than isnull(LAZYACCESS(L, I)).
+#define ISINDEXSAFE(L, I) (I >= 1 && I <= length(L))
+
+///Performs an insertion on the given lazy list with the given key and value. If the value already exists, a new one will not be made.
 #define LAZYORASSOCLIST(lazy_list, key, value) \
 	LAZYINITLIST(lazy_list); \
 	LAZYINITLIST(lazy_list[key]); \

code/controllers/subsystem/SSchat.dm

@@ -66,7 +66,7 @@ SUBSYSTEM_DEF(chat)
 		var/client/client = CLIENT_FROM_VAR(target)
 		if(isnull(client))
 			continue
-		LAZYADDASSOC(client_to_payloads, client.ckey, generate_payload(client, message_data))
+		LAZYADDASSOCLIST(client_to_payloads, client.ckey, generate_payload(client, message_data))
 
 /datum/controller/subsystem/chat/proc/send_immediate(send_target, list/message_data)
 	var/list/targets = islist(send_target) ? send_target : list(send_target)

code/datums/chatmessage.dm

@@ -210,7 +210,7 @@
 	animate_lifespan = lifespan
 
 	// View the message
-	LAZYADDASSOC(owned_by.seen_messages, message_loc, src)
+	LAZYADDASSOCLIST(owned_by.seen_messages, message_loc, src)
 	owned_by.images |= message
 
 	// Fade in

code/game/objects/effects/spawners/grouped_spawner.dm

@@ -51,7 +51,7 @@
 	..()
 
 	save_spawn_values()
-	LAZYADDASSOC(spawner_groups, group_id, src)
+	LAZYADDASSOCLIST(spawner_groups, group_id, src)
 
 	return INITIALIZE_HINT_LATELOAD