Buffer API (বাফার)

Binary data handling for efficient manipulation of raw bytes, file I/O, network protocols, and encoding conversions.

Overview

The Buffer API provides powerful tools for working with binary data in BanglaCode. Unlike strings that handle text, Buffers work with raw bytes, making them essential for:

File I/O: Reading and writing binary files (images, audio, video)
Network protocols: Building custom binary protocols (headers, payloads, checksums)
Encoding conversions: Converting between UTF-8, hex, base64
Performance: Efficient memory usage for large data processing

💡 Key Concept: Buffers are thread-safe and immutable by design. Operations that modify buffers return new Buffer instances, preventing accidental data corruption in concurrent code.

Quick Start

// Create a buffer with size
dhoro buf = buffer_banao(10);  // 10-byte buffer

// Create buffer from string
dhoro textBuf = buffer_theke("Hello World");

// Create buffer from byte array
dhoro byteBuf = buffer_theke([72, 101, 108, 108, 111]);

// Convert buffer to string
dhoro text = buffer_text(byteBuf);
dekho(text);  // "Hello"

// Concatenate buffers
dhoro combined = buffer_joro(textBuf, byteBuf);

// Slice buffer
dhoro slice = buffer_angsho(combined, 0, 5);

API Reference

buffer_banao(size)

বাফার বানাও - Create buffer

Creates a new Buffer with the specified size in bytes, initialized with zeros.

dhoro buf = buffer_banao(1024);  // 1KB buffer filled with zeros

Parameters:

size (Number) - Size in bytes (must be positive)

Returns: Buffer object

buffer_theke(data)

বাফার থেকে - Buffer from

Creates a Buffer from a string or byte array. Supports UTF-8 encoding for strings.

// From string
dhoro buf1 = buffer_theke("Hello");

// From byte array
dhoro buf2 = buffer_theke([72, 101, 108, 108, 111]);

// Both create identical buffers representing "Hello"

Parameters:

data (String | Array) - Source data (string or byte array)

Returns: Buffer object

buffer_joro(buf1, buf2, ...)

বাফার জোড়ো - Join buffers

Concatenates multiple buffers into a single buffer. Accepts variable number of arguments.

dhoro header = buffer_theke([255, 1]);
dhoro body = buffer_theke("Data");
dhoro footer = buffer_theke([171, 205]);

dhoro message = buffer_joro(header, body, footer);
// Result: [255, 1, 68, 97, 116, 97, 171, 205]

Parameters:

...buffers (Buffer) - Buffers to concatenate (at least 1)

Returns: New combined Buffer

buffer_text(buf, encoding?)

বাফার টেক্সট - Buffer to text

Converts a Buffer to a string using the specified encoding. Defaults to UTF-8.

dhoro buf = buffer_theke([72, 101, 108, 108, 111]);

dhoro utf8 = buffer_text(buf);           // "Hello"
dhoro utf8Explicit = buffer_text(buf, "utf8");  // "Hello"
dhoro hex = buffer_text(buf, "hex");     // "48656c6c6f"

Parameters:

buf (Buffer) - Buffer to convert
encoding (String, optional) - Encoding type ("utf8", "hex", "base64")

Returns: String representation

buffer_lekho(buf, data, offset)

বাফার লেখো - Write to buffer

Writes string data to a buffer at the specified offset. Returns number of bytes written.

dhoro buf = buffer_banao(20);

buffer_lekho(buf, "Hello", 0);   // Write at start
buffer_lekho(buf, "World", 10);  // Write at offset 10

dhoro text = buffer_text(buf);   // "Hello\x00\x00\x00\x00\x00World..."

Parameters:

buf (Buffer) - Target buffer (modified in place)
data (String) - String to write
offset (Number) - Starting position (must be within buffer bounds)

Returns: Number of bytes written

buffer_angsho(buf, start, end?)

বাফার অংশ - Buffer slice

