unpack

Contents: Description, Arguments, Usage, Sub-Functions Supported Under Version: >1.69 Current Davinci Version: 2.27 64-bit Safe: No Description Unpack binary data from a file, given a template Arguments and Return Values Arguments: A template string and a file name. Return Value: A davinci structure Usage Syntax: unpack(template = STRING, filename = STRING [, skip = 0 ] [, count = INT] [, col_names = STRING or TEXT BUFFER ]) The unpack function reads binary data from the input file, interprets it according to the specified record template, and returns it in a davinci structure. The optional skip parameter specifies the bytes into the file to skip before decoding the file. The optional count parameter specifies the number of records to be unpacked (a negative value means all records). The template is made up of column specifications of the form "A[n][*m]", where, "A" can be one of the following letters: Letter Meaning Allowable byte-sizes ("n") 'a' string 1+ 'I' signed msb int 1-4 'U' unsigned msb int 1-4 'i' signed lsb int 1-4 'u' unsigned lsb int 1-4 'r' lsb real 4, 8 'R' msb real 4, 8 'x' skip 1+ "n" is the size (in bytes), and "m" is the multiplicity, of repeat of "A[n]". If either "m" or "n" is not specified, it is assumed to be one. "*" is part of the syntax. For example, "i4*3" specifies an array of 3- 4-byte little-endian integers. Multiple column specifications are concatenated to form a template of a record. For example, "i4*3r8a5" specifies a 3-column record, with a 3-element array of 4-byte little-endian integers, followed by a little-endian double-float, followed by a character string of five characters. Gaps in the template can be specified using "x", e.g., "i4*3x10r8x5a5" specifies the same record structure as the previous example, except that the fields are non-contiguous. Every field in the record is placed in its own column within a davinci structure with generic names assigned in the form "cn" or "cn_m" unless the user specifies their own column names in the optional argument col_names. The argument col_names can be either a string (if the user is only reading 1 column) or a davinci text buffer (string array). Providing insufficient names will throw and error. Providing extra names is fine. Multiplicity in strings gets split into multiple fields, since davinci text arrays cannot be 3-dimensional. A string column with multiplicity will use only one of the user-provided names and add on "_m" to indicate the multiplicity. Notes: Unpack resizes types if necessary because davinci only supports unsigned bytes and signed shorts and ints. It checks and possibly converts columns with the type on the left to the types on the right: signed bytes -> shorts (required conversion) unsigned shorts -> ints unsigned ints -> doubles (floats have inadequate precision)

DavinciWiki Mini-Nav Bar Contents Functions Function Categories Common Procedures Glossary Download Davinci Change Log News Mailing List Contact Developers davinci-dev [AT] mars.asu.edu All other topics See navigation on the left Major Sub-Functions read filetype Recent Core Changes Change Log Modified On: 11-18-2016