/*===========================================================================
*
*                            PUBLIC DOMAIN NOTICE
*               National Center for Biotechnology Information
*
*  This software/database is a "United States Government Work" under the
*  terms of the United States Copyright Act.  It was written as part of
*  the author's official duties as a United States Government employee and
*  thus cannot be copyrighted.  This software/database is freely available
*  to the public for use. The National Library of Medicine and the U.S.
*  Government have not placed any restriction on its use or reproduction.
*
*  Although all reasonable efforts have been taken to ensure the accuracy
*  and reliability of the software and data, the NLM and the U.S.
*  Government do not and cannot warrant the performance or results that
*  may be obtained by using this software or data. The NLM and the U.S.
*  Government disclaim all warranties, express or implied, including
*  warranties of performance, merchantability or fitness for any particular
*  purpose.
*
*  Please cite the author in any work or product based on this material.
*
* ===========================================================================
*
*/

/*==========================================================================
 * VDB built-in functions, formats and types
 */
version 1;


/*--------------------------------------------------------------------------
 * types
 */

// Row id range consist of row_id_start and row_id_stop
typedef I64 vdb:row_id_range [ 2 ];


/*--------------------------------------------------------------------------
 * typesets
 */
typeset integer_set { I8, U8, I16, U16, I32, U32, I64, U64 };
typeset float_set { F32, F64 };
typeset numeric_set { integer_set, float_set };
typeset text_set { utf8, utf16, utf32, ascii };
typeset text8_set { utf8, ascii };
typeset transpose_set { B8, B16, B32, B64 };


/*--------------------------------------------------------------------------
 * formats
 */
fmtdef merged_fmt;
fmtdef transposed_fmt;
fmtdef delta_averaged_fmt;


/*--------------------------------------------------------------------------
 * constants
 */
const U8 ALIGN_LEFT = 0;
const U8 ALIGN_RIGHT = 1;

/*--------------------------------------------------------------------------
 * functions
 */


/* cast
 *  performs a "C++ reinterpret_cast" style cast
 *  rewrites input as required to produce output
 *
 *  legal operations include numeric_set -> numeric_set,
 *  numeric <-> character, etc.
 */
function
any cast #1.0 ( any in )
    = vdb:cast;

/* bit_or
 *  performs a bitwise operation 'OR' for every byte in A and B
 *  A and B are not neccesarily have the same size
 *  the resulting row will have the size of B while OR operation is done for portion of A overlapping B
 *  For different sizes of A and B 'align' parameter provides what edge of A and B are aligned
 *  possible values ALIGN_LEFT, ALIGN_RIGHT
 * 
 */
function < type T >
T  bit_or #1 < U8 align > ( T  A, T B  )
    = vdb:bit_or;

/* trim
 * performs trimming of value val from column A
 * align provides left- or right- trimming
 */
function < type T >
T trim #1 < U8 align, T val > ( T A )
    = vdb:trim;


/* redimension
 *  performs a change of dimension without changing bit pattern
 */
function
any redimension #1.0 ( any in )
    = vdb:redimension;


/* row_id
 *  returns the row id of a request
 */
function
I64 row_id #1.0 ()
    = vdb:row_id;


/* row_len
 *  returns the number of elements in a row
 *
 *  "in" [ DATA ] - column supplying row. if row does not exist
 *  in column, the resultant length is 0.
 */
function
U32 row_len #1.0 ( any in )
    = vdb:row_len;


/* fixed_row_len
 *  returns non-zero if the entire page
 *  has a uniform row-length, zero otherwise
 *
 *  "in" [ DATA ] - column to query
 */
function
U32 fixed_row_len #1.0 ( any in )
    = vdb:fixed_row_len;


/* compare
 *  evaluates src [ i ] == cmp [ i ]
 *  causes writing exception if unequal.
 *
 *  For whole types, equality is bitwise equal
 *  for floating point types see below.
 *
 *  "T" [ TYPE ] - base element type to be processed
 *
 *  "sig_bits" [ OPTIONAL CONST >= 1 ] - for floating point types, ignored
 *  otherwise, the number of significant binary digits in the mantissas to
 *  compare such that |x - y| <= 1, for corresponding numbers x (in a) and
 *  y (in b) both scaled according to sig_bits and their common magnitude.
 *  "sig_bits" may be an array, if so "sel" is required (see below).
 *
 *  "src" [ DATA ] - standard input data derived from source
 *
 *  "cmp" [ DATA ] - feedback data after being written and re-read
 *
 */
