added programmers cookbook raw draft

documentation/pvDataCPPCookbook.txt

@@ -0,0 +1,179 @@
+pvDataCPP cookbook
+------------------
+
+
+Creating introspection data interfaces
+
+// create a scalar
+getFieldCreate()->createScalar(pvDouble);
+
+// create a scalar array
+getFieldCreate()->createScalarArray(pvDouble);
+
+// create a structure
+getFieldCreate()->createFieldBuilder()->
+    setId("enum_t")->
+    add("index", pvDouble)->
+    addArray("choices", pvString)->
+    createStructure();
+
+// create a structure (cntd.)
+PVStructure::const_shared_pointer enum_t = 
+    getFieldCreate()->createFieldBuilder()->
+        setId("enum_t")->
+        add("index", pvInt)->
+        addArray("choices", pvString)->
+        createStructure();
+
+// create a structure (cntd.)
+PVStructure::const_shared_pointer ntEnum = 
+    getFieldCreate()->createFieldBuilder()->
+        setId("uri:ev4:nt/2012/pwd/NTEnum")->
+        add("value", enum_t)->
+        addNestedStructure("timeStamp")->
+            setId("time_t")->
+            add("secsPastEpoch", pvLong)->
+            add("nanoseconds", pvInt)->
+            add("userTag", pvInt)->
+            endNested()->
+        createStructure();
+
+// create an union == same as structure
+
+---
+
+Creating data containers
+
+// create a scalar
+PVDouble::shared_pointer doubleValue = getPVDataCreate()->createPVScalar<PVDouble>();
+
+// create a scalar array
+PVDoubleArray::shared_pointer doubleArrayValue = getPVDataCreate()->createPVScalarArray<PVDouble>();
+
+// create a structure 
+PVStructure::shared_pointer struct = getPVDataCreate()->createPVStructure(ntEnum);
+
+// create an union
+PVUnion::shared_pointer pvUnion = getPVDataCreate()->createPVUnion(unionIF);
+
+// create a structure array
+PVStructureArray::shared_pointer structArray = getPVDataCreate()->createPVStructureArray(ntEnum);
+
+
+// scalar usage
+PVInt::shared_pointer index = struct->getSubField<PVInt>("value.index");
+int32 ix = index->get();
+index->put(3);
+std::cout << *index << std::endl;
+
+
+// using <<=, >>= operators to get/set
+*doubleValue <<= 12.3;
+
+double val;
+*doubleValue >>= val;
+
+
+
+// array usage
+PVStringArray::shared_pointer choices = struct->getSubField<PVStringArray>("value.choices");
+
+// use view() to access read-only data
+PVStringArray::const_svector data(choices->view());
+for (std::size_t i = 0; i < data.size(); i++)
+    std::cout << data[i] << std::endl;
+    
+// use replace() to put new data
+PVStringArray::svector newdata;
+newdata.push_back("zero");
+newdata.push_back("one");
+newdata.push_back("two");
+choices->replace(freeze(newdata));
+
+// (add more use-cases) here
+
+// print entire array
+std::cout << *choices << std::endl;
+
+// print elmenet at index == 1
+std::cout << format::array_at(1) << *choices << std::endl;
+
+----
+
+Union handling
+
+
+Union::const_shared_pointer punion =
+    getFieldCreate()->createFieldBuilder()->
+        add("doubleValue", pvDouble)->
+        add("intValue", pvInt)->
+        createUnion();
+                            
+PVUnion::shared_pointer u = getPVDataCreate()->createPVUnion(punion);
+
+// select and put
+// this create a new instance of PVDouble (everytime select() is called)
+PVDouble::shared_pointer doubleValue = u->select<PVDouble>("doubleValue");
+doubeValue->put(12);
+// select using index (and direct put)
+u->select<PVDouble>(0)->put(12);
+// select using existing PVField (PVUnion stores by-reference)
+u->set("doubleValue", doubleValue);
+
+// get selected field name or index
+std::string selectedFN = u->getSelectedFieldName();
+int32 selectedIndex = u->getSelectedIndex();
+
+// get currently selected (knowing it's PVDouble)
+PVDouble value = u->get<PVDouble>();
+
+
+
+Variant Union handling
+
+
+PVUnion::shared_pointer any = getPVDataCreate()->createPVVariantUnion();
+
+PVDouble::shared_pointer doubleValue = getPVDataCreate()->createPVScalar<PVDouble>();
+doubleValue->put(12.8);
+any->set(doubleValue);
+
+PVDouble::shared_pointer doubleValue2 = any->get<PVDouble>();
+
+// variant union work by-reference (pointers match also)
+// doubleValue.get() == doubleValue2.get()
+
+
+
+------
+
+Convert
+
+
+// convert to int
+int32 i = doubleValue->getAs<int32>();
+
+// from int
+doubleValue->putFrom<int32>(i);
+
+// from string
+doubleValue->putFrom<std::string>("12.3");
+
+// from scalar field
+doubleValue->assign(pvScalar);
+
+
+
+// convert to int array
+PVIntArray::const_svector intData;
+doubleArrayValue->getAs<int32>(intData);
+
+// from string array
+PVStringArray::svector labels;
+labels.push_back("zero");
+labels.push_back("one");
+labels.push_back("two");
+doubleArrayValue->putFrom<std::string>(labels);
+
+// from scalar array 
+doubleArrayValue->assign(pvScalarArray);