Extracts a section of the buffer. If end is omitted, slices from start to end of buffer.

dhoro buf = buffer_theke("Hello World");

dhoro hello = buffer_angsho(buf, 0, 5);   // "Hello"
dhoro world = buffer_angsho(buf, 6, 11);  // "World"
dhoro tail = buffer_angsho(buf, 6);       // "World" (from 6 to end)

Parameters:

buf (Buffer) - Source buffer
start (Number) - Starting index (inclusive)
end (Number, optional) - Ending index (exclusive, defaults to buffer length)

Returns: New Buffer containing the slice

buffer_tulona(buf1, buf2)

বাফার তুলনা - Compare buffers

Compares two buffers lexicographically. Returns -1, 0, or 1.

dhoro buf1 = buffer_theke("ABC");
dhoro buf2 = buffer_theke("ABC");
dhoro buf3 = buffer_theke("DEF");

buffer_tulona(buf1, buf2);  // 0 (equal)
buffer_tulona(buf1, buf3);  // -1 (buf1 < buf3)
buffer_tulona(buf3, buf1);  // 1 (buf3 > buf1)

Parameters:

buf1 (Buffer) - First buffer
buf2 (Buffer) - Second buffer

Returns: Number (-1, 0, or 1)

-1 if buf1 < buf2
0 if buf1 == buf2
1 if buf1 > buf2

buffer_hex(buf)

বাফার হেক্স - Buffer to hex

Converts a buffer to hexadecimal string representation (lowercase).

dhoro buf = buffer_theke([255, 0, 127, 16]);
dhoro hex = buffer_hex(buf);
dekho(hex);  // "ff007f10"

Parameters:

buf (Buffer) - Buffer to convert

Returns: Hexadecimal string

buffer_copy(target, source, targetStart)

বাফার কপি - Copy buffer

Copies data from source buffer to target buffer starting at the specified offset.

dhoro target = buffer_banao(20);
dhoro source = buffer_theke("Hello");

dhoro written = buffer_copy(target, source, 0);
dekho(written);  // 5 (bytes copied)

dhoro text = buffer_text(target);
dekho(text);  // "Hello\x00\x00\x00\x00..."

Parameters:

target (Buffer) - Destination buffer (modified in place)
source (Buffer) - Source buffer
targetStart (Number) - Starting offset in target

Returns: Number of bytes copied

Real-World Examples

Example 1: Binary Network Protocol

Build a custom binary protocol message with header, payload, and checksum.

// Define protocol structure:
// - Header: 3 bytes (magic 255, version, message type)
// - Payload: variable length (UTF-8 string)
// - Checksum: 2 bytes

// Build message
dhoro header = buffer_theke([255, 1, 2]);  // Magic=255, Version=1, Type=2
dhoro payload = buffer_theke("Important data");
dhoro checksum = buffer_theke([171, 205]);  // Simple checksum

// Combine all parts
dhoro message = buffer_joro(header, payload, checksum);
dekho("Total message size:", dorghyo(buffer_text(message)), "bytes");

// Parse received message
dhoro receivedHeader = buffer_angsho(message, 0, 3);
dhoro receivedPayload = buffer_angsho(message, 3, 17);
dhoro receivedChecksum = buffer_angsho(message, 17);

// Verify magic number
dhoro magicByte = buffer_angsho(receivedHeader, 0, 1);
jodi (buffer_tulona(magicByte, buffer_theke([255])) == 0) {
    dekho("Valid protocol message");
    dekho("Payload:", buffer_text(receivedPayload));
} nahole {
    dekho("Invalid magic number");
}

Example 2: File Encoding Conversion

Read a file, convert its encoding, and write it back.

// Read file as binary
dhoro fileContent = poro("input.txt");
dhoro buf = buffer_theke(fileContent);

// Convert to hex for inspection or transmission
dhoro hexContent = buffer_hex(buf);
dekho("Hex representation:", hexContent);