validate function < type T >
void compare #1.0 < * U32 sig_bits > ( T src, T cmp )
    = vdb:compare;

validate function < type T >
void no_compare #1.0 ( T src, T cmp )
    = vdb:no_compare;


/* compare2f
 *  evaluates src [ i ] == cmp [ i ]
 *  causes writing exception if unequal.
 *
 *  "T" [ TYPE ] - base element type to be processed
 *
 *  "sig_bits" [ CONST >= 1 ] - for floating point types, ignored otherwise,
 *  array containing the number of significant binary digits in the mantissas
 *  to compare such that |x - y| <= 1, for corresponding numbers x (in a) and
 *  y (in b) both scaled according to sig_bits and their common magnitude.
 *
 *  "src" [ DATA ] - standard input data derived from source
 *
 *  "cmp" [ DATA ] - feedback data after being written and re-read
 *
 *  "sel" [ DATA ] - data to select which element of "sig_bits" to
 *  use for the comparison.  The valid values of "sel" are
 *  [0 .. length sig_bits).
 *
validate function < type T >
void compare2f #1.0 < U32 sig_bits > ( float_set src, float_set cmp, T sel )
    = vdb:compare2f;
*/

/* range_validate
 *  passes input through if all values fall between lower and
 *  upper bounds, INCLUSIVE
 *
 *  "T" [ TYPE ] - type to be validated
 *
 *  "lower" [ CONST ] and "upper" [ CONST ] - inclusive
 *  bounds on input values
 *
 *  "in" [ DATA ] - data to be validated
 */
function < type T >
T range_validate #1.0 < T lower, T upper > ( T in )
    = vdb:range_validate;


/* select
 *  return first non-empty input for id
 *  inputs are taken from first to last
 *
 *  "T" [ TYPE ] - data type of selection
 *
 *  "first" [ DATA ] - first of N inputs
 *
 *  "second" [ DATA ] - second of N inputs
 *  all other inputs are optional and must
 *  be compatible with type "T"
 */
function < type T >
T select #1.0 ( T first, T second, ... )
    = vdb:select;

/* passthru
 *  unconditionally passes through
 *  useful for when syntax requires a function (such as trigger productions)
 *  but there is no semantically significant function to call
 *
 *  "T" [ TYPE ] - data type of the input
 *
 *  "target" [ DATA ] - the input
 */
function < type T >
T passthru #1.0 ( T target )
    = vdb:passthru;

/* is_configuration_set
 *  if the configuration node is set to the
 *  given value, return the input
 *  else fail to resolve
 *
 *  "T" [ TYPE ] - data type of the input
 *
 *  "target" [ DATA ] - the input
 */
function < type T >
T is_configuration_set #1.0 < ascii node, ascii value > ( T target )
    = vdb:is_configuration_set;


/* transpose
 *  transpose a page of unformatted data
 *
 *  for example - convert a simple page of values,
 *  where vertical scale is row id and horizontal element index:
 *
 *        1   2   3
 *      +---+---+---+
 *    1 | a | b | c |
 *      +---+---+---+
 *    2 | d | e | f |
 *      +---+---+---+
 *    3 | g | h | i |
 *      +---+---+---+
 *    4 | j | k | l |
 *      +---+---+---+
 *
 *  into:
 *
 *        1   2   3   4
 *      +---+---+---+---+
 *    1 | a | d | g | j |
 *      +---+---+---+---+
 *    2 | b | e | h | k |
 *      +---+---+---+---+
 *    3 | c | f | i | l |
 *      +---+---+---+---+
 *
 *  variable row-lengths are supported. The output blob is
 *  formatted, meaning that the result can no longer be addressed
 *  as a matrix, but the transposition has be applied to data.
 *
 *  "in" [ DATA ] - unformatted data to be transposed
 */
