#178

Build # #178

Build Type

push

Committed by

Commit Message

<a href="https://github.com/apache/datasketches-java/commit/<a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/<a class="double-link" href="https://git"><a class=hub.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218">a87d8cbbf">&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/</a><a class="double-link" href="https://github.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/&lt;a class=&quot;double-link&quot; href=&quot;https://git">&lt;a class=</a>hub.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218">a87d8cbbf</a><a href="https://github.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218">&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/&lt;/a&gt;&lt;a class=&quot;double-link&quot; href=&quot;https://github.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/&amp;lt;a class=&amp;quot;double-link&amp;quot; href=&amp;quot;https://git&quot;&gt;&amp;lt;a class=&lt;/a&gt;hub.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218&quot;&gt;a87d8cbbf&lt;/a&gt;&lt;a href=&quot;https://github.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218&quot;&gt;&amp;lt;a href=&amp;quot;https://github.com/apache/datasketches-java/commit/a87d8cbbfc4a66b06a79e02f638d00baafbe2218&amp;quot;&amp;gt;&amp;amp;quot;&amp;amp;gt;&am... (continued)

Run Details

1411 of 1411 new or added lines in 10 files covered. (100.0%)

19123 of 19446 relevant lines covered (98.34%)

0.98 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

97.78

/src/main/java/org/apache/datasketches/kll/KllPreambleUtil.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

package org.apache.datasketches.kll;

import static org.apache.datasketches.Util.zeroPad;

import org.apache.datasketches.Util;
import org.apache.datasketches.memory.Memory;
import org.apache.datasketches.memory.WritableMemory;

//@formatter:off

/**
 * This class defines the serialized data structure and provides access methods for the key fields.
 *
 * <p>The intent of the design of this class was to isolate the detailed knowledge of the bit and
 * byte layout of the serialized form of the sketches derived from the base sketch classes into one place.
 * This allows the possibility of the introduction of different serialization
 * schemes with minimal impact on the rest of the library.</p>
 *
 * <p>
 * LAYOUT: The low significance bytes of this <i>long</i> based data structure are on the right.
 * The multi-byte primitives are stored in native byte order.
 * The single byte fields are treated as unsigned.</p>
 *
 * <p>An empty sketch requires only 8 bytes, which is only preamble.
 * A serialized, non-empty KllDoublesSketch requires at least 16 bytes of preamble.
 * A serialized, non-empty KllFloatsSketch requires at least 12 bytes of preamble.</p>
 *
 * <pre>{@code
 * Serialized float sketch layout, more than one item:
 *  Adr:
 *      ||    7    |   6   |    5   |    4   |    3   |    2    |    1   |      0       |
 *  0   || unused  |   M   |--------K--------|  Flags |  FamID  | SerVer | PreambleInts |
 *      ||   15    |   14  |   13   |   12   |   11   |   10    |    9   |      8       |
 *  1   ||---------------------------------N_LONG---------------------------------------|
 *      ||   23    |   22  |   21   |   20   |   19   |    18   |   17   |      16      |
 *  2   ||<--------------data----------------| unused |numLevels|--dynamic-min K--------|
 *
 * Serialized float sketch layout, Empty (8 bytes) and Single Item (12 bytes):
 *  Adr:
 *      ||    7    |   6   |    5   |    4   |    3   |    2    |    1   |      0       |
 *  0   || unused  |   M   |--------K--------|  Flags |  FamID  | SerVer | PreambleInts |
 *      ||   15    |   14  |   13   |   12   |   11   |   10    |    9   |      8       |
 *  1   ||                                   |-------------------data-------------------|
 *
 *
 *
 * Serialized double sketch layout, more than one item:
 *  Adr:
 *      ||    7    |   6   |    5   |    4   |    3   |    2    |    1   |      0       |
 *  0   || unused  |   M   |--------K--------|  Flags |  FamID  | SerVer | PreambleInts |
 *      ||   15    |   14  |   13   |   12   |   11   |   10    |    9   |      8       |
 *  1   ||---------------------------------N_LONG---------------------------------------|
 *      ||   23    |   22  |   21   |   20   |   19   |    18   |   17   |      16      |
 *  2   ||--------------unused------------------------|numLevels|--dynamic-min K--------|
 *      ||                                                               |      24      |
 *  3   ||<---------------------------------data----------------------------------------|
 *
 * Serialized double sketch layout, Empty (8 bytes) and Single Item (16 bytes):
 *  Adr:
 *      ||    7    |   6   |    5   |    4   |    3   |    2    |    1   |      0       |
 *  0   || unused  |   M   |--------K--------|  Flags |  FamID  | SerVer | PreambleInts |
 *      ||                                                               |      8       |
 *  1   ||----------------------------------data----------------------------------------|
 *
 * The structure of the data block depends on Layout:
 *
 *   For FLOAT_SINGLE_COMPACT or DOUBLE_SINGLE_COMPACT:
 *     The single data item is at offset DATA_START_ADR_SINGLE_ITEM = 8
 *
 *   For FLOAT_FULL_COMPACT:
 *     The int[] levels array starts at offset DATA_START_ADR_FLOAT = 20 with a length of numLevels integers;
 *     Followed by Float Min_Value, then Float Max_Value
 *     Followed by an array of Floats of length retainedItems()
 *
 *   For DOUBLE_FULL_COMPACT
 *     The int[] levels array starts at offset DATA_START_ADR_DOUBLE = 24 with a length of numLevels integers;
 *     Followed by Double Min_Value, then Double Max_Value
 *     Followed by an array of Doubles of length retainedItems()
 *
 *   For FLOAT_UPDATABLE
 *     The int[] levels array starts at offset DATA_START_ADR_FLOAT = 20 with a length of (numLevels + 1) integers;
 *     Followed by Float Min_Value, then Float Max_Value
 *     Followed by an array of Floats of length KllHelper.computeTotalItemCapacity(...).
 *
 *   For DOUBLE_UPDATABLE
 *     The int[] levels array starts at offset DATA_START_ADR_DOUBLE = 24 with a length of (numLevels + 1) integers;
 *     Followed by Double Min_Value, then Double Max_Value
 *     Followed by an array of Doubles of length KllHelper.computeTotalItemCapacity(...).
 *
 * }</pre>
 *
 *  @author Lee Rhodes
 */
