Add a few utility functions to the main library.

Lua API.html

@@ -1239,6 +1239,12 @@ Returns <em>false</em> in case of error.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.items.getContainedItems(item)</tt></p>
 <p>Returns a list of items contained in this one.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.items.getHolderBuilding(item)</tt></p>
+<p>Returns the holder building or <em>nil</em>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">dfhack.items.getHolderUnit(item)</tt></p>
+<p>Returns the holder unit or <em>nil</em>.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.items.moveToGround(item,pos)</tt></p>
 <p>Move the item to the ground at position. Returns <em>false</em> if impossible.</p>
 </li>

Lua API.rst

@@ -1019,6 +1019,14 @@ Items module
 
   Returns a list of items contained in this one.
 
+* ``dfhack.items.getHolderBuilding(item)``
+
+  Returns the holder building or *nil*.
+
+* ``dfhack.items.getHolderUnit(item)``
+
+  Returns the holder unit or *nil*.
+
 * ``dfhack.items.moveToGround(item,pos)``
 
   Move the item to the ground at position. Returns *false* if impossible.

library/LuaApi.cpp

@@ -942,6 +942,8 @@ static const LuaWrapper::FunctionReg dfhack_items_module[] = {
     WRAPM(Items, getOwner),
     WRAPM(Items, setOwner),
     WRAPM(Items, getContainer),
+    WRAPM(Items, getHolderBuilding),
+    WRAPM(Items, getHolderUnit),
     WRAPM(Items, getDescription),
     WRAPM(Items, isCasteMaterial),
     WRAPM(Items, getSubtypeCount),

library/MiscUtils.cpp

@@ -148,6 +148,11 @@ bool prefix_matches(const std::string &prefix, const std::string &key, std::stri
     return false;
 }
 
+int random_int(int max)
+{
+    return int(int64_t(rand())*max/(int64_t(RAND_MAX)+1));
+}
+
 #ifdef LINUX_BUILD // Linux
 uint64_t GetTimeMs64()
 {

library/include/MiscUtils.h

@@ -331,6 +331,8 @@ inline T clip_range(T a, T1 minv, T2 maxv) {
     return a;
 }
 
+DFHACK_EXPORT int random_int(int max);
+
 /**
  * Returns the amount of milliseconds elapsed since the UNIX epoch.
  * Works on both windows and linux.

library/include/modules/Items.h

@@ -151,6 +151,11 @@ DFHACK_EXPORT df::item *getContainer(df::item *item);
 /// which items does it contain?
 DFHACK_EXPORT void getContainedItems(df::item *item, /*output*/ std::vector<df::item*> *items);
 
+/// which building holds it?
+DFHACK_EXPORT df::building *getHolderBuilding(df::item *item);
+/// which unit holds it?
+DFHACK_EXPORT df::unit *getHolderUnit(df::item *item);
+
 /// Returns the true position of the item.
 DFHACK_EXPORT df::coord getPosition(df::item *item);
 

library/modules/Items.cpp

@@ -592,6 +592,20 @@ void Items::getContainedItems(df::item *item, std::vector<df::item*> *items)
     }
 }
 
+df::building *Items::getHolderBuilding(df::item * item)
+{
+    auto ref = getGeneralRef(item, general_ref_type::BUILDING_HOLDER);
+
+    return ref ? ref->getBuilding() : NULL;
+}
+
+df::unit *Items::getHolderUnit(df::item * item)
+{
+    auto ref = getGeneralRef(item, general_ref_type::UNIT_HOLDER);
+
+    return ref ? ref->getUnit() : NULL;
+}
+
 df::coord Items::getPosition(df::item *item)
 {
     CHECK_NULL_POINTER(item);

plugins/siege-engine.cpp

@@ -132,11 +132,6 @@ static void orient_engine(df::building_siegeenginest *bld, df::coord target)
             df::building_siegeenginest::Up;
 }
 
-static int random_int(int val)
-{
-    return int(int64_t(rand())*val/RAND_MAX);
-}
-
 static int point_distance(df::coord speed)
 {
     return std::max(abs(speed.x), std::max(abs(speed.y), abs(speed.z)));