Add a better find function to instances

Author: vallode

dist/library/base.lua

@@ -69,7 +69,6 @@ function dfbase:_displace(index, step) end
 
 ---@class df.instance: df.class
 ---@field get_vector fun(): any[] The same as doing `df.global.<instance>.all`
----@field find fun(key: integer): any Binary search by specified `key` of all instances of the structure.
 
 ---@class df.iter: df.base
 ---@field _first_item integer

dist/library/df.announcements.lua

@@ -1464,6 +1464,10 @@ df.announcements = {}
 ---@field speaker_id integer References: unit<br>unit speaking the conversation
 df.report = {}
 
+---@param key integer
+---@return report|nil
+function df.report.find(key) end
+
 ---@class _report_flags: integer, string, df.bitfield
 ---@field continuation 0
 ---@field [0] "continuation"

dist/library/df.art.lua

@@ -382,6 +382,10 @@ df.art_image = {}
 ---@field images art_image[]
 df.art_image_chunk = {}
 
+---@param key integer
+---@return art_image_chunk|nil
+function df.art_image_chunk.find(key) end
+
 ---@class art_image_ref: df.class
 ---@field id integer References: art_image_chunk
 ---@field subid integer References: art_image
@@ -867,6 +871,10 @@ df.poetic_form_additional_feature = {}
 ---@field perspectives poetic_form_perspective[]
 df.poetic_form = {}
 
+---@param key integer
+---@return poetic_form|nil
+function df.poetic_form.find(key) end
+
 ---@class _poetic_form_flags: integer, string, df.bitfield
 ---@field tone_patterns 0
 ---@field [0] "tone_patterns"
@@ -1650,6 +1658,10 @@ df.musical_form_sub4 = {}
 ---@field flags musical_form_flags
 df.musical_form = {}
 
+---@param key integer
+---@return musical_form|nil
+function df.musical_form.find(key) end
+
 ---@class _musical_form_flags: integer, string, df.bitfield
 ---@field produces_individual_songs 0
 ---@field [0] "produces_individual_songs"
@@ -2317,6 +2329,10 @@ df.dance_form_move = {}
 ---@field moves dance_form_move[]
 df.dance_form = {}
 
+---@param key integer
+---@return dance_form|nil
+function df.dance_form.find(key) end
+
 ---@class _scale_type: integer, string, df.enum
 ---@field Octave 0
 ---@field [0] "Octave"
@@ -2362,6 +2378,10 @@ df.named_scale = {}
 ---@field notes scale_notes Curiously, the named notes do not have to match the number of defined notes
 df.scale = {}
 
+---@param key integer
+---@return scale|nil
+function df.scale.find(key) end
+
 ---@class _scale_flags: integer, string, df.bitfield
 ---@field tonic_note_fixed_at_performance 0
 ---@field [0] "tonic_note_fixed_at_performance"
@@ -2388,6 +2408,10 @@ df.scale.T_notes = {}
 ---@field unk_2 integer
 df.rhythm = {}
 
+---@param key integer
+---@return rhythm|nil
+function df.rhythm.find(key) end
+
 ---@class _beat_type: integer, string, df.enum
 ---@field Silent 0
 ---@field [0] "Silent"
@@ -2525,6 +2549,10 @@ df.occupation_type = {}
 ---@field unk_5 abstract_building When these haven't crashed the data has been nonsensical. Has seen duplicate of unk_4 pointer value
 df.occupation = {}
 
+---@param key integer
+---@return occupation|nil
+function df.occupation.find(key) end
+
 ---@class occupation_sub1: df.class
 ---@field unk_1 integer
 ---@field unk_2 integer

dist/library/df.building-raws.lua

@@ -25,6 +25,10 @@
 ---@field build_stages integer
 df.building_def = {}
 
+---@param key integer
+---@return building_def|nil
+function df.building_def.find(key) end
+
 ---@param unk_0 integer
 ---@param unk_1 integer
 ---@param unk_2 integer

dist/library/df.buildings.lua

@@ -404,6 +404,10 @@ df.building_drawbuffer = {}
 ---@field location_id integer References: abstract_building
 df.building = {}
 
+---@param key integer
+---@return building|nil
+function df.building.find(key) end
+
 ---@return integer
 function df.building.getCustomType() end
 

dist/library/df.creature-raws.lua

@@ -2283,6 +2283,10 @@ df.tissue_style_raw = {}
 ---@field statute_texpos integer[]
 df.creature_raw = {}
 
+---@param key integer
+---@return creature_raw|nil
+function df.creature_raw.find(key) end
+
 ---@class creature_raw_profession_name: df.class
 ---@field singular string[]
 ---@field plural string[]
@@ -2321,6 +2325,10 @@ df.creature_variation_convert_tag = {}
 ---@field cv_remove_unk_v40_2 string[]
 df.creature_variation = {}
 
+---@param key integer
+---@return creature_variation|nil
+function df.creature_variation.find(key) end
+
 ---@class _body_part_template_flags: integer, string, df.enum
 ---@field HEAD 0
 ---@field [0] "HEAD"
@@ -2497,6 +2505,10 @@ df.body_part_template = {}
 ---@field parts body_part_template[]
 df.body_template = {}
 
