PackedArrayContext.d.ts 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. /**
  2. * A packed-value, sparse array context used for storing 64 bit signed values.
  3. *
  4. * An array context is optimised for tracking sparsely set (as in mostly zeros) values that tend to not make
  5. * use pof the full 64 bit value range even when they are non-zero. The array context's internal representation
  6. * is such that the packed value at each virtual array index may be represented by 0-8 bytes of actual storage.
  7. *
  8. * An array context encodes the packed values in 8 "set trees" with each set tree representing one byte of the
  9. * packed value at the virtual index in question. The {@link #getPackedIndex(int, int, boolean)} method is used
  10. * to look up the byte-index corresponding to the given (set tree) value byte of the given virtual index, and can
  11. * be used to add entries to represent that byte as needed. As a succesful {@link #getPackedIndex(int, int, boolean)}
  12. * may require a resizing of the array, it can throw a {@link ResizeException} to indicate that the requested
  13. * packed index cannot be found or added without a resize of the physical storage.
  14. *
  15. */
  16. export declare const MINIMUM_INITIAL_PACKED_ARRAY_CAPACITY = 16;
  17. export declare class PackedArrayContext {
  18. readonly isPacked: boolean;
  19. physicalLength: number;
  20. private array;
  21. private byteArray;
  22. private shortArray;
  23. private longArray;
  24. private populatedShortLength;
  25. private virtualLength;
  26. private topLevelShift;
  27. constructor(virtualLength: number, initialPhysicalLength: number);
  28. private initArrayViews;
  29. private init;
  30. clear(): void;
  31. copyAndIncreaseSize(newPhysicalArrayLength: number, newVirtualArrayLength: number): PackedArrayContext;
  32. getPopulatedShortLength(): number;
  33. getPopulatedLongLength(): number;
  34. setAtByteIndex(byteIndex: number, value: number): void;
  35. getAtByteIndex(byteIndex: number): number;
  36. /**
  37. * add a byte value to a current byte value in the array
  38. * @param byteIndex index of byte value to add to
  39. * @param valueToAdd byte value to add
  40. * @return the afterAddValue. ((afterAddValue & 0x100) != 0) indicates a carry.
  41. */
  42. addAtByteIndex(byteIndex: number, valueToAdd: number): number;
  43. setPopulatedLongLength(newPopulatedLongLength: number): void;
  44. getVirtualLength(): number;
  45. length(): number;
  46. setAtShortIndex(shortIndex: number, value: number): void;
  47. setAtLongIndex(longIndex: number, value: number): void;
  48. getAtShortIndex(shortIndex: number): number;
  49. getIndexAtShortIndex(shortIndex: number): number;
  50. setPackedSlotIndicators(entryIndex: number, newPackedSlotIndicators: number): void;
  51. getPackedSlotIndicators(entryIndex: number): number;
  52. private getIndexAtEntrySlot;
  53. setIndexAtEntrySlot(entryIndex: number, slot: number, newIndexValue: number): void;
  54. private expandArrayIfNeeded;
  55. private newEntry;
  56. private newLeafEntry;
  57. /**
  58. * Consolidate entry with previous entry verison if one exists
  59. *
  60. * @param entryIndex The shortIndex of the entry to be consolidated
  61. * @param previousVersionIndex the index of the previous version of the entry
  62. */
  63. private consolidateEntry;
  64. /**
  65. * Expand entry as indicated.
  66. *
  67. * @param existingEntryIndex the index of the entry
  68. * @param entryPointerIndex index to the slot pointing to the entry (needs to be fixed up)
  69. * @param insertedSlotIndex realtive [packed] index of slot being inserted into entry
  70. * @param insertedSlotMask mask value fo slot being inserted
  71. * @param nextLevelIsLeaf the level below this one is a leaf level
  72. * @return the updated index of the entry (-1 if epansion failed due to conflict)
  73. * @throws RetryException if expansion fails due to concurrent conflict, and caller should try again.
  74. */
  75. expandEntry(existingEntryIndex: number, entryPointerIndex: number, insertedSlotIndex: number, insertedSlotMask: number, nextLevelIsLeaf: boolean): number;
  76. getRootEntry(setNumber: number, insertAsNeeded?: boolean): number;
  77. /**
  78. * Get the byte-index (into the packed array) corresponding to a given (set tree) value byte of given virtual index.
  79. * Inserts new set tree nodes as needed if indicated.
  80. *
  81. * @param setNumber The set tree number (0-7, 0 corresponding with the LSByte set tree)
  82. * @param virtualIndex The virtual index into the PackedArray
  83. * @param insertAsNeeded If true, will insert new set tree nodes as needed if they do not already exist
  84. * @return the byte-index corresponding to the given (set tree) value byte of the given virtual index
  85. */
  86. getPackedIndex(setNumber: number, virtualIndex: number, insertAsNeeded: boolean): number;
  87. determineTopLevelShiftForVirtualLength(virtualLength: number): number;
  88. setVirtualLength(virtualLength: number): void;
  89. getTopLevelShift(): number;
  90. resizeArray(newLength: number): void;
  91. private populateEquivalentEntriesWithEntriesFromOther;
  92. private copyEntriesAtLevelFromOther;
  93. getAtUnpackedIndex(index: number): number;
  94. setAtUnpackedIndex(index: number, newValue: number): void;
  95. lazysetAtUnpackedIndex(index: number, newValue: number): void;
  96. incrementAndGetAtUnpackedIndex(index: number): number;
  97. addAndGetAtUnpackedIndex(index: number, valueToAdd: number): number;
  98. private nonLeafEntryToString;
  99. private leafEntryToString;
  100. toString(): string;
  101. }