function
transposed_fmt transpose #1 ( transpose_set in )
    = vdb:transpose;


/* detranspose
 *  pardoning the awful name, apply a transposition on the result
 *  of "transpose" to produce the original blob. "transpose"
 *  itself cannot be reused because of its signature.
 */
function
transpose_set detranspose #1 ( transposed_fmt in )
    = vdb:detranspose;

/*
 * delta_average computes average representation of the maximium 
 * lengh row and deltas every row against it
 */
function
delta_averaged_fmt delta_average #1 ( any in ) 
     = vdb:delta_average;

function
any undelta_average #1 ( delta_averaged_fmt in )
    = vdb:undelta_average;

/* merge
 *  merges all input blobs of any format/type into a single blob
 */
function
merged_fmt merge #1.0 ( any in, ... )
    = vdb:merge;


/* split
 *  extracts a single blob from a merged blob by index
 *
 *  "idx" [ CONST ] - blob index
 */

function
any split #1.0 < U32 idx > ( merged_fmt in )
    = vdb:split;


/* meta:read
 *  reads table metadata node as a row
 * meta:value
 *  reads metadata node as single value,
 *  performing size conversion if necessary,
 *  e.g. I8 TO I64, I32 TO I16
 *
 *  "T" [ TYPE ] - cast data type of metadata node
 *
 *  "node" [ CONST ] - path to metadata node
 */
function < type T >
T meta:read #1.0 < ascii node, * bool deterministic > ();

function < type T >
T meta:value #1.0 < ascii node, * bool deterministic > ();


/* meta:write
 *  writes row data to table metadata node
 *
 *  "T" [ TYPE ] - cast data type of metadata node
 *
 *  "node" [ CONST ] - path to metadata node
 *
 *  "in" [ DATA ] - source of row data
 */
function < type T >
T meta:write #1.0 < ascii node > ( T in );


/* meta:attr:read
 *  reads table metadata attribute as a row
 *
 *  "node" [ CONST ] - path to metadata node
 *
 *  "attr" [ CONST ] - attribute name on node
 */
function
ascii meta:attr:read #1.0 < ascii node, ascii attr, * bool deterministic > ();


/* meta:attr:write
 *  write row data as table metadata attribute
 *
 *  "node" [ CONST ] - path to metadata node
 *
 *  "attr" [ CONST ] - attribute name on node
 */
function
ascii meta:attr:write #1.0 < ascii node, ascii attr > ( ascii in );


/* parameter:read
 *  reads named cursor parameter text
 *
 *  "name" [ CONST ] - parameter name
 */
function
text8_set parameter:read #1.0 < ascii name, * bool deterministic > ();


/* environment:read
 *  reads named environment variable text
 *
 *  "name" [ CONST ] - environment variable name
 */
function
text8_set environment:read #1.0 < ascii name > ();

// case sensivity mode
const U8 CASE_SENSITIVE         =  0;
const U8 CASE_INSENSITIVE_LOWER =  1;
const U8 CASE_INSENSITIVE_UPPER =  2;

/* idx:text:project
 *  perform a reverse lookup in an index
 *  if key not found then use substitute
 *
 *  "index_name" [ CONST ] - name of text index
 *
 *  "substitute" [ DATA, OPTIONAL ] - source
 *  of values to substitute for values not
 *  found in the index.
 *
 *  Version 1.1: look into "substitute" (if available) first and then to the index,
 *  added parameter "case_sensitivity"
 */
function text8_set idx:text:project #1.1 < ascii index_name, * U8 case_sensitivity > ( * text8_set substitute );


/* idx:text:insert
 *  inserts "key" into index. returns key if insertion into index failed or
 *  when "case_insensitive" is true
 *
 *  Version 1.1: added parameter "case_sensitivity"
 */
function text8_set idx:text:insert #1.1 < ascii index_name, * U8 case_sensitivity > ( text8_set key );


/* idx:text:lookup
 *  perform a lookup in an index
 *  returns vdb:row_id_range associated with the
 *
 *  Version 1.1: added parameter "case_sensitivity"
 */
function vdb:row_id_range  idx:text:lookup #1.1 < ascii index_name , ascii query_by_name, * U8 case_sensitivity > ();