0.10.0

Author: vaind

CHANGELOG.md

@@ -1,3 +1,72 @@
+ObjectBox C and C++ API Changelog
+=================================
+
+0.10.0 (2020-08-13)
+------------------
+C++ API queries and model classes for more feature-rich generated code.
+C-API cleanup & docs updates, including the following changes (some of them breaking due to renames):
+
+##### Misc
+* new property type: DateNano for datetime with nanosecond precision
+* new store options obx_opt_*()
+  * validate_on_open - to validate the database during openining
+  * put_padding_mode - configure the padding used by your flatbuffers implementation
+  * use_previous_commit - roll-back the database to the previously committed version
+  * read_only - open the database in the read only mode
+  * debug_flags - configure debug logging
+
+##### Cursor
+* remove obx_cursor2(), use obx_cursor() in combination with obx_store_entity_id()
+* rename obx_cursor_put_mode() to obx_cursor_put4()
+* obx_cursor_put() drops the last parameter `checkForPreviousValue` and introduced a complementary obx_cursor_put_new()
+* remove obx_cursor_put_padded()
+* rename obx_cursor_backlink_bytes() to obx_cursor_backlinks()
+* rename obx_cursor_ts_limits() to obx_cursor_ts_min_max()
+* rename obx_cursor_ts_limits_range() to obx_cursor_ts_min_max_range()
+  
+##### Box  
+* rename obx_box_put() to obx_box_put5()
+* rename obx_box_put_object() to obx_box_put_object4()
+* change obx_box_put_many to fail when any of the individual inserts/updates fails and new obx_box_put_many5() to override this behavior
+* new obx_box_store() to get access to OBX_store* owning the given box
+* new obx_box_insert() obx_box_update() for for insert and update semantics, same as put mode arg in obx_box_put5()
+* new obx_box_put() without a mode argument (defaults to PUT) 
+* new obx_box_put_object() without a mode argument (defaults to PUT) 
+* new obx_box_ts_min_max() for time-series databases
+* new obx_box_ts_min_max_range() for time-series databases
+
+##### Async
+* rename obx_async_put_mode() to obx_async_put5()
+* rename obx_async_id_put() to obx_async_put_object()
+* rename obx_async_id_insert() to obx_async_insert_object()
+
+##### Query builder
+* obx_qb_{type}_{operation}() function naming changes to obx_qb_{operation}_{type}(), e.g. obx_qb_int_equal() becomes obx_qb_equals_int()
+* obx_qb_{operation}_{type}() functions taking multiple arguments have an "s" at the end, indicating plural, e.g. obx_qb_in_int64s()
+* operation `equal` becomes `equals`, `greater` becomes `greater_than`, `less` becomes `less_than` 
+* obx_qb_greater_than_string() drops `with_equal` argument in favor of the new obx_qb_greater_or_equal_string() function
+* obx_qb_less_than_string() drops `with_equal` argument in favor of the new obx_qb_less_or_equal_string() function
+* change obx_qb_in_strings() argument `const char* values[]` changes to `const char* const values[]`, 
+  i.e. const array of const char pointers
+* obx_qb_greater_than_bytes() drops `with_equal` argument in favor of the new obx_qb_greater_or_equal_bytes() function
+* obx_qb_less_than_bytes() drops `with_equal` argument in favor of the new obx_qb_less_or_equal_bytes() function
+
+##### Query
+Limit and offset are now part of the query state instead of function arguments, therefore:
+* new obx_query_offset() and obx_query_limit() set persistent offset/limit for all future calls to other query functions
+* obx_query_find(), obx_query_visit(), obx_query_find_ids(), as well as the cursor alternatives, 
+  all drop `offset` and `limit` arguments
+* note: some query functions, such as count/remove don't support non-zero offset/limit yet.
+* obx_query_{type}_param() function naming changes to obx_query_param_{type}(), e.g. obx_query_string_param() 
+  becomes obx_query_param_string() or obx_query_param_strings() for the plural variant 
+* obx_query_{type}_param_alias() function naming changes to obx_query_param_alias_{type}(), e.g. obx_query_string_param_alias() 
+  becomes obx_query_param_alias_string()
+* obx_query_param_strings() and obx_query_param_alias_strings() argument `const char* values[]`  
+  changes to `const char* const values[]`, i.e. const array of const char pointers
+* obx_query_prop_{type}_find() function naming changes to obx_query_prop_find_{type}s(), with an "s" indicating the return 
+  type is plural, e.g. obx_query_prop_find_strings
+* remove deprecated obx_query_prop_distinct_string()
+
 0.9.2 (2020-06-30)
 ------------------
 * Rename obx_cursor_ts_limits() to obx_cursor_ts_min_max()

README.md

