Source: lib/util/string_utils.js

  1. /**
  2.  * @license
  3.  * Copyright 2016 Google Inc.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  18. goog.provide('shaka.util.StringUtils');
  20. goog.require('shaka.log');
  21. goog.require('shaka.util.Error');
  24. /**
  25.  * @namespace shaka.util.StringUtils
  26.  * @summary A set of string utility functions.
  27.  * @exportDoc
  28.  */
  31. /**
  32.  * Creates a string from the given buffer as UTF-8 encoding.
  33.  *
  34.  * @param {?BufferSource} data
  35.  * @return {string}
  36.  * @throws {shaka.util.Error}
  37.  * @export
  38.  */
  39. shaka.util.StringUtils.fromUTF8 = function(data) {
  40.   if (!data) return '';
  42.   let uint8 = new Uint8Array(data);
  43.   // If present, strip off the UTF-8 BOM.
  44.   if (uint8[0] == 0xef && uint8[1] == 0xbb && uint8[2] == 0xbf) {
  45.     uint8 = uint8.subarray(3);
  46.   }
  48.   // http://stackoverflow.com/a/13691499
  49.   let utf8 = shaka.util.StringUtils.fromCharCode(uint8);
  50.   // This converts each character in the string to an escape sequence.  If the
  51.   // character is in the ASCII range, it is not converted; otherwise it is
  52.   // converted to a URI escape sequence.
  53.   // Example: '\x67\x35\xe3\x82\xac' -> 'g#%E3%82%AC'
  54.   let escaped = escape(utf8);
  55.   // Decode the escaped sequence.  This will interpret UTF-8 sequences into the
  56.   // correct character.
  57.   // Example: 'g#%E3%82%AC' -> 'g#€'
  58.   try {
  59.     return decodeURIComponent(escaped);
  60.   } catch (e) {
  61.     throw new shaka.util.Error(
  62.         shaka.util.Error.Severity.CRITICAL, shaka.util.Error.Category.TEXT,
  63.         shaka.util.Error.Code.BAD_ENCODING);
  64.   }
  65. };
  68. /**
  69.  * Creates a string from the given buffer as UTF-16 encoding.
  70.  *
  71.  * @param {?BufferSource} data
  72.  * @param {boolean} littleEndian true to read little endian, false to read big.
  73.  * @param {boolean=} noThrow true to avoid throwing in cases where we may
  74.  *     expect invalid input.  If noThrow is true and the data has an odd length,
  75.  *     it will be truncated.
  76.  * @return {string}
  77.  * @throws {shaka.util.Error}
  78.  * @export
  79.  */
  80. shaka.util.StringUtils.fromUTF16 = function(data, littleEndian, noThrow) {
  81.   if (!data) return '';
  83.   if (!noThrow && data.byteLength % 2 != 0) {
  84.     shaka.log.error('Data has an incorrect length, must be even.');
  85.     throw new shaka.util.Error(
  86.         shaka.util.Error.Severity.CRITICAL, shaka.util.Error.Category.TEXT,
  87.         shaka.util.Error.Code.BAD_ENCODING);
  88.   }
  90.   /** @type {ArrayBuffer} */
  91.   let buffer;
  92.   if (data instanceof ArrayBuffer) {
  93.     buffer = data;
  94.   } else {
  95.     // Have to create a new buffer because the argument may be a smaller
  96.     // view on a larger ArrayBuffer.  We cannot use an ArrayBufferView in
  97.     // a DataView.
  98.     let temp = new Uint8Array(data.byteLength);
  99.     temp.set(new Uint8Array(data));
  100.     buffer = temp.buffer;
  101.   }
  103.   // Use a DataView to ensure correct endianness.
  104.   let length = Math.floor(data.byteLength / 2);
  105.   let arr = new Uint16Array(length);
  106.   let dataView = new DataView(buffer);
  107.   for (let i = 0; i < length; i++) {
  108.     arr[i] = dataView.getUint16(i * 2, littleEndian);
  109.   }
  110.   return shaka.util.StringUtils.fromCharCode(arr);
  111. };
  114. /**
  115.  * Creates a string from the given buffer, auto-detecting the encoding that is
  116.  * being used.  If it cannot detect the encoding, it will throw an exception.
  117.  *
  118.  * @param {?BufferSource} data
  119.  * @return {string}
  120.  * @throws {shaka.util.Error}
  121.  * @export
  122.  */
  123. shaka.util.StringUtils.fromBytesAutoDetect = function(data) {
  124.   const StringUtils = shaka.util.StringUtils;
  126.   let uint8 = new Uint8Array(data);
  127.   if (uint8[0] == 0xef && uint8[1] == 0xbb && uint8[2] == 0xbf) {
  128.     return StringUtils.fromUTF8(uint8);
  129.   } else if (uint8[0] == 0xfe && uint8[1] == 0xff) {
  130.     return StringUtils.fromUTF16(uint8.subarray(2), false /* littleEndian */);
  131.   } else if (uint8[0] == 0xff && uint8[1] == 0xfe) {
  132.     return StringUtils.fromUTF16(uint8.subarray(2), true /* littleEndian */);
  133.   }
  135.   let isAscii = (function(arr, i) {
  136.     // arr[i] >= ' ' && arr[i] <= '~';
  137.     return arr.byteLength <= i || (arr[i] >= 0x20 && arr[i] <= 0x7e);
  138.   }.bind(null, uint8));
  140.   shaka.log.debug('Unable to find byte-order-mark, making an educated guess.');
  141.   if (uint8[0] == 0 && uint8[2] == 0) {
  142.     return StringUtils.fromUTF16(data, false /* littleEndian */);
  143.   } else if (uint8[1] == 0 && uint8[3] == 0) {
  144.     return StringUtils.fromUTF16(data, true /* littleEndian */);
  145.   } else if (isAscii(0) && isAscii(1) && isAscii(2) && isAscii(3)) {
  146.     return StringUtils.fromUTF8(data);
  147.   }
  149.   throw new shaka.util.Error(
  150.       shaka.util.Error.Severity.CRITICAL,
  151.       shaka.util.Error.Category.TEXT,
  152.       shaka.util.Error.Code.UNABLE_TO_DETECT_ENCODING);
  153. };
  156. /**
  157.  * Creates a ArrayBuffer from the given string, converting to UTF-8 encoding.
  158.  *
  159.  * @param {string} str
  160.  * @return {!ArrayBuffer}
  161.  * @export
  162.  */
  163. shaka.util.StringUtils.toUTF8 = function(str) {
  164.   // http://stackoverflow.com/a/13691499
  165.   // Converts the given string to a URI encoded string.  If a character falls
  166.   // in the ASCII range, it is not converted; otherwise it will be converted to
  167.   // a series of URI escape sequences according to UTF-8.
  168.   // Example: 'g#€' -> 'g#%E3%82%AC'
  169.   let encoded = encodeURIComponent(str);
  170.   // Convert each escape sequence individually into a character.  Each escape
  171.   // sequence is interpreted as a code-point, so if an escape sequence happens
  172.   // to be part of a multi-byte sequence, each byte will be converted to a
  173.   // single character.
  174.   // Example: 'g#%E3%82%AC' -> '\x67\x35\xe3\x82\xac'
  175.   let utf8 = unescape(encoded);
  177.   let result = new Uint8Array(utf8.length);
  178.   for (let i = 0; i < utf8.length; ++i) {
  179.     result[i] = utf8.charCodeAt(i);
  180.   }
  181.   return result.buffer;
  182. };
  185. /**
  186.  * Creates a ArrayBuffer from the given string, converting to UTF-16 encoding.
  187.  *
  188.  * @param {string} str
  189.  * @param {boolean} littleEndian
  190.  * @return {!ArrayBuffer}
  191.  * @export
  192.  */
  193. shaka.util.StringUtils.toUTF16 = function(str, littleEndian) {
  194.   const result = new Uint8Array(str.length * 2);
  195.   const view = new DataView(result.buffer);
  196.   for (let i = 0; i < str.length; ++i) {
  197.     const value = str.charCodeAt(i);
  198.     view.setUint16(/* position= */ i * 2, value, littleEndian);
  199.   }
  200.   return result.buffer;
  201. };
  204. /**
  205.  * Creates a new string from the given array of char codes.
  206.  *
  207.  * Using String.fromCharCode.apply is risky because you can trigger stack errors
  208.  * on very large arrays.  This breaks up the array into several pieces to avoid
  209.  * this.
  210.  *
  211.  * @param {!TypedArray} array
  212.  * @return {string}
  213.  */
  214. shaka.util.StringUtils.fromCharCode = function(array) {
  215.   let max = 16000;
  216.   let ret = '';
  217.   for (let i = 0; i < array.length; i += max) {
  218.     let subArray = array.subarray(i, i + max);
  219.     ret += String.fromCharCode.apply(null, subArray);
  220.   }
  222.   return ret;
  223. };