Blitz3D+ Command Reference

UuidToBytes ( value$,bank[,offset][,layout] )

Parameters

value$ - UUID text in D, N or braced form

bank - destination Bank with at least 16 bytes at offset

offset (optional) - byte position to write at; 0 (default)

layout (optional) - byte order to write:
UUID_BYTES_RFC: RFC network/display order (default)
UUID_BYTES_WINDOWS: mixed-endian Windows GUID / .NET Guid.ToByteArray() order

Description

Writes a UUID into a Bank as exactly 16 raw bytes.

Text UUIDs are 36 characters; binary save files and network packets would rather spend 16 bytes. UuidToBytes converts any accepted UUID text form into raw bytes at the given Bank offset, ready to write with WriteBankAtomic or send over the wire. UuidFromBytes is the exact inverse.

The layout is the famous gotcha of binary UUIDs. UUID_BYTES_RFC writes the bytes in the order the text reads - the portable choice for new file formats and network protocols. UUID_BYTES_WINDOWS writes the mixed-endian Windows GUID layout, matching .NET's Guid.ToByteArray(): the first three groups are little-endian while the final eight bytes keep display order. The same UUID produces different bytes in each layout, so always state which one a file or protocol uses - guessing wrong scrambles every id while still looking like 16 plausible bytes.

Everything is checked before anything is written: invalid UUID text returns 0 and leaves the Bank completely unchanged, while a Bank range without 16 bytes at the offset, or an unknown layout constant, is a programming error. On success it returns true with exactly 16 bytes written.

For the full rules, see the Application Data language reference.

Requires Extended mode.

See also: UuidFromBytes, CreateUuid, UuidValid, NormalizeUuid, CreateBank.

Example

; UuidToBytes Example
; -------------------
; Requires Extended mode.

; A binary save file stores object ids as 16 raw bytes, not text
id$="00112233-4455-6677-8899-aabbccddeeff"
Print "Object id: "+id
Print ""

bank=CreateBank(16)

; UUID_BYTES_RFC writes network/display order - the hex bytes
; appear in the same order as the text
If UuidToBytes(id,bank,0,UUID_BYTES_RFC)=0 Then RuntimeError "Invalid UUID"
Print "RFC layout:     "+BankHex(bank)

; UUID_BYTES_WINDOWS writes the mixed-endian Windows GUID /
; .NET Guid.ToByteArray() layout - the first three groups flip
If UuidToBytes(id,bank,0,UUID_BYTES_WINDOWS)=0 Then RuntimeError "Invalid UUID"
Print "Windows layout: "+BankHex(bank)
Print ""
Print "Always state which layout a file or protocol uses!"

FreeBank bank

Print ""
Print "Press any key to close the example"
WaitKey

End

; Render a Bank's bytes as lowercase hex
Function BankHex$(bank)
    hex_text$=""
    For i=0 To BankSize(bank)-1
        hex_text=hex_text+Right(Hex(PeekByte(bank,i)),2)
    Next
    Return Lower(hex_text)
End Function

Index