Add more native api functions for finding general and specific refs.

Lua API.rst

@@ -833,6 +833,14 @@ Job module
 
   Prints info about the job item.
 
+* ``dfhack.job.getGeneralRef(job, type)``
+
+  Searches for a general_ref with the given type.
+
+* ``dfhack.job.getSpecificRef(job, type)``
+
+  Searches for a specific_ref with the given type.
+
 * ``dfhack.job.getHolder(job)``
 
   Returns the building holding the job.
@@ -879,6 +887,14 @@ Units module
 
   Returns true *x,y,z* of the unit, or *nil* if invalid; may be not equal to unit.pos if caged.
 
+* ``dfhack.units.getGeneralRef(unit, type)``
+
+  Searches for a general_ref with the given type.
+
+* ``dfhack.units.getSpecificRef(unit, type)``
+
+  Searches for a specific_ref with the given type.
+
 * ``dfhack.units.getContainer(unit)``
 
   Returns the container (cage) item or *nil*.
@@ -1198,6 +1214,14 @@ Burrows module
 Buildings module
 ----------------
 
+* ``dfhack.buildings.getGeneralRef(building, type)``
+
+  Searches for a general_ref with the given type.
+
+* ``dfhack.buildings.getSpecificRef(building, type)``
+
+  Searches for a specific_ref with the given type.
+
 * ``dfhack.buildings.setOwner(item,unit)``
 
   Replaces the owner of the building. If unit is *nil*, removes ownership.

library/LuaApi.cpp

