carton_db 1.1.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce323ba4a0df06b409f1b35a150a9a638740e586
-  data.tar.gz: b2c95dca25fe7be9c0b7c8ff7ca2f8d3ea6e7ed0
+  metadata.gz: d16d6802fee28aa151d8eee4811d17d3a5dc00a5
+  data.tar.gz: 22cb133e4202c80ef89109a24163c41b666ec89c
 SHA512:
-  metadata.gz: ed9890e79acc8c72d7005834b9ed6f8fec56ab941d9c078957cb2fa84c5e82f486ea876d981af6850bd2835ea9fc58789194e0e061087054def1a2a35ab25fdb
-  data.tar.gz: 69de8aac4491cd13b67c3e2bb0a707961c8a359259278303a70e094c19fe7e60b3c5c3b2983f1b6268b74bc5045f762eeb7abb53b22e031049bfa6d2e962e06c
+  metadata.gz: 3ff1b4d0a6a5582d5903093e80051600e119f8c857b9ba32821081113b3cf90b3802c3f10f83a4fba0173b987ef55f699d3ae6289b1dfda47934b5105eb92b15
+  data.tar.gz: 04747d51836cc9864fc5e5245f884d42c585cb434ba7ce66441f19836c87d841ed74a60765d5b93a5767f13279ae93b3c81da2b59ec853fbda5082961841472e

data/.gitignore

@@ -3,6 +3,7 @@
 /Gemfile.lock
 /_yardoc/
 /coverage/
+/profiles/
 /doc/
 /pkg/
 /spec/reports/

data/README.md

@@ -4,7 +4,7 @@ A pure Ruby key/value data storage system where the values may
 consist of simple data structures.
 
 The primary goals of this library are simplicity of implementation
-and reliable, predicatble behavior when used as intended, along
+and reliable, predictable behavior when used as intended, along
 with documentation making it reasonably clear what is intended.
 
 ## Uses
@@ -53,11 +53,14 @@ filesystem containing the files that store the data.
 
 A database is accessed through an instance of a database class.
 
-An instance of a database class maintains no state in memory
+An instance of a database class maintains no internal state
 between calls to its methods except for the database name and the
 expectation of a directory with that name existing in the
 filesystem.
 
+Only instances of classes maintain any internal state. No global
+internal state is maintained.
+
 An empty directory is a valid empty database.
 
 Concurrent reads from a database are supported and safe.
@@ -68,24 +71,25 @@ attempting to do that are unpredictable.
 
 Initializing a new database class instance creates its directory
 in the filesystem if it does not already exist. The parent of the
-database directory is expected to already  exist, and an
-exception will be raised if it doesn't.
+database directory is expected to already exist, and an exception
+will be raised if it doesn't.
 
 The database structure is designed to effectively handle up to
