Recent changes to Home

Home modified by hpg

hpg — Wed, 23 Dec 2015 13:19:44 -0000

--- v2
+++ v3
@@ -1,4 +1,4 @@
-# Common DataItem library (dtitem-library)
+## Common DataItem library (dtitem-library)

 [TOC]

@@ -7,7 +7,7 @@

 I will change this in the next time and move this page downwards to a new sub page.

-## Getting started
+### Getting started
 The library contains a C++ class that can be used instead of any other type of
 variant classes or structures.

@@ -20,16 +20,16 @@
 *  uses `std::shared_ptr` and does not copy values but rather add references to objects
 *  makes use of come C++11 features like supporting a move copy c'tor and assignment operator 

-## Restrictions / Limitations
+### Restrictions / Limitations
 * Only tested with MSVC 10 yet
 * Requires C++11 or better 

-## What's coming next?
+### What's coming next?
 * Better documentation and better english.
 * A serialization format to read and store data item objects
 * Better change notification with details like what has been changed

-## Building the Library
+### Building the Library
 To build the library you will need at least MSVC 10 or better (express version should do).

 Other compilers may work, but I didn't test them yet.
@@ -63,29 +63,108 @@
 ~~~~

 `DoRef` objects may be used to assign another `dtitem` object or can be added to a child list of a `dtitem`
-without any concerns about freeing up something. This is done by `DoRef`automatically.
-
+without any concerns about freeing up something. This is done by `DoRef` automatically.
+
+## Samples
+Here are some sample C++ sources, just for given a first impression about the functions.
+
+Refer for details to the complete doxygen documentation as provided.

 ### DoRef and exception handling
 Whenever dealing with `DoRef` (or `dtitem`) classes you should consider to 
 handle `std::exception` throwings.

-@include sample-doref-exceptions.cpp
+~~~~ (cpp)
+void test()
+{
+    DoRef r;
+    
+    // this line will throw a dt::ex_unreferenced() exception rather
+    // than an access violation what would be the result when using 
+    // shared_ptr and not DoRef classes
+    std::cout << r->name() << std::endl; 
+}
+~~~~

 A better handling would be:

-@include sample-doref-exception-handling.cpp
+~~~~ (cpp)
+void test()
+{
+    DoRef r;
+    
+    try {    
+        // this line will throw a dt::ex_unreferenced() exception
+        std::cout << r->name() << std::endl; 
+    }
+    catch (const std::exception& ex) 
+    {
+        std::cerr << "exception caught: " << ex.what() << std::endl;
+    }
+}
+~~~~
+---------
+
+

 ### Creating a DoRef object
 Creating an object is safe when you create it "embedded" in a `DoRef` like:

-@include sample-doref-creation.cpp
+~~~~ (cpp)
+void test()
+{
+    DoRef r;
+    
+    // the created object is "embedded" into the r object and
+    // destroyed when r is going out-of-scope 
+    //i.e. leaving the test() function.
+    r = new dt::dtstruct("hello world");
+    
+    std::cout << "created a struct with name = "
+              << r->name() << std::endl; 
+              
+    // r will destruct the child object automatically
+}
+
+~~~~
+--------

 ### Removing a DoRef object explicitely
 If you want to destruct a `DoRef` explicitely, you can remove it from a 
 parent object's child list by:

-@include sample-doref-remove.cpp
+~~~~ (cpp)
+void test()
+{
+    DoRef r;
+    
+    // create the parent object 
+    r = new dt::dtstruct("hello");
+    
+    { // extra scope for adding a new item
+        // create a new string type dtitem and add it to 'r'
+        DoRef childRef(new dtstring("world"));
+        r->add(childRef);
+    }
+    
+    std::cout << "'r' contains count = child object(s)" 
+              << r.count() << ")" << std::endl; // > 1
+              
+    { // extra scope for the removal test
+        // get a pointer to the first child object of 'r'
+        DoRef childRef = r->at(0);
+        
+        // remove it from the child list of 'r'
+        r->remove(childRef);
+        
+        // the referenced object of childRef is destroyed here
+    }
+    
+    std::cout << "'r' contains count = child object(s)" 
+              << r.count() << ")" << std::endl; // > 0
+}
+~~~~
+-------

 ### DoRef and parent()
 Use the relation `child->parent` safely.
@@ -105,11 +184,44 @@

 You must also expect to get a null pointer when doing so.

