Source: lib/util/string_utils.js

  1. /*! @license
  2.  * Shaka Player
  3.  * Copyright 2016 Google LLC
  4.  * SPDX-License-Identifier: Apache-2.0
  5.  */
  7. goog.provide('shaka.util.StringUtils');
  9. goog.require('goog.asserts');
  10. goog.require('shaka.log');
  11. goog.require('shaka.util.BufferUtils');
  12. goog.require('shaka.util.Error');
  13. goog.require('shaka.util.Lazy');
  16. /**
  17.  * @namespace shaka.util.StringUtils
  18.  * @summary A set of string utility functions.
  19.  * @export
  20.  */
  21. shaka.util.StringUtils = class {
  22.   /**
  23.    * Creates a string from the given buffer as UTF-8 encoding.
  24.    *
  25.    * @param {?BufferSource} data
  26.    * @return {string}
  27.    * @export
  28.    */
  29.   static fromUTF8(data) {
  30.     if (!data) {
  31.       return '';
  32.     }
  34.     let uint8 = shaka.util.BufferUtils.toUint8(data);
  35.     // If present, strip off the UTF-8 BOM.
  36.     if (uint8[0] == 0xef && uint8[1] == 0xbb && uint8[2] == 0xbf) {
  37.       uint8 = uint8.subarray(3);
  38.     }
  40.     // Use the TextDecoder interface to decode the text.  This has the advantage
  41.     // compared to the previously-standard decodeUriComponent that it will
  42.     // continue parsing even if it finds an invalid UTF8 character, rather than
  43.     // stop and throw an error.
  44.     const utf8decoder = new TextDecoder();
  45.     const decoded = utf8decoder.decode(uint8);
  46.     if (decoded.includes('\uFFFD')) {
  47.       shaka.log.alwaysError('Decoded string contains an "unknown character" ' +
  48.                             'codepoint.  That probably means the UTF8 ' +
  49.                             'encoding was incorrect!');
  50.     }
  51.     return decoded;
  52.   }
  55.   /**
  56.    * Creates a string from the given buffer as UTF-16 encoding.
  57.    *
  58.    * @param {?BufferSource} data
  59.    * @param {boolean} littleEndian
  60.          true to read little endian, false to read big.
  61.    * @param {boolean=} noThrow true to avoid throwing in cases where we may
  62.    *     expect invalid input.  If noThrow is true and the data has an odd
  63.    *     length,it will be truncated.
  64.    * @return {string}
  65.    * @export
  66.    */
  67.   static fromUTF16(data, littleEndian, noThrow) {
  68.     if (!data) {
  69.       return '';
  70.     }
  72.     if (!noThrow && data.byteLength % 2 != 0) {
  73.       shaka.log.error('Data has an incorrect length, must be even.');
  74.       throw new shaka.util.Error(
  75.           shaka.util.Error.Severity.CRITICAL, shaka.util.Error.Category.TEXT,
  76.           shaka.util.Error.Code.BAD_ENCODING);
  77.     }
  79.     // Use a DataView to ensure correct endianness.
  80.     const length = Math.floor(data.byteLength / 2);
  81.     const arr = new Uint16Array(length);
  82.     const dataView = shaka.util.BufferUtils.toDataView(data);
  83.     for (let i = 0; i < length; i++) {
  84.       arr[i] = dataView.getUint16(i * 2, littleEndian);
  85.     }
  86.     return shaka.util.StringUtils.fromCharCode(arr);
  87.   }
  90.   /**
  91.    * Creates a string from the given buffer, auto-detecting the encoding that is
  92.    * being used.  If it cannot detect the encoding, it will throw an exception.
  93.    *
  94.    * @param {?BufferSource} data
  95.    * @return {string}
  96.    * @export
  97.    */
  98.   static fromBytesAutoDetect(data) {
  99.     const StringUtils = shaka.util.StringUtils;
  100.     if (!data) {
  101.       return '';
  102.     }
  104.     const uint8 = shaka.util.BufferUtils.toUint8(data);
  105.     if (uint8[0] == 0xef && uint8[1] == 0xbb && uint8[2] == 0xbf) {
  106.       return StringUtils.fromUTF8(uint8);
  107.     } else if (uint8[0] == 0xfe && uint8[1] == 0xff) {
  108.       return StringUtils.fromUTF16(
  109.           uint8.subarray(2), /* littleEndian= */ false);
  110.     } else if (uint8[0] == 0xff && uint8[1] == 0xfe) {
  111.       return StringUtils.fromUTF16(uint8.subarray(2), /* littleEndian= */ true);
  112.     }
  114.     const isAscii = (i) => {
  115.       // arr[i] >= ' ' && arr[i] <= '~';
  116.       return uint8.byteLength <= i || (uint8[i] >= 0x20 && uint8[i] <= 0x7e);
  117.     };
  119.     shaka.log.debug(
  120.         'Unable to find byte-order-mark, making an educated guess.');
  121.     if (uint8[0] == 0 && uint8[2] == 0) {
  122.       return StringUtils.fromUTF16(data, /* littleEndian= */ false);
  123.     } else if (uint8[1] == 0 && uint8[3] == 0) {
  124.       return StringUtils.fromUTF16(data, /* littleEndian= */ true);
  125.     } else if (isAscii(0) && isAscii(1) && isAscii(2) && isAscii(3)) {
  126.       return StringUtils.fromUTF8(data);
  127.     }
  129.     throw new shaka.util.Error(
  130.         shaka.util.Error.Severity.CRITICAL,
  131.         shaka.util.Error.Category.TEXT,
  132.         shaka.util.Error.Code.UNABLE_TO_DETECT_ENCODING);
  133.   }
  136.   /**
  137.    * Creates a ArrayBuffer from the given string, converting to UTF-8 encoding.
  138.    *
  139.    * @param {string} str
  140.    * @return {!ArrayBuffer}
  141.    * @export
  142.    */
  143.   static toUTF8(str) {
  144.     const utf8Encoder = new TextEncoder();
  145.     return shaka.util.BufferUtils.toArrayBuffer(utf8Encoder.encode(str));
  146.   }
  149.   /**
  150.    * Creates a ArrayBuffer from the given string, converting to UTF-16 encoding.
  151.    *
  152.    * @param {string} str
  153.    * @param {boolean} littleEndian
  154.    * @return {!ArrayBuffer}
  155.    * @export
  156.    */
  157.   static toUTF16(str, littleEndian) {
  158.     const result = new ArrayBuffer(str.length * 2);
  159.     const view = new DataView(result);
  160.     for (let i = 0; i < str.length; ++i) {
  161.       const value = str.charCodeAt(i);
  162.       view.setUint16(/* position= */ i * 2, value, littleEndian);
  163.     }
  164.     return result;
  165.   }
  168.   /**
  169.    * Creates a new string from the given array of char codes.
  170.    *
  171.    * Using String.fromCharCode.apply is risky because you can trigger stack
  172.    * errors on very large arrays.  This breaks up the array into several pieces
  173.    * to avoid this.
  174.    *
  175.    * @param {!TypedArray} array
  176.    * @return {string}
  177.    */
  178.   static fromCharCode(array) {
  179.     return shaka.util.StringUtils.fromCharCodeImpl_.value()(array);
  180.   }
  182.   /**
  183.    * Resets the fromCharCode method's implementation.
  184.    * For debug use.
  185.    * @export
  186.    */
  187.   static resetFromCharCode() {
  188.     shaka.util.StringUtils.fromCharCodeImpl_.reset();
  189.   }
  190. };
  193. /** @private {!shaka.util.Lazy.<function(!TypedArray):string>} */
  194. shaka.util.StringUtils.fromCharCodeImpl_ = new shaka.util.Lazy(() => {
  195.   /** @param {number} size @return {boolean} */
  196.   const supportsChunkSize = (size) => {
  197.     try {
  198.       // The compiler will complain about suspicious value if this isn't
  199.       // stored in a variable and used.
  200.       const buffer = new Uint8Array(size);
  202.       // This can't use the spread operator, or it blows up on Xbox One.
  203.       // So we use apply() instead, which is normally not allowed.
  204.       // See issue #2186 for more details.
  205.       // eslint-disable-next-line no-restricted-syntax
  206.       const foo = String.fromCharCode.apply(null, buffer);
  207.       goog.asserts.assert(foo, 'Should get value');
  208.       return foo.length > 0; // Actually use "foo", so it's not compiled out.
  209.     } catch (error) {
  210.       return false;
  211.     }
  212.   };
  214.   // Different browsers support different chunk sizes; find out the largest
  215.   // this browser supports so we can use larger chunks on supported browsers
  216.   // but still support lower-end devices that require small chunks.
  217.   // 64k is supported on all major desktop browsers.
  218.   for (let size = 64 * 1024; size > 0; size /= 2) {
  219.     if (supportsChunkSize(size)) {
  220.       return (buffer) => {
  221.         let ret = '';
  222.         for (let i = 0; i < buffer.length; i += size) {
  223.           const subArray = buffer.subarray(i, i + size);
  225.           // This can't use the spread operator, or it blows up on Xbox One.
  226.           // So we use apply() instead, which is normally not allowed.
  227.           // See issue #2186 for more details.
  228.           // eslint-disable-next-line no-restricted-syntax
  229.           ret += String.fromCharCode.apply(null, subArray);  // Issue #2186
  230.         }
  231.         return ret;
  232.       };
  233.     }
  234.   }
  235.   goog.asserts.assert(false, 'Unable to create a fromCharCode method');
  236.   return null;
  237. });