SSE4E

ByteString - Reference Documentation

Implementation of an immutable binary string, similar to the String class.

Index of Methods

• ByteString() constructor
• and()
• byteAt()
• bytes()
• concat()
• crc()
• equals()
• find()
• getL()
• getLV()
• left()
• neg()
• not()
• or()
• pad()
• right()
• startsWith()
• toBase64()
• toBcd()
• toHex()
• toSigned()
• toString()
• toUnsigned()
• xor()

Constants

Properties

Constructor

Prototype

ByteString(String stringValue, Number encoding)

Description

Create a ByteString object containing the data from stringValue decoded according to format defined in argument encoding

The following encoding formats can be used for the stringValue argument:

HEX - A string containing hexadecimal characters and arbitrary delimiters.

ASCII - A string containing ASCII characters and characters from Latin-1.

UTF8 - A string containing Unicode characters.

BASE64 - A string containing BASE-64 encoded data.

OID - A string containing an object identifier in dotted notation or separated by blanks (This is a proprietary extension to Global Platform Scripting).

Arguments

Exceptions

Example

x = new ByteString("1234", HEX);

assert(x.length == 2);
assert(x.toString() == "12 34");


x = new ByteString("", HEX);

assert(x.length == 0);
assert(x.toString() == "");


x = new ByteString("0x1234 56.78.90+AB#cd'EF", HEX);

assert(x.length == 8);
assert(x.toString() == "12 34 56 78 90 AB CD EF");


x = new ByteString("1234ABCDÄÖÜß", ASCII);

assert(x.length == 12);
assert(x.toString() == "31 32 33 34 41 42 43 44 C4 D6 DC DF");


x = new ByteString("1234ABCDÄÖÜß", UTF8);

assert(x.length == 16);
assert(x.toString() == "31 32 33 34 41 42 43 44 C3 84 C3 96 C3 9C C3 9F");


x = new ByteString("SGVsbG8gV29ybGQ=", BASE64);

assert(x.length == 11);
assert(x.toString(ASCII) == "Hello World");


x = new ByteString("1.2.840.113549.1.1.2", OID);

assert(x.length == 9);
assert(x.toString(OID) == "1.2.840.113549.1.1.2");
assert(x.toString(HEX) == "2A864886F70D010102"); 


x = new ByteString("1 2 840 113549 1 1 2", OID);

assert(x.toString(HEX) == "2A864886F70D010102"); 

and()

Prototype

