Utilities and Buffer Management

/**
 * Creates a buffer for binary data operations
 * @param input - Initial data (string, ArrayBuffer, or bytes)
 * @param encoding - Encoding format (default: 'raw', also supports 'utf8')
 * @returns ByteStringBuffer instance for data manipulation
 */
forge.util.createBuffer(input?: string | ArrayBuffer, encoding?: string): ByteStringBuffer;

interface ByteStringBuffer {
  /** Add a single byte to the buffer */
  putByte(byte: number): ByteStringBuffer;
  /** Add bytes to the buffer */
  putBytes(bytes: string): ByteStringBuffer;
  /** Add a string to the buffer */
  putString(str: string): ByteStringBuffer;
  /** Add a 16-bit integer in big-endian order */
  putInt16(value: number): ByteStringBuffer;
  /** Add a 24-bit integer in big-endian order */
  putInt24(value: number): ByteStringBuffer;
  /** Add a 32-bit integer in big-endian order */
  putInt32(value: number): ByteStringBuffer;
  /** Add an n-bit integer in big-endian order */
  putInt(value: number, n: number): ByteStringBuffer;
  /** Fill buffer with repeated byte value */
  fillWithByte(byte: number, count: number): ByteStringBuffer;
  
  /** Get a single byte and advance read pointer */
  getByte(): number;
  /** Get bytes and advance read pointer */
  getBytes(count?: number): string;
  /** Get a 16-bit integer in big-endian order and advance read pointer */
  getInt16(): number;
  /** Get a 24-bit integer in big-endian order and advance read pointer */
  getInt24(): number;
  /** Get a 32-bit integer in big-endian order and advance read pointer */
  getInt32(): number;
  /** Get an n-bit integer in big-endian order and advance read pointer */
  getInt(n: number): number;
  /** Get signed n-bit integer using two's complement */
  getSignedInt(n: number): number;
  
  /** Get current buffer length */
  length(): number;
  /** Check if buffer is empty */
  isEmpty(): boolean;
  /** Convert buffer to hexadecimal string */
  toHex(): string;
  /** Convert buffer to string representation */
  toString(): string;
  /** Create a copy of the buffer */
  copy(): ByteStringBuffer;
  /** Clear the buffer */
  clear(): ByteStringBuffer;
  /** Truncate buffer to specified length */
  truncate(count?: number): ByteStringBuffer;
}

const forge = require('node-forge');

// Create buffer from string
const buffer = forge.util.createBuffer('Hello World');

// Create buffer from hex data
const hexBuffer = forge.util.createBuffer();
hexBuffer.putBytes(forge.util.hexToBytes('48656c6c6f'));

// Working with integers
const intBuffer = forge.util.createBuffer();
intBuffer.putInt32(0x12345678);
intBuffer.putInt16(0xABCD);

// Reading data
const data = intBuffer.getInt32(); // 0x12345678
const shortData = intBuffer.getInt16(); // 0xABCD

/**
 * Encode binary data to base64 string
 * @param input - Binary data to encode
 * @param maxline - Optional line length for formatting
 * @returns Base64 encoded string
 */
forge.util.encode64(input: string, maxline?: number): string;

/**
 * Decode base64 string to binary data
 * @param input - Base64 encoded string
 * @returns Binary decoded string
 */
forge.util.decode64(input: string): string;

/**
 * Convert hexadecimal string to binary bytes
 * @param hex - Hexadecimal string (e.g., "48656c6c6f")
 * @returns Binary string representation
 */
forge.util.hexToBytes(hex: string): string;

/**
 * Convert binary bytes to hexadecimal string
 * @param bytes - Binary data string
 * @returns Hexadecimal string representation
 */
forge.util.bytesToHex(bytes: string): string;

// Base64 operations
const data = 'Hello World';
const encoded = forge.util.encode64(data);        // 'SGVsbG8gV29ybGQ='
const decoded = forge.util.decode64(encoded);     // 'Hello World'

// Hex operations
const hexString = '48656c6c6f20576f726c64';       // "Hello World" in hex
const bytes = forge.util.hexToBytes(hexString);   // Binary string
const backToHex = forge.util.bytesToHex(bytes);   // '48656c6c6f20576f726c64'

/**
 * Encode a string to UTF-8 bytes
 * @param str - String to encode
 * @returns UTF-8 encoded binary string
 */
forge.util.encodeUtf8(str: string): string;

/**
 * Decode UTF-8 bytes to string
 * @param bytes - UTF-8 encoded binary data
 * @returns Decoded string
 */
forge.util.decodeUtf8(bytes: string): string;

/**
 * Create a string filled with repeated character
 * @param char - Character to repeat
 * @param length - Number of repetitions
 * @returns String filled with character
 */
forge.util.fillString(char: string, length: number): string;

/**
 * XOR two byte strings
 * @param bytes1 - First byte string
 * @param bytes2 - Second byte string
 * @param count - Number of bytes to XOR
 * @param offset - Starting offset
 * @returns XOR result as string
 */
forge.util.xorBytes(bytes1: string, bytes2: string, count: number, offset: number): string;

/**
 * Check if value is an array
 * @param obj - Value to check
 * @returns True if value is array
 */
