;;;;;; utils.hex
;;;;; Standard Utilities (utils.hex)<a name="utils.hex"></a>
;;;;; This file contains a collection of standardized utility symbols extending the native symbols of the hex programming language.
;;;;; <ul>
;;;;; <li><a href="#utils.hex_input-output">Input/Output Symbols</a></li>
;;;;; <li><a href="#utils.hex_control-flow">Control Flow Symbols</a></li>
;;;;; <li><a href="#utils.hex_quotation">Quotation Symbols</a></li>
;;;;; <li><a href="#utils.hex_stack-management">Stack Management Symbols</a></li>
;;;;; <li><a href="#utils.hex_string">String Symbols</a></li>
;;;;; </ul>

;;;; <a name="utils.hex_input-output"></a>Input/Output Symbols
;;;; These additional symbols are used for input and output operations.

;;; dputs
;; a -> a
;; Duplicates and prints the top item on the stack followed by a new line.
(
  dup puts
) "dputs" ::

;;;; <a name="utils.hex_control-flow"></a>Control Flow Symbols
;;;; These symbols are used for controlling the flow of execution in a program.

;;; unless
;; q1 q2 -> *
;; If %:q1%% pushes $0 on the stack, dequotes %:q2%%.
(
  ()
  swap
  if
) "unless" ::

;;; when
;; q1 q2 -> *
;; If %:q1%% pushes $1 on the stack, dequotes %:q2%%.
(
  ()
  if
) "when" ::

;;;; <a name="utils.hex_quotation"></a>Quotation Symbols
;;;; These additional symbols are used for manipulating quotations.

;;; cons
;; a q1 -> q2
;; Prepends %:a%% to the beginning of %:q1%%.
(
  swap ' swap cat
) "cons" ::

;;; each
;; q1 q2 -> *
;; Applies %:q2%% to each element of %:q1%%.
(
  ($0) cat map drop
) "each" ::

;;; filter
;; q1 q2-> q3
;; Returns %:q3%% containing only the elements of %:q1%% that satisfy %:q2%%.
(
  "_filter_fn" :
  "_filter_list" :
  () "_filter_result" :
  _filter_list (
    "_filter_each_item" :
    (_filter_each_item _filter_fn .)
      (
        _filter_result _filter_each_item push "_filter_result" :
      ) 
    when
  ) each
  _filter_result
  "_filter_fn"     #
  "_filter_list"   #
  "_filter_result" #
) "filter" ::

