Self-describing object providing dynamic manipulation of heterogeneous data values and semantic identity between memory and transmission representations5754849Abstract An object for use in a computer memory and for transmission between computers flexibly stores a large variety of different types of data, in such a manner as to allow easy and efficient transfer and copying of the data between computers. The object includes any number of data elements, each of which is self-describing using type coding. Certain data elements may include other data elements, thereby providing for arbitrarily complex hierarchical arrangements of data in memory. The type codes may be based on the frequency of the types or values of data operated upon, such that the data itself may be used as a type code for at least one type of data, thereby reducing the memory and bandwidth requirements for handling the object. The object is capable of creating a data stream output for copying and transmission that preserves the semantic structure of the object, particularly its hierarchical organization, and is further capable of reconstituting the hierarchical arrangements. Because of the self describing nature of the object and its data elements, marshalling is not needed for inter-computer transfers of the object. Claims We claim: Description COPYRIGHT NOTICE
TABLE 1
______________________________________
$c If the character is in the ASCII range 32-127, except for
backslash, where c is the ASCII character.
$.backslash..backslash.
If the character is a backslash.
$.backslash.t
If the character is a tab.
$.backslash.xx
Where 'xx' are two hexadecimal digits, for all other
character values.
______________________________________
The printed representation of a Unicode character is .fwdarw.$.backslash.uxxxx where `xxxx` consists of four hexadecimal digits. The notation ".fwdarw." will be used throughout to indicate the printed representation of a value object 104 or other data. A date data element 124h stores data defining a point in time. Dates are preferably maintained in memory as GMT times, and are then converted to local time by the application 114 or operating system. The printed representation of a date is an array of the form: .fwdarw.›year, month, day, hour, minute, second, fraction! where year is a four-digit year (e.g. 1982), month is a number in the range 1 . . . 12, and day is a number in the range 1 . . . 31, hours are in the range 0-23, and minutes and seconds are in the range of 0-59. Fractions of a second is a 32-bit number in nanoseconds. Alternatively, an is GMT boolean element may be added indicating whether timestamp is GMT or local time, and thereby eliminating the need to always convert to local time. One alternative implementation of a date data element 124h uses an array, and will be described below. In one embodiment, scalar types do not include other data elements 124 at all. Accordingly, the memory representation of a scalar data element 124 is identical to its transmission arrangement. The flattener 110 need only to read out (or in, during unflattening) the type code 120 and data member 122 directly to (or from) the data stream 112. Referring now to FIG. 3b, there are shown the data storage arrangements for blob type data elements 124. In a preferred embodiment blob type data elements 124 include string, Unicode string, and binary, illustrated as data elements 124i to 124k, respectively. Each blob data element 124 has a type code 120, and a data member 124 that references a descriptor 130. The descriptor 130 includes a length field 126, and a content field 126. The length field 126 specifies a number of units of data of a specific type. Thus, a string data element 124i includes in the content field a number of characters. A Unicode string data element 124j includes in the content field 128 a number of Unicode characters. A binary data element 124k includes in the content field 128 a number of uninterpreted bytes (or other size of data). Binary data elements 124 are useful for storing and transmitting audio data, video data, graphics, and the like. As will be discussed below, because a value object 104 may include, via an aggregate type data element 124, numerous different types of data elements 124 in a single object, binary data element 124, for example of a graphics file, can be directly stored intermixed with string data elements, (e.g. a text file) describing the binary data element 124, and a date data element 124 describing the creation date, modification date, or the like, of the graphics file. One alternative implementation of blob data elements 124k uses an array and will be described below. As noted above, in the preferred embodiment, a blob data element 124 has as its data member 124 a reference to the descriptor 130. This is used in the memory representation of the value object 104 to access the parts of descriptor 130 in the local memory. Since the local memory reference is not valid when transferred to another computer, the flattener 110, when flattening a blob data element 124, obtains the descriptor 130 and directly builds it into the data stream 112 immediately following the type code 120 for the data element. This preserves the semantic structure of the memory representation and the transmission representation of the data element 124, and hence the value object 104 incorporating a blob data element 124. Referring now to FIG. 3c, there are shown the data storage arrangements for aggregate type data elements 124. In a preferred embodiment aggregate data elements 124 include array and map, illustrated as data elements 124i to 124k, respectively. Each aggregate data element 124 has a type code 120, and a data member 122 that references a descriptor 130, as with blob data elements 124. The reference is preferably a pointer to the descriptor 130, though other forms of reference may be used, such as indices, handles, or the like. For an array data element 124l, the descriptor 130d includes a length field 126, and a number of value objects 104, the number specified by the length field 126. Thus, array data element 124l defines a simple vector of values. Array data elements 124l are zero indexed. The value objects 104 contained by an array data element 124l may be of any type, including other array data elements 124l, or map data elements 124m. The printed representation of an array is: .fwdarw.›element1, element2, . . . ! where each element is printed according to its own printed representation, as described above. A map data element 124m is a collection of a number of <key 132, value object 104>pairs called map entries 136. Keys are preferably scalar type data elements, and are all of a same specific type. In other embodiments, varied types for keys may be used. The value objects 104 may be of any type, including arrays and maps. Accordingly, the descriptor 130e in a map data element 124m includes a length field 126 specifying the number of pairs of key value 132 and value objects 104. The map entries 136 are not guaranteed to be in any particular order. The printed representation of a map is: .fwdarw.{key: value object key: value object . . . } where each key and value object is printed as defined above. Because the aggregate data elements 124 include other value objects 104 in their data elements 124, they may be used to create hierarchical arrangements of data. The flattening and unflattening process preserves the hierarchical arrangement of data, and thereby the semantic structure of the value object 104 between its memory representation and its transmission representation. Array data elements 124l and map data elements 124 may optionally include a class field 138. The class field 138 contains a programmer defined value associated with the array data element 124l or map data element 124m. This allows the programmer to define particular operations that manipulate arrays or maps according to their class field 138. When a class field 138 is defined, the provided value is also output in the printed representation of the data element. FIG. 4 illustrates a schematic representation of an instance of an array data element 124l in a value object 104. Here, the array data element 124l is an array of class 138 "STUDENTS", and has three data elements, each of which is an array data element 124l with two string data elements 124i. As noted above, in one embodiment, scalar data elements 124 do not include other data elements 124. In an alternative embodiment, scalar types remain fixed in length, but may include other types of data elements 124, or even value objects 104. An example of this would be a date data element 124h defined using a array data element 124l, having a predetermined number of entries, such as seven, one each for year, month, day, hour, minute, second, fraction of second. The number of elements would be stored in the length field 126, as before. Similarly, blob type data elements may also be alternatively assembled from array data elements 124l. In such an embodiment, a binary data element 124k is an array data element 124l with an optional class field 138 value defining a user selected class value (e.g "movie", "graphic", "code"), and a length field 126 for the length of the binary data, and the data itself. The type codes 120 illustrated in FIGS. 3a-3d are merely illustrative, in order to demonstrate the structure of the data elements 124 in a value object 104. Table 2 describes the type codes 120 used in a preferred implementation:
TABLE 2
__________________________________________________________________________
Type Code
GetType
Stored in
Type of Data
Result
Memory
Type Code for Transmission
__________________________________________________________________________
Boolean
0 0 -61
Character
2 1 -59
Unicode Char.
1 2 -58
Short 2 3 -57
Long 3 5 Range: -64-63
Code: ›00Sxxxxx!
Range: -8192-8191
Code: ›01Sxxxxx! ›xxxxxxxx!
Range: all others
Code: ›11000000! ›MSB! ›! ›! ›LSB!
Float 4 6 -55
Double 5 7 -54
Date 7 8 -53
String 8 15 -52
Unicode String
8 16 -51
Binary 8 17 -49
Array 9 19 -47
Map 9 20 -44
__________________________________________________________________________
In Table 2, the GetType result is used merely to provide a correspondence with similar type codes used in Visual Basic. Note that Visual Basic does not fully recognize the distinctions in type between many of the data elements recognized in the present invention. The second column, Type Code Stored in Memory is the preferred type code 120 for the memory representation of a data element 124. The last column, Type Code for Transmission, is the preferred type code 120 for the transmission representation of a data element in a transmission medium. In addition to being specified with particular number values, type codes 120 may also be ranges of values, or sets of values. That is, a predetermined set, or range of numbers, may be selected as all identifying a particular type of data element 124. For a simple example, all values between 0 and 9 may be selected as the type codes 120 for short data elements 124d, and values 10 to 19 may be selected as the type codes 120 for float data elements 124f. This is the inverse of the duplication of type codes 120 in the GetType column. In one preferred embodiment, the type codes 120 for selected ones of the types of data elements 124 are determined according to a frequency distribution of the data values of the data elements. This allows the actual data values themselves to serve as both the type code 120 and the data member 122 for at least one type of data element 124. Having the data values of the data element 124 serve both functions reduces the amount memory required for storing (providing a form of data compression), and the time and bandwidth required for transmitting for these frequently used values and types of data element 124. The third column of Table 2 illustrates this feature of the invention. For example, it may be determined that a particular set of long data values used in long data elements 124e are frequently stored and transmitted, for example, long data values between -64 and 63. This range of values is then selected as the type codes 120 for long data elements 124e. When a data element 124 is retrieved and the type code 120 is read, if the value of the type code 120 is in the specified range, then the flattener 110, or other code in an application 114, knows that the data element 124 is a long data element 124e, and decodes/encodes the rest accordingly, using that part of the data in the type code 120 space as value of the data member 122. If the value of the type code 120 is outside the range, then data element 124 are treated as described, with specific type codes 120. In this example a range of values is used, but logically, any set of values could be used for this optimization. This optimization of the type code 120 further increase the performance of the system for storing and transmitting data. The domain over which the frequency determination is made may vary. For example, the frequency distribution may be determined with respect to any variety of applications 114. This type of determination would be useful, for example, when the value object 104 is provided as class in a general programming environment, and may be used by applications programmers to construct any variety of applications, including client-server applications of any type. In this type of embodiment, the selection of the type codes 120 would be made by the provider of the programming environment. Alternatively, the domain may be limited to particular classes of applications, preferably based on empirical testing of the application behaviors and usage characteristics. Thus, for examples, it may be determined that word processors use string data elements 124i most frequently with the ASCII values. In this case, values between -128 and 127 are used as both the type code 120 and the data member 122 of the data element 122, again, reducing the memory and network requirements for this class of application. The provider of the programming development environment would provide a table that applications programmers can select from when creating their applications that would identify the type of application, and thus the type codes 120 for the data elements 124. In order to facilitate data transfer between applications of different types, each application would include a table with type codes for all other types of applications. When a connection is initially made between applications, they would exchange their application types, and then use that information to decode the value objects between transmitted between them. Finally, in other alternative embodiments, the type codes 120 may be specified by the applications programmer herself, based on any desirable criteria. It should be noted that the type codes 120 used in the transmission representation, as for example in Table 2, are then translated to memory representation type codes 120, and vice versa, by the flattening and unflattening methods. As described above, the value object 104 is able to output its data elements 124 into "flattened" byte stream 112 for transmission over a network. The flattened byte stream 112 has identical semantics to the memory representation with the hierarchical arrangement of data. The flattener 110 is preferably implemented as a flatten method of the value object 104. A preferred implementation of the flatten method operates using recursive descent in order to unnest nested array data elements 124l and map data elements 125m. One pseudo code description of a flatten method is as follows:
______________________________________
procedure: flatten (dest.sub.-- buffer)
switch (type.sub.-- code)
case: array.sub.-- code
if class |= nil
emitClass (class, dest.sub.-- buffer)
emitNumber (t.sub.-- array.sub.-- code, dest.sub.-- buffer)
emitNumber (no. of elements, dest.sub.-- buffer)
emitNumber (class, dest.sub.-- buffer)
for all elements i
element›i!.flatten (dest.sub.-- buffer)
case: map.sub.-- code
if class |= nil
emitClass (class)
emitNumber (t.sub.-- map.sub.-- code, dest.sub.-- buffer)
emitNumber (no. of elements, dest.sub.-- buffer)
emitNumber (class, dest.sub.-- buffer)
for all elements i
element›i!.flatten (dest.sub.-- buffer)
case: binary.sub.-- code
emitNumber (t.sub.-- binary.sub.-- code, dest.sub.-- buffer)
emitNumber (length, dest.sub.-- buffer)
emitBytes (length, source.sub.-- buffer, dest.sub.-- buffer)
case: unicode.sub.-- string.sub.-- code
emitNumber (t.sub.-- unicode.sub.-- string.sub.-- code, dest.sub.--
buffer)
emitNumber (length, dest.sub.-- buffer)
emitBytes (length, source.sub.-- buffer, dest.sub.-- buffer)
case: string
emitNumber (t.sub.-- string code, dest.sub.-- buffer)
emitNumber (length, dest.sub.-- buffer)
emitBytes (length, source.sub.-- buffer, dest.sub.-- buffer)
case: date.sub.-- code
emitNumber (t.sub.-- date.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (date), source.sub.-- buffer, dest.sub.-- buffer)
case: double.sub.-- code
emitNumber (double.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (double), source.sub.-- buffer, dest.sub.-- buffer)
case: float.sub.-- code
emitNumber (t.sub.-- float.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (float), source.sub.-- buffer, dest.sub.-- buffer)
case: long.sub.-- code
emitNumber (value, dest.sub.-- buffer)
case: short.sub.-- code
emitNumber (t.sub.-- float.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (float); source.sub.-- buffer, dest.sub.-- buffer)
case: unicode.sub.-- char.sub.-- code
emitNumber (t.sub.-- unicode char.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (unicode.sub.-- char), source.sub.-- buffer,
dest.sub.-- buffer)
case: char.sub.-- code
emitNumber (t.sub.-- char.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (char), source.sub.-- buffer, dest.sub.-- buffer)
case: boolean.sub.-- code
emitNumber (t.sub.-- boolean.sub.-- code, dest.sub.-- buffer)
emitBytes (sizeof (boolean), source.sub.-- buffer, dest.sub.-- buffer)
procedure: emitClass (class, buffer)
emitNumber (class.sub.-- code)
emitNumber (length of class)
emitBytes (length of class, source.sub.-- buffer, dest.sub.-- buffer)
______________________________________
The procedure emitNumber(value, destination.sub.13 buffer) outputs the byte of value to the destination buffer, which may be coupled to a network socket or other network connection. In the flatten method the values are the transmission representation type codes 120, and in the unflatten method they are memory representation type codes 120. The procedure emit bytes(number of bytes, source.sub.13 buffer, destination.sub.13 buffer) reads the number of bytes from the source buffer to the destination buffer. The first two cases perform the recursive descent through a hierarchical arrangement of data. The remaining cases structure the output bytes in the transmission representation, that is the actual byte ordering that is transmitted between two computers (or that may be restored locally). The procedure emitClass(class, buffer) outputs a class code (e.g. -50), the length of the class, and bytes from the buffer containing the actual class data. The flatten method also puts the output in network standard order, as needed. The flatten method thereby creates the transmission representation of a given value object 104, with all hierarchical relationships between the data preserved. One preferred implementation of the flatten method is further described below, using an intermediate data structure, a flat value object, to hold the flattened data stream 112. FIG. 5 illustrates schematically the flattened transmission representation of the various types of data elements 124 capable of being held by a value object 104. The type code 120 values used in FIG. 5 are the same as those used in FIGS. 3a-3c, and are merely illustrative. The placement of the class field 138 is not shown. If a class field 138 is used, then it preferably prefixes the data stream for the data element 124. The value object 104 is likewise capable of reconstructing itself from the flattened data stream 112. An "unflatten" method (see the Get method, below, for one implementation) operates in a similar manner to the flatten method to perform this reconstruction. The unflatten method adds in each case a call to allocate a new instance of a data element 124 of the type defined by the type code 120, and then reads the data from a source buffer into the data element. In addition to being able to hold a large number of different types of data, a value object 104 can dynamically (after instantiation) alter or change the type of any of its data elements. Thus, once a data element 124 in a value object 104 is created as a first type, for example, an short, it may subsequently changed to a different type of data. Examples of methods for these types of manipulations are further described below with respect to the Set methods. A value object 104 supports a number of methods to get, set, create, test, remove, add, and otherwise manipulate the data elements 124 in the object. As explained above, value objects 104 may include aggregate types of data, such as array and maps, thereby allowing complex hierarchical arrangements of data elements 124. Accordingly, in the methods of the value object, each data element 124 in any aggregate type value object 124 is addressable using a path expression. A path is a sequence of array indices or map entries that specifies a "trip" from an outer value (such as an array or map) to some inner value. More particularly, each element E.sub.i in a path expression is an index into an array or map defined at element E.sub.i-1, where E.sub.0 is a top level array. Paths are most easily explained by examples. For example, a value object v may be created with a five element array data element 124: v.SetArray 5 Here, the "5" is the path expression. The third element of the array may be set to some string:
______________________________________
v.Set 2, "Frogstar"
Debug.Print v.GetString
-> ›nil, nil, "Frogstar", nil, nil!
______________________________________
The path in this call to a Set method is a one-element path "2". The final argument to Set, the string "Frogstar", is the value to set the element pointed to by the path. The Print method outputs the printable representation of the value object v. "nil" is the value a data member takes when it is initially created, and not specified. A nested array data element 124l may be added:
______________________________________
v.SetArray 3, 2
Debug.Print v.GetString
-> ›nil, nil, "Frogstar", ›nil, nil!, nil!
______________________________________
This dynamically changes the third element to a array data element 124l with two elements. The nested array by adding an index to the path:
______________________________________
v.Set 3, 0, "Thing 1"
v.Set 3, 1, "Thing 2"
Debug.Print v.GetString
-> ›nil, nil, "Frogstar", ›"Thing 1", "Thing 2"!, nil!
______________________________________
The path "3, 1" in two calls to Set above start with the index of the inner array (3) and include an index into the inner array (0 or 1). The last argument to Set is always the value to set. Paths are also used with map data elements 124m. A value object V including a map data element 125m, that itself containing an array data element 124l and another map data element 124m:
______________________________________
v.SetMap
v.SetArray "a", 0
v.SetMap "b"
Debug.Print v.GetString
-> {a: ›!, b: {}}
______________________________________
By specifying the key "a" as the first element of a path, further elements may be added to the nested array:
______________________________________
v.AddLast "a", 42
v.AddLast "a", 99
v.AddLast "a", 50
Debug.Print v.GetString
-> {a: ›42, 99, 50!, b: {}}
______________________________________
Likewise, by specifying the key "b" as the first path element, elements may be added to the nested map:
______________________________________
v.Set "b", "x", "Fred"
v.Set "b", "y", "John"
Debug.Print v.GetString
-> {a: ›42, 99, 50!, b: {x: "Fred", y: "John"}}
______________________________________
Another map may be added inside the already nested map:
______________________________________
v.SetMap "b", "z"
v.Set "b", "z", "q", 99
Debug.Print v.GetString
-> {a: ›42, 99, 50!, b: {x: "Fred", y: "John", z: {q: 99}}}
______________________________________
The map entry q is printed by calling GetString with the path "b", "z" and "q": Debug.Print v.GetString("b", "z", "q").fwdarw.99 As is evident, depending on the nesting, paths, and the hierarchical arrangement of data storage in value objects 104 may be arbitrarily complex, As noted, the value object 104 supports a variety of different methods for manipulating the data elements contained therein. Table 3 through Table 12 define the interfaces (in Visual Basic syntax) of the preferred methods of the value object 104. Here path refers to path expressions previously described:
TABLE 4
______________________________________
Getting and Setting
______________________________________
( index )
value | symbol
Count ›path!
Extract ›path,! index, count
Get ›path!
GetClass ›path!
GetElem ›path,! index
GetKey ›path,! index
GetType ›path!
Hash ›path!
Length ›path!
Set ›path,! value
SetClass ›path,! class
______________________________________
The operation of each of these methods is as follows: (index) value (index) Parenthesis are used to get or set array elements and map entries.
TABLE 15
______________________________________
Array The index must be a positive value. For assignment, if
the array is too small then the array is grown as necessary
Sorted Array
The index must be positive and less than the size of the
or Set array. This syntax can only be used to retrieve a value - it
cannot be used for assignment.
Map The index can be any value, and is the map entry's
______________________________________
key.
If the first assignment to an uninitialized value object 104 is with parenthesis, the object will automatically turn into an array:
______________________________________
Dim v As New Wvalue
v(0) = "in an array"
Debug.Print v.GetString
.fwdarw. ›"in an array"!
______________________________________
EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v(0) = "Fred"
v(1) = "Jones"
Debug.Print v.GetString
.fwdarw. ›"Fred", "Jones"!
v.SetMap
v(0) = "Fred"
v(1) = "Jones"
Debug.Print v.GetString
.fwdarw. {0: "Fred", 1: "Jones"}
______________________________________
value | name value | name Visual Basic's "|" syntax can used to get or set map entries by name. The value must be a map. A map entry can be created (or set) with assignment:
______________________________________
Dim v As New WValue
v.SetMap
v|FirstName = "Fred"
v|LastName = "Jones"
Debug.Print v.GetString
.fwdarw. {FirstName: "Fred", LastName: "Jones"}
______________________________________
Likewise, map entries can be retrieved by name: Debug.Print v|FirstName, v|LastName.fwdarw.Fred Jones If the first assignment to an uninitialized value object 104 is with "|" syntax, the value object 104 will automatically become a map.
______________________________________
Dim v As New Wvalue
v|FirstName = "Marcus"
v|LastName = "Garvey"
Debug.Print v.GetString
.fwdarw. {FirstName: "Marcus", LastName: "Garvey"}
______________________________________
Add value.Add ›path,! value This method adds the value to an aggregate. The path must refer to an aggregate value. The exact behavior of Add depends on the kind of aggregate that the value is being added to:
TABLE 16
______________________________________
Array The value is appended to the array. This is the same as
using AddLast.
Sorted Array
The value is placed in the sorted array in the correct,
sorted position.
Set If the value is not present in the set, it is added.
Map The value is added to the map as if
mapValue.Set value, NULL
were used.
______________________________________
EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.Add "Fred"
v.Add "Joe"
Debug.Print v.pp
.fwdarw. ›"Fred",
"Joe"!
v.SetMap
v.Add "Fred"
v.Add "Jones"
Debug.Print v.pp
.fwdarw. {Fred: nil,
Jones: nil}
______________________________________
AddFirst value.AddFirst ›path,! value This method prepends a value to an array. The path must refer to an array, the value can be any value. This method can also be used to prepend a binary or string to another binary or string. Both values must be of the same type (binary or string). EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddFirst "Fred"
v.AddFirst "Joe"
v.AddFirst "Twonky"
Debug.Print v.pp
.fwdarw. ›"Twonky",
"Joe",
"Fred"!
______________________________________
AddLast value.AddLast ›path,! value This method appends a value to an array. The path must refer to an array, the value can be any value. This method can also be used to append a binary or string to another binary or string. Both values must be of the same type (binary or string). EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddLast "Fred"
v.AddLast "Joe"
v.AddLast "Twonky"
Debug.Print v.pp
.fwdarw. ›"Fred",
"Joe",
"Twonky"!
______________________________________
AddUnique value.AddUnique ›path,! value Appends a value to an array (or adds a value to a sorted array or set) if the value does not already appear. The path must refer to an array, the value can be any value. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddUnique "Fred"
v.AddUnique "Fred"
Debug.Print v.pp
.fwdarw. ›"Fred"!
______________________________________
AsGMT date=value.AsGMT ›path! The path must refer to a value that is a date. The date is returned as a GMT time. EXAMPLE
______________________________________
Dim v As New WValue
v.Set Now
Debug.Print v.Get
.fwdarw. 12/1/95 6:24:36 PM
Debug.Print v.AsGMT
.fwdarw. 12/2/95 2:24:36 AM
______________________________________
Clone value2=value.Clone ›path! This method returns a copy of the specified value. The copy is deep; operations on the copy or any of its contents will not affect any elements of the original. EXAMPLE
______________________________________
Dim v1 As New WValue, v2 As WValue
v1.SetString "{a:1, b:›1,2,3!}"
Set v2 = v1.Clone
V1|a = 42
v1|b.SetLength 0
Debug.Print v1.GetString
.fwdarw. {a:42,b:›!}
Debug.Print v2.GetString
.fwdarw. {a:1,b:›1,2,3!}
______________________________________
Count count=value.Count ›path! Returns the number of elements in an object. What the number means depends on the object's type:
TABLE 17
______________________________________
Array Returns the array's length.
Sorted Array
Returns the array's length.
Set Returns the number of set members.
Map Returns the number of map entries.
String Returns the number of characters in the string.
Symbol Returns the number of characters in the symbol.
Unicode String
Returns the number of characters in the string.
Binary Returns the number of bytes in the binary.
______________________________________
This method is identical to the Length method. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddLast 1
v.AddLast 2
v.Insert 0,55
Debug.Print v.Count
.fwdarw. 57
v.Set "This is a string"
Debug.Print v.Count
.fwdarw. 16
______________________________________
Delete value.Delete ›path,! index, count If the value is an array, sorted array or set, the Delete method removes count elements starting at the offset index. If the value is a string or Unicode string, the Delete method removes count characters starting at the offset index. If the value is a binary, the Delete method removes count bytes starting at the offset index. It is not possible to use Delete on any other value types, including symbols and maps. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddLast 4
v.AddLast 5
v.AddLast 6
Debug.Print v.GetString
.fwdarw. ›4,5,6!
v.Delete 1,2
Debug.Print v.GetString
.fwdarw. ›4!
v.Set "This is a string"
v.Delete 4,3
Debug.Print v.Get
.fwdarw. This a string
______________________________________
Equals boolean=value.Equals value2 This method returns true if the value is equal to the argument value, value2. The comparison is deep; the contents of arrays and other aggregates are compared recursively. Strings are compared without regard to case. EXAMPLE
______________________________________
Dim v1 As New WValue, v2 As WValue
v1.SetString "{a:1, b:›1,2,3!, c:'fred'}"
Set v2 = v1.Clone
Debug.Print v1.Equals(v2)
.fwdarw. True
v1|a = 99
Debug.Print v1.Equals(v2)
.fwdarw. False
______________________________________
ErrorText string=value.ErrorText (errorNumber) This method returns the text associated with an error returned by the application programming environment. EXAMPLE
______________________________________
Dim v As New WValue
Debug.Print v.ErrorText(0)
.fwdarw. No error.
Debug.Print v.ErrorText(20000)
.fwdarw. No memory available.
______________________________________
Exists boolean=value.Exists ›path! This method returns true if the specified value exists. Normally this method is used with a path. This can be used to test if an entry exists in a map: If myMap.Exists("fred") Then . . . Or if an element exists in an array: If myArray.Exists(42) Then . . . The IsXxxx set of methods (IsArray, IsSet, IsLong, and the like) provide stronger versions of Exists that also check if the specified item is of a particular type. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray 5
Debug.Print v.Exists(0)
.fwdarw. True
Debug.Print v.Exists(5)
.fwdarw. False
v.SetString "{a:1, b:›1,2,3!, c:'Fred'}"
Debug.Print v.Exists("a")
.fwdarw. True
Debug.Print v.Exists("frobble")
.fwdarw. False
______________________________________
Extract result=value.Extract ›path,! index, count The Extract method returns a specified piece of an array, sorted array, set, string, Unicode string or binary, depending on the type of the value:
TABLE 18
______________________________________
Array, Return an array that is a deep copy of the specified array
Sorted Array,
elements.
Set
String, Return the specified sub-string . . .
Unicode String
Binary Return a new binary containing the appropriate bytes
from the original.
______________________________________
EXAMPLE
______________________________________
Dim v As New WValue
Dim v2 As WValue
v.Setstring "›a b c d e f g h i j k l!"
Set v2 = v.Extract(2, 5)
Debug.Print v2.GetString
.fwdarw. ›c,d,e,f,g!
v.Set "This is a string"
Debug.Print v.Extract(5, 11)
.fwdarw. is a string
______________________________________
Find index=value.Find ›path,! expression The value specified by the path must be an aggregate. The aggregate is searched to see if it contains the value expression. If it does, an index greater than or equal to zero is returned. If the aggregate does not contain the value, the index -1 is returned. EXAMPLE
______________________________________
Dim v As New WValue
v.Setstring "›Fred Joe John Susan Ralph Guido!"
Debug.Print v.Find("john")
.fwdarw. 2
Debug.Print v.Find("Donald")
.fwdarw. -1
v.Setstring "{Fred: true, Joe: false, John: true, Susan: false}"
Debug.Print v.Find("john")
.fwdarw. 2
Debug.Print v.Find("Donald")
.fwdarw. -1
______________________________________
Flatten flattener=value.Flatten Referring to FIG. 6, the Flatten method makes a copy of the value and returns a flat value object 140, which holds the raw bytes of the original value object 104, and is capable of outputting those bytes as the data stream 112 from which the value object 104 can be reconstructed. Once a flat value object 140 is constructed by the a call to the flatten method of a value object 104, a call to the Size method of the flat value object 140 returns the number of bytes in the flattened value. A Get method call on the flat value object 140, which takes an offset and a count, returns a byte array containing the appropriate bytes of all of the flattened data elements 124 in the value object 104. For example:
______________________________________
Dim v As New WValue
Dim bytes() As Byte
Dim flattener As FlatValue
v.Setstring "{a:1, b:›1,2,3!, c:'fred'}"
Set flattener = v.Flatten
bytes = flattener.Get(0, flattener.Size)
______________________________________
From the bytes, a copy of the original value object 104 can be reconstructed:
______________________________________
Dim v2 As WValue
Dim flattener2 As New FlatValue
flattener2.Add bytes
Set v2 = flattener2.GetValue
Debug.Print v2.GetString
.fwdarw. {a:1, b:›1,2,3!, c:"fred"}
______________________________________
Here "v2" is the new value object 104, corresponding logically for example, to value object 104b in FIG. 1. The hierarchical arrangement of the data elements 124 in this second value object 104 is identical to that of the original value object 104, as shown in the final output line. Notice that no marshalling calls are required in this code example. Thus, the applications programmer is able to easily transmit value objects 104 between computer systems. Get result=value.Get ›path! Returns the value found by following the specified path. If the value can be represented directly in Visual Basic, then a Visual Basic value of the appropriate type is returned:
______________________________________
Dim v As New WValue
v.SetString "{Bob: 'Redmond', Greg: ›'San Jose', 'Mountain View'!}"
Dim s As String
s = v.Get("Bob")
Debug.Print s
.fwdarw. Redmond
______________________________________
However, if the value specified by the path is an aggregate then Get will return a Value object and you must use Visual Basic's Set syntax if you are performing assignment:
______________________________________
Dim v2 As WValue
Set v2 = v.Get("Greg")
Debug.Print v2.GetString
-> ›"San Jose", "Mountain View"!
______________________________________
If a value holds a primitive type, such as a string or a number, the Get method without any arguments will retrieve the value:
______________________________________
v.Set "some string"
Debug.Print v.Get
-> some string
______________________________________
GetClass string=value.GetClass ›path! Returns the class symbol for an array, map or binary. If the value does not have a class, NULL is returned. EXAMPLE
______________________________________
Dim v As New WValue
v.SetBinary "---some contents---", "Dreedle"
Debug.Print v.GetClass
-> Dreedle
v.SetClass "Gronk"
Debug.Print v.GetClass
-> Gronk
______________________________________
GetElem result=value.GetElem ›path,! index Returns the value of the index'th entry in a map. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a:1, b:›1,2,3!, c: `Fred`}"
Dim elems As New WValue
elems.SetArray
For i = 0 To v.Length - 1
elems.AddLast v.GetElem(i)
Next i
Debug.Print elems.GetString
-> ›1, ›1, 2, 3!, "Fred"!
______________________________________
GetKey result=value.GetKey ›path,! index Returns the key of the index'th entry in a map. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a:1, b:›1,2,3!, c: `Fred`}"
Dim keys As New WValue
keys.SetArray
For i = 0 To v.Length - 1
keys.AddLast v.GetKey(i)
Next i
Debug.Print keys.GetString
-> ›"a", "b", "c"!
______________________________________
GetString string=value.GetString ›path! Returns a printable representation of the value at the specified path, as a string. The string returned can be used for several purposes, such as a debugging aid. Alternatively, the string may be fed back into a value object, reconstituting the original value, with the SetString method. This is one of the means by which persistent values may be implemented. EXAMPLE
______________________________________
Dim v1 As New WValue
v1.SetMap
v1|a = 42
v1|b = "Fred"
Debug.Print v1.GetString
-> {a: 42, b: "Fred"}
Dim v2 As New WValue
v2.SetString v1.GetString
Debug.Print v1.Equals(v2)
-> True
______________________________________
GetType typeNumber=value.GetType ›path! Returns an integer indicating the type code 120 of the data element 124 specified by the path. The type code 120 is preferrably the memory representation type 120. However in to provide compatiblity with the Visual Basic programming environment which uses a set of small integers to define the available types, the following type codes are returned:
TABLE 19
______________________________________
Type
Type Code
______________________________________
nil 0
Boolean 0
Character
2
Unicode 1
Character
Integer 2
Long 3
Float 4
Double 5
Date 7
String 8
Unicode String
8
Binary 8
Symbol 8
Array 9
Sorted Array
9
Set 9
Map 9
OLE Object
9
Reference
______________________________________
Note that Table 19 includes a variety of other types of data elements, such as symbol, sorted array, and integer, which as all specifies of the more general types of data elements 124 described above. The OLE object reference type is a data element that holds a reference to an OLE object. Again the type codes here are merely to correspond with Visual Basic types. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›42 98.6 `string` ›array! {map:0}!"
Dim i As Long
For i = 0 To v.Length - 1
Debug.Print v.GetString(i), v.GetType(i)
Next i
-> 42 3
98.6 5
"string" 8
›array! 9
{map: 0} 9
______________________________________
GetVBString string=value.GetVBString ›path! Returns a string representation of the value specified by the path. The string's characters are encoded in such a manner that it can be written to a file with a print statement, and read back in with an input statement. EXAMPLE This example first writes a value to a file using Visual Basic's GetVBString, then re-opens the file, reads from it, and uses SetVBString to reconstitute the value.
______________________________________
Dim v As New WValue
v.SetString "{a:1, b:›1,2,3!, c:`Fred`}"
Dim fn As Integer
fn = FreeFile
Open "Prefs.dat" For Output As #fn
Print #fn, """" + v.GetVBString + """"
Close #fn
v.SetNil
Dim s As String
fn = FreeFile
Open "Prefs.dat" For Input As fn
Input #fn, s
v.SetVBString s
Close #fn
Debug.Print v.GetString
-> {a: 1, b: ›1, 2, 3!, c: "Fred"}
______________________________________
Hash longHash=value.Hash ›path! Returns a 32-bit hash of the value specified by the path. EXAMPLE
______________________________________
Dim v As New WValue
v.Set "a string"
Debug.Print v.Hash
-> 128682615
v.Set "a different string"
Debug.Print v.Hash
-> 44739351
______________________________________
Insert value.Insert ›path,! index, count If the value specified by the path is an array, this method inserts count nil values at the index. If the value specified by the path is a string or Unicode string, then count characters whose value is zero are inserted at the index. If the value specified by the path is a binary, then count bytes of zero are inserted at the index. No other value types can be modified with Insert. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›a b c d e f!"
v.Insert 0, 1
v.Insert 2, 3
Debug.Print v.GetString
-> ›nil, a, nil, nil, nil, b, c, d, e, f!
v.SetBinary "A binary object", "class"
v.Insert 0, 5
Debug.Print v.GetString
-> ›binary:class ".backslash.x00.backslash.x00.backslash.x00.backslash.x00
.backslash.x00A binary
object"!
______________________________________
InsertValue value.InsertValue ›path,! index, value2 If the path refers to an array, the value argument (value2) is inserted before the index'th element. If the index is equal to the length of the array, the value is appended to the array. Example
______________________________________
Dim v As New WValue
v.Set "Some string"
v.InsertValue 5, "silly"
Debug.Print v.GetString
-> "Some silly string"
v.SetString "›a b c d!"
v.InsertValue 1, "a string"
Debug.Print v.GetString
-> ›a, "a string", b, c, d!
v.InsertValue 2, v
Debug.Print v.GetString
-> ›a, "a string", ›a, "a string", nil, b, c, d!, b, c,
______________________________________
d!
If the path refers to a string or Unicode string, the value argument (value2) should be another string. That string is inserted before the index'th character. Example
______________________________________
Dim v As New WValue
v.Set "Some string"
v.InsertValue 5, "silly"
Debug.Print v.GetString
-> "Some silly string"
______________________________________
If the path refers to a binary object, the value argument can be a Visual Basic byte array, a string, or another binary object. The bytes from the value argument are inserted before the specified index. EXAMPLE
______________________________________
Dim v As New WValue
v.SetBinary "---some contents---", "Dreedle"
Debug.Print v.GetString
-> ›binary: Dreedle "---some contents---"!
Dim b() As Byte
ReDim b(5)
For i = 0 To 5
b(i) = 64 + i
Next i
v.InsertValue 0, b
v.InsertValue v.Length, "the end"
Debug.Print v.GetString
-> ›binary: Dreedle "@ABCDE---some contents---the end"!
______________________________________
IsAggregate boolean=value.IsAggregate ›path! This method returns true if the value specified by the path is an array, sorted array, set or map. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
Debug.Print v.IsAggregate
-> True
v.Set "Fred"
Debug.Print v.IsAggregate
-> False
______________________________________
boolean=value.IsXxxxx ›path! These methods return true if the value specified by the path exists and is of the appropriate type. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a: 1, b: ›1,2,3!, 99: `a string`, 100: 98.6 }"
Debug.Print v.IsNumber("a")
-> True
Debug.Print v.IsString("a")
-> False
Debug.Print v.IsArray("b")
-> True
Debug.Print v. IsNumber("b", 0)
-> True
Debug.Print v.IsString(99)
-> True
Debug.Print v.IsNumber(100), v.IsDouble(100)
-> True True
______________________________________
IsNumber boolean=value.IsNumber ›path! This method returns true if the value specified by the path is any number (e.g. integer, long, float, or double). EXAMPLE
______________________________________
Dim v As New WValue
v.Set 42
Debug.Print v.IsNumber
-> True
v.Set "Fred"
Debug.Print v.IsNumber
-> False
______________________________________
Length length=value.Length ›path! This method returns: The number of elements in an array, sorted array or set. The number of elements in a map. The number of characters in a string, Unicode string or symbol. The number of bytes in a binary. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.AddLast 1
v.AddLast 2
v.Insert 0, 55
Debug.Print v.Length
-> 57
v.Set "This is a string"
Debug.Print v. Length
-> 16
______________________________________
NewArray arrayValue=factoryValue.NewArray (›size ›, initialValue!!) This is a factory method that creates a new array. If a size is present, the new array will have the specified number of elements, initialized to nil. If an initial value is present, the array elements are initialized to that value. The original value (used as the factory) is not affected. EXAMPLE
______________________________________
Dim factory As New WValue, vArray As WValue
Set vArray = factory.NewArray
Debug.Print vArray.GetString
-> ›!
Set vArray = factory.NewArray(4)
Debug.Print vArray.GetString
-> ›nil, nil, nil, nil!
Set vArray = factory.NewArray(4, "Fred")
Debug.Print vArray.GetString
-> ›"Fred", "Fred", "Fred", "Fred"!
______________________________________
NewBinary binaryValue=factoryValue.NewBinary (contents, class) EXAMPLE
______________________________________
Dim factory As New WValue, v As WValue
Set v = factory.NewBinary("contents", "class")
Debug.Print v.GetString
-> ›binary: class "contents"!
______________________________________
valueobject=factoryValue.NewXxxxx (initialValue ) These factory methods use an existing value object to create another value object of a specific type, with an initial value. The existing value object is not affected. Example
______________________________________
Dim factory As New WValue
Dim v As WValue
Set v = factory.NewLong(42)
Debug.Print v.GetString
-> 42
Set v = factory.NewString("This is a string")
Debug.Print v.GetString
-> "This is a string"
______________________________________
Example 2 One use of the factory methods is to declare a global, gv, like this: Global gV As New WValue Then a factory method is called on gV any time a new value object 104 is desired:
______________________________________
Set onlineUsers = gV.NewArray
Set onlineServices = gV.NewArray
Set sharedInfo = gV.NewMap
______________________________________
NewMap mapValue=factoryValue.NewMap This method uses an existing value object to create a new, empty map value object 104. EXAMPLE
______________________________________
Dim factory As New WValue
Dim v As WValue
Set v = factory.NewMap
v.Set "a", 42
Debug.Print v.GetString
-> {a: 42}
______________________________________
NewSet setValue=factoryValue.NewSet This method uses an existing value object 104 to create a new, empty set. EXAMPLE
______________________________________
Dim factory As New WValue
Dim v As WValue
Set v = factory.NewSet
v.Add "a"
v.Add "a"
v.Add "b"
Debug.Print v.GetString
-> ›.sub.-- sortedset: "a", "b"!
______________________________________
NewSorted sortedValue=factoryValue.New Sorted This method uses an existing value object 104 to create a new, empty sorted array. EXAMPLE
______________________________________
Dim factory As New WValue
Dim v As WValue
Set v = factory.NewSorted
v.Add "a"
v.Add "a"
v.Add "b"
Debug.Print v.GetString
-> ›.sub.-- sorted: "a", "a", "b"!
______________________________________
NewValue value=factoryValue.Newvalue (string) This factory method uses an existing value object 104 to create a new one from a string. The string is the print-representation of a value (e.g. as produced by GetString). EXAMPLE
______________________________________
Dim factory As New WValue
Dim v As WValue
Set v = factory.NewValue("{a:1, b:›1,2,3!, c:""Fred""}")
Debug.Print v.GetString
-> {a: 1, b: ›1, 2, 3!, c: "Fred"}
______________________________________
Op "ArrayToMap" Set value2=value.Op("ArrayToMap"›, path!) This Op method requires that the path specify an array. The array is used to construct a new map; each array element is used as the key of a map entry. The value of each map entry is set to nil. EXAMPLE
______________________________________
Dim vArray As New WValue
vArray.SetString "›Fred Joe 100 42 `a string`!"
Dim v As New WValue
Set v = vArray.Op("ArrayToMap")
Debug.Print v.GetString
-> {Fred: nil, Joe: nil, 100: nil, 42: nil, .vertline.a string.vertline.:
nil}
______________________________________
Op "GetPat"Op "GetNotPat" Set mapValue=value.Op("GetPat", ›, path,! pattern) Set mapValue=value.Op("GetNotPat", ›, path,! pattern) These Op methods require that the path specify map. The pattern is a string. A new map is constructed, whose entries are copies the map entries whose keys start with (or that do not start with) the specified pattern. EXAMPLE
______________________________________
Dim vMap As New WValue
vMap.SetString "{a.sub.-- able: 1, a.sub.-- baker: 2, b.sub.-- zaphod:3,
b.sub.-- goop:4, x:5}"
Dim v As WValue
Set v = vMap.Op("GetPat", "a.sub.-- ")
Debug.Print v.Getstring
-> {a.sub.-- able: 1, a.sub.-- baker: 2}
Set v = vMap.Op("GetPat", "b.sub.-- ")
Debug.Print v.GetString
-> {b.sub.-- zaphod: 3, b.sub.-- goop: 4}
______________________________________
Op "GetPID" longvalue=value.Op("GetPID") This Op method returns the process ID of the Value object in question. By comparing this to the result of GetPID on a Value object known to be created by the current process, this can be used to determine if another Value object was created in process. EXAMPLE
______________________________________
Dim v As New WValue
Debug.Print v.Op("CetPID")
-> 93
______________________________________
Op "MapToArray" Set arrayValue=value.Op("MapToArray"›, path!) This Op method requires that the path specify a map. An array is returned that consists of the keys of all of the map's entries. EXAMPLE
______________________________________
Dim vMap As New WValue
vMap.SetString "{a:1, b:›1,2,3!, c:`foo`}"
Dim v As WValue
Set v = vMap.Op("MapToArray")
Debug.Print v.GetString
-> ›a,b,c!
______________________________________
Op "MD5" string=value.Op("MD5"›, path!) This Op method computes the MD5 hash (a one-way secure hash) of the Value object in question. It returns a 32-character string of hexadecimal numbers that is the hash. All elements of the value object are taken into consideration; even a slight change to one element of, for example, a map or an array will result in a completely different hash value. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a:1, b:›1,2,3!, c:`fred`}"
Debug.Print v.Op("MD5")
-> cd12fc419e838208727d508447da7a1c
v|a = 2
Debug.Print v.Op("MD5")
-> 3820a22a5e5c804533a67539e6ea6e79
______________________________________
Op "Merge" value.Op("Merge"›, path,! mapValue) This Op method is used to merge maps. The path must refer to a map, which will be the destination of the merge. The mapValue argument must be a map; its map entries are copied into the destination map. If a map entry exists in both maps, the map entry in the destination is overwritten. EXAMPLE
______________________________________
Dim vMap As New WValue
Dim v As New WValue
vMap.SetString "{a:1, b:2}"
v.SetString "{alpha: bravo, delta: tango}"
v.Op "Merge", vMap
Debug.Print v.GetString
-> {alpha: bravo, delta: tango, a: 1, b: 2}
______________________________________
Op "RegGet" value.Op "RegGet", ›path,! rootHandle, registryPath, registryValueName This Op method replaces the value's current value by reading the string contained in a registry entry. The registry entry is assumed to contain a printed value. The rootHandle is the longword of an open registry entry, or one of the well-known registry handles such as HKEY.sub.-- LOCAL.sub.-- MACHINE. The registryPath is the path to the registry entry in question. The registryValueName is the name of a value within the registry entry to get.If the registry entry does not exist, the value becomes nil. EXAMPLE
______________________________________
Const HKEY.sub.-- LOCAL.sub.-- MACHINE = &H80000002
Dim v As New Wvalue
v.SetString "{a: 42, b:›1,2,3!, c: `fred`}"
v.Op "RegSet", HKFY.sub.-- LOCAL.sub.-- MACHINE, "Software.backslash.Xyzzy
",
"valueName"
v.SetNil
v.Op "RegGet", HKEY.sub.-- LOCAL.sub.-- MACHINE, "Software.backslash.Xyzzy
",
"valueName"
Debug.Print v.GetString
-> {a: 42, b: ›1, 2, 3!, c: "fred"}
______________________________________
Op "RegGetString" value.Op "RegGetString", ›path,! rootHandle, registryPath, registryValueName This Op method replaces the value's current value with the string contained in a registry entry. The roothandle is the longword of an open registry entry, or one of the well-known registry handles such as HKEY.sub.-- LOCAL.sub.-- MACHINE. The registryPath is the path to the registry entry in question. The registryValueName is the name of a value within the registry entry to get. EXAMPLE
______________________________________
Const HKEY.sub.-- LOCAL.sub.-- MACHINE = &H80000002
Dim v As New Wvalue
v.Set "This is a string."
v.Op "RegSetString", HKEY.sub.-- LOCAL.sub.-- MACHINE,
"Software.backslash.Xyzzy",
"valueName"
v.SetNil
v.Op "RegGetString", HKEY.sub.-- LOCAL.sub.-- MACHINE,
"Software.backslash.Xyzzy",
"valueName"
Debug.Print v.GetString
-> "This is a string."
______________________________________
Op "RegSet" value.Op "RegSet", ›path,! rootHandle, registryPath, registryValueName This Op method prints (writes the string representation) of the value referred to by the path to the specified registry entry. If the value is nil, the registry entry is removed. The rootHandle is the longword of an open registry entry, or one of the well-known registry handles such as HKEY.sub.-- LOCAL.sub.-- MACHINE. The registryPath is the path to the registry entry in question. The registryValueName is the name of a value within the registry entry to get. EXAMPLE
______________________________________
Const HKEY.sub.-- LOCAL.sub.-- MACHINE = &H80000002
Dim v As New Wvalue
v.SetString "{a:42, b:›1,2,3!, c: `fred`}"
v.Op "RegSet", HKEY.sub.-- LOCAL.sub.-- MACHINE, "Software.backslash.Xyzzy
",
"valueName"
______________________________________
Op "RegSetString" value.Op "RegSetString", ›path,! rootHandle, registryPath, registry ValueName The path must refer to a value object 104 that is a string. This Op method writes the string referred to by the path to the specified registry entry. The rootHandle is the longword of an open registry entry, or one of the well-known registry handles such as HKEY.sub.-- LOCAL.sub.-- MACHINE. The registryPath is the path to the registry entry in question. The registryValueName is the name of a value within the registry entry to get. EXAMPLE
______________________________________
Const HKEY.sub.-- LOCAL.sub.-- MACHINE = &H80000002
Dim v As New Wvalue
v.Set "This is a string."
v.Op "RegSetString", HKEY.sub.-- LOCAL.sub.-- MACHINE, "Software.backslash
.Xyzzy",
f "valueName"
______________________________________
Op "SortBy" value.Op "SortBy", ›path,! sortOrder The value specified by the path should be an array of arrays. These inner arrays are rearranged in the outer array in a specified sorting order. For example, assume a set of arrays describing people, account balances:
______________________________________
› ›"Allen", "Appleseed", 100.45!,
›"Xavier", "Zarko", -38.61!,
›"Monty", "Mumfred", 4.32!
______________________________________
The arrays may be sorted by the person's last name by specifying that the second field be sorted on before any others:
______________________________________
Dim v As New WValue
v.SetArray
v.SetString 0, "›`Allen`, `Appleseed`, 100.45!"
v.SetString 1, "›`Xavier`, `Zarkot`, -38.61!"
v.SetString 2, "›`Monty`, `Mumfred`, 4.32!"
v.Op "SortBy", v.NewValue("›1!")
Debug.Print v.pp
.fwdarw. ››"Allen", "Appleseed", 100.45!,
›"Monty", "Mumfred", 4.32!,
›"Xavier", "Zarko", -38.61!
!
______________________________________
The sortOrder parameter controls how the inner arrays are sorted. It is an array whose elements indicate the order in which to consider elements of the sub-arrays. In this case, the sort order: . . NewValue("›1!") is used, indicating that the second field be the primary sort key. (The factory method NewValue is used to create a temporary sort order array). Likewise, the account balance may be sorted:
______________________________________
v.Op "SortBy", v.NewValue("›2!")
Debug.Print v.pp
.fwdarw. ››"Xavier", "Zarko", -38.61!,
›"Monty", "Mumfred", 4.32!,
›"Allen", "Appleseed", 100.45!
!
______________________________________
By following a sort key with the string "r", the sort is performed in reverse order:
______________________________________
v.Op "SortBy", v.NewValue("›2 `r`!")
Debug.Print v.pp
.fwdarw. ››"Allen", "Appleseed", 100.45!,
›"Monty", "Mumfred", 4.32!,
›"Xavier", "Zarko", -38.61!,
!
______________________________________
Op "StripPat" Op "StripNotPat" value.Op "StripPat", ›path,! pattern value.Op "StripNotPat", ›path,! pattern This method expects the value to be a map. The pattern is a string. All map elements whose keys start with (or that do not start with) the specified pattern are removed from the map. EXAMPLE
______________________________________
Dim v As New WValue, v2 As WValue
v.SetString "{a:1, aa:2, b:1, bb:2}"
Set v2 = v.Clone
v2.Op "StripPat", "a"
Debug.Print v2.GetString
.fwdarw. {b:1,bb:2}
Set v2 = v.Clone
v2.Op "StripNotPat", "a"
Debug.Print v2.GetString
.fwdarw. {a:1, aa:2}
______________________________________
Op"ToLower" value.Op "ToLower", ›path! The value referenced by the path must be a string. The contents of the string is converted to lowercase. Example 1
______________________________________
Dim v As New WValue
v.Set "CAPTAIN DREEDLE"
v.Op "ToLower"
Debug.Print v.Get
.fwdarw. captain dreedle
______________________________________
Example 2
______________________________________
Dim v As New WValue
v.SetString "›`OBSESSED AVENGER`, `SUPERPIIIG|`,
`MEGA COW`!"
v.Op "ToLower", 0
v.Op "ToLower", 1
v.Op "ToLower", 2Debug.Print v.Get
.fwdarw. ›"obsessed avenger", "superpiiig|", "mega cow"!
______________________________________
Remove value.Remove ›path,! item If the path specifies an array, the item must be an array index. The item'th array element is removed. If the path specifies a sorted array or a set, the first value that matches the item's value is removed. If the path specifies a map, item is the key of an element to remove. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›a b c d!"
v.Remove 1
Debug.Print v.GetString
.fwdarw. ›a,c,d!
v.SetSet
v.Add "a"
v.Add "b"
v.Add "c"
v.Add "d"
Debug.Print v.GetString
.fwdarw. ›.sub.-- sortedset: "a", "b", "c", "d"!
v.Remove "c"
Debug.Print v.GetString
.fwdarw. ›.sub.-- sortedset: "a", "b", "d"!
______________________________________
RemoveAll value.RemoveAll ›path! The path must refer to an aggregate. All elements of the aggregate are removed. EXAMPLE
______________________________________
Dim v As New WValue
v.SetMap
v|alpha = 0
v|ralpha = 1
v|boulevard = 2
Debug.Print v.GetString
-> {alpha: 0, ralpha: 1, boulevard: 2}
v.RemoveAll
Debug.Print v.GetString
-> {}
______________________________________
RemoveFirst result=value.RemoveFirst ›path! The path must refer to an array, sorted array or set. The first element of the array is removed and returned. EXAMPLE
______________________________________
Dim v as New WValue
v.SetString "›a b c d!"
Debug.Print v.RemoveFirst
-> a
Debug.Print v.GetString
-> ›b, c, d!
______________________________________
RemoveLast result=value.RemoveLast ›path! The path must refer to an array, sorted array or set. The last element of the array is removed and returned. EXAMPLE
______________________________________
Dim v as New WValue
v.SetString "›a b c d!"
Debug.Print v.RemoveLast
-> d
Debug.Print v.GetString
-> ›a, b, c!
______________________________________
RemoveValue value.RemoveValue ›path,! valueToRemove The path must refer to an aggregate. The first element or map entry with the value of valueToRemove is deleted. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›alpha, beta, gamma, wonk, 30, 40, 50, gronk!"
Debug.Print v.GetString
-> ›alpha, beta, gamma, wonk, 30, 40, 50, gronk!
v.RemoveValue 40
v.RemoveValue "gamma"
Debug.Print v.GetString
-> ›alpha, beta, wonk, 30, 50, gronk!
v.SetMap
v|a = "Brooklyn"
v|b = "Sandusky"
v|c = "Blithering Heights"
Debug.Print v.GetString
-> {a: "Brooklyn", b: "Sandusky", c: "Blithering Heights"}
v.RemoveValue "Sandusky"
Debug.Print v.GetString
-> {a: "Brooklyn", c: "Blithering Heights"}
______________________________________
Set value.Set ›path,! newValue As described above, the data elements of a value object 104 dynamically altered after the value object 104 has been instantiated and give values in its data elements 124. This dynamic alternation is provided by the Set methods. The value specified by the path is set to the new value. If the path refers to an array element or map entry that does not exist, the array is grown as necessary, or a map element is created. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.Set 0, "Fred"
v.Set 1, "John"
v.Set 2, "Cecil"
Debug.Print v.GetString
-> ›"Fred", "John", "Cecil"!
v.SetMap
v.Set "Fred", 1
v.Set "John", 2
v.Set "Cecil", 3
Debug.Print v.GetString
-> {Fred: 1, John: 2, Cecil: 3}
v.Set "A string"
Debug.Print v.GetString
-> "A string"
v.Set 42
Debug.Print v.Get
-> 42
______________________________________
FIG. 7 illustrates a flowchart for basic implementation of a set method. The method is called 700 on a particular value, or data element in a value object 104, as specified by a path expression. The method takes a new type code 120, and new value for the data element. The method determines 702 whether the data element 124 is an aggregate type. If so, the data member 120, including the descriptor 130 is deallocated 704. If not, the method tests 706 whether the value is a blob type. Again, the data member and descriptor is deallocated 708 if necessary. In either of these cases, the method then sets 710 the type code 120 to the new type code 120. If the type code is an aggregate (712), then an aggregate descriptor 130 is allocated, and the descriptor of the new value is copied 714 to the body of the new descriptor 130. If the new type is blob type (716), then a blob descriptor 130 is allocated, and the descriptor 130 of the data value is copied 718. In either case, the actual data values are set 720 to the values in the new data value that have been passed to the method. SetArray value.SetArray › ›path,! size! This causes the value referenced by the path to become an array of the specified size. The array's element's initial values are nil. If the path is empty, the Value object receiving this method becomes an empty array.
______________________________________
Dim v As New WValue
v.SetArray
Debug.Print v.GetString
-> ›!
______________________________________
An array of a particular size can be created by specifying the size:
______________________________________
v.SetArray 5
Debug.Print v.GetString
-> ›nil, nil, nil, nil, nil!
______________________________________
Likewise, using a path, a sub-array can be created as one of the outer array's elements:
______________________________________
v.SetArray 5
v.SetArray 2, 3
Debug.Print v.GetString
-> ›nil, nil, ›nil, nil, nil!, nil, nil!
______________________________________
SetBinary value.SetBinary ›path,! contents, classSymbol This method causes the value specified by the path to become a binary. The initial contents may be a Visual Basic string, or a byte array. The class symbol is a string, or a value object that is a symbol or nil. EXAMPLE
______________________________________
Dim v As New WValue
v.SetBinary "---some contents---", "Dreedle"
Debug.Print v.GetString
-> ›binary: Dreedle "---some contents---"!
v.SetMap
v.SetBinary "someKey", "---some contents---", "Dreedle"
Debug.Print v.GetString
-> {someKey: ›binary: Dreedle "---some contents---"!}
______________________________________
SetClass value.SetClass ›path,! symbol This method allows you to set the class symbol of an array, map or binary. The class symbols of sorted arrays and sets cannot be changed. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v.SetClass "someClass"
Debug.Print v.GetString
.fwdarw. ›someClass:!
v.SetMap
v.SetClass "anotherClass".
Debug.Print v.GetString
.fwdarw. {# anotherClass}
- - contents - - - ", "class"
v.SetClass "yetAnotherClass"
Debug.Print v.GetString
- - contents - - - "!AnotherClass "
______________________________________
SetGMT value.SetGMT ›path,! date This method allows the applications programmer to set a time value that has a specific GMT time, rather than a local time. Normally, the Set method converts any date value to GMT internally. This method permits the programmer to bypass this conversion. The corresponding method, AsGMT, allows the programmer to access a time value as GMT directly. EXAMPLE
______________________________________
Dim v As New WValue
Debug.Print Now
.fwdarw. 12/7/95 6:39:48 PM
v.SetGMT Now
Debug.Print v.Get
.fwdarw. 12/7/95 10:39:48 AM
Debug.Print v.AsGMT
.fwdarw. 12/7/95 6:39:48 PM
______________________________________
SetLength value.SetLength ›path,! length This method is used to set the length of a resizable value. The path must refer to an array, sorted array, set, string, Unicode string or binary. If the new length is smaller than the old length, values at the end of the array, sorted array or set are simply released. If the new length is larger than the old length: for arrays, nils are added at the end of the array. for strings, Unicode strings and binaries, zeros are added to the end of the value. sets and sorted arrays cannot be grown. EXAMPLE
______________________________________
Dim v As New WValue
v.SetArray
v(0) = 0
v(1) = 1
v.SetLength 5
Debug.Print v.GetString
.fwdarw. ›0,1,nil,nil,nil!
v.Set "The Pelagic Argosy sights the land."
v.SetLength 18
Debug.Print v.Get
.fwdarw. The Pelagic Argosy
______________________________________
SetMap value.SetMap ›path! The value specified by the path is turned into an empty map. The previous contents of the value object 104 are lost. EXAMPLE
______________________________________
Dim v As New WValue
v.SetMap
v|a = 42
v|b = v.NewValue("›1,2,3!")
v|c = "Fred"
Debug.Print v.pp
.fwdarw. {a:42,
b:›1,2,3!,
c:"Fred"}
______________________________________
SetNil value.SetNil ›path! The value specified by the path is set to nil. The previous contents of the value object 104 are lost. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a:42, b:›1,2,3!, c:`Fred`}"
Debug.Print v.GetString
.fwdarw. {a: 42, b:›1,2,3!, c: "Fred"}
v.SetNil "b"
Debug;Print v.GetString
.fwdarw. {a:42, b:nil, c:"Fred"}
v.SetNil
Debug.Print v.GetString
.fwdarw. nil
______________________________________
SetSet value.SetSet ›path! The value specified by the path is turned into an empty set. The previous contents of the value object 104 are lost. EXAMPLE
______________________________________
Dim v As New WValue
v.SetSet
v.Add "alpha"
v.Add "Alpha"
v.Add "beta"
Debug.Print v.GetString
.fwdarw. ›.sub.-- sortedset "alpha", "beta"!
______________________________________
SetSorted value.SetSorted ›path! The value specified by the path is turned into an empty sorted array. The previous contents of the value object 104 are lost. EXAMPLE
______________________________________
Dim v As New WValue
v.SetSorted
v.Add "alpha"
v.Add "Alpha"
v.Add "beta"
Debug.Print v.GetString
.fwdarw. ›.sub.-- sorted: "Alpha", "alpha", "beta"!
______________________________________
SetString value.SetString ›path,! string This method sets the value specified by the path to the string's interpreted value. Using the SetString method is an easy way to initialize values. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›a sample array!"
Debug.Print v.GetString
.fwdarw. ›a, sample, array!
v.SetString {.sub.-- a:1, b:›1,2,3!, c:`Fred`, d:{x:1000, y:2000}}"
Debug.Print v.pp
.fwdarw. {a:1,
b:›1,2,3!,
c:"Fred",
d:{x:1000,
y:2000}}
______________________________________
SetSymbol value.SetSymbol ›path,! string The value specified by the path is set to a symbol. The string argument should a string. EXAMPLE
______________________________________
Dim v As New WValue
v.SetSymbol "Froggy"
Debug.Print v.GetString
.fwdarw. Froggy
v.SetString "›an array of symbols!"
Debug.Print v.GetString
.fwdarw. ›an,array,of,symbols!
Debug.Print v.IsSymbol(0), v.IsSymbol(1), v.IsSymbol(2)
.fwdarw. True True True
______________________________________
SetUnicodeChar value.SetUnicodeChar ›path,! number The value specified by the path is set to a Unicode character. EXAMPLE
______________________________________
Dim v As New WValue
v.SetUnicodeChar 12334
Debug.Print v.GetString
-> $.backslash.u302e
v.SetArray 3
v.SetUnicodeChar 1, 12334
Debug.Print v.GetString
-> ›nil, $.backslash.u302e, nil!
______________________________________
SetUnicodeString value.SetUnicodeString ›path,! string The value specified by the path is set to a Unicode string. EXAMPLE
______________________________________
Dim v As New Wvalue
v.SetUnicodeString "A unicode string"
Debug.Print v.GetString
-> #"A.backslash.x00 .backslash.x00u.backslash.x00n.backslash.x00i.backsla
sh.x00c.backslash.x00o.backslash.x00d.backslash.x00e.backslash.x00
.backslash.x00s.backslash.x00t.backslash.x00r.backslash.x00i.backslash.x00
n.backslash.x00g.backslash.x00"
______________________________________
SetVBString value.SetVBString ›path,! string This method is used in conjunction with the result of the strings returned by the method GetVBString. The SetVBString method accepts a string formatted from a value by GetVBString and reconstitutes the value. The only difference between the methods GetString/SetString and GetVBString/SetVBString is that the latter set of methods escape characters (such as quotation marks) in a manner that is friendly to Visual Basic's Input# statement. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "{a: 1, b: ›1, 2, 3!, c: 'Fred'}"
Dim s As String
s = v.GetVBString
Debug.Print s
-> {a: 1, b: ›1, 2, 3!, c: 'qFred'q}
Dim v2 As New WValue
v2.SetVBString s
Debug.Print v2.GetString
-> {a: 1, b: ›1, 2, 3!, c: "Fred"}
______________________________________
Sort value.Sort path The path must refer to an array. The elements of the array are sorted in ascending order. If the array contains values of different types (e.g., strings mixed with numbers), then numbers are sorted before strings. If the array contains any sub-arrays, the sub-arrays are ordered in the outer array in increasing order according to the elements that the sub-arrays contain. EXAMPLE
______________________________________
Dim v As New WValue
v.SetString "›99 -1 42 100 -4!"
v.Sort
Debug.Print v.GetString
-> ›-4, -1, 42, 99, 100!
v.SetString "›Xavier Fred John Allan Queeqog!"
v.Sort
Debug.Print v.GetString
-> ›Allan, Fred, John, Queeqog, Xavier!
v.SetArray
v.SetString 0, "›Xavier 450!"
v.SetString 1, "›Fred 45!"
v.SetString 2, "›Fred -1!"
v.SetString 3, "›Allan 35!"
v.Sort
Debug.Print v.GetString
-> ››Allan, 35!, ›Fred, -1!, ›Fred, 45!, ›Xavier, 450!!
______________________________________
Version string=value.Version This method returns a string indicating a version level of the value object 104, as set by the provider of the application programming environment containing the value object 104 class. EXAMPLE
______________________________________
Dim v As New WValue
Debug.Print v.Version
-> 2.0
______________________________________
In summary, the present invention provides a simple but powerful tool for working with data structures. A value object can contain a rich variety of data types and data elements, including text, tables, numbers, binary objects, arrays, maps, sets and the like. Value objects provide a single, convenient representation for data that works well as a local general-purpose data structure, and that is also easily transported from one computer to another, without the need to use conventional marshalling routines. Value objects support a rich set of data types that allows information to be expressed simply and naturally. When value objects are transmitted or stored, their representation is relatively compact. The semantic structure of the value object is preserved between its memory representation in a computer memory and its transmission representation in a transmission medium. Value objects are self-describing, making it easy to design message formats that are flexible and extensible. There is no inherent need for message format "version numbers," as in conventional messaging systems. Value objects can easily be made persistent by storing them in database tables or text files. This makes store-and-forward services particularly easy to design and implement.
|
Same subclass | ||||||||||