// Write hex to file for debugging
lekho("output.hex", hexContent);

// Convert back to UTF-8 and process
dhoro text = buffer_text(buf, "utf8");
dekho("Original text:", text);

Example 3: Efficient Binary Data Processing

Process large binary data in chunks to optimize memory usage.

// Simulate reading a large file in chunks
dhoro largeData = buffer_theke("This is a very long data stream that needs processing...");
dhoro chunkSize = 10;
dhoro totalChunks = 0;

// Process in chunks
dhoro offset = 0;
jotokkhon (offset < dorghyo(buffer_text(largeData))) {
    // Extract chunk
    dhoro chunk = buffer_angsho(largeData, offset, offset + chunkSize);
    
    // Process chunk (e.g., search for pattern, transform data)
    dhoro chunkText = buffer_text(chunk);
    dekho("Processing chunk", totalChunks + 1, ":", chunkText);
    
    offset = offset + chunkSize;
    totalChunks = totalChunks + 1;
}

dekho("Total chunks processed:", totalChunks);

Example 4: Low-Level Byte Manipulation

Direct byte-level operations for performance-critical code.

// Create buffer with specific bytes
dhoro buf = buffer_banao(8);

// Write integers as bytes
buffer_lekho(buf, "AB", 0);  // First 2 bytes
buffer_lekho(buf, "CD", 4);  // Bytes 4-5

// Read specific sections
dhoro part1 = buffer_angsho(buf, 0, 2);
dhoro part2 = buffer_angsho(buf, 4, 6);

dekho("Part 1:", buffer_text(part1));
dekho("Part 2:", buffer_text(part2));

// Compare parts
jodi (buffer_tulona(part1, part2) != 0) {
    dekho("Parts are different");
}

Best Practices

✅ DO:

Pre-allocate buffers: Use buffer_banao() with known size for better performance
Reuse buffers: When processing streams, reuse buffer instances to reduce allocations
Use slicing for parsing: buffer_angsho() is efficient for extracting protocol parts
Validate buffer sizes: Always check bounds before writing to prevent overflows
Choose appropriate encoding: Use hex for debugging, UTF-8 for text, binary for performance

❌ DON'T:

Don't concatenate repeatedly: Use buffer_joro() with all buffers at once, not in a loop
Don't use buffers for small strings: Regular strings are more efficient for text-only data
Don't ignore encoding: Always specify encoding when converting to/from strings
Don't assume immutability: buffer_lekho() and buffer_copy() modify buffers in place
Don't forget to validate: Check buffer sizes before operations to prevent runtime errors

Performance Considerations

⚡ Optimization Tips:

Batch operations: Combine multiple small buffers into one with buffer_joro() instead of multiple concatenations
Buffer pooling: For high-throughput applications, reuse buffer instances instead of creating new ones
Avoid conversions: Keep data in buffer form as long as possible; convert to string only when needed
Use appropriate sizes: Allocate buffers with the exact size needed to avoid wasted memory
Slicing is cheap: buffer_angsho() creates a view, making it efficient for parsing large data

Common Use Cases

Binary File I/O

Read/write images, audio, video, or any binary format efficiently without text conversion overhead.

Network Protocols

Build custom binary protocols with headers, payloads, and checksums for efficient network communication.

Encoding Conversions

Convert between UTF-8, hex, and base64 encodings for data transmission, storage, or debugging.

Cryptography

Work with raw bytes for encryption, hashing, and digital signatures where binary precision is critical.

Related Features

File I/O Functions Networking Async/Await

Summary

The Buffer API provides powerful, performance-optimized tools for working with binary data in BanglaCode. Whether you're building network protocols, processing binary files, or handling encoding conversions, Buffers offer the low-level control and efficiency you need.

Key takeaways: Use buffer_banao() for pre-allocation, buffer_joro()for combining data, and buffer_angsho() for efficient parsing. Always validate buffer sizes and choose appropriate encodings for your use case.