final class KllPreambleUtil {

  private KllPreambleUtil() {}

  static final String LS = System.getProperty("line.separator");

  /**
   * The default value of K
   */
  public static final int DEFAULT_K = 200;
  static final int DEFAULT_M = 8;
  static final int MIN_K = DEFAULT_M;
  static final int MAX_K = (1 << 16) - 1; // serialized as an unsigned short

  // Preamble byte addresses
  static final int PREAMBLE_INTS_BYTE_ADR     = 0;
  static final int SER_VER_BYTE_ADR           = 1;
  static final int FAMILY_BYTE_ADR            = 2;
  static final int FLAGS_BYTE_ADR             = 3;
  static final int K_SHORT_ADR                = 4;  // to 5
  static final int M_BYTE_ADR                 = 6;
  //                                            7 is reserved for future use
  // SINGLE ITEM ONLY
  static final int DATA_START_ADR_SINGLE_ITEM = 8;

  // MULTI-ITEM
  static final int N_LONG_ADR                 = 8;  // to 15
  static final int DY_MIN_K_SHORT_ADR         = 16; // to 17
  static final int NUM_LEVELS_BYTE_ADR        = 18;

  // FLOAT SKETCH                               19 is reserved for future use in float sketch
  static final int DATA_START_ADR_FLOAT       = 20; // float sketch, not single item

  // DOUBLE SKETCH                              19 to 23 is reserved for future use in double sketch
  static final int DATA_START_ADR_DOUBLE      = 24; // double sketch, not single item

  // Other static values
  static final byte SERIAL_VERSION_EMPTY_FULL = 1; // Empty or full preamble, NOT single item format
  static final byte SERIAL_VERSION_SINGLE     = 2; // only single-item format
  static final byte SERIAL_VERSION_UPDATABLE  = 3; //
  static final int PREAMBLE_INTS_EMPTY_SINGLE = 2; // for empty or single item
  static final int PREAMBLE_INTS_FLOAT        = 5; // not empty nor single item, full preamble float
  static final int PREAMBLE_INTS_DOUBLE       = 6; // not empty nor single item, full preamble double

  // Flag bit masks
  static final int EMPTY_BIT_MASK             = 1;
  static final int LEVEL_ZERO_SORTED_BIT_MASK = 2;
  static final int SINGLE_ITEM_BIT_MASK       = 4;
  static final int DOUBLES_SKETCH_BIT_MASK    = 8;
  static final int UPDATABLE_BIT_MASK         = 16;

  enum Layout {
    FLOAT_FULL_COMPACT,       FLOAT_EMPTY_COMPACT,      FLOAT_SINGLE_COMPACT,
    DOUBLE_FULL_COMPACT,      DOUBLE_EMPTY_COMPACT,     DOUBLE_SINGLE_COMPACT,
    FLOAT_UPDATABLE,  DOUBLE_UPDATABLE }

