Class Vectors

java.lang.Object
com.frostwire.jlibtorrent.Vectors
public final class Vectors extends Object
Utility methods for converting between Java and native C++ vector types.

Vectors provides static helper functions to convert between Java collections and SWIG-generated native vector wrappers. These conversions are essential for interoperability between jlibtorrent's Java API and the underlying libtorrent C++ library.

Understanding Vector Conversions:
The native libtorrent library uses C++ vectors (std::vector) for collections. SWIG generates Java wrapper classes for these types (e.g., byte_vector, string_vector). This utility class converts between Java native types and SWIG-wrapped vectors:

  • Byte Vectors: Convert between byte[], String, and native vectors
  • Int Vectors: Convert between int[], lists, and native vectors
  • Long Vectors: Convert between long[], lists, and native vectors
  • String Vectors: Convert between List<String> and native vectors
  • Byte Arrays: Convert between fixed-size arrays (32, 64 bytes) and native arrays

Byte Array Conversions: 

 // Convert native byte_vector to Java byte array
 byte_vector nativeVec = ...; // From libtorrent
 byte[] javaArray = Vectors.byte_vector2bytes(nativeVec);

 // Convert Java byte array to native byte_vector
 byte[] data = new byte[] {1, 2, 3, 4, 5};
 byte_vector nativeVec = Vectors.bytes2byte_vector(data);

 // Batch conversion (more efficient for large arrays)
 byte_vector source = ...;
 byte[] destination = new byte[1024];
 Vectors.byte_vector2bytes(source, destination);

Integer Vector Conversions: 

 // Convert native int_vector to Java int array
 int_vector nativeVec = ...; // From libtorrent
 int[] javaArray = Vectors.int_vector2ints(nativeVec);

 // Convert native int64_vector to Java long array
 int64_vector nativeLongVec = ...;
 long[] javaArray = Vectors.int64_vector2longs(nativeLongVec);