@@ -3,17 +3,18 @@ ObjectBox C and C++ APIs
 [ObjectBox](https://objectbox.io) is a superfast database for objects.
 This is the **ObjectBox runtime library** to run ObjectBox as an embedded database in your C or C++ application.
 
-**Latest version: 0.9.2** (2020-06-30). See [changelog](CHANGELOG.md) for more details. 
+**Latest version: 0.10.0** (2020-08-13). See [changelog](CHANGELOG.md) for more details. 
 
-In most cases you want to use the C and C++ APIs in combination with the **companion project [ObjectBox Generator](https://github.com/objectbox/objectbox-generator)**.
-Like this, you get a convenient API which requires minimal code on your side to work with the database.
+In most cases you want to use the C and C++ APIs in combination with the **[ObjectBox Generator](https://github.com/objectbox/objectbox-generator) tool**.
+This way, you get a convenient C or C++ API which requires minimal code on your side to work with the database.
 
 Here's a C++ code example that inserts a `Task` data object into the database: 
+```c++
+obx::Box<Task> box(store);
+box.put({.text = "Buy milk"}); 
+```
 
-    obx::Box<Task> box(store);
-    box.put({.text = "Buy milk"}); 
-    
-Note: `Task` is a `struct` representing a user defined data model - see [ObjectBox Generator](https://github.com/objectbox/objectbox-generator) for details.  
+Note: `Task` is a `struct` representing a user defined data model - see [ObjectBox C and C++ docs](https://cpp.objectbox.io/) for details.  
 
 Some features
 -------------
@@ -38,45 +39,35 @@ The APIs come as single header file for C and C++:
   * C++: [include/objectbox-cpp.h](include/objectbox-cpp.h) (depends on objectbox.h)
   
 Compile your code against it and use the binary library (.so, .dylib, .dll depending on the platform) to link against.
-  
-There are a couple of ways to get the library:
-
-* Using the download.sh script (on Windows, use something like Git Bash to run it)
-    * Either clone the repo and run `./download.sh`
-    * ... or download [download.sh](download.sh) and run it in a terminal:<br> 
-      `wget https://raw.githubusercontent.com/objectbox/objectbox-c/master/download.sh`<br>
-      `chmod +x download.sh`<br>
-      `./download.sh`
-* Conan (wip, details coming later): https://bintray.com/objectbox/conan/objectbox-c%3Aobjectbox
-
-Details on the download.sh script:
-
-* It creates a "download" directory and a version dependent sub directory named like "libobjectbox-0.1-some-hex-hash"
-* Inside the version dependent sub directory, you will find the directories "include" and "lib"
-* The "lib" directory contains the binary library
-* On systems supporting 'sudo', the download.sh script also asks you to install the library in /usr/local/lib.
+Head over to [ObjectBox C and C++ installation docs](https://cpp.objectbox.io/installation) for step-by-step instructions.
 
 C++ API
 -------
 The C++ API is built on top of the C API exposed by the library (e.g. you still need objectbox.h).
-You can also use both APIs from your code if need be.
+You can also use both APIs from your code if necessary.
 For example, you use the C++ `obx::Box` class for most database operations, but "break out" into the C API for a special function you need.  
 Note that to use the `obx::Box` class, you also need the [ObjectBox Generator](https://github.com/objectbox/objectbox-generator) to generate binding code.
-In short, it generates "boiler plate" source code and maintains some metadata around the data model.
+Find more details how to use it the [Getting started](https://cpp.objectbox.io/getting-started) section of the docs.
+
+Examples
+--------
+Have a look at the following TaskList example apps, depending on your programming language and preference:
 
-Examples & API Documentation
-----------------------------
-Documentation is still on-going work.
-For now, please refer to the [ObjectBox Generator](https://github.com/objectbox/objectbox-generator) for more details.
+* [C, cursor, no generated code](examples/c-cursor-no-gen) - plain C; using flatcc directly; without any generated code
+* [C, with generated code](examples/cpp-gen) - plain C, using code generated by `objectbox-generator` 
+* [C++, with generated code](examples/cpp-gen) - C++, using code generated by `objectbox-generator` 
 
-For an API reference check one of those:
 
-* [include/objectbox.h](include/objectbox.h): single header file 
-* [API reference docs](https://objectbox.io/docfiles/c/current/): online HTML docs (Doxygen) 
+Documentation
+-------------
+* [C and C++ docs](https://cpp.objectbox.io/) - official ObjectBox C and C++ documentation 
+* [include/objectbox.h](include/objectbox.h) - C-API header file contains docs in as code comments 
+* [include/objectbox-cpp.h](include/objectbox-cpp.h) - C-API header file contains docs in as code comments 
+* [C and C++ API reference docs](https://objectbox.io/docfiles/c/current/) - online HTML docs (Doxygen) 
 
 Current state / Changelog
 -------------------------
-The C API is a thin wrapper around a robust DB core, which is version 2.x and already used on million of devices.
+The C API is a thin wrapper around a robust DB core, which is version 2.x and already used on millions of devices.
 
 **Beta notice:** the C API will become stable starting from version 1.0.
 Until then, API improvements may result in breaking changes. For example, functions may still be renamed.
@@ -88,7 +79,7 @@ C API as the Foundation for Higher Languages
 --------------------------------------------
 The plain C API (without the Generator) also serves as a basis for ObjectBox bindings in higher languages.
 For example, the official APIs for [Go](https://github.com/objectbox/objectbox-go), [Swift](https://github.com/objectbox/objectbox-swift), [Dart/Flutter](https://github.com/objectbox/objectbox-dart) and [Python](https://github.com/objectbox/objectbox-python) rely on the C API.
-In the same way, you could create a ObjectBox API for another programming language, e.g. for JavaScript.
+In the same way, you could create an ObjectBox API for another programming language, e.g. for JavaScript.
 For the C API, data consists of bytes representing FlatBuffers tables, which you can build and read in your language of choice.
 
 License

download.sh

@@ -39,7 +39,7 @@ tty -s || quiet=true
 
 # Note: optional arguments like "--quiet" shifts argument positions in the case block above
 
-version=${1:-0.9.2}
+version=${1:-0.10.0}
 repoType=${2:-testing}
 os=${3:-$(uname)}
 arch=${4:-$(uname -m)}

doxygen/Changelog.md

@@ -1,7 +1,73 @@
 [TOC]
 
-ObjectBox C API Changelog
-=========================
+ObjectBox C and C++ API Changelog
+=================================
+
+0.10.0 (2020-08-13)
+------------------
+C++ API queries and model classes for more feature-rich generated code.
+C-API cleanup & docs updates, including the following changes (some of them breaking due to renames):
+
+##### Misc
+* new property type: DateNano for datetime with nanosecond precision
+* new store options obx_opt_*()
+  * validate_on_open - to validate the database during openining
+  * put_padding_mode - configure the padding used by your flatbuffers implementation
+  * use_previous_commit - roll-back the database to the previously committed version
+  * read_only - open the database in the read only mode
+  * debug_flags - configure debug logging
+
+##### Cursor
+* remove obx_cursor2(), use obx_cursor() in combination with obx_store_entity_id()
+* rename obx_cursor_put_mode() to obx_cursor_put4()
+* obx_cursor_put() drops the last parameter `checkForPreviousValue` and introduced a complementary obx_cursor_put_new()
+* remove obx_cursor_put_padded()
+* rename obx_cursor_backlink_bytes() to obx_cursor_backlinks()
+* rename obx_cursor_ts_limits() to obx_cursor_ts_min_max()
+* rename obx_cursor_ts_limits_range() to obx_cursor_ts_min_max_range()
+  
+##### Box  
+* rename obx_box_put() to obx_box_put5()
+* rename obx_box_put_object() to obx_box_put_object4()
+* change obx_box_put_many to fail when any of the individual inserts/updates fails and new obx_box_put_many5() to override this behavior
+* new obx_box_store() to get access to OBX_store* owning the given box
+* new obx_box_insert() obx_box_update() for for insert and update semantics, same as put mode arg in obx_box_put5()
+* new obx_box_put() without a mode argument (defaults to PUT) 
+* new obx_box_put_object() without a mode argument (defaults to PUT) 
+* new obx_box_ts_min_max() for time-series databases
+* new obx_box_ts_min_max_range() for time-series databases
+
+##### Async
+* rename obx_async_put_mode() to obx_async_put5()
+* rename obx_async_id_put() to obx_async_put_object()
+* rename obx_async_id_insert() to obx_async_insert_object()
+
+##### Query builder
+* obx_qb_{type}_{operation}() function naming changes to obx_qb_{operation}_{type}(), e.g. obx_qb_int_equal() becomes obx_qb_equals_int()
+* obx_qb_{operation}_{type}() functions taking multiple arguments have an "s" at the end, indicating plural, e.g. obx_qb_in_int64s()
+* operation `equal` becomes `equals`, `greater` becomes `greater_than`, `less` becomes `less_than` 
+* obx_qb_greater_than_string() drops `with_equal` argument in favor of the new obx_qb_greater_or_equal_string() function
+* obx_qb_less_than_string() drops `with_equal` argument in favor of the new obx_qb_less_or_equal_string() function
+* change obx_qb_in_strings() argument `const char* values[]` changes to `const char* const values[]`, 
+  i.e. const array of const char pointers
+* obx_qb_greater_than_bytes() drops `with_equal` argument in favor of the new obx_qb_greater_or_equal_bytes() function
+* obx_qb_less_than_bytes() drops `with_equal` argument in favor of the new obx_qb_less_or_equal_bytes() function
+
+##### Query
+Limit and offset are now part of the query state instead of function arguments, therefore:
+* new obx_query_offset() and obx_query_limit() set persistent offset/limit for all future calls to other query functions
+* obx_query_find(), obx_query_visit(), obx_query_find_ids(), as well as the cursor alternatives, 
+  all drop `offset` and `limit` arguments
+* note: some query functions, such as count/remove don't support non-zero offset/limit yet.
+* obx_query_{type}_param() function naming changes to obx_query_param_{type}(), e.g. obx_query_string_param() 
+  becomes obx_query_param_string() or obx_query_param_strings() for the plural variant 
+* obx_query_{type}_param_alias() function naming changes to obx_query_param_alias_{type}(), e.g. obx_query_string_param_alias() 
+  becomes obx_query_param_alias_string()
+* obx_query_param_strings() and obx_query_param_alias_strings() argument `const char* values[]`  
+  changes to `const char* const values[]`, i.e. const array of const char pointers
+* obx_query_prop_{type}_find() function naming changes to obx_query_prop_find_{type}s(), with an "s" indicating the return 
+  type is plural, e.g. obx_query_prop_find_strings
+* remove deprecated obx_query_prop_distinct_string()
 
 0.9.2 (2020-06-30)
 ------------------

doxygen/Doxyfile

@@ -32,13 +32,13 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "ObjectBox C API"
+PROJECT_NAME           = "ObjectBox C and C++ API"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.9.2"
+PROJECT_NUMBER         = "0.10.0"
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -790,7 +790,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include/objectbox.h
+INPUT                  = ../include
 INPUT                  += main-page.md
 # Doxygen seems buggy with our standard CHANGELOG.md: it does not show headers.
 # To work-around those problems, we have a special version for Doxygen:

doxygen/main-page.md

@@ -6,13 +6,12 @@ Introduction
 
 Installation and examples
 ------------------------- 
-Check the [ObjectBox C repository](https://github.com/objectbox/objectbox-c) for additional info and examples including the usage of flatcc.
+See [Installation docs](https://cpp.objectbox.io/installation) and check the [project's GitHub repository](https://github.com/objectbox/objectbox-c) for additional info and examples including the usage of flatcc.
 
-Single header
+Headers
 -------------
-The entire ObjectBox C API is defined in a single header file:
-
-**objectbox.h**
+* ObjectBox C99 support is provided by a single header file: **objectbox.h**
+* ObjectBox C++11 support is available in an additional header: **objectbox-cpp.h**
 
 Basic concepts
 --------------
@@ -22,22 +21,26 @@ Basic concepts
 * Objects are addressed using a 64 bit integer ID (`obx_id`)
 * There is no query language; queries are build using a [query builder](\ref OBX_query_builder)
 
+See [docs](https://cpp.objectbox.io) for more information on how to use ObjectBox in C and C++
+
 API Naming conventions
 ----------------------
-* methods: obx_thing_action()
-* structs: OBX_thing {}
-* error codes: OBX_ERROR_REASON
+* C methods: obx_thing_action()
+* C structs: OBX_thing {}
+* C error codes: OBX_ERROR_REASON
+* C++ namespace: obx::
 
 Essential types
 -----------------
 Check the docs for the following types:
 
-* [OBX_store](\ref OBX_store): the "database"; "opens" data files in a given directory
-* [OBX_box](\ref OBX_box): object operations like put and get  
-* [OBX_query_builder](\ref OBX_query_builder): used to construct queries using "query conditions"  
-* [OBX_query](\ref OBX_query): the product of a query builder can be executed to find objects matching the previously defined conditions  
+* [OBX_store](\ref OBX_store) and [obx::Store](\ref obx::Store): the "database"; "opens" data files in a given directory
+* [OBX_box](\ref OBX_box) and [obx::Box](\ref obx::Box): object operations like put and get  
+* [OBX_query_builder](\ref OBX_query_builder) and [obx::QueryBuilder](\ref obx::QueryBuilder): used to construct queries using "query conditions"  
+* [OBX_query](\ref OBX_query) and [obx::Query](\ref obx::Query): the product of a query builder can be executed to find objects matching the previously defined conditions  
 
 Essential Links/Readings
 ------------------------
+* High-level docs and examples: https://cpp.objectbox.io
 * Entity (object) IDs: https://docs.objectbox.io/advanced/object-ids
 * Meta model and UIDs: https://docs.objectbox.io/advanced/meta-model-ids-and-uids

examples/CMakeLists.txt

@@ -1 +1,3 @@
-add_subdirectory(tasks)
+add_subdirectory(c-cursor-no-gen)
+add_subdirectory(c-gen)
+add_subdirectory(cpp-gen)