Initial Public Release.

Author: lorinder

.gitignore

@@ -0,0 +1,7 @@
+*.o
+*.os
+*.so
+.sconsign.dblite
+test/rng_mt_test
+test/runif_geti_test
+test/runif_getf_test

CMakeLists.txt

@@ -0,0 +1,85 @@
+cmake_minimum_required(VERSION 3.10)
+
+project(csnip
+	VERSION 0.1
+	LANGUAGES C
+)
+
+### Check for C++
+include(CheckLanguage)
+check_language(CXX)
+if (CMAKE_CXX_COMPILER)
+	set(has_cxx ON)
+else()
+	set(has_cxx OFF)
+endif()
+option(BUILD_CXX_PIECES "Build C++ parts" ${has_cxx})
+if (BUILD_CXX_PIECES)
+	enable_language(CXX)
+endif()
+
+### Project-wide settings and compiler flags
+
+#set(CMAKE_C_VISIBILITY_PRESET hidden)
+
+if (CMAKE_C_COMPILER_ID MATCHES GNU OR CMAKE_C_COMPILER_ID MATCHES CLANG)
+	set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -Wall")
+endif ()
+if (CMAKE_CXX_COMPILER_ID MATCHES GNU OR
+  CMAKE_CXX_COMPILER_ID MATCHES CLANG)
+	set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall")
+endif ()
+
+### Dependencies
+option(BUILD_DOCS "Build documentation" ON)
+if (BUILD_DOCS)
+	find_package(Doxygen REQUIRED)
+endif ()
+
+### Testing
+
+enable_testing()
+
+#### Installation
+
+include(GNUInstallDirs)
+set(INSTALL_LIBDIR ${CMAKE_INSTALL_LIBDIR}
+	CACHE STRING "Relative installation directory for libraries")
+set(INSTALL_BINDIR ${CMAKE_INSTALL_BINDIR}
+	CACHE STRING "Relative installation directory for binaries")
+set(INSTALL_INCLUDEDIR
+	${CMAKE_INSTALL_INCLUDEDIR}/csnip-${PROJECT_VERSION}
+  	CACHE STRING "Relative installation directory for headers")
+set(INSTALL_DOCDIR
+	${CMAKE_INSTALL_DOCDIR}
+	CACHE STRING "Relative installation directory for documentation")
+
+#### Subdirectories
+
+add_subdirectory(examples)
+add_subdirectory(in)
+add_subdirectory(src)
+add_subdirectory(test)
+
+# doc/ comes last as Doxygen will need to know the complete other
+# targets.
+add_subdirectory(doc)
+
+
+### Packaging
+
+set(CPACK_PACKAGE_NAME "${PROJECT_NAME}")
+set(CPACK_PACKAGE_VENDOR "[email protected]")
+set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "C snippet library")
+set(CPACK_PACKAGE_VERSION_MAJOR ${PROJECT_VERSION_MAJOR})
+set(CPACK_PACKAGE_VERSION_MINOR ${PROJECT_VERSION_MINOR})
+set(CPACK_PACKAGE_VERSION_PATCH ${PROJECT_VERSION_PATCH})
+set(CPACK_PACKAGE_VERSION ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR})
+if(NOT DEFINED CPACK_SYSTEM_NAME)
+	set(CPACK_SYSTEM_NAME ${CMAKE_SYSTEM_NAME})
+endif()
+set(CPACK_SOURCE_IGNORE_FILES ${PROJECT_BINARY_DIR} .git .gitignore)
+set(CPACK_SOURCE_GENERATOR "TGZ")
+set(CPACK_GENERATOR "TGZ")
+
+include(CPack)

LICENSE

@@ -0,0 +1,20 @@
+Copyright 2018-2020 Lorenz Minder
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

doc/CMakeLists.txt