+---@param key integer
+---@return body_template|nil
+function df.body_template.find(key) end
+
 ---@class _tissue_flags: integer, string, df.enum
 ---@field THICKENS_ON_STRENGTH 0
 ---@field [0] "THICKENS_ON_STRENGTH"
@@ -2610,6 +2622,10 @@ df.tissue_flags = {}
 ---@field tissue_shape_str string
 df.tissue_template = {}
 
+---@param key integer
+---@return tissue_template|nil
+function df.tissue_template.find(key) end
+
 ---@class tissue: df.class
 ---@field id string
 ---@field flags tissue_flags[]
@@ -2666,3 +2682,7 @@ df.tissue = {}
 ---@field bp_relation_extent df.container
 df.body_detail_plan = {}
 
+---@param key integer
+---@return body_detail_plan|nil
+function df.body_detail_plan.find(key) end
+

dist/library/df.descriptors.lua

@@ -43,6 +43,10 @@ df.pattern_type = {}
 ---@field unk_v50_1 integer[]
 df.descriptor_color = {}
 
+---@param key integer
+---@return descriptor_color|nil
+function df.descriptor_color.find(key) end
+
 ---@class descriptor_shape: df.instance
 ---@field id string
 ---@field words_str string[] temporary storage before resolving to language_word
@@ -62,6 +66,10 @@ df.descriptor_color = {}
 ---@field unk_v50_6 integer
 df.descriptor_shape = {}
 
+---@param key integer
+---@return descriptor_shape|nil
+function df.descriptor_shape.find(key) end
+
 ---@class _descriptor_shape_gems_use: integer, string, df.bitfield
 ---@field noun 0
 ---@field [0] "noun"
@@ -86,3 +94,7 @@ df.descriptor_shape.T_gems_use = {}
 ---@field cp_color string[]
 df.descriptor_pattern = {}
 
+---@param key integer
+---@return descriptor_pattern|nil
+function df.descriptor_pattern.find(key) end
+

dist/library/df.entities.lua

@@ -885,6 +885,10 @@ df.entity_unk_v47_1 = {}
 ---@field unk_11 integer
 df.historical_entity = {}
 
+---@param key integer
+---@return historical_entity|nil
+function df.historical_entity.find(key) end
+
 ---@class _historical_entity_flags: integer, string, df.bitfield
 ---@field neighbor 0
 ---@field [0] "neighbor"
@@ -2149,6 +2153,10 @@ df.entity_event.T_data.T_artifact_destroyed = {}
 ---@field flags agreement_flags
 df.agreement = {}
 
+---@param key integer
+---@return agreement|nil
+function df.agreement.find(key) end
+
 ---@class _agreement_flags: integer, string, df.bitfield
 ---@field petition_not_accepted 0
 ---@field [0] "petition_not_accepted"

dist/library/df.entity-raws.lua

@@ -654,6 +654,10 @@ df.entity_name_type = {}
 ---@field animal entity_animal_raw[]
 df.entity_raw = {}
 
+---@param key integer
+---@return entity_raw|nil
+function df.entity_raw.find(key) end
+
 ---@class entity_raw_equipment: df.class
 ---@field digger_id df.container References: itemdef_weaponst
 ---@field weapon_id df.container References: itemdef_weaponst

dist/library/df.history.lua

@@ -1614,6 +1614,10 @@ df.vague_relationship_type = {}
 ---@field unk_5 integer
 df.historical_figure = {}
 
+---@param key integer
+---@return historical_figure|nil
+function df.historical_figure.find(key) end
+
 ---Do not have to be available mutually, i.e. DF can display Legends relations forming for the other party that does not have an entry (plus time and other conditions not located)
 ---@class historical_figure_vague_relationships: df.class
 ---@field hfid integer[] References: historical_figure
@@ -1705,6 +1709,10 @@ df.identity_type.attrs = {}
 ---@field unk_5 identity_unk_95[]
 df.identity = {}
 
+---@param key integer
+---@return identity|nil
+function df.identity.find(key) end
+
 ---@class identity_unk_94: df.class
 ---@field unk_0 integer
 ---@field unk_1 df.container
@@ -2998,6 +3006,10 @@ df.merc_role_type = {}
 ---@field id integer
 df.history_event = {}
 
+---@param key integer
+---@return history_event|nil
+function df.history_event.find(key) end
+
 ---@return history_event_type
 function df.history_event.getType() end
 
@@ -5266,6 +5278,10 @@ df.history_event_collection_type = {}
 ---@field id integer
 df.history_event_collection = {}
 
+---@param key integer
+---@return history_event_collection|nil
+function df.history_event_collection.find(key) end
+
 ---@return history_event_collection_type
 function df.history_event_collection.getType() end
 
@@ -5670,6 +5686,10 @@ df.world_history.T_event_collections = {}
 ---@field circumstance history_event_circumstance_info
 df.intrigue = {}
 
+---@param key integer
+---@return intrigue|nil
+function df.intrigue.find(key) end
+
 ---@class intrigue_corruption: df.class
 ---@field crime crime_type
 ---@field corruptor_id integer References: historical_figure