new methods: equals, appendfile

Author: osch

.github/workflows/test.yml

@@ -31,6 +31,7 @@ jobs:
         lua -v
         cd tests
         lua test01.lua
+        lua test02.lua
         cd ../examples
         lua example01.lua
      

doc/README.md

@@ -24,6 +24,8 @@
         * [array:setlen()](#array_setlen)
         * [array:reserve()](#array_reserve)
         * [array:tostring()](#array_tostring)
+        * [array:equals()](#array_equals)
+        * [array:appendfile()](#array_appendfile)
 
 <!-- ---------------------------------------------------------------------------------------- -->
 ##   Overview
@@ -46,7 +48,7 @@ local carray = require("carray")
 ##   Module Functions
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="carray_new">**`  carray.new(type[, count])
+* <a id="carray_new">**`carray.new(type[, count])
   `**</a>
 
   Creates a new array object with the specified element type.
@@ -109,9 +111,17 @@ to [carray.new()](#carray_new).
 
 Array objects can be created by calling the module function [carray.new()](#carray_new).
 
+If not other specified, array methods return the array object to allow method chaining, 
+e.g.
+```lua
+    local a = carray.new("char"):append("testdata:"):appendfile("test1.data")
+```
+creates a new array with data from string and file content and assigns this array to the
+variable *a*.
+
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_get">**`      array:get(pos1[, pos2])
+* <a id="array_get">**`array:get(pos1[, pos2])
   `** </a>
 
   Get elements from the array.
@@ -128,7 +138,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_set">**`      array:set(pos, ...)
+* <a id="array_set">**`array:set(pos, ...)
   `** </a>
 
   Sets the given elements at the specified position of the array object.
@@ -147,7 +157,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_append">**`      array:append(...)
+* <a id="array_append">**`array:append(...)
   `** </a>
 
   Appends the given elements to the end of the array object.
@@ -160,7 +170,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_insert">**`      array:insert(pos, ...)
+* <a id="array_insert">**`array:insert(pos, ...)
   `** </a>
 
   Inserts the given elements at the specified position of the array object.
@@ -175,7 +185,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_setsub">**`      array:setsub(pos0, array2, pos1, pos2)
+* <a id="array_setsub">**`array:setsub(pos0, array2, pos1, pos2)
   `** </a>
 
   Sets elements of another array *array2* to the specified position *pos0*
@@ -201,7 +211,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_appendsub">**`      array:appendsub(array2, pos1, pos2)
+* <a id="array_appendsub">**`array:appendsub(array2, pos1, pos2)
   `** </a>
 
   Appends elements of another array *array2* to the end of the array object.
@@ -222,7 +232,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_insertsub">**`      array:insertsub(pos0, array2, pos1, pos2)
+* <a id="array_insertsub">**`array:insertsub(pos0, array2, pos1, pos2)
   `** </a>
 
   Inserts elements of another array *array2* to the specified position *pos0*
@@ -246,7 +256,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_remove">**`      array:remove(pos1[, pos2])
+* <a id="array_remove">**`array:remove(pos1[, pos2])
   `** </a>
 
   Removes elements from the array.
@@ -264,14 +274,14 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_len">**`      array:len()
+* <a id="array_len">**`array:len()
   `** </a>
 
   Returns the number of elements in the array object.
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_type">**`      array:type()
+* <a id="array_type">**`array:type()
   `** </a>
 
   Returns the element type name as string value. Possible values are:
@@ -287,7 +297,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_basetype">**`      array:basetype()
+* <a id="array_basetype">**`array:basetype()
   `** </a>
 
   Returns the element base type name as string value. Possible values are:
@@ -300,7 +310,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_bitwidth">**`      array:bitwidth()
+* <a id="array_bitwidth">**`array:bitwidth()
   `** </a>
 
   Returns the number of bits per element as integer value.
@@ -309,7 +319,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_reset">**`      array:reset([shrink])
+* <a id="array_reset">**`array:reset([shrink])
   `** </a>
 
   Resets the array to length 0.
@@ -321,7 +331,7 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_setlen">**`      array:setlen(newlen[, shrink])
+* <a id="array_setlen">**`array:setlen(newlen[, shrink])
   `** </a>
 
   Sets how many elements can be stored in the array. 
@@ -337,22 +347,23 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_reserve">**`      array:reserve([count])
+* <a id="array_reserve">**`array:reserve([count])
   `** </a>
 
-  Sets or get the reserve count. The reserve count denotes the number of new elements that
+  Sets or gets the reserve count. The reserve count denotes the number of new elements that
   can be appended to the array without the need to re-allocate the array's memory.
 
   * *count* - optional integer, if greater zero this methods assures that the reserve is at 
               least *count* number of elements. If zero or less the reserve is
               released, i.e. the allocated memory for this array object is not greater than
               needed for the [arry:len()](#array_len) number of elements in this array.
 
-  This method returns the current reserve count.
+  This method returns the current reserve count if no argument *count* is given, 
+  otherwise the array object itself is returned to allow method chaining.
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
-* <a id="array_tostring">**`      array:tostring([pos1, pos2])
+* <a id="array_tostring">**`array:tostring([pos1, pos2])
   `** </a>
 
   Returns array elements as string value for arrays that have element type *signed char*
@@ -371,6 +382,24 @@ Array objects can be created by calling the module function [carray.new()](#carr
 
 <!-- ---------------------------------------------------------------------------------------- -->
 
+* <a id="array_equals">**`array:equals(array2)
+  `** </a>
+
+  Returns *true* if the two arrays are having the same number and type of elements.
+  
+<!-- ---------------------------------------------------------------------------------------- -->
+
+* <a id="array_appendfile">**`array:appendfile(file[, pos])
+  `** </a>
+
+  Appends the content of the given file to the array.
+  
+  * *file* - a file name string or open file handle.
+  * *pos*  - optional integer, the maximal number of elements that are read from the
+             given file.
+
+<!-- ---------------------------------------------------------------------------------------- -->
+
 [Lua]:          https://www.lua.org
 [Carray C API]: https://github.com/lua-capis/lua-carray-capi
 

src/carray.c

@@ -1,4 +1,6 @@
 #include <limits.h>
+#include <stdio.h>
+#include <stddef.h>
 
 #define CARRAY_CAPI_IMPLEMENT_SET_CAPI 1
 #define CARRAY_CAPI_IMPLEMENT_GET_CAPI 1
@@ -1206,7 +1208,8 @@ static int Carray_reserve(lua_State* L)
         else if (newRes <= 0) {
             carray_capi_impl.resizeCarray(impl, currCount, -1);
         }
-        return 0;
+        lua_settop(L, 1);
+        return 1;
     }
     lua_pushinteger(L, impl->elementCapacity - impl->elementCount);
     return 1;
@@ -1278,6 +1281,92 @@ static int Carray_resizable(lua_State* L)
 
 /* ============================================================================================ */
 
+static int Carray_appendfile(lua_State* L)
+{
+    int arg = 1;
+    CarrayUserData* udata = checkWritableUdata(L, arg);
+    carray*         impl  = udata->impl;
+    
+    luaL_Stream* stream = (luaL_Stream*)luaL_testudata(L, ++arg, LUA_FILEHANDLE);
+    FILE* file;
+    if (stream) {
+        file = stream->f;
+        if (!file) {
+            return luaL_argerror(L, arg, "invalid file");
+        }
+    } else {
+        const char* name = lua_tostring(L, arg);
+        if (!name) {
+            luaL_argerror(L, arg, "file handle or name expected");
+        }
+        file = fopen(name, "rb");
+        if (!file) {
+            luaL_argerror(L, arg, "cannot open file");
+        }
+    }
+    lua_Integer maxCount = -1;
+    if (!lua_isnoneornil(L, ++arg)) {
+        maxCount = luaL_checkinteger(L, arg);
+        if (maxCount <= 0) {
+            if (!stream) fclose(file);
+            lua_settop(L, 1);
+            return 1;
+        }
+    }
+    size_t elementSize = impl->elementSize;
+again:;
+    size_t elementCount = impl->elementCount;
+    size_t nitems;
+    if (maxCount > 0) {
+        nitems = maxCount;
+    } else {
+        nitems = impl->elementCapacity - elementCount;
+        if (nitems < 8*1024) {
+            nitems = 8*1024;
+        }
+    }
+    char* data = carray_capi_impl.resizeCarray(impl, elementCount + nitems, 0);
+    if (!data) {
+        if (!stream) fclose(file);
+        return luaL_error(L, "resizing carray failed");
+    }
+    size_t rslt = fread(data + (elementSize * elementCount), elementSize, nitems, file);
+    if (rslt > 0) {
+        impl->elementCount = elementCount + rslt;
+        if (rslt == nitems && maxCount < 0) {
+            goto again;
+        }
+    } else {
+        impl->elementCount = elementCount;
+    }
+    if (rslt < nitems && ferror(file)) {
+        int en = errno;
+        if (!stream) fclose(file);
+        return luaL_error(L, "error reading from file: %s (errno=%d)", strerror(en), en);
+    }
+    if (!stream) fclose(file);
+    lua_settop(L, 1);
+    return 1;
+}
+
+/* ============================================================================================ */
+
+static int Carray_equals(lua_State* L)
+{
+    carray* udata1 = checkReadableUdata(L, 1)->impl;
+    carray* udata2 = checkReadableUdata(L, 2)->impl;
+
+    size_t dataLength = udata1->elementSize * udata1->elementCount;
+
+    lua_pushboolean(L, udata1->elementType  == udata2->elementType
+                   &&  udata1->elementSize  == udata2->elementSize
+                   &&  udata1->elementCount == udata2->elementCount
+                   && (dataLength == 0 || memcmp(udata1->buffer, udata2->buffer, dataLength) == 0));
+    return 1;
+}
+
+/* ============================================================================================ */
+
 static int Carray_toString(lua_State* L)
 {
     CarrayUserData* udata = luaL_checkudata(L, 1, CARRAY_CLASS_NAME);
@@ -1326,6 +1415,8 @@ static const luaL_Reg CarrayMethods[] =
     { "bitwidth",   Carray_bitwidth  },
     { "writable",   Carray_writable  },
     { "resizable",  Carray_resizable },
+    { "equals",     Carray_equals    },
+    { "appendfile", Carray_appendfile },
     { NULL,         NULL } /* sentinel */
 };
 

tests/test01.lua

@@ -845,4 +845,4 @@ do
     assert(a:tostring() == "1232345678")
 end
 PRINT("==================================================================================")
-print("OK.")
+print("test01 OK.")

tests/test02.data

@@ -0,0 +1 @@
+123456789

tests/test02.lua

@@ -0,0 +1,27 @@
+c=require"carray"
+a=c.new"char"
+assert(a==a:appendfile("test02.data"))
+assert(a:len() == 10)
+assert(a:tostring(1,-1) == "123456789\n")
+a:reset():appendfile("test02.data", 2)
+assert(a:len() == 2)
+assert(a:tostring(1,-1) == "12")
+f=io.open("test02.data", "rb")
+
+a:reset():appendfile(f, 2)
+assert(a:len() == 2)
+assert(a:tostring(1,-1) == "12")
+
+a:appendfile(f, 2)
+assert(a:len() == 4)
+assert(a:tostring(1,-1) == "1234")
+
+a:appendfile(f, 10)
+assert(a:len() == 10)
+assert(a:tostring(1,-1) == "123456789\n")
+
+assert(a:equals(c.new("char"):appendfile("test02.data")))
+
+assert(not a:equals(c.new("char"):appendfile("test02.data", 3)))
+
+print("test02 OK.")