GlueGen Struct Generator Update *API Change* .. etc

GlueGen Revised Struct Mapping (esp pointer to array or single element), Struct String Charset, .. and Documentation

- Documentation:
    - Added README.md
      Let's have a proper face for the git repo

    - Added doc/GlueGen_Mapping.md (and its html conversion doc/GlueGen_Mapping.html)
      Created a new document covering application and implementation details suitable for users/devs.

    - Added doc/JogAmpMacOSVersions.md conversion to doc/JogAmpMacOSVersions.html

    - Updated www/index.html

- Use *CodeUnit instead of PrintWriter, representing a Java or C code unit covering a set of functions and structs.
    The CCodeUnit also handles common code shared by its unit across functions etc.

- Dropping 'static initializer', as its no more required
    due to simplified `JVMUtil_NewDirectByteBufferCopy()` variant.

- Revised Struct Mapping:
  - Pure Java implementation to map primitive and struct fields within a struct
    by utilizing ElementBuffer.

    Only 'Function Pointer' fields within a struct require native code.

    Exposes `static boolean usesNativeCode()` to query whether native code is used/required.

  - Transparent native memory address API

    Expose `long getDirectBufferAddress()` and `static TK_Struct derefPointer(long addr)`,
    allowing to
    - pass the native struct-pointer with native code
    - reconstruct the struct from a native struct-pointer
    - have a fully functional `TK_Struct.derefPointer(struct.getDirectBufferAddress())` cycle.

  - Add 'boolean is<Val>Null() to query whether a pointer (array) is NULL

  - *Changed* array get/set method for more flexibility alike `System.arraycopy(src, srcPos, dest, destPos, len)`,
    where 'src' is being dropped for the getter and 'dest' is being dropped for the setter
    as both objects are reflected by the struct instance.

  - *Changed* `get<Val>ArrayLength()` -> `get<Val>ElemCount()` for clarity

  - Considering all ConstElemCount values with config 'ReturnedArrayLength <int>'
    to be owned by native code -> NativeOwnership -> Not changing the underlying memory region!
    JavaOwnership is considered for all pointer-arrays not of NativeOwnership.
    Hence any setter on a NativeOwnership pointer-array will fail with non-matching elem-count.

  - Add 'release<Val>()' for JavaOwnership pointer-arrays,
    allowing to release the Java owned native memory incl. null-ing pointer and set<Val>ElemCount(0).

  - Support setter for 'const <type>*' w/ JavaOwnership, i.e. pointer to const value of a primitive or struct,
    setter and getter using pointer to array or single element in general.

  - Added Config `ImmutableAccess symbol` to disable all setter for whole struct or a field

  - Added Config `MaxOneElement symbol` to restrict a pointer to maximum one element and unset
    initial value (zero elements)

  - Added Config `ReturnsStringOnly symbol` to restrict mapping only to a Java String,
    dropping the ByteBuffer variant for 'char'

  - String mapping default is UTF-8 and can be read and set via [get|set]Charset(..) per class.

  - Dynamic string length retrieval in case no `ReturnedArrayLength` has been configured
    has changed from `strlen()` to `strnlen(aptr, max_len)` to be on the safe site.

    The maximum length default is 8192 bytes and can be read and set via [get|set]MaxStrnlen(..) per class.

    FIXME: strnlen(..) using EOS byte non-functional for non 8-bit codecs like UTF-8, US-ASCII.
           This is due to e.g. UTF-16 doesn't use an EOS byte, but interprets it as part of a code point.

  - TODO: Perhaps a few more unit tests

  - TODO: Allow plain 'int' to be mapped in structs IFF their size is same for all MachineDescriptions used.
          Currently this is the case -> 4 bytes like int32_t.

  /** Setter for native field <code>constInt32PointerVariaLen</code>: CType[(PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], [const[false], pointer*1]], with initial array length of <code>0</code> */
  public final TK_Field setConstInt32PointerVariaLen(int[] src, final int srcPos, final int destPos, final int length) {
    if( 0 > srcPos || 0 > destPos || 0 > length || srcPos + length > src.length ) { throw new IndexOutOfBoundsException("src[pos "+srcPos+", length "+src.length+"], destPos "+destPos+", length "+length); }
    final int newElemCount = destPos + length;
    final ElementBuffer eb = ElementBuffer.allocateDirect(4, newElemCount);
    ( ( IntBuffer)(eb.getByteBuffer().asIntBuffer().position(destPos) ) ).put(src, srcPos, length).rewind();
    eb.storeDirectAddress(getBuffer(), constInt32PointerVariaLen_offset[mdIdx]);
    _ebConstInt32PointerVariaLen = eb;
    setConstInt32PointerVariaLenElemCount( newElemCount );
    return this;
  }

  /** Setter for native field <code>variaInt32PointerVariaLen</code>: CType[(PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], [const[false], pointer*1]], with initial array length of <code>0</code> */
  public final TK_Field setVariaInt32PointerVariaLen(int[] src, final int srcPos, final int destPos, final int length) {
    if( 0 > srcPos || 0 > destPos || 0 > length || srcPos + length > src.length ) { throw new IndexOutOfBoundsException("src[pos "+srcPos+", length "+src.length+"], destPos "+destPos+", length "+length); }
    final int elemCount = getVariaInt32PointerVariaLenElemCount();
    if( destPos + length <= elemCount ) {
      final ElementBuffer eb = ElementBuffer.derefPointer(4, elemCount, getBuffer(), variaInt32PointerVariaLen_offset[mdIdx]);
      ( ( IntBuffer)(eb.getByteBuffer().asIntBuffer().position(destPos) ) ).put(src, srcPos, length).rewind();
    } else {
      final int newElemCount = destPos + length;
      final ElementBuffer eb = ElementBuffer.allocateDirect(4, newElemCount);
      ( ( IntBuffer)(eb.getByteBuffer().asIntBuffer().position(destPos) ) ).put(src, srcPos, length).rewind();
      eb.storeDirectAddress(getBuffer(), variaInt32PointerVariaLen_offset[mdIdx]);
      _ebVariaInt32PointerVariaLen = eb;
      setVariaInt32PointerVariaLenElemCount( newElemCount );
    }
    return this;
  }

Sven Gothel wrote

If my answer would be taken, we would have:

- Copy old -> new non-covered data when allocating new memory
- Adding a 'allowShrink' to the setter

???