Source: name.js

  1. /**
  2.  * This class represents a Name as an array of components where each is a byte array.
  3.  * Copyright (C) 2013-2016 Regents of the University of California.
  4.  * @author: Meki Cheraoui, Jeff Thompson <jefft0@remap.ucla.edu>
  5.  *
  6.  * This program is free software: you can redistribute it and/or modify
  7.  * it under the terms of the GNU Lesser General Public License as published by
  8.  * the Free Software Foundation, either version 3 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * This program is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU Lesser General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU Lesser General Public License
  17.  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18.  * A copy of the GNU Lesser General Public License is in the file COPYING.
  19.  */
  21. /** @ignore */
  22. var Blob = require('./util/blob.js').Blob; /** @ignore */
  23. var DataUtils = require('./encoding/data-utils.js').DataUtils; /** @ignore */
  24. var LOG = require('./log.js').Log.LOG;
  26. /**
  27.  * Create a new Name from components.
  28.  *
  29.  * @constructor
  30.  * @param {string|Name|Array<string|Array<number>|ArrayBuffer|Buffer|Name>} components if a string, parse it as a URI.  If a Name, add a deep copy of its components.
  31.  * Otherwise it is an array of components which are appended according to Name.append, so
  32.  * convert each and store it as an array of Buffer.  If a component is a string, encode as utf8.
  33.  */
  34. var Name = function Name(components)
  35. {
  36.   if (typeof components == 'string') {
  37.     if (LOG > 3) console.log('Content Name String ' + components);
  38.     this.components = Name.createNameArray(components);
  39.   }
  40.   else if (typeof components === 'object') {
  41.     this.components = [];
  42.     if (components instanceof Name)
  43.       this.append(components);
  44.     else {
  45.       for (var i = 0; i < components.length; ++i)
  46.         this.append(components[i]);
  47.     }
  48.   }
  49.   else if (components == null)
  50.     this.components = [];
  51.   else
  52.     if (LOG > 1) console.log("NO CONTENT NAME GIVEN");
  54.   this.changeCount = 0;
  55. };
  57. exports.Name = Name;
  59. /**
  60.  * Create a new Name.Component with a copy of the given value.
  61.  * @param {Name.Component|String|Array<number>|ArrayBuffer|Buffer} value If the value is a string, encode it as utf8 (but don't unescape).
  62.  * @constructor
  63.  */
  64. Name.Component = function NameComponent(value)
  65. {
  66.   if (typeof value === 'object' && value instanceof Name.Component)
  67.     this.value_ = value.value_;
  68.   else if (!value)
  69.     this.value_ = new Blob([]);
  70.   else if (typeof value === 'object' && typeof ArrayBuffer !== 'undefined' &&
  71.            value instanceof ArrayBuffer)
  72.     // Make a copy.  Turn the value into a Uint8Array since the Buffer
  73.     //   constructor doesn't take an ArrayBuffer.
  74.     this.value_ = new Blob(new Buffer(new Uint8Array(value)), false);
  75.   else if (typeof value === 'object' && value instanceof Blob)
  76.     this.value_ = value;
  77.   else
  78.     // Blob will make a copy if needed.
  79.     this.value_ = new Blob(value);
  80. };
  82. /**
  83.  * Get the component value.
  84.  * @returns {Blob} The component value.
  85.  */
  86. Name.Component.prototype.getValue = function()
  87. {
  88.   return this.value_;
  89. };
  91. /**
  92.  * @deprecated Use getValue. This method returns a Buffer which is the former
  93.  * behavior of getValue, and should only be used while updating your code.
  94.  */
  95. Name.Component.prototype.getValueAsBuffer = function()
  96. {
  97.   // Assume the caller won't modify it.
  98.   return this.value_.buf();
  99. };
  101. /**
  102.  * @deprecated Use getValue which returns a Blob.
  103.  */
  104. Object.defineProperty(Name.Component.prototype, "value",
  105.   { get: function() { return this.getValueAsBuffer(); } });
  107. /**
  108.  * Convert this component value to a string by escaping characters according to the NDN URI Scheme.
  109.  * This also adds "..." to a value with zero or more ".".
  110.  * @returns {string} The escaped string.
  111.  */
  112. Name.Component.prototype.toEscapedString = function()
  113. {
  114.   return Name.toEscapedString(this.value_.buf());
  115. };
  117. /**
  118.  * Check if this component is a segment number according to NDN naming
  119.  * conventions for "Segment number" (marker 0x00).
  120.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  121.  * @returns {number}  True if this is a segment number.
  122.  */
  123. Name.Component.prototype.isSegment = function()
  124. {
  125.   return this.value_.size() >= 1 && this.value_.buf()[0] == 0x00;
  126. };
  128. /**
  129.  * Check if this component is a segment byte offset according to NDN
  130.  * naming conventions for segment "Byte offset" (marker 0xFB).
  131.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  132.  * @returns  True if this is a segment byte offset.
  133.  */
  134. Name.Component.prototype.isSegmentOffset = function()
  135. {
  136.   return this.value_.size() >= 1 && this.value_.buf()[0] == 0xFB;
  137. };
  139. /**
  140.  * Check if this component is a version number  according to NDN naming
  141.  * conventions for "Versioning" (marker 0xFD).
  142.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  143.  * @returns {number}  True if this is a version number.
  144.  */
  145. Name.Component.prototype.isVersion = function()
  146. {
  147.   return this.value_.size() >= 1 && this.value_.buf()[0] == 0xFD;
  148. };
  150. /**
  151.  * Check if this component is a timestamp  according to NDN naming
  152.  * conventions for "Timestamp" (marker 0xFC).
  153.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  154.  * @returns  True if this is a timestamp.
  155.  */
  156. Name.Component.prototype.isTimestamp = function()
  157. {
  158.   return this.value_.size() >= 1 && this.value_.buf()[0] == 0xFC;
  159. };
  161. /**
  162.  * Check if this component is a sequence number according to NDN naming
  163.  * conventions for "Sequencing" (marker 0xFE).
  164.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  165.  * @returns  True if this is a sequence number.
  166.  */
  167. Name.Component.prototype.isSequenceNumber = function()
  168. {
  169.   return this.value_.size() >= 1 && this.value_.buf()[0] == 0xFE;
  170. };
  172. /**
  173.  * Interpret this name component as a network-ordered number and return an integer.
  174.  * @returns {number} The integer number.
  175.  */
  176. Name.Component.prototype.toNumber = function()
  177. {
  178.   return DataUtils.bigEndianToUnsignedInt(this.value_.buf());
  179. };
  181. /**
  182.  * Interpret this name component as a network-ordered number with a marker and
  183.  * return an integer.
  184.  * @param {number} marker The required first byte of the component.
  185.  * @returns {number} The integer number.
  186.  * @throws Error If the first byte of the component does not equal the marker.
  187.  */
  188. Name.Component.prototype.toNumberWithMarker = function(marker)
  189. {
  190.   if (this.value_.size() == 0 || this.value_.buf()[0] != marker)
  191.     throw new Error("Name component does not begin with the expected marker");
  193.   return DataUtils.bigEndianToUnsignedInt(this.value_.buf().slice(1));
  194. };
  196. /**
  197.  * Interpret this name component as a segment number according to NDN naming
  198.  * conventions for "Segment number" (marker 0x00).
  199.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  200.  * @returns {number} The integer segment number.
  201.  * @throws Error If the first byte of the component is not the expected marker.
  202.  */
  203. Name.Component.prototype.toSegment = function()
  204. {
  205.   return this.toNumberWithMarker(0x00);
  206. };
  208. /**
  209.  * Interpret this name component as a segment byte offset according to NDN
  210.  * naming conventions for segment "Byte offset" (marker 0xFB).
  211.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  212.  * @returns The integer segment byte offset.
  213.  * @throws Error If the first byte of the component is not the expected marker.
  214.  */
  215. Name.Component.prototype.toSegmentOffset = function()
  216. {
  217.   return this.toNumberWithMarker(0xFB);
  218. };
  220. /**
  221.  * Interpret this name component as a version number  according to NDN naming
  222.  * conventions for "Versioning" (marker 0xFD). Note that this returns
  223.  * the exact number from the component without converting it to a time
  224.  * representation.
  225.  * @returns {number} The integer version number.
  226.  * @throws Error If the first byte of the component is not the expected marker.
  227.  */
  228. Name.Component.prototype.toVersion = function()
  229. {
  230.   return this.toNumberWithMarker(0xFD);
  231. };
  233. /**
  234.  * Interpret this name component as a timestamp  according to NDN naming
  235.  * conventions for "Timestamp" (marker 0xFC).
  236.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  237.  * @returns The number of microseconds since the UNIX epoch (Thursday,
  238.  * 1 January 1970) not counting leap seconds.
  239.  * @throws Error If the first byte of the component is not the expected marker.
  240.  */
  241. Name.Component.prototype.toTimestamp = function()
  242. {
  243.   return this.toNumberWithMarker(0xFC);
  244. };
  246. /**
  247.  * Interpret this name component as a sequence number according to NDN naming
  248.  * conventions for "Sequencing" (marker 0xFE).
  249.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  250.  * @returns The integer sequence number.
  251.  * @throws Error If the first byte of the component is not the expected marker.
  252.  */
  253. Name.Component.prototype.toSequenceNumber = function()
  254. {
  255.   return this.toNumberWithMarker(0xFE);
  256. };
  258. /**
  259.  * Create a component whose value is the nonNegativeInteger encoding of the
  260.  * number.
  261.  * @param {number} number
  262.  * @returns {Name.Component}
  263.  */
  264. Name.Component.fromNumber = function(number)
  265. {
  266.   var encoder = new TlvEncoder(8);
  267.   encoder.writeNonNegativeInteger(number);
  268.   return new Name.Component(new Blob(encoder.getOutput(), false));
  269. };
  271. /**
  272.  * Create a component whose value is the marker appended with the
  273.  * nonNegativeInteger encoding of the number.
  274.  * @param {number} number
  275.  * @param {number} marker
  276.  * @returns {Name.Component}
  277.  */
  278. Name.Component.fromNumberWithMarker = function(number, marker)
  279. {
  280.   var encoder = new TlvEncoder(9);
  281.   // Encode backwards.
  282.   encoder.writeNonNegativeInteger(number);
  283.   encoder.writeNonNegativeInteger(marker);
  284.   return new Name.Component(new Blob(encoder.getOutput(), false));
  285. };
  287. /**
  288.  * Create a component with the encoded segment number according to NDN
  289.  * naming conventions for "Segment number" (marker 0x00).
  290.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  291.  * param {number} segment The segment number.
  292.  * returns {Name.Component} The new Component.
  293.  */
  294. Name.Component.fromSegment = function(segment)
  295. {
  296.   return Name.Component.fromNumberWithMarker(segment, 0x00);
  297. };
  299. /**
  300.  * Create a component with the encoded segment byte offset according to NDN
  301.  * naming conventions for segment "Byte offset" (marker 0xFB).
  302.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  303.  * param {number} segmentOffset The segment byte offset.
  304.  * returns {Name.Component} The new Component.
  305.  */
  306. Name.Component.fromSegmentOffset = function(segmentOffset)
  307. {
  308.   return Name.Component.fromNumberWithMarker(segmentOffset, 0xFB);
  309. };
  311. /**
  312.  * Create a component with the encoded version number according to NDN
  313.  * naming conventions for "Versioning" (marker 0xFD).
  314.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  315.  * Note that this encodes the exact value of version without converting from a
  316.  * time representation.
  317.  * param {number} version The version number.
  318.  * returns {Name.Component} The new Component.
  319.  */
  320. Name.Component.fromVersion = function(version)
  321. {
  322.   return Name.Component.fromNumberWithMarker(version, 0xFD);
  323. };
  325. /**
  326.  * Create a component with the encoded timestamp according to NDN naming
  327.  * conventions for "Timestamp" (marker 0xFC).
  328.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  329.  * param {number} timestamp The number of microseconds since the UNIX epoch (Thursday,
  330.  * 1 January 1970) not counting leap seconds.
  331.  * returns {Name.Component} The new Component.
  332.  */
  333. Name.Component.fromTimestamp = function(timestamp)
  334. {
  335.   return Name.Component.fromNumberWithMarker(timestamp, 0xFC);
  336. };
  338. /**
  339.  * Create a component with the encoded sequence number according to NDN naming
  340.  * conventions for "Sequencing" (marker 0xFE).
  341.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  342.  * param {number} sequenceNumber The sequence number.
  343.  * returns {Name.Component} The new Component.
  344.  */
  345. Name.Component.fromSequenceNumber = function(sequenceNumber)
  346. {
  347.   return Name.Component.fromNumberWithMarker(sequenceNumber, 0xFE);
  348. };
  350. /**
  351.  * Get the successor of this component, as described in Name.getSuccessor.
  352.  * @returns {Name.Component} A new Name.Component which is the successor of this.
  353.  */
  354. Name.Component.prototype.getSuccessor = function()
  355. {
  356.   // Allocate an extra byte in case the result is larger.
  357.   var result = new Buffer(this.value_.size() + 1);
  359.   var carry = true;
  360.   for (var i = this.value_.size() - 1; i >= 0; --i) {
  361.     if (carry) {
  362.       result[i] = (this.value_.buf()[i] + 1) & 0xff;
  363.       carry = (result[i] === 0);
  364.     }
  365.     else
  366.       result[i] = this.value_.buf()[i];
  367.   }
  369.   if (carry)
  370.     // Assume all the bytes were set to zero (or the component was empty). In
  371.     // NDN ordering, carry does not mean to prepend a 1, but to make a component
  372.     // one byte longer of all zeros.
  373.     result[result.length - 1] = 0;
  374.   else
  375.     // We didn't need the extra byte.
  376.     result = result.slice(0, this.value_.size());
  378.   return new Name.Component(new Blob(result, false));
  379. };
  381. /**
  382.  * Check if this is the same component as other.
  383.  * @param {Name.Component} other The other Component to compare with.
  384.  * @returns {Boolean} true if the components are equal, otherwise false.
  385.  */
  386. Name.Component.prototype.equals = function(other)
  387. {
  388.   return typeof other === 'object' && other instanceof Name.Component &&
  389.     this.value_.equals(other.value_);
  390. };
  392. /**
  393.  * Compare this to the other Component using NDN canonical ordering.
  394.  * @param {Name.Component} other The other Component to compare with.
  395.  * @returns {number} 0 if they compare equal, -1 if this comes before other in
  396.  * the canonical ordering, or 1 if this comes after other in the canonical
  397.  * ordering.
  398.  *
  399.  * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
  400.  */
  401. Name.Component.prototype.compare = function(other)
  402. {
  403.   return Name.Component.compareBuffers(this.value_.buf(), other.value_.buf());
  404. };
  406. /**
  407.  * Do the work of Name.Component.compare to compare the component buffers.
  408.  * @param {Buffer} component1
  409.  * @param {Buffer} component2
  410.  * @returns {number} 0 if they compare equal, -1 if component1 comes before
  411.  * component2 in the canonical ordering, or 1 if component1 comes after
  412.  * component2 in the canonical ordering.
  413.  */
  414. Name.Component.compareBuffers = function(component1, component2)
  415. {
  416.   if (component1.length < component2.length)
  417.     return -1;
  418.   if (component1.length > component2.length)
  419.     return 1;
  421.   for (var i = 0; i < component1.length; ++i) {
  422.     if (component1[i] < component2[i])
  423.       return -1;
  424.     if (component1[i] > component2[i])
  425.       return 1;
  426.   }
  428.   return 0;
  429. };
  431. /**
  432.  * @deprecated Use toUri.
  433.  */
  434. Name.prototype.getName = function()
  435. {
  436.   return this.toUri();
  437. };
  439. /** Parse uri as a URI and return an array of Buffer components.
  440.  */
  441. Name.createNameArray = function(uri)
  442. {
  443.   uri = uri.trim();
  444.   if (uri.length <= 0)
  445.     return [];
  447.   var iColon = uri.indexOf(':');
  448.   if (iColon >= 0) {
  449.     // Make sure the colon came before a '/'.
  450.     var iFirstSlash = uri.indexOf('/');
  451.     if (iFirstSlash < 0 || iColon < iFirstSlash)
  452.       // Omit the leading protocol such as ndn:
  453.       uri = uri.substr(iColon + 1, uri.length - iColon - 1).trim();
  454.   }
  456.   if (uri[0] == '/') {
  457.     if (uri.length >= 2 && uri[1] == '/') {
  458.       // Strip the authority following "//".
  459.       var iAfterAuthority = uri.indexOf('/', 2);
  460.       if (iAfterAuthority < 0)
  461.         // Unusual case: there was only an authority.
  462.         return [];
  463.       else
  464.         uri = uri.substr(iAfterAuthority + 1, uri.length - iAfterAuthority - 1).trim();
  465.     }
  466.     else
  467.       uri = uri.substr(1, uri.length - 1).trim();
  468.   }
  470.   var array = uri.split('/');
  472.   // Unescape the components.
  473.   for (var i = 0; i < array.length; ++i) {
  474.     var value = Name.fromEscapedString(array[i]);
  476.     if (value.isNull()) {
  477.       // Ignore the illegal componenent.  This also gets rid of a trailing '/'.
  478.       array.splice(i, 1);
  479.       --i;
  480.       continue;
  481.     }
  482.     else
  483.       array[i] = new Name.Component(value);
  484.   }
  486.   return array;
  487. };
  489. /**
  490.  * Parse the uri according to the NDN URI Scheme and set the name with the
  491.  * components.
  492.  * @param {string} uri The URI string.
  493.  */
  494. Name.prototype.set = function(uri)
  495. {
  496.   this.components = Name.createNameArray(uri);
  497.   ++this.changeCount;
  498. };
  500. /**
  501.  * Convert the component to a Buffer and append to this Name.
  502.  * Return this Name object to allow chaining calls to add.
  503.  * @param {Name.Component|String|Array<number>|ArrayBuffer|Buffer|Name} component If a component is a string, encode as utf8 (but don't unescape).
  504.  * @returns {Name}
  505.  */
  506. Name.prototype.append = function(component)
  507. {
  508.   if (typeof component == 'object' && component instanceof Name) {
  509.     var components;
  510.     if (component == this)
  511.       // special case, when we need to create a copy
  512.       components = this.components.slice(0, this.components.length);
  513.     else
  514.       components = component.components;
  516.     for (var i = 0; i < components.length; ++i)
  517.       this.components.push(new Name.Component(components[i]));
  518.   }
  519.   else
  520.     // Just use the Name.Component constructor.
  521.     this.components.push(new Name.Component(component));
  523.   ++this.changeCount;
  524.   return this;
  525. };
  527. /**
  528.  * @deprecated Use append.
  529.  */
  530. Name.prototype.add = function(component)
  531. {
  532.   return this.append(component);
  533. };
  535. /**
  536.  * Clear all the components.
  537.  */
  538. Name.prototype.clear = function()
  539. {
  540.   this.components = [];
  541.   ++this.changeCount;
  542. };
  544. /**
  545.  * Return the escaped name string according to NDN URI Scheme.
  546.  * @param {boolean} includeScheme (optional) If true, include the "ndn:" scheme
  547.  * in the URI, e.g. "ndn:/example/name". If false, just return the path, e.g.
  548.  * "/example/name". If ommitted, then just return the path which is the default
  549.  * case where toUri() is used for display.
  550.  * @returns {String}
  551.  */
  552. Name.prototype.toUri = function(includeScheme)
  553. {
  554.   if (this.size() == 0)
  555.     return includeScheme ? "ndn:/" : "/";
  557.   var result = includeScheme ? "ndn:" : "";
  559.   for (var i = 0; i < this.size(); ++i)
  560.     result += "/"+ Name.toEscapedString(this.components[i].getValue().buf());
  562.   return result;
  563. };
  565. /**
  566.  * @deprecated Use toUri.
  567.  */
  568. Name.prototype.to_uri = function()
  569. {
  570.   return this.toUri();
  571. };
  573. Name.prototype.toString = function() { return this.toUri(); }
  575. /**
  576.  * Append a component with the encoded segment number according to NDN
  577.  * naming conventions for "Segment number" (marker 0x00).
  578.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  579.  * @param {number} segment The segment number.
  580.  * @returns {Name} This name so that you can chain calls to append.
  581.  */
  582. Name.prototype.appendSegment = function(segment)
  583. {
  584.   return this.append(Name.Component.fromSegment(segment));
  585. };
  587. /**
  588.  * Append a component with the encoded segment byte offset according to NDN
  589.  * naming conventions for segment "Byte offset" (marker 0xFB).
  590.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  591.  * @param {number} segmentOffset The segment byte offset.
  592.  * @returns {Name} This name so that you can chain calls to append.
  593.  */
  594. Name.prototype.appendSegmentOffset = function(segmentOffset)
  595. {
  596.   return this.append(Name.Component.fromSegmentOffset(segmentOffset));
  597. };
  599. /**
  600.  * Append a component with the encoded version number according to NDN
  601.  * naming conventions for "Versioning" (marker 0xFD).
  602.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  603.  * Note that this encodes the exact value of version without converting from a time representation.
  604.  * @param {number} version The version number.
  605.  * @returns {Name} This name so that you can chain calls to append.
  606.  */
  607. Name.prototype.appendVersion = function(version)
  608. {
  609.   return this.append(Name.Component.fromVersion(version));
  610. };
  612. /**
  613.  * Append a component with the encoded timestamp according to NDN naming
  614.  * conventions for "Timestamp" (marker 0xFC).
  615.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  616.  * @param {number} timestamp The number of microseconds since the UNIX epoch (Thursday,
  617.  * 1 January 1970) not counting leap seconds.
  618.  * @returns This name so that you can chain calls to append.
  619.  */
  620. Name.prototype.appendTimestamp = function(timestamp)
  621. {
  622.   return this.append(Name.Component.fromTimestamp(timestamp));
  623. };
  625. /**
  626.  * Append a component with the encoded sequence number according to NDN naming
  627.  * conventions for "Sequencing" (marker 0xFE).
  628.  * http://named-data.net/doc/tech-memos/naming-conventions.pdf
  629.  * @param {number} sequenceNumber The sequence number.
  630.  * @returns This name so that you can chain calls to append.
  631.  */
  632. Name.prototype.appendSequenceNumber = function(sequenceNumber)
  633. {
  634.   return this.append(Name.Component.fromSequenceNumber(sequenceNumber));
  635. };
  637. /**
  638.  * @deprecated Use appendSegment.
  639.  */
  640. Name.prototype.addSegment = function(number)
  641. {
  642.   return this.appendSegment(number);
  643. };
  645. /**
  646.  * Get a new name, constructed as a subset of components.
  647.  * @param {number} iStartComponent The index if the first component to get. If
  648.  * iStartComponent is -N then return return components starting from
  649.  * name.size() - N.
  650.  * @param {number} (optional) nComponents The number of components starting at
  651.  * iStartComponent. If omitted or greater than the size of this name, get until
  652.  * the end of the name.
  653.  * @returns {Name} A new name.
  654.  */
  655. Name.prototype.getSubName = function(iStartComponent, nComponents)
  656. {
  657.   if (iStartComponent < 0)
  658.     iStartComponent = this.components.length - (-iStartComponent);
  660.   if (nComponents == undefined)
  661.     nComponents = this.components.length - iStartComponent;
  663.   var result = new Name();
  665.   var iEnd = iStartComponent + nComponents;
  666.   for (var i = iStartComponent; i < iEnd && i < this.components.length; ++i)
  667.     result.components.push(this.components[i]);
  669.   return result;
  670. };
  672. /**
  673.  * Return a new Name with the first nComponents components of this Name.
  674.  * @param {number} nComponents The number of prefix components.  If nComponents is -N then return the prefix up
  675.  * to name.size() - N. For example getPrefix(-1) returns the name without the final component.
  676.  * @returns {Name} A new name.
  677.  */
  678. Name.prototype.getPrefix = function(nComponents)
  679. {
  680.   if (nComponents < 0)
  681.     return this.getSubName(0, this.components.length + nComponents);
  682.   else
  683.     return this.getSubName(0, nComponents);
  684. };
  686. /**
  687.  * @deprecated Use getPrefix(-nComponents).
  688.  */
  689. Name.prototype.cut = function(nComponents)
  690. {
  691.   return new Name(this.components.slice(0, this.components.length - nComponents));
  692. };
  694. /**
  695.  * Return the number of name components.
  696.  * @returns {number}
  697.  */
  698. Name.prototype.size = function()
  699. {
  700.   return this.components.length;
  701. };
  703. /**
  704.  * Get a Name Component by index number.
  705.  * @param {Number} i The index of the component, starting from 0.  However, if i is negative, return the component
  706.  * at size() - (-i).
  707.  * @returns {Name.Component}
  708.  */
  709. Name.prototype.get = function(i)
  710. {
  711.   if (i >= 0) {
  712.     if (i >= this.components.length)
  713.       throw new Error("Name.get: Index is out of bounds");
  715.     return new Name.Component(this.components[i]);
  716.   }
  717.   else {
  718.     // Negative index.
  719.     if (i < -this.components.length)
  720.       throw new Error("Name.get: Index is out of bounds");
  722.     return new Name.Component(this.components[this.components.length - (-i)]);
  723.   }
  724. };
  726. /**
  727.  * @deprecated Use size().
  728.  */
  729. Name.prototype.getComponentCount = function()
  730. {
  731.   return this.components.length;
  732. };
  734. /**
  735.  * @deprecated To get just the component value array, use get(i).getValue().buf().
  736.  */
  737. Name.prototype.getComponent = function(i)
  738. {
  739.   return new Buffer(this.components[i].getValue().buf());
  740. };
  742. /**
  743.  * The "file name" in a name is the last component that isn't blank and doesn't start with one of the
  744.  *   special marker octets (for version, etc.).  Return the index in this.components of
  745.  *   the file name, or -1 if not found.
  746.  */
  747. Name.prototype.indexOfFileName = function()
  748. {
  749.   for (var i = this.size() - 1; i >= 0; --i) {
  750.     var component = this.components[i].getValue().buf();
  751.     if (component.length <= 0)
  752.       continue;
  754.     if (component[0] == 0 || component[0] == 0xC0 || component[0] == 0xC1 ||
  755.         (component[0] >= 0xF5 && component[0] <= 0xFF))
  756.       continue;
  758.     return i;
  759.   }
  761.   return -1;
  762. };
  764. /**
  765.  * Encode this Name for a particular wire format.
  766.  * @param {WireFormat} wireFormat (optional) A WireFormat object  used to encode
  767.  * this object. If omitted, use WireFormat.getDefaultWireFormat().
  768.  * @returns {Blob} The encoded buffer in a Blob object.
  769.  */
  770. Name.prototype.wireEncode = function(wireFormat)
  771. {
  772.   wireFormat = (wireFormat || WireFormat.getDefaultWireFormat());
  773.   return wireFormat.encodeName(this);
  774. };
  776. /**
  777.  * Decode the input using a particular wire format and update this Name.
  778.  * @param {Blob|Buffer} input The buffer with the bytes to decode.
  779.  * @param {WireFormat} wireFormat (optional) A WireFormat object used to decode
  780.  * this object. If omitted, use WireFormat.getDefaultWireFormat().
  781.  */
  782. Name.prototype.wireDecode = function(input, wireFormat)
  783. {
  784.   wireFormat = (wireFormat || WireFormat.getDefaultWireFormat());
  785.   // If input is a blob, get its buf().
  786.   var decodeBuffer = typeof input === 'object' && input instanceof Blob ?
  787.                      input.buf() : input;
  788.   wireFormat.decodeName(this, decodeBuffer);
  789. };
  791. /**
  792.  * Compare this to the other Name using NDN canonical ordering.  If the first
  793.  * components of each name are not equal, this returns -1 if the first comes
  794.  * before the second using the NDN canonical ordering for name components, or 1
  795.  * if it comes after. If they are equal, this compares the second components of
  796.  * each name, etc.  If both names are the same up to the size of the shorter
  797.  * name, this returns -1 if the first name is shorter than the second or 1 if it
  798.  * is longer. For example, std::sort gives: /a/b/d /a/b/cc /c /c/a /bb .  This
  799.  * is intuitive because all names with the prefix /a are next to each other.
  800.  * But it may be also be counter-intuitive because /c comes before /bb according
  801.  * to NDN canonical ordering since it is shorter.
  802.  * @param {Name} other The other Name to compare with.
  803.  * @returns {boolean} If they compare equal, -1 if *this comes before other in
  804.  * the canonical ordering, or 1 if *this comes after other in the canonical
  805.  * ordering. The first form of compare is simply compare(other). The second form is
  806.  * compare(iStartComponent, nComponents, other [, iOtherStartComponent] [, nOtherComponents])
  807.  * which is equivalent to
  808.  * self.getSubName(iStartComponent, nComponents).compare
  809.  * (other.getSubName(iOtherStartComponent, nOtherComponents)) .
  810.  * @param {number} iStartComponent The index if the first component of this name
  811.  * to get. If iStartComponent is -N then compare components starting from
  812.  * name.size() - N.
  813.  * @param {number} nComponents The number of components starting at
  814.  * iStartComponent. If greater than the size of this name, compare until the end
  815.  * of the name.
  816.  * @param {Name other: The other Name to compare with.
  817.  * @param {number} iOtherStartComponent (optional) The index if the first
  818.  * component of the other name to compare. If iOtherStartComponent is -N then
  819.  * compare components starting from other.size() - N. If omitted, compare
  820.  * starting from index 0.
  821.  * @param {number} nOtherComponents (optional) The number of components
  822.  * starting at iOtherStartComponent. If omitted or greater than the size of this
  823.  * name, compare until the end of the name.
  824.  * @returns {number} 0 If they compare equal, -1 if self comes before other in
  825.  * the canonical ordering, or 1 if self comes after other in the canonical
  826.  * ordering.
  827.  * @see http://named-data.net/doc/0.2/technical/CanonicalOrder.html
  828.  */
  829. Name.prototype.compare = function
  830.   (iStartComponent, nComponents, other, iOtherStartComponent, nOtherComponents)
  831. {
  832.   if (iStartComponent instanceof Name) {
  833.     // compare(other)
  834.     other = iStartComponent;
  835.     iStartComponent = 0;
  836.     nComponents = this.size();
  837.   }
  839.   if (iOtherStartComponent == undefined)
  840.     iOtherStartComponent = 0;
  841.   if (nOtherComponents == undefined)
  842.     nOtherComponents = other.size();
  844.   if (iStartComponent < 0)
  845.     iStartComponent = this.size() - (-iStartComponent);
  846.   if (iOtherStartComponent < 0)
  847.     iOtherStartComponent = other.size() - (-iOtherStartComponent);
  849.   nComponents = Math.min(nComponents, this.size() - iStartComponent);
  850.   nOtherComponents = Math.min(nOtherComponents, other.size() - iOtherStartComponent);
  852.   var count = Math.min(nComponents, nOtherComponents);
  853.   for (var i = 0; i < count; ++i) {
  854.     var comparison = this.components[iStartComponent + i].compare
  855.       (other.components[iOtherStartComponent + i]);
  856.     if (comparison == 0)
  857.       // The components at this index are equal, so check the next components.
  858.       continue;
  860.     // Otherwise, the result is based on the components at this index.
  861.     return comparison;
  862.   }
  864.   // The components up to min(this.size(), other.size()) are equal, so the
  865.   // shorter name is less.
  866.   if (nComponents < nOtherComponents)
  867.     return -1;
  868.   else if (nComponents > nOtherComponents)
  869.     return 1;
  870.   else
  871.     return 0;
  872. };
  874. /**
  875.  * Return true if this Name has the same components as name.
  876.  */
  877. Name.prototype.equals = function(name)
  878. {
  879.   if (this.components.length != name.components.length)
  880.     return false;
  882.   // Start from the last component because they are more likely to differ.
  883.   for (var i = this.components.length - 1; i >= 0; --i) {
  884.     if (!this.components[i].equals(name.components[i]))
  885.       return false;
  886.   }
  888.   return true;
  889. };
  891. /**
  892.  * @deprecated Use equals.
  893.  */
  894. Name.prototype.equalsName = function(name)
  895. {
  896.   return this.equals(name);
  897. };
  899. /**
  900.  * Find the last component in name that has a ContentDigest and return the digest value as Buffer,
  901.  *   or null if not found.  See Name.getComponentContentDigestValue.
  902.  */
  903. Name.prototype.getContentDigestValue = function()
  904. {
  905.   for (var i = this.size() - 1; i >= 0; --i) {
  906.     var digestValue = Name.getComponentContentDigestValue(this.components[i]);
  907.     if (digestValue != null)
  908.       return digestValue;
  909.   }
  911.   return null;
  912. };
  914. /**
  915.  * If component is a ContentDigest, return the digest value as a Buffer slice (don't modify!).
  916.  * If not a ContentDigest, return null.
  917.  * A ContentDigest component is Name.ContentDigestPrefix + 32 bytes + Name.ContentDigestSuffix.
  918.  */
  919. Name.getComponentContentDigestValue = function(component)
  920. {
  921.   if (typeof component == 'object' && component instanceof Name.Component)
  922.     component = component.getValue().buf();
  924.   var digestComponentLength = Name.ContentDigestPrefix.length + 32 + Name.ContentDigestSuffix.length;
  925.   // Check for the correct length and equal ContentDigestPrefix and ContentDigestSuffix.
  926.   if (component.length == digestComponentLength &&
  927.       DataUtils.arraysEqual(component.slice(0, Name.ContentDigestPrefix.length),
  928.                             Name.ContentDigestPrefix) &&
  929.       DataUtils.arraysEqual(component.slice
  930.          (component.length - Name.ContentDigestSuffix.length, component.length),
  931.                             Name.ContentDigestSuffix))
  932.    return component.slice(Name.ContentDigestPrefix.length, Name.ContentDigestPrefix.length + 32);
  933.  else
  934.    return null;
  935. };
  937. // Meta GUID "%C1.M.G%C1" + ContentDigest with a 32 byte BLOB.
  938. Name.ContentDigestPrefix = new Buffer([0xc1, 0x2e, 0x4d, 0x2e, 0x47, 0xc1, 0x01, 0xaa, 0x02, 0x85]);
  939. Name.ContentDigestSuffix = new Buffer([0x00]);
  942. /**
  943.  * Return value as an escaped string according to NDN URI Scheme.
  944.  * We can't use encodeURIComponent because that doesn't encode all the characters we want to.
  945.  * @param {Buffer|Name.Component} component The value or Name.Component to escape.
  946.  * @returns {string} The escaped string.
  947.  */
  948. Name.toEscapedString = function(value)
  949. {
  950.   if (typeof value == 'object' && value instanceof Name.Component)
  951.     value = value.getValue().buf();
  952.   else if (typeof value === 'object' && value instanceof Blob)
  953.     value = value.buf();
  955.   var result = "";
  956.   var gotNonDot = false;
  957.   for (var i = 0; i < value.length; ++i) {
  958.     if (value[i] != 0x2e) {
  959.       gotNonDot = true;
  960.       break;
  961.     }
  962.   }
  963.   if (!gotNonDot) {
  964.     // Special case for component of zero or more periods.  Add 3 periods.
  965.     result = "...";
  966.     for (var i = 0; i < value.length; ++i)
  967.       result += ".";
  968.   }
  969.   else {
  970.     for (var i = 0; i < value.length; ++i) {
  971.       var x = value[i];
  972.       // Check for 0-9, A-Z, a-z, (+), (-), (.), (_)
  973.       if (x >= 0x30 && x <= 0x39 || x >= 0x41 && x <= 0x5a ||
  974.           x >= 0x61 && x <= 0x7a || x == 0x2b || x == 0x2d ||
  975.           x == 0x2e || x == 0x5f)
  976.         result += String.fromCharCode(x);
  977.       else
  978.         result += "%" + (x < 16 ? "0" : "") + x.toString(16).toUpperCase();
  979.     }
  980.   }
  981.   return result;
  982. };
  984. /**
  985.  * Make a blob value by decoding the escapedString according to NDN URI Scheme.
  986.  * If escapedString is "", "." or ".." then return null, which means to skip the component in the name.
  987.  * @param {string} escapedString The escaped string to decode.
  988.  * @returns {Blob} The unescaped Blob value. If the escapedString is not a valid
  989.  * escaped component, then the Blob isNull().
  990.  */
  991. Name.fromEscapedString = function(escapedString)
  992. {
  993.   var value = unescape(escapedString.trim());
  995.   if (value.match(/[^.]/) == null) {
  996.     // Special case for value of only periods.
  997.     if (value.length <= 2)
  998.       // Zero, one or two periods is illegal.  Ignore this componenent to be
  999.       //   consistent with the C implementation.
  1000.       return new Blob();
  1001.     else
  1002.       // Remove 3 periods.
  1003.       return new Blob
  1004.         (DataUtils.toNumbersFromString(value.substr(3, value.length - 3)), false);
  1005.   }
  1006.   else
  1007.     return new Blob(DataUtils.toNumbersFromString(value), false);
  1008. };
  1010. /**
  1011.  * @deprecated Use fromEscapedString. This method returns a Buffer which is the former
  1012.  * behavior of fromEscapedString, and should only be used while updating your code.
  1013.  */
  1014. Name.fromEscapedStringAsBuffer = function(escapedString)
  1015. {
  1016.   return Name.fromEscapedString(escapedString).buf();
  1017. };
  1019. /**
  1020.  * Get the successor of this name which is defined as follows.
  1021.  *
  1022.  *     N represents the set of NDN Names, and X,Y ∈ N.
  1023.  *     Operator < is defined by the NDN canonical order on N.
  1024.  *     Y is the successor of X, if (a) X < Y, and (b) ∄ Z ∈ N s.t. X < Z < Y.
  1025.  *
  1026.  * In plain words, the successor of a name is the same name, but with its last
  1027.  * component advanced to a next possible value.
  1028.  *
  1029.  * Examples:
  1030.  *
  1031.  * - The successor of / is /%00
  1032.  * - The successor of /%00%01/%01%02 is /%00%01/%01%03
  1033.  * - The successor of /%00%01/%01%FF is /%00%01/%02%00
  1034.  * - The successor of /%00%01/%FF%FF is /%00%01/%00%00%00
  1035.  *
  1036.  * @returns {Name} A new name which is the successor of this.
  1037.  */
  1038. Name.prototype.getSuccessor = function()
  1039. {
  1040.   if (this.size() == 0) {
  1041.     // Return "/%00".
  1042.     var result = new Name();
  1043.     result.append(new Blob(new Buffer([0]), false));
  1044.     return result;
  1045.   }
  1046.   else
  1047.     return this.getPrefix(-1).append(this.get(-1).getSuccessor());
  1048. };
  1050. /**
  1051.  * Return true if the N components of this name are the same as the first N
  1052.  * components of the given name.
  1053.  * @param {Name} name The name to check.
  1054.  * @returns {Boolean} true if this matches the given name. This always returns
  1055.  * true if this name is empty.
  1056.  */
  1057. Name.prototype.match = function(name)
  1058. {
  1059.   var i_name = this.components;
  1060.   var o_name = name.components;
  1062.   // This name is longer than the name we are checking it against.
  1063.   if (i_name.length > o_name.length)
  1064.     return false;
  1066.   // Check if at least one of given components doesn't match. Check from last to
  1067.   // first since the last components are more likely to differ.
  1068.   for (var i = i_name.length - 1; i >= 0; --i) {
  1069.     if (!i_name[i].equals(o_name[i]))
  1070.       return false;
  1071.   }
  1073.   return true;
  1074. };
  1076. /**
  1077.  * Return true if the N components of this name are the same as the first N
  1078.  * components of the given name.
  1079.  * @param {Name} name The name to check.
  1080.  * @returns {Boolean} true if this matches the given name. This always returns
  1081.  * true if this name is empty.
  1082.  */
  1083. Name.prototype.isPrefixOf = function(name) { return this.match(name); }
  1085. /**
  1086.  * Get the change count, which is incremented each time this object is changed.
  1087.  * @returns {number} The change count.
  1088.  */
  1089. Name.prototype.getChangeCount = function()
  1090. {
  1091.   return this.changeCount;
  1092. };
  1094. // Put these requires at the bottom to avoid circular references.
  1095. var TlvEncoder = require('./encoding/tlv/tlv-encoder.js').TlvEncoder;
  1096. var WireFormat = require('./encoding/wire-format.js').WireFormat;