define: DUK_USE_EXTSTR_INTERN_CHECK
introduced: 1.1.0
requires:
  - DUK_USE_HSTRING_EXTDATA
default: false
tags:
  - memory
  - experimental
description: >
  Provide a hook for checking if data for a certain string can be used from
  external memory (outside of Duktape heap, e.g. memory mapped flash).
  The hook is called during string interning with the following semantics:

  The string data with no NUL termination resides at "ptr" and has "len"
  bytes.  The "udata" argument is the heap userdata which may be ignored
  if not needed.  If the hook returns NULL, Duktape interns the string
  normally, i.e. string data is allocated from Duktape heap.  Otherwise the
  hook return value must point to a memory area which contains
  "len" bytes from "ptr" followed by a NUL byte which is NOT PRESENT
  in the input data.  Data behind the returned pointer may not change after
  the hook returns.

  The hook may be called several times for the same input string.  This
  happens when a string is interned, garbage collected, and then interned
  again.

  The DUK_USE_EXTSTR_FREE() hook allows application code to detect when
  an external string is about to be freed.

  In most cases the hook should reject strings whose "len" is less than 4
  because there is no RAM advantage in moving so short strings into external
  memory.  The ordinary "duk_hstring" header followed by the data (and a
  NUL byte) has the same size as "duk_hstring_external" header which hosts
  a pointer instead of string data.

  Also enable DUK_USE_HSTRING_EXTDATA to use this feature.

  See doc/low-memory.rst for more discussion how to use this feature option
  in practice.