forge.util.isArray(obj: any): boolean;

/**
 * Check if value is an ArrayBuffer
 * @param obj - Value to check
 * @returns True if value is ArrayBuffer
 */
forge.util.isArrayBuffer(obj: any): boolean;

/**
 * Check if value is an ArrayBuffer view
 * @param obj - Value to check
 * @returns True if value is ArrayBuffer view
 */
forge.util.isArrayBufferView(obj: any): boolean;

/**
 * Schedule callback for next tick (cross-platform)
 * @param callback - Function to execute
 */
forge.util.nextTick(callback: () => void): void;

/**
 * Schedule callback for immediate execution (cross-platform)
 * @param callback - Function to execute
 */
forge.util.setImmediate(callback: () => void): void;

/**
 * Convert IP address string to binary bytes
 * @param ip - IP address string (IPv4 or IPv6)
 * @returns Binary representation or null if invalid
 */
forge.util.bytesFromIP(ip: string): string | null;

/**
 * Convert binary bytes to IP address string
 * @param bytes - Binary IP address data
 * @returns IP address string
 */
forge.util.bytesToIP(bytes: string): string;

/**
 * Convert IPv4 address to binary bytes
 * @param ip - IPv4 address string (e.g., "192.168.1.1")
 * @returns 4-byte binary string or null if invalid
 */
forge.util.bytesFromIPv4(ip: string): string | null;

/**
 * Convert binary bytes to IPv4 address string
 * @param bytes - 4-byte binary data
 * @returns IPv4 address string
 */
forge.util.bytesToIPv4(bytes: string): string;

/**
 * Convert IPv6 address to binary bytes
 * @param ip - IPv6 address string
 * @returns 16-byte binary string or null if invalid
 */
forge.util.bytesFromIPv6(ip: string): string | null;

/**
 * Convert binary bytes to IPv6 address string
 * @param bytes - 16-byte binary data
 * @returns IPv6 address string
 */
forge.util.bytesToIPv6(bytes: string): string;

/**
 * Store data in storage with automatic JSON encoding
 * @param storage - Storage API object
 * @param key - Storage key
 * @param data - Data to store (automatically JSON encoded)
 * @returns Storage operation result
 */
forge.util.setItem(storage: any, key: string, data: any): any;

/**
 * Retrieve data from storage with automatic JSON decoding
 * @param storage - Storage API object
 * @param key - Storage key
 * @returns Retrieved and decoded data
 */
forge.util.getItem(storage: any, key: string): any;

/**
 * Remove item from storage
 * @param storage - Storage API object
 * @param key - Storage key
 * @returns Storage operation result
 */
forge.util.removeItem(storage: any, key: string): any;

/**
 * Clear items from storage matching key pattern
 * @param storage - Storage API object
 * @param key - Key pattern for matching items to clear
 * @returns Storage operation result
 */
forge.util.clearItems(storage: any, key: string): any;

/**
 * Format a string with substitution parameters (similar to printf)
 * @param format - Format string with %s, %d, etc. placeholders
 * @param ...args - Arguments for substitution
 * @returns Formatted string
 */
forge.util.format(format: string, ...args: any[]): string;

/**
 * Format a number with decimal places and separators
 * @param number - Number to format
 * @param decimals - Number of decimal places
 * @param decimalPoint - Decimal separator character
 * @param thousandsSeparator - Thousands separator character
 * @returns Formatted number string
 */
forge.util.formatNumber(number: number, decimals?: number, decimalPoint?: string, thousandsSeparator?: string): string;

/**
 * Format a byte size to human-readable string
 * @param size - Size in bytes
 * @returns Formatted size string (e.g., "1.5 KB", "2.3 MB")
 */
forge.util.formatSize(size: number): string;

/**
 * Convert 32-bit integer to 4-byte binary string
 * @param integer - 32-bit integer value
 * @returns 4-byte binary string
 */
forge.util.int32ToBytes(integer: number): string;

/**
 * Check if an object is empty (has no enumerable properties)
 * @param obj - Object to check
 * @returns True if object is empty
 */
forge.util.isEmpty(obj: object): boolean;

/**
 * Deflate (compress) data using specified algorithm
 * @param api - Compression API to use
 * @param data - Data to compress
 * @param raw - Whether to output raw deflate data
 * @returns Compressed data
 */
forge.util.deflate(api: object, data: string, raw?: boolean): string;

/**
 * Inflate (decompress) data using specified algorithm
 * @param api - Compression API to use
 * @param data - Data to decompress
 * @param raw - Whether input is raw deflate data
 * @returns Decompressed data
 */
forge.util.inflate(api: object, data: string, raw?: boolean): string;

/**
 * Estimate number of CPU cores available (with callback for async operation)
 * @param options - Configuration options for estimation
 * @param callback - Callback function receiving estimated core count
 */
forge.util.estimateCores(options?: object, callback?: (cores: number) => void): void;

/**
 * Estimate number of CPU cores available (synchronous)
 * @returns Estimated core count
 */
forge.util.estimateCores(): number;

/**
 * Indicates whether running in Node.js environment
 */
forge.util.isNodejs: boolean;

/**
 * Reference to global scope object (cross-platform)
 */
forge.util.globalScope: any;