Buffer Manipulation

/**
 * Copy data from this buffer to a target buffer
 * @param targetBuffer - Buffer to copy data to
 * @param targetStart - Offset in target buffer to start writing (default: 0)
 * @param sourceStart - Offset in source buffer to start reading (default: 0)
 * @param sourceEnd - Offset in source buffer to stop reading (default: buffer.length)
 * @returns Number of bytes copied
 */
copy(targetBuffer: Buffer, targetStart?: number, sourceStart?: number, sourceEnd?: number): number;

const source = Buffer.from('Hello World');
const target = Buffer.alloc(20);

// Basic copy (entire buffer)
const bytesCopied1 = source.copy(target);
console.log(target.toString()); // "Hello World"

// Copy with target offset
target.fill(0); // Clear buffer
const bytesCopied2 = source.copy(target, 5);
console.log(target.toString()); // "     Hello World"

// Copy partial data
target.fill(0);
const bytesCopied3 = source.copy(target, 0, 6, 11); // Copy "World"
console.log(target.toString()); // "World"

// Complex copy operation
const src = Buffer.from('ABCDEFGHIJ');
const dst = Buffer.alloc(10, '-');
src.copy(dst, 2, 3, 7); // Copy "DEFG" to position 2
console.log(dst.toString()); // "--DEFG----"

/**
 * Create a new buffer that references a portion of this buffer
 * @param start - Start offset (default: 0)
 * @param end - End offset (default: buffer.length)
 * @returns New buffer sharing memory with original
 */
slice(start?: number, end?: number): Buffer;

const buf = Buffer.from('Hello World');

// Full slice (copy)
const full = buf.slice();
console.log(full.toString()); // "Hello World"

// Partial slice
const hello = buf.slice(0, 5);
console.log(hello.toString()); // "Hello"

const world = buf.slice(6);
console.log(world.toString()); // "World"

// Negative indices (from end)
const last3 = buf.slice(-3);
console.log(last3.toString()); // "rld"

// Memory sharing behavior
const original = Buffer.from('ABCD');
const slice = original.slice(1, 3);
slice[0] = 0x58; // Change 'B' to 'X'
console.log(original.toString()); // "AXCD" (original is modified!)

/**
 * Fill buffer with specified value
 * @param value - Value to fill with (string, number, or Buffer)
 * @param offset - Start offset (default: 0)
 * @param end - End offset (default: buffer.length)
 * @param encoding - Encoding for string values (default: 'utf8')
 * @returns This buffer for chaining
 */
fill(value: string | number | Buffer, offset?: number, end?: number, encoding?: string): Buffer;

// Fill with number (byte value)
const buf1 = Buffer.alloc(10);
buf1.fill(0x41); // Fill with 'A' (ASCII 65)
console.log(buf1.toString()); // "AAAAAAAAAA"

// Fill with string
const buf2 = Buffer.alloc(10);
buf2.fill('abc'); // Repeats "abc" pattern
console.log(buf2.toString()); // "abcabcabca"

// Fill partial range
const buf3 = Buffer.alloc(10, '-');
buf3.fill('X', 2, 8);
console.log(buf3.toString()); // "--XXXXXX--"

// Fill with different encodings
const buf4 = Buffer.alloc(4);
buf4.fill('FF', 0, 4, 'hex'); // Each byte becomes 0xFF
console.log(buf4); // <Buffer ff ff ff ff>

// Fill with another buffer
const pattern = Buffer.from('AB');
const buf5 = Buffer.alloc(8);
buf5.fill(pattern);
console.log(buf5.toString()); // "ABABABAB"

/**
 * Test equality with another buffer
 * @param otherBuffer - Buffer to compare with
 * @returns True if buffers have identical content
 */
equals(otherBuffer: Buffer): boolean;

/**
 * Compare buffers lexicographically
 * @param target - Buffer to compare with
 * @param targetStart - Start offset in target (default: 0)
 * @param targetEnd - End offset in target (default: target.length)
 * @param sourceStart - Start offset in source (default: 0)
 * @param sourceEnd - End offset in source (default: this.length)
 * @returns -1, 0, or 1 for less than, equal, or greater than
 */
compare(target: Buffer, targetStart?: number, targetEnd?: number, sourceStart?: number, sourceEnd?: number): number;

/**
 * Static method to compare two buffers
 * @param buf1 - First buffer
 * @param buf2 - Second buffer  
 * @returns -1, 0, or 1 for less than, equal, or greater than
 */
Buffer.compare(buf1: Buffer, buf2: Buffer): number;

const buf1 = Buffer.from('ABC');
const buf2 = Buffer.from('ABC');
const buf3 = Buffer.from('ABD');

// Equality testing
console.log(buf1.equals(buf2)); // true
console.log(buf1.equals(buf3)); // false

// Comparison (lexicographic)
console.log(buf1.compare(buf2)); // 0 (equal)
console.log(buf1.compare(buf3)); // -1 (buf1 < buf3)
console.log(buf3.compare(buf1)); // 1 (buf3 > buf1)

// Static comparison
console.log(Buffer.compare(buf1, buf2)); // 0
console.log(Buffer.compare(buf1, buf3)); // -1

// Partial comparison
const long1 = Buffer.from('ABCDEF');
const long2 = Buffer.from('XYZDEF');
const result = long1.compare(long2, 3, 6, 3, 6); // Compare "DEF" parts
console.log(result); // 0 (equal)

// Sorting buffers
const buffers = [Buffer.from('Z'), Buffer.from('A'), Buffer.from('M')];
buffers.sort(Buffer.compare);
console.log(buffers.map(b => b.toString())); // ['A', 'M', 'Z']