;; ins
;; q1 a i -> q2
;; Inserts item %:a%% before position %:i%% within a quotation.
(
  "_ins_index" :
  "_ins_item" :
  "_ins_list" :
  $0 "_ins_c" :
  () "_ins_result" :
  _ins_list len "_ins_len" :
  (_ins_index _ins_len >= _ins_index $0 < or)
    ("[symbol ins] Index out of bounds" throw)
  when
  (_ins_c _ins_len <)
    (
      (_ins_c _ins_index ==)
        (_ins_result _ins_item ' cat "_ins_result" :)
      when
      _ins_result _ins_list  _ins_c get ' cat "_ins_result" :
      _ins_c $1 + "_ins_c" :
    )
  while
  _ins_result
  "_ins_index"   #
  "_ins_item"    #
  "_ins_list"    #
  "_ins_c"       #
  "_ins_result"  #
  "_ins_len"     #
) "ins" ::

;;; max
;; q -> a
;; Pushes the maximum item of q on the stack.
(
  "_max_list" :
  _max_list $0 get "_max_result" :
  $1 "_max_c" :
  (_max_c _max_list len <)
    (
      (_max_result _max_list _max_c get <)
        (_max_list _max_c get "_max_result" :)
      when
      _max_c $1 + "_max_c" :
    )
  while
  _max_result
  "_max_list"   #
  "_max_result" #
  "_max_c"      #
) "max" ::

;;; min
;; q -> a
;; Pushes the minimum item of q on the stack.
(
  "_min_list" :
  _min_list $0 get "_min_result" :
  $1 "_min_c" :
  (_min_c _min_list len <)
    (
      (_min_result _min_list _min_c get >)
        (_min_list _min_c get "_min_result" :)
      when
      _min_c $1 + "_min_c" :
    )
  while
  _min_result
  "_min_list"   #
  "_min_result" #
  "_min_c"      #
) "min" ::

;;; pop
;; q1 -> q2
;; Removes the last item at the end of %:q1%%.
(
  "_pop_q" :
  () "_pop_res" :
  $0 "_pop_c" :
  (_pop_c _pop_q len $1 - <)
    (
      _pop_res _pop_q _pop_c get push "_pop_res" :
      _pop_c $1 + "_pop_c" :
    )
  while
  _pop_res
  "_pop_q"   #
  "_pop_res" #
  "_pop_c"   #
) "pop" ::


;;; push
;; q1 a -> q2
;; Appends %:a%% to the end of %:q1%%.
(
  ' cat
) "push" ::

;;; rem
;; q1 i -> q2
;; Removes the item at index %:i%% of %:q1%%.
(
  "_rem_index" :
  "_rem_list"  :
  () "_rem_result" :
  (_rem_index _rem_list len >= _rem_index $0 < or)
    ("[symbol rem] Index out of bounds" throw)
  when
  $0 "_rem_c" :
  (_rem_c _rem_list len <)
    (
      (_rem_c _rem_index !=)
        (_rem_result _rem_list _rem_c get ' cat "_rem_result" :)
      when
      _rem_c $1 + "_rem_c" :
    )
  while
  _rem_result
  "_rem_index"   #
  "_rem_c"       #
  "_rem_list"    #
  "_rem_result"  #
) "rem" ::

;;; reverse
;; q1 -> q2
;; Reverses the order of the items in a quotation.
(
  "_reverse_list" :
  _reverse_list len $1 - "_reverse_c" : 
  () "_reverse_result" :
  (_reverse_c $0 >=)
    (
       _reverse_result _reverse_list _reverse_c get ' cat "_reverse_result" :
       _reverse_c $1 - "_reverse_c" :
    )
  while
  _reverse_result
  "_reverse_list"   #
  "_reverse_c"      # 
  "_reverse_result" # 
) "reverse" ::

;;; set
;; q1 a i -> q2
;; Sets the item at index %:i%% of %:q1%% to %:a%%.
(
  "_set_index" :
  "_set_item"  :
  "_set_list"  :
  () "_set_result" :
  (_set_index _set_list len >= _set_index $0 < or)
    ("[symbol set] Index out of bounds" throw)
  when
  $0 "_set_c" :
  (_set_c _set_list len <)
    (
      (_set_c _set_index ==)
        (_set_result _set_item ' cat "_set_result" :)
        (_set_result _set_list  _set_c get ' cat "_set_result" :)
      if
      _set_c $1 + "_set_c" :
    )
  while
  _set_result
  "_set_index"   #
  "_set_c"       #
  "_set_item"    #
  "_set_list"    #
  "_set_result"  #
) "set" ::

;;; sort
;; q1 q2 -> q3
;; Sorts the items of q1 based on the comparison quotation q2 (must push $0 or $1 on the stack).
(
  "_sort_check"            :
  "_sort_list"             :
  _sort_list len "_sort_n" :
  $0 "_sort_i"            :
  $1 "_sort_swapped"      :
  (_sort_swapped)
    (
      $0 "_sort_swapped"    :
      $0 "_sort_i"          :
      (_sort_i _sort_n $1 - <)
        (
          _sort_list _sort_i get "_sort_current" :
          _sort_list _sort_i $1 + get "_sort_next" :
          (_sort_current _sort_next _sort_check .)
            (
              _sort_list 
                _sort_current _sort_i $1 + set
                _sort_next _sort_i set
              "_sort_list" :
              $1 "_sort_swapped" :
            )
          when
          _sort_i $1 + "_sort_i" :
          "_sort_current" #
          "_sort_next"    #
        )
      while
    )
  while
  _sort_list
  "_sort_check"     #
  "_sort_list"      #
  "_sort_n"         #
  "_sort_i"         #
  "_sort_swapped"   #
) "sort" ::

;;; swons
;; q1 a -> q2
;; Prepends %:a%% to the beginning of %:q1%%.
(
  ' swap cat
) "swons" ::


;;; times
;; q i -> *
;; Execute quotation %:q%% %:i%% times.
(
  "_times_i" :
  "_times_q" :
  (_times_i $0 >)
    (
      _times_q . 
      _times_i $1 - "_times_i" :
    )
  while
  "_times_q" #
  "_times_i" #
) "times" ::

;;; uncons
;; q1 -> a q2
;; Removes the first item from %:q1%% and pushes it on the stack along with %:q2%% containing the rest of the items of %:q1%%.
(
  "_uncons_list" :
  () "_uncons_result" :
  $1 "_uncons_c" :
  (_uncons_c _uncons_list len <)
    (
      _uncons_result _uncons_list _uncons_c get push "_uncons_result" :
      _uncons_c $1 + "_uncons_c" :
    )
  while
  _uncons_list $0 get ; Push the first item
  _uncons_result ; Push the rest of the items
  "_uncons_list"   #
  "_uncons_result" #
  "_uncons_c"      #
) "uncons" ::


;;; unswons
;; q1 -> q2 a
;; Removes the first item from %:q1%% and pushes it on the stack along with %:q2%% containing the rest of the items of %:q1%%.
(
  "_unswons_list" :
  () "_unswons_result" :
  $1 "_unswons_c" :
  (_unswons_c _unswons_list len <)
    (
      _unswons_result _unswons_list _unswons_c get push "_unswons_result" :
      _unswons_c $1 + "_unswons_c" :
    )
  while
  _unswons_result ; Push the rest of the items
  _unswons_list $0 get ; Push the first item
  "_unswons_list"   #
  "_unswons_result" #
  "_unswons_c"      #
) "unswons" ::

;;;; <a name="utils.hex_stack-management"></a>Stack Management Symbols
;;;; These additional symbols are used for manipulating the stack.

;;; dip
;; a1 (a2) -> a2 a1
;; Dequotes the first item on the stack and restores the second item on top.
(
  swap ' cat .
) "dip" ::

;;; over
;; a1 a2 -> a1 a2 a1
;; Copies the second item on the stack and pushes it on top
(
  "_over_a" :
  dup _over_a swap
  "_over_a" #
) "over" ::

;;;; <a name="utils.hex_string"></a>String Symbols
;;;; These additional symbols are used for manipulating strings.

;;; begins
;; s1 s2 -> s3
;; Pushes $!1$$ on the stack if %:s1%% begins with %:s2%%, or $!0$$ otherwise.
(
  index $0 ==
) "begins" ::

;;; ends
;; s1 s2 -> s3
;; Pushes $!1$$ on the stack if %:s1%% ends with %:s2%%, or $!0$$ otherwise.
(
  "_ends_suffix" :
  "_ends_s"      :
  _ends_s _ends_suffix index 
  _ends_s len _ends_suffix len -
  ==
  "_ends_suffix" #
  "_ends_s"      #
) "ends" ::

;;; fmt
;; s1 q -> s2
;; Substitutes %:$\{0\}%% to %%$\{9\}%% placeholders in %:s1%% with items in %:q%%.
(
  "_fmt_q" :
  "_fmt_s" :
  $0 "_fmt_c" :
  (_fmt_q len $a >)
    ("[symbol fmt] Only a maximum of 10 placeholders are supported" throw)
  when
  (_fmt_c _fmt_q len <)
    (
      _fmt_s "${" _fmt_c str cat "}" cat _fmt_q _fmt_c get gsub "_fmt_s" :
      _fmt_c $1 + "_fmt_c" :
    )
  while
  _fmt_s
  "_fmt_s" #
  "_fmt_q" #
  "_fmt_c" #
) "fmt" ::

;;; gsub
;; s1 s2 s3 -> s4
;; Replaces all occurrences of %:s2%% with %%s3%% in %:s1%%.
(
  "_gsub_rep"  :
  "_gsub_src"  :
  "_gsub_text" :
  (_gsub_text _gsub_src index $0 >=)
    (_gsub_text _gsub_src _gsub_rep sub "_gsub_text" :)
  while
  _gsub_text
  "_gsub_rep"  #
  "_gsub_src"  #
  "_gsub_text" #
) "gsub" ::

;;; slice
;; s1 i1 i2 -> s2
;; Extracts the portion of the string between indices %:i1%% and %:i2%%.
(
  "_slice_end" :
  "_slice_start" :
  "_slice_str" :
  "" "_slice_result" :
  (_slice_end _slice_str len >= _slice_start $0 < or)
    ("[symbol slice] Index out of bounds" throw)
  when
  (_slice_start _slice_end <=)
    (
      _slice_result _slice_str _slice_start get cat "_slice_result" : 
      _slice_start $1 + "_slice_start" :
    )
  while
  _slice_result
  "_slice_end"    #
  "_slice_start"  #
  "_slice_str"    #
  "_slice_result" #
) "slice" ::