-@include sample-doref-parent.cpp
-
-See also doxygen documentation:
-- dt::DoRef 
-- dt::RefPtr<t>
+~~~~ (cpp)
+void test(DoRef r)
+{
+    DoRef guardRef(r); // do not allow destruction from outside e.g. another thread
+        
+    if (r.empty()) {
+        std::cerr << "'r' does not point to a valid object" << std::endl;
+        return;
+    }
+    
+    if (r->empty()) {
+        std::cout << "Given 'r' does not contain any child object" << std::endl;
+        return;
+    }
+    
+    // get a pointer to the first child object of 'r'
+    DoRef childRef = r->at(0);
+
+    // DoRef parentRef = childRef->parent();    
+    // WRONG: This would create a NEW shared_ptr with pointing to 
+    // the object childRef->parent() points to
+    //        
+    // And this would destruct the new shared_ptr when leaving
+    // the inner scope.
+    //
+    // What finally would lead to an access violation when leaving 
+    // test() or the function called test()
+    
+    // Correctly accessing the parent by using:
+    const dtitem *parentPtr = childRef->parent();
+    
+    // the reference count of childRef's parent is not changed
+    if (parentPtr) {
+        std::cout << "The parent object's name = " 
+                  << parentPtr->name() << std::endl;
+    }
+}
+~~~~

 ---------------------------------------------------------------------------

Home modified by hpg

hpg — Wed, 23 Dec 2015 13:09:21 -0000

--- v1
+++ v2
@@ -1,8 +1,122 @@
-Welcome to your wiki!
+# Common DataItem library (dtitem-library)

-This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].
+[TOC]

-The wiki uses [Markdown](/p/dtitem-library/wiki/markdown_syntax/) syntax.
+This is taken partially from the doxygen documentation (already in progress) and should
+better tell more about the Library itself than to tell how to use it.
+
+I will change this in the next time and move this page downwards to a new sub page.
+
+## Getting started
+The library contains a C++ class that can be used instead of any other type of
+variant classes or structures.
+
+It is easy-to-use and provides a lot of features such as:
+*  native C++ class
+*  not based on other 3rd party libraries
+*  a data item may have a child list of other data items 
+*  dynamic adding or remove items at runtime is supported
+*  intergrated iteration support by using `at()`and `count()`
+*  uses `std::shared_ptr` and does not copy values but rather add references to objects
+*  makes use of come C++11 features like supporting a move copy c'tor and assignment operator 
+
+## Restrictions / Limitations
+* Only tested with MSVC 10 yet
+* Requires C++11 or better 
+
+## What's coming next?
+* Better documentation and better english.
+* A serialization format to read and store data item objects
+* Better change notification with details like what has been changed
+
+## Building the Library
+To build the library you will need at least MSVC 10 or better (express version should do).
+
+Other compilers may work, but I didn't test them yet.
+
+If you make the library compile with another compiler, please let me know, drop me a line 
+and/or send me the makefile together with version of you compiler and system :)
+
+----------
+## DataItem Objects
+The library consist mainly of the main data item class `dtitem`, that is the data item class itself.
+
+All classes, functions and variables are located in namespace `dt`.
+
+All strings in the library are of type `dt::str_type`.
+This is a `typedef` to `std::string` currently but may be changed to e.g. `std::wstring` later.
+
+### DoRef - a reference to a `dt::dtitem`
+`DoRef` is s a specialized `dt::RefPtr<std::shared_ptr>` and is the type to be used with
+the library.
+
+A `DoRef` may point to nothing or to created `dtitem`. To call a method of the item simply use the `->`
+e.g.
+
+~~~~ (cpp)
+DoRef ref;
+ref.reset(new dt::dtitem("struct")); // creates the object, ref holds the reference to it
+
+// calls method name() which is 'struct' for this item
+std::cout << ref->name() << std::endl;
+// ==> >struct
+~~~~
+
+`DoRef` objects may be used to assign another `dtitem` object or can be added to a child list of a `dtitem`
+without any concerns about freeing up something. This is done by `DoRef`automatically.
+
+
+### DoRef and exception handling
+Whenever dealing with `DoRef` (or `dtitem`) classes you should consider to 
+handle `std::exception` throwings.
+
+@include sample-doref-exceptions.cpp
+
+A better handling would be:
+
+@include sample-doref-exception-handling.cpp
+
+### Creating a DoRef object
+Creating an object is safe when you create it "embedded" in a `DoRef` like:
+
+@include sample-doref-creation.cpp
+
+### Removing a DoRef object explicitely
+If you want to destruct a `DoRef` explicitely, you can remove it from a 
+parent object's child list by:
+
+@include sample-doref-remove.cpp
+
+### DoRef and parent()
+Use the relation `child->parent` safely.
+
+The design of the `dtitem` child list is done by using `DoRef` classes to
+reference objects. 
+
+An object contains a reference to its parent as well. 
+
+This is a so called `weak` kind of reference or simply said its just a pointer to a `dtitem`.
+
+This circumvents recursion trouble that otherwise would appear when adding an 
+object to a parent and the object would reference it with a `DoRef` instead.
+
+I.e. you may "access" the parent of a `dtitem` object only with a raw `const dtitem*` 
+and never using a `DoRef`. 
+
+You must also expect to get a null pointer when doing so.
+
+@include sample-doref-parent.cpp
+
+See also doxygen documentation:
+- dt::DoRef 
+- dt::RefPtr<t>
+
+---------------------------------------------------------------------------
+

 [[members limit=20]]
 [[download_button]]
+
+
+
+

Home modified by hpg

hpg — Tue, 22 Dec 2015 21:05:21 -0000

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a new page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

Project Members:

hpg (admin)