  /**
   * Returns a human readable string summary of the internal state of the given byte array.
   * Used primarily in testing.
   *
   * @param byteArr the given byte array.
   * @return the summary string.
   */
  static String toString(final byte[] byteArr) {
    final Memory mem = Memory.wrap(byteArr);
    return toString(mem);
  }

  /**
   * Returns a human readable string summary of the internal state of the given Memory.
   * Used primarily in testing.
   *
   * @param mem the given Memory
   * @return the summary string.
   */
  static String toString(final Memory mem) {
    return memoryToString(mem);
  }

  static String memoryToString(final Memory mem) {
    final MemoryValidate memChk = new MemoryValidate(mem);
    final int flags = memChk.flags & 0XFF;
    final String flagsStr = (flags) + ", 0x" + (Integer.toHexString(flags)) + ", "
        + zeroPad(Integer.toBinaryString(flags), 8);
    final int preInts = memChk.preInts;
    final StringBuilder sb = new StringBuilder();
    sb.append(Util.LS).append("### KLL SKETCH MEMORY SUMMARY:").append(LS);
    sb.append("Byte   0   : Preamble Ints      : ").append(preInts).append(LS);
    sb.append("Byte   1   : SerVer             : ").append(memChk.serVer).append(LS);
    sb.append("Byte   2   : FamilyID           : ").append(memChk.familyID).append(LS);
    sb.append("             FamilyName         : ").append(memChk.famName).append(LS);
    sb.append("Byte   3   : Flags Field        : ").append(flagsStr).append(LS);
    sb.append("         Bit Flag Name").append(LS);
    sb.append("           0 EMPTY COMPACT      : ").append(memChk.empty).append(LS);
    sb.append("           1 LEVEL_ZERO_SORTED  : ").append(memChk.level0Sorted).append(LS);
    sb.append("           2 SINGLE_ITEM COMPACT: ").append(memChk.singleItem).append(LS);
    sb.append("           3 DOUBLES_SKETCH     : ").append(memChk.doublesSketch).append(LS);
    sb.append("           4 UPDATABLE          : ").append(memChk.updatable).append(LS);
    sb.append("Bytes  4-5 : K                  : ").append(memChk.k).append(LS);
    sb.append("Byte   6   : Min Level Cap, M   : ").append(memChk.m).append(LS);
    sb.append("Byte   7   : (Reserved)         : ").append(LS);

    switch (memChk.layout) {
      case DOUBLE_FULL_COMPACT:
      case FLOAT_FULL_COMPACT:
      case FLOAT_UPDATABLE:
      case DOUBLE_UPDATABLE:
      {
        sb.append("Bytes  8-15: N                  : ").append(memChk.n).append(LS);
        sb.append("Bytes 16-17: DyMinK             : ").append(memChk.dyMinK).append(LS);
        sb.append("Byte  18   : NumLevels          : ").append(memChk.numLevels).append(LS);
        break;
      }
      case FLOAT_EMPTY_COMPACT:
      case FLOAT_SINGLE_COMPACT:
      case DOUBLE_EMPTY_COMPACT:
      case DOUBLE_SINGLE_COMPACT:
      {
        sb.append("Assumed    : N                  : ").append(memChk.n).append(LS);
        sb.append("Assumed    : DyMinK             : ").append(memChk.dyMinK).append(LS);
        sb.append("Assumed    : NumLevels          : ").append(memChk.numLevels).append(LS);
        break;
      }
      default: break; //can never happen
    }
    sb.append("PreambleBytes                   : ").append(preInts * 4).append(LS);
    sb.append("Sketch Bytes                    : ").append(memChk.sketchBytes).append(LS);
    sb.append("Memory Capacity Bytes           : ").append(mem.getCapacity()).append(LS);
    sb.append("### END KLL Sketch Memory Summary").append(LS);
    return sb.toString();
  }

  static int extractPreInts(final Memory mem) {
    return mem.getByte(PREAMBLE_INTS_BYTE_ADR) & 0XFF;
  }

  static int extractSerVer(final Memory mem) {
    return mem.getByte(SER_VER_BYTE_ADR) & 0XFF;
  }

  static int extractFamilyID(final Memory mem) {
    return mem.getByte(FAMILY_BYTE_ADR) & 0XFF;
  }

  static int extractFlags(final Memory mem) {
    return mem.getByte(FLAGS_BYTE_ADR) & 0XFF;
  }

  static boolean extractEmptyFlag(final Memory mem) {
    return (extractFlags(mem) & EMPTY_BIT_MASK) != 0;
  }

  static boolean extractLevelZeroSortedFlag(final Memory mem) {
    return (extractFlags(mem) & LEVEL_ZERO_SORTED_BIT_MASK) != 0;
  }