-several million elements with entries containing up to 1 or 2
-thousand elements each.
+several million elements with any entry containing up to around
+50 thousand characters (elements ⨉ chars in an entry's content).
 
-The speed of database operations is relatively good, but this is
-not a high performance database management system. See the
-code documentation in the classes for more details about the
-performance of particular database operations.
+The speed of database operations is good, but this is not a high
+performance database management system. See the code
+documentation in the classes for more details about the
+performance of each kind of database operation.
 
 ## Usage
 
-Currently, this gem includes only one kind of database, which is
-implemented by the `CartonDB::ListMapDb` class. It is a map of
-lists where each entry has a string for a key and a list of of 0
-or more string elements as content.
+The primary kind of database provided by this gem is the one
+implemented by `CartonDB::ListMapDb`. It is a map of lists where
+each entry has a string for a key and a list of of 0 or more
+string elements as content. Other kinds of database are
+implemented on top of that and share the same storage format.
 
 The name of the database is the path of a directory in the
 filesystem that either already exists or shall be created as

data/carton_db.gemspec

@@ -14,6 +14,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/stevecj/carton_db.rb"
   spec.license       = "MIT"
 
+  spec.required_ruby_version = '>= 2.3.0'
+
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
@@ -24,4 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.14"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-prof", "~> 0.0"
 end

data/lib/carton_db/list_map_db/segment.rb

@@ -71,6 +71,18 @@ module CartonDb
         end
       end
 
+      def each_first_element
+        first_entries = nil
+        each_entry_element_line do |key_d, elem_d, _line|
+          first_entries ||= {}
+          first_entries[key_d] ||= elem_d.plain
+        end
+        return unless first_entries
+        first_entries.each do |key_d, element|
+          yield key_d.plain, element
+        end
+      end
+
       def each_entry_element_line
         return if empty?
         each_line do |line|

data/lib/carton_db/list_map_db.rb

@@ -6,7 +6,7 @@ require 'carton_db/list_map_db/segment_group'
 
 module CartonDb
 
-  # A map with string keys lists of strings as contents.
+  # A map with strings as keys and lists of strings as contents.
   #
   # This is suitable for storing a total number of elements as
   # large as the low millions, with each entry containing a
@@ -215,6 +215,23 @@ module CartonDb
       end
     end
 
+    # For each entry in the database, yields the first element
+    # in the entry's content or nil if the content is an empty
+    # list.
+    #
+    # Performance is pretty much identical to that of #each.
+    #
+    # @yieldparam key [String] The key of the entry.
+    # @yeildparam array [String, nil] The first element of the
+    #   entry's content.
+    def each_first_element
+      ListMapDb::Segment.each_in_db name do |segment|
+        segment.each_first_element do |key, element|
+          yield key, element
+        end
+      end
+    end
+
     # Removes an entry from the database. Has no effect if the
     # entry already does not exist.
     #
@@ -322,9 +339,13 @@ module CartonDb
     # necessary so the content has an element corresponding to
     # each of the given elements.
     #
+    # Performance is similar to #[] when no new elements need to
+    # be added and similar to #[] followed by #concat_elements
+    # when one or more new elements needs to be added.
+    #
     # @param key [String] The key identifying the entry.
     # @param elements [Array<String>] An array or other
-    #   enumerable collection of elements to appended as
+    #   enumerable collection of elements to be appended as
     #   applicable.
     def merge_elements(key, elements)
       key_d = CartonDb::Datum.for_plain(key)

data/lib/carton_db/set_map_db.rb

@@ -0,0 +1,111 @@
+require 'set'
+require 'forwardable'
+
+module CartonDb
+
+  class SetMapDb
+    extend Forwardable
+
+    def initialize(name)
+      self.list_map_db = CartonDb::ListMapDb.new(name)
+    end
+
+    # Creates a new entry or replaces the contents of the
+    # existing entry identified by the given key.
+    #
+    # The is a fairly fast operation, but can be somewhat
+    # slower in a large database.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param content [Set<String>] A set or other enumerable
+    #   collection of 0 or more list element string values to be
+    #   stored.
+    def []=(key, content)
+      content = Set.new(content) unless content.is_a?(Set)
+      list_map_db[key] = content
+    end
+
+    # Returns the content of the entry identified by the given
+    # key or nil if no such entry exists.
+    #
+    # This operation is fast, but may be slower for a larger
+    # database.
+    #
+    # @param key [String] The key identifying the entry.
+    # @return [Set<String>] if a matching entry exists.
+    # @return [nil] if no matching entry exists.
+    def [](key)
+      list = list_map_db[key]
+      list && Set.new(list)
+    end
+
+    # See CartonDb::ListMapDb#empty?
+    def_delegator :list_map_db, :empty?
+
+    # see cartondb::listmapdb#count
+    def_delegator :list_map_db, :count
+
+    # See CartonDb::ListMapDb#Key?
+    def_delegator :list_map_db, :key?
+
+    # See CartonDb::ListMapDb#touch_element
+    def_delegator :list_map_db, :touch_element
+
+    # See CartonDb::ListMapDb#delete
+    def_delegator :list_map_db, :delete
+
+    # Creates an entry with an empty set as its content if no
+    # entry exists for the given key. Has no effect on the content
+    # of the entry if it already exists.
+    #
+    # See the documentation for CartonDb::ListMapDb#touch for
+    # performance characteristics.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param optimization[:small, :fast] The optimization mode.
+    def_delegator :list_map_db, :touch
+
+    # See CartonDb::ListMapDb#clear
+    def_delegator :list_map_db, :clear
+
+    # Performs a set-wise merge of the given elements with the
+    # content of an entry. Adds whatever elements are necessary
+    # so the content has an element corresponding to unique
+    # given element.
+    #
+    # See the documentation for
+    # CartonDb::ListMapDb#merge_elements for performance
+    # characteristics.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param elements [Set<String>] A set or other enumerable
+    #   collection of elements to be added as applicable.
+    def merge_elements(key, elements)
+      elements = Set.new(content) unless elements.is_a?(Set)
+      list_map_db.merge_elements key, elements
+    end
+
+    # See CartonDb::ListMapDb#element?
+    def_delegator :list_map_db, :element?
+
+    # Yields each entry in the database as a key/array pair.
+    #
+    # See the documentation for CartonDb::ListMapDb#each for
+    # performance characteristics.
+    #
+    # @yieldparam key [String] The key of the entry.
+    # @yeildparam array [Array<String>] The elements of the list
+    #   entry's content.
+    def each
+      list_map_db.each do |key, list|
+        yield key, Set.new(list)
+      end
+    end
+
+    private
+
+    attr_accessor :list_map_db
+
+  end
+
+end

data/lib/carton_db/simple_map_db.rb

@@ -0,0 +1,102 @@
+require 'forwardable'
+
+module CartonDb
+
+  # A map with strings as keys and values that can each be either
+  # a string or nil.
+  #
+  # Data storage is in the same form as ListMapDb, but string
+  # values are stored as single-element lists and nil values are
+  # stored as empty lists. Only the first element in an entry's
+  # content is significant when retrieving a value from a
+  # multi-element underlying entry.
+  #
+  # See the documentation for CartonDb::ListMapDb for additional
+  # details.
+  class SimpleMapDb
+    extend Forwardable
+    include Enumerable
+
+    # Initializes an instance that interacts with the database
+    # identified by the given name, which is the full path to a
+    # directory in the filesystem.
+    #
+    # See the documentation for CartonDb::ListMapDb#initialize
+    # for additional details.
+    #
+    # @param name [String] The full path of the directory in the
+    #   filesystem in which the data is stored or will be stored.
+    def initialize(name)
+      self.list_map_db = CartonDb::ListMapDb.new(name)
+    end
+
+    # Creates a new entry or replaces the contents of the
+    # existing entry identified by the given key.
+    #
+    # See the documentation for CartonDb::ListMapDb#initialize
+    # for performance characteristics.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param value [String, nil] The value to be stored.
+    def []=(key, value)
+      content = value.nil? ? [] : [value.to_s]
+      list_map_db[key] = content
+    end
+
+    # Returns the content of the entry identified by the given
+    # key or nil if no such entry exists.
+    #
+    # See the documentation for CartonDb::ListMapDb#initialize
+    # for performance characteristics.
+    #
+    # @param key [String] The key identifying the entry.
+    # @return [String, nil] if a matching entry exists.
+    # @return [nil] if no matching entry exists.
+    def [](key)
+      content = list_map_db[key]
+      content&.first
+    end
+
+    # See CartonDb::ListMapDb#empty?
+    def_delegator :list_map_db, :empty?
+
+    # see cartondb::listmapdb#count
+    def_delegator :list_map_db, :count
+
+    # See CartonDb::ListMapDb#Key?
+    def_delegator :list_map_db, :key?
+
+    # See CartonDb::ListMapDb#delete
+    def_delegator :list_map_db, :delete
+
+    # Creates an entry with a nil value if no entry exists for
+    # the given key. Has no effect on the value of the entry if
+    # it already exists.
+    #
+    # See the documentation for CartonDb::ListMapDb#touch for
+    # performance characteristics.
+    #
+    # @param key [String] The key identifying the entry.
+    # @param optimization[:small, :fast] The optimization mode.
+    def_delegator :list_map_db, :touch
+
+    # See CartonDb::ListMapDb#clear
+    def_delegator :list_map_db, :clear
+
+    # Yields each entry in the database as a key/value pair.
+    #
+    # See the documentation for CartonDb::ListMapDb#yield for
+    # performance characteristics.
+    #
+    # @yieldparam key [String] The key of the entry.
+    # @yeildparam array [Array<String>] The elements of the list
+    #   entry's content.
+    def_delegator :list_map_db, :each_first_element, :each
+
+    private
+
+    attr_accessor :list_map_db
+
+  end
+
+end

data/lib/carton_db/version.rb

@@ -1,4 +1,4 @@
 # -*- coding: UTF-8 -*-
 module CartonDb
-  VERSION = "1.1.1"
+  VERSION = "1.1.2"
 end

data/lib/carton_db.rb

@@ -3,6 +3,8 @@ require "carton_db/version"
 require "carton_db/escaping"
 require "carton_db/datum"
 require "carton_db/list_map_db"
+require "carton_db/simple_map_db"
+require "carton_db/set_map_db"
 
 module CartonDb
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carton_db
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Steve Jorgensen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-05-06 00:00:00.000000000 Z
+date: 2017-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-prof
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 description: 
 email:
 - stevej@stevej.name
@@ -76,6 +90,8 @@ files:
 - lib/carton_db/list_map_db.rb
 - lib/carton_db/list_map_db/segment.rb
 - lib/carton_db/list_map_db/segment_group.rb
+- lib/carton_db/set_map_db.rb
+- lib/carton_db/simple_map_db.rb
 - lib/carton_db/version.rb
 - tmp/.gitkeep
 homepage: https://github.com/stevecj/carton_db.rb
@@ -90,7 +106,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="