/**
 * Find first occurrence of value in buffer
 * @param value - Value to search for (string, number, or Buffer)
 * @param byteOffset - Start offset for search (default: 0)
 * @param encoding - Encoding for string values (default: 'utf8')
 * @returns Index of first occurrence or -1 if not found
 */
indexOf(value: string | number | Buffer, byteOffset?: number, encoding?: string): number;

/**
 * Find last occurrence of value in buffer
 * @param value - Value to search for (string, number, or Buffer)
 * @param byteOffset - Start offset for reverse search (default: buffer.length - 1)
 * @param encoding - Encoding for string values (default: 'utf8')
 * @returns Index of last occurrence or -1 if not found
 */
lastIndexOf(value: string | number | Buffer, byteOffset?: number, encoding?: string): number;

/**
 * Test if buffer contains value
 * @param value - Value to search for (string, number, or Buffer)
 * @param byteOffset - Start offset for search (default: 0)
 * @param encoding - Encoding for string values (default: 'utf8')
 * @returns True if value is found in buffer
 */
includes(value: string | number | Buffer, byteOffset?: number, encoding?: string): boolean;

const buf = Buffer.from('Hello World Hello');

// Search for strings
console.log(buf.indexOf('Hello'));     // 0 (first occurrence)
console.log(buf.lastIndexOf('Hello')); // 12 (last occurrence)
console.log(buf.includes('World'));    // true

// Search for byte values
console.log(buf.indexOf(0x6c));        // 2 (first 'l')
console.log(buf.lastIndexOf(0x6c));    // 15 (last 'l')

// Search with offset
console.log(buf.indexOf('Hello', 5));  // 12 (skip first occurrence)

// Search for buffer
const pattern = Buffer.from('Wor');
console.log(buf.indexOf(pattern));     // 6

// Search with encoding
const hexBuf = Buffer.from('48656c6c6f', 'hex'); // "Hello"
console.log(buf.indexOf('48656c6c6f', 0, 'hex')); // 0

// Not found cases
console.log(buf.indexOf('xyz'));       // -1
console.log(buf.includes('xyz'));      // false

/**
 * Concatenate array of buffers into single buffer
 * @param list - Array of buffers to concatenate
 * @param totalLength - Total length hint for optimization (optional)
 * @returns New buffer containing concatenated data
 */
Buffer.concat(list: Buffer[], totalLength?: number): Buffer;

const buf1 = Buffer.from('Hello');
const buf2 = Buffer.from(' ');
const buf3 = Buffer.from('World');

// Basic concatenation
const combined = Buffer.concat([buf1, buf2, buf3]);
console.log(combined.toString()); // "Hello World"

// With total length hint (optimization)
const optimized = Buffer.concat([buf1, buf2, buf3], 11);
console.log(optimized.toString()); // "Hello World"

// Empty array
const empty = Buffer.concat([]);
console.log(empty.length); // 0

// Single buffer (returns first buffer)
const single = Buffer.concat([buf1]);
console.log(single === buf1); // true (same reference)

// Truncation with totalLength
const truncated = Buffer.concat([buf1, buf2, buf3], 7);
console.log(truncated.toString()); // "Hello W" (truncated to 7 bytes)

/**
 * Check if object is a Buffer instance
 * @param obj - Object to test
 * @returns True if object is a Buffer
 */
Buffer.isBuffer(obj: any): obj is Buffer;

/**
 * Create debug representation of buffer
 * @returns String representation for debugging
 */
inspect(): string;

const buf = Buffer.from('Hello');
const arr = new Uint8Array([1, 2, 3]);
const obj = { data: [1, 2, 3] };

// Type checking
console.log(Buffer.isBuffer(buf)); // true
console.log(Buffer.isBuffer(arr)); // false
console.log(Buffer.isBuffer(obj)); // false

// Debug inspection
console.log(buf.inspect()); // "<Buffer 48 65 6c 6c 6f>"

// Automatic inspection in console
console.log(buf); // <Buffer 48 65 6c 6c 6f>

// Large buffer inspection (truncated)
const largeBuf = Buffer.alloc(100, 0x41);
console.log(largeBuf.inspect()); // Shows first 50 bytes + "..."

// Buffers created from ArrayBuffer share memory
const ab = new ArrayBuffer(8);
const buf1 = Buffer.from(ab);
const buf2 = Buffer.from(ab, 2, 4); // Offset 2, length 4

buf1[0] = 0x41;
console.log(buf2.buffer === ab); // true (shares memory)

// Slices share memory with original
const original = Buffer.from('ABCD');
const slice = original.slice(1, 3);
slice[0] = 0x58; // Modifies original
console.log(original.toString()); // "AXCD"

// To ArrayBuffer
const buf = Buffer.from('Hello');
const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);

// To Uint8Array (already is one)
const uint8 = new Uint8Array(buf);

// To regular array
const array = Array.from(buf);
console.log(array); // [72, 101, 108, 108, 111]

// From various typed arrays
const int16 = new Int16Array([0x4865, 0x6c6c, 0x6f00]);
const fromInt16 = Buffer.from(int16.buffer);

const buf = Buffer.alloc(10);

try {
  buf.copy(null); // Throws TypeError
} catch (error) {
  console.error('Copy error:', error.message);
}

try {
  buf.slice(20, 30); // Out of bounds - returns empty buffer
  console.log('Slice succeeded'); // This will run
} catch (error) {
  console.error('Slice error:', error.message);
}

try {
  buf.fill('test', -5); // Throws RangeError
} catch (error) {
  console.error('Fill error:', error.message);
}

// Performance tip: Use slice() for views, copy() for independent data
const original = Buffer.alloc(1000000);

// Fast - creates a view
const view = original.slice(100, 200);

// Slower - copies data  
const independent = Buffer.alloc(100);
original.copy(independent, 0, 100, 200);