native_btree 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4744529a22fe3d5cd3eb53cf258fa5440346df593e6d268d7af3d2e4b197addf
-  data.tar.gz: 887db38cf3c3c23cd72984f6ec2bbdfce1ebce57e547c5cc2d96c81184a36833
+  metadata.gz: 48b0e894826a65be636d9e13813c6d084c69a306d0778caf3fc709511dc5d2f5
+  data.tar.gz: 18f2f200813df0762181ebb4e7d3cc32c1cd8ae337ab9a35547d9265fa91eaeb
 SHA512:
-  metadata.gz: f46367c894c10a0ca5db645470228f08edafabe9010a5115d9c92008688eec29f9a0973ba462138483912a2bebe52660eb17828298ea69ebd1709d4811cfb470
-  data.tar.gz: 9a342ae22e6ced29b02aa24917f1307fc0a0721885667185266eaa1b23f73fd37c90918126dd1ac6aa24cee08a3c838c25a951e3a84ea5f23cb93e2532d9549d
+  metadata.gz: 4c574719cc0366f86f8459e5e17c59739dab7886ae2cfe56450ed8696906fe4c13be6e90265756a195d04548a627018540c8d119e143d19e0b5cab378c166448
+  data.tar.gz: 8239197687c68a713da92c7d108b41acfe83c30dcbee888e7363e0842b2f6bdc7af30e584e96a5438c08bb5bd306399f986cb31d0dad86d2cf17c9ee65820638

data/CHANGELOG.md

@@ -14,6 +14,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * #<
 * #<=
 
+## [0.6.1] - 2023-05-05
+
+### Added
+
+* api docs
+
 ## [0.6.0] - 2022-10-28
 
 ### Added

data/CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.5)
 
 project(ruby-native-btree
 	LANGUAGES C
-	VERSION 0.6.0)
+	VERSION 0.6.1)
 
 include(CheckSymbolExists)
 include(CheckCCompilerFlag)
@@ -22,7 +22,7 @@ if(HAVE_CC_MARCH_NATIVE)
 	string(APPEND CMAKE_C_FLAGS " -march=native")
 endif()
 
-set(CMAKE_C_FLAGS_DEBUG "-O0 -ggdb3 -Wall -Wextra -Wno-unused-parameter")
+set(CMAKE_C_FLAGS_DEBUG "-O0 -ggdb3 -Wall -Wextra -Wno-unused-parameter --coverage")
 set(CMAKE_C_FLAGS_RELEASE "-O3 -fomit-frame-pointer")
 
 # Force -fPIC

data/README.md