  static boolean extractSingleItemFlag(final Memory mem) {
    return (extractFlags(mem) & SINGLE_ITEM_BIT_MASK) != 0;
  }

  static boolean extractDoubleSketchFlag(final Memory mem) {
    return (extractFlags(mem) & DOUBLES_SKETCH_BIT_MASK) != 0;
  }

  static boolean extractUpdatableFlag(final Memory mem) {
    return (extractFlags(mem) & UPDATABLE_BIT_MASK) != 0;
  }

  static int extractK(final Memory mem) {
    return mem.getShort(K_SHORT_ADR) & 0XFFFF;
  }

  static int extractM(final Memory mem) {
    return mem.getByte(M_BYTE_ADR) & 0XFF;
  }

  static long extractN(final Memory mem) {
    return mem.getLong(N_LONG_ADR);
  }

  static int extractDyMinK(final Memory mem) {
    return mem.getShort(DY_MIN_K_SHORT_ADR) & 0XFFFF;
  }

  static int extractNumLevels(final Memory mem) {
    return mem.getByte(NUM_LEVELS_BYTE_ADR) & 0XFF;
  }

  static void insertPreInts(final WritableMemory wmem, final int value) {
    wmem.putByte(PREAMBLE_INTS_BYTE_ADR, (byte) value);
  }

  static void insertSerVer(final WritableMemory wmem, final int value) {
    wmem.putByte(SER_VER_BYTE_ADR, (byte) value);
  }

  static void insertFamilyID(final WritableMemory wmem, final int value) {
    wmem.putByte(FAMILY_BYTE_ADR, (byte) value);
  }

  static void insertFlags(final WritableMemory wmem, final int value) {
    wmem.putByte(FLAGS_BYTE_ADR, (byte) value);
  }

  static void insertEmptyFlag(final WritableMemory wmem,  final boolean empty) {
    final int flags = extractFlags(wmem);
    insertFlags(wmem, empty ? flags | EMPTY_BIT_MASK : flags & ~EMPTY_BIT_MASK);
  }

  static void insertLevelZeroSortedFlag(final WritableMemory wmem,  final boolean levelZeroSorted) {
    final int flags = extractFlags(wmem);
    insertFlags(wmem, levelZeroSorted ? flags | LEVEL_ZERO_SORTED_BIT_MASK : flags & ~LEVEL_ZERO_SORTED_BIT_MASK);
  }

  static void insertSingleItemFlag(final WritableMemory wmem,  final boolean singleItem) {
    final int flags = extractFlags(wmem);
    insertFlags(wmem, singleItem ? flags | SINGLE_ITEM_BIT_MASK : flags & ~SINGLE_ITEM_BIT_MASK);
  }

  static void insertDoubleSketchFlag(final WritableMemory wmem,  final boolean doubleSketch) {
    final int flags = extractFlags(wmem);
    insertFlags(wmem, doubleSketch ? flags | DOUBLES_SKETCH_BIT_MASK : flags & ~DOUBLES_SKETCH_BIT_MASK);
  }

  static void insertUpdatableFlag(final WritableMemory wmem,  final boolean updatable) {
    final int flags = extractFlags(wmem);
    insertFlags(wmem, updatable ? flags | UPDATABLE_BIT_MASK : flags & ~UPDATABLE_BIT_MASK);
  }

  static void insertK(final WritableMemory wmem, final int value) {
    wmem.putShort(K_SHORT_ADR, (short) value);
  }

  static void insertM(final WritableMemory wmem, final int value) {
    wmem.putByte(M_BYTE_ADR, (byte) value);
  }

  static void insertN(final WritableMemory wmem, final long value) {
    wmem.putLong(N_LONG_ADR, value);
  }

  static void insertDyMinK(final WritableMemory wmem, final int value) {
    wmem.putShort(DY_MIN_K_SHORT_ADR, (short) value);
  }

  static void insertNumLevels(final WritableMemory wmem, final int value) {
    wmem.putByte(NUM_LEVELS_BYTE_ADR, (byte) value);
  }

}