@@ -0,0 +1,47 @@
+function(get_target_sources retvar target_name)
+	get_target_property(src_files ${target_name} SOURCES)
+	get_target_property(src_dir ${target_name} SOURCE_DIR)
+	set(ret "")
+	foreach(src ${src_files})
+		list(APPEND ret ${src_dir}/${src})
+	endforeach()
+	set(${retvar} ${ret} PARENT_SCOPE)
+endfunction()
+
+function(add_docs_target)
+	if(NOT BUILD_DOCS)
+		return()
+	endif()
+	set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
+	set(DOXYGEN_MAX_INITIALIZER_LINES 3)
+	set(DOXYGEN_REPEAT_BRIEF NO)
+	set(DOXYGEN_EXAMPLE_PATH examples/)
+	set(DOXYGEN_QUIET YES)
+
+	# Get the sources from the csnip library
+	get_target_sources(src_csnip csnip)
+
+	# Figure out whether we can use a stamp file
+	set(use_stamp "")
+	if(CMAKE_MAJOR_VERSION GREATER 3 OR (CMAKE_MAJOR_VERSION GREATER_EQUAL 3
+	  AND CMAKE_MINOR_VERSION GREATER_EQUAL 16))
+		set(use_stamp "USE_STAMP_FILE")
+	endif()
+
+	doxygen_add_docs(docs
+		${src_csnip}
+		${CMAKE_CURRENT_SOURCE_DIR}/mainpage.md
+		ALL
+		${use_stamp}
+		WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
+	)
+endfunction()
+
+option(BUILD_DOCS "Build documentation" ON)
+add_docs_target()
+
+# Installation
+if (BUILD_DOCS)
+	install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
+		DESTINATION ${INSTALL_DOCDIR})
+endif ()

doc/mainpage.md

@@ -0,0 +1,87 @@
+# Introduction					{#mainpage}
+
+## What is Csnip?
+
+Csnip is a library of C code macros and functions (snippets, hence the
+name), that are frequently useful for general purpose C programming.
+It augments the standard C library with generic container data
+structures, such as dynamic arrays, lists, hash tables, and so on.  It
+also provides high quality implementations of frequently used
+functionality such as for example random number generation.
+
+In short, it provides functionality similar to C++'s standard template
+library for C programs.
+
+## Csnip design goals
+
+We strive to provide components that are:
+
+- **Quality**.  Csnip aims to provide higher quality algorithms and
+  datastructures than what you would typically get if you implemented
+  the same in an ad hoc fashion.
+
+- **Transparency**.  The implementation of csnip's datastructures is
+  documented in addition to the interfaces.  You may opt to modify them
+  directly; and in some cases this can come in handy, say, if you want
+  to do something that's not possible or easy with the official
+  interfaces.  For example, you can use direct access to sample a random
+  entry from a hash set, or can read data from a file into a dynamic
+  array that way.
+
+  In contrast, most other libraries are designed to be opaque, providing
+  _data abstraction_ as a means to compartmentalize funcionality.  In
+  csnip, the same can be achieved with CSNIP\_\*\_{DECL,DEF}\_FUNCS()
+  (see XXX), but it is entirely optional.  It can be used when it makes
+  sense, but avoided when it gets into the way.
+
+- **General**.  Csnip wants to be useful for as wide a class of users
+  and environments as possible.  A liberal license is used so it can be
+  used in as many contexts as possible.  We try to stay portable where
+  this is possible, but to provide the extras for environments that have
+  them.  Thus, e.g., type generic macros via \_Generic are used for C11
+  users along with non-generic versions for those which don't have that
+  functionality available.
+
+  Csnip is generic, thus e.g. the sorting functions do not depend on the
+  data type being sorted, or what type of random access container is
+  used to store the elements.
+
+  We aim to design the library in a way that they can also be useful in
+  uncommon use cases, provided that doesn't result in unduly burdening
+  typical use cases.  
+
+- **Pragmatic**.  Csnip strives to be pragmatic.  For example, we like
+  consistent interfaces, but if they get in the way of e.g. usability,
+  we'll do something else.  Csnip tries to be general in the definition
+  of its datastructures and function, but not to the point of making
+  them unnecessarily painful.
+
+## Library conventions
+
+### Notation
+
+Csnip uses the prefixes csnip\_ or CSNIP\_ for its symbols and macros.
+Users should not define their own symbols or macros with such names.
+
+Many functions or macros are grouped by functionality, e.g. things
+related to memory management are called csnip\_mem\_\*.  Though some very
+frequently used functionality that does not nicely fit into a group is
+directly under csnip\_\*, without further grouping.
+
+Macros that expand to statements or expression (_statement macros_ or
+_expression macros_) have upper CamelCase names; thus for example
+csnip\_arr\_Init() is a macro.  Unless the behavior of the macro is
+documented for the case when the argument has side effects, the user is
+expected to use arguments without side effects, since the arguments may
+be evaluated more than once.
+
+Macros and enumeration values that expand to constants are all-caps
+after the prefix, e.g. csnip\_err\_SUCCESS is such a constant.
+
+Macros that evaluate to more than an expression or a statement are
+written in all-caps.  Examples include macros that generate functions for
+container manipulation, such as CSNIP\_LPHASH\_TABLE\_DEF\_FUNCS().
+
+Normal C functions and variables are written in snake case, for example
+csnip\_time\_timespec\_as\_float() is a function.
+

