--- url: /api/scripts/extension-modules/core/base/bytes.md --- # bytes The bytes module provides binary data buffer operations for handling raw byte data. This is an extension module of xmake. ::: tip TIP To use this module, you need to import it first: `import("core.base.bytes")` ::: ## bytes * Create a byte buffer #### Function Prototype ::: tip API ```lua bytes(size: , initval: ) bytes(str: ) bytes(buffer: , offset: , size: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | size | Required. Buffer size in bytes | | initval | Optional. Initial value for buffer (number or character) | | str | Required. String to convert to bytes object | | buffer | Required. Source bytes buffer for slice | | offset | Required. Offset position in source buffer | | size | Required. Size of the slice | #### Return Value | Type | Description | |------|-------------| | bytes | Returns a bytes buffer object | #### Usage The bytes constructor supports multiple creation methods, providing flexible buffer creation and management. ##### Create a buffer of specified size ```lua -- Create a 1024-byte buffer local buff = bytes(1024) print("Buffer size:", buff:size()) -- Output: 1024 -- Create buffer and initialize with specified value local buff = bytes(100, 0) -- Initialize to 0 local buff = bytes(100, 255) -- Initialize to 255 local buff = bytes(100, 'A') -- Initialize to character 'A' ``` ##### Create from string Create a bytes object from a string, commonly used to convert strings to binary data: ```lua local buff = bytes("hello world") print(buff:size()) -- Output: 11 print(buff:str()) -- Output: hello world ``` ::: warning WARNING bytes objects created from strings are read-only and cannot be modified. ::: ##### Create a slice Create a slice from an existing bytes object, sharing underlying memory without copying data: ```lua local original = bytes("123456789") local slice = bytes(original, 3, 5) -- Slice bytes 3-5 print(slice:str()) -- Output: 345 ``` ##### Concatenate multiple buffers ```lua -- Concatenate using parameter list local buff = bytes(bytes("123"), bytes("456"), bytes("789")) print(buff:str()) -- Output: 123456789 -- Concatenate using array local buff = bytes({bytes("123"), bytes("456"), bytes("789")}) print(buff:str()) -- Output: 123456789 ``` ##### Create empty buffer ```lua local buff = bytes() -- Empty buffer local buff = bytes({}) -- Empty buffer ``` ##### Index operations bytes objects support accessing and modifying individual bytes through indexing (indices start from 1): ```lua local buff = bytes(9) buff:copy("123456789") -- Read byte local byte_value = buff[1] print(byte_value) -- Output: 49 (ASCII code for '1') -- Modify byte buff[1] = string.byte('2') print(buff:str()) -- Output: 223456789 ``` Access slices through range indexing: ```lua local buff = bytes("123456789") local slice = buff[{1, 4}] print(slice:str()) -- Output: 1234 -- Range assignment local buff = bytes(9) buff[{1, 9}] = bytes("123456789") print(buff:str()) -- Output: 123456789 ``` ##### Concatenation operation Use the `..` operator to concatenate two bytes objects, creating a new buffer: ```lua local buff1 = bytes("123") local buff2 = bytes("456") local buff3 = buff1 .. buff2 print(buff3:str()) -- Output: 123456 ``` ## bytes:size * Get buffer size #### Function Prototype ::: tip API ```lua bytes:size() ``` ::: #### Parameter Description No parameters required for this function. #### Usage Returns the number of bytes in the buffer. ```lua local buff = bytes(1024) print(buff:size()) -- Output: 1024 ``` ## bytes:str * Convert to string #### Function Prototype ::: tip API ```lua bytes:str(start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | start | Start position (optional, default 1) | | last | End position (optional, default buffer size) | #### Usage Converts a bytes object to a string, optionally specifying the conversion range. Parameters: * `start` (optional): Start position, default 1 * `last` (optional): End position, default is buffer size Commonly used to convert data read from network or files to strings: ```lua import("core.base.bytes") local buff = bytes("hello world") print(buff:str()) -- Output: hello world print(buff:str(1, 5)) -- Output: hello print(buff:str(7)) -- Output: world ``` ## bytes:slice * Create a slice #### Function Prototype ::: tip API ```lua bytes:slice(start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | start | Start position | | last | End position | #### Usage Creates a slice of the buffer, returns a new bytes object that shares the underlying memory (no data copying). Parameters: * `start`: Start position * `last`: End position Slicing is an efficient data access method that avoids data copying: ```lua local buff = bytes("123456789") local slice = buff:slice(3, 5) print(slice:str()) -- Output: 345 print(slice:size()) -- Output: 3 ``` ## bytes:clone * Clone the buffer #### Function Prototype ::: tip API ```lua bytes:clone() ``` ::: #### Parameter Description No parameters required for this function. #### Usage Creates a complete copy of the buffer, allocating new memory and copying all data. Unlike slice, clone copies data, so they don't affect each other: ```lua local original = bytes("hello") local cloned = original:clone() print(cloned:str()) -- Output: hello -- Modifying cloned buffer doesn't affect original cloned[1] = string.byte('H') print(cloned:str()) -- Output: Hello print(original:str()) -- Output: hello (unchanged) ``` ## bytes:copy * Copy data to buffer #### Function Prototype ::: tip API ```lua bytes:copy(src: , start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | src | Source data, can be string or bytes object | | start | Source data start position (optional, default 1) | | last | Source data end position (optional, default source data size) | #### Usage Copies data from source to the beginning of the buffer. Parameters: * `src`: Source data, can be string or bytes object * `start` (optional): Source data start position, default 1 * `last` (optional): Source data end position, default is source data size ```lua local buff = bytes(9) buff:copy("123456789") print(buff:str()) -- Output: 123456789 -- Copy only partial data local buff = bytes(5) buff:copy("123456789", 5, 9) print(buff:str()) -- Output: 56789 ``` ## bytes:copy2 * Copy data to specified position #### Function Prototype ::: tip API ```lua bytes:copy2(pos: , src: , start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | pos | Target position | | src | Source data, can be string or bytes object | | start | Source data start position (optional) | | last | Source data end position (optional) | #### Usage Copies data from source to the specified position in the buffer. Parameters: * `pos`: Target position * `src`: Source data, can be string or bytes object * `start` (optional): Source data start position * `last` (optional): Source data end position Used to concatenate multiple segments of data in a buffer: ```lua local buff = bytes(18) buff:copy("123456789") -- Copy to beginning buff:copy2(10, "123456789") -- Copy to position 10 print(buff:str()) -- Output: 123456789123456789 ``` ## bytes:move * Move data to buffer beginning #### Function Prototype ::: tip API ```lua bytes:move(start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | start | Source data start position | | last | Source data end position (optional) | #### Usage Moves the specified range of data within the buffer to the beginning, supporting memory overlap-safe movement. Parameters: * `start`: Source data start position * `last` (optional): Source data end position ```lua local buff = bytes(9):copy("123456789") buff:move(5, 9) print(buff:str()) -- Output: 567896789 (5-9 moved to beginning) ``` ## bytes:move2 * Move data to specified position #### Function Prototype ::: tip API ```lua bytes:move2(pos: , start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | pos | Target position | | start | Source data start position | | last | Source data end position (optional) | #### Usage Moves the specified range of data within the buffer to the specified position. Parameters: * `pos`: Target position * `start`: Source data start position * `last` (optional): Source data end position ```lua local buff = bytes(9):copy("123456789") buff:move2(2, 5, 9) print(buff:str()) -- Output: 156789789 ``` ## bytes:u8 * Read unsigned 8-bit integer #### Function Prototype ::: tip API ```lua bytes:u8(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage Reads a byte from the specified offset as an unsigned 8-bit integer (0-255). ## bytes:u8\_set * Write unsigned 8-bit integer #### Function Prototype ::: tip API ```lua bytes:u8_set(offset: , value: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | | value | Value to write (0-255) | #### Usage Writes an unsigned 8-bit integer to the specified offset. Writes an unsigned 8-bit integer value to the specified offset. ```lua local buff = bytes(10) buff:u8_set(1, 255) local value = buff:u8(1) print(value) -- Output: 255 ``` ## bytes:s8 * Read signed 8-bit integer #### Function Prototype ::: tip API ```lua bytes:s8(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage Reads a byte from the specified offset as a signed 8-bit integer (-128 to 127). ## bytes:u16le * Read unsigned 16-bit integer (little-endian) #### Function Prototype ::: tip API ```lua bytes:u16le(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage 参数Reads 2 bytes from the specified offset as an unsigned 16-bit integer (little-endian byte order). ## bytes:u16le\_set * Write unsigned 16-bit integer (little-endian) #### Function Prototype ::: tip API ```lua bytes:u16le_set(offset: , value: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | | value | Value to write (0-65535) | #### Usage Writes an unsigned 16-bit integer to the specified offset (little-endian byte order). ```lua local buff = bytes(10) buff:u16le_set(5, 12346) local value = buff:u16le(5) print(value) -- Output: 12346 ``` ## bytes:u16be * Read unsigned 16-bit integer (big-endian) #### Function Prototype ::: tip API ```lua bytes:u16be(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage Reads 2 bytes from the specified offset as an unsigned 16-bit integer (big-endian byte order). ## bytes:u16be\_set * Write unsigned 16-bit integer (big-endian) #### Function Prototype ::: tip API ```lua bytes:u16be_set(offset: , value: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | | value | Value to write (0-65535) | #### Usage Writes an unsigned 16-bit integer to the specified offset (big-endian byte order). ## bytes:u32le * Read unsigned 32-bit integer (little-endian) #### Function Prototype ::: tip API ```lua bytes:u32le(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage Reads 4 bytes from the specified offset as an unsigned 32-bit integer (little-endian byte order). ## bytes:u32le\_set * Write unsigned 32-bit integer (little-endian) #### Function Prototype ::: tip API ```lua bytes:u32le_set(offset: , value: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | | value | Value to write (0-4294967295) | #### Usage Writes an unsigned 32-bit integer to the specified offset (little-endian byte order). Used for handling binary protocols and data formats: ```lua local buff = bytes(20) -- Write protocol header (little-endian format) buff:u16le_set(1, 0x1234) -- Magic number buff:u32le_set(3, 100) -- Data length -- Read protocol header local magic = buff:u16le(1) local length = buff:u32le(3) print(string.format("Magic: 0x%04X, Length: %d", magic, length)) ``` ## bytes:u32be * Read unsigned 32-bit integer (big-endian) #### Function Prototype ::: tip API ```lua bytes:u32be(offset: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | #### Usage Reads 4 bytes from the specified offset as an unsigned 32-bit integer (big-endian byte order). ## bytes:u32be\_set * Write unsigned 32-bit integer (big-endian) #### Function Prototype ::: tip API ```lua bytes:u32be_set(offset: , value: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | offset | Byte offset position | | value | Value to write (0-4294967295) | #### Usage Writes an unsigned 32-bit integer to the specified offset (big-endian byte order). ## bytes:dump * Display buffer contents in hexadecimal format #### Function Prototype ::: tip API ```lua bytes:dump(start: , last: ) ``` ::: #### Parameter Description | Parameter | Description | |-----------|-------------| | start | Start position (optional, default 1) | | last | End position (optional, default buffer size) | #### Usage Displays buffer contents in hexadecimal and ASCII format, similar to the hexdump tool. Parameters: * `start` (optional): Start position * `last` (optional): End position Used for debugging binary data, visually displaying memory contents: ```lua local buff = bytes("hello world, this is a test") buff:dump() -- Output similar to: -- 00000000 68 65 6C 6C 6F 20 77 6F 72 6C 64 2C 20 74 68 69 hello world, thi -- 00000010 73 20 69 73 20 61 20 74 65 73 74 s is a test ``` ## bytes:readonly * Check if buffer is read-only #### Function Prototype ::: tip API ```lua bytes:readonly() ``` ::: #### Parameter Description No parameters required for this function. #### Usage Returns true if the buffer is read-only and cannot be modified. bytes objects created from strings are read-only. ```lua local buff1 = bytes("hello") print(buff1:readonly()) -- Output: true (cannot modify) local buff2 = bytes(10) print(buff2:readonly()) -- Output: false (can modify) -- Attempting to modify read-only buffer will raise error local buff = bytes("test") -- buff[1] = 65 -- Error! Read-only buffer cannot be modified ``` ::: tip TIP bytes objects can be seamlessly used across socket, pipe, lz4, and other modules. Pre-creating large buffers and reusing them can reduce memory allocation overhead. ::: ::: warning WARNING * Indices start from 1 (following Lua convention) * bytes objects created from strings are read-only * Slices share memory with the original bytes object * Pay attention to byte order (big-endian/little-endian) when using integer read/write interfaces :::