@@ -1121,6 +1121,8 @@ static const LuaWrapper::FunctionReg dfhack_job_module[] = {
     WRAPM(Job,cloneJobStruct),
     WRAPM(Job,printItemDetails),
     WRAPM(Job,printJobDetails),
+    WRAPM(Job,getGeneralRef),
+    WRAPM(Job,getSpecificRef),
     WRAPM(Job,getHolder),
     WRAPM(Job,getWorker),
     WRAPM(Job,checkBuildingsNow),
@@ -1157,6 +1159,8 @@ static const luaL_Reg dfhack_job_funcs[] = {
 /***** Units module *****/
 
 static const LuaWrapper::FunctionReg dfhack_units_module[] = {
+    WRAPM(Units, getGeneralRef),
+    WRAPM(Units, getSpecificRef),
     WRAPM(Units, getContainer),
     WRAPM(Units, setNickname),
     WRAPM(Units, getVisibleName),
@@ -1427,6 +1431,8 @@ static bool buildings_containsTile(df::building *bld, int x, int y, bool room) {
 }
 
 static const LuaWrapper::FunctionReg dfhack_buildings_module[] = {
+    WRAPM(Buildings, getGeneralRef),
+    WRAPM(Buildings, getSpecificRef),
     WRAPM(Buildings, setOwner),
     WRAPM(Buildings, allocInstance),
     WRAPM(Buildings, checkFreeTiles),

library/Types.cpp

@@ -100,6 +100,24 @@ bool DFHack::removeRef(std::vector<df::general_ref*> &vec, df::general_ref_type
     return false;
 }
 
+df::item *DFHack::findItemRef(std::vector<df::general_ref*> &vec, df::general_ref_type type)
+{
+    auto ref = findRef(vec, type);
+    return ref ? ref->getItem() : NULL;
+}
+
+df::building *DFHack::findBuildingRef(std::vector<df::general_ref*> &vec, df::general_ref_type type)
+{
+    auto ref = findRef(vec, type);
+    return ref ? ref->getBuilding() : NULL;
+}
+
+df::unit *DFHack::findUnitRef(std::vector<df::general_ref*> &vec, df::general_ref_type type)
+{
+    auto ref = findRef(vec, type);
+    return ref ? ref->getUnit() : NULL;
+}
+
 df::specific_ref *DFHack::findRef(std::vector<df::specific_ref*> &vec, df::specific_ref_type type)
 {
     for (int i = vec.size()-1; i >= 0; i--)

library/include/Types.h

@@ -80,6 +80,10 @@ namespace DFHack
     DFHACK_EXPORT df::general_ref *findRef(std::vector<df::general_ref*> &vec, df::general_ref_type type);
     DFHACK_EXPORT bool removeRef(std::vector<df::general_ref*> &vec, df::general_ref_type type, int id);
 
+    DFHACK_EXPORT df::item *findItemRef(std::vector<df::general_ref*> &vec, df::general_ref_type type);
+    DFHACK_EXPORT df::building *findBuildingRef(std::vector<df::general_ref*> &vec, df::general_ref_type type);
+    DFHACK_EXPORT df::unit *findUnitRef(std::vector<df::general_ref*> &vec, df::general_ref_type type);
+
     DFHACK_EXPORT df::specific_ref *findRef(std::vector<df::specific_ref*> &vec, df::specific_ref_type type);
     DFHACK_EXPORT bool removeRef(std::vector<df::specific_ref*> &vec, df::specific_ref_type type, void *ptr);
 }// namespace DFHack

library/include/modules/Buildings.h

@@ -92,6 +92,9 @@ DFHACK_EXPORT bool Read (const uint32_t index, t_building & building);
  */
 DFHACK_EXPORT bool ReadCustomWorkshopTypes(std::map <uint32_t, std::string> & btypes);
 
+DFHACK_EXPORT df::general_ref *getGeneralRef(df::building *building, df::general_ref_type type);
+DFHACK_EXPORT df::specific_ref *getSpecificRef(df::building *building, df::specific_ref_type type);
+
 /**
  * Sets the owner unit for the building.
  */

library/include/modules/Job.h

@@ -28,6 +28,8 @@ distribution.
 
 #include "Export.h"
 #include "Module.h"
+#include "Types.h"
+
 #include <ostream>
 
 #include "DataDefs.h"
@@ -55,6 +57,9 @@ namespace DFHack
         DFHACK_EXPORT void printItemDetails(color_ostream &out, df::job_item *item, int idx);
         DFHACK_EXPORT void printJobDetails(color_ostream &out, df::job *job);
 
+        DFHACK_EXPORT df::general_ref *getGeneralRef(df::job *job, df::general_ref_type type);
+        DFHACK_EXPORT df::specific_ref *getSpecificRef(df::job *job, df::specific_ref_type type);
+
         DFHACK_EXPORT df::building *getHolder(df::job *job);
         DFHACK_EXPORT df::unit *getWorker(df::job *job);
 

library/include/modules/Units.h

@@ -205,6 +205,9 @@ DFHACK_EXPORT void CopyNameTo(df::unit *creature, df::language_name * target);
 /// Returns the true position of the unit (non-trivial in case of caged).
 DFHACK_EXPORT df::coord getPosition(df::unit *unit);
 
+DFHACK_EXPORT df::general_ref *getGeneralRef(df::unit *unit, df::general_ref_type type);
+DFHACK_EXPORT df::specific_ref *getSpecificRef(df::unit *unit, df::specific_ref_type type);
+
 DFHACK_EXPORT df::item *getContainer(df::unit *unit);
 
 DFHACK_EXPORT void setNickname(df::unit *unit, std::string nick);

library/modules/Buildings.cpp

@@ -178,6 +178,20 @@ bool Buildings::ReadCustomWorkshopTypes(map <uint32_t, string> & btypes)
     return true;
 }
 
+df::general_ref *Buildings::getGeneralRef(df::building *building, df::general_ref_type type)
+{
+    CHECK_NULL_POINTER(building);
+
+    return findRef(building->general_refs, type);
+}
+
+df::specific_ref *Buildings::getSpecificRef(df::building *building, df::specific_ref_type type)
+{
+    CHECK_NULL_POINTER(building);
+
+    return findRef(building->specific_refs, type);
+}
+
 bool Buildings::setOwner(df::building *bld, df::unit *unit)
 {
     CHECK_NULL_POINTER(bld);

library/modules/Job.cpp

@@ -35,6 +35,7 @@ using namespace std;
 #include "Error.h"
 #include "PluginManager.h"
 #include "MiscUtils.h"
+#include "Types.h"
 
 #include "modules/Job.h"
 #include "modules/Materials.h"
@@ -228,6 +229,20 @@ void DFHack::Job::printJobDetails(color_ostream &out, df::job *job)
         printItemDetails(out, job->job_items[i], i);
 }
 
+df::general_ref *Job::getGeneralRef(df::job *job, df::general_ref_type type)
+{
+    CHECK_NULL_POINTER(job);
+
+    return findRef(job->general_refs, type);
+}
+
+df::specific_ref *Job::getSpecificRef(df::job *job, df::specific_ref_type type)
+{
+    CHECK_NULL_POINTER(job);
+
+    return findRef(job->specific_refs, type);
+}
+
 df::building *DFHack::Job::getHolder(df::job *job)
 {
     CHECK_NULL_POINTER(job);

library/modules/Units.cpp

@@ -519,18 +519,25 @@ df::coord Units::getPosition(df::unit *unit)
     return unit->pos;
 }
 
-df::item *Units::getContainer(df::unit *unit)
+df::general_ref *Units::getGeneralRef(df::unit *unit, df::general_ref_type type)
 {
     CHECK_NULL_POINTER(unit);
 
-    for (size_t i = 0; i < unit->general_refs.size(); i++)
+    return findRef(unit->general_refs, type);
+}
+
+df::specific_ref *Units::getSpecificRef(df::unit *unit, df::specific_ref_type type)
 {
-        df::general_ref *ref = unit->general_refs[i];
+    CHECK_NULL_POINTER(unit);
-        if (ref->getType() == general_ref_type::CONTAINED_IN_ITEM)
+
-            return ref->getItem();
+    return findRef(unit->specific_refs, type);
 }
 
-    return NULL;
+df::item *Units::getContainer(df::unit *unit)
+{
+    CHECK_NULL_POINTER(unit);
+
+    return findItemRef(unit->general_refs, general_ref_type::CONTAINED_IN_ITEM);
 }
 
 static df::assumed_identity *getFigureIdentity(df::historical_figure *figure)