examples/CMakeLists.txt

@@ -0,0 +1,23 @@
+set(samples_c
+	clopts.c
+	dlist.c
+	getopt.c
+	sort_cmdline.c
+)
+if (BUILD_CXX_PIECES)
+	set(samples_cxx
+		find.cc
+		sort_perf.cc
+	)
+else()
+	set(samples_cxx)
+endif()
+
+foreach(fn
+	${samples_c}
+	${samples_cxx}
+)
+	get_filename_component(tgt "${fn}" NAME_WE)
+	add_executable(${tgt} ${fn})
+	target_link_libraries(${tgt} csnip)
+endforeach()

examples/clopts.c

@@ -0,0 +1,37 @@
+#include <stdio.h>
+
+#define CSNIP_SHORT_NAMES
+#include <csnip/err.h>
+#include <csnip/clopts.h>
+
+int main(int argc, char** argv)
+{
+	clopts opts = {
+	  .description = "Testing tool for clopts library."
+	};
+	clopts_add_defaults(&opts);
+
+	/* Do the command line parsing */
+	int i = 0;
+	long l = 1;
+	unsigned long ul = 2;
+	const char* str = "unset";
+	_Bool flag = 0;
+	clopts_Addvar(&opts, 'i', "int", "int argument", &i, _);
+	clopts_Addvar(&opts, 'l', "long", "long int argument", &l, _);
+	clopts_Addvar(&opts, 'u', "ulong", "unsigned long argument", &ul, _);
+	clopts_Addvar(&opts, 's', "string", "string argument", &str, _);
+	clopts_Addflag(&opts, 'f', "flag", "flag", &flag, _);
+	int err = clopts_process(&opts, argc - 1, argv + 1, NULL);
+	if (err != 0) {
+		printf("Error from clopts_process: %s\n", err_str(err));
+		return 1;
+	}
+
+	/* Display result */
+	printf("Done with argument processing.\n");
+	printf("Got i = %d, l = %ld, ul = %lu, str = \"%s\", flag = %s\n",
+	  i, l, ul, str, (flag ? "true" : "false"));
+
+	return 0;
+}

examples/dlist.c

@@ -0,0 +1,40 @@
+#include <stdio.h>
+
+#define CSNIP_SHORT_NAMES
+#include <csnip/mem.h>
+#include <csnip/list.h>
+#include <csnip/util.h>
+
+struct Entry {
+	const char* name;
+	struct Entry *prev, *next;
+};
+
+int main(void)
+{
+	// Create an empty list:
+	struct Entry *head, *tail;
+	dlist_Init(head, tail, prev, next);
+
+	// Add some stuff to it
+	const char* names_to_add[] = {
+	  "John", "David", "Michael", "Scott"
+	};
+	for (int i = 0; i < Static_len(names_to_add); ++i) {
+		struct Entry* enew;
+		mem_Alloc(1, enew, _);
+		enew->name = names_to_add[i];
+
+		// Add the entry
+		dlist_PushTail(head, tail, prev, next, enew);
+	}
+
+	// Now read out backwards
+	struct Entry* p = tail;
+	while (p) {
+		printf("%s\n", p->name);
+		p = p->prev;
+	}
+
+	return 0;
+}

examples/find.cc

@@ -0,0 +1,28 @@
+#include <stdio.h>
+
+#define CSNIP_SHORT_NAMES
+#include <csnip/find.h>
+#include <csnip/util.h>
+
+int main()
+{
+	int a[] = {0, 1, 2, 3, 4};
+	const int N = Static_len(a);
+
+	/* Search with indices */
+	for (int i = -1; i < N + 2; ++i) {
+		int ret;
+		Bsearch(int, u, a[u] < i, N, ret);
+		printf("search for %d: index %d\n", i, (int)ret);
+	}
+
+	/* Search for intermediate values */
+	for (int i = -1; i < N + 1; ++i) {
+		const float target = i + 0.5;
+		int ret;
+		Bsearch(int, u, a[u] < target, N, ret);
+		printf("search for %g: index %d with value %d\n", target, ret,
+			ret < N ? a[ret] : -999);
+	}
+	return 0;
+}