Binary Data Import/Export



[1]
strX.value() Evaluate string's content and convert to value
  Returns Director value / <err>
     
  Description Converts the string to a Director value - same as value( strX.string )
     
  Examples s=_s("[#a:1, #b:2]")
put s.value()
-- [#a: 1, #b: 2]
put s.value()[1]
-- 1
     
  Notes As opposed to the strX.value property, it is possible to directly access the properties of the returned object, as shown above.

[2]
strX.hexBlock() Export Hex Block
  Returns strS / <err>
     
  Description Returns a new string, containing the strX's binary data in hexadecimal format
     
  Examples s=_s("a word")
hb=s.hexBlock()
put hb
-- 6120776F7264
     
  Notes The codepage of the new object will be the strX's CP.

[3]
strS.hexBlockToS({cp}) / hexBlockToD Convert Hex Block to string
  Returns strS / <err>
  CP Optional code page to be used as the decoded string's code page.
     
  Description Converts a hexBlock to a str object.
If strS is actually a DDS or the size of strS is not even, an <err> is returned (since two hex digits per byte are required).
For hexBlockToD(), if the strX's data is not a product of 4, an <err> is returned (four hex digits per DDS digit).
     
  Examples s=_s("a word")
hb=s.hexBlock()
put hb
-- 6120776F7264
put hb.hexBlockToS()
-- a word

d=_d("a word")
hb=d.hexBlock()
put hb
-- 6100200077006F0072006400
put hb.hexBlockToD()
-- a word

put _s("ww").hexBlockToS()
-- <xErr 66624 InvalidData>
     
  Notes

The codepage of the new object will be the strX's CP.

In future versions, these commands will be moved to the list class's command's set.


[4]
strX.byteList( {#hex / #dHex} ) / .dgtList / .charList Export byte / digit / character values List
  Returns list / <err>
  #hex The list values will be hexadecimal strings
  #dHex The list values will be hexadecimal director strings
     
  Description Exports a string's byte, digit or character values as a list.
     
  Examples d=_d("ab-ΓΔ")
put d.byteList()
-- [97, 0, 98, 0, 45, 0, 147, 3, 148, 3]
put d.dgtList(#hex)
-- [0061, 0062, 002D, 0393, 0394]
put d.charList(#dHex)
-- ["0061", "0062", "002D", "0393", "0394"]

s=_s("キ") --Japanese character (cp 932) as displayed on Shift JIS system.
put s.byteList()
-- [131, 76]
put s.dgtList()
-- [131, 76]
put s.charList()
-- [33612]
     
  Notes Exporting bytes or digits is faster than exporting characters. Unless working with MBCS strings, or non UCS-2 strings, exporting dList and cList produce the same results, but dList is faster to create.

[5]
strX.byteListToStr(list) / .dgtListToStr / .charListToStr Byte / digit / character values List to String
  Returns strS / strD / <err>
  list list of integer or hex string values
     
  Description Converts a list of byte/digit/character values to a str object.
The type of the object to be created depends on strX's type - if strX is a SDS, a strS will be created. Otherwise, a strD. The codepage of the new object will be the strX's CP.
If the operation fails, an <err> will be returned instead.
     
  Examples dBytesList=_d("ab-ΓΔ").byteList()
put _d().byteListToStr(dBytesList)
-- ab-ΓΔ

s=_s("キ") --Japanese character (cp 932) as displayed on Shift JIS system.
sCharList = s.charList(#dirHex)
put sCharList
-- ["834C"]

put _s("", 932).charListToStr( ["834C"]).pop()
-- ƒL    --result as displayed on non - shift jis systems.
     
  Notes

On the last example, the double-byte character キ is displayed as two characters on non Japanese systems. This is normal, since the Xtra returns the SDS data as is to Director. Internally however, the two bytes are treated as a single character. If e.g. the length of the string is requested, the Xtra will check the string's code page, and return 1, instead of 2 that Director will return (since it's string objects are not utilizing code pages) for the same string.

In future versions, these commands will be moved to the list class's command's set.