@@ -1,6 +1,7 @@
 # GLib Balanced binary tree (GTree) bindings for Ruby
 
 [![Ruby](https://github.com/unixs/ruby-native-btree/actions/workflows/main.yml/badge.svg)](https://github.com/unixs/ruby-native-btree/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/unixs/ruby-native-btree/branch/master/graph/badge.svg?token=10JIVX89NG)](https://codecov.io/gh/unixs/ruby-native-btree)
 [![Gem Version](https://badge.fury.io/rb/native_btree.svg)](https://badge.fury.io/rb/native_btree)
 [![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
 
@@ -87,38 +88,11 @@ tree.to_a
 #]
 ```
 
-## API ref
+## API
 
-You must provide your own comparator for keys in `new` class method block.
+* You must provide your own comparator for keys in `new` class method block.
+* You can mix in the `Enumerable` module if additional methods are needed.
 
 ### API methods
 
-In general this class behave same as Hash
-
-Implemented methods:
-
-* `[]= (alias: set)`
-* `[] (alias: get)`
-* `==`
-* `delete`
-* `size`
-* `height`
-* `each`
-* `include?`
-* `clear`
-* `to_h`
-* `to_a`
-* `to_proc`
-* `to_s`
-* `inspect`
-* `filter` (alias: select)
-* `filter!` (alias: select!)
-* `each_value`
-* `each_key`
-* `search_before` (GLib version >= 2.68) - Select keys <= first arg, ret new Btree
-* `search_after` (GLib version >= 2.68) - Select keys >= first arg, ret new Btree
-* `empty?`
-* `reverse_each`
-* `delete_if`
-
-You can mix in the `Enumerable` module if additional methods are needed.
+[YARD documentation](https://rubydoc.info/gems/native_btree)

data/Rakefile

@@ -37,7 +37,7 @@ namespace :cmake do
     sh "cmake --build #{BUILD_DIR}"
   end
 
-  desc "`Rebuild ext CMake project"
+  desc "Rebuild ext CMake project"
   task rebuild: %i[cmake:configure] do
     sh "cmake --build #{BUILD_DIR} --clean-first"
   end

data/ext/native_btree/constructor.c

@@ -27,6 +27,14 @@ init_rbtree(RBTree *rbtree, gushort flags)
   rbtree->flags = flags;
 }
 
+/**
+ * Constructor
+ *
+ * Accepts block as "comparator" function.
+ * This function will recive two keys for comparison.
+ *
+ * @return [Btree] new instance
+ */
 VALUE
 rbtree_initialize(int argc, VALUE* argv, VALUE self)
 {

data/ext/native_btree/conversion.c

@@ -26,7 +26,11 @@ rbtree_to_a_callback(gpointer key, gpointer value, gpointer data)
   return FALSE;
 }
 
-
+/**
+ * Converts tree to Hash
+ *
+ * @return [Hash] result
+ */
 VALUE
 rbtree_to_h(VALUE self)
 {
@@ -39,7 +43,13 @@ rbtree_to_h(VALUE self)
   return hash;
 }
 
-
+/**
+ * Converts tree to array
+ *
+ * Coverts tree to array of arrays with key and value
+ *
+ * @return [Array] result
+ */
 VALUE
 rbtree_to_a(VALUE self)
 {
@@ -70,14 +80,24 @@ to_proc_proc(RB_BLOCK_CALL_FUNC_ARGLIST(key, callback_arg))
   return value;
 }
 
-
+/**
+ * Returns a Proc object that maps a key to its value
+ *
+ * @return [Proc] block
+ */
 VALUE
 rbtree_to_proc(VALUE self)
 {
   return rb_proc_new(to_proc_proc, self);
 }
 
-
+/**
+ * Converts tree to string.
+ *
+ * Under hood will convert tree to Hash.
+ *
+ * @return [String] result
+ */
 VALUE
 rbtree_to_s(VALUE self)
 {

data/ext/native_btree/instance.c

@@ -110,7 +110,15 @@ legacy_rbtree_compare(const RBTree *a, const RBTree *b)
 
 #endif
 
-
+/**
+ * Adds key/value pair in to tree.
+ *
+ * Key/value will be replaced if key already exists.
+ *
+ * @param key [Object]
+ * @param value [Object]
+ * @return [Btree] self
+ */
 VALUE
 rbtree_set(VALUE self, VALUE key, VALUE value)
 {
@@ -121,7 +129,14 @@ rbtree_set(VALUE self, VALUE key, VALUE value)
   return self;
 }
 
-
+/**
+ * Gets value by key from tree.
+ *
+ * * Returns +nil+ if key does not exist.
+ *
+ * @param key [Object]
+ * @return [Object] result
+ */
 VALUE
 rbtree_get(VALUE self, VALUE key)
 {
@@ -138,7 +153,16 @@ rbtree_get(VALUE self, VALUE key)
   return result;
 }
 
-
+/**
+ * Deletes key/value pair from tree.
+ *
+ * * Returns value if key exists
+ * * Returns +nil+ if key does not exists
+ * * Returns result of block if block was given
+ *
+ * @param key [Object] Key
+ * @return [Object] result
+ */
 VALUE
 rbtree_delete(VALUE self, VALUE key)
 {
@@ -166,7 +190,11 @@ rbtree_delete(VALUE self, VALUE key)
   }
 }
 
-
+/**
+ * Returns tree height
+ *
+ * @return [Integer] maximum nodes in path from root to leaf
+ */
 VALUE
 rbtree_height(VALUE self)
 {
@@ -178,7 +206,11 @@ rbtree_height(VALUE self)
   return result;
 }
 
-
+/**
+ * Returns number of nodes
+ *
+ * @return [Integer] number of nodes
+ */
 VALUE
 rbtree_size(VALUE self)
 {
@@ -190,7 +222,11 @@ rbtree_size(VALUE self)
   return result;
 }
 
-
+/**
+ * Remove all nodes from tree.
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_clear(VALUE self)
 {
@@ -206,6 +242,12 @@ rbtree_clear(VALUE self)
 }
 
 
+/**
+ * Checks that the given key is in the tree.
+ *
+ * @param key [Object]
+ * @return [Boolean] result
+ */
 VALUE
 rbtree_is_include(VALUE self, VALUE key)
 {
@@ -220,7 +262,11 @@ rbtree_is_include(VALUE self, VALUE key)
   return Qtrue;
 }
 
-
+/**
+ * Checks that self tree is empty.
+ *
+ * @return [Boolean] result
+ */
 VALUE
 rbtree_is_empty(VALUE self)
 {
@@ -231,7 +277,18 @@ rbtree_is_empty(VALUE self)
   return size > 0 ? Qfalse : Qtrue;
 }
 
-
+/**
+ * Checks if two trees are equal.
+ *
+ * Compares with +==+ method all keys and values from trees by order.
+ *
+ * * Returns +false+ if number of keys are not equal.
+ * * Returns +false+ if one keys or one values pair are not equal.
+ * * Returns +true+ if all keys and values are equal.
+ *
+ * @param second [Btree]
+ * @return [Boolean] result
+ */
 VALUE
 rbtree_equal(VALUE self, VALUE second)
 {
@@ -266,7 +323,11 @@ rbtree_equal(VALUE self, VALUE second)
   return result;
 }
 
-
+/**
+ * Returns value from smallest key
+ *
+ * @return [Object] result
+ */
 VALUE
 rbtree_first(VALUE self)
 {
@@ -299,7 +360,11 @@ rbtree_first(VALUE self)
 #endif
 }
 
-
+/**
+ * Returns value from largest key
+ *
+ * @return [Object] result
+ */
 VALUE
 rbtree_last(VALUE self)
 {

data/ext/native_btree/iterators.c

@@ -48,7 +48,11 @@ rbtree_enum_length(VALUE rbtree, VALUE args, VALUE eobj)
   return rbtree_size(rbtree);
 }
 
-
+/**
+ * Execute block for each key/value pairs
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_each(VALUE self)
 {
@@ -63,7 +67,11 @@ rbtree_each(VALUE self)
   return self;
 }
 
-
+/**
+ * Execute block for each key
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_each_key(VALUE self)
 {
@@ -78,7 +86,11 @@ rbtree_each_key(VALUE self)
   return self;
 }
 
-
+/**
+ * Execute block for each value
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_each_value(VALUE self)
 {
@@ -93,7 +105,11 @@ rbtree_each_value(VALUE self)
   return self;
 }
 
-
+/**
+ * Execute block for each key/value pairs in reverse order
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_reverse_each(VALUE self)
 {
@@ -149,7 +165,14 @@ rbtree_delete_if_cb(gpointer k, gpointer v, gpointer data)
   return FALSE;
 }
 
-
+/**
+ * Deletes key/value pair from tree by result of block.
+ *
+ * Will execute block for each key/value pairs
+ * and delete them if block returns +true+
+ *
+ * @return [Btree] self
+ */
 VALUE
 rbtree_delete_if(VALUE self)
 {

data/ext/native_btree/native_btree.c

@@ -2,29 +2,25 @@
 #include <rbtree_type.h>
 #include <glib_module.h>
 
-#define NATIVE_BTREE_MODULE "NativeBtree"
-#define NATIVE_BTREE_CLASS "Btree"
-#define NATIVE_BTREE_CONST_INT_COMPARATOR "INT_COMPARATOR"
-
-
 VALUE native_btree_class;
 VALUE native_btree_module;
 
 void
 Init_native_btree()
 {
-  native_btree_module = rb_define_module(NATIVE_BTREE_MODULE);
-  native_btree_class = rb_define_class_under(
-    native_btree_module,
-    NATIVE_BTREE_CLASS,
-    rb_cObject
-  );
+  native_btree_module = rb_define_module("NativeBtree");
+  native_btree_class = rb_define_class_under(native_btree_module, "Btree", rb_cObject);
 
   VALUE int_comparator = USHORT2NUM(RBTREE_FLAG_INT_COMPARATOR);
   OBJ_FREEZE(int_comparator);
+
+  /**
+   * Represents native comparator for integer keys
+   * @note Can be replaced with specific class in future releases
+   */
   rb_define_const(
     native_btree_class,
-    NATIVE_BTREE_CONST_INT_COMPARATOR,
+    "INT_COMPARATOR",
     int_comparator
   );
 

data/ext/native_btree/search.c

@@ -43,6 +43,13 @@ filter_bang_callback(gpointer a, gpointer b, gpointer data)
   return FALSE;
 }
 
+/**
+ * Filters btree by block call
+ *
+ * If block returns true, key/value will include in result tree
+ *
+ * @return [Btree] result
+ */
 VALUE
 rbtree_filter(VALUE self)
 {
@@ -68,6 +75,13 @@ rbtree_filter(VALUE self)
   return new_tree;
 }
 
+/**
+ * Filters btree by block call
+ *
+ * Same as #filter but returns changed self.
+ *
+ * @return [Btree] result
+ */
 VALUE
 rbtree_filter_bang(VALUE self)
 {

data/lib/native_btree/btree.rb

@@ -0,0 +1,6 @@
+module NativeBtree
+  # Main Btree class
+  class Btree # rubocop:disable Lint/EmptyClass
+    # all methods defined in native module
+  end
+end

data/lib/native_btree/version.rb

@@ -1,3 +1,4 @@
 module NativeBtree
-  VERSION = "0.6.0".freeze
+  # gem version
+  VERSION = "0.6.1".freeze
 end

data/lib/native_btree.rb

@@ -1,4 +1,6 @@
-# Bindings to GLib-2.0 data structure BTree
+# Bindings to GLib-2.0 BTree data structure
+#
+# gem root namespace
 module NativeBtree
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: native_btree
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Alexander Feodorov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-27 00:00:00.000000000 Z
+date: 2023-05-05 00:00:00.000000000 Z
 dependencies: []
 description: Ruby bindings to GTree balanced binary tree from GLib library.
 email:
@@ -48,6 +48,7 @@ files:
 - ext/native_btree/search.c
 - ext/native_btree/utils.c
 - lib/native_btree.rb
+- lib/native_btree/btree.rb
 - lib/native_btree/native_btree.bundle
 - lib/native_btree/version.rb
 - native_btree.gemspec