Class | Qpid::Proton::Codec::Data |
In: |
lib/codec/data.rb
|
Parent: | Object |
The Data class provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data. A Data object contains a tree of AMQP values. Leaf nodes in this tree correspond to scalars in the AMQP type system such as INT or STRING. Interior nodes in this tree correspond to compound values in the AMQP type system such as LIST,MAP, ARRAY, or DESCRIBED. The root node of the tree is the Data object itself and can have an arbitrary number of children.
A Data object maintains the notion of the current sibling node and a current parent node. Siblings are ordered within their parent. Values are accessed and/or added by using the next, prev, enter, and exit methods to navigate to the desired location in the tree and using the supplied variety of mutator and accessor methods to access or add a value of the desired type.
The mutator methods will always add a value after the current node in the tree. If the current node has a next sibling the mutator method will overwrite the value on this node. If there is no current node or the current node has no next sibling then one will be added. The accessor methods always set the added/modified node to the current node. The accessor methods read the value of the current node and do not change which node is current.
The following types of scalar values are supported:
The following types of compound values are supported:
Creates a new instance with the specified capacity.
@param capacity [Fixnum, Object] The initial capacity or content.
If the current node is an array, returns a tuple of the element count, a boolean indicating whether the array is described, and the type of each element. Otherwise it returns +(0, false, nil).
Array data can be accessed by entering the array.
@example
# get the details of thecurrent array count, described, array_type = @data.array # enter the node data.enter # get the next node data.next puts "Descriptor: #{data.symbol}" if described (0...count).each do @data.next puts "Element: #{@data.string}" end
If the current node is a boolean, then it returns the value. Otherwise, it returns false.
@return [Boolean] The boolean value.
If the current node is a character, returns its value. Otherwise, returns 0.
@return [Fixnum] The character value.
If the current node is a decimal128, returns its value. Otherwise, returns 0.
@return [Fixnum] The decimal128 value.
Decodes the first value from supplied AMQP data and returns the number of bytes consumed.
@param encoded [String] The encoded data.
@example
# SCENARIO: A string of encoded data, @encoded, contains the text # of "This is a test." and is passed to an instance of Data # for decoding. @data.decode(@encoded) @data.string #=> "This is a test."
Checks if the current node is a described value.
The described and value may be accessed by entering the described value.
@example
if @data.described? @data.enter puts "The symbol is #{@data.symbol}" puts "The value is #{@data.string}" end
Sets the parent node to the current node and clears the current node.
Clearing the current node sets it before the first child.
If the current node is a float, returns its value. Otherwise, returns 0.
@return [Float] The floating point value.
If the current node is an integer, returns its value. Otherwise, returns 0.
@return [Fixnum] The integer value.
If the current node is a list, this returns the number of elements. Otherwise, it returns zero.
List elements can be accessed by entering the list.
@example
count = @data.list @data.enter (0...count).each type = @data.next puts "Value: #{@data.string}" if type == STRING # ... process other node types end
If the current node is a map, this returns the number of child elements. Otherwise, it returns zero.
Key/value pairs can be accessed by entering the map.
@example
count = @data.map @data.enter (0...count).each do type = @data.next puts "Key=#{@data.string}" if type == STRING # ... process other key types type = @data.next puts "Value=#{@data.string}" if type == STRING # ... process other value types end @data.exit
Advances the current node to its previous sibling and returns its type.
If there is no previous sibling then the current node remains unchanged and nil is return.
Puts an array value.
Elements may be filled by entering the array node and putting the element values. The values must all be of the specified array element type.
If an array is described then the first child value of the array is the descriptor and may be of any type.
@param described [Boolean] True if the array is described. @param element_type [Fixnum] The AMQP type for each element of the array.
@example
# create an array of integer values data = Qpid::Proton::Codec::Data.new data.put_array(false, INT) data.enter data.int = 1 data.int = 2 data.int = 3 data.exit # create a described array of double values data.put_array(true, DOUBLE) data.enter data.symbol = "array-descriptor" data.double = 1.1 data.double = 1.2 data.double = 1.3 data.exit
Puts a described value.
A described node has two children, the descriptor and the value. These are specified by entering the node and putting the desired values.
@example
data = Qpid::Proton::Codec::Data.new data.put_described data.enter data.symbol = "value-descriptor" data.string = "the value" data.exit
Clears the current node and sets the parent to the root node.
Clearing the current node sets it before the first node, calling next will advance to the first node.
If the current node is an unsigned int, returns its value. Otherwise, returns 0.
@return [Fixnum] The unsigned integer value.
If the current value is a UUID, returns its value. Otherwise, it returns nil.
@return [String] The string representation of the UUID.
Puts a UUID value.
The UUID is expected to be in the format of a string or else a 128-bit integer value.
@param value [String, Numeric] A string or numeric representation of the UUID.
@example
# set a uuid value from a string value require 'securerandom' @data.uuid = SecureRandom.uuid # or @data.uuid = "fd0289a5-8eec-4a08-9283-81d02c9d2fff" # set a uuid value from a 128-bit value @data.uuid = 0 # sets to 00000000-0000-0000-0000-000000000000