ByteString and(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.and(y);
assert(z.toString(HEX) == "00A500", HEX);

byteAt()

Prototype

Number byteAt(Number offset)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABCÄÖÜ", ASCII);
assert(typeof(x.byteAt(0)) == "number");
assert(x.byteAt(0) == 0x31);
assert(x.byteAt(3) == 0x41);
assert(x.byteAt(6) == 0xC4);

bytes()

Prototype

ByteString bytes(Number offset)

ByteString bytes(Number offset, Number count)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABCÄÖÜ", ASCII);
y = x.bytes(3, 3);
assert(y.toString(ASCII) == "ABC");

y = x.bytes(6);
assert(y.toString(ASCII) == "ÄÖÜ");

y = x.bytes(9);
assert(y.toString(ASCII) == "");

concat()

Prototype

ByteString concat(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123", ASCII);
y = new ByteString("414243", HEX);

z = x.concat(y);

assert(z.toString(ASCII) == "123ABC");

z = z.concat(new ByteString("", HEX));

assert(z.toString(ASCII) == "123ABC");

crc()

Prototype

ByteString crc(Number method)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("A55A", HEX);
c = x.crc(ByteString.XOR);
assert(c.toString(HEX) == "FF");

x = new ByteString("", HEX);
c = x.crc(ByteString.XOR);
assert(c.toString(HEX) == "00");

equals()

Prototype

Boolean equals(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("414243", HEX);
y = new ByteString("ABC", ASCII);

assert(x.equals(y));

y = new ByteString("CBA", ASCII);
assert(!x.equals(y));

y = new ByteString("ABCD", ASCII);
assert(!x.equals(y));

y = new ByteString("AB", ASCII);
assert(!x.equals(y));

find()

Prototype

Number find(ByteString value)

Number find(ByteString value, Number offset)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("ABCDABCD", ASCII);
y = new ByteString("BC", ASCII);

assert(typeof(x.find(y)) == "number");
assert(x.find(y) == 1);
assert(x.find(y, 2) == 5);
assert(x.find(y, -2) == 1);

y = new ByteString("CD", ASCII);
assert(x.find(y, 4) == 6);

y = new ByteString("CD", ASCII);
assert(x.find(y, 6) == 6);

y = new ByteString("CB", ASCII);
assert(x.find(y) == -1);

y = new ByteString("BCDE", ASCII);
assert(x.find(y) == -1);

y = new ByteString("", ASCII);
assert(x.find(y) == 0);

x = new ByteString("", ASCII);
y = new ByteString("", ASCII);
assert(x.find(y) == 0);
assert(x.find(y, 0) == 0);

getL()

Prototype

ByteString getL(Number method)

Description

Return a length field encoded as per specification in method.

TLV.EMV encodes the length field with a variable length as per ASN.1 DER encoding. Values in the range 0 to 127 are encoded in one byte. Values in the range 128 to 255 are encoded in two bytes with a leading '81'. Length fields in the range 256 to 65535 are encoded in three bytes with a leading '82' and two bytes in MSB/LSB order. Length fields in the range 65536 to 16777215 are encoded in four bytes with a leading '83' and three bytes in MSB/LSB format.

TLV.DGI encodes length values between 0 and 254 in one byte and length values between 255 and 65535 in three bytes with a leading 'FF' and two bytes in MSB/LSB format.

Arguments

Return

Exceptions

Example

x = new ByteString("", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "00");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "00");


x = new ByteString("123ABC", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "06");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "06");


x = new ByteString("01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "8180");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "80");


x = new ByteString("012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "81FF");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "FF00FF");


x = new ByteString("0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345", ASCII);
y = x.getL(TLV.EMV);
assert(y.toString(HEX) == "820100");

y = x.getL(TLV.DGI);
assert(y.toString(HEX) == "FF0100");

getLV()

Prototype

ByteString getLV(Number method)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("", ASCII);
y = x.getLV(TLV.EMV);
assert(y.toString(HEX) == "00");

y = x.getLV(TLV.DGI);
assert(y.toString(HEX) == "00");


x = new ByteString("123ABC", ASCII);
y = x.getLV(TLV.EMV);
assert(y.toString(HEX) == "06313233414243");

y = x.getLV(TLV.DGI);
assert(y.toString(HEX) == "06313233414243");


x = new ByteString("01234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567", ASCII);
y = x.getLV(TLV.EMV);
assert(y.equals(x.getL(TLV.EMV).concat(x)));

y = x.getLV(TLV.DGI);
assert(y.equals(x.getL(TLV.DGI).concat(x)));


x = new ByteString("0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345", ASCII);
y = x.getLV(TLV.EMV);
assert(y.equals(x.getL(TLV.EMV).concat(x)));

y = x.getLV(TLV.DGI);
assert(y.equals(x.getL(TLV.DGI).concat(x)));

left()

Prototype

ByteString left(Number value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABC", ASCII);
y = x.left(3);
assert(y.toString(ASCII) == "123");

y = x.left(9);
assert(y.toString(ASCII) == "123ABC");

neg()

Prototype

ByteString neg()

ByteString neg(Number size)

Description

Return a ByteString object with the negative binary value of the ByteString object the method is applied to.

The method calculates the ones-complement by inverting all bits and adding 1.

The method can be applied to ByteString objects of arbitrary length.

If no size argument is given, then the resulting ByteString has the same length as the ByteString object the method is called for

Arguments

Return

Exceptions

Example

x = new ByteString("0101", HEX);
y = x.neg();
assert(y.toString(HEX) == "FEFF");

x = new ByteString("0101", HEX);
y = x.neg(3);
assert(y.toString(HEX) == "FFFEFF");

x = new ByteString("0000", HEX);
y = x.neg(3);
assert(y.toString(HEX) == "000000");

x = new ByteString("FFFF", HEX);
y = x.neg();
assert(y.toString(HEX) == "0001");

x = new ByteString("", HEX);
y = x.neg();
assert(y.toString(HEX) == "");

x = new ByteString("", HEX);
y = x.neg(2);
assert(y.toString(HEX) == "0000");

not()

Prototype

ByteString not()

Description

Return

Exceptions

Example

x = new ByteString("0101", HEX);

y = x.not();
assert(y.toString(HEX) == "FEFE");

y = y.not();
assert(y.toString(HEX) == "0101");

x = new ByteString("", HEX);

y = x.not();
assert(y.toString(HEX) == "");

or()

Prototype

ByteString or(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.or(y);
assert(z.toString(HEX) == "FFA5FF", HEX);

pad()

Prototype

ByteString pad(Number method)

ByteString pad(Number method, Boolean optional)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABC", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1);
assert(y.toString(HEX) == "123ABC0000000000");

y = x.pad(Crypto.ISO9797_METHOD_2);
assert(y.toString(HEX) == "123ABC8000000000");

x = new ByteString("123ABC11223333", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1);
assert(y.toString(HEX) == "123ABC1122333300");

y = x.pad(Crypto.ISO9797_METHOD_2);
assert(y.toString(HEX) == "123ABC1122333380");

x = new ByteString("123ABC1122333399", HEX);

y = x.pad(Crypto.ISO9797_METHOD_1, true);
assert(y.toString(HEX) == "123ABC1122333399");

y = x.pad(Crypto.ISO9797_METHOD_2, true);
assert(y.toString(HEX) == "123ABC1122333399");

right()

Prototype

ByteString right(Number count)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABC", ASCII);
y = x.right(3);
assert(y.toString(ASCII) == "ABC");

y = x.right(9);
assert(y.toString(ASCII) == "123ABC");

startsWith()

Prototype

Number startsWith(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("123ABC", ASCII);
y = new ByteString("123", ASCII);

assert(typeof(x.startsWith(y)) == "number");
assert(x.startsWith(y) == 3);
assert(y.startsWith(x) == 3);

y = new ByteString("1234", ASCII);
assert(x.startsWith(y) == 3);

y = new ByteString("01234", ASCII);
assert(x.startsWith(y) == 0);

toBase64()

Prototype

ByteString toBase64()

ByteString toBase64(Boolean linebreak)

Description

Return a new ByteString object containing the BASE64 encoding of the ByteString object for which the method is called.

The resulting ByteString will only contain ASCII characters.

If the linebreak argument is true, then a newline is inserted after each 62. character (48 Bytes).

Arguments

Return

Exceptions

Example

x = new ByteString("Hello World", ASCII);
y = x.toBase64();
assert(y.toString(ASCII) == "SGVsbG8gV29ybGQ=");

x = new ByteString("The quick brown fox jumped over the lazy dog12345", ASCII);
y = x.toBase64(false);
assert(y.toString(ASCII) ==
  "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cxMjM0NQ==");

x = new ByteString("The quick brown fox jumped over the lazy dog12345", ASCII);
y = x.toBase64(true);
assert(y.toString(ASCII) == 
  "VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cxMjM0\nNQ==");

x = new ByteString("", ASCII);
y = x.toBase64(true);
assert(y.length == 0);

toBcd()

Prototype

ByteString toBcd()

ByteString toBcd(Number countBytes)

Description

Return a new ByteString object containing the BCD encoded binary value of the ByteString for which the method is called.

The ByteString can be up to 63 bits long.

If the optional countBytes argument is given, then the resulting ByteString has countBytes length. If the resulting ByteString is longer than the BCD encoded value, then zeros are padded to the left. If the resulting ByteString is smaller than the BCD encoded value, then only the rightmost digits are preserved.

Arguments

Return

Exceptions

Example

x = new ByteString("0101", HEX);
y = x.toBcd();
assert(y.toString(HEX) == "0257");

y = x.toBcd(3);
assert(y.toString(HEX) == "000257");

y = x.toBcd(1);
assert(y.toString(HEX) == "57");

x = new ByteString("7FFFFFFFFFFFFFFF", HEX);

y = x.toBcd();
assert(y.toString(HEX) == "09223372036854775807");

y = x.toBcd(0);
assert(y.toString(HEX) == "");

toHex()

Prototype

ByteString toHex()

ByteString toHex(Number countBytes)

Description

Return a new ByteString object containing in ASCII the HEX encoded binary value of the ByteString for which the method is called.

The ByteString can be of arbitrary length.

If the optional countBytes argument is given, then the resulting ByteString has countBytes length. If the resulting ByteString is longer than the HEX encoded value, then ASCII zeros ('0') are padded to the left. If the resulting ByteString is smaller than the HEX encoded value, then only the rightmost digits are preserved.

Arguments

Return

Exceptions

Example

x = new ByteString("65666768", HEX);
y = x.toHex();
assert(y.toString(ASCII) == "65666768");

x = new ByteString("65666768", HEX);
y = x.toHex(10);
assert(y.toString(ASCII) == "0065666768");

x = new ByteString("65666768", HEX);
y = x.toHex(4);
assert(y.toString(ASCII) == "6768");

x = new ByteString("", HEX);
y = x.toHex();
assert(y.toString(ASCII) == "");

toSigned()

Prototype

Number toSigned()

Number toSigned(Boolean littleEndian)

Description

Return the signed binary value of the ByteString.

The ByteString can be of arbitrary length, however the number of significant bits must not exceed 32. Leading zeros for positive values or ones for negative values are skipped. The first bit in the ByteString is used as sign bit.

Arguments

Return

Exceptions

Example

x = new ByteString("", HEX);
assert(typeof(x.toSigned()) == "number");
assert(x.toSigned() == 0);

x = new ByteString("0123", HEX);
assert(x.toSigned() == 0x0123);

x = new ByteString("FF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("7FFFFFFF", HEX);
assert(x.toSigned() == 0x7FFFFFFF);

x = new ByteString("007FFFFFFF", HEX);
assert(x.toSigned() == 0x7FFFFFFF);

x = new ByteString("007FEDCBA0", HEX);
assert(x.toSigned() == 0x7FEDCBA0);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("FFFFFFFFFF", HEX);
assert(x.toSigned() == -1);

x = new ByteString("FF80000000", HEX);
assert(x.toSigned() == -0x80000000);

x = new ByteString("", HEX);
assert(x.toSigned(true) == 0);

x = new ByteString("0123", HEX);
assert(x.toSigned(true) == 0x2301);

x = new ByteString("FF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("FFFFFF7F", HEX);
assert(x.toSigned(true) == 0x7FFFFFFF);

x = new ByteString("FFFFFF7F00", HEX);
assert(x.toSigned(true) == 0x7FFFFFFF);

x = new ByteString("A0CBED7F00", HEX);
assert(x.toSigned(true) == 0x7FEDCBA0);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("FFFFFFFFFF", HEX);
assert(x.toSigned(true) == -1);

x = new ByteString("00000080FF", HEX);
assert(x.toSigned(true) == -0x80000000);

toString()

Prototype

String toString()

String toString(Number encoding)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("41 42 43", HEX);
assert(x.toString(HEX) == "414243");

x = new ByteString("41 42 43 C4 D6 DC DF", HEX);
assert(x.toString(ASCII) == "ABCÄÖÜß");

x = new ByteString("C3 84 C3 96 C3 9C C3 9F", HEX);
assert(x.toString(UTF8) == "ÄÖÜß");

x = new ByteString("Hello World", ASCII);
assert(x.toString(BASE64) == "SGVsbG8gV29ybGQ=");

toUnsigned()

Prototype

Number toUnsigned()

Number toUnsigned(Boolean littleEndian)

Description

Return the unsigned binary value of the ByteString.

The ByteString can be of arbitrary length, however the number of significant bits must not exceed 32. Leading zeros are skipped.

Arguments

Return

Exceptions

Example

x = new ByteString("", HEX);
assert(typeof(x.toUnsigned()) == "number");
assert(x.toUnsigned() == 0);

x = new ByteString("0123", HEX);
assert(x.toUnsigned() == 0x0123);

x = new ByteString("FF", HEX);
assert(x.toUnsigned() == 255);

x = new ByteString("FFFFFFFF", HEX);
assert(x.toUnsigned() == 0xFFFFFFFF);

x = new ByteString("00FFFFFFFF", HEX);
assert(x.toUnsigned() == 0xFFFFFFFF);

x = new ByteString("00DFEDCBA0", HEX);
assert(x.toUnsigned() == 0xDFEDCBA0);


x = new ByteString("", HEX);
assert(x.toUnsigned(true) == 0);

x = new ByteString("0123", HEX);
assert(x.toUnsigned(true) == 0x2301);

x = new ByteString("FF", HEX);
assert(x.toUnsigned(true) == 0xFF);

x = new ByteString("FFFFFF8F", HEX);
assert(x.toUnsigned(true) == 0x8FFFFFFF);

x = new ByteString("FFFFFF8F00", HEX);
assert(x.toUnsigned(true) == 0x8FFFFFFF);

x = new ByteString("A0CBED7F00", HEX);
assert(x.toUnsigned(true) == 0x7FEDCBA0);

xor()

Prototype

ByteString xor(ByteString value)

Description

Arguments

Return

Exceptions

Example

x = new ByteString("AA A5 55", HEX);
y = new ByteString("55 A5 AA", HEX);
z = x.xor(y);

assert(z.toString(HEX) == "FF00FF", HEX);

© Copyright 2003 - 2010 CardContact Software & System Consulting, Minden, Germany