String Vector Conversions: 

 // Convert native string_vector to Java List
 string_vector nativeVec = ...; // From libtorrent
 java.util.List<String> stringList = Vectors.string_vector2list(nativeVec);

 for (String str : stringList) {
     System.out.println(\"String: \" + str);
 }

String Encoding Conversions: 

 // Convert byte_vector to String with specific encoding
 byte_vector data = ...; // From libtorrent

 // UTF-8 encoding (supports international characters)
 String utf8String = Vectors.byte_vector2utf8(data);

 // ASCII encoding (7-bit ASCII only)
 String asciiString = Vectors.byte_vector2ascii(data);

 // Custom encoding
 String customString = Vectors.byte_vector2string(data, \"ISO-8859-1\");

 // Reverse: convert String to byte_vector
 String text = \"Hello, World!\";
 byte_vector utf8Vec = Vectors.ascii2byte_vector(text);\n * byte_vector customVec = Vectors.string2byte_vector(text, \"UTF-8\");

Fixed-Size Byte Array Conversions: 

 // Convert 32-byte fixed array (e.g., SHA-256 hash)
 byte[] hash32 = new byte[32];\n * // ... populate hash ...\n * byte_array_32 nativeArray = Vectors.bytes2byte_array_32(hash32);

 // Convert back
 byte_array_32 native = ...;
 byte[] javaArray = Vectors.byte_array2bytes(native);\n *
 // 64-byte fixed array (e.g., Ed25519 keypair)
 byte_array_64 keyPair = Vectors.bytes2byte_array_64(new byte[64]);
 byte[] javaKeyPair = Vectors.byte_array2bytes(keyPair);

Byte Span Conversions (Const References): 

 // byte_const_span is a read-only reference to byte data
 byte_const_span constSpan = ...;  // From libtorrent
 byte[] data = Vectors.byte_span2bytes(constSpan);\n * System.out.println(\"Data size: \" + data.length);

Creating New Native Vectors: 

 // Create a zero-initialized native byte_vector
 int size = 1024;
 byte_vector nativeVec = Vectors.new_byte_vector(size);

 // Now you can pass it to libtorrent functions that populate it
 libtorrent.some_function_that_fills_vector(nativeVec);

 // Convert result back to Java array
 byte[] result = Vectors.byte_vector2bytes(nativeVec);

Common Use Cases in jlibtorrent: 

 // Creating a torrent (converting file hashes)
 java.util.List<String> hashes = ...;
 string_vector nativeHashes = new string_vector();
 for (String hash : hashes) {
     nativeHashes.add(hash);
 }

 // Reading session statistics
 int64_vector statsVec = session.get_stats();
 long[] stats = Vectors.int64_vector2longs(statsVec);

 // Processing piece hashes
 byte_const_span pieceHashes = torrentInfo.pieces();
 byte[] hashes = Vectors.byte_span2bytes(pieceHashes);

Performance Notes:

  • Conversions create new Java objects; reuse arrays when possible for efficiency
  • Batch conversion methods (e.g., byte_vector2bytes(source, dest)) avoid creating temporary arrays
  • String encoding conversions have overhead; cache results if used repeatedly
  • Native vectors are garbage-collected when no longer referenced
  • Prefer UTF-8 for international text; ASCII for simple byte data

Important Notes:

  • String conversions null-terminate at first zero byte (C string convention)
  • Fixed-size arrays must be exact size (32 or 64 bytes) or conversion will fail
  • SWIG-generated types are from com.frostwire.jlibtorrent.swig package
  • These utilities are internal to jlibtorrent; direct use is rare in application code
See Also:

  • Method Details

    • byte_vector2bytes

      public static byte[] byte_vector2bytes(com.frostwire.jlibtorrent.swig.byte_vector v)

    • byte_vector2bytes

      public static void byte_vector2bytes(com.frostwire.jlibtorrent.swig.byte_vector v, byte[] arr)

    • bytes2byte_vector

      public static com.frostwire.jlibtorrent.swig.byte_vector bytes2byte_vector(byte[] arr)

    • bytes2byte_vector

      public static void bytes2byte_vector(byte[] arr, com.frostwire.jlibtorrent.swig.byte_vector v)

    • int_vector2ints

      public static int[] int_vector2ints(com.frostwire.jlibtorrent.swig.int_vector v)

    • int64_vector2longs

      public static long[] int64_vector2longs(com.frostwire.jlibtorrent.swig.int64_vector v)

    • byte_span2bytes

      public static byte[] byte_span2bytes(com.frostwire.jlibtorrent.swig.byte_const_span v)

    • new_byte_vector

      public static com.frostwire.jlibtorrent.swig.byte_vector new_byte_vector(int size)

    • string_vector2list

      public static List<String> string_vector2list(com.frostwire.jlibtorrent.swig.string_vector v)

    • byte_vector2string

      public static String byte_vector2string(com.frostwire.jlibtorrent.swig.byte_vector v, String encoding)

    • byte_vector2ascii

      public static String byte_vector2ascii(com.frostwire.jlibtorrent.swig.byte_vector v)

    • byte_vector2utf8

      public static String byte_vector2utf8(com.frostwire.jlibtorrent.swig.byte_vector v)

    • string2byte_vector

      public static com.frostwire.jlibtorrent.swig.byte_vector string2byte_vector(String s, String encoding)

    • ascii2byte_vector

      public static com.frostwire.jlibtorrent.swig.byte_vector ascii2byte_vector(String s)

    • bytes2byte_array_32

      public static com.frostwire.jlibtorrent.swig.byte_array_32 bytes2byte_array_32(byte[] arr)

    • byte_array2bytes

      public static byte[] byte_array2bytes(com.frostwire.jlibtorrent.swig.byte_array_32 v)

    • byte_array2bytes

      public static byte[] byte_array2bytes(com.frostwire.jlibtorrent.swig.byte_array_64 v)

    • bytes2byte_array_64

      public static com.frostwire.jlibtorrent.swig.byte_array_64 bytes2byte_array_64(byte[] arr)