1	/*
2	* Licensed to the Apache Software Foundation (ASF) under one
3	* or more contributor license agreements. See the NOTICE file
4	* distributed with this work for additional information
5	* regarding copyright ownership. The ASF licenses this file
6	* to you under the Apache License, Version 2.0 (the
7	* "License"); you may not use this file except in compliance
8	* with the License. You may obtain a copy of the License at
9	*
10	* http://www.apache.org/licenses/LICENSE-2.0
11	*
12	* Unless required by applicable law or agreed to in writing,
13	* software distributed under the License is distributed on an
14	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15	* KIND, either express or implied. See the License for the
16	* specific language governing permissions and limitations
17	* under the License.
18	*/
19
20	package org.apache.datasketches.kll;
21
22	import static org.apache.datasketches.Util.zeroPad;
23
24	import org.apache.datasketches.Util;
25	import org.apache.datasketches.memory.Memory;
26	import org.apache.datasketches.memory.WritableMemory;
27
28	//@formatter:off
29
30	/**
31	* This class defines the serialized data structure and provides access methods for the key fields.
32	*
33	* <p>The intent of the design of this class was to isolate the detailed knowledge of the bit and
34	* byte layout of the serialized form of the sketches derived from the base sketch classes into one place.
35	* This allows the possibility of the introduction of different serialization
36	* schemes with minimal impact on the rest of the library.</p>
37	*
38	* <p>
39	* LAYOUT: The low significance bytes of this <i>long</i> based data structure are on the right.
40	* The multi-byte primitives are stored in native byte order.
41	* The single byte fields are treated as unsigned.</p>
42	*
43	* <p>An empty sketch requires only 8 bytes, which is only preamble.
44	* A serialized, non-empty KllDoublesSketch requires at least 16 bytes of preamble.
45	* A serialized, non-empty KllFloatsSketch requires at least 12 bytes of preamble.</p>
46	*
47	* <pre>{@code
48	* Serialized float sketch layout, more than one item:
49	* Adr:
50	* \|\| 7 \| 6 \| 5 \| 4 \| 3 \| 2 \| 1 \| 0 \|
51	* 0 \|\| unused \| M \|--------K--------\| Flags \| FamID \| SerVer \| PreambleInts \|
52	* \|\| 15 \| 14 \| 13 \| 12 \| 11 \| 10 \| 9 \| 8 \|
53	* 1 \|\|---------------------------------N_LONG---------------------------------------\|
54	* \|\| 23 \| 22 \| 21 \| 20 \| 19 \| 18 \| 17 \| 16 \|
55	* 2 \|\|<--------------data----------------\| unused \|numLevels\|--dynamic-min K--------\|
56	*
57	* Serialized float sketch layout, Empty (8 bytes) and Single Item (12 bytes):
58	* Adr:
59	* \|\| 7 \| 6 \| 5 \| 4 \| 3 \| 2 \| 1 \| 0 \|
60	* 0 \|\| unused \| M \|--------K--------\| Flags \| FamID \| SerVer \| PreambleInts \|
61	* \|\| 15 \| 14 \| 13 \| 12 \| 11 \| 10 \| 9 \| 8 \|
62	* 1 \|\| \|-------------------data-------------------\|
63	*
64	*
65	*
66	* Serialized double sketch layout, more than one item:
67	* Adr:
68	* \|\| 7 \| 6 \| 5 \| 4 \| 3 \| 2 \| 1 \| 0 \|
69	* 0 \|\| unused \| M \|--------K--------\| Flags \| FamID \| SerVer \| PreambleInts \|
70	* \|\| 15 \| 14 \| 13 \| 12 \| 11 \| 10 \| 9 \| 8 \|
71	* 1 \|\|---------------------------------N_LONG---------------------------------------\|
72	* \|\| 23 \| 22 \| 21 \| 20 \| 19 \| 18 \| 17 \| 16 \|
73	* 2 \|\|--------------unused------------------------\|numLevels\|--dynamic-min K--------\|
74	* \|\| \| 24 \|
75	* 3 \|\|<---------------------------------data----------------------------------------\|
76	*
77	* Serialized double sketch layout, Empty (8 bytes) and Single Item (16 bytes):
78	* Adr:
79	* \|\| 7 \| 6 \| 5 \| 4 \| 3 \| 2 \| 1 \| 0 \|
80	* 0 \|\| unused \| M \|--------K--------\| Flags \| FamID \| SerVer \| PreambleInts \|
81	* \|\| \| 8 \|
82	* 1 \|\|----------------------------------data----------------------------------------\|
83	*
84	* The structure of the data block depends on Layout:
85	*
86	* For FLOAT_SINGLE_COMPACT or DOUBLE_SINGLE_COMPACT:
87	* The single data item is at offset DATA_START_ADR_SINGLE_ITEM = 8
88	*
89	* For FLOAT_FULL_COMPACT:
90	* The int[] levels array starts at offset DATA_START_ADR_FLOAT = 20 with a length of numLevels integers;
91	* Followed by Float Min_Value, then Float Max_Value
92	* Followed by an array of Floats of length retainedItems()
93	*
94	* For DOUBLE_FULL_COMPACT
95	* The int[] levels array starts at offset DATA_START_ADR_DOUBLE = 24 with a length of numLevels integers;
96	* Followed by Double Min_Value, then Double Max_Value
97	* Followed by an array of Doubles of length retainedItems()
98	*
99	* For FLOAT_UPDATABLE
100	* The int[] levels array starts at offset DATA_START_ADR_FLOAT = 20 with a length of (numLevels + 1) integers;
101	* Followed by Float Min_Value, then Float Max_Value
102	* Followed by an array of Floats of length KllHelper.computeTotalItemCapacity(...).
103	*
104	* For DOUBLE_UPDATABLE
105	* The int[] levels array starts at offset DATA_START_ADR_DOUBLE = 24 with a length of (numLevels + 1) integers;
106	* Followed by Double Min_Value, then Double Max_Value
107	* Followed by an array of Doubles of length KllHelper.computeTotalItemCapacity(...).
108	*
109	* }</pre>
110	*
111	* @author Lee Rhodes
112	*/
113	final class KllPreambleUtil {
114
115	private KllPreambleUtil() {}
116
117	static final String LS = System.getProperty("line.separator");	1✔
118
119	/**
120	* The default value of K
121	*/
122	public static final int DEFAULT_K = 200;
123	static final int DEFAULT_M = 8;
124	static final int MIN_K = DEFAULT_M;
125	static final int MAX_K = (1 << 16) - 1; // serialized as an unsigned short
126
127	// Preamble byte addresses
128	static final int PREAMBLE_INTS_BYTE_ADR = 0;
129	static final int SER_VER_BYTE_ADR = 1;
130	static final int FAMILY_BYTE_ADR = 2;
131	static final int FLAGS_BYTE_ADR = 3;
132	static final int K_SHORT_ADR = 4; // to 5
133	static final int M_BYTE_ADR = 6;
134	// 7 is reserved for future use
135	// SINGLE ITEM ONLY
136	static final int DATA_START_ADR_SINGLE_ITEM = 8;
137
138	// MULTI-ITEM
139	static final int N_LONG_ADR = 8; // to 15
140	static final int DY_MIN_K_SHORT_ADR = 16; // to 17
141	static final int NUM_LEVELS_BYTE_ADR = 18;
142
143	// FLOAT SKETCH 19 is reserved for future use in float sketch
144	static final int DATA_START_ADR_FLOAT = 20; // float sketch, not single item
145
146	// DOUBLE SKETCH 19 to 23 is reserved for future use in double sketch
147	static final int DATA_START_ADR_DOUBLE = 24; // double sketch, not single item
148
149	// Other static values
150	static final byte SERIAL_VERSION_EMPTY_FULL = 1; // Empty or full preamble, NOT single item format
151	static final byte SERIAL_VERSION_SINGLE = 2; // only single-item format
152	static final byte SERIAL_VERSION_UPDATABLE = 3; //
153	static final int PREAMBLE_INTS_EMPTY_SINGLE = 2; // for empty or single item
154	static final int PREAMBLE_INTS_FLOAT = 5; // not empty nor single item, full preamble float
155	static final int PREAMBLE_INTS_DOUBLE = 6; // not empty nor single item, full preamble double
156
157	// Flag bit masks
158	static final int EMPTY_BIT_MASK = 1;
159	static final int LEVEL_ZERO_SORTED_BIT_MASK = 2;
160	static final int SINGLE_ITEM_BIT_MASK = 4;
161	static final int DOUBLES_SKETCH_BIT_MASK = 8;
162	static final int UPDATABLE_BIT_MASK = 16;
163
164	enum Layout {	1✔
165	FLOAT_FULL_COMPACT, FLOAT_EMPTY_COMPACT, FLOAT_SINGLE_COMPACT,	1✔
166	DOUBLE_FULL_COMPACT, DOUBLE_EMPTY_COMPACT, DOUBLE_SINGLE_COMPACT,	1✔
167	FLOAT_UPDATABLE, DOUBLE_UPDATABLE }	1✔
168
169	/**
170	* Returns a human readable string summary of the internal state of the given byte array.
171	* Used primarily in testing.
172	*
173	* @param byteArr the given byte array.
174	* @return the summary string.
175	*/
176	static String toString(final byte[] byteArr) {
177	final Memory mem = Memory.wrap(byteArr);	×
178	return toString(mem);	×
179	}
180
181	/**
182	* Returns a human readable string summary of the internal state of the given Memory.
183	* Used primarily in testing.
184	*
185	* @param mem the given Memory
186	* @return the summary string.
187	*/
188	static String toString(final Memory mem) {
189	return memoryToString(mem);	1✔
190	}
191
192	static String memoryToString(final Memory mem) {
193	final MemoryValidate memChk = new MemoryValidate(mem);	1✔
194	final int flags = memChk.flags & 0XFF;	1✔
195	final String flagsStr = (flags) + ", 0x" + (Integer.toHexString(flags)) + ", "	1✔
196	+ zeroPad(Integer.toBinaryString(flags), 8);	1✔
197	final int preInts = memChk.preInts;	1✔
198	final StringBuilder sb = new StringBuilder();	1✔
199	sb.append(Util.LS).append("### KLL SKETCH MEMORY SUMMARY:").append(LS);	1✔
200	sb.append("Byte 0 : Preamble Ints : ").append(preInts).append(LS);	1✔
201	sb.append("Byte 1 : SerVer : ").append(memChk.serVer).append(LS);	1✔
202	sb.append("Byte 2 : FamilyID : ").append(memChk.familyID).append(LS);	1✔
203	sb.append(" FamilyName : ").append(memChk.famName).append(LS);	1✔
204	sb.append("Byte 3 : Flags Field : ").append(flagsStr).append(LS);	1✔
205	sb.append(" Bit Flag Name").append(LS);	1✔
206	sb.append(" 0 EMPTY COMPACT : ").append(memChk.empty).append(LS);	1✔
207	sb.append(" 1 LEVEL_ZERO_SORTED : ").append(memChk.level0Sorted).append(LS);	1✔
208	sb.append(" 2 SINGLE_ITEM COMPACT: ").append(memChk.singleItem).append(LS);	1✔
209	sb.append(" 3 DOUBLES_SKETCH : ").append(memChk.doublesSketch).append(LS);	1✔
210	sb.append(" 4 UPDATABLE : ").append(memChk.updatable).append(LS);	1✔
211	sb.append("Bytes 4-5 : K : ").append(memChk.k).append(LS);	1✔
212	sb.append("Byte 6 : Min Level Cap, M : ").append(memChk.m).append(LS);	1✔
213	sb.append("Byte 7 : (Reserved) : ").append(LS);	1✔
214
215	switch (memChk.layout) {	1✔
216	case DOUBLE_FULL_COMPACT:
217	case FLOAT_FULL_COMPACT:
218	case FLOAT_UPDATABLE:
219	case DOUBLE_UPDATABLE:
220	{
221	sb.append("Bytes 8-15: N : ").append(memChk.n).append(LS);	1✔
222	sb.append("Bytes 16-17: DyMinK : ").append(memChk.dyMinK).append(LS);	1✔
223	sb.append("Byte 18 : NumLevels : ").append(memChk.numLevels).append(LS);	1✔
224	break;	1✔
225	}
226	case FLOAT_EMPTY_COMPACT:
227	case FLOAT_SINGLE_COMPACT:
228	case DOUBLE_EMPTY_COMPACT:
229	case DOUBLE_SINGLE_COMPACT:
230	{
231	sb.append("Assumed : N : ").append(memChk.n).append(LS);	1✔
232	sb.append("Assumed : DyMinK : ").append(memChk.dyMinK).append(LS);	1✔
233	sb.append("Assumed : NumLevels : ").append(memChk.numLevels).append(LS);	1✔
234	break;	1✔
235	}
236	default: break; //can never happen
237	}
238	sb.append("PreambleBytes : ").append(preInts * 4).append(LS);	1✔
239	sb.append("Sketch Bytes : ").append(memChk.sketchBytes).append(LS);	1✔
240	sb.append("Memory Capacity Bytes : ").append(mem.getCapacity()).append(LS);	1✔
241	sb.append("### END KLL Sketch Memory Summary").append(LS);	1✔
242	return sb.toString();	1✔
243	}
244
245	static int extractPreInts(final Memory mem) {
246	return mem.getByte(PREAMBLE_INTS_BYTE_ADR) & 0XFF;	1✔
247	}
248
249	static int extractSerVer(final Memory mem) {
250	return mem.getByte(SER_VER_BYTE_ADR) & 0XFF;	1✔
251	}
252
253	static int extractFamilyID(final Memory mem) {
254	return mem.getByte(FAMILY_BYTE_ADR) & 0XFF;	1✔
255	}
256
257	static int extractFlags(final Memory mem) {
258	return mem.getByte(FLAGS_BYTE_ADR) & 0XFF;	1✔
259	}
260
261	static boolean extractEmptyFlag(final Memory mem) {
262	return (extractFlags(mem) & EMPTY_BIT_MASK) != 0;	1✔
263	}
264
265	static boolean extractLevelZeroSortedFlag(final Memory mem) {
266	return (extractFlags(mem) & LEVEL_ZERO_SORTED_BIT_MASK) != 0;	1✔
267	}
268
269	static boolean extractSingleItemFlag(final Memory mem) {
270	return (extractFlags(mem) & SINGLE_ITEM_BIT_MASK) != 0;	1✔
271	}
272
273	static boolean extractDoubleSketchFlag(final Memory mem) {
274	return (extractFlags(mem) & DOUBLES_SKETCH_BIT_MASK) != 0;	1✔
275	}
276
277	static boolean extractUpdatableFlag(final Memory mem) {
278	return (extractFlags(mem) & UPDATABLE_BIT_MASK) != 0;	1✔
279	}
280
281	static int extractK(final Memory mem) {
282	return mem.getShort(K_SHORT_ADR) & 0XFFFF;	1✔
283	}
284
285	static int extractM(final Memory mem) {
286	return mem.getByte(M_BYTE_ADR) & 0XFF;	1✔
287	}
288
289	static long extractN(final Memory mem) {
290	return mem.getLong(N_LONG_ADR);	1✔
291	}
292
293	static int extractDyMinK(final Memory mem) {
294	return mem.getShort(DY_MIN_K_SHORT_ADR) & 0XFFFF;	1✔
295	}
296
297	static int extractNumLevels(final Memory mem) {
298	return mem.getByte(NUM_LEVELS_BYTE_ADR) & 0XFF;	1✔
299	}
300
301	static void insertPreInts(final WritableMemory wmem, final int value) {
302	wmem.putByte(PREAMBLE_INTS_BYTE_ADR, (byte) value);	1✔
303	}	1✔
304
305	static void insertSerVer(final WritableMemory wmem, final int value) {
306	wmem.putByte(SER_VER_BYTE_ADR, (byte) value);	1✔
307	}	1✔
308
309	static void insertFamilyID(final WritableMemory wmem, final int value) {
310	wmem.putByte(FAMILY_BYTE_ADR, (byte) value);	1✔
311	}	1✔
312
313	static void insertFlags(final WritableMemory wmem, final int value) {
314	wmem.putByte(FLAGS_BYTE_ADR, (byte) value);	1✔
315	}	1✔
316
317	static void insertEmptyFlag(final WritableMemory wmem, final boolean empty) {
318	final int flags = extractFlags(wmem);	1✔
319	insertFlags(wmem, empty ? flags \| EMPTY_BIT_MASK : flags & ~EMPTY_BIT_MASK);	1✔
320	}	1✔
321
322	static void insertLevelZeroSortedFlag(final WritableMemory wmem, final boolean levelZeroSorted) {
323	final int flags = extractFlags(wmem);	1✔
324	insertFlags(wmem, levelZeroSorted ? flags \| LEVEL_ZERO_SORTED_BIT_MASK : flags & ~LEVEL_ZERO_SORTED_BIT_MASK);	1✔
325	}	1✔
326
327	static void insertSingleItemFlag(final WritableMemory wmem, final boolean singleItem) {
328	final int flags = extractFlags(wmem);	1✔
329	insertFlags(wmem, singleItem ? flags \| SINGLE_ITEM_BIT_MASK : flags & ~SINGLE_ITEM_BIT_MASK);	1✔
330	}	1✔
331
332	static void insertDoubleSketchFlag(final WritableMemory wmem, final boolean doubleSketch) {
333	final int flags = extractFlags(wmem);	1✔
334	insertFlags(wmem, doubleSketch ? flags \| DOUBLES_SKETCH_BIT_MASK : flags & ~DOUBLES_SKETCH_BIT_MASK);	1✔
335	}	1✔
336
337	static void insertUpdatableFlag(final WritableMemory wmem, final boolean updatable) {
338	final int flags = extractFlags(wmem);	1✔
339	insertFlags(wmem, updatable ? flags \| UPDATABLE_BIT_MASK : flags & ~UPDATABLE_BIT_MASK);	1✔
340	}	1✔
341
342	static void insertK(final WritableMemory wmem, final int value) {
343	wmem.putShort(K_SHORT_ADR, (short) value);	1✔
344	}	1✔
345
346	static void insertM(final WritableMemory wmem, final int value) {
347	wmem.putByte(M_BYTE_ADR, (byte) value);	1✔
348	}	1✔
349
350	static void insertN(final WritableMemory wmem, final long value) {
351	wmem.putLong(N_LONG_ADR, value);	1✔
352	}	1✔
353
354	static void insertDyMinK(final WritableMemory wmem, final int value) {
355	wmem.putShort(DY_MIN_K_SHORT_ADR, (short) value);	1✔
356	}	1✔
357
358	static void insertNumLevels(final WritableMemory wmem, final int value) {
359	wmem.putByte(NUM_LEVELS_BYTE_ADR, (byte) value);	1✔
360	}	1✔
361
362	}
363

apache / datasketches-java / #178

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous